node-firebird 2.14.3 → 2.14.4

package/README.md

@@ -1558,14 +1558,15 @@ fb.attach(_connection, function (err, svc) {
 
 Node-Firebird defaults to `UTF-8` for database connections, but fully supports custom client character sets. You can set the connection encoding by specifying `options.encoding` (e.g. `'UTF8'`, `'WIN1252'`, `'ISO8859_1'`, `'LATIN1'`, `'ASCII'`, or `'NONE'`).
 
-Commonly used Firebird character sets are automatically mapped to their corresponding Node.js Buffer encodings:
+Commonly used Firebird character sets are handled through the corresponding Node.js encoding or ICU codec:
 
-| Firebird Character Set | Node.js Buffer Encoding | Description / Notes |
-| ---------------------- | ----------------------- | ------------------- |
-| `UTF8`, `UNICODE_FSS`  | `utf8`                  | Unicode. Handles character-level truncation automatically based on charset width. |
-| `WIN1252`, `ISO8859_1`, `LATIN1` | `latin1`      | 8-bit European encodings. Safely decodes special accented characters. |
-| `ASCII`                | `ascii`                 | 7-bit ASCII. |
-| `NONE`                 | `latin1`                | Raw/unspecified character set. Treated as binary-safe 8-bit characters. |
+| Firebird Character Set | Node.js encoding / ICU codec | Description / Notes |
+| ---------------------- | ---------------------------- | ------------------- |
+| `UTF8`, `UNICODE_FSS`  | `utf8`                       | Unicode. Handles character-level truncation automatically based on charset width. |
+| `WIN1252`              | ICU `windows-1252` codec     | Windows Western European encoding, including the printable characters in bytes `0x80`–`0x9F`. |
+| `ISO8859_1`, `LATIN1`  | `latin1`                     | ISO-8859-1-compatible byte mapping; intentionally distinct from Windows-1252. |
+| `ASCII`                | `ascii`                      | 7-bit ASCII. |
+| `NONE`                 | `latin1`                     | Raw/unspecified character set. Treated as binary-safe 8-bit characters. |
 
 Beyond Node's native encodings, the driver ships **codepage codecs** for the
 single-byte charsets (decode *and* encode — columns, parameters, SQL
@@ -1581,7 +1582,9 @@ await db.queryAsync('INSERT INTO T VALUES (?)', ['Привет']); // encoded as
 ```
 
 The codecs are built from Node's ICU tables at first use (present in every
-official Node build). `attachOrCreate`/`create` honour `options.encoding`
+official Node build). If a constrained runtime does not provide a requested
+codec, the driver throws a descriptive error instead of silently falling back
+to UTF-8 and corrupting text. `attachOrCreate`/`create` honour `options.encoding`
 for the new database's default charset too. Accented characters and
 fixed-length `CHAR(N)` whitespace/truncation are handled automatically per
 the charset width — and single-byte columns (including charset `NONE`) are
@@ -1597,7 +1600,7 @@ var options = {
     database: 'win1252_db.fdb',
     user: 'SYSDBA',
     password: 'masterkey',
-    encoding: 'WIN1252' // Automatically maps to 'latin1' under the hood
+    encoding: 'WIN1252' // Uses the WHATWG/ICU Windows-1252 codec
 };
 
 Firebird.attach(options, function (err, db) {
@@ -2296,7 +2299,7 @@ options.blobReadChunkSize = 65535;
 
 If your server and client are on the same host, this won't matter much — the slowdown is latency-bound, not throughput-bound.
 
-#### How do I use an encoding other than UTF-8 (e.g. WIN1252/Latin1)?
+#### How do I use an encoding other than UTF-8 (e.g. WIN1252 or Latin1)?
 
 Set `options.encoding` — no source changes required (see [Character Set & Encoding Support](#character-set--encoding-support) for the full mapping table):
 

package/lib/wire/codepages.d.ts

@@ -17,7 +17,9 @@ export interface TextCodec {
 }
 export declare function charsetWidthById(id: number | undefined): number;
 /**
- * Codec for a Firebird charset name, or null when the charset is unknown,
- * natively handled by Buffer, or the ICU tables are unavailable. Cached.
+ * Codec for a Firebird charset name, or null when the charset is unknown or
+ * natively handled by Buffer. A known codepage whose ICU table is unavailable
+ * throws instead of silently falling back to UTF-8. Successful and unknown
+ * lookups are cached; failures are not.
  */
 export declare function getCodec(charsetName: string | undefined): TextCodec | null;

package/lib/wire/codepages.js

@@ -17,6 +17,7 @@ exports.getCodec = getCodec;
 const ICU_LABELS = Object.freeze({
     WIN1250: 'windows-1250',
     WIN1251: 'windows-1251',
+    WIN1252: 'windows-1252',
     WIN1253: 'windows-1253',
     WIN1254: 'windows-1254',
     WIN1255: 'windows-1255',
@@ -60,30 +61,63 @@ function charsetWidthById(id) {
     return CHARSET_WIDTH_BY_ID[id] || 1;
 }
 const cache = new Map();
-function buildCodec(name) {
-    const label = ICU_LABELS[name];
-    if (!label) {
-        return null;
+/**
+ * WHATWG windows-1252 code points for bytes 0x80–0x9F (the only range
+ * where it differs from Latin-1). Node's TextDecoder cannot be trusted
+ * here: through at least Node 20 the 'windows-1252' label is routed
+ * through a latin1 fast path, decoding this range as C1 controls, so
+ * the WIN1252 table is built from this fixed spec table instead of the
+ * runtime decoder. Later Node majors agree with this table exactly.
+ */
+const WIN1252_C1 = Object.freeze([
+    0x20AC, 0x0081, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021,
+    0x02C6, 0x2030, 0x0160, 0x2039, 0x0152, 0x008D, 0x017D, 0x008F,
+    0x0090, 0x2018, 0x2019, 0x201C, 0x201D, 0x2022, 0x2013, 0x2014,
+    0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0x009D, 0x017E, 0x0178,
+]);
+function buildByteToCodeTable(name, label) {
+    const toCode = new Uint16Array(256);
+    if (name === 'WIN1252') {
+        // Latin-1 identity outside 0x80–0x9F; spec table inside. Needs no
+        // ICU support at all, so WIN1252 works even on small-icu builds.
+        for (let i = 0; i < 256; i++) {
+            toCode[i] = (i & 0xE0) === 0x80 ? WIN1252_C1[i - 0x80] : i;
+        }
+        return toCode;
     }
     let decoder;
     try {
         decoder = new TextDecoder(label);
     }
     catch {
-        // Node built with small-icu: legacy encodings unavailable
-        return null;
+        // Falling through to DEFAULT_ENCODING (UTF-8) would silently write
+        // different bytes from the explicitly requested Firebird codepage.
+        // Official Node builds include these ICU tables; constrained builds
+        // must fail clearly instead of corrupting text.
+        throw new Error(`The requested Firebird encoding ${name} requires the ${label} ICU codec, ` +
+            'but this Node.js runtime does not provide it. Use an official full-ICU ' +
+            'Node.js build, or connect with encoding NONE and pass explicitly encoded Buffer values.');
     }
-    // Build both directions from the decoder, one byte at a time — every
-    // byte of a single-byte codepage maps to exactly one BMP character
-    // (undefined bytes decode to U+FFFD, which is kept for decoding but
-    // never used for the reverse map).
-    const toCode = new Uint16Array(256);
-    const toByte = new Map();
     const one = Buffer.alloc(1);
     for (let i = 0; i < 256; i++) {
         one[0] = i;
-        const ch = decoder.decode(one);
-        toCode[i] = ch.charCodeAt(0);
+        toCode[i] = decoder.decode(one).charCodeAt(0);
+    }
+    return toCode;
+}
+function buildCodec(name) {
+    const label = ICU_LABELS[name];
+    if (!label) {
+        return null;
+    }
+    // Build both directions from one byte→code table — every byte of a
+    // single-byte codepage maps to exactly one BMP character (undefined
+    // bytes decode to U+FFFD, which is kept for decoding but never used
+    // for the reverse map).
+    const toCode = buildByteToCodeTable(name, label);
+    const toByte = new Map();
+    for (let i = 0; i < 256; i++) {
+        const ch = String.fromCharCode(toCode[i]);
         if (ch !== '�' && !toByte.has(ch)) {
             toByte.set(ch, i);
         }
@@ -120,8 +154,10 @@ function buildCodec(name) {
     };
 }
 /**
- * Codec for a Firebird charset name, or null when the charset is unknown,
- * natively handled by Buffer, or the ICU tables are unavailable. Cached.
+ * Codec for a Firebird charset name, or null when the charset is unknown or
+ * natively handled by Buffer. A known codepage whose ICU table is unavailable
+ * throws instead of silently falling back to UTF-8. Successful and unknown
+ * lookups are cached; failures are not.
  */
 function getCodec(charsetName) {
     if (!charsetName) {

package/lib/wire/xsqlvar.js

@@ -39,13 +39,13 @@ const EMPTY_BUFFER = Buffer.alloc(0);
  * We must decode raw bytes with the matching Node.js encoding so that
  * characters outside ASCII are reproduced correctly.
  *
- * Commonly used Firebird charsets not listed here fall back to the
- * connection-level DEFAULT_ENCODING (typically 'utf8').
+ * Other recognized single-byte character sets are handled by the ICU-backed
+ * codec path. Only unknown character-set names fall back to the
+ * connection-level DEFAULT_ENCODING, typically UTF-8.
  */
 const FirebirdToNodeEncoding = Object.freeze({
     UTF8: 'utf8',
     UNICODE_FSS: 'utf8',
-    WIN1252: 'latin1',
     ISO8859_1: 'latin1',
     LATIN1: 'latin1',
     ASCII: 'ascii',

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "node-firebird",
-    "version": "2.14.3",
+    "version": "2.14.4",
     "description": "Pure JavaScript and Asynchronous Firebird client for Node.js.",
     "keywords": [
         "firebird",

package/src/wire/codepages.ts

@@ -21,6 +21,7 @@ export interface TextCodec {
 const ICU_LABELS: Readonly<Record<string, string>> = Object.freeze({
     WIN1250: 'windows-1250',
     WIN1251: 'windows-1251',
+    WIN1252: 'windows-1252',
     WIN1253: 'windows-1253',
     WIN1254: 'windows-1254',
     WIN1255: 'windows-1255',
@@ -68,30 +69,67 @@ export function charsetWidthById(id: number | undefined): number {
 
 const cache = new Map<string, TextCodec | null>();
 
-function buildCodec(name: string): TextCodec | null {
-    const label = ICU_LABELS[name];
-    if (!label) {
-        return null;
+/**
+ * WHATWG windows-1252 code points for bytes 0x80–0x9F (the only range
+ * where it differs from Latin-1). Node's TextDecoder cannot be trusted
+ * here: through at least Node 20 the 'windows-1252' label is routed
+ * through a latin1 fast path, decoding this range as C1 controls, so
+ * the WIN1252 table is built from this fixed spec table instead of the
+ * runtime decoder. Later Node majors agree with this table exactly.
+ */
+const WIN1252_C1 = Object.freeze([
+    0x20AC, 0x0081, 0x201A, 0x0192, 0x201E, 0x2026, 0x2020, 0x2021,
+    0x02C6, 0x2030, 0x0160, 0x2039, 0x0152, 0x008D, 0x017D, 0x008F,
+    0x0090, 0x2018, 0x2019, 0x201C, 0x201D, 0x2022, 0x2013, 0x2014,
+    0x02DC, 0x2122, 0x0161, 0x203A, 0x0153, 0x009D, 0x017E, 0x0178,
+]);
+
+function buildByteToCodeTable(name: string, label: string): Uint16Array {
+    const toCode = new Uint16Array(256);
+    if (name === 'WIN1252') {
+        // Latin-1 identity outside 0x80–0x9F; spec table inside. Needs no
+        // ICU support at all, so WIN1252 works even on small-icu builds.
+        for (let i = 0; i < 256; i++) {
+            toCode[i] = (i & 0xE0) === 0x80 ? WIN1252_C1[i - 0x80] : i;
+        }
+        return toCode;
     }
     let decoder: TextDecoder;
     try {
         decoder = new TextDecoder(label);
     } catch {
-        // Node built with small-icu: legacy encodings unavailable
+        // Falling through to DEFAULT_ENCODING (UTF-8) would silently write
+        // different bytes from the explicitly requested Firebird codepage.
+        // Official Node builds include these ICU tables; constrained builds
+        // must fail clearly instead of corrupting text.
+        throw new Error(
+            `The requested Firebird encoding ${name} requires the ${label} ICU codec, ` +
+            'but this Node.js runtime does not provide it. Use an official full-ICU ' +
+            'Node.js build, or connect with encoding NONE and pass explicitly encoded Buffer values.'
+        );
+    }
+    const one = Buffer.alloc(1);
+    for (let i = 0; i < 256; i++) {
+        one[0] = i;
+        toCode[i] = decoder.decode(one).charCodeAt(0);
+    }
+    return toCode;
+}
+
+function buildCodec(name: string): TextCodec | null {
+    const label = ICU_LABELS[name];
+    if (!label) {
         return null;
     }
 
-    // Build both directions from the decoder, one byte at a time — every
-    // byte of a single-byte codepage maps to exactly one BMP character
-    // (undefined bytes decode to U+FFFD, which is kept for decoding but
-    // never used for the reverse map).
-    const toCode = new Uint16Array(256);
+    // Build both directions from one byte→code table — every byte of a
+    // single-byte codepage maps to exactly one BMP character (undefined
+    // bytes decode to U+FFFD, which is kept for decoding but never used
+    // for the reverse map).
+    const toCode = buildByteToCodeTable(name, label);
     const toByte = new Map<string, number>();
-    const one = Buffer.alloc(1);
     for (let i = 0; i < 256; i++) {
-        one[0] = i;
-        const ch = decoder.decode(one);
-        toCode[i] = ch.charCodeAt(0);
+        const ch = String.fromCharCode(toCode[i]);
         if (ch !== '�' && !toByte.has(ch)) {
             toByte.set(ch, i);
         }
@@ -130,8 +168,10 @@ function buildCodec(name: string): TextCodec | null {
 }
 
 /**
- * Codec for a Firebird charset name, or null when the charset is unknown,
- * natively handled by Buffer, or the ICU tables are unavailable. Cached.
+ * Codec for a Firebird charset name, or null when the charset is unknown or
+ * natively handled by Buffer. A known codepage whose ICU table is unavailable
+ * throws instead of silently falling back to UTF-8. Successful and unknown
+ * lookups are cached; failures are not.
  */
 export function getCodec(charsetName: string | undefined): TextCodec | null {
     if (!charsetName) {

package/src/wire/xsqlvar.ts

@@ -29,13 +29,13 @@ const EMPTY_BUFFER = Buffer.alloc(0);
  * We must decode raw bytes with the matching Node.js encoding so that
  * characters outside ASCII are reproduced correctly.
  *
- * Commonly used Firebird charsets not listed here fall back to the
- * connection-level DEFAULT_ENCODING (typically 'utf8').
+ * Other recognized single-byte character sets are handled by the ICU-backed
+ * codec path. Only unknown character-set names fall back to the
+ * connection-level DEFAULT_ENCODING, typically UTF-8.
  */
 const FirebirdToNodeEncoding: Readonly<Record<string, string>> = Object.freeze({
     UTF8:        'utf8',
     UNICODE_FSS: 'utf8',
-    WIN1252:     'latin1',
     ISO8859_1:   'latin1',
     LATIN1:      'latin1',
     ASCII:       'ascii',