@earendil-works/chord 1.4.0 → 1.5.1

package/dist/store/live-query.js

@@ -0,0 +1,254 @@
+// Live queries (decision "Live queries over an object's own tables"): `self.query(table, q, limit)`, a JSON watchable
+// of a query's rows over a table of the object itself. Run once before the object goes live, then again inside the
+// commit step of every commit of the object that wrote the table (after its writes, so it sees them) and published in
+// that commit's batch as the diff from the previous rows (W1). Only the object writes its tables, so its commits are
+// the exact invalidation; a commit writing no table with a live query runs none.
+import { ChordError } from "../data/index.js";
+import { invalid } from "../data/internal.js";
+import { diffRevisions } from "../delta/index.js";
+import { handedOut, Source } from "../state/internal.js";
+import { chordMetrics } from "../telemetry.js";
+/**
+ * Refuses what the types cannot (plugin code is bundled without type checks; declaration policy): a query of another
+ * table than `table`, and a `limit` that is no positive integer (a live query must be bounded: one run per commit
+ * that writes its table reads at most `limit` rows).
+ */
+export function checkLiveQuery(table, q, limit, label) {
+    if (q.table !== table) {
+        throw invalid("args", `${label}: self.query: a query of table "${q.table.name}" over "${table.name}"`);
+    }
+    if (!Number.isSafeInteger(limit) || limit < 1) {
+        throw invalid("args", `${label}: self.query: a limit is required, a positive integer`);
+    }
+}
+/** The live queries of one object by table (its SQL name), across its attempts: what its commits re-run. */
+export class LiveQueries {
+    #byTable = new Map();
+    /** Adds `query` (its attempt declared it): re-run by every commit writing its table from now on. */
+    add(query) {
+        const table = query.handle.sql.table;
+        let queries = this.#byTable.get(table);
+        if (queries === undefined) {
+            queries = new Set();
+            this.#byTable.set(table, queries);
+        }
+        queries.add(query);
+    }
+    /** Removes `query` (its attempt ended). */
+    delete(query) {
+        const table = query.handle.sql.table;
+        const queries = this.#byTable.get(table);
+        if (queries === undefined)
+            return;
+        queries.delete(query);
+        if (queries.size === 0)
+            this.#byTable.delete(table);
+    }
+    /** The live queries over `table`, if any. */
+    on(table) {
+        return this.#byTable.get(table);
+    }
+}
+/**
+ * The re-run of the live queries over the tables a transaction writes (`handles`), `undefined` when none has one (the
+ * common case: a map lookup per written table, nothing more). `context` is the transaction's: the runs count through it.
+ */
+export function refreshOf(handles, context) {
+    let queries;
+    for (const handle of handles) {
+        const on = handle.owner.queries.on(handle.sql.table);
+        if (on === undefined)
+            continue;
+        queries ??= new Set();
+        for (const query of on)
+            queries.add(query);
+    }
+    return queries === undefined ? undefined : new QueryRefresh([...queries], context);
+}
+const NO_WRITES = [];
+/**
+ * The re-run of live queries in one commit: `write` reads them in the commit step after the commit's own writes (the
+ * last write of the last phase), and `adopt` publishes their rows in the commit's batch; a refused step adopts nothing.
+ * A transaction stages it as its own change (`Staged`).
+ */
+export class QueryRefresh {
+    #queries;
+    #context;
+    #runs = [];
+    /** The staged write that reads the queries; it writes nothing and records nothing in the outbox. */
+    write;
+    constructor(queries, context) {
+        this.#queries = queries;
+        this.#context = context;
+        this.write = { order: "write", apply: (step) => this.#rerun(step) };
+    }
+    async #rerun(step) {
+        // A grouped commit that rolled back applies again alone (store.ts): only the last application's runs count.
+        this.#runs.length = 0;
+        for (const query of this.#queries)
+            this.#runs.push(await query.rerun(step, this.#context));
+        return NO_WRITES;
+    }
+    /** Publishes each query's new rows (or its failure), inside the commit's batch. */
+    adopt() {
+        for (const [index, query] of this.#queries.entries())
+            query.adopt(this.#runs[index]);
+    }
+    committed() { }
+    discarded() { }
+}
+/** What the watches of a failed live query had: no rows, so its next rows replace the value whole. */
+const NO_VALUE = Symbol("no value");
+const NO_ROWS = new Map();
+/**
+ * A live query: the rows of `query` (at most `limit`, in its order) over its object's table `handle`, as a JSON source
+ * (a state member, a derive source, an `on` source). Its statement is compiled once; each run decodes only the rows
+ * whose stored columns changed and keeps the others the same objects, so its frame, the diff from the rows its watches
+ * had, compares unchanged rows by identity (a window shifted by one row: one insert and one removal, not a comparison
+ * of every row with every other).
+ */
+export class LiveQuery extends Source {
+    handle;
+    #owner;
+    #statement;
+    #state = { kind: "loading" };
+    /** The last adopted rows by key, with the stored rows they were decoded from (the next run reuses unchanged ones). */
+    #byKey = NO_ROWS;
+    /** The rows this query's watches have, kept from its adoption to its frame in the batch; `undefined`: not listed. */
+    #framed;
+    /** Commits adopted so far: an activation run that a commit overtook keeps the commit's newer rows. */
+    #adopted = 0;
+    /** Set from a failed run until the next good one: a failure episode is reported once. */
+    #failing = false;
+    constructor(handle, query, limit, owner, batch) {
+        super(batch);
+        this.handle = handle;
+        this.#owner = owner;
+        this.#statement = handle.sql.select(query.condition, query.order, undefined, limit);
+    }
+    get value() {
+        const state = this.#state;
+        if (state.kind === "rows")
+            return state.value;
+        if (state.kind === "loading") {
+            throw new ChordError({ code: "not_ready", message: `${this.#owner.label}: a live query read before it ran` });
+        }
+        throw state.error;
+    }
+    /** Its rows, or while failed its failure and last good rows (a detached query throws). */
+    start() {
+        const state = this.#state;
+        if (state.kind === "failed")
+            return { kind: "failed", error: state.error, last: state.last };
+        return { kind: "value", value: this.value };
+    }
+    /**
+     * The first run, before its object goes live (activation, after its tables are prepared): a failure throws and fails
+     * the activation. Rows a commit adopted meanwhile are newer and stay.
+     */
+    async load(context) {
+        const adopted = this.#adopted;
+        this.#count(context);
+        const { sql, params } = this.#statement;
+        const stored = await this.handle.store.read((executor) => executor.all(sql, ...params), context);
+        // Decoded outside the store's read: a row the code cannot read is this query's failure, not the backend's.
+        const rows = this.#decode(stored, context);
+        if (this.#adopted !== adopted)
+            return;
+        this.#byKey = rows.byKey;
+        this.#state = { kind: "rows", value: rows.value };
+    }
+    /** A run inside the commit step `step`, after its writes: the rows, or the failure; it never throws. */
+    async rerun(step, context) {
+        try {
+            this.#count(context);
+            const { sql, params } = this.#statement;
+            return { kind: "rows", rows: this.#decode(await step.all(sql, ...params), context) };
+        }
+        catch (error) {
+            return { kind: "failed", error };
+        }
+    }
+    /**
+     * Takes a commit's run, inside its batch: listed for a frame when watched, its dependents marked. A failed run makes
+     * the query a failed member (as a throwing derive): its watches get one failure call, the owner a report per
+     * failure episode; the next good run replaces the value whole.
+     */
+    adopt(run) {
+        const state = this.#state;
+        if (state.kind === "detached")
+            return;
+        this.#adopted++;
+        if (this.watched && this.#framed === undefined)
+            this.#framed = state.kind === "rows" ? state.value : NO_VALUE;
+        if (run.kind === "rows") {
+            this.#failing = false;
+            this.#byKey = run.rows.byKey;
+            this.#state = { kind: "rows", value: run.rows.value };
+        }
+        else {
+            if (!this.#failing)
+                this.#owner.report(handedOut(run.error));
+            this.#failing = true;
+            const last = state.kind === "rows" ? state.value : state.kind === "failed" ? state.last : undefined;
+            this.#state = { kind: "failed", error: run.error, last };
+        }
+        this.changed();
+    }
+    /** Delivers the frame: the diff from the rows its watches had, or one failure call when they had rows. */
+    deliver(context) {
+        const before = this.#framed;
+        this.#framed = undefined;
+        const state = this.#state;
+        if (state.kind === "rows") {
+            // Listed by `adopt`, so `before` was kept (a detach in the batch leaves no rows).
+            const after = state.value;
+            const ops = before === NO_VALUE ? [["r", after]] : diffRevisions(before, after);
+            if (ops.length > 0)
+                this.publish(after, ops, false, context);
+            return;
+        }
+        // Still failed since the last call: nothing new for the watches.
+        if (state.kind === "failed" && before !== NO_VALUE)
+            this.failWatches(state.error, context);
+    }
+    /** Its attempt ended: no commit re-runs it, reads throw `error` (the object's), its watches end `ended`. */
+    detach(error) {
+        this.handle.owner.queries.delete(this);
+        this.#state = { kind: "detached", error };
+        this.#framed = undefined;
+        this.endWatches();
+    }
+    /** One run, counted where it happens (the cost guard: a commit not writing the table runs none). */
+    #count(context) {
+        chordMetrics(context.telemetry.metrics).counter("chord.query.runs").add(1);
+    }
+    /**
+     * The rows of `stored`: a row whose stored columns are all the same as in the last adopted run is that run's object
+     * (one comparison per physical column), any other is decoded.
+     */
+    #decode(stored, context) {
+        const { key, rows } = this.handle.definition;
+        const value = [];
+        const byKey = new Map();
+        for (const each of stored) {
+            const id = key.length === 1 ? each[key[0]] : JSON.stringify(key.map((column) => each[column]));
+            const before = this.#byKey.get(id);
+            const row = before !== undefined && sameStored(before.stored, each, rows.physical)
+                ? before.row
+                : // A table's rows hold its columns' values: scalars and JSON.
+                    rows.decode(each, context);
+            value.push(row);
+            byKey.set(id, { stored: each, row });
+        }
+        return { value, byKey };
+    }
+}
+/** Whether two stored rows have the same value in every physical column (SQLite values compare by `===`). */
+function sameStored(a, b, physical) {
+    for (const column of physical)
+        if (a[column] !== b[column])
+            return false;
+    return true;
+}
+//# sourceMappingURL=live-query.js.map

package/dist/store/live-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"live-query.js","sourceRoot":"","sources":["../../src/store/live-query.ts"],"names":[],"mappings":"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","sourcesContent":["// Live queries (decision \"Live queries over an object's own tables\"): `self.query(table, q, limit)`, a JSON watchable\n// of a query's rows over a table of the object itself. Run once before the object goes live, then again inside the\n// commit step of every commit of the object that wrote the table (after its writes, so it sees them) and published in\n// that commit's batch as the diff from the previous rows (W1). Only the object writes its tables, so its commits are\n// the exact invalidation; a commit writing no table with a live query runs none.\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport { diffRevisions, type Op } from \"../delta/index.ts\";\nimport type { JsonValue } from \"../json.ts\";\nimport type { SqliteValue } from \"../sqlite/index.ts\";\nimport { type Batch, handedOut, Source, type WatchStart } from \"../state/internal.ts\";\nimport { chordMetrics } from \"../telemetry.ts\";\nimport type { Query } from \"./query.ts\";\nimport type { Statement } from \"./sql.ts\";\nimport type { StagedWrite, Step } from \"./step.ts\";\nimport type { TableDefinition } from \"./table.ts\";\nimport type { TableHandle } from \"./table-handle.ts\";\nimport type { StoreWrite } from \"./writes.ts\";\n\n/** Who a live query belongs to: its object, and where its failures after activation are reported (`query_failed`). */\nexport type QueryOwner = {\n\treadonly label: string;\n\treport(error: unknown): void;\n};\n\n/**\n * The rows of one run: in order, and by key with the stored row each was decoded from, which the next run compares\n * against to keep an unchanged row the same object.\n */\ntype Rows = { readonly value: JsonValue[]; readonly byKey: ReadonlyMap<unknown, Decoded> };\n\n/** A row as a run decoded it, with the stored row it came from. */\ntype Decoded = { readonly stored: StoredRow; readonly row: JsonValue };\n\n/** One run of a live query in a commit step: its rows, or why it could not read them. */\ntype QueryRun = { readonly kind: \"rows\"; readonly rows: Rows } | { readonly kind: \"failed\"; readonly error: unknown };\n\n/**\n * Where a live query stands: before its first run (activation), with rows, failed (its last run threw; its last good\n * rows kept for a watch opened meanwhile), or detached (its attempt ended).\n */\ntype QueryState =\n\t| { readonly kind: \"loading\" }\n\t| { readonly kind: \"rows\"; readonly value: JsonValue[] }\n\t| { readonly kind: \"failed\"; readonly error: unknown; readonly last: JsonValue[] | undefined }\n\t| { readonly kind: \"detached\"; readonly error: unknown };\n\n/** A stored row as the backend returns it. */\ntype StoredRow = { readonly [column: string]: SqliteValue };\n\n/**\n * Refuses what the types cannot (plugin code is bundled without type checks; declaration policy): a query of another\n * table than `table`, and a `limit` that is no positive integer (a live query must be bounded: one run per commit\n * that writes its table reads at most `limit` rows).\n */\nexport function checkLiveQuery(table: TableDefinition, q: Query, limit: unknown, label: string): void {\n\tif (q.table !== table) {\n\t\tthrow invalid(\"args\", `${label}: self.query: a query of table \"${q.table.name}\" over \"${table.name}\"`);\n\t}\n\tif (!Number.isSafeInteger(limit) || (limit as number) < 1) {\n\t\tthrow invalid(\"args\", `${label}: self.query: a limit is required, a positive integer`);\n\t}\n}\n\n/** The live queries of one object by table (its SQL name), across its attempts: what its commits re-run. */\nexport class LiveQueries {\n\treadonly #byTable = new Map<string, Set<LiveQuery>>();\n\n\t/** Adds `query` (its attempt declared it): re-run by every commit writing its table from now on. */\n\tadd(query: LiveQuery): void {\n\t\tconst table = query.handle.sql.table;\n\t\tlet queries = this.#byTable.get(table);\n\t\tif (queries === undefined) {\n\t\t\tqueries = new Set();\n\t\t\tthis.#byTable.set(table, queries);\n\t\t}\n\t\tqueries.add(query);\n\t}\n\n\t/** Removes `query` (its attempt ended). */\n\tdelete(query: LiveQuery): void {\n\t\tconst table = query.handle.sql.table;\n\t\tconst queries = this.#byTable.get(table);\n\t\tif (queries === undefined) return;\n\t\tqueries.delete(query);\n\t\tif (queries.size === 0) this.#byTable.delete(table);\n\t}\n\n\t/** The live queries over `table`, if any. */\n\ton(table: string): ReadonlySet<LiveQuery> | undefined {\n\t\treturn this.#byTable.get(table);\n\t}\n}\n\n/**\n * The re-run of the live queries over the tables a transaction writes (`handles`), `undefined` when none has one (the\n * common case: a map lookup per written table, nothing more). `context` is the transaction's: the runs count through it.\n */\nexport function refreshOf(handles: Iterable<TableHandle>, context: Context): QueryRefresh | undefined {\n\tlet queries: Set<LiveQuery> | undefined;\n\tfor (const handle of handles) {\n\t\tconst on = handle.owner.queries.on(handle.sql.table);\n\t\tif (on === undefined) continue;\n\t\tqueries ??= new Set();\n\t\tfor (const query of on) queries.add(query);\n\t}\n\treturn queries === undefined ? undefined : new QueryRefresh([...queries], context);\n}\n\nconst NO_WRITES: readonly StoreWrite[] = [];\n\n/**\n * The re-run of live queries in one commit: `write` reads them in the commit step after the commit's own writes (the\n * last write of the last phase), and `adopt` publishes their rows in the commit's batch; a refused step adopts nothing.\n * A transaction stages it as its own change (`Staged`).\n */\nexport class QueryRefresh {\n\treadonly #queries: readonly LiveQuery[];\n\treadonly #context: Context;\n\treadonly #runs: QueryRun[] = [];\n\t/** The staged write that reads the queries; it writes nothing and records nothing in the outbox. */\n\treadonly write: StagedWrite;\n\n\tconstructor(queries: readonly LiveQuery[], context: Context) {\n\t\tthis.#queries = queries;\n\t\tthis.#context = context;\n\t\tthis.write = { order: \"write\", apply: (step) => this.#rerun(step) };\n\t}\n\n\tasync #rerun(step: Step): Promise<readonly StoreWrite[]> {\n\t\t// A grouped commit that rolled back applies again alone (store.ts): only the last application's runs count.\n\t\tthis.#runs.length = 0;\n\t\tfor (const query of this.#queries) this.#runs.push(await query.rerun(step, this.#context));\n\t\treturn NO_WRITES;\n\t}\n\n\t/** Publishes each query's new rows (or its failure), inside the commit's batch. */\n\tadopt(): void {\n\t\tfor (const [index, query] of this.#queries.entries()) query.adopt(this.#runs[index]!);\n\t}\n\n\tcommitted(): void {}\n\n\tdiscarded(): void {}\n}\n\n/** What the watches of a failed live query had: no rows, so its next rows replace the value whole. */\nconst NO_VALUE: unique symbol = Symbol(\"no value\");\n\nconst NO_ROWS: ReadonlyMap<unknown, Decoded> = new Map();\n\n/**\n * A live query: the rows of `query` (at most `limit`, in its order) over its object's table `handle`, as a JSON source\n * (a state member, a derive source, an `on` source). Its statement is compiled once; each run decodes only the rows\n * whose stored columns changed and keeps the others the same objects, so its frame, the diff from the rows its watches\n * had, compares unchanged rows by identity (a window shifted by one row: one insert and one removal, not a comparison\n * of every row with every other).\n */\nexport class LiveQuery extends Source {\n\treadonly handle: TableHandle;\n\treadonly #owner: QueryOwner;\n\treadonly #statement: Statement;\n\t#state: QueryState = { kind: \"loading\" };\n\t/** The last adopted rows by key, with the stored rows they were decoded from (the next run reuses unchanged ones). */\n\t#byKey: ReadonlyMap<unknown, Decoded> = NO_ROWS;\n\t/** The rows this query's watches have, kept from its adoption to its frame in the batch; `undefined`: not listed. */\n\t#framed: JsonValue[] | typeof NO_VALUE | undefined;\n\t/** Commits adopted so far: an activation run that a commit overtook keeps the commit's newer rows. */\n\t#adopted = 0;\n\t/** Set from a failed run until the next good one: a failure episode is reported once. */\n\t#failing = false;\n\n\tconstructor(handle: TableHandle, query: Query, limit: number, owner: QueryOwner, batch: Batch) {\n\t\tsuper(batch);\n\t\tthis.handle = handle;\n\t\tthis.#owner = owner;\n\t\tthis.#statement = handle.sql.select(query.condition, query.order, undefined, limit);\n\t}\n\n\tget value(): JsonValue[] {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"rows\") return state.value;\n\t\tif (state.kind === \"loading\") {\n\t\t\tthrow new ChordError({ code: \"not_ready\", message: `${this.#owner.label}: a live query read before it ran` });\n\t\t}\n\t\tthrow state.error;\n\t}\n\n\t/** Its rows, or while failed its failure and last good rows (a detached query throws). */\n\toverride start(): WatchStart {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"failed\") return { kind: \"failed\", error: state.error, last: state.last };\n\t\treturn { kind: \"value\", value: this.value };\n\t}\n\n\t/**\n\t * The first run, before its object goes live (activation, after its tables are prepared): a failure throws and fails\n\t * the activation. Rows a commit adopted meanwhile are newer and stay.\n\t */\n\tasync load(context: Context): Promise<void> {\n\t\tconst adopted = this.#adopted;\n\t\tthis.#count(context);\n\t\tconst { sql, params } = this.#statement;\n\t\tconst stored = await this.handle.store.read((executor) => executor.all<StoredRow>(sql, ...params), context);\n\t\t// Decoded outside the store's read: a row the code cannot read is this query's failure, not the backend's.\n\t\tconst rows = this.#decode(stored, context);\n\t\tif (this.#adopted !== adopted) return;\n\t\tthis.#byKey = rows.byKey;\n\t\tthis.#state = { kind: \"rows\", value: rows.value };\n\t}\n\n\t/** A run inside the commit step `step`, after its writes: the rows, or the failure; it never throws. */\n\tasync rerun(step: Step, context: Context): Promise<QueryRun> {\n\t\ttry {\n\t\t\tthis.#count(context);\n\t\t\tconst { sql, params } = this.#statement;\n\t\t\treturn { kind: \"rows\", rows: this.#decode(await step.all<StoredRow>(sql, ...params), context) };\n\t\t} catch (error) {\n\t\t\treturn { kind: \"failed\", error };\n\t\t}\n\t}\n\n\t/**\n\t * Takes a commit's run, inside its batch: listed for a frame when watched, its dependents marked. A failed run makes\n\t * the query a failed member (as a throwing derive): its watches get one failure call, the owner a report per\n\t * failure episode; the next good run replaces the value whole.\n\t */\n\tadopt(run: QueryRun): void {\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"detached\") return;\n\t\tthis.#adopted++;\n\t\tif (this.watched && this.#framed === undefined) this.#framed = state.kind === \"rows\" ? state.value : NO_VALUE;\n\t\tif (run.kind === \"rows\") {\n\t\t\tthis.#failing = false;\n\t\t\tthis.#byKey = run.rows.byKey;\n\t\t\tthis.#state = { kind: \"rows\", value: run.rows.value };\n\t\t} else {\n\t\t\tif (!this.#failing) this.#owner.report(handedOut(run.error));\n\t\t\tthis.#failing = true;\n\t\t\tconst last = state.kind === \"rows\" ? state.value : state.kind === \"failed\" ? state.last : undefined;\n\t\t\tthis.#state = { kind: \"failed\", error: run.error, last };\n\t\t}\n\t\tthis.changed();\n\t}\n\n\t/** Delivers the frame: the diff from the rows its watches had, or one failure call when they had rows. */\n\tdeliver(context: Context): void {\n\t\tconst before = this.#framed;\n\t\tthis.#framed = undefined;\n\t\tconst state = this.#state;\n\t\tif (state.kind === \"rows\") {\n\t\t\t// Listed by `adopt`, so `before` was kept (a detach in the batch leaves no rows).\n\t\t\tconst after = state.value;\n\t\t\tconst ops: readonly Op[] = before === NO_VALUE ? [[\"r\", after]] : diffRevisions(before!, after);\n\t\t\tif (ops.length > 0) this.publish(after, ops, false, context);\n\t\t\treturn;\n\t\t}\n\t\t// Still failed since the last call: nothing new for the watches.\n\t\tif (state.kind === \"failed\" && before !== NO_VALUE) this.failWatches(state.error, context);\n\t}\n\n\t/** Its attempt ended: no commit re-runs it, reads throw `error` (the object's), its watches end `ended`. */\n\tdetach(error: Error): void {\n\t\tthis.handle.owner.queries.delete(this);\n\t\tthis.#state = { kind: \"detached\", error };\n\t\tthis.#framed = undefined;\n\t\tthis.endWatches();\n\t}\n\n\t/** One run, counted where it happens (the cost guard: a commit not writing the table runs none). */\n\t#count(context: Context): void {\n\t\tchordMetrics(context.telemetry.metrics).counter(\"chord.query.runs\").add(1);\n\t}\n\n\t/**\n\t * The rows of `stored`: a row whose stored columns are all the same as in the last adopted run is that run's object\n\t * (one comparison per physical column), any other is decoded.\n\t */\n\t#decode(stored: readonly StoredRow[], context: Context): Rows {\n\t\tconst { key, rows } = this.handle.definition;\n\t\tconst value: JsonValue[] = [];\n\t\tconst byKey = new Map<unknown, Decoded>();\n\t\tfor (const each of stored) {\n\t\t\tconst id = key.length === 1 ? each[key[0]!] : JSON.stringify(key.map((column) => each[column]));\n\t\t\tconst before = this.#byKey.get(id);\n\t\t\tconst row =\n\t\t\t\tbefore !== undefined && sameStored(before.stored, each, rows.physical)\n\t\t\t\t\t? before.row\n\t\t\t\t\t: // A table's rows hold its columns' values: scalars and JSON.\n\t\t\t\t\t\t(rows.decode(each, context) as JsonValue);\n\t\t\tvalue.push(row);\n\t\t\tbyKey.set(id, { stored: each, row });\n\t\t}\n\t\treturn { value, byKey };\n\t}\n}\n\n/** Whether two stored rows have the same value in every physical column (SQLite values compare by `===`). */\nfunction sameStored(a: StoredRow, b: StoredRow, physical: readonly string[]): boolean {\n\tfor (const column of physical) if (a[column] !== b[column]) return false;\n\treturn true;\n}\n"]}

package/dist/store/outbox.d.ts

@@ -0,0 +1,26 @@
+import type { Context } from "../context/index.ts";
+import type { ChordStore } from "./store.ts";
+import type { StoreWrite } from "./writes.ts";
+/** The write vocabulary's version an outbox commit is stored in; a newer one is refused, data intact. */
+export declare const OUTBOX_FORMAT = 1;
+/** One commit as the outbox gives it: its seq, the allocator's value it persisted (D3) and its writes in applied order. */
+export type OutboxCommit = {
+    readonly seq: number;
+    readonly nextId: number;
+    readonly writes: readonly StoreWrite[];
+};
+/** A store's outbox: its commits after the floor (the seq it was turned on at, advanced by `trim`). */
+export declare class Outbox {
+    #private;
+    constructor(store: ChordStore, floor: number);
+    /** The seq the outbox starts after: `read` takes any `afterSeq` from it to `lastSeq`. */
+    get floor(): number;
+    /** Up to `limit` commits after `afterSeq`, in seq order; `afterSeq` outside floor..lastSeq is `invalid/args`. */
+    read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]>;
+    /**
+     * Drops the commits through `throughSeq` and advances the floor; idempotent; beyond `lastSeq` is `invalid/args`.
+     * Trims run one at a time, so the stored floor only rises and equals the one in memory.
+     */
+    trim(throughSeq: number, context: Context): Promise<void>;
+}
+//# sourceMappingURL=outbox.d.ts.map

package/dist/store/outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.d.ts","sourceRoot":"","sources":["../../src/store/outbox.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAInD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,yGAAyG;AACzG,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,2HAA2H;AAC3H,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAIrH,uGAAuG;AACvG,qBAAa,MAAM;;IASlB,YAAY,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAG3C;IAED,yFAAyF;IACzF,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,iHAAiH;IAC3G,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAIrF;IAED;;;OAGG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAUxD;CA6CD"}

package/dist/store/outbox.js

@@ -0,0 +1,80 @@
+// The outbox (slice 6a §2; decisions "The outbox is optional, internal and versioned", small items 3-4): the store's
+// commits as the sync layer reads them, one `{ seq, writes }` per commit from its floor on, in the current format.
+import { ChordError } from "../data/index.js";
+import { invalid } from "../data/internal.js";
+import { TABLES } from "./schema.js";
+/** The write vocabulary's version an outbox commit is stored in; a newer one is refused, data intact. */
+export const OUTBOX_FORMAT = 1;
+const NOTHING = () => { };
+/** A store's outbox: its commits after the floor (the seq it was turned on at, advanced by `trim`). */
+export class Outbox {
+    #store;
+    #floor;
+    /**
+     * The outbox's reads and trims, one at a time: a read checks the floor and reads with no trim running (a trim's
+     * commit may have deleted rows before its floor is set), a trim waits for the reads in flight.
+     */
+    #queue = Promise.resolve();
+    constructor(store, floor) {
+        this.#store = store;
+        this.#floor = floor;
+    }
+    /** The seq the outbox starts after: `read` takes any `afterSeq` from it to `lastSeq`. */
+    get floor() {
+        return this.#floor;
+    }
+    /** Up to `limit` commits after `afterSeq`, in seq order; `afterSeq` outside floor..lastSeq is `invalid/args`. */
+    async read(afterSeq, limit, context) {
+        if (!Number.isSafeInteger(afterSeq))
+            throw invalid("args", `outbox: read after ${afterSeq}, not an integer`);
+        if (!Number.isSafeInteger(limit) || limit < 1)
+            throw invalid("args", "outbox: limit is a positive integer");
+        return this.#queued(() => this.#read(afterSeq, limit, context));
+    }
+    /**
+     * Drops the commits through `throughSeq` and advances the floor; idempotent; beyond `lastSeq` is `invalid/args`.
+     * Trims run one at a time, so the stored floor only rises and equals the one in memory.
+     */
+    trim(throughSeq, context) {
+        try {
+            context.abortSignal?.throwIfAborted();
+            if (!Number.isSafeInteger(throughSeq) || throughSeq > this.#store.lastSeq) {
+                throw invalid("args", `outbox: trim through ${throughSeq}, beyond ${this.#store.lastSeq}`);
+            }
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return this.#queued(() => this.#trim(throughSeq));
+    }
+    /** Runs `operation` once the outbox operations before it settled. */
+    #queued(operation) {
+        const run = this.#queue.then(operation);
+        this.#queue = run.then(NOTHING, NOTHING);
+        return run;
+    }
+    /** `read`, its turn come: the floor as no trim moves it. */
+    async #read(afterSeq, limit, context) {
+        if (afterSeq < this.#floor || afterSeq > this.#store.lastSeq) {
+            throw invalid("args", `outbox: read after ${afterSeq}, outside ${this.#floor}..${this.#store.lastSeq}`);
+        }
+        const rows = await this.#store.read((executor) => executor.all(`SELECT seq, format, next_id, writes FROM ${TABLES.outbox} WHERE seq > ? ORDER BY seq LIMIT ?`, afterSeq, limit), context);
+        return rows.map(({ seq, format, next_id, writes }) => {
+            if (format !== OUTBOX_FORMAT) {
+                const message = `outbox: commit ${seq} is in format ${format}, newer than ${OUTBOX_FORMAT}`;
+                throw new ChordError({ code: "unavailable", message });
+            }
+            return { seq, nextId: next_id, writes: JSON.parse(writes) };
+        });
+    }
+    async #trim(throughSeq) {
+        if (throughSeq <= this.#floor)
+            return;
+        await this.#store.maintain(async (executor) => {
+            await executor.run(`DELETE FROM ${TABLES.outbox} WHERE seq <= ?`, throughSeq);
+            await executor.run(`UPDATE ${TABLES.meta} SET outbox_floor = ? WHERE singleton = 1`, throughSeq);
+        });
+        this.#floor = throughSeq;
+    }
+}
+//# sourceMappingURL=outbox.js.map

package/dist/store/outbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbox.js","sourceRoot":"","sources":["../../src/store/outbox.ts"],"names":[],"mappings":"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","sourcesContent":["// The outbox (slice 6a §2; decisions \"The outbox is optional, internal and versioned\", small items 3-4): the store's\n// commits as the sync layer reads them, one `{ seq, writes }` per commit from its floor on, in the current format.\n\nimport type { Context } from \"../context/index.ts\";\nimport { ChordError } from \"../data/index.ts\";\nimport { invalid } from \"../data/internal.ts\";\nimport { TABLES } from \"./schema.ts\";\nimport type { ChordStore } from \"./store.ts\";\nimport type { StoreWrite } from \"./writes.ts\";\n\n/** The write vocabulary's version an outbox commit is stored in; a newer one is refused, data intact. */\nexport const OUTBOX_FORMAT = 1;\n\n/** One commit as the outbox gives it: its seq, the allocator's value it persisted (D3) and its writes in applied order. */\nexport type OutboxCommit = { readonly seq: number; readonly nextId: number; readonly writes: readonly StoreWrite[] };\n\nconst NOTHING = (): void => {};\n\n/** A store's outbox: its commits after the floor (the seq it was turned on at, advanced by `trim`). */\nexport class Outbox {\n\treadonly #store: ChordStore;\n\t#floor: number;\n\t/**\n\t * The outbox's reads and trims, one at a time: a read checks the floor and reads with no trim running (a trim's\n\t * commit may have deleted rows before its floor is set), a trim waits for the reads in flight.\n\t */\n\t#queue: Promise<void> = Promise.resolve();\n\n\tconstructor(store: ChordStore, floor: number) {\n\t\tthis.#store = store;\n\t\tthis.#floor = floor;\n\t}\n\n\t/** The seq the outbox starts after: `read` takes any `afterSeq` from it to `lastSeq`. */\n\tget floor(): number {\n\t\treturn this.#floor;\n\t}\n\n\t/** Up to `limit` commits after `afterSeq`, in seq order; `afterSeq` outside floor..lastSeq is `invalid/args`. */\n\tasync read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]> {\n\t\tif (!Number.isSafeInteger(afterSeq)) throw invalid(\"args\", `outbox: read after ${afterSeq}, not an integer`);\n\t\tif (!Number.isSafeInteger(limit) || limit < 1) throw invalid(\"args\", \"outbox: limit is a positive integer\");\n\t\treturn this.#queued(() => this.#read(afterSeq, limit, context));\n\t}\n\n\t/**\n\t * Drops the commits through `throughSeq` and advances the floor; idempotent; beyond `lastSeq` is `invalid/args`.\n\t * Trims run one at a time, so the stored floor only rises and equals the one in memory.\n\t */\n\ttrim(throughSeq: number, context: Context): Promise<void> {\n\t\ttry {\n\t\t\tcontext.abortSignal?.throwIfAborted();\n\t\t\tif (!Number.isSafeInteger(throughSeq) || throughSeq > this.#store.lastSeq) {\n\t\t\t\tthrow invalid(\"args\", `outbox: trim through ${throughSeq}, beyond ${this.#store.lastSeq}`);\n\t\t\t}\n\t\t} catch (error) {\n\t\t\treturn Promise.reject(error);\n\t\t}\n\t\treturn this.#queued(() => this.#trim(throughSeq));\n\t}\n\n\t/** Runs `operation` once the outbox operations before it settled. */\n\t#queued<T>(operation: () => Promise<T>): Promise<T> {\n\t\tconst run = this.#queue.then(operation);\n\t\tthis.#queue = run.then(NOTHING, NOTHING);\n\t\treturn run;\n\t}\n\n\t/** `read`, its turn come: the floor as no trim moves it. */\n\tasync #read(afterSeq: number, limit: number, context: Context): Promise<OutboxCommit[]> {\n\t\tif (afterSeq < this.#floor || afterSeq > this.#store.lastSeq) {\n\t\t\tthrow invalid(\"args\", `outbox: read after ${afterSeq}, outside ${this.#floor}..${this.#store.lastSeq}`);\n\t\t}\n\t\tconst rows = await this.#store.read(\n\t\t\t(executor) =>\n\t\t\t\texecutor.all<{\n\t\t\t\t\treadonly seq: number;\n\t\t\t\t\treadonly format: number;\n\t\t\t\t\treadonly next_id: number;\n\t\t\t\t\treadonly writes: string;\n\t\t\t\t}>(\n\t\t\t\t\t`SELECT seq, format, next_id, writes FROM ${TABLES.outbox} WHERE seq > ? ORDER BY seq LIMIT ?`,\n\t\t\t\t\tafterSeq,\n\t\t\t\t\tlimit,\n\t\t\t\t),\n\t\t\tcontext,\n\t\t);\n\t\treturn rows.map(({ seq, format, next_id, writes }) => {\n\t\t\tif (format !== OUTBOX_FORMAT) {\n\t\t\t\tconst message = `outbox: commit ${seq} is in format ${format}, newer than ${OUTBOX_FORMAT}`;\n\t\t\t\tthrow new ChordError({ code: \"unavailable\", message });\n\t\t\t}\n\t\t\treturn { seq, nextId: next_id, writes: JSON.parse(writes) as StoreWrite[] };\n\t\t});\n\t}\n\n\tasync #trim(throughSeq: number): Promise<void> {\n\t\tif (throughSeq <= this.#floor) return;\n\t\tawait this.#store.maintain(async (executor) => {\n\t\t\tawait executor.run(`DELETE FROM ${TABLES.outbox} WHERE seq <= ?`, throughSeq);\n\t\t\tawait executor.run(`UPDATE ${TABLES.meta} SET outbox_floor = ? WHERE singleton = 1`, throughSeq);\n\t\t});\n\t\tthis.#floor = throughSeq;\n\t}\n}\n"]}

package/dist/store/query.d.ts

@@ -0,0 +1,39 @@
+import type { SqliteValue } from "../sqlite/index.ts";
+import type { Columns, ColumnTypeOf, ValueOf } from "./columns.ts";
+import { type ColumnRef, type Condition, type WhereNode } from "./expression.ts";
+import type { Order } from "./sql.ts";
+import type { TableDefinition } from "./table.ts";
+/** The column references a table's callbacks get: `e.path`, `e.at`. */
+export type ColumnRefs<C extends Columns> = {
+    readonly [K in keyof C & string]: ColumnRef<ValueOf<C[K]>, ColumnTypeOf<C[K]>>;
+};
+/** A query of `table`: its rows, in key order. */
+export declare function query<C extends Columns, K extends readonly string[]>(table: TableDefinition<C, K>): Query<C, K>;
+/**
+ * An immutable query of one table: an optional condition (several `where`s are `and`ed) and an order (`orderBy`
+ * columns, one direction, the key appended unless already there).
+ */
+export declare class Query<C extends Columns = Columns, K extends readonly string[] = readonly string[]> {
+    #private;
+    readonly table: TableDefinition<C, K>;
+    readonly condition: WhereNode | undefined;
+    constructor(table: TableDefinition<C, K>, condition: WhereNode | undefined, orderBy: readonly string[], direction: "asc" | "desc" | undefined);
+    /** This query with `fn`'s condition too. */
+    where(fn: (row: ColumnRefs<C>) => Condition): Query<C, K>;
+    /**
+     * This query ordered by `fn`'s column next (a non-`opt` `str` or `int` one), in `direction`: one direction per
+     * query, no column twice (`invalid/args`).
+     */
+    orderBy(fn: (row: ColumnRefs<C>) => ColumnRef<unknown, "str" | "int">, direction?: "asc" | "desc"): Query<C, K>;
+    /** The order of its rows: the `orderBy` columns, then the key columns not among them. */
+    get order(): Order;
+}
+/** The cursor of the position after a row with the order values `values` in the table named `table` (its SQL name). */
+export declare function encodeCursor(table: string, order: Order, values: readonly SqliteValue[]): string;
+/**
+ * The order values of `cursor` (a trust boundary: an app hands it back): one made for `table`'s `order` (any
+ * condition) in the table named `sqlName` (another object's table of the same definition is another table), each value
+ * of its column's type; `invalid/args` otherwise.
+ */
+export declare function decodeCursor(table: TableDefinition, sqlName: string, order: Order, cursor: unknown): SqliteValue[];
+//# sourceMappingURL=query.d.ts.map

package/dist/store/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/store/query.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAgB,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE/F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,uEAAuE;AACvE,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,OAAO,IAAI;IAC3C,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC9E,CAAC;AAEF,kDAAkD;AAClD,wBAAgB,KAAK,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAE/G;AAED;;;GAGG;AACH,qBAAa,KAAK,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,CAAC,SAAS,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE;;IAC9F,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAI1C,YACC,KAAK,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAC5B,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,SAAS,EAMrC;IAED,4CAA4C;IAC5C,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,SAAS,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAKxD;IAED;;;OAGG;IACH,OAAO,CACN,EAAE,EAAE,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,OAAO,EAAE,KAAK,GAAG,KAAK,CAAC,EAC7D,SAAS,GAAE,KAAK,GAAG,MAAc,GAC/B,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAab;IAED,yFAAyF;IACzF,IAAI,KAAK,IAAI,KAAK,CAGjB;CACD;AAED,uHAAuH;AACvH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAKhG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAuBlH"}

package/dist/store/query.js

@@ -0,0 +1,97 @@
+// Queries (decision "Query runner"; slice 6a §6, rule 17): `query(Table).where(…).orderBy(…)` as immutable data
+// (the condition compiled when given, the order with the key appended as the tie-break), and the opaque cursors that
+// continue a page, bound to the table, the order columns and the direction.
+import { invalid } from "../data/internal.js";
+import { compileWhere } from "./expression.js";
+import { checkScalar } from "./rows.js";
+/** A query of `table`: its rows, in key order. */
+export function query(table) {
+    return new Query(table, undefined, [], undefined);
+}
+/**
+ * An immutable query of one table: an optional condition (several `where`s are `and`ed) and an order (`orderBy`
+ * columns, one direction, the key appended unless already there).
+ */
+export class Query {
+    table;
+    condition;
+    #orderBy;
+    #direction;
+    constructor(table, condition, orderBy, direction) {
+        this.table = table;
+        this.condition = condition;
+        this.#orderBy = orderBy;
+        this.#direction = direction;
+    }
+    /** This query with `fn`'s condition too. */
+    where(fn) {
+        // The refs are the table's columns, typed by `C`.
+        const compiled = compileWhere(this.table, fn(this.table.refs), "where");
+        const condition = this.condition === undefined ? compiled : { and: [this.condition, compiled] };
+        return new Query(this.table, condition, this.#orderBy, this.#direction);
+    }
+    /**
+     * This query ordered by `fn`'s column next (a non-`opt` `str` or `int` one), in `direction`: one direction per
+     * query, no column twice (`invalid/args`).
+     */
+    orderBy(fn, direction = "asc") {
+        const table = this.table;
+        // The refs are `C`'s columns; what the plugin's callback returns is checked below.
+        const ref = fn(table.refs);
+        const column = table.byName.get(ref?.column ?? "");
+        if (column === undefined || column.optional || (column.type !== "str" && column.type !== "int")) {
+            throw invalid("args", `${table.name}: orderBy: expected a non-opt str() or int() column`);
+        }
+        if (this.#orderBy.includes(column.name))
+            throw invalid("args", `${table.name}: orderBy: "${column.name}" twice`);
+        if (this.#direction !== undefined && this.#direction !== direction) {
+            throw invalid("args", `${table.name}: orderBy: one direction per query`);
+        }
+        return new Query(table, this.condition, [...this.#orderBy, column.name], direction);
+    }
+    /** The order of its rows: the `orderBy` columns, then the key columns not among them. */
+    get order() {
+        const columns = [...this.#orderBy, ...this.table.key.filter((column) => !this.#orderBy.includes(column))];
+        return { columns, direction: this.#direction ?? "asc" };
+    }
+}
+/** The cursor of the position after a row with the order values `values` in the table named `table` (its SQL name). */
+export function encodeCursor(table, order, values) {
+    const json = JSON.stringify({ t: table, o: order.columns, d: order.direction, v: values });
+    let binary = "";
+    for (const byte of new TextEncoder().encode(json))
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+/**
+ * The order values of `cursor` (a trust boundary: an app hands it back): one made for `table`'s `order` (any
+ * condition) in the table named `sqlName` (another object's table of the same definition is another table), each value
+ * of its column's type; `invalid/args` otherwise.
+ */
+export function decodeCursor(table, sqlName, order, cursor) {
+    const refuse = () => {
+        throw invalid("args", `${table.name}: the cursor is not one of this table's order`);
+    };
+    if (typeof cursor !== "string")
+        return refuse();
+    let decoded;
+    try {
+        const binary = atob(cursor.replaceAll("-", "+").replaceAll("_", "/"));
+        decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+    }
+    catch {
+        return refuse();
+    }
+    // Wire input: every field is checked below.
+    const { t, o, d, v } = (decoded ?? {});
+    if (t !== sqlName || d !== order.direction || JSON.stringify(o) !== JSON.stringify(order.columns))
+        refuse();
+    if (!Array.isArray(v) || v.length !== order.columns.length)
+        return refuse();
+    return order.columns.map((name, index) => {
+        const column = table.byName.get(name);
+        // Order columns are non-opt `str` or `int` (checked when the query was built).
+        return checkScalar(column.type, v[index], `${table.name}: cursor`);
+    });
+}
+//# sourceMappingURL=query.js.map

package/dist/store/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/store/query.ts"],"names":[],"mappings":"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","sourcesContent":["// Queries (decision \"Query runner\"; slice 6a §6, rule 17): `query(Table).where(…).orderBy(…)` as immutable data\n// (the condition compiled when given, the order with the key appended as the tie-break), and the opaque cursors that\n// continue a page, bound to the table, the order columns and the direction.\n\nimport { invalid } from \"../data/internal.ts\";\nimport type { SqliteValue } from \"../sqlite/index.ts\";\nimport type { Columns, ColumnTypeOf, ValueOf } from \"./columns.ts\";\nimport { type ColumnRef, type Condition, compileWhere, type WhereNode } from \"./expression.ts\";\nimport { checkScalar } from \"./rows.ts\";\nimport type { Order } from \"./sql.ts\";\nimport type { TableDefinition } from \"./table.ts\";\n\n/** The column references a table's callbacks get: `e.path`, `e.at`. */\nexport type ColumnRefs<C extends Columns> = {\n\treadonly [K in keyof C & string]: ColumnRef<ValueOf<C[K]>, ColumnTypeOf<C[K]>>;\n};\n\n/** A query of `table`: its rows, in key order. */\nexport function query<C extends Columns, K extends readonly string[]>(table: TableDefinition<C, K>): Query<C, K> {\n\treturn new Query(table, undefined, [], undefined);\n}\n\n/**\n * An immutable query of one table: an optional condition (several `where`s are `and`ed) and an order (`orderBy`\n * columns, one direction, the key appended unless already there).\n */\nexport class Query<C extends Columns = Columns, K extends readonly string[] = readonly string[]> {\n\treadonly table: TableDefinition<C, K>;\n\treadonly condition: WhereNode | undefined;\n\treadonly #orderBy: readonly string[];\n\treadonly #direction: \"asc\" | \"desc\" | undefined;\n\n\tconstructor(\n\t\ttable: TableDefinition<C, K>,\n\t\tcondition: WhereNode | undefined,\n\t\torderBy: readonly string[],\n\t\tdirection: \"asc\" | \"desc\" | undefined,\n\t) {\n\t\tthis.table = table;\n\t\tthis.condition = condition;\n\t\tthis.#orderBy = orderBy;\n\t\tthis.#direction = direction;\n\t}\n\n\t/** This query with `fn`'s condition too. */\n\twhere(fn: (row: ColumnRefs<C>) => Condition): Query<C, K> {\n\t\t// The refs are the table's columns, typed by `C`.\n\t\tconst compiled = compileWhere(this.table, fn(this.table.refs as ColumnRefs<C>), \"where\");\n\t\tconst condition = this.condition === undefined ? compiled : { and: [this.condition, compiled] };\n\t\treturn new Query(this.table, condition, this.#orderBy, this.#direction);\n\t}\n\n\t/**\n\t * This query ordered by `fn`'s column next (a non-`opt` `str` or `int` one), in `direction`: one direction per\n\t * query, no column twice (`invalid/args`).\n\t */\n\torderBy(\n\t\tfn: (row: ColumnRefs<C>) => ColumnRef<unknown, \"str\" | \"int\">,\n\t\tdirection: \"asc\" | \"desc\" = \"asc\",\n\t): Query<C, K> {\n\t\tconst table = this.table;\n\t\t// The refs are `C`'s columns; what the plugin's callback returns is checked below.\n\t\tconst ref = fn(table.refs as ColumnRefs<C>) as ColumnRef | undefined;\n\t\tconst column = table.byName.get(ref?.column ?? \"\");\n\t\tif (column === undefined || column.optional || (column.type !== \"str\" && column.type !== \"int\")) {\n\t\t\tthrow invalid(\"args\", `${table.name}: orderBy: expected a non-opt str() or int() column`);\n\t\t}\n\t\tif (this.#orderBy.includes(column.name)) throw invalid(\"args\", `${table.name}: orderBy: \"${column.name}\" twice`);\n\t\tif (this.#direction !== undefined && this.#direction !== direction) {\n\t\t\tthrow invalid(\"args\", `${table.name}: orderBy: one direction per query`);\n\t\t}\n\t\treturn new Query(table, this.condition, [...this.#orderBy, column.name], direction);\n\t}\n\n\t/** The order of its rows: the `orderBy` columns, then the key columns not among them. */\n\tget order(): Order {\n\t\tconst columns = [...this.#orderBy, ...this.table.key.filter((column) => !this.#orderBy.includes(column))];\n\t\treturn { columns, direction: this.#direction ?? \"asc\" };\n\t}\n}\n\n/** The cursor of the position after a row with the order values `values` in the table named `table` (its SQL name). */\nexport function encodeCursor(table: string, order: Order, values: readonly SqliteValue[]): string {\n\tconst json = JSON.stringify({ t: table, o: order.columns, d: order.direction, v: values });\n\tlet binary = \"\";\n\tfor (const byte of new TextEncoder().encode(json)) binary += String.fromCharCode(byte);\n\treturn btoa(binary).replaceAll(\"+\", \"-\").replaceAll(\"/\", \"_\").replace(/=+$/, \"\");\n}\n\n/**\n * The order values of `cursor` (a trust boundary: an app hands it back): one made for `table`'s `order` (any\n * condition) in the table named `sqlName` (another object's table of the same definition is another table), each value\n * of its column's type; `invalid/args` otherwise.\n */\nexport function decodeCursor(table: TableDefinition, sqlName: string, order: Order, cursor: unknown): SqliteValue[] {\n\tconst refuse = (): never => {\n\t\tthrow invalid(\"args\", `${table.name}: the cursor is not one of this table's order`);\n\t};\n\tif (typeof cursor !== \"string\") return refuse();\n\tlet decoded: unknown;\n\ttry {\n\t\tconst binary = atob(cursor.replaceAll(\"-\", \"+\").replaceAll(\"_\", \"/\"));\n\t\tdecoded = JSON.parse(\n\t\t\tnew TextDecoder(\"utf-8\", { fatal: true }).decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))),\n\t\t);\n\t} catch {\n\t\treturn refuse();\n\t}\n\t// Wire input: every field is checked below.\n\tconst { t, o, d, v } = (decoded ?? {}) as { t?: unknown; o?: unknown; d?: unknown; v?: unknown };\n\tif (t !== sqlName || d !== order.direction || JSON.stringify(o) !== JSON.stringify(order.columns)) refuse();\n\tif (!Array.isArray(v) || v.length !== order.columns.length) return refuse();\n\treturn order.columns.map((name, index) => {\n\t\tconst column = table.byName.get(name)!;\n\t\t// Order columns are non-opt `str` or `int` (checked when the query was built).\n\t\treturn checkScalar(column.type as \"str\" | \"int\", v[index], `${table.name}: cursor`) as string | number;\n\t});\n}\n"]}

package/dist/store/refusal.d.ts

@@ -0,0 +1,15 @@
+import { ChordError } from "../data/index.ts";
+/** How a Chord commit ended that the store rejected: `check` fails the transaction only, `broken` its object too. */
+export type Refusal = {
+    readonly kind: "check";
+    readonly error: ChordError;
+} | {
+    readonly kind: "broken";
+    readonly error: ChordError;
+};
+/**
+ * The refusal behind `error`, a store commit's rejection; `undefined` when it is the store's own (`released` at
+ * admission or after close, `unavailable/storage_failed` once stopped), which the owner rethrows as it is.
+ */
+export declare function refusalOf(error: unknown, label: string): Refusal | undefined;
+//# sourceMappingURL=refusal.d.ts.map

package/dist/store/refusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal.d.ts","sourceRoot":"","sources":["../../src/store/refusal.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,UAAU,EAAgB,MAAM,kBAAkB,CAAC;AAE5D,qHAAqH;AACrH,MAAM,MAAM,OAAO,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;CAAE,CAAC;AAK3D;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAc5E"}