@earendil-works/chord 1.5.0 → 1.5.1

package/dist/next/store/store.js

@@ -1,627 +0,0 @@
-// The store (slice 6a §2, §3, slice 6b §1): opened over a backend, one commit queue that serializes only the commit step
-// (the seal fence's admission check, `BEGIN`, the writes in their order, the outbox commit, `lastSeq` and the
-// allocator's value, `COMMIT`, then the owner's adoption), the id allocator, the claims of its tables and documents,
-// reads guarded as Durable's `GuardedStorage` guards them, Durable's Storage semantics for a refused step (D4), and the
-// stop after an unknown outcome.
-import { awaitWithContext } from "../../context/index.js";
-import { ChordError } from "../data/index.js";
-import { invalid } from "../data/internal.js";
-import { IdAllocator } from "./allocator.js";
-import { readCatalog, writeCatalog } from "./catalog.js";
-import { Claims } from "./claims.js";
-import { StoreExport } from "./export.js";
-import { OUTBOX_FORMAT, Outbox } from "./outbox.js";
-import { applyStoreSchema, TABLES } from "./schema.js";
-import { Step } from "./step.js";
-/**
- * Opens a store over `backend`: the store's schema migrations, the UTF-8 check, the metadata read once, the outbox
- * switched when asked. A failure closes the backend and rejects (rule 12).
- */
-export async function openStore(backend, context, options = {}) {
-    const { db } = backend;
-    try {
-        context.abortSignal?.throwIfAborted();
-        const meta = await switchOutbox(db, await applyStoreSchema(db), options.outbox);
-        return new ChordStore(db, meta, await readCatalog(db));
-    }
-    catch (error) {
-        try {
-            await db.close();
-        }
-        catch {
-            // The open's own failure is the one to report.
-        }
-        throw error;
-    }
-}
-/** Turns the outbox on (from the current `lastSeq`) or off (its commits dropped) when `outbox` asks for the other. */
-async function switchOutbox(db, meta, outbox) {
-    if (outbox === undefined || outbox === (meta.outbox === 1))
-        return meta;
-    const floor = outbox ? meta.last_seq : 0;
-    await db.transaction(async (executor) => {
-        await executor.run(`UPDATE ${TABLES.meta} SET outbox = ?, outbox_floor = ? WHERE singleton = 1`, outbox ? 1 : 0, floor);
-        if (!outbox)
-            await executor.run(`DELETE FROM ${TABLES.outbox}`);
-    });
-    return { ...meta, outbox: outbox ? 1 : 0, outbox_floor: floor };
-}
-const ORDER = ["retire", "create", "write"];
-const NOTHING = () => { };
-/** The step's own error, until its callback throws one: a distinct value no thrown error can be. */
-const NONE = Symbol("none");
-/** The store behind `Store`, with what Chord's layers use: commits, guarded reads, the host's failure listener. */
-export class ChordStore {
-    #db;
-    #lastSeq;
-    /** The allocator's value as the last commit persisted it (an export's manifest). */
-    #committedNextId;
-    #ids;
-    /** The claims of its tables and documents (slice 6b). */
-    claims = new Claims();
-    #outbox;
-    #state = { kind: "open" };
-    /** Set once a batch's recorded count did not reproduce (S17): no batch applies any more. */
-    #diverged = false;
-    /** The commit queue's tail: each step starts after the one before it settled. */
-    #tail = Promise.resolve();
-    /** Reads and maintenance writes underway, which `close` waits for. */
-    #underway = 0;
-    /** Resolves `close`'s wait once no read is underway. */
-    #drained;
-    /** The open host's listener for `storage_failed` (told once) and batch; one host per store (rule 7). */
-    #attachment;
-    #closing;
-    /** The versions migrations of tables announced (`announceTable`), by SQL name, until their last commit. */
-    #announced = new Map();
-    /** The recorded tables, by SQL name; changed only after a step's `COMMIT`. */
-    #catalog;
-    /** The ends of the exports holding the queue or waiting for it, which closing the store calls. */
-    #held = new Set();
-    constructor(db, meta, catalog) {
-        this.#db = db;
-        this.#catalog = catalog;
-        this.#lastSeq = meta.last_seq;
-        this.#committedNextId = meta.next_id;
-        this.#ids = new IdAllocator(meta.next_id);
-        this.#outbox = meta.outbox === 1 ? new Outbox(this, meta.outbox_floor) : undefined;
-    }
-    get lastSeq() {
-        return this.#lastSeq;
-    }
-    get outbox() {
-        return this.#outbox;
-    }
-    /** The allocator's value as the last commit persisted it. */
-    get nextId() {
-        return this.#committedNextId;
-    }
-    /** The id allocator: `mint` takes the next id, `raise` makes room above an explicit one (D3). */
-    get ids() {
-        return this.#ids;
-    }
-    /** Takes the next id from the allocator (Durable's `mintId`); refused once the store stopped or closed. */
-    mintId() {
-        this.assertUsable();
-        return this.#ids.mint();
-    }
-    /** The open host's batch, in which an adapter publishes its commits; `undefined` without a host. */
-    get batch() {
-        return this.#attachment?.batch;
-    }
-    /** Every recorded table, by SQL name, as of the last commit. */
-    get tables() {
-        return this.#catalog;
-    }
-    export(context) {
-        this.assertUsable();
-        return new StoreExport(this, context);
-    }
-    /**
-     * Takes the commit queue (an export): resolves once every earlier commit settled, with the release that lets the
-     * later ones run (idempotent). Closing the store calls `end` (from the call on, also while waiting, and at once for a
-     * store closed before the call took the queue), which must release.
-     */
-    take(end) {
-        const held = Promise.withResolvers();
-        const release = () => {
-            this.#held.delete(end);
-            held.resolve();
-        };
-        this.#held.add(end);
-        const taken = this.#tail.then(() => {
-            // A store closed meanwhile (also before the export's first `next()`) holds nothing: the export ends.
-            if (this.#state.kind === "closed") {
-                release();
-                end();
-            }
-            return release;
-        });
-        this.#tail = taken.then(() => held.promise);
-        return taken;
-    }
-    /** The recorded table `name` (its SQL name), as of the last commit. */
-    table(name) {
-        return this.#catalog.get(name);
-    }
-    /**
-     * The version table `name` is at or is being migrated to: the recorded one, or a higher one a migration announced
-     * before its first commit (`announceTable`), so an old handle is refused before its SQL could queue behind the
-     * migration's DDL (fix round 1, Sol 8).
-     */
-    tableVersion(name) {
-        const recorded = this.#catalog.get(name)?.version;
-        const announced = this.#announced.get(name);
-        return announced === undefined || (recorded !== undefined && recorded >= announced) ? recorded : announced;
-    }
-    /** Announces a migration of table `name` to `version` until the returned withdrawal (after its last commit). */
-    announceTable(name, version) {
-        this.#announced.set(name, version);
-        return () => {
-            if (this.#announced.get(name) === version)
-                this.#announced.delete(name);
-        };
-    }
-    /** Attaches the open host; a store attached to an open host is refused (rule 7). */
-    attach(attachment) {
-        if (this.#attachment !== undefined) {
-            throw new ChordError({ code: "invalid", reason: "args", message: "store: already attached to an open host" });
-        }
-        this.#attachment = attachment;
-    }
-    /** The host closed: the store may serve another one. */
-    detach() {
-        this.#attachment = undefined;
-    }
-    /**
-     * Commits `writes` as one seq when the commit queue reaches it: `fence.admit()` at the step's entry, the writes in
-     * their order (retirements, creations, the rest), the outbox commit, `lastSeq` and the allocator's value, `COMMIT`,
-     * then `fence.adopt` before the next step starts. Resolves with the seq. A refused admission rejects `released`. A
-     * step the backend rolled back after the step's own code threw (a refusal, D4) rejects with that error unchanged and
-     * the store goes on; any other failure (`BEGIN`, `COMMIT`, `ROLLBACK`, a throwing `adopt`) is an unknown outcome
-     * that stops the store (`storage_failed`). `context` counts the step (no abort once queued).
-     */
-    commit(writes, fence, context) {
-        try {
-            this.assertUsable();
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
-        const step = this.#tail.then(() => this.#step(writes, fence, context));
-        this.#tail = step.then(NOTHING, NOTHING);
-        return step;
-    }
-    /**
-     * Commits `commits` in one backend transaction when the commit queue reaches them, one seq each, in order: each
-     * commit's `check`, which writes nothing, then its writes as `commit` writes them, with its own outbox commit and the
-     * metadata (a commit without writes takes no seq: it stands at the one before). A `check` that throws refuses its
-     * commit: the series stops there and the transaction commits the ones before it. A check whose backend statement
-     * failed, and a throw of a commit's writes, roll the whole series back and reject with that error, the store going
-     * on (D4); any other failure is an unknown outcome that stops the store, as for `commit`. After `COMMIT`,
-     * `receive(index, seq, ids)` is called per stored commit, in order, before the next step starts (`ids`: its created
-     * documents). Resolves with what it stored.
-     */
-    commitSeries(commits, receive, context) {
-        try {
-            this.assertUsable();
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
-        const series = this.#tail.then(() => this.#series(commits, receive, context));
-        this.#tail = series.then(NOTHING, NOTHING);
-        return series;
-    }
-    /**
-     * Runs `read` on the backend under the guard (rule 11, Durable's `GuardedStorage`): refused once the store stopped
-     * or closed; a backend error fails the store unless `context` was aborted (then `aborted`); a read settling after
-     * the store stopped rejects `unavailable/storage_failed`. `read` returns data and never throws for a request: an
-     * adapter checks a request from what it returned, after the guard (slice 6b §1.4).
-     */
-    read(read, context) {
-        return this.#guarded(() => read(this.#db), context);
-    }
-    /**
-     * `read` for several queries that must see one state (S4, a document from its record and revisions): one backend
-     * transaction, guarded as `read`.
-     */
-    readTransaction(read, context) {
-        return this.#guarded(() => this.#db.transaction(read), context);
-    }
-    async #guarded(run, context) {
-        this.assertUsable();
-        this.#underway++;
-        let result;
-        try {
-            // A read throwing before its first await is the backend's too: inside the `try`.
-            result = await run();
-        }
-        catch (error) {
-            this.assertUsable();
-            const signal = context.abortSignal;
-            if (signal?.aborted)
-                throw new ChordError({ code: "aborted", message: "store: read aborted" }, { cause: signal.reason });
-            throw this.#fail(error);
-        }
-        finally {
-            this.#settle();
-        }
-        this.assertUsable();
-        return result;
-    }
-    /** One read or maintenance write settled: `close` goes on once none is underway. */
-    #settle() {
-        if (--this.#underway === 0)
-            this.#drained?.();
-    }
-    /**
-     * Runs `write` on the backend outside the commit queue (the outbox's `trim`), in a backend transaction, guarded as
-     * a read without a context: any error stops the store.
-     */
-    async maintain(write) {
-        this.assertUsable();
-        this.#underway++;
-        try {
-            await this.#db.transaction(write);
-        }
-        catch (error) {
-            this.assertUsable();
-            throw this.#fail(error);
-        }
-        finally {
-            this.#settle();
-        }
-    }
-    close(context) {
-        this.#closing ??= this.#close();
-        return awaitWithContext(this.#closing, context);
-    }
-    async #close() {
-        this.#state = { kind: "closed" };
-        for (const end of [...this.#held])
-            end();
-        await this.#tail;
-        if (this.#underway > 0) {
-            await new Promise((resolve) => {
-                this.#drained = resolve;
-            });
-        }
-        await this.#db.close();
-    }
-    async #step(writes, fence, context) {
-        this.assertUsable();
-        if (!fence.admit()) {
-            throw new ChordError({ code: "released", reason: "discarded", message: "store: the commit's attempt ended" });
-        }
-        if (writes.length === 0) {
-            // An empty commit takes no seq; a throwing `adopt` stops the store as for any commit.
-            try {
-                fence.adopt(this.#lastSeq, []);
-            }
-            catch (error) {
-                throw this.#fail(error);
-            }
-            return this.#lastSeq;
-        }
-        const seq = this.#lastSeq + 1;
-        // Past the safe range seqs stop counting exactly (a later one would repeat): the store cannot number further.
-        if (seq > Number.MAX_SAFE_INTEGER)
-            throw this.#fail(new Error("store: no seq past Number.MAX_SAFE_INTEGER"));
-        let thrown = NONE;
-        let done;
-        try {
-            done = await this.#db.transaction(async (executor) => {
-                try {
-                    const step = new Step(executor, seq, this.#ids, this.#catalog);
-                    const nextId = await this.#write(step, writes);
-                    await writeMeta(step, nextId);
-                    return { step, nextId };
-                }
-                catch (error) {
-                    thrown = error;
-                    throw error;
-                }
-            });
-        }
-        catch (error) {
-            // The facade rolled back and rejects with the step's own error: a refusal, the store goes on (D4).
-            if (error === thrown)
-                throw error;
-            throw this.#fail(error);
-        }
-        // `COMMIT` returned: the commit is durable, and memory follows.
-        const { step, nextId } = done;
-        this.#lastSeq = seq;
-        this.#committedNextId = nextId;
-        for (const [name, record] of step.tables)
-            this.#catalog.set(name, record);
-        const metrics = context.telemetry.metrics;
-        metrics?.counter("chord.store.commits").add(1);
-        metrics?.counter("chord.store.statements").add(step.statements);
-        try {
-            fence.adopt(seq, step.created);
-        }
-        catch (error) {
-            throw this.#fail(error);
-        }
-        return seq;
-    }
-    /**
-     * A series inside one backend transaction: per commit a step at the next seq, its check (a throw refuses it, unless
-     * one of its statements failed), then its writes; then, after `COMMIT`, memory and the receipts as after `#step`.
-     */
-    async #series(commits, receive, context) {
-        this.assertUsable();
-        // Past the safe range seqs stop counting exactly (a later one would repeat): the store cannot number further. Only
-        // a commit with writes takes a seq, as for `commit`.
-        let seqs = 0;
-        for (const commit of commits)
-            if (commit.writes.length > 0)
-                seqs++;
-        if (this.#lastSeq + seqs > Number.MAX_SAFE_INTEGER) {
-            throw this.#fail(new Error("store: no seq past Number.MAX_SAFE_INTEGER"));
-        }
-        let thrown = NONE;
-        let refused;
-        let done;
-        try {
-            done = await this.#db.transaction(async (executor) => {
-                try {
-                    return await this.#writeSeries(executor, commits, (error) => {
-                        refused = { error };
-                    });
-                }
-                catch (error) {
-                    thrown = error;
-                    throw error;
-                }
-            });
-        }
-        catch (error) {
-            // The facade rolled back and rejects with the series' own error: the store goes on (D4).
-            if (error === thrown)
-                throw error;
-            throw this.#fail(error);
-        }
-        // `COMMIT` returned: the stored commits are durable, and memory follows.
-        const { stored, last, written, statements } = done;
-        if (last !== undefined) {
-            this.#lastSeq = last.seq;
-            this.#committedNextId = last.nextId;
-            for (const [name, record] of last.tables)
-                this.#catalog.set(name, record);
-        }
-        const metrics = context.telemetry.metrics;
-        metrics?.counter("chord.store.commits").add(written);
-        metrics?.counter("chord.store.statements").add(statements);
-        try {
-            for (const [index, { seq, created }] of stored.entries())
-                receive(index, seq, created);
-        }
-        catch (error) {
-            throw this.#fail(error);
-        }
-        return refused === undefined ? { stored: stored.length } : { stored: stored.length, refused: refused.error };
-    }
-    /**
-     * The commits of a series in its backend transaction, until one is refused (`refuse`): each commit's check, then its
-     * writes; the metadata once, at the end.
-     */
-    async #writeSeries(executor, commits, refuse) {
-        const calls = { failed: false };
-        const watched = watchCalls(executor, calls);
-        const progress = {
-            stored: [],
-            last: undefined,
-            nextId: this.#ids.value,
-            changed: undefined,
-            statements: 0,
-        };
-        for (const commit of commits) {
-            const refusal = await this.#checkCommit(commit, watched, calls, progress);
-            if (refusal !== undefined) {
-                refuse(refusal.error);
-                break;
-            }
-            await this.#writeCommit(commit, executor, progress);
-        }
-        return this.#closeSeries(progress);
-    }
-    /**
-     * Runs `commit`'s check on a step at the series' next seq whose backend calls are watched; resolves with its refusal,
-     * if it refused. A check one of whose backend calls failed throws instead: a failure, not a refusal.
-     */
-    async #checkCommit(commit, watched, calls, progress) {
-        const step = new Step(watched, this.#nextSeq(progress), this.#ids, progress.changed ?? this.#catalog);
-        calls.failed = false;
-        try {
-            await commit.check(step);
-            return undefined;
-        }
-        catch (error) {
-            if (calls.failed)
-                throw error;
-            return { error };
-        }
-        finally {
-            progress.statements += step.statements;
-        }
-    }
-    /**
-     * Writes `commit` on its own step at the series' next seq (`#write`), unwatched, and keeps the table records it
-     * changed in a copy of the catalog, made only once one changed; a commit without writes takes no seq.
-     */
-    async #writeCommit(commit, executor, progress) {
-        const seq = this.#nextSeq(progress);
-        if (commit.writes.length === 0) {
-            progress.stored.push({ seq: seq - 1, created: [] });
-            return;
-        }
-        const step = new Step(executor, seq, this.#ids, progress.changed ?? this.#catalog);
-        progress.nextId = await this.#write(step, commit.writes);
-        progress.statements += step.statements;
-        if (step.tables.size > 0) {
-            progress.changed ??= new Map(this.#catalog);
-            for (const [name, record] of step.tables)
-                progress.changed.set(name, record);
-        }
-        progress.last = step;
-        progress.stored.push({ seq, created: step.created });
-    }
-    /** The seq the series' next commit takes. */
-    #nextSeq(progress) {
-        return (progress.last?.seq ?? this.#lastSeq) + 1;
-    }
-    /** Ends the series' writes with the metadata, once, after its last commit that wrote; returns what memory takes. */
-    async #closeSeries(progress) {
-        const { stored, last, nextId, changed, statements } = progress;
-        if (last === undefined)
-            return { stored, last: undefined, written: 0, statements };
-        await writeMeta(last, nextId);
-        return {
-            stored,
-            last: { seq: last.seq, nextId, tables: changed ?? new Map() },
-            written: last.seq - this.#lastSeq,
-            statements: statements + 1,
-        };
-    }
-    /**
-     * The step's writes inside its backend transaction: each staged write in its phase, the catalog, the outbox commit.
-     * Returns the allocator's value, taken once, after the writes applied (mints meanwhile only raise it); the metadata
-     * (`writeMeta`) is the caller's.
-     */
-    async #write(step, writes) {
-        const seq = step.seq;
-        const recorded = this.#outbox !== undefined ? [] : undefined;
-        for (const order of ORDER) {
-            for (const write of writes) {
-                if (write.order !== order)
-                    continue;
-                const done = await write.apply(step);
-                recorded?.push(...done);
-            }
-        }
-        await writeCatalog(step);
-        const nextId = this.#ids.value;
-        if (recorded !== undefined) {
-            await step.run(`INSERT INTO ${TABLES.outbox} (seq, format, next_id, writes) VALUES (?, ?, ?, ?)`, seq, OUTBOX_FORMAT, nextId, JSON.stringify(recorded));
-        }
-        return nextId;
-    }
-    /**
-     * Batch apply's turn (slice 6b §1.6, S5): refused (`invalid/args`) while an owner holds a claim (its memory would
-     * go stale) and once the store diverged; otherwise `apply` runs in the commit queue, in one backend transaction, and
-     * returns the position its last commit leaves (`lastSeq`, the allocator's value) and the tables it changed, which
-     * memory takes after `COMMIT`. `apply`'s own error rolls back and rejects as a refusal (a `Diverged` one marks the
-     * store diverged); any other failure stops the store.
-     */
-    replay(apply, isDivergence) {
-        try {
-            this.#assertReplayable();
-        }
-        catch (error) {
-            return Promise.reject(error);
-        }
-        const turn = this.#tail.then(() => this.#replay(apply, isDivergence));
-        this.#tail = turn.then(NOTHING, NOTHING);
-        return turn;
-    }
-    /** At its call and again at its turn: a claim or a divergence may come between the two. */
-    #assertReplayable() {
-        this.assertUsable();
-        if (this.#diverged)
-            throw invalid("args", "store: diverged; a batch can no longer apply");
-        if (this.claims.held)
-            throw invalid("args", "store: an owner holds claims; a batch would stale its memory");
-    }
-    async #replay(apply, isDivergence) {
-        this.#assertReplayable();
-        // While it applies, no owner may claim (and read) what it is changing.
-        const unlock = this.claims.lock();
-        try {
-            await this.#applyReplay(apply, isDivergence);
-        }
-        finally {
-            unlock();
-        }
-    }
-    async #applyReplay(apply, isDivergence) {
-        let thrown = NONE;
-        let replayed;
-        try {
-            replayed = await this.#db.transaction(async (executor) => {
-                try {
-                    return await apply(executor, this.#catalog);
-                }
-                catch (error) {
-                    thrown = error;
-                    throw error;
-                }
-            });
-        }
-        catch (error) {
-            if (error !== thrown)
-                throw this.#fail(error);
-            if (isDivergence(error))
-                this.#diverged = true;
-            throw error;
-        }
-        this.#lastSeq = replayed.lastSeq;
-        this.#committedNextId = replayed.nextId;
-        this.#ids.raise(replayed.nextId - 1);
-        for (const [name, record] of replayed.tables)
-            this.#catalog.set(name, record);
-    }
-    /** Whether the store has an outbox, which a replayed batch writes too. */
-    get recordsOutbox() {
-        return this.#outbox !== undefined;
-    }
-    /** Throws `unavailable/storage_failed` once the store stopped, `released` once it closed. */
-    assertUsable() {
-        const state = this.#state;
-        if (state.kind === "failed")
-            throw storageFailed(state.error);
-        if (state.kind === "closed")
-            throw new ChordError({ code: "released", reason: "closed", message: "store: closed" });
-    }
-    /** Stops the store after `error` (once; its host is told once); returns the error the caller rejects with. */
-    #fail(error) {
-        if (this.#state.kind === "open") {
-            this.#state = { kind: "failed", error };
-            this.#attachment?.failed(error);
-        }
-        return storageFailed(error);
-    }
-}
-/** Records `seq`, the step's, as the store's last, and the allocator's value `nextId`. */
-function writeMeta(step, nextId) {
-    return step.run(`UPDATE ${TABLES.meta} SET last_seq = ?, next_id = ? WHERE singleton = 1`, step.seq, nextId);
-}
-/**
- * `executor`, setting `calls.failed` when one of its calls throws, synchronously or by rejecting, with any value: a
- * check that throws then failed in the backend, not by its own decision.
- */
-function watchCalls(executor, calls) {
-    const watched = async (call) => {
-        try {
-            return await call();
-        }
-        catch (error) {
-            calls.failed = true;
-            throw error;
-        }
-    };
-    return {
-        exec: (sql) => watched(() => executor.exec(sql)),
-        run: (sql, ...params) => watched(() => executor.run(sql, ...params)),
-        runCounted: (sql, ...params) => watched(() => executor.runCounted(sql, ...params)),
-        get: (sql, ...params) => watched(() => executor.get(sql, ...params)),
-        all: (sql, ...params) => watched(() => executor.all(sql, ...params)),
-    };
-}
-/** The `unavailable/storage_failed` error of a stopped store, its backend error as the cause. */
-function storageFailed(error) {
-    return new ChordError({ code: "unavailable", reason: "storage_failed", message: "store: storage failed" }, { cause: error });
-}
-//# sourceMappingURL=store.js.map