@vbarbarosh/node-helpers 3.74.1 → 3.76.0

package/src/fcmp_utf8_natural_cs.md

@@ -0,0 +1,13 @@
+Locale-aware natural string comparison, case-sensitive: `localeCompare` with
+`{numeric: true, sensitivity: 'variant'}`. Digit chunks compare as numbers
+(`'file2' < 'file10'`), base letters dominate (`'apple2' < 'Banana1'`), and
+case/accents distinguish otherwise equal strings.
+
+```js
+['a10', 'a2', 'A20', 'A3'].sort(fcmp_utf8_natural_cs)   // 'a2' 'A3' 'a10' 'A20'
+```
+
+Results depend on the runtime locale/ICU — the exact order of case variants
+varies between machines. For deterministic natural order (uppercase before
+lowercase, identical everywhere) use `fcmp_utf8_natural_bin`, the string order
+behind `fcmp_default`/`fcmpx`. For ignoring case use `fcmp_utf8_natural_ci`.

package/src/fcmpx.md

@@ -1,17 +1,34 @@
-Comparator builder using compact expressions.
+Comparator builder using compact expressions: creates an `fcmp` function
+suitable for `[].sort()`. Values compare with `fcmp_default` (natural order —
+see `fcmp_default.md`) unless a custom `fcmp` is given.
 
-fcmp expression — Creates an `fcmp` function from an expression, suitable for use with `[].sort()`.
+**Expression forms** (composable — an array mixes any of them as sort keys,
+first key wins, later keys break ties):
 
 ```js
-fcmpx('user.email')
-fcmpx('-user.age,user.email')
-fcmpx(v => v.user.email)
-fcmpx(['user.age', 'user.email'])
-fcmpx(['-user.age', 'user.email'])
+fcmpx('user.email')                       // dotted property path
+fcmpx('-user.age')                        // '-' prefix → descending
+fcmpx('-user.age,user.email')             // comma → multiple keys
+fcmpx(v => v.user.email)                  // read function
+fcmpx('')                                 // '' or '.' → the item itself
+fcmpx(['-age', 'name'])                   // array of keys
+fcmpx({read: 'v', fcmp: (a, b) => b - a}) // object form: custom comparator
+fcmpx({read: 'type', top: ['dir']})       // listed values first, in listed order
+fcmpx({read: 'type', bottom: ['tmp']})    // listed values last
+fcmpx({read: 'age', desc: true})          // descending via object form
 ```
 
-Sorting rule: Missing values are considered greater than any defined value
-and are therefore placed after all defined values.
+```js
+users.sort(fcmpx('-age,name'));
+// age 35 first, ties by name; {name: 'bob'} (no age) goes last
+
+files.sort(fcmpx([{read: 'type', top: ['dir', 'file']}, 'name']));
+// dirs, then files, then everything else — each group sorted by name
+```
+
+**Missing values:** `null`/`undefined` (and dead-end paths) are considered
+greater than any defined value, so they always land after all defined values —
+even in descending order.
 
 - YouTube: [Сортировка объектов в JavaScript](https://www.youtube.com/watch?v=rHEH_JfQjL4)
 - https://github.com/vbarbarosh/speaking/tree/master/20250822-js-sort-fcmpx

package/src/filter1_from_spec.js

@@ -39,8 +39,8 @@ function parse_spec(spec)
 function parse_expr(expr)
 {
     let substr;
-    let starts = false; // ^
-    let ends = false; // $
+    let starts; // ^
+    let ends; // $
     substr = expr.replaceAll('^', '');
     starts = (substr.length !== expr.length);
     expr = substr;
@@ -50,7 +50,7 @@ function parse_expr(expr)
     substr = expr.replaceAll('!', '');
     if ((expr.length - substr.length) % 2) { // not
         if (starts && ends) {
-            return s => !s.startsWith(substr) && !s.endsWith(substr);
+            return s => !(s.startsWith(substr) && s.endsWith(substr));
         }
         if (starts) {
             return s => !s.startsWith(substr);

package/src/format_bytes.md

@@ -0,0 +1,15 @@
+Formats a byte count as a human-readable size using base-1024 math with
+`B`/`KB`/`MB`/`GB`/`TB`/`PB` suffixes.
+
+- Non-number or `NaN` input returns `'n/a'`.
+- `0` returns `'0KB'`; any other value below 1024 returns `'1KB'` — sizes are
+  never shown in bytes or fractions of a KB.
+- Values up to 1 MB are rounded to a whole number; above 1 MB two decimals are
+  kept, with a trailing `.00` collapsed to `.0`.
+
+```js
+format_bytes(500)              // '1KB'
+format_bytes(2048)             // '2KB'
+format_bytes(2*1024*1024)      // '2.0MB'
+format_bytes(35.45*1024*1024)  // '35.45MB'
+```

package/src/format_date.md

@@ -0,0 +1,7 @@
+Formats a `Date` as `YYYY/MM/DD HH:MM:SS` in local time, all fields
+zero-padded to two digits. Same output as `format_date_human`, which is the
+more readable implementation.
+
+```js
+format_date(new Date('2026/07/06 09:05:03'))    // '2026/07/06 09:05:03'
+```

package/src/format_date_fs.md

@@ -0,0 +1,7 @@
+Formats a `Date` as `YYYYMMDD_HHMMSS` in local time — no separators except the
+underscore, so the result is safe to use in file names and sorts
+chronologically.
+
+```js
+format_date_fs(new Date('2026/07/06 09:05:03'))    // '20260706_090503'
+```

package/src/format_date_human.md

@@ -0,0 +1,6 @@
+Formats a `Date` as `YYYY/MM/DD HH:MM:SS` in local time, all fields
+zero-padded to two digits. Produces the same output as `format_date`.
+
+```js
+format_date_human(new Date('2026/07/06 09:05:03'))    // '2026/07/06 09:05:03'
+```

package/src/format_date_ymd.md

@@ -0,0 +1,6 @@
+Formats the date part of a `Date` as `YYYY/MM/DD` in local time, month and day
+zero-padded to two digits.
+
+```js
+format_date_ymd(new Date('2026/07/06 09:05:03'))    // '2026/07/06'
+```

package/src/format_error_report.js

@@ -37,11 +37,11 @@ ${JSON.stringify(error.response.config.headers||{}, null, 4).slice(1, -1).replac
 
 ${error.response.status} ${error.response.statusText}
 
-${(error.response.data.toString()||'').slice(0, 10240) || 'n/a'}
+${String(error.response.data ?? '').slice(0, 10240) || 'n/a'}
 
 --- STACK ---
 
-${error.stack ? error.stack.split(/\\n\\s*/) : 'n/a'}
+${error.stack ?? 'n/a'}
 `.trimStart();
 }
 
@@ -58,7 +58,7 @@ ${JSON.stringify(error.config.headers||{}, null, 4).slice(1, -1).replace(/^\s+|,
 
 --- STACK ---
 
-${error.stack ? error.stack.split(/\\n\\s*/) : 'n/a'}
+${error.stack ?? 'n/a'}
 `.trimStart();
 }
 

package/src/format_error_report.md

@@ -0,0 +1,12 @@
+Formats an error into a multi-line text report suitable for logs. Axios
+errors get special treatment; everything else becomes indented JSON.
+
+**Rules:**
+- Axios error with a response (`error.response.status/statusText/config`) —
+  plain-text report with `--- REQUEST ---` (method, url, headers),
+  `--- RESPONSE ---` (status, first 10240 chars of body), and `--- STACK ---` sections.
+- Axios error without a response (`error.config`) — same, minus the RESPONSE section.
+- Any other truthy error — JSON with `code`, `name`, `message`, and `stack`
+  split into an array of lines (circular-safe via `json_stringify_safe`).
+- Falsy error — `{"error":null}`-style JSON; `undefined` is reported as the
+  string `'---undefined---'`.

package/src/format_kilo.md

@@ -0,0 +1,13 @@
+Formats a number in metric (base-1000) notation with `K`/`M`/`G`/`T`/`P`
+suffixes.
+
+- Non-number or `NaN` input returns `'n/a'`.
+- `0` returns `'0'`; values below 1000 are rounded to a whole number, no
+  suffix.
+- Values of 1000 and above always keep two decimals.
+
+```js
+format_kilo(55.55)      // '56'
+format_kilo(1500)       // '1.50K'
+format_kilo(35.45e6)    // '35.45M'
+```

package/src/format_ms.js

@@ -10,11 +10,12 @@ function format_ms(ms)
     }
 
     // 00:05
+    const sign = ms < 0 ? '-' : '';
     const [h, m, s] = factorize_ms(ms);
     if (h) {
-        return `0${h}:0${m}:0${s}`.replace(/0+(?=\d\d)/g, '');
+        return sign + `0${h}:0${m}:0${s}`.replace(/0+(?=\d\d)/g, '');
     }
-    return `0${m}:0${s}`.replace(/0+(?=\d\d)/g, '');
+    return sign + `0${m}:0${s}`.replace(/0+(?=\d\d)/g, '');
 }
 
 module.exports = format_ms;

package/src/format_ms.md

@@ -0,0 +1,12 @@
+Formats a millisecond duration as `MM:SS`, or `HH:MM:SS` when there is a
+nonzero hours part (via `factorize_ms`). Fields are zero-padded to two digits;
+the hours field grows as needed (`'999:00:00'`). Sub-second precision is
+truncated, not rounded. Falsy input formats as `0`; negative input is
+factorized by magnitude and prefixed with `'-'`.
+
+```js
+format_ms(5445)       // '00:05'
+format_ms(1500.7)     // '00:01'
+format_ms(3661000)    // '01:01:01'
+format_ms(-61000)     // '-01:01'
+```

package/src/format_ms2.js

@@ -10,11 +10,14 @@ function format_ms2(ms)
     }
 
     // 00:05.45
-    const [h, m, s, xx] = factorize_ms(ms);
+    // Round to centiseconds before factorizing so the carry propagates:
+    // rounding the factorized remainder would turn 5999 into "00:05.100"
+    const sign = ms < 0 ? '-' : '';
+    const [h, m, s, xx] = factorize_ms(Math.round(Math.abs(ms)/10)*10);
     if (h) {
-        return `0${h}:0${m}:0${s}.0${Math.round(xx/10)}`.replace(/0+(?=\d\d)/g, '');
+        return sign + `0${h}:0${m}:0${s}.0${xx/10}`.replace(/0+(?=\d\d)/g, '');
     }
-    return `0${m}:0${s}.0${Math.round(xx/10)}`.replace(/0+(?=\d\d)/g, '');
+    return sign + `0${m}:0${s}.0${xx/10}`.replace(/0+(?=\d\d)/g, '');
 }
 
 module.exports = format_ms2;

package/src/format_ms2.md

@@ -0,0 +1,12 @@
+Formats a millisecond duration as `MM:SS.cc` (centiseconds), or `HH:MM:SS.cc`
+when there is a nonzero hours part. The value is rounded to the nearest
+centisecond *before* factorizing, so the carry propagates through the larger
+units. Falsy input formats as `0`; negative input is factorized by magnitude
+and prefixed with `'-'`.
+
+```js
+format_ms2(5445)        // '00:05.45'
+format_ms2(5999)        // '00:06.00' (rounding carries into seconds)
+format_ms2(3599999)     // '01:00:00.00' (…and all the way up)
+format_ms2(-3661500)    // '-01:01:01.50'
+```

package/src/format_ms3.js

@@ -10,11 +10,12 @@ function format_ms3(ms, include_zero_hours = false)
     }
 
     // 00:05.445
+    const sign = ms < 0 ? '-' : '';
     const [h, m, s, xx] = factorize_ms(ms);
     if (h || include_zero_hours) {
-        return `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
+        return sign + `0${h}:0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '');
     }
-    return `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')
+    return sign + `0${m}:0${s}.00${xx}`.replace(/0+(?=\d\d+[:.]|\d\d\d)/g, '')
 }
 
 module.exports = format_ms3;

package/src/format_ms3.md

@@ -0,0 +1,12 @@
+Formats a millisecond duration as `MM:SS.mmm` (full milliseconds), or
+`HH:MM:SS.mmm` when there is a nonzero hours part. Sub-millisecond fractions
+are truncated, not rounded. Pass `include_zero_hours = true` to force the
+hours field even when it is zero. Falsy input formats as `0`; negative input
+is factorized by magnitude and prefixed with `'-'`.
+
+```js
+format_ms3(5445)          // '00:05.445'
+format_ms3(5445, true)    // '00:00:05.445'
+format_ms3(1500.7)        // '00:01.500'
+format_ms3(-3661500)      // '-01:01:01.500'
+```

package/src/format_percents.md

@@ -0,0 +1,10 @@
+Formats a fraction (`0` to `1`) as a percentage with two decimal places. The
+exact endpoints drop the decimals: `0` gives `'0%'` and `1` gives `'100%'`,
+while everything in between keeps them (`'50.00%'`).
+
+```js
+format_percents(0)         // '0%'
+format_percents(0.0101)    // '1.01%'
+format_percents(0.5)       // '50.00%'
+format_percents(1)         // '100%'
+```

package/src/format_progress_bytes.md

@@ -0,0 +1,13 @@
+Formats a `make_progress` snapshot (`{percents, total, done, rate, eta, duration}`)
+as a one-line byte-progress string, using 1024-based units (`format_bytes`).
+Unknown parts (zero/null rate, eta, total) render as `~`; the layout degrades
+as less is known: full form → `done of ~` (no total) → `~ duration=…`
+(nothing done) → `~`. When `done > total`, the percents/total part is
+dropped entirely.
+
+```js
+format_progress_bytes({percents: 0.2525, total: 15*1024*1024, done: 5*1024*1024, rate: 10*1024*1024, eta: 5, duration: 1})
+// '25.25% | 5.0MB of 15.0MB at 10.0MB/s ETA 00:00:05 duration=00:00:01'
+format_progress_bytes({percents: 0, total: 0, done: 0, rate: 0, eta: 0, duration: 0})
+// '~'
+```

package/src/format_progress_kilo.md

@@ -0,0 +1,10 @@
+Formats a `make_progress` snapshot (`{percents, total, done, rate, eta, duration}`)
+as a one-line progress string using metric 1000-based units (`format_kilo`) —
+for counting items, jobs, rows, etc. Identical layout and degradation rules
+to `format_progress_bytes`: unknown parts render as `~`, and when
+`done > total` the percents/total part is dropped.
+
+```js
+format_progress_kilo({percents: 0.2525, total: 15e6, done: 5e6, rate: 10e6, eta: 5, duration: 1})
+// '25.25% | 5.00M of 15.00M at 10.00M/s ETA 00:00:05 duration=00:00:01'
+```

package/src/format_seconds.md

@@ -0,0 +1,11 @@
+Formats a duration in seconds as `HH:MM:SS`. Hours are always present and grow
+beyond two digits as needed. Fractional seconds are truncated toward zero. The
+`'-'` prefix appears only for `seconds <= -1`, so values in `(-1, 0)` format as
+plain `'00:00:00'`.
+
+```js
+format_seconds(3661)       // '01:01:01'
+format_seconds(1000000)    // '277:46:40'
+format_seconds(-0.9)       // '00:00:00'
+format_seconds(-1)         // '-00:00:01'
+```

package/src/format_thousands.md

@@ -0,0 +1,9 @@
+Formats a number with commas as thousands separators. Works on the value's
+`toString()` output: only the integer part is grouped, fractional digits are
+left untouched, and negative numbers are handled.
+
+```js
+format_thousands(1234567)            // '1,234,567'
+format_thousands(-1000)              // '-1,000'
+format_thousands(123456789.01234)    // '123,456,789.01234'
+```

package/src/fs_append.md

@@ -0,0 +1,7 @@
+Appends data to a file, creating the file if it does not exist.
+Thin wrapper over `fs.promises.appendFile(file, data, options)`; `data` may be a string or a `Buffer`.
+See `fs_append_utf8` for text and `fs_append_json` for JSON lines.
+
+```js
+fs_append(file, data, options) → Promise<void>
+```

package/src/fs_append_json.md

@@ -0,0 +1,8 @@
+Appends a value to a file as one line of JSON (JSON Lines format).
+The value is serialized with `json_stringify_stable` (object keys sorted) and followed by a newline.
+
+```js
+await fs_append_json(file, {b: 1, a: [2]});
+await fs_append_json(file, 'x');
+// file content: '{"a":[2],"b":1}\n"x"\n'
+```

package/src/fs_append_utf8.md

@@ -0,0 +1,6 @@
+Appends text to a file, creating the file if it does not exist.
+Same wrapper over `fs.promises.appendFile` as `fs_append`; the name documents the intent (UTF-8 is the default encoding).
+
+```js
+fs_append_utf8(file, text, options) → Promise<void>
+```

package/src/fs_assert_file_exists.md

@@ -0,0 +1,3 @@
+Asserts that `file` is a regular file; resolves with nothing on success.
+Rejects with `ENOENT` if the path is missing, and with `Not a file: <file>` for anything else.
+The check is lstat-based (`fs_fi`), so even a symlink pointing at a regular file rejects.

package/src/fs_assert_file_readable.js

@@ -6,7 +6,7 @@ async function fs_assert_file_readable(file)
     if (!fi.isFile()) {
         throw new Error(`Not a file: ${file}`);
     }
-    if (fi.mode & 0o111) {
+    if ((fi.mode & 0o444) !== 0o444) {
         throw new Error(`File is not readable by all: ${file}`);
     }
 }

package/src/fs_assert_file_readable.md

@@ -0,0 +1,3 @@
+Asserts that `file` is a regular file readable by everyone: rejects unless the mode
+includes all three read bits (`0o444`).
+Like `fs_assert_file_exists`, the check is lstat-based, so symlinks fail it.

package/src/fs_assert_file_socket.md

@@ -0,0 +1,2 @@
+Asserts that `file` is a Unix domain socket.
+Rejects with `Not a socket: <file>` for any other entry type, and with `ENOENT` if the path is missing.

package/src/fs_copy.md

@@ -0,0 +1,7 @@
+Copies `src` to `dest`, overwriting `dest` if it exists.
+Thin wrapper over `fs.promises.copyFile(src, dest, mode)`; `mode` takes `fs.constants` copy flags.
+Use `fs_copy_excl` to fail instead of overwriting.
+
+```js
+fs_copy(src, dest, mode) → Promise<void>
+```

package/src/fs_copy_excl.md

@@ -0,0 +1,2 @@
+Copies `src` to `dest`, rejecting with `EEXIST` if `dest` already exists (`COPYFILE_EXCL`).
+Use `fs_copy` when overwriting is fine.

package/src/fs_exists.md

@@ -0,0 +1,6 @@
+Resolves with `true` if `path` is accessible and `false` otherwise; never rejects.
+Follows symlinks (via `fs.access`), so a broken symlink reports `false`.
+
+```js
+fs_exists(path) → Promise<boolean>
+```

package/src/fs_fclose.md

@@ -0,0 +1,5 @@
+Closes a file descriptor obtained from `fs_fopen`.
+
+```js
+fs_fclose(fp) → Promise<void>
+```

package/src/fs_fi.js

@@ -15,7 +15,19 @@ async function fs_fi(pathname)
         const target = await fs_readlink(fi.pathname);
         const target_pathname = fs_path_resolve(fs_path_dirname(pathname), target);
         fi.target = target;
-        fi.target_fi = await fs_lstat(target_pathname);
+        try {
+            fi.target_fi = await fs_lstat(target_pathname);
+        }
+        catch (error) {
+            if (!['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) {
+                throw error;
+            }
+            // A broken symlink is a legitimate directory entry: report it
+            // with target_fi = null instead of failing the whole listing
+            // (fs_find, fs_list, fs_ls, fs_lsr, fs_list_deep).
+            fi.target_fi = null;
+            return fi;
+        }
         fi.target_fi.pathname = target_pathname;
         fi.target_fi.basename = fs_path_basename(target_pathname);
         flags(fi.target_fi);

package/src/fs_fi.md

@@ -0,0 +1,11 @@
+Returns extended file info: an lstat `Stats` object augmented with `pathname`, `basename`,
+`flags` (e.g. `['is_file']`) and `flags_map` (e.g. `{is_file: true}`).
+For a symlink it also resolves the target: `target` is the raw link text and `target_fi`
+the target's own info object — or `null` for a broken symlink, so directory listings
+(`fs_find`, `fs_list`, ...) never fail on dangling links.
+
+```js
+await fs_fi('/tmp/d/link');    // link → 'data.txt'
+// { ..., flags: ['is_symbolic_link'], target: 'data.txt',
+//   target_fi: { pathname: '/tmp/d/data.txt', flags: ['is_file'], ... } }
+```

package/src/fs_file_md5.md

@@ -0,0 +1,8 @@
+Computes the MD5 of a file by streaming it (constant memory regardless of
+file size). The second argument is the digest encoding, `'hex'` by default;
+any `crypto` digest encoding (e.g. `'base64'`) works.
+
+```js
+await fs_file_md5('/tmp/data.txt')           // '5eb63bbbe01eeed093cb22bb8f5acdc3'
+await fs_file_md5('/tmp/data.txt', 'base64') // 'XrY7u+Ae7tCTyyK7j1rNww=='
+```

package/src/fs_find.md

@@ -0,0 +1,7 @@
+Recursively lists a directory tree as an array of `fs_fi` info objects with absolute
+pathnames — the root entry first, then its contents depth-first in `readdir` order.
+A non-directory pathname yields just its own entry.
+Broken symlinks are reported (`target_fi: null`) instead of failing the walk,
+and symlinks to directories are not descended into.
+See `fs_list` for a shallow listing and `fs_list_deep` for a recursive one
+that keeps pathnames relative to the input.

package/src/fs_fopen.md

@@ -0,0 +1,6 @@
+Opens a file and resolves with a numeric file descriptor for use with
+`fs_fread`, `fs_fwrite`, `fs_fstat`, `fs_fsize` and `fs_fclose`.
+
+```js
+fs_fopen(file, flags = 'r', mode = 0o666) → Promise<number>
+```

package/src/fs_fread.js

@@ -5,12 +5,12 @@ const fs = require('fs');
  */
 async function fs_fread(fp, buffer, offset = null, size = buffer.length)
 {
-    const {bytesRead} = await new Promise(function (resolve, reject) {
+    const bytes_read = await new Promise(function (resolve, reject) {
         fs.read(fp, buffer, 0, size, offset, function (error, out) {
             error ? reject(error) : resolve(out);
         });
     });
-    return (bytesRead === buffer.length) ? buffer : buffer.subarray(0, bytesRead);
+    return (bytes_read === buffer.length) ? buffer : buffer.subarray(0, bytes_read);
 }
 
 module.exports = fs_fread;

package/src/fs_fread.md

@@ -0,0 +1,11 @@
+Reads up to `size` bytes (default: the buffer length) from a file descriptor into the start of `buffer`.
+With `offset = null` (default) it reads from the current file position and advances it;
+an explicit `offset` reads at that position without moving it.
+Resolves with the filled part of the buffer: `buffer` itself when filled exactly,
+otherwise `buffer.subarray(0, bytes_read)` — an empty chunk past the end of file.
+
+```js
+const fp = await fs_fopen(file);                      // file content: 'hello world'
+await fs_fread(fp, Buffer.alloc(1024), 6, 5);         // <Buffer 'world'>
+await fs_fread(fp, Buffer.alloc(1024), 100);          // <Buffer > (length 0)
+```

package/src/fs_fsize.md

@@ -0,0 +1,2 @@
+Resolves with the size in bytes of an open file descriptor (`fs_fstat(fp).size`).
+For a pathname, see `fs_size` / `fs_size_enoent`.

package/src/fs_fstat.md

@@ -0,0 +1,2 @@
+Promisified `fs.fstat(fp, options)` — resolves with the `Stats` of an open file descriptor.
+For pathnames, see `fs_stat` (follows symlinks) and `fs_lstat` (does not).

package/src/fs_fwrite.js

@@ -5,12 +5,12 @@ const fs = require('fs');
  */
 async function fs_fwrite(fp, buffer, offset = null)
 {
-    const {bytesWritten} = await new Promise(function (resolve, reject) {
+    const bytes_written = await new Promise(function (resolve, reject) {
         fs.write(fp, buffer, 0, buffer.length, offset, function (error, out) {
             error ? reject(error) : resolve(out);
         });
     });
-    return bytesWritten;
+    return bytes_written;
 }
 
 module.exports = fs_fwrite;

package/src/fs_fwrite.md

@@ -0,0 +1,9 @@
+Writes the whole `buffer` to a file descriptor and resolves with `bytes_written`.
+With `offset = null` (default) it writes at the current file position;
+pass an explicit `offset` to write at that position instead.
+
+```js
+const fp = await fs_fopen(file, 'w');
+await fs_fwrite(fp, Buffer.from('hello world'));  // 11
+await fs_fwrite(fp, Buffer.from('WORLD'), 6);     // 5 — file is now 'hello WORLD'
+```

package/src/fs_list.md

@@ -0,0 +1,5 @@
+Shallow directory listing: resolves with an array of `fs_fi` info objects for the direct
+entries of `pathname` (the directory itself is not included).
+A non-directory pathname yields `[fi]` of itself.
+Entry pathnames are `pathname` joined with each name, so they stay relative if the input is relative.
+See `fs_list_deep` and `fs_find` for recursive variants.

package/src/fs_list_deep.md

@@ -0,0 +1,5 @@
+Recursively lists `path` as an array of `fs_fi` info objects, including the root entry
+itself and every directory below it.
+Traversal is stack-based: the root comes first, but the rest is in no particular order.
+Pathnames are joined from the input, so they stay relative if the input is relative.
+See `fs_list` (shallow) and `fs_find` (recursive, absolute pathnames, depth-first order).

package/src/fs_ls.md

@@ -0,0 +1,2 @@
+**Deprecated** in favor of `fs_list` (identical behavior):
+a shallow directory listing as an array of `fs_fi` info objects.

package/src/fs_lsr.md

@@ -0,0 +1,4 @@
+**Deprecated** in favor of `fs_walk`.
+Recursive listing like `fs_find`, but keeps pathnames relative to the input and adds
+`content_size` to every `fs_fi` entry: a file's own `size`, the recursive total of file
+sizes for a directory, and `0` for anything else.

package/src/fs_lstat.md

@@ -0,0 +1,3 @@
+Thin wrapper over `fs.promises.lstat(path, options)`: stats the link itself instead of
+following symlinks.
+See `fs_stat` (follows symlinks) and `fs_fi` (lstat plus pathname/flags/symlink-target info).

package/src/fs_mkdir.md

@@ -0,0 +1,3 @@
+Thin wrapper over `fs.promises.mkdir(path, options)`.
+Rejects with `EEXIST` if the path exists, and does not create missing parents unless
+`options.recursive` is set — see `fs_mkdirp` for that.

package/src/fs_mkdirp.js

@@ -1,36 +1,9 @@
-const fs_exists = require('./fs_exists');
-const fs_mkdir = require('./fs_mkdir');
-const fs_path_dirname = require('./fs_path_dirname');
+const fs = require('fs');
 
 async function fs_mkdirp(pathname)
 {
-    const parents = [];
-
-    for (let p = pathname; p && p !== '/'; p = fs_path_dirname(p)) {
-        if (await fs_exists(p)) {
-            break;
-        }
-        parents.push(p);
-    }
-
-    while (parents.length) {
-        try {
-            await fs_mkdir(parents.pop());
-        }
-        catch (error) {
-            // Error: EEXIST: file already exists, mkdir [...]
-            if (error.code === 'EEXIST') {
-                // Exiting here is not correct. When two processes are running in parallel,
-                // one tries to create `a/b/c` and another `a`. When second process creates
-                // `a`, the first process will get `EEXIST` and stops (break) creating any
-                // nested directories, which is not correct.
-                // break;
-                continue;
-            }
-            throw error;
-        }
-    }
-
+    // Unlike the native call, resolves with `pathname` (handy for chaining).
+    await fs.promises.mkdir(pathname, {recursive: true});
     return pathname;
 }
 

package/src/fs_mkdirp.md

@@ -0,0 +1,7 @@
+Creates a directory and any missing parents (`mkdir -p`). An already existing directory
+is fine (safe to call in parallel), but a path that exists as a regular file rejects with `EEXIST`.
+Unlike the native call, resolves with `pathname` itself — handy for chaining.
+
+```js
+await fs_mkdirp('/tmp/a/b/c');    // '/tmp/a/b/c'
+```

package/src/fs_path_basename.md

@@ -0,0 +1,2 @@
+Thin wrapper over node's `path.basename(p)`, kept for the consistent `fs_*`
+naming.  Returns the last portion of the path.