feat: add configurable connection charset (lc_ctype)

[reinhardt1053]

Problem

Legacy Firebird databases commonly use charset NONE on text columns. In these databases, text is stored as raw bytes in the application's encoding (typically WIN1252) without any charset metadata on the columns.

The driver currently hardcodes utf8 as the connection charset (lc_ctype in the DPB). When connecting to a database with charset NONE columns, Firebird does not transliterate the data: it sends the raw bytes as-is. The driver then incorrectly decodes these WIN1252 bytes as UTF-8, corrupting accented characters:

• Tournée → Tourn�e
• Café → Caf�

This affects a large number of production Firebird databases where charset NONE was the default.

Solution

Add a charset option to ConnectOptions that:

1. Sets the DPB lc_ctype to the specified charset instead of hardcoded utf8
2. Propagates the charset to the data reader/writer so string encoding/decoding matches the connection charset

Usage

const attachment = await client.connect('host:database', {
  username: 'SYSDBA',
  password: 'masterkey',
  charset: 'WIN1252',
});

How it works

• mapCharsetToEncoding() maps Firebird charset names to Node.js BufferEncoding values (utf8 for UTF8, latin1 for all single-byte charsets)
• latin1 encoding in Node.js provides a 1:1 byte-to-codepoint mapping, which correctly handles any single-byte Firebird charset (WIN1252, ISO8859_1, WIN1250, etc.)
• The encoding is stored on AbstractAttachment and passed through to createDataReader() and createDataWriter() via StatementImpl.prepare()

Changes

• node-firebird-driver:

  • ConnectOptions: add optional charset property
  • createDpb(): use options.charset instead of hardcoded 'utf8'
  • mapCharsetToEncoding(): new helper to map Firebird charset → Node.js encoding
  • AbstractAttachment: add encoding property
  • createDataReader() / createDataWriter(): accept encoding parameter

• node-firebird-driver-native:

  • AttachmentImpl.connect(): set encoding from mapCharsetToEncoding(options.charset)
  • StatementImpl.prepare(): pass attachment.encoding to reader/writer

Backward compatible

When charset is not specified, the behavior is identical to before (defaults to utf8).

[asfernandes]

Isn't node.js strings assumed to be utf8?
How would it will work with strings that are just bytes?

[reinhardt1053]

Isn't node.js strings assumed to be utf8?

JavaScript strings are Unicode internally but the key issue is how raw bytes from the wire are decoded into JS strings, and how JS strings are encoded back to bytes when writing. At the moment with charset NONE columns Firebird sends raw bytes without transliteration, the byte 0xE9 (which is é in WIN1252) is not valid as a single-byte UTF-8 sequence, so StringDecoder('utf8') replaces it with �

How would it will work with strings that are just bytes?

With NONE columns the data is indeed just bytes, the driver can't know the encoding. That's why it's left to the user to specify it via the charset option, the user knows what encoding their application uses (e.g. Delphi apps typically use WIN1252). The driver then uses the corresponding node.js encoding (latin1) to decode/encode correctly.

[asfernandes]

Usage of latin1 is wrong there.
Looks like TextDecoder would be the correct way.

[reinhardt1053]

Updated with your recommendation and it is now using TextDecoder for reading and a reverse lookup table for writing instead of latin1. This correctly supports all single-byte Firebird charsets (WIN1252, WIN1251, ISO8859_x, etc.)

[asfernandes]

I offer this alternative: #165
Please verify and test.