@substrio/cli 0.0.0-stage → 0.1.0

package/src/ops.mjs

@@ -0,0 +1,265 @@
+/**
+ * Substrio CLI: any registry operation, by name, through its HTTP route.
+ *
+ * The server describes every operation of its registry, with its route, in
+ * GET /v1/_openapi (x-substrio-operation is the dotted name, such as webhook.get);
+ * nothing here knows one operation from another. An input is built from
+ * --data, --file and key=value arguments, the route's {placeholders} are
+ * filled from it, declared query parameters go in the query string, and what
+ * is left goes in the query string (GET, HEAD, DELETE) or the JSON body.
+ *
+ * Reading a catalog route, picking the route and building the request are the
+ * SDK's operation client's (one owner); this module adds the CLI's input
+ * parsing, name lookup and listing. The client loads through ./sdk.mjs
+ * (the package when installed, the sibling packages/substrio-sdk in a checkout).
+ */
+
+import { readFileSync } from 'node:fs';
+import { catalogRoute, pickRoute as pickOperationRoute } from './sdk.mjs';
+
+export { buildRequest } from './sdk.mjs';
+
+/**
+ * A key=value argument's value: JSON when it parses as JSON (numbers, true,
+ * false, null, arrays, objects, quoted strings), else the text itself.
+ * `key:=value` forces JSON and `key==value` forces text.
+ */
+function argValue(raw, mode) {
+    if (mode === 'text') return raw;
+    try {
+        return JSON.parse(raw);
+    } catch (err) {
+        if (mode === 'json') throw new Error(`not valid JSON: ${raw} (${err.message})`);
+        return raw;
+    }
+}
+
+// Sets a dotted key (a.b.c) in obj, making tables along the way.
+function setPath(obj, key, value) {
+    const parts = key.split('.');
+    let at = obj;
+    for (const part of parts.slice(0, -1)) {
+        if (at[part] === undefined) at[part] = {};
+        else if (typeof at[part] !== 'object' || at[part] === null || Array.isArray(at[part])) {
+            throw new Error(`${key}: ${part} is already a value, not a table`);
+        }
+        at = at[part];
+    }
+    at[parts[parts.length - 1]] = value;
+}
+
+/**
+ * The input an invocation gives, from its arguments (pure):
+ *   --data '{...}'   an object (or any JSON value for a body-only op)
+ *   --file f.json    the same, from a file ("-" reads stdin)
+ *   key=value        one field, dotted keys nest; later ones win
+ *   --method M       which route, when the operation has several methods
+ *   --page           a paged list: this one page, not every page
+ * Returns {input, flags} where flags holds raw, method and page. --help, --json
+ * (output) and the other global flags are taken off by the one global parser
+ * (cli.mjs parseGlobal) before this runs.
+ */
+export function parseOpArgs(args, readFile = (f) => readFileSync(f === '-' ? 0 : f, 'utf8')) {
+    let input;
+    const fields = {};
+    const flags = { raw: false, method: null, page: false };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--raw') flags.raw = true;
+        else if (arg === '--page') flags.page = true;
+        else if (arg === '--method' || arg === '-X') {
+            if (i + 1 >= args.length) throw new Error(`${arg} needs a value`);
+            flags.method = args[++i].toUpperCase();
+        }
+        else if (arg === '--data' || arg === '--file') {
+            if (i + 1 >= args.length) throw new Error(`${arg} needs a value`);
+            const text = arg === '--data' ? args[++i] : readFile(args[++i]);
+            try {
+                input = JSON.parse(text);
+            } catch (err) {
+                throw new Error(`${arg}: not valid JSON (${err.message})`);
+            }
+        } else {
+            const m = arg.match(/^([^=:]+?)(:=|==|=)([\s\S]*)$/);
+            if (!m) throw new Error(`unexpected argument "${arg}" (use key=value, --data or --file)`);
+            const mode = m[2] === ':=' ? 'json' : m[2] === '==' ? 'text' : 'auto';
+            setPath(fields, m[1], argValue(m[3], mode));
+        }
+    }
+    if (Object.keys(fields).length > 0) {
+        if (input !== undefined && (typeof input !== 'object' || input === null || Array.isArray(input))) {
+            throw new Error('key=value fields need --data or --file to be an object');
+        }
+        input = { ...(input || {}), ...fields };
+    }
+    return { input, flags };
+}
+
+// Flags that take the next argument as their value.
+const VALUE_FLAGS = new Set(['--data', '--file', '--method', '-X']);
+
+/**
+ * A wrapper's arguments split in two (pure): `positional` (bare words and
+ * "-", which fill the route's path parameters in order) and `rest` (key=value fields
+ * and flags, for parseOpArgs). `valueFlags` are the wrapper's own flags that take the next
+ * argument as their value, besides those of parseOpArgs. `--` ends option
+ * parsing: every argument after it is positional, whatever it starts with
+ * (`substrio undo -- -abc`).
+ */
+export function splitPositional(args, valueFlags = []) {
+    const positional = [];
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--') {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (VALUE_FLAGS.has(arg) || valueFlags.includes(arg)) {
+            rest.push(arg);
+            if (i + 1 < args.length) rest.push(args[++i]);
+        } else if ((arg.startsWith('-') && arg !== '-') || /^[^=:]+?(:=|==|=)/.test(arg)) rest.push(arg);
+        else positional.push(arg);
+    }
+    return { positional, rest };
+}
+
+/**
+ * The operations an OpenAPI document (GET /v1/_openapi) describes, one per
+ * route (pure): the SDK's catalog route (method, path, params, query,
+ * parameters, body, bodyProperty, bodySchema) with {name, id, summary, tags},
+ * sorted by name. `body` is true when the route carries the operation's
+ * input as a JSON request body. `name` is the registry's dotted operation
+ * name.
+ */
+export function indexOperations(openapi) {
+    const ops = [];
+    for (const [path, methods] of Object.entries(openapi?.paths || {})) {
+        for (const [method, op] of Object.entries(methods || {})) {
+            // Keyed on the registry's dotted name (x-substrio-operation); operationId
+            // is a per-route spelling and not the operation's identity.
+            if (!op || typeof op !== 'object' || !op['x-substrio-operation']) continue;
+            const route = catalogRoute(path, method, { ...op, parameters: resolveParameters(openapi, op.parameters) });
+            ops.push({
+                ...route,
+                name: op['x-substrio-operation'],
+                id: op['x-substrio-operation-id'],
+                summary: op.summary || op.description || '',
+                tags: op.tags || [],
+            });
+        }
+    }
+    // By name; an operation's routes keep the server's order, canonical first
+    // (the sort is stable).
+    ops.sort((a, b) => (a.name === b.name ? 0 : a.name < b.name ? -1 : 1));
+    return withoutCollectionRoutes(ops);
+}
+
+// The parameters of a route with every {"$ref": "#/components/..."} replaced by
+// what it points at (a JSON pointer into the catalog). A reference that
+// points at nothing is an error: a parameter is never dropped unseen.
+function resolveParameters(openapi, parameters) {
+    if (!Array.isArray(parameters)) return parameters;
+    return parameters.map((p) => (p && typeof p === 'object' && p.$ref !== undefined ? resolvePointer(openapi, p.$ref) : p));
+}
+
+// The value a JSON pointer ("#/components/parameters/X", with ~1 for / and ~0
+// for ~) names in `document`.
+function resolvePointer(document, pointer) {
+    const [root, ...keys] = String(pointer).split('/');
+    let at = document;
+    for (const key of keys) at = at !== null && typeof at === 'object' ? at[key.replaceAll('~1', '/').replaceAll('~0', '~')] : undefined;
+    if (root !== '#' || at === undefined || at === null) throw new Error(`the catalog refers to ${pointer}, which it does not hold`);
+    return at;
+}
+
+/** The path parameter that names a collection in the routes `{collection}`. */
+export const COLLECTION_PARAM = 'collection';
+
+// Whether `route` is the template route written out for one collection: the
+// same path as `template` with its {collection} segment a literal name.
+function isCollectionRoute(route, template) {
+    if (route.method !== template.method || !template.params.includes(COLLECTION_PARAM)) return false;
+    const own = route.path.split('/');
+    const shape = template.path.split('/');
+    if (own.length !== shape.length) return false;
+    let named = false;
+    for (let i = 0; i < shape.length; i++) {
+        if (shape[i] === `{${COLLECTION_PARAM}}`) {
+            if (own[i] === shape[i]) return false;
+            named = true;
+        } else if (own[i] !== shape[i]) return false;
+    }
+    return named;
+}
+
+// The server lists each {collection} route once more for every collection it
+// has (/v1/events/_import beside /v1/{collection}/_import). Those are the same
+// operation, and a route with no path parameter to fill would be picked for
+// an input that names none (inserting into the first collection). The
+// template route covers them: a collection is the `collection` parameter.
+function withoutCollectionRoutes(ops) {
+    const templates = ops.filter((op) => op.params.includes(COLLECTION_PARAM));
+    return ops.filter((op) => !templates.some((t) => t.name === op.name && isCollectionRoute(op, t)));
+}
+
+// A name in the forms people and agents use: "webhook.get", its MCP tool
+// name "substrio_webhook_get", or "webhook_get".
+const normalize = (name) => name.toLowerCase().replace(/^substrio_/, '').replace(/[._-]/g, '_');
+
+/**
+ * The routes of the operation `name` names, exact dotted name first, else by
+ * normalized name; throws when none or several operations match (pure).
+ */
+export function findOperation(ops, name) {
+    let found = ops.filter((op) => op.name === name);
+    if (found.length === 0) found = ops.filter((op) => normalize(op.name) === normalize(name));
+    const names = [...new Set(found.map((op) => op.name))];
+    if (names.length === 0) {
+        const near = [...new Set(ops.map((op) => op.name))]
+            .filter((n) => n.includes(name.replace(/^substrio_/, '').split(/[._]/)[0])).slice(0, 8);
+        throw new Error(`no operation "${name}"${near.length ? `; did you mean ${near.join(', ')}?` : ''} (substrio op list)`);
+    }
+    if (names.length > 1) throw new Error(`"${name}" matches ${names.join(', ')}; give the dotted name`);
+    return found;
+}
+
+/**
+ * The route of an operation to call with `input` (pure). Among its routes
+ * (those with `method`, when given) whose path parameters the input provides,
+ * the canonical one is the route that carries the operation's input schema
+ * as a JSON body: any field fits there, while a query-only alias takes only
+ * its declared parameters. Without a body route, the first that fits; when
+ * none fits, the first (so its error names what is missing). Throws when no
+ * route has the method.
+ */
+export function pickRoute(routes, input, method = null) {
+    return pickOperationRoute({ name: routes[0].name, routes }, input, method);
+}
+
+// The paging shape every list operation answers in (B313): a page's
+// `next_cursor`, given back as the `cursor` input for the next page.
+export const PAGE_CURSOR_INPUT = 'cursor';
+export const PAGE_NEXT_CURSOR_FIELD = 'next_cursor';
+
+/**
+ * Two pages of one list as one answer (pure): each array both carry is
+ * joined, `count` summed, and `next_cursor` is the later page's.
+ */
+export function mergePages(first, next) {
+    const merged = { ...first };
+    for (const [key, value] of Object.entries(next)) {
+        if (Array.isArray(merged[key]) && Array.isArray(value)) merged[key] = [...merged[key], ...value];
+        else if (key === 'count' && typeof merged[key] === 'number' && typeof value === 'number') merged[key] += value;
+        else if (key === PAGE_NEXT_CURSOR_FIELD) merged[key] = value;
+    }
+    return merged;
+}
+
+// Whether a list row matches a filter: every word is in its name, path,
+// summary or tags.
+export function matchesFilter(op, filter) {
+    if (!filter) return true;
+    const hay = `${op.name} ${op.method} ${op.path} ${op.summary} ${op.tags.join(' ')}`.toLowerCase();
+    return filter.toLowerCase().split(/\s+/).filter(Boolean).every((word) => hay.includes(word));
+}

package/src/readers.mjs

@@ -0,0 +1,416 @@
+/**
+ * Substrio CLI: the byte-level document readers behind `substrio data import`.
+ *
+ * Each reader is an async generator over raw Buffer chunks (never decoded
+ * text, never JSON.parse'd) that yields {position, raw, endOffset} (`raw` is
+ * a Buffer of that document's own JSON text, sent on as the server's bytes:
+ * no parse, no object graph, no stringify) or {position, error, endOffset,
+ * violations?} for what only the reader can know (a truncated final
+ * element, a CSV row with the wrong field count); whether a document's JSON
+ * text is well-formed, or an object, is the server's row error to make.
+ * endOffset is the absolute byte offset in the input just past that
+ * document, for checkpointing. Each holds at most one document's bytes
+ * beyond the chunk in flight: a chunk arrives, is appended, and every byte
+ * before the current document's start is dropped before the next chunk is
+ * pulled.
+ */
+
+import { createReadStream } from 'node:fs';
+
+import { CliError, ErrorCode } from './cli.mjs';
+
+export const CsvType = Object.freeze({ STRING: 'string', NUMBER: 'number', DATE: 'date', BOOLEAN: 'boolean', JSON: 'json' });
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * One document, or why a value is not one (pure): {position, document, size}
+ * or {position, error}. `size` is the document's length in JSON text, which
+ * the caller may know already (a line, a byte span), else it is measured.
+ */
+export function documentAt(position, value, size = null) {
+    if (isObject(value)) return { position, document: value, size: size ?? JSON.stringify(value).length };
+    const kind = Array.isArray(value) ? 'an array' : value === null ? 'null' : `a ${typeof value}`;
+    return { position, error: `not a JSON object (it is ${kind})` };
+}
+
+/** One NDJSON line as a document or an error (pure); null for a blank line. */
+export function documentOfLine(position, line) {
+    if (line.trim() === '') return null;
+    try {
+        return documentAt(position, JSON.parse(line), Buffer.byteLength(line));
+    } catch (err) {
+        return { position, error: `not valid JSON (${err.message})` };
+    }
+}
+
+export function unreadable(path, err) {
+    return new CliError(`${path}: ${err.message}`, { code: err.code === 'ENOENT' ? ErrorCode.FILE_NOT_FOUND : ErrorCode.INVALID_ARGUMENT });
+}
+
+/** Raw byte chunks of `source` ({path} or {text}), from `start` on. stdin ("-") cannot be sought. */
+export async function* byteChunksOf(source, start = 0) {
+    if (source.text !== undefined) {
+        const buf = Buffer.from(source.text, 'utf8');
+        yield start > 0 ? buf.subarray(start) : buf;
+        return;
+    }
+    const isStdin = source.path === '-';
+    if (isStdin && start > 0) throw new CliError('--resume cannot be used with stdin (--file -): it cannot be sought', { code: ErrorCode.INVALID_ARGUMENT });
+    const stream = isStdin ? process.stdin : createReadStream(source.path, start > 0 ? { start } : undefined);
+    try {
+        for await (const chunk of stream) yield chunk;
+    } catch (err) {
+        throw unreadable(source.path, err);
+    }
+}
+
+const BOM0 = 0xEF, BOM1 = 0xBB, BOM2 = 0xBF;
+const QUOTE = 0x22, BACKSLASH = 0x5C, COMMA = 0x2C, OPEN_BRACE = 0x7B, OPEN_BRACKET = 0x5B,
+    CLOSE_BRACE = 0x7D, CLOSE_BRACKET = 0x5D, SPACE = 0x20, TAB = 0x09, LF = 0x0A, CR = 0x0D, COLON = 0x3A;
+const isWs = (c) => c === SPACE || c === TAB || c === LF || c === CR;
+
+// Whether a byte span is entirely whitespace (a blank line), at the byte level: no decode.
+function isBlank(buf, start, end) {
+    for (let k = start; k < end; k++) if (!isWs(buf[k])) return false;
+    return true;
+}
+
+/**
+ * NDJSON documents of `chunks` (one JSON object per line); `baseOffset` is
+ * the absolute byte offset the first chunk starts at (for a resumed read).
+ * Each line's own bytes are yielded as `raw`, unparsed: whether it is valid
+ * JSON, or an object, is the server's row error to make.
+ */
+export async function* ndjsonDocuments(chunks, { baseOffset = 0 } = {}) {
+    let offset = baseOffset;
+    let position = 0;
+    let pending = Buffer.alloc(0);
+    let strippedBOM = baseOffset !== 0;
+    for await (const chunk of chunks) {
+        pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+        let start = 0;
+        let nl;
+        while ((nl = pending.indexOf(LF, start)) !== -1) {
+            let end = nl;
+            if (end > start && pending[end - 1] === CR) end--;
+            let raw = pending.subarray(start, end);
+            if (!strippedBOM) {
+                if (raw.length >= 3 && raw[0] === BOM0 && raw[1] === BOM1 && raw[2] === BOM2) raw = raw.subarray(3);
+                strippedBOM = true;
+            }
+            position++;
+            offset += nl + 1 - start;
+            if (!isBlank(raw, 0, raw.length)) yield { position, raw, endOffset: offset };
+            start = nl + 1;
+        }
+        if (start > 0) pending = pending.subarray(start);
+    }
+    if (pending.length) {
+        position++;
+        let raw = pending;
+        if (!strippedBOM && raw.length >= 3 && raw[0] === BOM0 && raw[1] === BOM1 && raw[2] === BOM2) raw = raw.subarray(3);
+        offset += pending.length;
+        if (!isBlank(raw, 0, raw.length)) yield { position, raw, endOffset: offset };
+    }
+}
+
+/**
+ * A JSON array of documents, read without ever holding more than one
+ * element's text: a byte scanner tracks only string, escape and nesting
+ * state to cut each top-level element's span, yielded unparsed as `raw`.
+ * Also accepts {"documents": [...]}. `resuming` skips the opening `[`/wrapper
+ * (a resumed read lands just past a previous element, expecting `,` or `]`).
+ */
+export async function* jsonArrayDocuments(chunks, { baseOffset = 0, resuming = false } = {}) {
+    const pull = chunks[Symbol.asyncIterator]();
+    let buf = Buffer.alloc(0);
+    let bufBase = baseOffset;
+    let i = 0;
+    let keepFrom = 0;
+    let eof = false;
+
+    const truncated = () => new CliError(`truncated JSON array: unexpected end of input at byte ${bufBase + i}`, { code: ErrorCode.INVALID_ARGUMENT });
+
+    async function more() {
+        if (eof) return false;
+        const { value, done } = await pull.next();
+        if (done) { eof = true; return false; }
+        const drop = keepFrom;
+        buf = Buffer.concat([buf.subarray(drop), value]);
+        bufBase += drop;
+        i -= drop;
+        keepFrom = 0;
+        return true;
+    }
+    async function peek() {
+        if (i >= buf.length) { if (!(await more())) return -1; }
+        return buf[i];
+    }
+    async function skipWs() {
+        for (;;) {
+            const c = await peek();
+            if (c === -1 || !isWs(c)) return c;
+            i++;
+        }
+    }
+    async function scanStringBody() {
+        for (;;) {
+            const c = await peek();
+            if (c === -1) throw truncated();
+            i++;
+            if (c === BACKSLASH) {
+                if ((await peek()) === -1) throw truncated();
+                i++;
+                continue;
+            }
+            if (c === QUOTE) return;
+        }
+    }
+    async function scanValue() {
+        const c = await peek();
+        if (c === -1) throw truncated();
+        if (c === QUOTE) { i++; await scanStringBody(); return; }
+        if (c === OPEN_BRACE || c === OPEN_BRACKET) {
+            let depth = 0;
+            do {
+                const ch = await peek();
+                if (ch === -1) throw truncated();
+                if (ch === QUOTE) { i++; await scanStringBody(); continue; }
+                if (ch === OPEN_BRACE || ch === OPEN_BRACKET) depth++;
+                else if (ch === CLOSE_BRACE || ch === CLOSE_BRACKET) depth--;
+                i++;
+            } while (depth > 0);
+            return;
+        }
+        for (;;) {
+            const ch = await peek();
+            if (ch === -1 || ch === COMMA || ch === CLOSE_BRACKET || ch === CLOSE_BRACE || isWs(ch)) return;
+            i++;
+        }
+    }
+
+    if (!resuming) {
+        if (baseOffset === 0) {
+            while (buf.length < 3) { if (!(await more())) break; }
+            if (buf.length >= 3 && buf[0] === BOM0 && buf[1] === BOM1 && buf[2] === BOM2) i = 3;
+        }
+        let c = await skipWs();
+        if (c === OPEN_BRACE) {
+            i++;
+            for (;;) {
+                c = await skipWs();
+                if (c === CLOSE_BRACE) throw new CliError('a .json file holds an array of objects or {"documents": [...]}; no "documents" field was found', { code: ErrorCode.INVALID_ARGUMENT });
+                if (c === -1) throw truncated();
+                if (c !== QUOTE) throw new CliError('not valid JSON (expected a field name)', { code: ErrorCode.INVALID_ARGUMENT });
+                keepFrom = i;
+                i++;
+                await scanStringBody();
+                const key = buf.subarray(keepFrom + 1, i - 1).toString('utf8');
+                c = await skipWs();
+                if (c !== COLON) throw new CliError('not valid JSON (expected ":")', { code: ErrorCode.INVALID_ARGUMENT });
+                i++;
+                await skipWs();
+                if (key === 'documents') {
+                    const vc = await peek();
+                    if (vc !== OPEN_BRACKET) throw new CliError('"documents" must be an array of objects', { code: ErrorCode.INVALID_ARGUMENT });
+                    i++;
+                    break;
+                }
+                keepFrom = i;
+                await scanValue();
+                c = await skipWs();
+                if (c === COMMA) { i++; continue; }
+                if (c === CLOSE_BRACE) throw new CliError('a .json file holds an array of objects or {"documents": [...]}; no "documents" field was found', { code: ErrorCode.INVALID_ARGUMENT });
+                throw new CliError('not valid JSON (expected "," or "}")', { code: ErrorCode.INVALID_ARGUMENT });
+            }
+        } else if (c === OPEN_BRACKET) {
+            i++;
+        } else if (c === -1) {
+            throw new CliError('not valid JSON (empty input)', { code: ErrorCode.INVALID_ARGUMENT });
+        } else {
+            throw new CliError('a .json file holds an array of objects or {"documents": [...]}; for one object per line use .ndjson', { code: ErrorCode.INVALID_ARGUMENT });
+        }
+    }
+
+    let index = 0;
+    let seenOne = resuming;
+    for (;;) {
+        let c = await skipWs();
+        if (c === CLOSE_BRACKET) { i++; return; }
+        if (seenOne) {
+            if (c !== COMMA) throw new CliError(`not valid JSON (expected "," or "]" at byte ${bufBase + i})`, { code: ErrorCode.INVALID_ARGUMENT });
+            i++;
+            c = await skipWs();
+            if (c === CLOSE_BRACKET) { i++; return; }
+        }
+        seenOne = true;
+        if (c === -1) throw truncated();
+        index++;
+        keepFrom = i;
+        await scanValue();
+        const raw = buf.subarray(keepFrom, i);
+        const endOffset = bufBase + i;
+        keepFrom = i;
+        // raw is only a balanced-brackets/quoted-string span, unparsed: whether it is well-formed
+        // JSON, or an object, is the server's row error to make (mapped back to this position).
+        yield { position: index, raw, endOffset };
+    }
+}
+
+// A value that failed its declared CSV type.
+const TYPE_ERROR = Symbol('csv-type-error');
+
+// A JSON string literal of `s`: the engine's own escaper (one native call; it also escapes a lone
+// surrogate, which a hand-written loop would let through to be replaced when the text is encoded).
+const jsonStringLiteral = (s) => JSON.stringify(s);
+
+// A JSON number literal exactly as written: embedded as given, so no digit is lost to a double.
+const JSON_NUMBER_RE = /^-?(0|[1-9]\d*)(\.\d+)?([eE][+-]?\d+)?$/;
+
+// `raw`'s declared-type value, as JSON text (not a JS value: the row is built as JSON text directly, never
+// an object that is then stringified). A CsvType.JSON field is parsed once and written again on one line.
+function csvFieldJsonText(type, raw) {
+    switch (type) {
+        case CsvType.STRING: return jsonStringLiteral(raw);
+        case CsvType.NUMBER: {
+            const text = raw.trim();
+            if (JSON_NUMBER_RE.test(text)) return text;  // already a JSON number: its own digits, whole
+            // Another spelling a number takes (.5, +5, 0x10): the value, written as JSON.
+            const n = Number(text);
+            return text !== '' && Number.isFinite(n) ? String(n) : TYPE_ERROR;
+        }
+        case CsvType.BOOLEAN: {
+            const low = raw.toLowerCase();
+            if (low === 'true') return 'true';
+            if (low === 'false') return 'false';
+            return TYPE_ERROR;
+        }
+        case CsvType.DATE: return Number.isNaN(Date.parse(raw)) ? TYPE_ERROR : jsonStringLiteral(raw);
+        // Written again from its parse, on one line: the row travels as one NDJSON line, and the field as
+        // given may hold a raw newline (pretty-printed JSON in a quoted CSV field) that would split it.
+        case CsvType.JSON: try { return JSON.stringify(JSON.parse(raw)); } catch { return TYPE_ERROR; }
+        default: return TYPE_ERROR;
+    }
+}
+
+/**
+ * CSV documents of `chunks` (RFC 4180: quoted fields, doubled quotes,
+ * embedded newlines, CRLF, a leading BOM; a header row is required). `types`
+ * is a Map of field name -> CsvType (absent fields are strings); `emptyAs`,
+ * when given, is the value an empty field becomes (absent otherwise).
+ * `resumeOffset`: data rows ending at or before it are read (for the
+ * header) but not yielded, since the header itself must always be read.
+ */
+export async function* csvDocuments(chunks, { types = null, emptyAs = undefined, resumeOffset = 0 } = {}) {
+    const pull = chunks[Symbol.asyncIterator]();
+    let buf = Buffer.alloc(0);
+    let bufBase = 0;
+    let i = 0;
+    let keepFrom = 0;
+    let fieldStart = 0; // the current field's start, another index into buf: more() must shift it too
+    let eof = false;
+
+    async function more() {
+        if (eof) return false;
+        const { value, done } = await pull.next();
+        if (done) { eof = true; return false; }
+        const drop = keepFrom;
+        buf = Buffer.concat([buf.subarray(drop), value]);
+        bufBase += drop;
+        i -= drop;
+        fieldStart -= drop;
+        keepFrom = 0;
+        return true;
+    }
+    async function peek() {
+        if (i >= buf.length) { if (!(await more())) return -1; }
+        return buf[i];
+    }
+
+    while (buf.length < 3) { if (!(await more())) break; }
+    if (buf.length >= 3 && buf[0] === BOM0 && buf[1] === BOM1 && buf[2] === BOM2) i = 3;
+    keepFrom = i;
+
+    let header = null;
+    let keyTexts = null;  // each header name as its JSON key text, escaped once for the file, not once a row
+    let dataRow = 0;
+    let fields = [];
+    let pieces = [];
+    fieldStart = i;
+    let quoted = false;
+    let openedWithQuote = false;
+
+    // keepFrom tracks fieldStart: nothing before the field in progress is ever needed again, so a
+    // compaction (more()) may drop it, bounding memory to the current field plus one incoming chunk.
+    function startField() { fieldStart = i; keepFrom = i; pieces = []; quoted = false; openedWithQuote = false; }
+    function pushPiece(end) { if (end > fieldStart) pieces.push(Buffer.from(buf.subarray(fieldStart, end))); }
+    function fieldText() { return pieces.length === 0 ? '' : Buffer.concat(pieces).toString('utf8'); }
+
+    function typeOf(name) { return types?.get(name) ?? CsvType.STRING; }
+
+    function finishRow() {
+        const absEnd = bufBase + i;
+        const rowFields = fields;
+        fields = [];
+        if (header === null) { header = rowFields; keyTexts = header.map(jsonStringLiteral); return null; }
+        dataRow++;
+        if (absEnd <= resumeOffset) return null;
+        if (rowFields.length !== header.length) {
+            return { position: dataRow, error: `row has ${rowFields.length} field${rowFields.length === 1 ? '' : 's'}, the header has ${header.length}`, endOffset: absEnd };
+        }
+        const parts = [];
+        const violations = [];
+        for (let k = 0; k < header.length; k++) {
+            const name = header[k];
+            const raw = rowFields[k];
+            if (raw === '') {
+                if (emptyAs !== undefined) parts.push(`${keyTexts[k]}:null`);
+                continue;
+            }
+            const type = typeOf(name);
+            const text = csvFieldJsonText(type, raw);
+            if (text === TYPE_ERROR) { violations.push({ field: name, message: `is not a valid ${type}: ${JSON.stringify(raw)}` }); continue; }
+            parts.push(`${keyTexts[k]}:${text}`);
+        }
+        if (violations.length) return { position: dataRow, error: `row ${dataRow} does not match its declared types`, violations, endOffset: absEnd };
+        return { position: dataRow, raw: Buffer.from(`{${parts.join(',')}}`, 'utf8'), endOffset: absEnd };
+    }
+
+    startField();
+    for (;;) {
+        const c = await peek();
+        if (c === -1) {
+            if (quoted) { yield { position: dataRow + 1, error: `truncated input: an unterminated quoted field at byte ${bufBase + i}`, endOffset: bufBase + i }; return; }
+            pushPiece(i);
+            if (fields.length || pieces.length || openedWithQuote) fields.push(fieldText());
+            if (fields.length) { const r = finishRow(); if (r !== null) yield r; }
+            return;
+        }
+        if (quoted) {
+            if (c === QUOTE) {
+                pushPiece(i); // flush the content before this quote
+                i++;
+                const n = await peek();
+                if (n === QUOTE) { pieces.push(Buffer.from('"')); i++; fieldStart = i; keepFrom = i; continue; }
+                quoted = false;
+                fieldStart = i;
+                keepFrom = i;
+                continue;
+            }
+            i++;
+            continue;
+        }
+        if (c === QUOTE && i === fieldStart && pieces.length === 0) { quoted = true; openedWithQuote = true; i++; fieldStart = i; keepFrom = i; continue; }
+        if (c === COMMA) { pushPiece(i); fields.push(fieldText()); i++; startField(); continue; }
+        if (c === CR) { pushPiece(i); i++; fieldStart = i; keepFrom = i; continue; }
+        if (c === LF) {
+            pushPiece(i); fields.push(fieldText()); i++;
+            const r = finishRow();
+            startField();
+            if (r !== null) yield r;
+            continue;
+        }
+        i++;
+    }
+}