@vbarbarosh/node-helpers 3.75.0 → 3.76.0

package/src/http_put_utf8.md

@@ -0,0 +1,9 @@
+Sends a `PUT` request via axios with a string body sent as-is and resolves
+with `response.data`. Extra axios options — e.g. a `Content-Type` header —
+pass through.
+
+```js
+await http_put_utf8(upload_url, csv, {headers: {'Content-Type': 'text/csv'}});
+```
+
+Sibling of `http_put_buffer` (binary body) and `http_put_json` (JSON body).

package/src/http_range_parse.js

@@ -12,15 +12,18 @@ function http_range_parse(range, total)
     let first = +m[1];
     let last = +m[2];
 
-    if (!m[1]) { // -LAST
-        first = total - last;
+    if (!m[1]) { // -LAST: a suffix longer than the resource means the whole resource (RFC 7233)
+        first = Math.max(0, total - last);
         last = total - 1;
     }
     else if (!m[2]) { // FIRST-
         last = total - 1;
     }
+    else if (last >= total) { // FIRST-LAST reaching past the end reads to the end (RFC 7233)
+        last = total - 1;
+    }
 
-    if (first < 0 || first > last || first >= total || last < 0 || last < first || last >= total) {
+    if (first < 0 || first > last || first >= total) {
         throw new Error(`Invalid range: first=${first}, last=${last}, total=${total}, expr="${range}"`);
     }
 

package/src/http_range_parse.md

@@ -0,0 +1,18 @@
+Parses an HTTP `Range` request header against a known resource size. Supports
+`bytes=FIRST-LAST`, `bytes=FIRST-`, and `bytes=-LAST` (single range, `bytes`
+unit only; spaces around `=` are allowed). Returns `{first, last}` with both
+bounds inclusive.
+
+Clamping follows RFC 7233:
+
+- a suffix longer than the resource (`bytes=-5000` of 100) → the whole resource
+- `last` past the end (`bytes=0-999999` of 100) → reads to the end
+
+Throws for unparsable expressions and for unsatisfiable ranges: `first` past
+the end (`bytes=100-` of 100), `first > last`, or an empty suffix (`bytes=-0`).
+
+```js
+http_range_parse('bytes=500-', 1000)   // {first: 500, last: 999}
+http_range_parse('bytes=-100', 1000)   // {first: 900, last: 999}
+http_range_parse('bytes=0-999999', 100) // {first: 0, last: 99}
+```

package/src/http_stream_range.js

@@ -27,6 +27,7 @@ async function http_stream_range(req, res, file)
     const mime = mime_types.lookup(file);
 
     if (req.method === 'HEAD') {
+        res.header('Accept-Ranges', 'bytes');
         res.header('Content-Type', mime);
         res.header('Content-Length', total);
         res.header('Content-Disposition', `inline; filename=${escape_content_disposition(fs_path_basename(file))};`);
@@ -40,6 +41,34 @@ async function http_stream_range(req, res, file)
         return;
     }
 
+    res.header('Accept-Ranges', 'bytes');
+
+    let first = 0;
+    let last = total - 1;
+    let status = 200;
+
+    // bytes=0-
+    // bytes=-100
+    if (req.headers.range) {
+        try {
+            const range = http_range_parse(req.headers.range, total);
+            first = range.first;
+            last = range.last;
+            status = 206;
+        }
+        catch (error) {
+            // A Range expression we cannot parse is ignored (RFC 7233 says to
+            // serve the whole resource), but a syntactically valid range which
+            // cannot be satisfied gets 416
+            if (error.message.startsWith('Invalid range')) {
+                res.status(416);
+                res.header('Content-Range', `bytes */${total}`);
+                res.end();
+                return;
+            }
+        }
+    }
+
     const fp = await fs_fopen(file);
     const buf = Buffer.alloc(2*1024*1024);
 
@@ -47,33 +76,17 @@ async function http_stream_range(req, res, file)
         let req_close = false;
         req.once('close', () => req_close = true);
 
-        let first, last;
-
-        // bytes=0-
-        // bytes=-100
-        if (req.headers.range) {
-            const range = http_range_parse(req.headers.range, total);
-            first = range.first;
-            last = range.last;
-            // req.log(`[http_stream_range_range] ${JSON.stringify({range: req.headers.range, first, last, total, orig: req.headers.range})}`);
-            // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range
-            res.status(206);
-            res.header('Content-Type', mime);
+        // https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range
+        res.status(status);
+        res.header('Content-Type', mime);
+        res.header('Content-Length', last - first + 1);
+        if (status === 206) {
             res.header('Content-Range', `bytes ${first}-${last}/${total}`);
-            res.header('Content-Length', last - first + 1);
-        }
-        else {
-            first = 0;
-            last = total - 1;
-            res.header('Content-Type', mime);
-            res.header('Content-Length', last - first + 1);
         }
 
-        let total_read = 0;
         for (let offset = first; offset <= last && !req_close; ) {
             const chunk = await fs_fread(fp, buf, offset, Math.min(buf.length, last - offset + 1));
             offset += chunk.length;
-            total_read += chunk.length;
             if (res.write(chunk)) {
                 // req.log(`[http_stream_range_write] ${chunk.length}`);
                 continue;
@@ -96,7 +109,7 @@ async function http_stream_range(req, res, file)
             });
         }
 
-        // req.log(`[http_stream_range_end_ok] ${JSON.stringify({req_close, total_read})}`);
+        // req.log(`[http_stream_range_end_ok] ${JSON.stringify({req_close})}`);
         res.end();
     }
     finally {

package/src/http_stream_range.md

@@ -0,0 +1,29 @@
+Express/Node request handler that streams a file from disk, honoring a single
+HTTP `Range` header (parsed with `http_range_parse`; see its doc for supported
+forms and clamping). `Content-Type` comes from `mime-types` lookup on the file
+name.
+
+## Signature
+
+```
+http_stream_range(req, res, file) → Promise
+```
+
+- `HEAD` → 200 with `Content-Type`, `Content-Length`, and an
+  `inline; filename=...` `Content-Disposition` (escaped via
+  `escape_content_disposition`); no body.
+- `GET` with `Range` → 206 with `Content-Range: bytes first-last/total` and a
+  matching `Content-Length`.
+- `GET` without `Range` → 200 with the whole file.
+- A `Range` expression it cannot parse is ignored → 200 with the whole file
+  (RFC 7233); an unsatisfiable range → 416 with `Content-Range: bytes */total`.
+- Any other method → 405.
+
+`GET` and `HEAD` responses advertise `Accept-Ranges: bytes`.
+
+Reads in 2 MiB chunks with an `fs_fread` loop, respecting backpressure
+(`res.write` + `drain`) and stopping early when the client disconnects.
+
+```js
+app.get('/file', (req, res) => http_stream_range(req, res, '/data/movie.mp4'));
+```

package/src/identity.md

@@ -0,0 +1,2 @@
+Returns its first argument unchanged (objects by reference). Useful as a
+default projection or a no-op transformer.

package/src/ignore.md

@@ -0,0 +1,2 @@
+Does nothing and returns `undefined`, whatever the arguments. Useful as a
+no-op callback or for explicitly discarding a promise result.

package/src/json_stringify_safe.md

@@ -0,0 +1,10 @@
+Re-export of the [json-stringify-safe](https://www.npmjs.com/package/json-stringify-safe)
+package: `JSON.stringify` that never throws on circular references — cycles
+are replaced with `'[Circular ~]'`-style markers. Same signature as
+`JSON.stringify(obj, replacer, spaces)` plus an optional 4th `cycleReplacer`.
+
+```js
+const a = {name: 'x'};
+a.self = a;
+json_stringify_safe(a)      // '{"name":"x","self":"[Circular ~]"}'
+```

package/src/json_stringify_stable.md

@@ -0,0 +1,9 @@
+Re-export of the [json-stable-stringify](https://www.npmjs.com/package/json-stable-stringify)
+package: deterministic `JSON.stringify` — object keys are sorted at every
+level, so equal objects always produce byte-identical output. Useful for
+hashing, caching keys, and diff-friendly snapshots.
+
+```js
+json_stringify_stable({b: 2, a: 1, c: {z: 1, y: 2}})
+// '{"a":1,"b":2,"c":{"y":2,"z":1}}'
+```

package/src/logger.js

@@ -5,15 +5,14 @@ const re = /^((?:\[\s*[^\]]*\])*)\s*(.*)$/m;
 
 /**
  * log = logger();
- * log.add('hey')
- * log.add('[tag] heyhey')
+ * log('hey');
+ * log('[tag] heyhey');
  */
 function logger(options = {})
 {
     function out(message) {
         const v = typeof message === 'string' ? JSON.stringify(message.trim()).slice(1, -1) : JSON.stringify(message);
         const [, a, m] = v.match(re);
-        const time = new Date().toJSON();
         console.log(`${a} ${m}`.trim());
     };
     out.spawn = function () {

package/src/logger.md

@@ -0,0 +1,15 @@
+Creates a minimal console logger. The returned function prints one line per
+call via `console.log`: string messages are trimmed and JSON-escaped (without
+the surrounding quotes), non-strings are printed as JSON. Leading `[tag]`
+prefixes are split off and the whitespace between the tags and the message is
+normalized to a single space.
+
+```js
+const log = logger();
+log('hey');             // hey
+log('[tag]   heyhey');  // [tag] heyhey
+log({a: 1});            // {"a":1}
+```
+
+`log.spawn()` is a stub that throws `NotImplemented` — the `redis_poll_*`
+helpers expect a logger whose `spawn()` returns a child logger.

package/src/make_progress.js

@@ -22,7 +22,7 @@ function make_progress(total)
         percents: null,
         add: function (delta = 0) {
             const now_minus_10sec = Date.now() - 10000;
-            history.splice(0, history.findLastIndex(v => v.time < now_minus_10sec));
+            history.splice(0, history.findLastIndex(v => v.time < now_minus_10sec) + 1);
             history.push({time: Date.now(), delta});
             out.done += delta;
             out.refresh();
@@ -32,16 +32,19 @@ function make_progress(total)
         },
         refresh: function () {
             out.duration = (Date.now() - time0)/1000;
-            out.percents = !out.total ? null : out.done/out.total;
-            out.eta = !out.total ? null : (out.total - out.done)/out.rate;
+            // `rate` and `eta` are null while unknown (same as before the
+            // first add): a zero time window would give rate = Infinity,
+            // and a zero rate would give eta = Infinity.
             if (history.length) {
                 const delta = history.reduce((a,v) => a + v.delta, 0);
                 const time_sec = (Date.now() - history[0].time)/1000;
-                out.rate = delta/time_sec;
+                out.rate = time_sec ? delta/time_sec : null;
             }
             else {
-                out.rate = out.done/out.duration;
+                out.rate = out.duration ? out.done/out.duration : null;
             }
+            out.percents = !out.total ? null : out.done/out.total;
+            out.eta = (!out.total || !out.rate) ? null : (out.total - out.done)/out.rate;
         },
     };
     return out;

package/src/make_progress.md

@@ -0,0 +1,20 @@
+Creates a progress tracker for any countable work (bytes copied, jobs done,
+rows created). Pass the snapshot to `format_progress_bytes` /
+`format_progress_kilo` for display.
+
+**Fields:** `done`, `total`, `duration` (seconds since creation), `rate`
+(units/second over a sliding 10-second history window), `eta` (seconds),
+`percents` (a fraction, `done/total`). `rate` and `eta` are `null` while
+unknown — before the first `add`, or when they would be `Infinity` (zero
+time window, zero rate); `percents` is `null` when `total` is falsy.
+
+**Methods:**
+- `add(delta)` — add `delta` to `done` and recompute
+- `update(done)` — set the absolute `done` value
+- `refresh()` — recompute `duration`/`rate`/`eta`/`percents` without adding
+
+```js
+const p = make_progress(100);
+p.add(10);          // p.done → 10, p.percents → 0.1
+p.rate; p.eta;      // numbers once enough history exists, null while unknown
+```

package/src/math_gcd.js

@@ -4,7 +4,8 @@ function math_gcd(a, b)
     if (b) {
         return math_gcd(b, a % b);
     }
-    return a;
+    // GCD is canonically non-negative: without abs, gcd(4,-6) would be -2
+    return Math.abs(a);
 }
 
 module.exports = math_gcd;

package/src/mongo_stream_upsert.js

@@ -15,8 +15,9 @@ function mongo_stream_upsert({collection, concurrency = 1})
             next();
         },
         destroy: async function (error, next) {
+            // Wait for in-flight bulkWrite operations before tearing down.
             await wait_while(() => this.running > 0);
-            next();
+            next(error);
         },
         write: async function (items, enc, next) {
             if (errors.length) {
@@ -39,7 +40,10 @@ function mongo_stream_upsert({collection, concurrency = 1})
                     };
                 });
                 this.running++;
-                Promise.resolve(collection.bulkWrite(operations)).catch(e => errors.push(e)).finally(() => this.running--);
+                // Promise.try turns a synchronous throw from bulkWrite into a
+                // rejection, so `running` is always decremented; otherwise
+                // destroy/final would wait for it forever.
+                Promise.try(() => collection.bulkWrite(operations)).catch(e => errors.push(e)).finally(() => this.running--);
                 next();
             }
             catch (error) {
@@ -47,11 +51,14 @@ function mongo_stream_upsert({collection, concurrency = 1})
             }
         },
         final: async function (next) {
+            // Wait for in-flight bulkWrite operations before checking `errors`,
+            // otherwise an error from the last batch(es) would be silently
+            // dropped and the stream would finish successfully.
+            await wait_while(() => this.running > 0);
             if (errors.length) {
                 next(errors[0]);
                 return;
             }
-            await wait_while(() => this.running > 0);
             next();
         },
     });

package/src/mongo_stream_upsert.md

@@ -0,0 +1,17 @@
+Object-mode writable that inserts or replaces documents in a mongo collection.
+Every chunk written to it must be an array of documents; each document becomes
+a `replaceOne` upsert keyed by its `_id`, and the batch goes to
+`collection.bulkWrite`.
+
+- Up to `concurrency` (default `1`) `bulkWrite` calls run in flight; further
+  writes wait until a slot frees up.
+- A `bulkWrite` error is reported on the next write or when the stream
+  finishes. `final` and `destroy` wait for all in-flight batches first, so an
+  error from the last batch is never silently dropped.
+- A non-array chunk errors the stream (`An array of objects is expected.`).
+
+## Signature
+
+```
+mongo_stream_upsert({collection, concurrency = 1}) → stream.Writable
+```

package/src/mongo_stream_write.js

@@ -15,8 +15,9 @@ function mongo_stream_write({collection, concurrency = 1})
             next();
         },
         destroy: async function (error, next) {
+            // Wait for in-flight bulkWrite operations before tearing down.
             await wait_while(() => this.running > 0);
-            next();
+            next(error);
         },
         write: async function (operations, enc, next) {
             if (errors.length) {
@@ -30,7 +31,10 @@ function mongo_stream_write({collection, concurrency = 1})
                 }
                 await wait_while(() => this.running >= concurrency);
                 this.running++;
-                Promise.resolve(collection.bulkWrite(operations)).catch(e => errors.push(e)).finally(() => this.running--);
+                // Promise.try turns a synchronous throw from bulkWrite into a
+                // rejection, so `running` is always decremented; otherwise
+                // destroy/final would wait for it forever.
+                Promise.try(() => collection.bulkWrite(operations)).catch(e => errors.push(e)).finally(() => this.running--);
                 next();
             }
             catch (error) {
@@ -38,11 +42,14 @@ function mongo_stream_write({collection, concurrency = 1})
             }
         },
         final: async function (next) {
+            // Wait for in-flight bulkWrite operations before checking `errors`,
+            // otherwise an error from the last batch(es) would be silently
+            // dropped and the stream would finish successfully.
+            await wait_while(() => this.running > 0);
             if (errors.length) {
                 next(errors[0]);
                 return;
             }
-            await wait_while(() => this.running > 0);
             next();
         },
     });

package/src/mongo_stream_write.md

@@ -0,0 +1,16 @@
+Object-mode writable that feeds batches of `bulkWrite` operations to a mongo
+collection. Every chunk written to it must be an array of operations; it is
+passed to `collection.bulkWrite(operations)` as is.
+
+- Up to `concurrency` (default `1`) `bulkWrite` calls run in flight; further
+  writes wait until a slot frees up.
+- A `bulkWrite` error is reported on the next write or when the stream
+  finishes. `final` and `destroy` wait for all in-flight batches first, so an
+  error from the last batch is never silently dropped.
+- A non-array chunk errors the stream (`An array of objects is expected.`).
+
+## Signature
+
+```
+mongo_stream_write({collection, concurrency = 1}) → stream.Writable
+```

package/src/msval.md

@@ -0,0 +1,10 @@
+Converts hours, minutes, seconds, and milliseconds to a single millisecond
+value: `msval(h, m, s, ms)` → `h*3600000 + m*60000 + s*1000 + ms`. All four
+arguments are required. Components are not normalized — `msval(0, 90, 0, 0)`
+is fine — and negative components subtract.
+
+```js
+msval(1, 30, 15, 500)   // 5415500
+msval(0, 90, 0, 0)      // 5400000
+msval(1, 0, 0, -1)      // 3599999
+```

package/src/now_fs.md

@@ -0,0 +1,7 @@
+Returns the current local time as a filesystem-safe timestamp:
+`YYYYMMDD_HHMMSS` (via `format_date_fs`). Resolution is 1 second — handy for
+naming files, dumps, and backups.
+
+```js
+now_fs()    // '20260716_194122'
+```

package/src/now_human.md

@@ -0,0 +1,6 @@
+Returns the current local time in a human-readable form:
+`YYYY/MM/DD HH:MM:SS` (via `format_date_human`).
+
+```js
+now_human()     // '2026/07/16 19:41:22'
+```

package/src/object_defaults.md

@@ -0,0 +1,11 @@
+Fills missing keys of `obj` from `defaults`, mutating and returning `obj`.
+Only keys whose current value is `undefined` (missing or explicitly set) are
+filled; falsy values like `0`, `''`, `false`, and `null` are kept. The
+`defaults` object is never modified.
+
+```js
+object_defaults({a: 1, b: undefined}, {a: 10, b: 20, c: 30})
+// {a: 1, b: 20, c: 30}
+object_defaults({a: 0, b: null}, {a: 5, b: 5})
+// {a: 0, b: null}
+```

package/src/object_schema.js

@@ -8,12 +8,13 @@ function object_schema(obj)
     switch (type) {
     case const_type.array:
         return obj.map(object_schema).map(v => json_stringify_stable(v)).sort().filter((v,i,a) => a[i-1] !== v).map(v => JSON.parse(v));
-    case const_type.object:
+    case const_type.object: {
         const out = {};
         Object.keys(obj).forEach(function (key) {
             out[key] = object_schema(obj[key]);
         });
         return out;
+    }
     default:
         return type;
     }

package/src/object_schema.md

@@ -0,0 +1,12 @@
+Returns the shape of a value with every leaf replaced by its `gettype` name.
+Objects keep their keys; an array becomes the deduplicated, sorted list of
+its distinct member schemas (compared via `json_stringify_stable`), so
+`[1, 2, 'x']` collapses to `['number', 'string']`. Useful for eyeballing the
+structure of unknown JSON.
+
+```js
+object_schema({name: 'Bob', tags: ['a', 1], meta: {ok: true}})
+// {name: 'string', tags: ['number', 'string'], meta: {ok: 'boolean'}}
+object_schema([{a: 1}, {a: 2}, {a: 'x'}])
+// [{a: 'number'}, {a: 'string'}]
+```

package/src/object_walk_preorder.md

@@ -0,0 +1,16 @@
+Recursively visits every nested value of an object/array in preorder
+(parents before children), calling `fn(value, path)`. The root itself is not
+visited (`path` would be empty). `path` is an array of keys from the root;
+array elements contribute `'*'` instead of their index. `null` values are
+visited but not descended into. Returns nothing.
+
+```js
+object_walk_preorder({aaa: {foo: 1}, bbb: [10, 20]}, function (value, path) {
+    console.log(path.join('/'), value);
+});
+// aaa {foo: 1}
+// aaa/foo 1
+// bbb [10, 20]
+// bbb/* 10
+// bbb/* 20
+```

package/src/parallel.js

@@ -28,11 +28,22 @@ async function parallel({concurrency, spawn, progress})
                 if (failed) {
                     break;
                 }
-                const w = spawn();
+                let w;
+                try {
+                    w = spawn();
+                }
+                catch (error) {
+                    // A synchronous throw from spawn must go through fail():
+                    // when schedule() runs inside a resolved() handler it
+                    // would otherwise become an unhandled rejection and this
+                    // promise would never settle (and the timer would leak).
+                    fail(error);
+                    return;
+                }
                 if (!w) {
                     break;
                 }
-                const item = Promise.resolve(w).then(resolved, rejected);
+                const item = Promise.resolve(w).then(resolved, fail);
                 running.push(item);
                 function resolved() {
                     if (failed) {
@@ -45,20 +56,22 @@ async function parallel({concurrency, spawn, progress})
                     running.splice(i, 1);
                     schedule();
                 }
-                function rejected(error) {
-                    if (failed) {
-                        return;
-                    }
-                    running.splice(0, running.length);
-                    reject(error);
-                }
             }
-            if (running.length === 0) {
+            if (running.length === 0 && !failed) {
                 tick();
                 clearInterval(timer);
                 resolve();
             }
         }
+        function fail(error) {
+            if (failed) {
+                return;
+            }
+            failed = true;
+            running.splice(0, running.length);
+            clearInterval(timer);
+            reject(error);
+        }
         function tick() {
             if (progress) {
                 progress(running);

package/src/parse_bytes.js

@@ -4,11 +4,13 @@ function parse_bytes(bytes)
     if (typeof bytes !== 'string') {
         return Number.NaN;
     }
-    const m = bytes.toUpperCase().match(/(\d+([.]?\d+)?)(([KMGTP]I?)?B)/);
+    // Anchored: trailing garbage ('12KB34') is NaN rather than 12KB. A bare
+    // number means bytes; whitespace around and between number and unit is ok
+    const m = bytes.toUpperCase().match(/^\s*(\d+(?:[.]\d+)?)\s*((?:[KMGTP]I?)?B)?\s*$/);
     if (!m) {
         return Number.NaN;
     }
-    return Math.floor(m[1]*Math.pow(1024, sizes.indexOf(m[3].replace('I', ''))));
+    return Math.floor(m[1]*Math.pow(1024, sizes.indexOf((m[2] || 'B').replace('I', ''))));
 }
 
 module.exports = parse_bytes;

package/src/parse_bytes.md

@@ -0,0 +1,15 @@
+Parses a human-readable size string into a number of bytes. Units are
+1024-based: `B`, `KB`, `MB`, `GB`, `TB`, `PB`; the `KiB`/`MiB` spellings are
+accepted and mean the same thing. Matching is case-insensitive and anchored:
+whitespace around and between number and unit is fine, but any other
+trailing/leading garbage gives `NaN`. A bare number means bytes. The result
+is `Math.floor`ed. Non-strings (including numbers) return `NaN`.
+
+```js
+parse_bytes('10.5MB')   // 11010048
+parse_bytes('1KIB')     // 1024
+parse_bytes('5 mb')     // 5242880
+parse_bytes('123')      // 123 (bare number means bytes)
+parse_bytes('12KB34')   // NaN (trailing garbage, not 12KB)
+parse_bytes(123)        // NaN (not a string)
+```

package/src/parse_hms.js

@@ -11,7 +11,7 @@ function parse_hms(expr)
 
     const parts = expr.split(':');
 
-    let h = 0, m = 0, s = 0;
+    let h = 0, m = 0, s;
 
     if (parts.length === 1) {
         // "SS(.fff)"

package/src/parse_http_content_range.js

@@ -1,14 +1,18 @@
 function parse_http_content_range(value)
 {
     // Content-Range: bytes 262144000-272629759/5037662208
-    const m = value.match(/^(\w+)\s+(\d+)-(\d+)[/](\d+)$/);
-    if (!m) {
+    // Content-Range: bytes */5037662208 (unsatisfied range → first/last are null)
+    // Content-Range: bytes 0-499/* (unknown total → total is null)
+    const m = value.match(/^(\w+)\s+(?:(\d+)-(\d+)|[*])[/](?:(\d+)|[*])$/);
+    // "*/*" is not in the RFC 7233 grammar: an unsatisfied range must state
+    // the complete length
+    if (!m || (m[2] === undefined && m[4] === undefined)) {
         throw new Error(`Invalid Content-Range: [${value}]`);
     }
     const type = m[1];
-    const first = +m[2];
-    const last = +m[3];
-    const total = +m[4];
+    const first = m[2] === undefined ? null : +m[2];
+    const last = m[3] === undefined ? null : +m[3];
+    const total = m[4] === undefined ? null : +m[4];
     return {type, first, last, total};
 }
 

package/src/parse_http_content_range.md

@@ -0,0 +1,16 @@
+Parses an HTTP `Content-Range` response header into
+`{type, first, last, total}` (numbers, bounds inclusive).
+
+- `bytes 0-499/1000` — a regular range.
+- `bytes */5000` — unsatisfied range: `first` and `last` are `null`.
+- `bytes 0-499/*` — unknown total: `total` is `null`.
+- `bytes */*` throws — it is not in the RFC 7233 grammar: an unsatisfied
+  range must state the complete length.
+
+Throws for anything else it cannot parse.
+
+```js
+parse_http_content_range('bytes 0-499/1000') // {type: 'bytes', first: 0, last: 499, total: 1000}
+parse_http_content_range('bytes */5000')     // {type: 'bytes', first: null, last: null, total: 5000}
+parse_http_content_range('bytes 0-499/*')    // {type: 'bytes', first: 0, last: 499, total: null}
+```