@vbarbarosh/node-helpers 3.74.1 → 3.76.0

package/src/fs_path_dirname.md

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

package/src/fs_path_extname.md

@@ -0,0 +1,9 @@
+Thin wrapper over node's `path.extname(p)`, kept for the consistent `fs_*` naming.
+Returns the extension including the dot, or `''` when there is none — note node's dotfile rules:
+
+```js
+fs_path_extname('file.js');   // '.js'
+fs_path_extname('.foo');      // ''
+fs_path_extname('..foo');     // '.foo'
+fs_path_extname('/a/b.js/c'); // ''
+```

package/src/fs_path_join.md

@@ -0,0 +1,2 @@
+Thin wrapper over node's `path.join(...parts)`, kept for the consistent `fs_*` naming.
+Joins and normalizes the given path segments.

package/src/fs_path_relative.md

@@ -0,0 +1,2 @@
+Thin wrapper over node's `path.relative(from, to)`, kept for the consistent `fs_*` naming.
+Returns the relative path from `from` to `to`.

package/src/fs_path_resolve.md

@@ -0,0 +1,2 @@
+Thin wrapper over node's `path.resolve(...parts)`, kept for the consistent `fs_*` naming.
+Resolves the segments right-to-left into an absolute path (against the current working directory if needed).

package/src/fs_path_tempdir.md

@@ -0,0 +1,2 @@
+Thin wrapper over node's `os.tmpdir()`, kept for the consistent `fs_*` naming.
+Returns the OS default directory for temporary files, e.g. `/tmp`.

package/src/fs_path_untildify.md

@@ -0,0 +1,8 @@
+Expands a leading `~` in a path to the current user's home directory (ported from sindresorhus/untildify).
+Only a `~` that is the whole path or is followed by `/` or `\` is expanded; anything else is returned unchanged.
+If the home directory cannot be determined, the path is returned as-is.
+
+```js
+fs_path_untildify('~/x');    // '/home/ubuntu/x'
+fs_path_untildify('~foo/x'); // '~foo/x'
+```

package/src/fs_read.md

@@ -0,0 +1,3 @@
+Thin wrapper over `fs.promises.readFile(path, options)`.
+Without an `encoding` in `options` it resolves with a `Buffer`; with one, a string.
+Prefer the specialized variants: `fs_read_buffer`, `fs_read_utf8`, `fs_read_json`, `fs_read_lines`.

package/src/fs_read_buffer.md

@@ -0,0 +1,5 @@
+Reads the entire contents of a file into a `Buffer` (i.e. `fs_read` with no encoding).
+
+```js
+fs_read_buffer(file) → Promise<Buffer>
+```

package/src/fs_read_json.md

@@ -0,0 +1,6 @@
+Reads a file as UTF-8 and parses it with `JSON.parse`.
+Rejects if the file is missing or the content is not valid JSON.
+
+```js
+fs_read_json(file) → Promise<any>
+```

package/src/fs_read_lines.md

@@ -0,0 +1,7 @@
+Reads a file as UTF-8 and splits it on `'\n'`.
+The trailing newline is NOT stripped: a file ending in `\n` yields a final `''` element.
+
+```js
+// file content: 'one\ntwo\n'
+await fs_read_lines(file); // ['one', 'two', '']
+```

package/src/fs_read_stream.md

@@ -0,0 +1,2 @@
+Thin wrapper over `fs.createReadStream(path, options)`.
+Returns a readable stream synchronously (not a Promise); open errors are emitted as `'error'` events on the stream.

package/src/fs_read_utf8.md

@@ -0,0 +1,5 @@
+Reads the entire contents of a file into a UTF-8 decoded string.
+
+```js
+fs_read_utf8(file) → Promise<string>
+```

package/src/fs_readdir.md

@@ -0,0 +1,3 @@
+Thin wrapper over `fs.promises.readdir(path, options)`.
+Resolves with an array of basenames (not full paths); pass `{withFileTypes: true}` for `Dirent` objects.
+Rejects if `path` is missing or not a directory.

package/src/fs_readlink.md

@@ -0,0 +1,6 @@
+Promisified `fs.readlink`: resolves with the target a symbolic link points to.
+Rejects if the path is missing or not a symlink (`EINVAL`).
+
+```js
+fs_readlink(path) → Promise<string>
+```

package/src/fs_rename.md

@@ -0,0 +1,6 @@
+Promisified `fs.rename`: moves/renames a file or directory, overwriting an existing file at the destination.
+Fails across filesystem boundaries (`EXDEV`) — copy + remove in that case.
+
+```js
+fs_rename(old_path, new_path) → Promise<void>
+```

package/src/fs_rm.md

@@ -0,0 +1,4 @@
+Removes a single file (thin wrapper over `fs.promises.unlink`).
+Rejects if the path is missing (`ENOENT`) or is a directory.
+
+See also: `fs_rmf` (ignore missing), `fs_rmdir` (empty directory), `fs_rmrf` (recursive, never throws on missing).

package/src/fs_rmdir.md

@@ -0,0 +1,3 @@
+Removes an **empty** directory (thin wrapper over `fs.promises.rmdir`).
+Rejects if the path is missing (`ENOENT`), not empty (`ENOTEMPTY`), or not a directory.
+Use `fs_rmrf` to remove a directory with contents.

package/src/fs_rmf.md

@@ -0,0 +1,2 @@
+Removes the file if it exists: `fs_rm` that swallows `ENOENT` (like `rm -f`).
+Any other error (e.g. the path is a directory) is still thrown.

package/src/fs_rmrf.md

@@ -0,0 +1,8 @@
+Removes a file or directory recursively, like `rm -rf`.
+A missing path is silently ignored; children of a directory are removed in parallel.
+Uses `lstat`, so a symlink is removed itself — its target is never followed.
+
+**Signature:** `fs_rmrf(path, progress = ignore) → Promise<void>`
+
+The optional `progress` callback is called as `progress('rm', path)` before each file
+and `progress('rmdir', path)` before each directory removal.

package/src/fs_sha256.js

@@ -0,0 +1,16 @@
+const crypto = require('crypto');
+const fs = require('fs');
+
+async function fs_sha256(path)
+{
+    const hash = crypto.createHash('sha256');
+
+    const highWaterMark = 1024*1024;
+    for await (const chunk of fs.createReadStream(path, {highWaterMark})) {
+        hash.update(chunk);
+    }
+
+    return hash.digest('hex');
+}
+
+module.exports = fs_sha256;

package/src/fs_sha256.md

@@ -0,0 +1,9 @@
+Computes the SHA-256 of a file, streaming it in 1 MiB chunks (constant
+memory regardless of file size). Returns the digest as a lowercase hex
+string. Rejects with `ENOENT` for a missing file; an empty file gives the
+well-known empty-input digest.
+
+```js
+await fs_sha256('/tmp/data.txt')
+// '2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824' ('hello')
+```

package/src/fs_size.js

@@ -1,8 +1,8 @@
 const fs_stat = require('./fs_stat');
 
-async function fs_size(file)
+async function fs_size(path)
 {
-    const stat = await fs_stat(file);
+    const stat = await fs_stat(path);
     return stat.size;
 }
 

package/src/fs_size.md

@@ -0,0 +1,6 @@
+Resolves with the size of a file in bytes (`fs_stat(path)` → `stat.size`).
+Rejects if the path is missing; see `fs_size_enoent` for the variant that returns 0 instead.
+
+```js
+fs_size(path) → Promise<number>
+```

package/src/fs_stat.md

@@ -0,0 +1,2 @@
+Thin wrapper over `fs.promises.stat(path, options)`: resolves with an `fs.Stats` object.
+Follows symlinks (use `fs_lstat` to stat the link itself); rejects with `ENOENT` if the path is missing.

package/src/fs_tempdir.js

@@ -11,9 +11,16 @@ const mkdtemp = util.promisify(fs.mkdtemp);
 // * http://www.tldp.org/LDP/abs/html/exitcodes.html from https://stackoverflow.com/q/14031763/1478566
 // * https://www.exratione.com/2013/05/die-child-process-die/
 
+// A single shared SIGINT listener no matter how many calls are in flight:
+// one listener per call trips MaxListenersExceededWarning at 10+ concurrent calls.
+const cleanups = new Set();
+
 async function fs_tempdir(fn)
 {
-    process.on('SIGINT', sigint);
+    cleanups.add(clean);
+    if (cleanups.size === 1) {
+        process.on('SIGINT', sigint);
+    }
 
     let d = null, out;
     try {
@@ -26,17 +33,25 @@ async function fs_tempdir(fn)
     return out;
 
     async function clean() {
-        process.removeListener('SIGINT', sigint);
+        if (!cleanups.delete(clean)) {
+            return;
+        }
+        if (cleanups.size === 0) {
+            process.removeListener('SIGINT', sigint);
+        }
         if (d) {
             await fs_rmrf(d);
         }
     }
+}
 
-    async function sigint() {
+async function sigint()
+{
+    for (const clean of [...cleanups]) {
         await clean().catch(function () {/* ignore */});
-        // https://stackoverflow.com/questions/14031763/doing-a-cleanup-action-just-before-node-js-exits#comment68567869_21947851
-        process.kill(process.pid, 'SIGINT');
     }
+    // https://stackoverflow.com/questions/14031763/doing-a-cleanup-action-just-before-node-js-exits#comment68567869_21947851
+    process.kill(process.pid, 'SIGINT');
 }
 
 module.exports = fs_tempdir;

package/src/fs_touch.md

@@ -0,0 +1,6 @@
+Creates the file if it does not exist, then sets its atime and mtime to now — like the `touch` command.
+Rejects with `Cannot touch a directory: <file>` when the path is an existing directory.
+
+```js
+fs_touch(file) → Promise<void>
+```

package/src/fs_walk.js

@@ -3,7 +3,7 @@ const fs_path_join = require('./fs_path_join');
 const fs_readdir = require('./fs_readdir');
 const ignore = require('./ignore');
 
-async function fs_walk({path = '.', user_friendly_status = ignore, error_handler = error_handler, signal})
+async function fs_walk({path = '.', user_friendly_status = ignore, error_handler = default_error_handler, signal})
 {
     const out = [];
     const queue = [path];
@@ -32,7 +32,7 @@ async function fs_walk({path = '.', user_friendly_status = ignore, error_handler
     return out;
 }
 
-function error_handler(error)
+function default_error_handler(error)
 {
     console.log(`⚠️ ${error.message}`);
 }

package/src/fs_walk.md

@@ -0,0 +1,14 @@
+Walks a directory tree and resolves with a flat array of `lstat` results,
+each with a `path` property added; the root entry is included. Order is not guaranteed.
+
+**Options:** `fs_walk({path = '.', user_friendly_status, error_handler, signal})`
+- `user_friendly_status(text)` — called with `Reading <path>` per entry
+- `error_handler(error)` — per-entry errors are reported here and the walk continues (default logs to console)
+- `signal` — an `AbortSignal` to cancel the walk
+
+Symlinks are not followed (`lstat`), and the contents of `/dev` and `/proc` are skipped.
+
+```js
+await fs_walk({path: 'w'});
+// [Stats {path: 'w', ...}, Stats {path: 'w/sub', ...}, Stats {path: 'w/a.txt', ...}, ...]
+```

package/src/fs_write.md

@@ -0,0 +1,3 @@
+Thin wrapper over `fs.promises.writeFile(file, data, options)`.
+Creates or truncates the file; `data` may be a string (written as UTF-8 unless `options` says otherwise), a `Buffer`, or a `TypedArray`.
+For objects, prefer `fs_write_json`.

package/src/fs_write_json.md

@@ -0,0 +1,7 @@
+Serializes `data` with `JSON.stringify(data, null, 4)` and writes it to the file as UTF-8.
+The output is pretty-printed with 4-space indentation and has no trailing newline.
+
+```js
+await fs_write_json(file, {name: 'x'});
+// file content: '{\n    "name": "x"\n}'
+```

package/src/fs_write_stream.md

@@ -0,0 +1,2 @@
+Thin wrapper over `fs.createWriteStream(path, options)`.
+Returns a writable stream synchronously (not a Promise); open errors are emitted as `'error'` events on the stream.

package/src/gettype.md

@@ -0,0 +1,13 @@
+Returns the type of a value as a string (see `const_type`). Like `typeof`,
+but with the usual annoyances fixed: `null` is `'null'` (not `'object'`),
+arrays are `'array'`, and the special numbers get their own names — `'nan'`,
+`'-inf'`, `'+inf'`.
+
+```js
+gettype(null)       // 'null'
+gettype([])         // 'array'
+gettype(NaN)        // 'nan'
+gettype(-Infinity)  // '-inf'
+gettype(1n)         // 'bigint'
+gettype({})         // 'object'
+```

package/src/http_delete.md

@@ -0,0 +1,11 @@
+Sends a `DELETE` request via axios with `responseType: 'json'` and resolves
+with `response.data`. Extra axios options pass through (and may override the
+defaults).
+
+```js
+await http_delete('https://api.example.com/items/15')
+// → parsed response body
+```
+
+Sibling of `http_get_json`, `http_post_json`, `http_put_json`,
+`http_patch_json`.

package/src/http_get_blob.md

@@ -0,0 +1,8 @@
+Sends a `GET` request via axios with `responseType: 'blob'` and resolves with
+`response.data` — a `Blob`. Meant for browser code; in Node prefer
+`http_get_buffer` (Buffer) or `http_get_stream` (readable stream). Extra axios
+options pass through.
+
+```js
+const blob = await http_get_blob('https://example.com/image.png');
+```

package/src/http_get_buffer.md

@@ -0,0 +1,10 @@
+Sends a `GET` request via axios with `responseType: 'arraybuffer'` and
+resolves with `response.data` — a `Buffer` in Node, an `ArrayBuffer` in the
+browser. Extra axios options pass through.
+
+```js
+const buf = await http_get_buffer('https://example.com/image.png');
+```
+
+See also `http_get_utf8` (string), `http_get_json` (parsed JSON),
+`http_get_blob` (browser Blob), `http_get_stream` (readable stream).

package/src/http_get_file.js

@@ -1,17 +1,17 @@
 const axios = require('axios');
 const fs = require('fs');
 const stream = require('stream');
-const util = require('util');
-
-const stream_finished = util.promisify(stream.finished);
 
 // https://stackoverflow.com/a/61269447
-function http_get_file(url, out_file, options)
+async function http_get_file(url, out_file, options)
 {
-    const ws = fs.createWriteStream(out_file);
-    return axios.get(url, {responseType: 'stream', ...options}).then(function (response) {
-        return stream_finished(response.data.pipe(ws));
-    });
+    // Create out_file only after a successful response: a failed request
+    // (e.g. 404) should not leave an empty file behind.
+    const response = await axios.get(url, {responseType: 'stream', ...options});
+    // pipeline destroys both streams on any failure: an aborted download
+    // rejects instead of hanging forever, an unwritable out_file rejects
+    // instead of raising an uncaught 'error' event.
+    await stream.promises.pipeline(response.data, fs.createWriteStream(out_file));
 }
 
 module.exports = http_get_file;

package/src/http_get_file.md

@@ -0,0 +1,14 @@
+Downloads `url` into `out_file`.
+
+- An HTTP error status (e.g. 404) rejects and does not create `out_file` —
+  the file is only created after a successful response.
+- Rejects when the server aborts the download mid-stream (no hanging) and
+  when `out_file` is not writable; both streams are destroyed on any failure.
+- `options` are passed through to `axios.get` (after
+  `responseType: 'stream'`).
+
+## Signature
+
+```
+http_get_file(url, out_file, options) → Promise<void>
+```

package/src/http_get_json.md

@@ -0,0 +1,10 @@
+Sends a `GET` request via axios with `responseType: 'json'` and resolves with
+`response.data` — the parsed response body. Extra axios options (headers,
+params, timeout, ...) pass through.
+
+```js
+const user = await http_get_json('https://api.example.com/users/15');
+```
+
+See also `http_get_utf8` (raw string), `http_get_buffer`/`http_get_blob`
+(binary), `http_get_stream` (readable stream).

package/src/http_get_stream.md

@@ -0,0 +1,14 @@
+Sends a `GET` request via axios with `responseType: 'stream'` and resolves
+with the response's readable stream, decorated with two extra properties:
+`headers` (the response headers) and `total` (the `Content-Length` as an
+integer, or `null` when the header is missing or unparsable). Extra axios
+options pass through.
+
+```js
+const stream = await http_get_stream('https://example.com/big.bin');
+stream.total          // 3000000 (or null)
+stream.headers        // response headers
+stream.pipe(dest);
+```
+
+See also `http_get_buffer` when the whole body fits in memory.

package/src/http_get_stream_range.js

@@ -10,21 +10,39 @@ async function http_get_stream_range(url, first, last)
     const res = await axios.get(url, {responseType: 'stream', headers});
     const out = res.data;
     out.headers = res.headers;
-    if (res.headers['content-range']) {
-        out.content_range = parse_http_content_range(res.headers['content-range']);
+    try {
+        if (res.headers['content-range']) {
+            out.content_range = parse_http_content_range(res.headers['content-range']);
+        }
+        else if (res.headers['content-length']) {
+            const len = +res.headers['content-length'];
+            out.content_range = parse_http_content_range(`bytes 0-${len - 1}/${len}`);
+        }
+        else {
+            // Chunked 200 response: the body starts at byte 0, size unknown
+            out.content_range = {type: 'bytes', first: 0, last: null, total: null};
+        }
     }
-    else {
-        const len = res.headers['content-length'];
-        out.content_range = parse_http_content_range(`${res.headers['accept-ranges']} 0-${len}/${len}`);
+    catch (error) {
+        out.destroy(); // release the socket; nobody will ever read this stream
+        throw error;
     }
-    if (a && out.content_range.first !== a) {
-        out.destroy(new Error(`First byte of a returned range (${format_thousands(out.content_range.first)}) is not as expected: [${format_thousands(a)}]`));
+    // A server reaching the end of the resource returns a shorter range than
+    // requested: `bytes=0-999999` of a 500-byte file is `bytes 0-499/500` (RFC 7233)
+    const expected_last = (b === '' || out.content_range.total === null) ? b : Math.min(b, out.content_range.total - 1);
+    if (a !== '' && out.content_range.first !== a) {
+        out.destroy(new Error(`First byte of a returned range (${fmt(out.content_range.first)}) is not as expected: [${fmt(a)}]`));
     }
-    else if (b && out.content_range.last !== b) {
-        out.destroy(new Error(`Last byte of a returned range (${format_thousands(out.content_range.last)}) is not as expected: [${format_thousands(b)}]`));
+    else if (b !== '' && out.content_range.last !== expected_last) {
+        out.destroy(new Error(`Last byte of a returned range (${fmt(out.content_range.last)}) is not as expected: [${fmt(expected_last)}]`));
     }
     out.total = out.content_range.total;
     return out;
 }
 
+function fmt(v)
+{
+    return v === null ? 'null' : format_thousands(v);
+}
+
 module.exports = http_get_stream_range;

package/src/http_get_stream_range.md

@@ -0,0 +1,22 @@
+GETs `url` with a `Range: bytes=first-last` header and returns the response
+body as a readable stream. Either bound may be omitted (non-integer) to send
+an open-ended range; with both omitted a plain `bytes=-` request degrades to
+a regular GET.
+
+The stream gets extra properties attached: `headers` (raw response headers),
+`content_range` (parsed `{type, first, last, total}`), and `total`. When the
+server sends no `Content-Range`, it is synthesized from `Content-Length`; a
+chunked 200 response (neither header) is accepted as
+`{first: 0, last: null, total: null}` — body starts at byte 0, size unknown.
+
+The returned range is validated: a `first` or `last` that differs from the
+request destroys the stream with an error (reading it rejects) — this also
+catches a server that ignores the range and replies 200. A `last` clamped to
+the end of the resource is accepted: `bytes=0-999999` of a 500-byte file is
+`bytes 0-499/500` (RFC 7233).
+
+```js
+const rs = await http_get_stream_range(url, 100, 199);
+rs.content_range // {type: 'bytes', first: 100, last: 199, total: 1000}
+rs.total         // 1000 (null when unknown)
+```

package/src/http_get_utf8.md

@@ -0,0 +1,9 @@
+Sends a `GET` request via axios with `responseType: 'text'` and
+`responseEncoding: 'utf8'`, and resolves with `response.data` — the body as a
+UTF-8 string. Extra axios options pass through.
+
+```js
+const html = await http_get_utf8('https://example.com/');
+```
+
+See also `http_get_json` (parsed JSON) and `http_get_buffer` (binary).

package/src/http_head.md

@@ -0,0 +1,9 @@
+Sends a `HEAD` request via axios and resolves with the raw response headers
+(`response.request.res.headers` — the Node http headers object, keys
+lowercased), not the body. Extra axios options pass through.
+
+```js
+const headers = await http_head('https://example.com/file.bin');
+headers['content-length'] // '3000000'
+headers['content-type']   // 'application/octet-stream'
+```

package/src/http_patch_json.md

@@ -0,0 +1,10 @@
+Sends a `PATCH` request via axios with `body` as the request payload (a plain
+object is serialized as JSON by axios) and resolves with `response.data`.
+Extra axios options pass through.
+
+```js
+await http_patch_json('https://api.example.com/items/15', {title: 'New title'})
+// → parsed response body
+```
+
+Sibling of `http_post_json`, `http_put_json`, `http_delete`.

package/src/http_post_json.md

@@ -0,0 +1,11 @@
+Sends a `POST` request via axios with `body` as the request payload (a plain
+object is serialized as JSON by axios) and resolves with `response.data`.
+Extra axios options pass through.
+
+```js
+await http_post_json('https://api.example.com/items', {title: 'Hello'})
+// → parsed response body
+```
+
+See also `http_post_urlencoded` and `http_post_multipart` for other request
+body encodings.

package/src/http_post_multipart.md

@@ -0,0 +1,15 @@
+Sends a `POST` request with a `multipart/form-data` body built from an array
+of `{name, body, options}` items and resolves with `response.data`. `body` may
+be a string, Buffer, or readable stream; `options` (e.g. `{filename}`) is
+passed to `FormData#append` when present. In Node the `form-data` package is
+used and its boundary headers are merged into `options.headers`; in the
+browser (with `form-data` webpack-externed to the native `FormData`) the form
+is posted as-is. Extra axios options pass through.
+
+```js
+const items = [
+    {name: 'subject', body: 'Hello'},
+    {name: 'attachment', body: fs_read_stream(file), options: {filename: 'hello.txt'}},
+];
+await http_post_multipart(url, items, {auth});
+```

package/src/http_post_urlencoded.md

@@ -0,0 +1,11 @@
+Sends a `POST` request via axios with `body` serialized by Node's
+`querystring.stringify` into an `application/x-www-form-urlencoded` string,
+and resolves with `response.data`. Extra axios options (e.g. a `Content-Type`
+header) pass through.
+
+```js
+await http_post_urlencoded(url, {grant_type: 'refresh_token', refresh_token})
+// body sent as 'grant_type=refresh_token&refresh_token=...'
+```
+
+See also `http_post_json` and `http_post_multipart`.

package/src/http_put_buffer.md

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

package/src/http_put_file.js

@@ -32,13 +32,11 @@ async function http_put_file(url, file, options = {})
                 chunks.push(chunk);
             });
             response.on('end', function () {
-                switch (response.statusCode) {
-                case 200:
+                if (response.statusCode >= 200 && response.statusCode < 300) {
                     resolve({request, response, data: Buffer.concat(chunks)});
-                    break;
-                default:
+                }
+                else {
                     reject(new Error(`${response.statusCode} ${response.statusMessage}\n\n${Buffer.concat(chunks).toString('utf8')}`));
-                    break;
                 }
             });
         });
@@ -53,7 +51,12 @@ async function http_put_file(url, file, options = {})
                 prev = ready;
             });
         }
-        fs.createReadStream(file).pipe(request);
+        const rs = fs.createReadStream(file);
+        rs.on('error', function (error) {
+            reject(error);
+            request.destroy();
+        });
+        rs.pipe(request);
     });
 }
 

package/src/http_put_file.md

@@ -0,0 +1,16 @@
+PUTs a local file to `url` with an explicit `Content-Length` header (some
+services, e.g. S3, reject `Transfer-Encoding: chunked`). Any 2xx status
+resolves with `{request, response, data}` where `data` is the response body
+as a Buffer; any other status rejects with an error containing the status
+line and the response body. Errors reading the file reject too, even when
+the request is already in flight.
+
+**Options:**
+- `headers` — extra request headers (`Content-Length` is always set).
+- `progress_upload(delta, ready, total)` — called on socket drain.
+- `progress_download(delta, ready, total)` — called per response chunk;
+  `total` is `null` without a response `Content-Length`.
+
+```js
+const {response, data} = await http_put_file(signed_url, '/tmp/build.zip');
+```

package/src/http_put_json.md

@@ -0,0 +1,11 @@
+Sends a `PUT` request via axios with `body` as the request payload (a plain
+object is serialized as JSON by axios) and resolves with `response.data`.
+Extra axios options pass through.
+
+```js
+await http_put_json('https://api.example.com/items/15', {title: 'New title'})
+// → parsed response body
+```
+
+Sibling of `http_post_json`, `http_patch_json`, `http_put_buffer`,
+`http_put_utf8`.