colbin 0.0.0-stage → 0.8.0

package/dist/core.js

@@ -0,0 +1,360 @@
+// The `Codec` handle — INTERNALS.md §16.2.
+//
+// Everything the module can do hangs off one instance, and the instance is
+// what holds the schema. That is the shape the format's recommended delivery
+// already implies: a section is sent once per connection, so the thing that
+// parses it should outlive the message that follows it.
+//
+// # Why the operations are synchronous
+//
+// `Codec.open()` is async because compiling WebAssembly is, and there is no
+// synchronous escape — `new WebAssembly.Module` is blocked on the main thread
+// above 4 KB and this module is 244 KB. Everything after that is not:
+// `new WebAssembly.Instance` over an already-compiled module is synchronous,
+// so `open` instantiates once and every call afterwards is a straight run of
+// wasm calls with no `await` in it.
+//
+// That is what lets one instance back the whole handle rather than the pool
+// `web/src/lib/codec.ts` needed. The pool existed because that file compiled
+// lazily inside each call, so two calls fired with `Promise.all` could both be
+// waiting on `compile()` and then interleave their writes into one instance's
+// `INPUT`. With the compile hoisted into `open`, a call cannot be preempted
+// between writing its input and reading its output, because there is nothing
+// in it to preempt.
+import { ColbinError } from "./errors.js";
+import { readRows, readColumns } from "./materialize.js";
+/** Encode flags, mirroring `colbin::build`. */
+const SELF_DESCRIBING = 1;
+const VERIFY = 2;
+/** Byte 0 of a message, with bit 2 set, says the section is in front of the
+ * body. See `rust/wasm/src/lib.rs` and ENCODER.md. */
+const ROOT_SCHEMA_BIT = 0x04;
+const ROOT_FIRST = 0xd0;
+const ROOT_LAST = 0xdf;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * The handle. One WebAssembly instance, the schema it holds, and the module's
+ * whole surface.
+ *
+ * Construct it with `Codec.open()` from whichever entry point suits — `colbin`
+ * carries the module inline, `colbin/asset` resolves it as a URL beside
+ * itself.
+ */
+export class Codec {
+    #exports;
+    /** The section last written into this instance, by identity. Holding it is
+     * what keeps a handle from re-parsing the same section once per message. */
+    #applied = null;
+    #held = null;
+    #lastPath = 'json';
+    constructor(exports) {
+        this.#exports = exports;
+    }
+    /**
+     * Compiles the module and instantiates it. Async because compiling
+     * WebAssembly is; nothing after it is.
+     */
+    static async open(options = {}) {
+        const module = options.module ?? (await compile(options.wasm));
+        return Codec.fromModule(module);
+    }
+    /** A second handle over an already-compiled module — its own instance, its
+     * own schema, no compile. */
+    static fromModule(module) {
+        // No imports: the module does not abort, and a missing import would be a
+        // link error rather than a trap on first use.
+        const instance = new WebAssembly.Instance(module, {});
+        return new Codec(instance.exports);
+    }
+    /**
+     * Holds a schema section for the messages that follow — the delivery the
+     * format recommends, where the section is sent once per connection and every
+     * message after it carries only its body. `null` clears it.
+     *
+     * A self-describing message ignores this and uses its own.
+     */
+    setSchema(section) {
+        this.#held = section && section.length > 0 ? section : null;
+    }
+    /** Which path the last {@link unmarshal} took: a caller that wants to know
+     * it landed on the slow one should not have to guess. */
+    get lastPath() {
+        return this.#lastPath;
+    }
+    /**
+     * A message to real objects, without JSON text in the middle when the shape
+     * allows it.
+     *
+     * The fast path is the one that is exact past 2^53: a column whose values do
+     * not fit a `Number` comes back as `bigint`, where the JSON fallback goes
+     * through `JSON.parse` and rounds like any other JSON reader would.
+     * {@link lastPath} says which ran.
+     */
+    unmarshal(message, options = {}) {
+        const e = this.#exports;
+        this.#schema(options.section);
+        // A module built without `materialize` has no fast path to try, and that
+        // is not an error — the text path answers every shape. Treated exactly
+        // like the materializer declining the shape.
+        const length = this.canMaterialize ? this.#call(e.materialize(this.#write(message))) : 0;
+        if (length > 0) {
+            this.#lastPath = 'materialize';
+            // A copy this call owns outright, not a live view: `readRows` builds
+            // several typed-array views over it, and any later `alloc` that grows
+            // the module's memory would detach every one of them.
+            const at = e.result_ptr();
+            return readRows(e.memory.buffer.slice(at, at + length), options);
+        }
+        // Not the table shape the materializer covers — the text path.
+        this.#lastPath = 'json';
+        return JSON.parse(this.toJSONText(message, options));
+    }
+    /**
+     * The columns themselves, for a caller feeding a grid or a chart that never
+     * wants row objects — it skips even the 7 µs the row build costs.
+     *
+     * Returns `null` when the message is not the table shape the fast path covers, since
+     * there is no honest column view of a nested document; such a caller should
+     * fall back to {@link unmarshal}.
+     */
+    columns(message, options = {}) {
+        const e = this.#exports;
+        this.#needs('materialize', 'materialize', 'rebuild the module with --features materialize');
+        this.#schema(options.section);
+        const length = this.#call(e.materialize(this.#write(message)));
+        if (length === 0)
+            return null;
+        const at = e.result_ptr();
+        return readColumns(e.memory.buffer.slice(at, at + length));
+    }
+    /** A message back to JSON text. Every shape, and the only path for the ones
+     * {@link unmarshal} reports as `json`. */
+    toJSONText(message, options = {}) {
+        const e = this.#exports;
+        this.#schema(options.section);
+        const length = this.#call(e.decode(this.#write(message)));
+        return decoder.decode(this.#result(length));
+    }
+    /**
+     * A value or JSON text to a colbin message.
+     *
+     * A string is taken as JSON text and handed to the module as it stands;
+     * anything else goes through `JSON.stringify` first — which means an integer
+     * past 2^53 must arrive as text, since by the time it is a JavaScript
+     * `Number` it has already been rounded.
+     */
+    marshal(value, options = {}) {
+        const e = this.#exports;
+        this.#needs('encode', 'encode', 'rebuild the module with --features encode');
+        const text = typeof value === 'string' ? value : JSON.stringify(value);
+        const flags = options.verify ? VERIFY : 0;
+        const length = this.#call(e.encode(this.#write(encoder.encode(text)), flags));
+        const message = this.#result(length);
+        const section = this.#result(this.#call(e.section()));
+        // Warnings ride in the same envelope as errors, and reading them
+        // overwrites the output — so both copies are already taken above.
+        const warnings = this.#diagnostic().warnings;
+        let standalone;
+        return {
+            message,
+            section,
+            warnings,
+            get standalone() {
+                // The self-describing form is the same body behind the same section,
+                // with bit 2 of the root byte set — so it is composed here rather than
+                // encoded a second time. `js/tests/package.test.mjs` asserts this
+                // against what the module writes for `SELF_DESCRIBING` over the whole
+                // corpus, which is what makes the shortcut checkable rather than
+                // merely plausible.
+                if (standalone)
+                    return standalone;
+                // A typed narrow message has no root byte unless its key run begins in
+                // the root range, so the root is the message's own first byte only then.
+                const rooted = message.length > 0 && message[0] >= ROOT_FIRST && message[0] <= ROOT_LAST;
+                const body = rooted ? message.subarray(1) : message;
+                const out = new Uint8Array(1 + section.length + body.length);
+                out[0] = (rooted ? message[0] : ROOT_FIRST) | ROOT_SCHEMA_BIT;
+                out.set(section, 1);
+                out.set(body, 1 + section.length);
+                standalone = out;
+                return out;
+            },
+        };
+    }
+    /**
+     * The field tree of a message, with every node's byte span — absolute
+     * offsets into the bytes handed in, so a hex view needs no arithmetic.
+     *
+     * Needs a module built with the `inspect` feature, which is **not** the one
+     * `colbin` and `colbin/asset` carry: the span walk is 15 KB that nothing but
+     * a tool drawing the bytes ever calls, so it has a module of its own behind
+     * `colbin/inspect`.
+     */
+    inspect(message, options = {}) {
+        const e = this.#exports;
+        this.#needs('inspect_message', 'inspect', "import { Codec } from 'colbin/inspect'");
+        this.#schema(options.section);
+        const length = this.#call(e.inspect_message(this.#write(message)));
+        return JSON.parse(decoder.decode(this.#result(length)));
+    }
+    /** Whether this handle's module can {@link inspect} — i.e. whether it came
+     * from `colbin/inspect` or another build with the feature on. */
+    get canInspect() {
+        return typeof this.#exports.inspect_message === 'function';
+    }
+    /** Whether this handle's module carries the fast path. True of every build
+     * this package ships; false only for a module a caller supplied. */
+    get canMaterialize() {
+        return typeof this.#exports.materialize === 'function';
+    }
+    /** The flag the encoder needs to write a document that carries its own
+     * schema, for a caller composing `encode` flags directly. */
+    static get SELF_DESCRIBING() {
+        return SELF_DESCRIBING;
+    }
+    // --- the boundary ------------------------------------------------------
+    /**
+     * Writes `input` into the module and returns its length, which is what every
+     * export takes. Allocate first and take the view second: allocating may grow
+     * memory, and growing detaches every view taken before it.
+     */
+    #write(input) {
+        const e = this.#exports;
+        const at = e.alloc(input.length);
+        new Uint8Array(e.memory.buffer).set(input, at);
+        return input.length;
+    }
+    /** A copy of the module's last output. */
+    #result(length) {
+        const e = this.#exports;
+        const at = e.result_ptr();
+        return new Uint8Array(e.memory.buffer).slice(at, at + length);
+    }
+    /**
+     * Refuses a call the module was not built to answer, by name, before it
+     * becomes a `TypeError: e.inspect_message is not a function` several frames
+     * from anything a caller can act on.
+     *
+     * Which exports exist is a property of the bytes, not of this wrapper: the
+     * module is built per feature set (`rust/wasm/Cargo.toml`), and the entries
+     * differ in which build they carry.
+     */
+    #needs(exported, feature, fix) {
+        if (typeof this.#exports[exported] === 'function')
+            return;
+        throw new Error(`colbin: this module was built without \`${feature}\`, so it has no ` +
+            `\`${exported}\` export. ${fix}`);
+    }
+    /** Turns the ABI's negative length into the thrown `ColbinError`. */
+    #call(length) {
+        if (length < 0)
+            throw new ColbinError(this.#diagnostic());
+        return length;
+    }
+    #diagnostic() {
+        const e = this.#exports;
+        return JSON.parse(decoder.decode(this.#result(e.last_error())));
+    }
+    /**
+     * Makes this instance hold `section` — the per-call one when there is one,
+     * the handle's own otherwise.
+     *
+     * Compared by identity, not by content: re-parsing a section the instance
+     * already holds is exactly the cost a handle exists to avoid, and
+     * a caller who mutates a section's bytes in place and passes the same object
+     * again is not a case worth a memcmp per message.
+     */
+    #schema(section) {
+        const want = section && section.length > 0 ? section : this.#held;
+        if (want === this.#applied)
+            return;
+        const e = this.#exports;
+        this.#call(want === null ? e.set_schema(0) : e.set_schema(this.#write(want)));
+        this.#applied = want;
+    }
+}
+/** Turns whatever `open` was given into a compiled module. */
+async function compile(source) {
+    if (source === undefined) {
+        throw new TypeError('colbin: no module to compile — pass `wasm` or `module` to Codec.open(), ' +
+            "or import an entry that carries one ('colbin' or 'colbin/asset')");
+    }
+    const resolved = await source;
+    if (resolved instanceof WebAssembly.Module)
+        return resolved;
+    if (typeof resolved === 'string' || resolved instanceof URL) {
+        return compileResponse(await fetch(resolved));
+    }
+    if (typeof Response !== 'undefined' && resolved instanceof Response) {
+        return compileResponse(resolved);
+    }
+    return WebAssembly.compile(resolved);
+}
+async function compileResponse(response) {
+    if (!response.ok) {
+        throw new Error(`colbin: ${response.url || 'the module'} answered ${response.status}`);
+    }
+    // `compileStreaming` needs the right content type and some static hosts do
+    // not set it, so fall back on the header rather than fail on it.
+    if (typeof WebAssembly.compileStreaming === 'function' &&
+        response.headers.get('content-type')?.includes('application/wasm')) {
+        return WebAssembly.compileStreaming(response);
+    }
+    return WebAssembly.compile(await response.arrayBuffer());
+}
+/**
+ * The `Codec` an entry point exports: `open()` with the entry's own way of
+ * finding the module already wired in, overridable per call.
+ *
+ * Compiled once per entry and cached, so a page that opens a second handle
+ * pays for an instance and not for a compile.
+ */
+export function codecFor(source) {
+    let compiled;
+    const module = () => (compiled ??= compile(source()));
+    return {
+        async open(options = {}) {
+            if (options.module)
+                return Codec.fromModule(options.module);
+            if (options.wasm !== undefined)
+                return Codec.open(options);
+            return Codec.fromModule(await module());
+        },
+        fromModule: Codec.fromModule,
+        preload() {
+            void module().catch(() => { });
+        },
+    };
+}
+/**
+ * The free functions each entry re-exports — `unmarshal(bytes)` without
+ * holding a handle, for the caller who has one message to read and no
+ * connection to hold a schema for.
+ *
+ * They share one lazily-opened codec rather than opening a fresh one per call:
+ * a fresh instance per message is what the handle exists to avoid, and none of these
+ * hold a schema across calls, so there is nothing for the sharing to leak.
+ */
+export function convenience(entry) {
+    let held;
+    const codec = () => (held ??= entry.open());
+    return {
+        async unmarshal(message, options) {
+            return (await codec()).unmarshal(message, options);
+        },
+        async columns(message, options) {
+            return (await codec()).columns(message, options);
+        },
+        async toJSONText(message, options) {
+            return (await codec()).toJSONText(message, options);
+        },
+        async marshal(value, options) {
+            return (await codec()).marshal(value, options);
+        },
+        async inspect(message, options) {
+            return (await codec()).inspect(message, options);
+        },
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The one failure type. INTERNALS.md §16.2: a thrown error rather than an
+ * `Outcome` union, because a library consumer's normal path is success and a
+ * page that wants a union can wrap this in three lines.
+ *
+ * Every field the module's diagnostic carries survives onto the error, so a
+ * caller can point at the byte that failed rather than re-deriving it from a
+ * message string.
+ */
+export declare class ColbinError extends Error {
+    /** The module's diagnostic code. `2` is the wire-level refusal every
+     * decode-only build can still produce; the encoder's parser uses its own. */
+    readonly code: number;
+    /** Byte offset into the input the failure was found at, or -1. */
+    readonly offset: number;
+    /** 1-based line, for a failure in JSON text, or -1. */
+    readonly line: number;
+    /** The path through the document — `records[3].price` — or `''`. */
+    readonly path: string;
+    /** Warnings the module gathered before it gave up. Usually empty. */
+    readonly warnings: string[];
+    constructor(diagnostic: Diagnostic);
+}
+/** The JSON envelope `colbin::diag::Diag::encode` writes. */
+export type Diagnostic = {
+    code: number;
+    offset: number;
+    line: number;
+    path: string;
+    message: string;
+    warnings: string[];
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC;iFAC6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;gBAEf,UAAU,EAAE,UAAU;CASnC;AAED,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA"}

package/dist/errors.js

@@ -0,0 +1,32 @@
+/**
+ * The one failure type. INTERNALS.md §16.2: a thrown error rather than an
+ * `Outcome` union, because a library consumer's normal path is success and a
+ * page that wants a union can wrap this in three lines.
+ *
+ * Every field the module's diagnostic carries survives onto the error, so a
+ * caller can point at the byte that failed rather than re-deriving it from a
+ * message string.
+ */
+export class ColbinError extends Error {
+    /** The module's diagnostic code. `2` is the wire-level refusal every
+     * decode-only build can still produce; the encoder's parser uses its own. */
+    code;
+    /** Byte offset into the input the failure was found at, or -1. */
+    offset;
+    /** 1-based line, for a failure in JSON text, or -1. */
+    line;
+    /** The path through the document — `records[3].price` — or `''`. */
+    path;
+    /** Warnings the module gathered before it gave up. Usually empty. */
+    warnings;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.name = 'ColbinError';
+        this.code = diagnostic.code;
+        this.offset = diagnostic.offset;
+        this.line = diagnostic.line;
+        this.path = diagnostic.path;
+        this.warnings = diagnostic.warnings ?? [];
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC;iFAC6E;IACpE,IAAI,CAAQ;IACrB,kEAAkE;IACzD,MAAM,CAAQ;IACvB,uDAAuD;IAC9C,IAAI,CAAQ;IACrB,oEAAoE;IAC3D,IAAI,CAAQ;IACrB,qEAAqE;IAC5D,QAAQ,CAAU;IAE3B,YAAY,UAAsB;QAChC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAA;QACzB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAA;QAC3B,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAA;QAC/B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAA;QAC3B,IAAI,CAAC,QAAQ,GAAG,UAAU,CAAC,QAAQ,IAAI,EAAE,CAAA;IAC3C,CAAC;CACF"}