@vbarbarosh/node-helpers 3.75.0 → 3.76.1

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}
+```

package/src/perf_end_human.md

@@ -0,0 +1,10 @@
+Returns the time elapsed since `perf_start()` as a human-readable string of
+seconds: `perf_end_human(time0, digits = 4)`. Uses `process.hrtime(time0)`
+under the hood, formatted via `format_hrtime`.
+
+```js
+const time0 = perf_start();
+// ... work ...
+perf_end_human(time0)       // '0.0008s'
+perf_end_human(time0, 2)    // '0.00s'
+```

package/src/perf_end_ms.md

@@ -0,0 +1,8 @@
+Returns the time elapsed since `perf_start()` in milliseconds, rounded to an
+integer. Uses `process.hrtime(time0)` under the hood.
+
+```js
+const time0 = perf_start();
+// ... work ...
+perf_end_ms(time0)      // 1
+```

package/src/perf_measure.md

@@ -0,0 +1,10 @@
+Runs `fn` (sync or async — the result is awaited) and measures how long it
+took with `process.hrtime`. `perf_measure(fn, digits = 4)` returns a promise
+of `{value, time_ms, time_human}` where `value` is the resolved result of
+`fn`, `time_ms` is rounded integer milliseconds, and `time_human` is a
+seconds string with `digits` decimal places.
+
+```js
+await perf_measure(() => 42)
+// {value: 42, time_ms: 1, time_human: '0.0008s'}
+```

package/src/perf_measure_human.md

@@ -0,0 +1,8 @@
+Runs `fn` (sync or async — the result is awaited) and returns a promise of
+just the elapsed time as a human-readable seconds string:
+`perf_measure_human(fn, digits = 4)`. The return value of `fn` is discarded;
+use `perf_measure` when you need it too.
+
+```js
+await perf_measure_human(() => heavy_work())    // '0.0006s'
+```

package/src/perf_start.md

@@ -0,0 +1,9 @@
+Starts a high-resolution timer: returns `process.hrtime()` — a
+`[seconds, nanoseconds]` tuple to be passed later to `perf_end_ms` or
+`perf_end_human`.
+
+```js
+const time0 = perf_start();
+// ... work ...
+perf_end_ms(time0)      // elapsed integer milliseconds
+```

package/src/pgid_exists.md

@@ -0,0 +1,6 @@
+Checks whether a process group is alive by sending signal `0` to the group via
+`process.kill(-pgid, 0)`. Returns `true` when the signal can be delivered to
+at least one member, `false` on any error (no such group, or no permission).
+A group id equals the pid of the group leader.
+
+See `pid_exists` for the single-process variant.

package/src/pgid_kill_grace.js

@@ -12,7 +12,7 @@ async function pgid_kill_grace(pgid, {grace_timeout_ms = 5000, log = ignore} = {
         process.kill(-pgid, 'SIGTERM');
     }
     catch (error) {
-        throw new Error(`Failed to send SIGTERM to process group ${pgid}: ${error.message}`);
+        throw new Error(`Failed to send SIGTERM to process group ${pgid}: ${error.message}`, {cause: error});
     }
 
     const end = Date.now() + grace_timeout_ms;

package/src/pgid_kill_grace.md

@@ -0,0 +1,15 @@
+Terminates a whole process group gracefully: sends `SIGTERM` to the group
+(`kill(-pgid, ...)`), polls (every ≤100ms) until the group dies or the grace
+period expires, then sends `SIGKILL` and waits up to 200ms more for the kernel
+to deliver it. A group id equals the pid of the group leader.
+
+- Options: `grace_timeout_ms` (default `5000`) and `log` (progress callback,
+  default no-op).
+- Throws `Failed to send SIGTERM to process group <pgid>: ...` when the
+  initial signal cannot be sent.
+- A group that dies on its own during the grace period skips the `SIGKILL`;
+  `ESRCH` on the `SIGKILL` itself is treated as already dead.
+- Throws `Process group <pgid> survived SIGKILL` if it is still alive 200ms
+  after the kill.
+
+See `pid_kill_grace` for the single-process variant.

package/src/pid_exists.md

@@ -0,0 +1,5 @@
+Checks whether a process is alive by sending signal `0` via
+`process.kill(pid, 0)`. Returns `true` when the signal can be delivered,
+`false` on any error (no such process, or no permission to signal it).
+
+See `pgid_exists` for the process-group variant.

package/src/pid_kill_grace.js

@@ -11,7 +11,7 @@ async function pid_kill_grace(pid, {grace_timeout_ms = 5000, log = ignore} = {})
         process.kill(pid, 'SIGTERM');
     }
     catch (error) {
-        throw new Error(`Failed to send SIGTERM to process ${pid}: ${error.message}`);
+        throw new Error(`Failed to send SIGTERM to process ${pid}: ${error.message}`, {cause: error});
     }
 
     const end = Date.now() + grace_timeout_ms;

package/src/pid_kill_grace.md

@@ -0,0 +1,14 @@
+Terminates a single process gracefully: sends `SIGTERM`, polls (every ≤100ms)
+until the process dies or the grace period expires, then sends `SIGKILL` and
+waits up to 200ms more for the kernel to deliver it.
+
+- Options: `grace_timeout_ms` (default `5000`) and `log` (progress callback,
+  default no-op).
+- Throws `Failed to send SIGTERM to process <pid>: ...` when the initial
+  signal cannot be sent (e.g. the process does not exist).
+- A process that dies on its own during the grace period skips the `SIGKILL`
+  entirely; `ESRCH` on the `SIGKILL` itself is treated as already dead.
+- Throws `Process <pid> survived SIGKILL` if it is still alive 200ms after
+  the kill.
+
+See `pgid_kill_grace` for the process-group variant.

package/src/plural.md

@@ -0,0 +1,13 @@
+Slavic-style pluralizer: `plural(n, singular, plural, zero)`. The `singular`
+form is used when `n` ends in 1 but not in 11 (1, 21, 101, ...); everything
+else gets the `plural` form. Every `#` in the chosen form is replaced with
+`n`. The optional `zero` string is returned as-is when `n === 0`.
+
+```js
+plural(1, '# apple', '# apples')                // '1 apple'
+plural(2, '# apple', '# apples')                // '2 apples'
+plural(11, '# apple', '# apples')               // '11 apples'
+plural(21, '# apple', '# apples')               // '21 apple'
+plural(0, '# apple', '# apples')                // '0 apples'
+plural(0, '# apple', '# apples', 'No apples')   // 'No apples'
+```

package/src/random_hex.md

@@ -0,0 +1,9 @@
+Returns `bytes` cryptographically random bytes (`crypto.randomBytes`) as a
+lowercase hex string — 2 characters per byte. Defaults to 32 bytes (64 hex
+characters).
+
+```js
+random_hex(4)   // '0566a554'
+random_hex()    // 64-character hex string
+random_hex(0)   // ''
+```

package/src/random_int.md

@@ -0,0 +1,8 @@
+Returns a random integer between `min` and `max`, both inclusive. Based on
+`Math.random` — not cryptographically secure (use `random_hex` for tokens).
+
+```js
+random_int(1, 6)    // 1..6, like a die roll
+random_int(-3, 3)   // -3..3
+random_int(7, 7)    // 7
+```

package/src/range.js

@@ -17,7 +17,8 @@ function range(begin, end = na, step = 1, limit = 1E6)
 
 function range_forward(begin, end, step, limit)
 {
-    if (step < 0) {
+    // step = 0 cannot make progress: an empty array, not `limit` copies of begin
+    if (step <= 0) {
         return [];
     }
 
@@ -30,7 +31,8 @@ function range_forward(begin, end, step, limit)
 
 function range_backward(begin, end, step, limit)
 {
-    if (step > 0) {
+    // step = 0 cannot make progress: an empty array, not `limit` copies of begin
+    if (step >= 0) {
         return [];
     }
 

package/src/range.md

@@ -10,6 +10,8 @@ Generates a numeric sequence.
 - Positive `step` counts **up** while `value < stop`
 - Negative `step` counts **down** while `value > stop`
 - If `step` direction does not allow progress, the result is an empty array
+- `step = 0` never makes progress and gives an empty array
+- The output is capped at `limit` items (4th parameter, default `1e6`)
 
 **Returns:**
 An array of numbers.

package/src/redis_connect.js

@@ -6,7 +6,7 @@ const redis = require('redis');
 async function redis_connect(url)
 {
     const tmp = new URL(url);
-    const password = tmp.password || tmp.searchParams.get('password');
+    const password = tmp.password ? decodeURIComponent(tmp.password) : tmp.searchParams.get('password');
 
     if (url.match(/^tls:/)) {
         const out = redis.createClient({

package/src/redis_connect.md

@@ -0,0 +1,10 @@
+Connects to redis from a URL and returns a connected `redis` (node-redis v4+
+style) client. `tcp://` is rewritten to `redis://`; `tls://` is rewritten to
+`rediss://` with peer certificate verification disabled
+(`rejectUnauthorized: false`). The password comes from the URL userinfo
+(URL-decoded) or, failing that, from a `?password=` query parameter.
+
+```js
+await redis_connect('tcp://127.0.0.1:6379');
+await redis_connect('tls://11.11.11.11:6378?password=xxx');
+```

package/src/redis_lshift.md

@@ -0,0 +1,14 @@
+Atomically pops up to `limit` items (default `1`) from the head of a redis
+list: a `MULTI` transaction of `LRANGE queue 0 limit-1` plus
+`LTRIM queue limit -1`. Returns the array of popped items — empty when the
+list is empty.
+
+Works with both legacy callback clients (redis@1–3, detected by the presence
+of a lowercase `lrange` method) and promise clients (redis@4–6); the tests run
+against all six major versions.
+
+## Signature
+
+```
+redis_lshift(redis, queue, limit = 1) → Promise<string[]>
+```

package/src/redis_poll.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-unused-vars -- destructured option lists document the full options contract */
 const Promise = require('bluebird');
 const random_int = require('./random_int');
 const redis_zshift = require('./redis_zshift');

package/src/redis_poll.md

@@ -0,0 +1,17 @@
+Generic worker poll loop with pluggable queue I/O: repeatedly calls
+`options.poll_message()` for the next message object, runs `options.callback`
+on it, and reports the result via `options.push_response({uid, version, type,
+value})` with `type: 'resolve'` on success or `'reject'` (stack/message
+string) on failure. An empty poll sleeps a random 500–1500ms; the loop runs
+at most 86400 iterations.
+
+- Messages without `uid` are skipped; a missing or past `expires_at` rejects
+  the message (payloads carry signed urls with limited lifetime).
+- The callback receives `{message, log, user_friendly_status}`;
+  `user_friendly_status(value)` still rpushes
+  `{uid, version, type: 'user_friendly_status', value}` JSON directly to
+  `options.redis`/`options.redis_output_queue`, starting with `'Started...'`.
+- `options.log` must provide `spawn()`; the many `log_waiter_*`/`log_worker_*`
+  options are the tag names used in log lines.
+
+See `redis_poll_zshift_callback_rpush` for the concrete zshift/rpush variant.

package/src/redis_poll_zshift_callback_rpush.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-unused-vars -- destructured option lists document the full options contract */
 const Promise = require('bluebird');
 const random_int = require('./random_int');
 const redis_zshift = require('./redis_zshift');
@@ -54,8 +55,6 @@ async function redis_poll_zshift_callback_rpush(options)
                 await Promise.delay(ms);
                 continue;
             }
-            console.log(message_string);
-
             let message = null;
             try {
                 message = JSON.parse(message_string);

package/src/redis_poll_zshift_callback_rpush.md

@@ -0,0 +1,17 @@
+Worker poll loop over redis queues: repeatedly `redis_zshift`s one message
+from `redis_input_queue`, JSON-parses it, runs `options.callback({message,
+log, user_friendly_status})`, and rpushes a JSON response `{uid, version,
+type, value}` to `redis_output_queue` — `type: 'resolve'` with the callback's
+return value, or `'reject'` with the error stack/message. An empty poll
+sleeps a random 500–1500ms; the loop runs at most 86400 iterations.
+
+- Unparseable messages and messages without `uid` are skipped; a missing or
+  past `expires_at` rejects the message (payloads carry signed urls with
+  limited lifetime).
+- `user_friendly_status(value)` rpushes `{uid, version, type:
+  'user_friendly_status', value}` to the output queue; a generic
+  `'Started...'` status is always pushed first so the consumer starts
+  refreshing.
+- `options.log` must provide `spawn()`; the `log_waiter_*`/`log_worker_*`
+  options are the tag names used in log lines. The redis client must provide
+  `rpush_p`.

package/src/redis_poll_zshift_spawn_rpush.js

@@ -138,7 +138,8 @@ async function worker(log, request, options)
             try {
                 await new Promise(function (resolve, reject) {
                     proc.once('error', reject);
-                    proc.once('exit', code => code ? reject(new Error(`Process terminated with code ${code}`)) : resolve());
+                    // A signal-killed process exits with code = null: only 0 is a success
+                    proc.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(`Process terminated with code ${code} and signal ${signal}`)));
                     end_stdout = stream_data_ln(proc.stdout, line => log(`[${log_worker_stdout}] ${line}`));
                     end_stderr = stream_data_ln(proc.stderr, line => log(`[${log_worker_stderr}] ${line}`));
                     end_user_friendly_status = stream_data_ln(proc.stdio[3], function (line) {

package/src/redis_poll_zshift_spawn_rpush.md

@@ -0,0 +1,20 @@
+Worker poll loop over redis queues that delegates the actual work to an
+external executable. Repeatedly `redis_zshift`s one message from
+`redis_input_queue`, JSON-parses it, dumps it as `request.json` into a fresh
+temp directory, and spawns `spawn_command` with that directory as `cwd`. On
+exit code 0 it rpushes `{uid, version, type: 'resolve', value: null}` to
+`redis_output_queue`; any failure rpushes `type: 'error'` with the stack.
+An empty poll sleeps a random 500–1500ms; the loop runs at most 86400
+iterations.
+
+- The child gets an extra pipe on fd 3: each line written there is rpushed as
+  a `{uid, version, type: 'user_friendly_status', value}` message; a generic
+  `'Started...'` status is always pushed first. stdout/stderr are logged
+  line by line under the `log_worker_stdout`/`log_worker_stderr` tags.
+- Only exit code 0 is a success — a signal-killed child (code `null`) fails.
+- Unparseable messages and messages without `uid` are skipped; a missing or
+  past `expires_at` fails the message (payloads carry signed urls with
+  limited lifetime).
+- `options.log` must provide `spawn()`; the redis client must provide
+  `rpush_p`. See `redis_poll_zshift_callback_rpush` for the in-process
+  callback variant (which reports failures as `type: 'reject'`).

package/src/redis_zshift.md

@@ -0,0 +1,14 @@
+Atomically pops up to `limit` (default `1`) lowest-scored members from a redis
+sorted set: a `MULTI` transaction of `ZRANGE queue 0 limit-1` plus
+`ZREMRANGEBYRANK queue 0 limit-1`. Returns the array of popped members —
+empty when the set is empty.
+
+Works with both legacy callback clients (redis@1–3, detected by the presence
+of a lowercase `zrange` method) and promise clients (redis@4–6); the tests run
+against all six major versions.
+
+## Signature
+
+```
+redis_zshift(redis, queue, limit = 1) → Promise<string[]>
+```

package/src/round.js

@@ -26,14 +26,13 @@ function get_decimal_places(precision)
         return 0;
     }
 
-    // Scientific notation support: e.g., 1e-20
-    const e = precision.toExponential().split('e');
-    if (e.length > 1) {
-        return Math.abs(parseInt(e[1], 10));
-    }
-
-    // Normal decimal notation (e.g., 0.001)
-    return precision.toString().split('.')[1]?.length || 0;
+    // toExponential gives MANTISSAe±EXP; decimal places = mantissa fraction
+    // digits minus the exponent. Counting the exponent alone is not enough:
+    // 0.25 → "2.5e-1" → 1 - (-1) = 2 (not 1, which would re-round 1.25 → 1.3)
+    // 0.001 → "1e-3" → 0 - (-3) = 3
+    const [mantissa, exp] = precision.toExponential().split('e');
+    const digits = (mantissa.split('.')[1] || '').length;
+    return Math.max(0, digits - parseInt(exp, 10));
 }
 
 // // round(34.037531, 0.001) -> 34.038000000000004

package/src/round.md

@@ -0,0 +1,15 @@
+Rounds `value` to the nearest multiple of `precision` (default `1`).
+Precision can be fractional (`0.01`), coarse (`25`, `1000`), or a non-power
+of 10 (`0.25`). A tiny signed epsilon fixes floating-point tie cases
+(`1.005` at `0.01` correctly gives `1.01`, `-1.005` gives `-1.01`), and a
+final `toFixed` cleanup strips artifacts like `34.038000000000004`.
+`precision = 0` returns the value unchanged.
+
+```js
+round(2.7)                  // 3
+round(34.037531, 0.001)     // 34.038
+round(1.005, 0.01)          // 1.01
+round(123.456, 10)          // 120
+round(37.5, 25)             // 50
+round(1.13, 0.25)           // 1.25
+```

package/src/sanitize_dash_name.md

@@ -0,0 +1,13 @@
+Converts a string to a lowercase dash-name (slug): accents are stripped via
+NFD normalization, every other non-ASCII-alphanumeric character becomes a
+dash, runs of dashes collapse, and leading/trailing dashes are trimmed.
+Characters with no ASCII base letter (e.g. Cyrillic) are dropped, so the
+result can be an empty string.
+
+```js
+sanitize_dash_name('1000 Stories')      // '1000-stories'
+sanitize_dash_name('Ópera Prima')       // 'opera-prima'
+sanitize_dash_name('Black & Decker')    // 'black-decker'
+sanitize_dash_name('M&M\'s')            // 'm-m-s'
+sanitize_dash_name('привет')            // ''
+```

package/src/sanitize_filename.md

@@ -0,0 +1,9 @@
+Thin wrapper around the [sanitize-filename](https://www.npmjs.com/package/sanitize-filename)
+package: makes a string safe to use as a single filename by removing path
+separators, reserved/control characters, and Windows-reserved names. It does
+not slugify — spaces, dots, and unicode are kept.
+
+```js
+sanitize_filename('../some/file*name?.txt')     // '..somefilename.txt'
+sanitize_filename('report: 2024/Q1.pdf')        // 'report 2024Q1.pdf'
+```

package/src/sanitize_var_name.md

@@ -0,0 +1,14 @@
+Converts an arbitrary string (a spreadsheet header, an API field name) into
+a safe snake_case identifier: camelCase is split first
+(`str_camel_to_snake`), accents and symbols are handled by
+`sanitize_dash_name`, and the dashes become underscores. The result always
+matches `[a-z0-9_]+`: an empty result becomes `'_'`, and a leading digit is
+prefixed with `'_'`.
+
+```js
+sanitize_var_name('Image URL')          // 'image_url'
+sanitize_var_name('ItemInternalId')     // 'item_internal_id'
+sanitize_var_name('@odata.etag')        // 'odata_etag'
+sanitize_var_name('1000-stories')       // '_1000_stories'
+sanitize_var_name('')                   // '_'
+```

package/src/sftp_get_file_info.js

@@ -3,10 +3,10 @@ const ignore = require('./ignore');
 const ssh2 = require('ssh2');
 const waitcb = require('./waitcb');
 
-async function sftp_get_file_info(url, {user_friendly_status = ignore})
+async function sftp_get_file_info(url, {user_friendly_status = ignore} = {})
 {
     const u = new URL(url);
-    const host = u.host;
+    const host = u.hostname; // u.host would include the :port, breaking dns lookup
     const port = +u.port || 22;
     const username = decodeURIComponent(u.username);
     const password = decodeURIComponent(u.password);

package/src/sftp_get_file_info.md

@@ -0,0 +1,14 @@
+Connects to an sftp server described by a URL
+(`sftp://user:pass@host:port/path`) and returns `{stat, lstat, readdir}` for
+the path. Credentials are percent-decoded from the URL; the port defaults
+to 22. The connection is always closed afterwards, on success and on failure.
+
+Rejects on connection or authentication errors, and when the path does not
+exist. The optional `user_friendly_status` callback receives progress
+messages (`'Establishing connection...'`, ...).
+
+```js
+const info = await sftp_get_file_info('sftp://user:p%40ss@example.com/upload');
+info.stat.isDirectory() // true
+info.readdir[0]         // {filename, longname, attrs}
+```

package/src/sftp_get_stream_range.js

@@ -5,7 +5,7 @@ const waitcb = require('./waitcb');
 async function sftp_get_stream_range(url, first, last, {user_friendly_status = ignore} = {})
 {
     const u = new URL(url);
-    const host = u.host;
+    const host = u.hostname; // u.host would include the :port, breaking dns lookup
     const port = +u.port || 22;
     const username = decodeURIComponent(u.username);
     const password = decodeURIComponent(u.password);
@@ -19,31 +19,41 @@ async function sftp_get_stream_range(url, first, last, {user_friendly_status = i
         conn.connect({host, port, username, password});
     });
 
-    user_friendly_status('Asking for an sftp service...');
-    const sftp = await waitcb(cb => conn.sftp(cb));
+    try {
+        user_friendly_status('Asking for an sftp service...');
+        const sftp = await waitcb(cb => conn.sftp(cb));
 
-    user_friendly_status('Requesting file info...');
-    const stat = await waitcb(cb => sftp.stat(pathname, cb));
+        user_friendly_status('Requesting file info...');
+        const stat = await waitcb(cb => sftp.stat(pathname, cb));
 
-    if (first < 0 || last >= stat.size) {
-        throw new Error(`Invalid range: [first=${first}][last=${last}]`);
-    }
+        if (first < 0 || last >= stat.size) {
+            throw new Error(`Invalid range: [first=${first}][last=${last}]`);
+        }
 
-    const out = sftp.createReadStream(pathname, {start: first, end: last})
-    out.content_range = {
-        type: 'bytes',
-        first,
-        last,
-        total: stat.size,
-    };
-    out.total = out.content_range.total;
-    out.once('error', function () {
-        conn.destroy();
-    });
-    out.once('end', function () {
+        const out = sftp.createReadStream(pathname, {start: first, end: last})
+        out.content_range = {
+            type: 'bytes',
+            first,
+            last,
+            total: stat.size,
+        };
+        out.total = out.content_range.total;
+        // 'close' fires on end, on error, and also when the consumer
+        // destroys the stream early (e.g. an aborted http range request) —
+        // 'end'/'error' alone would leak the connection in that case.
+        out.once('close', function () {
+            // destroying the connection errors the in-flight sftp requests
+            // (prefetched READs) with "No response from server", and those
+            // land on this already-closed stream — ignore them
+            out.on('error', ignore);
+            conn.destroy();
+        });
+        return out;
+    }
+    catch (error) {
         conn.destroy();
-    });
-    return out;
+        throw error;
+    }
 }
 
 module.exports = sftp_get_stream_range;

package/src/sftp_get_stream_range.md

@@ -0,0 +1,20 @@
+Opens a byte range of a remote file over sftp and returns it as a readable
+stream. The URL carries the connection details
+(`sftp://user:pass@host:port/path`); credentials are percent-decoded, the
+port defaults to 22. `first` and `last` are inclusive byte offsets.
+
+The file is `stat`ed first: `first < 0` or `last >= size` rejects with an
+`Invalid range` error (no clamping, unlike `http_range_parse`). Like
+`http_get_stream_range`, the stream gets `content_range`
+(`{type, first, last, total}`) and `total` (the full file size) attached.
+
+The ssh connection is destroyed when the stream closes — on end, on error,
+and also when the consumer destroys the stream early (e.g. an aborted http
+range request); nothing leaks. Setup failures (bad credentials, missing
+file, invalid range) also close the connection before rejecting. The
+optional `user_friendly_status` callback receives progress messages.
+
+```js
+const rs = await sftp_get_stream_range(url, 0, 1023, {user_friendly_status: console.log});
+rs.total // full file size
+```

package/src/shell_curl_progress.js

@@ -21,7 +21,8 @@ async function shell_curl_progress(args, {options, user_friendly_status})
     const promises = [];
     promises.push(new Promise(function (resolve, reject) {
         proc.once('error', reject);
-        proc.once('exit', code => code ? reject(new Error(`Process terminated with code ${code}`)) : resolve());
+        // A signal-killed process exits with code = null: only 0 is a success
+        proc.once('exit', (code, signal) => code === 0 ? resolve() : reject(new Error(`Process terminated with code ${code} and signal ${signal}`)));
     }));
     promises.push(stream.promises.pipeline(proc.stderr, stream_curl_progress(), stream_each(progress_fn)));