@vbarbarosh/node-helpers 3.75.0 → 3.76.1

package/src/cli.js

@@ -9,7 +9,9 @@ function cli(main, report = error => console.error(error))
     // https://stackoverflow.com/a/46916601/1478566
     const timer = setInterval(v => v, 1E9);
 
-    Promise.resolve(main()).then(resolve, reject);
+    // Promise.resolve(main()) would evaluate main() before wrapping:
+    // a synchronous throw would bypass report() and the exit code handling
+    Promise.try(main).then(resolve, reject);
 
     function resolve() {
         clearInterval(timer);

package/src/cli.md

@@ -0,0 +1,15 @@
+Entry point for Node CLI apps. Runs `main` (sync or async), keeps the event
+loop alive until it settles, and turns a failure into a proper exit code.
+
+- Resolves → the process exits naturally with code `0`.
+- Rejects or throws → the error is passed to `report` (default
+  `console.error`), then `process.exit(1)`.
+- An `ExitCodeError` exits with its `exit_code` instead of `1`.
+- Synchronous throws from `main` are handled the same way as rejections —
+  they do not bypass `report` or the exit code handling.
+
+```js
+cli(async function main() {
+    // ...
+});
+```

package/src/const_stream.md

@@ -0,0 +1,7 @@
+Constants for passing values through Node.js streams that the stream
+protocol itself cannot carry.
+
+**Members:**
+- `const_stream.null` — a `Symbol('stream[null]')` used to represent `null`
+  inside an object-mode stream, since pushing a real `null` is the
+  end-of-stream mark.

package/src/const_type.md

@@ -0,0 +1,5 @@
+String constants for the type names returned by `gettype`. Covers the
+standard `typeof` results (`'null'`, `'undefined'`, `'boolean'`, `'number'`,
+`'bigint'`, `'string'`, `'symbol'`, `'function'`, `'object'`) plus the extra
+distinctions `gettype` makes: `array` → `'array'`, `nan` → `'nan'`,
+`neg_inf` → `'-inf'`, `pos_inf` → `'+inf'`.

package/src/countdown.js

@@ -2,7 +2,7 @@ const Promise = require('bluebird');
 
 /**
  * Wait for a promise/value to be settled. Meanwhile, call `tick` function every `tick_ms` milliseconds.
- * After `timeout` seconds, reject with 'Timeout' error.
+ * After `timeout` milliseconds, reject with 'Timeout' error.
  *
  * @see user_friendly_status
  * @see progress
@@ -11,38 +11,55 @@ function countdown(ctx)
 {
     let done = false;
     let timer = null;
+    let timeout_timer = null;
     return new Promise(function (resolve, reject) {
         ctx.value = ctx.fn ? Promise.method(ctx.fn).call() : Promise.resolve(ctx.value);
         ctx.timeout = ctx.timeout || 0; // ⚠️ Rename to timeout_ms
         ctx.time_now = new Date();
         ctx.time_begin = new Date();
-        ctx.time_end = Date.now() + ctx.timeout;
+        // No timeout means no deadline
+        ctx.time_end = ctx.timeout ? Date.now() + ctx.timeout : Infinity;
         ctx.tick_ms = ctx.tick_ms || 1000;
         ctx.tick = ctx.tick || function () {};
         ctx.resolve = function (value) {
             if (done) {
-                throw new Error('Already settled');
+                return;
             }
             done = true;
             clearInterval(timer);
+            clearTimeout(timeout_timer);
             resolve(value);
         };
         ctx.reject = function (error) {
             if (done) {
-                throw new Error('Already settled');
+                return;
             }
             done = true;
             clearInterval(timer);
+            clearTimeout(timeout_timer);
             reject(error);
         };
         timer = setInterval(tick, ctx.tick_ms);
+        if (ctx.timeout) {
+            // The interval alone enforces the deadline only at tick_ms granularity
+            timeout_timer = setTimeout(tick, ctx.timeout);
+        }
         ctx.value.then(ctx.resolve, ctx.reject);
         tick();
         function tick() {
             ctx.time_now = Date.now();
             ctx.time_elapsed = ctx.time_now - ctx.time_begin;
             ctx.time_remained = Math.max(0, ctx.time_end - ctx.time_now);
-            ctx.tick(ctx);
+            try {
+                ctx.tick(ctx);
+            }
+            catch (error) {
+                // A throwing tick must reject and clear the timers: a bare
+                // throw inside setInterval is an uncaughtException, and the
+                // interval would keep firing (and throwing) forever.
+                ctx.reject(error);
+                return;
+            }
             if (!ctx.time_remained) {
                 ctx.reject(new Error('Timeout'));
             }

package/src/countdown.md

@@ -0,0 +1,21 @@
+Wait for a promise/value to settle while calling `ctx.tick(ctx)` every
+`ctx.tick_ms` milliseconds (default 1000, first call is immediate). After
+`ctx.timeout` milliseconds, reject with a `Timeout` error; without `timeout`
+there is no deadline.
+
+**Input:** a single `ctx` object with either `value` (promise or plain value)
+or `fn` (called once; sync throws become rejections). `countdown` mutates
+`ctx`, exposing `time_begin`, `time_now`, `time_elapsed`, `time_remained`,
+and `resolve`/`reject` functions — so `tick` can render progress or settle
+the countdown early. A throwing `tick` rejects and stops the timers.
+
+```js
+await countdown({
+    fn: () => upload(file),
+    timeout: 60000,
+    tick_ms: 1000,
+    tick: ctx => console.log(`${ctx.time_elapsed}ms elapsed`),
+});
+```
+
+@see user_friendly_status, eta

package/src/crypto_decrypt_aes256.md

@@ -0,0 +1,13 @@
+Decrypts a `Buffer` produced by `crypto_encrypt_aes256` (`aes-256-ctr`, key =
+`sha256(password)`, layout `[iv_length, iv, ciphertext]`). Returns the
+plaintext as a `Buffer` — call `.toString('utf8')` for text.
+
+```js
+const ivenc = crypto_encrypt_aes256('pass123', 'hello');
+crypto_decrypt_aes256('pass123', ivenc).toString('utf8');   // 'hello'
+crypto_decrypt_aes256('wrong', ivenc).toString('utf8');     // garbage, no error
+```
+
+**No integrity check:** CTR mode does not authenticate — a wrong password or
+tampered ciphertext yields garbage bytes, never an error, so verify the result
+yourself if you need to detect bad input.

package/src/crypto_encrypt_aes256.md

@@ -0,0 +1,13 @@
+Encrypts data with `aes-256-ctr`. The key is `sha256(password)`, the IV is a
+fresh random 16 bytes on every call, so encrypting the same input twice gives
+different output. Returns a `Buffer` laid out as `[iv_length, iv, ciphertext]`
+(1 + 16 + data-length bytes); pass it as-is to `crypto_decrypt_aes256`.
+
+```js
+const ivenc = crypto_encrypt_aes256('pass123', 'hello');
+// <Buffer 10 ...> — 22 bytes: 0x10 (iv length), 16-byte iv, 5-byte ciphertext
+crypto_decrypt_aes256('pass123', ivenc).toString('utf8');  // 'hello'
+```
+
+**No integrity check:** CTR mode does not authenticate — a wrong password or
+tampered data decrypts to garbage, not an error.

package/src/crypto_hash_md5.md

@@ -0,0 +1,10 @@
+Computes the MD5 hash of a string or `Buffer`. Returns a 16-byte `Buffer` —
+call `.toString('hex')` for the usual hex digest.
+
+```js
+crypto_hash_md5('hello').toString('hex')
+// '5d41402abc4b2a76b9719d911017c592'
+```
+
+MD5 is broken for security purposes; use it for checksums and cache keys, and
+`crypto_hash_sha256` where collision resistance matters.

package/src/crypto_hash_sha256.md

@@ -0,0 +1,10 @@
+Computes the SHA-256 hash of a string or `Buffer`. Returns a 32-byte `Buffer`
+— call `.toString('hex')` for the usual hex digest.
+
+```js
+crypto_hash_sha256('hello').toString('hex')
+// '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824'
+```
+
+For a keyed hash (verifying that data came from someone who knows a secret)
+use `crypto_hmac_sha256` instead of hashing a concatenation.

package/src/crypto_hmac_sha256.md

@@ -0,0 +1,11 @@
+Computes the HMAC-SHA256 of `data` keyed with `password` (both strings or
+`Buffer`s). Returns a 32-byte `Buffer` — call `.toString('hex')` for the usual
+hex form.
+
+```js
+crypto_hmac_sha256('key', 'The quick brown fox jumps over the lazy dog').toString('hex')
+// 'f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8'
+```
+
+Unlike `crypto_hash_sha256`, the output depends on the key, so it can
+authenticate data: only holders of the key can produce or verify the mac.

package/src/date_add_hours.md

@@ -0,0 +1,8 @@
+Adds `hours` hours to a `Date` via `setHours`. **Mutates the passed `Date` in
+place and returns the same instance** — clone first if the original must be
+preserved. Negative values subtract; overflow rolls over into the next
+day/month/year.
+
+```js
+date_add_hours(new Date('2026/07/06 23:30:00'), 2)    // 2026/07/07 01:30:00 (same Date object)
+```

package/src/date_add_milliseconds.md

@@ -0,0 +1,4 @@
+Adds `milliseconds` milliseconds to a `Date` via `setMilliseconds`. **Mutates
+the passed `Date` in place and returns the same instance** — clone first if the
+original must be preserved. Negative values subtract; overflow rolls over into
+seconds and beyond.

package/src/date_add_minutes.md

@@ -0,0 +1,4 @@
+Adds `minutes` minutes to a `Date` via `setMinutes`. **Mutates the passed
+`Date` in place and returns the same instance** — clone first if the original
+must be preserved. Negative values subtract; overflow rolls over into hours and
+beyond.

package/src/date_add_months.md

@@ -0,0 +1,13 @@
+Adds `months` calendar months to a `Date`. **Mutates the passed `Date` in
+place and returns the same instance** (a falsy `months`, e.g. `0`, is a no-op).
+Negative values subtract.
+
+Unlike a bare `setMonth`, the day of month never overflows into the next
+month: when the target month is shorter, the date is clamped to its last day
+(Carbon-style behavior).
+
+```js
+date_add_months(new Date('2023/01/31'), 1)     // 2023/02/28, not 2023/03/03
+date_add_months(new Date('2019/03/31'), -1)    // 2019/02/28
+date_add_months(new Date('2024/02/29'), 12)    // 2025/02/28
+```

package/src/date_add_seconds.md

@@ -0,0 +1,4 @@
+Adds `seconds` seconds to a `Date` via `setSeconds`. **Mutates the passed
+`Date` in place and returns the same instance** — clone first if the original
+must be preserved. Negative values subtract; overflow rolls over into minutes
+and beyond.

package/src/date_diff_seconds.md

@@ -0,0 +1,4 @@
+Returns the difference `a - b` between two `Date`s in whole seconds:
+`Math.floor((a.getTime() - b.getTime()) / 1000)`. Positive when `a` is later
+than `b`. Because of the flooring, negative sub-second differences round away
+from zero: if `b` is 500 ms later than `a`, the result is `-1`, not `0`.

package/src/date_is_leap_year.md

@@ -0,0 +1,9 @@
+Returns `true` if the `Date`'s year (local time, `getFullYear`) is a Gregorian
+leap year: divisible by 4, except century years not divisible by 400. Verified
+by brute force against `Date` itself for years 100–9998.
+
+```js
+date_is_leap_year(new Date('2024/01/01'))    // true
+date_is_leap_year(new Date('1900/01/01'))    // false (century, not /400)
+date_is_leap_year(new Date('2000/01/01'))    // true
+```

package/src/escape_content_disposition.js

@@ -9,10 +9,13 @@ function escape_content_disposition(s)
         .replaceAll('%', '\\%')
         .replaceAll('\n', '%x0A')
         .replaceAll('\0', '%x00');
-    if (out.match(/\s|;/)) {
-        return `"${out}"`;
+    // A bare value must be a pure RFC 7230 token: any other character
+    // (space, ';', ',', '"', '\', ...) requires the whole value to be a
+    // quoted-string — an unquoted 'a\"b' or 'a,b' breaks header parsing.
+    if (out === s && /^[!#$%&'*+.^_`|~0-9a-zA-Z-]+$/.test(s)) {
+        return s;
     }
-    return out;
+    return `"${out}"`;
 }
 
 module.exports = escape_content_disposition;

package/src/escape_content_disposition.md

@@ -0,0 +1,13 @@
+Escapes a value (typically a filename) for use in a `Content-Disposition`
+header. A pure RFC 7230 token (letters, digits, `!#$%&'*+.^_`|~-`) is returned
+as-is; anything else — spaces, `;`, `,`, quotes, etc. — becomes a quoted-string
+with `\` `"` `%` backslash-escaped and `\n`/`\0` encoded as `%x0A`/`%x00`.
+An unquoted `a"b` or `a,b` would break header parsing.
+
+```js
+escape_content_disposition('report.pdf')  // 'report.pdf'
+escape_content_disposition('foo bar.txt') // '"foo bar.txt"'
+escape_content_disposition('foo"bar')     // '"foo\\"bar"'
+escape_content_disposition('foo\nbar')    // '"foo%x0Abar"'
+escape_content_disposition('')            // '""'
+```

package/src/escape_regexp.md

@@ -0,0 +1,7 @@
+Escapes regular-expression special characters (`. * + ? ^ $ { } ( ) | [ ] \`)
+in a string with a backslash, so the string can be embedded literally in
+`new RegExp(...)`.
+
+```js
+escape_regexp('a.b*c?')    // 'a\\.b\\*c\\?'
+```

package/src/eta.js

@@ -5,7 +5,13 @@ function eta(time0, total, done, resumed = 0)
     const seconds = (Date.now() - time0)/1000;
     const remained = total - done;
     const bps = (done - resumed)/seconds;
-    return format_seconds(remained/bps);
+    const seconds_remained = remained/bps;
+    // No progress yet (e.g. the first tick of a progress loop): remained/bps
+    // is Infinity or NaN, which format_seconds renders as 0Infinity:0NaN:0NaN
+    if (!Number.isFinite(seconds_remained)) {
+        return '--:--:--';
+    }
+    return format_seconds(seconds_remained);
 }
 
 module.exports = eta;

package/src/eta.md

@@ -0,0 +1,18 @@
+Estimates the remaining time of a progress loop and formats it as `HH:MM:SS`
+(via `format_seconds`). The rate is derived from what was processed since
+`time0`; pass `resumed` to exclude units that were already done at start (e.g.
+a resumed download), so they don't inflate the rate.
+
+## Signature
+
+```
+eta(time0, total, done, resumed = 0) → string
+```
+
+`time0` is a `Date.now()`-style start timestamp in milliseconds. When no
+progress was made yet (rate is zero), returns the placeholder `'--:--:--'`.
+
+```js
+eta(Date.now() - 10000, 100, 50)    // '00:00:10'
+eta(Date.now(), 100, 0)             // '--:--:--'
+```

package/src/factorize_ms.js

@@ -1,5 +1,8 @@
 function factorize_ms(v)
 {
+    // Factorize the magnitude: the sign is the caller's concern, and
+    // sub-millisecond fractions are truncated.
+    v = Math.trunc(Math.abs(v));
     const h = Math.floor(v / 3600000);
     const m = Math.floor(v % 3600000 / 60000);
     const s = Math.floor(v % 60000 / 1000);

package/src/factorize_ms.md

@@ -0,0 +1,10 @@
+Splits a duration in milliseconds into `[hours, minutes, seconds, ms]`.
+Hours are unbounded (no days component). The magnitude is factorized: negative
+input gives the same result as its absolute value — the sign is the caller's
+concern — and sub-millisecond fractions are truncated.
+
+```js
+factorize_ms(3723456)    // [1, 2, 3, 456]
+factorize_ms(-1500.7)    // [0, 0, 1, 500]
+factorize_ms(999)        // [0, 0, 0, 999]
+```

package/src/fastdl.js

@@ -36,6 +36,7 @@ async function fastdl({file, read_stream_with_range, concurrency = 60, user_frie
     let connections = 0;
     let next_first = 0;
     let total_written = 0;
+    let rs0_used = false;
 
     const timer = setInterval(tick, 1000);
     function tick() {
@@ -70,15 +71,17 @@ async function fastdl({file, read_stream_with_range, concurrency = 60, user_frie
             if (first > last) {
                 return;
             }
-            const rs = (first === 0) ? rs0 : await read_stream_with_range(first, last);
+            const rs = (first === 0 && !rs0_used) ? rs0 : await read_stream_with_range(first, last);
+            rs0_used = rs0_used || (rs === rs0);
             if (rs.content_range.total !== total) {
                 rs.once('error', ignore);
                 rs.destroy();
                 throw new UserFriendlyError('Size of a file changed during download');
             }
+            let counted = 0;
             const acc = new stream.PassThrough({
                 transform(buf, encoding, next) {
-                    first += buf.length;
+                    counted += buf.length;
                     total_written += buf.length;
                     progress.add(buf.length);
                     next(null, buf);
@@ -88,7 +91,15 @@ async function fastdl({file, read_stream_with_range, concurrency = 60, user_frie
                 flags: fs.constants.O_WRONLY, // |fs.constants.O_CREAT,
                 start: first,
             });
-            await stream.promises.pipeline(rs, acc, ws);
+            try {
+                await stream.promises.pipeline(rs, acc, ws);
+            }
+            catch (error) {
+                // Counted bytes may not have reached the disk; retry rewrites the chunk from its start
+                total_written -= counted;
+                progress.add(-counted);
+                throw error;
+            }
         }
     }
 }

package/src/fcmp_dates.md

@@ -0,0 +1,12 @@
+Compares two `Date` objects for sorting, ascending, by returning the difference
+of their timestamps in milliseconds (`a.getTime() - b.getTime()`). Distinct
+`Date` objects with the same timestamp compare equal. Throws if either argument
+is not a `Date`.
+
+```js
+const input = ['2022-05-01', '1999-12-31', '2000-01-01'].map(v => new Date(v));
+input.sort(fcmp_dates); // 1999-12-31, 2000-01-01, 2022-05-01
+```
+
+`fcmp_default` also orders `Date` objects (via `<`/`>`), so this is only needed
+when a dedicated date comparator is clearer.

package/src/fcmp_default.js

@@ -1,5 +1,12 @@
+const fcmp_utf8_natural_bin = require('./fcmp_utf8_natural_bin');
+
+// See fcmp_default.md
 function fcmp_default(a, b)
 {
+    if (typeof a === 'string' && typeof b === 'string') {
+        // Natural order: '2' < '10', 'file2' < 'file10'
+        return fcmp_utf8_natural_bin(a, b);
+    }
     if (a < b) {
         return -1;
     }

package/src/fcmp_default.md

@@ -0,0 +1,29 @@
+Compares two values for sorting. Numbers, dates, and bigints compare via
+`<`/`>`. Strings compare in natural order: digit chunks — ASCII `[0-9]` only,
+Unicode digits are treated as plain text — compare numerically, all other
+characters compare in UTF-16 code-unit order, exactly like the plain `<`/`>`
+operators. No `Intl`/ICU is involved — the order is identical on every machine.
+
+```js
+[999, 22, 15, 10, 3, 2, 1].sort(fcmp_default)       // 1 2 3 10 15 22 999
+['10', '2', '1'].sort(fcmp_default)                 // '1' '2' '10'
+['ccc', 'aaa', 'CCC', 'AAA'].sort(fcmp_default)     // 'AAA' 'CCC' 'aaa' 'ccc'
+['readme.md', 'README.md'].sort(fcmp_default)       // 'README.md' 'readme.md'
+['a10', 'a2', 'A20', 'A3'].sort(fcmp_default)       // 'A3' 'A20' 'a2' 'a10'
+```
+
+This is the default comparator behind `array_sort`, `array_sort_other`,
+`fcmp_tuples`, and `fcmpx`; `fcmp_default_desc` is its descending mirror. For
+strict UTF-16 code-unit ordering of digit-bearing strings use `fcmp_utf8_bin`;
+for locale-aware ordering use the `fcmp_utf8_*` family.
+
+Caveats:
+
+- Equal digit values with different padding order by padding: `'2' < '02'`
+  (fewer leading zeros first). They never compare equal, so the order is
+  total and stable.
+- Mixed types (number vs string) are not a total order; sorting a
+  heterogeneous array gives unspecified order between types.
+
+Changed in v3.76: digit chunks used to compare by code units, which put
+`'10'` before `'2'`.

package/src/fcmp_default_desc.js

@@ -1,12 +1,9 @@
+const fcmp_default = require('./fcmp_default');
+
+// See fcmp_default.md
 function fcmp_default_desc(b, a)
 {
-    if (a < b) {
-        return -1;
-    }
-    if (a > b) {
-        return 1;
-    }
-    return 0;
+    return fcmp_default(a, b);
 }
 
 module.exports = fcmp_default_desc;

package/src/fcmp_default_desc.md

@@ -0,0 +1,10 @@
+Descending mirror of `fcmp_default`: it calls `fcmp_default` with the arguments
+swapped, so everything in `fcmp_default.md` (natural string order, deterministic
+no-`Intl` comparison, caveats) applies here in reverse.
+
+```js
+[1, 10, 2, 9].sort(fcmp_default_desc)                   // 10 9 2 1
+['file1', 'file10', 'file2'].sort(fcmp_default_desc)    // 'file10' 'file2' 'file1'
+```
+
+For descending order by an object property use `fcmpx('-prop')` instead.

package/src/fcmp_from_spec.md

@@ -0,0 +1,13 @@
+Creates a comparator from an array of property names; prefix a name with `-`
+for descending order. Each property compares with `localeCompare` when both
+values are strings (locale-dependent, no natural order), and with subtraction
+otherwise.
+
+```js
+items.sort(fcmp_from_spec(['-price', 'name', 'id']));
+// price desc, then name asc, then id asc
+```
+
+**Deprecated:** use `fcmpx` instead — it supports paths (`'user.email'`),
+functions, natural string order via `fcmp_default`, and defined-before-missing
+ordering.

package/src/fcmp_numbers.md

@@ -0,0 +1,11 @@
+Compares two numbers for sorting, ascending, via plain subtraction (`a - b`).
+Useful because the default `[].sort()` compares numbers as strings.
+
+```js
+[10, 9, 1, 100, 2].sort()               // 1 10 100 2 9 (default sort is lexicographic)
+[10, 9, 1, 100, 2].sort(fcmp_numbers)   // 1 2 9 10 100
+```
+
+Incomparable pairs (`NaN` vs anything, `Infinity` vs `Infinity`) return `NaN`,
+not `0`. For mixed types use `fcmp_default`, which also sorts numbers
+ascending and handles `NaN` by returning `0`.

package/src/fcmp_tuples.md

@@ -0,0 +1,17 @@
+Compares two arrays (tuples) lexicographically: items are compared pairwise
+with `fcmp` (default `fcmp_default`) and the first non-zero result wins.
+
+## Signature
+
+```js
+fcmp_tuples(a, b, fcmp = fcmp_default)
+```
+
+```js
+[[2, 1], [1, 2], [1, 1]].sort(fcmp_tuples)  // [1,1] [1,2] [2,1]
+fcmp_tuples([1], [1, 2])                    // 0 — length is not a tiebreaker
+```
+
+Only the first `Math.min(a.length, b.length)` items are compared: a shorter
+tuple that is a prefix of a longer one compares as equal (unlike string
+comparison, where `'a' < 'ab'`).

package/src/fcmp_utf8_bin.md

@@ -0,0 +1,14 @@
+Strict binary string comparison via the plain `<`/`>` operators — UTF-16
+code-unit order, like MySQL's `utf8_bin` collation. Case-sensitive, all
+uppercase ASCII sorts before lowercase, no numeric awareness
+(`'file10' < 'file2'`). No `Intl`/ICU is involved — the order is identical
+on every machine, unlike the other `fcmp_utf8_*` comparators.
+
+```js
+['b', 'A', 'a', 'B'].sort(fcmp_utf8_bin)    // 'A' 'B' 'a' 'b'
+['file10', 'file2'].sort(fcmp_utf8_bin)     // 'file10' 'file2'
+```
+
+For deterministic natural order (`'file2' < 'file10'`) use
+`fcmp_utf8_natural_bin` (the string order behind `fcmp_default`/`fcmpx`);
+for locale-aware ordering use `fcmp_utf8_cs`/`_ci`.

package/src/fcmp_utf8_ci.md

@@ -0,0 +1,14 @@
+Locale-aware, case-insensitive string comparison, like MySQL's `utf8_ci` /
+`utf8mb4_ci` collations. Uses `localeCompare` with `{sensitivity: 'base'}`,
+so both case and accents are ignored: `'a'` = `'A'`, `'é'` = `'e'`. No numeric
+awareness (`'file10' < 'file2'`).
+
+```js
+['b', 'A', 'B', 'a'].sort(fcmp_utf8_ci)     // 'A' 'a' 'b' 'B' ([].sort is stable)
+fcmp_utf8_ci('HELLO', 'hello')              // 0
+```
+
+Results depend on the runtime locale/ICU, unlike `fcmp_utf8_bin` and
+`fcmp_utf8_natural_bin`, which are deterministic on every machine. For a
+case-sensitive locale-aware order use `fcmp_utf8_cs`; for locale-aware natural
+order use `fcmp_utf8_natural_ci`.

package/src/fcmp_utf8_cs.md

@@ -0,0 +1,15 @@
+Locale-aware, case-sensitive string comparison, like MySQL's `utf8_cs` /
+`utf8mb4_cs` collations but using the runtime locale. Uses `localeCompare`
+with `{sensitivity: 'variant'}`: base letters dominate, so `'apple' < 'Banana'`
+(unlike code-unit order), while case and accents still distinguish otherwise
+equal strings. No numeric awareness.
+
+```js
+['cherry', 'Apple', 'banana'].sort(fcmp_utf8_cs)    // 'Apple' 'banana' 'cherry'
+```
+
+Results depend on the runtime locale/ICU — the exact order of case/accent
+variants varies between machines; use `fcmp_utf8_bin` or
+`fcmp_utf8_natural_bin` (the string order behind `fcmp_default`) for a
+deterministic order. For ignoring case use `fcmp_utf8_ci`; for natural order
+use `fcmp_utf8_natural_cs`.

package/src/fcmp_utf8_natural_bin.js

@@ -0,0 +1,38 @@
+// Natural sort (numeric), code-unit order for everything else.
+// Deterministic on every machine — no Intl/ICU involved. See fcmp_default.md
+function fcmp_utf8_natural_bin(a, b)
+{
+    const ax = a.match(/\d+|\D+/g) || [];
+    const bx = b.match(/\d+|\D+/g) || [];
+    const end = Math.min(ax.length, bx.length);
+    for (let i = 0; i < end; ++i) {
+        const is_digits = (ax[i][0] <= '9' && bx[i][0] <= '9' && ax[i][0] >= '0' && bx[i][0] >= '0');
+        const tmp = is_digits ? fcmp_digits(ax[i], bx[i]) : fcmp_units(ax[i], bx[i]);
+        if (tmp) {
+            return tmp;
+        }
+    }
+    return ax.length - bx.length;
+}
+
+// Compare digit runs of any length by numeric value (no Number() overflow);
+// equal values differ by padding: fewer leading zeros first ('2' < '02')
+function fcmp_digits(a, b)
+{
+    const as = a.replace(/^0+/, '');
+    const bs = b.replace(/^0+/, '');
+    return (as.length - bs.length) || fcmp_units(as, bs) || (a.length - b.length);
+}
+
+function fcmp_units(a, b)
+{
+    if (a < b) {
+        return -1;
+    }
+    if (a > b) {
+        return 1;
+    }
+    return 0;
+}
+
+module.exports = fcmp_utf8_natural_bin;

package/src/fcmp_utf8_natural_bin.md

@@ -0,0 +1,8 @@
+Natural string comparison without locale: digit chunks — ASCII `[0-9]` only,
+Unicode digits are treated as plain text — compare numerically (`'2' < '10'`,
+`'file2' < 'file10'`), everything else compares in UTF-16 code-unit order
+(uppercase before lowercase). Deterministic on every machine — no `Intl`/ICU.
+Accepts strings only, like the rest of the `fcmp_utf8_*` family; `fcmp_default`
+handles other types before delegating string pairs here.
+This is the string order behind `fcmp_default`; see `fcmp_default.md` for
+caveats. For locale-aware natural order use `fcmp_utf8_natural_cs`/`_ci`.