iconv-tiny 1.2.3 → 1.4.0

package/README.md

@@ -12,7 +12,7 @@
 [![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![npm version](https://img.shields.io/npm/v/iconv-tiny)](https://www.npmjs.com/package/iconv-tiny)
 
-Pure JS character encoding conversion as an ECMAScript Module (ESM). Auto-Generated from http://www.unicode.org/Public/MAPPINGS.
+Pure JS character encoding conversion as an ECMAScript Module (ESM). Auto-Generated from https://www.unicode.org/Public/MAPPINGS.
 
 ## About
 
@@ -27,9 +27,9 @@ It is an ES-module and should work in all modern browsers and NodeJS that suppor
 1. Tree shaking and other ESM-related benefits.
 1. Table mappings and default characters overrides.
 1. Native `TextDecoder` for some encodings.
-1. `encodeInto(Uint8Array)` and `byteLength(string)`
+1. `encodeInto(Uint8Array)` and `byteLength(string)` functions
 1. Typescript friendly.
-1. Tiny: 1 file, ~12KB in gzip.
+1. Tiny: 1 file with dbcs tables, ~30KB in gzip.
 
 ## Installation
 
@@ -43,7 +43,7 @@ or use CDN:
 <script type="importmap">
   {
     "imports": {
-      "iconv-tiny": "https://unpkg.com/iconv-tiny@1.2.2/dist/iconv-tiny.mjs"
+      "iconv-tiny": "https://unpkg.com/iconv-tiny@1.4.0/dist/iconv-tiny.mjs"
     }
   }
 </script>
@@ -54,10 +54,10 @@ or use CDN:
 API is very close to **iconv-lite** API, see [iconv-tiny.d.mts](dist/iconv-tiny.d.mts).
 
 ```javascript
-import { IconvTiny, aliases, encodings, canonicalize } from "iconv-tiny";
+import { canonicalize, createIconv, encodings, aliases } from "iconv-tiny";
 
 // Create iconv
-const iconv = new IconvTiny(encodings, aliases);
+const iconv = createIconv(encodings, aliases);
 
 // Convert from an Uint8Array to a js string.
 str = iconv.decode(new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f]), "win1251");
@@ -88,32 +88,33 @@ import { UTF16LE } from "iconv-tiny";
 const utf16 = UTF16LE.create();
 
 // Create decoder, it works like TextDecoder with {stream: true} option.
-const decoder = utf16.newDecoder();
+const decoder = utf16.getDecoder();
 
 // Decode a fragment
-const part = decoder.decode(new Uint8Array([0x3d, 0xd8, 0x0a]));
+const part = decoder.write(new Uint8Array([0x3d, 0xd8, 0x0a]));
 
 // Decode the next fragment
-const str = decoder.decode(new Uint8Array([0xde])); // 😊
+const str = decoder.write(new Uint8Array([0xde])); // 😊
 
 // Finish stream decoding
-const tail = decoder.decode();
+const tail = decoder.end();
 ```
 
 See more [examples](examples).
 
-## Supported encodings:
+## Supported encodings (singlebyte & doublebyte encodings, Unicode):
 
 1. **ISO-8859**: 1,2,3,4,5,6,7,8,9,10,11,13,14,15,16
-1. **EBCDIC**: Cp037, Cp500, Cp875, Cp1026
+1. **EBCDIC**: Cp037, Cp424, Cp500, Cp875, Cp1026
 1. **DOS**: Cp437, Cp737, Cp775, Cp850, Cp852, Cp855, Cp857, Cp860, Cp861, Cp862, Cp863, Cp864, Cp865, Cp866, Cp869, Cp874
 1. **WINDOWS**: Cp1250, Cp1251, Cp1252, Cp1253, Cp1254, Cp1255, Cp1256, Cp1257, Cp1258
 1. **MAC**: CYRILLIC, GREEK, ICELAND, LATIN2, ROMAN, TURKISH
-1. **MISC**: ATARIST, Cp424, CP856, Cp1006, KOI8-R, KOI8-U, KZ1048, NEXTSTEP
-1. **OTHER**: US-ASCII
+1. **MISC**: ATARIST, CP856, Cp1006, KOI8-R, KOI8-U, KZ1048, NEXTSTEP
+1. **OTHER**: [US-ASCII](https://en.wikipedia.org/wiki/ASCII)
 1. **UNICODE**: UTF-8, UTF-16, UTF-32
+1. **Japanese**: [JIS-0201](https://en.wikipedia.org/wiki/JIS_X_0201), [SHIFT-JIS](https://en.wikipedia.org/wiki/Shift_JIS), [CP932](https://en.wikipedia.org/wiki/Code_page_932_(Microsoft_Windows))
 
-All encodings are generated automatically from http://www.unicode.org/Public/MAPPINGS with a few additional mappings for **CP875** (0xE1 -> 0x20AF, 0xEC -> 0x037A, 0xFC -> 0x20AC) and **CP1255** (0xCA -> 0x05BA), see [mappings](scripts/mappings/)
+All encodings are generated automatically from https://www.unicode.org/Public/MAPPINGS with a few additional mappings for **CP875** (0xE1 -> 0x20AF, 0xEC -> 0x037A, 0xFC -> 0x20AC) and **CP1255** (0xCA -> 0x05BA), see [mappings](scripts/mappings/)
 
 **iconv-tiny** output is identical to **iconv-lite** output, see [tests/regression.test.mjs](tests/regression.test.mjs).
 
@@ -122,10 +123,10 @@ All encodings are generated automatically from http://www.unicode.org/Public/MAP
 Comparison with iconv-lite module (Core i7-7500U CPU @ 2.7GHz, Node v24.2.0). Note: your results may vary, so please always check on your hardware.
 
 ```
-operation          iconv-lite@0.7.0   iconv-tiny@1.2.3
+operation          iconv-lite@0.7.2   iconv-tiny@1.4.0
 ------------------------------------------------------
-encode('win1251')     ~598 Mb/s          ~622 Mb/s
-decode('win1251')     ~218 Mb/s          ~263 Mb/s
+encode('win1251')     ~270 Mb/s          ~270 Mb/s
+decode('win1251')     ~120 Mb/s          ~220 Mb/s
 ```
 
 **iconv-lite** is NodeJS oriented and use specific API like `Buffer` and native NodeJS encodings.
@@ -140,7 +141,7 @@ decode('win1251')     ~218 Mb/s          ~263 Mb/s
 1. UTF-16 is an alias of UTF-16LE
 1. UTF-32 is an alias of UTF-32LE
 
-## Testing
+## Testing & Coverage
 
 ```
 $ git clone https://github.com/vip-delete/iconv-tiny.git
@@ -153,16 +154,22 @@ $ node tests\perf-test-unicode.mjs
 
 $ # To view test coverage:
 $ npm run coverage
-
-----------------|---------|----------|---------|---------|-------------------
-File            | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
-----------------|---------|----------|---------|---------|-------------------
-All files       |     100 |      100 |   96.72 |     100 |
- commons.mjs    |     100 |      100 |   81.81 |     100 |
- iconv-tiny.mjs |     100 |      100 |     100 |     100 |
- sbcs.mjs       |     100 |      100 |     100 |     100 |
- unicode.mjs    |     100 |      100 |     100 |     100 |
-----------------|---------|----------|---------|---------|-------------------
+-------------|---------|----------|---------|---------|-------------------
+File         | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
+-------------|---------|----------|---------|---------|-------------------
+All files    |   97.86 |    95.55 |   96.66 |   97.93 |
+ commons.mjs |   93.83 |       95 |   97.29 |    94.2 | 36-41,53-56
+ dbcs.mjs    |   97.02 |    89.47 |     100 |   96.87 | 27,134,143
+ iconv.mjs   |     100 |      100 |     100 |     100 |
+ mapped.mjs  |     100 |      100 |     100 |     100 |
+ native.mjs  |     100 |      100 |     100 |     100 |
+ sbcs.mjs    |     100 |     90.9 |     100 |     100 | 36-66
+ types.mjs   |     100 |      100 |      50 |     100 |
+ unicode.mjs |     100 |      100 |     100 |     100 |
+ utf16.mjs   |     100 |      100 |     100 |     100 |
+ utf32.mjs   |   98.76 |     97.5 |     100 |   98.76 | 224
+ utf8.mjs    |     100 |      100 |     100 |     100 |
+-------------|---------|----------|---------|---------|-------------------
 ```
 
 ## Commands

package/dist/iconv-tiny.d.mts

@@ -1,14 +1,3 @@
-export class IconvTiny {
-  /**
-   * @param encodings A map of encodings to support.
-   * @param aliases Comma-separated groups, each containing space-separated aliases for the same encoding.
-   */
-  constructor(encodings?: { [key: string]: EncodingFactory }, aliases?: string);
-  decode(array: Uint8Array, encoding: string, options?: OptionsAndDecoderOptions): string;
-  encode(content: string, encoding: string, options?: OptionsAndEncoderOptions): Uint8Array;
-  getEncoding(encoding: string, options?: Options): Encoding;
-}
-
 /**
  * Converts an encoding name to a normalized, unique name.
  * Removes non-alphanumeric characters and leading zeros.
@@ -18,31 +7,71 @@ export class IconvTiny {
  */
 export function canonicalize(encoding: string): string;
 
-interface Encoding {
-  getName(): string;
-  decode(array: Uint8Array, options?: DecoderOptions): string;
-  encode(text: string, options?: EncoderOptions): Uint8Array;
-  newDecoder(options?: DecoderOptions): CharsetDecoder;
-  newEncoder(options?: EncoderOptions): CharsetEncoder;
-}
+/**
+ * @param encodings - A map of encodings to support.
+ * @param aliases - Comma-separated groups, each containing space-separated aliases for the same encoding.
+ */
+export function createIconv(encodings?: { [key: string]: EncodingFactory }, aliases?: string): Iconv;
 
 interface EncodingFactory {
   create(options?: Options): Encoding;
 }
 
-interface CharsetDecoder {
-  decode(array?: Uint8Array): string;
+interface Iconv {
+  /** get/create an encoding, create a decoder, decode and flush */
+  decode(buf: Uint8Array, encoding: string, options?: OptionsAndDecoderOptions): string;
+  /** get/create an encoding, create a encoder, encode and flush */
+  encode(str: string, encoding: string, options?: OptionsAndEncoderOptions): Uint8Array;
+  /** get/create an encoding */
+  getEncoding(encoding: string, options?: Options): Encoding;
 }
 
-interface CharsetEncoder {
-  encode(text?: string): Uint8Array;
-  encodeInto(src: string, dst: Uint8Array): TextEncoderEncodeIntoResult;
+/** Encoding that doesn't keep any state */
+interface Encoding {
+  getName(): string;
+
+  /** get/create a decoder, decode and flush */
+  decode(buf: Uint8Array, options?: DecodeOptions): string;
+  /** get/create a encoder, encode and flush */
+  encode(str: string, options?: EncodeOptions): Uint8Array;
+
   /**
-   * Similar to Buffer.byteLength;
-   * @param src input to calculate the length of
+   * Similar to Buffer.byteLength.
+   *
+   * @param str - input to calculate the length of
    * @returns The number of bytes of the specified string
    */
-  byteLength(src: string): number;
+  byteLength(str: string): number;
+
+  // --- Low-level Stream APIs ---
+
+  /** create a decoder to keep the decoding state. */
+  getDecoder(options?: DecodeOptions): DecoderStream;
+  /** create an encoder to keep the encoding state. */
+  getEncoder(options?: EncodeOptions): EncoderStream;
+}
+
+/** Decoder to keep the decoding state */
+interface DecoderStream {
+  /** decode, keep the leftover in the state */
+  write(buf: Uint8Array): string;
+  /** flush the leftover */
+  end(): string;
+}
+
+/** Encoder to keep the encoding state */
+interface EncoderStream {
+  /** encode into a new array, keep the leftover in the state */
+  write(str: string): Uint8Array;
+  /** flush the leftover into a new array */
+  end(): Uint8Array;
+
+  // --- Low-Level Encoding APIs ---
+
+  /** encode into the given array, keep the leftover in the state */
+  encodeInto(str: string, buf: Uint8Array): TextEncoderEncodeIntoResult;
+  /** flush the leftover into the given array */
+  flushInto(buf: Uint8Array): TextEncoderEncodeIntoResult;
 }
 
 type TextEncoderEncodeIntoResult = {
@@ -50,11 +79,11 @@ type TextEncoderEncodeIntoResult = {
   written: number;
 }
 
-type DecoderOptions = {
+type DecodeOptions = {
   /**
    * Sets the replacement character used by the "decode" method for unmapped bytes (default: "�").
    */
-  defaultCharUnicode?: string | DefaultCharUnicodeFunction;
+  defaultCharUnicode?: string | DefaultFunction;
   /**
    * Specifies the behavior of the "decode" method (default: false)
    *
@@ -70,11 +99,11 @@ type DecoderOptions = {
   stripBOM?: boolean;
 };
 
-type EncoderOptions = {
+type EncodeOptions = {
   /**
    * Sets the replacement byte used by the "encode" method for unmapped symbols (default: "?").
    */
-  defaultCharByte?: string | DefaultCharByteFunction;
+  defaultCharByte?: string | DefaultFunction;
   /**
    * Unicode only. No BOM added by default, unless overridden by addBOM: true
    */
@@ -96,22 +125,16 @@ type Options = {
 type Overrides = Array<number | string>;
 
 /**
- * @param {number} input - input character code (0-65536)
- * @param {number} index - index of the character
- * @returns {number} default byte (0-255)
+ * @param {number} input - input character code (0-65535) if encoding; or an input byte (0-255) if decoding
+ * @param {number} index - index of the character if encoding; or an index of the byte if decoding
+ * @returns {number} default byte (0-255) if encoding; or a default character code (0-65535) if decoding
  */
-type DefaultCharByteFunction = (input: number, index: number) => number | null | undefined;
+type DefaultFunction = (input: number, index: number) => number | null | undefined;
 
-/**
- * @param {number} input - input byte (0-255)
- * @param {number} index - index of the byte
- * @returns {number} default character code (0-65536)
- */
-type DefaultCharUnicodeFunction = (input: number, index: number) => number | null | undefined;
-
-type OptionsAndDecoderOptions = Options & DecoderOptions;
-type OptionsAndEncoderOptions = Options & EncoderOptions;
+type OptionsAndDecoderOptions = Options & DecodeOptions;
+type OptionsAndEncoderOptions = Options & EncodeOptions;
 
+export const US_ASCII: EncodingFactory;
 export const ISO_8859_1: EncodingFactory;
 export const ISO_8859_2: EncodingFactory;
 export const ISO_8859_3: EncodingFactory;
@@ -128,6 +151,7 @@ export const ISO_8859_14: EncodingFactory;
 export const ISO_8859_15: EncodingFactory;
 export const ISO_8859_16: EncodingFactory;
 export const CP037: EncodingFactory;
+export const CP424: EncodingFactory;
 export const CP500: EncodingFactory;
 export const CP875: EncodingFactory;
 export const CP1026: EncodingFactory;
@@ -163,14 +187,15 @@ export const MAC_LATIN2: EncodingFactory;
 export const MAC_ROMAN: EncodingFactory;
 export const MAC_TURKISH: EncodingFactory;
 export const ATARIST: EncodingFactory;
-export const CP424: EncodingFactory;
 export const CP856: EncodingFactory;
 export const CP1006: EncodingFactory;
 export const KOI8_R: EncodingFactory;
 export const KOI8_U: EncodingFactory;
 export const KZ1048: EncodingFactory;
 export const NEXTSTEP: EncodingFactory;
-export const US_ASCII: EncodingFactory;
+export const JIS_0201: EncodingFactory;
+export const SHIFT_JIS: EncodingFactory;
+export const CP932: EncodingFactory;
 export const UTF8: EncodingFactory;
 export const UTF16LE: EncodingFactory;
 export const UTF16BE: EncodingFactory;