@arki/journal 0.0.0-stage → 0.1.0

package/dist/history.js

@@ -0,0 +1,259 @@
+import { and, asc, eq, gt, inArray, max, sql } from 'drizzle-orm';
+import { debugReplay } from './debug.js';
+import { JournalError } from './errors.js';
+import { findEventDefinition, fold, hasDeclaredEventType } from './fold.js';
+import { assertExactId, assertStoredId, assertStoredValues, deepFreeze, isRowOf, loadRow, sameValue, saveReplayed, toRecord, } from './storage.js';
+/**
+ * Every version from 1 to the top must be stored. A hole means an event was lost
+ * after it was written. Folding around it would build a row the real history never
+ * produced, and `repair` would save it. The rows come ordered by version, and the
+ * unique index allows one row per version, so position and version must agree.
+ */
+function assertNoHoles(kind, id, rows) {
+    for (const [index, row] of rows.entries()) {
+        if (row.version !== index + 1) {
+            throw new JournalError('HISTORY_GAP', kind, id, `version ${index + 1} is missing from the log; the next stored version is ${row.version}`);
+        }
+    }
+}
+/**
+ * A stored row newer than a log that says the entity is alive lost its last events.
+ * Repair would quietly roll the row back, so replay refuses instead. When the log
+ * says the entity is gone, a row at any version was placed outside the journal and
+ * repair removes it: see `assertLogSaysGone`.
+ */
+function assertRowNotAhead(kind, id, folded, top, current) {
+    if (folded === null || current === null)
+        return;
+    if ('version' in current && typeof current.version === 'number' && current.version > top) {
+        throw new JournalError('HISTORY_GAP', kind, id, `the row is at version ${current.version} but the log ends at version ${top}`);
+    }
+}
+export function createHistory(deps) {
+    const { metaSchema } = deps;
+    const eventsTable = deps.tables.events;
+    /**
+     * Turn a stored log row into a recorded event, parsing data and meta with
+     * their current schemas. `id` is the row's entity id as the caller types it.
+     */
+    /**
+     * Lift a row's data from the schema version it was written at to the event's current
+     * one, one step at a time. Each step parses with its own `from` schema first, so a bad
+     * row names the version it failed at. Data already at the current version is returned as is.
+     */
+    const upcast = (row, def, at) => {
+        const fail = (why) => {
+            throw new JournalError('REPLAY_FAILED', row.kind, row.entityId, `${at}: ${why}`);
+        };
+        if (row.schemaVersion > def.version) {
+            return fail(`written at schema version ${row.schemaVersion}, but the event declares version ${def.version}`);
+        }
+        let value = row.data;
+        for (let version = row.schemaVersion; version < def.version; version += 1) {
+            const step = def.upcasters[version - 1];
+            if (step === undefined)
+                return fail(`no upcaster for schema version ${version}`);
+            const old = step.from.safeParse(value);
+            if (!old.success)
+                return fail(`the data does not fit schema version ${version}: ${old.error.message}`);
+            try {
+                value = step.up(old.data);
+            }
+            catch (error) {
+                return fail(`the upcaster from version ${version} threw: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        return value;
+    };
+    const decodeStoredEvent = (row, def, id) => {
+        const at = `event ${row.id} ("${row.type}" at version ${row.version})`;
+        if (def === undefined) {
+            throw new JournalError('REPLAY_FAILED', row.kind, row.entityId, `${at}: the entity declares no event of this type`);
+        }
+        const data = def.schema.safeParse(upcast(row, def, at));
+        if (!data.success) {
+            const after = row.schemaVersion < def.version ? ` after upcasting from version ${row.schemaVersion}` : '';
+            throw new JournalError('REPLAY_FAILED', row.kind, row.entityId, `${at}: the data does not fit the current schema${after}: ${data.error.message}`);
+        }
+        const meta = metaSchema.safeParse(row.meta);
+        if (!meta.success) {
+            throw new JournalError('REPLAY_FAILED', row.kind, row.entityId, `${at}: the meta does not fit the current meta schema: ${meta.error.message}`);
+        }
+        // Events are recorded facts: read-only for every reducer, projection, effect and caller.
+        return deepFreeze({
+            type: row.type,
+            data: data.data,
+            seq: row.seq,
+            id: row.id,
+            kind: row.kind,
+            entityId: id,
+            version: row.version,
+            meta: meta.data,
+            recordedAt: row.recordedAt,
+            commandId: row.commandId,
+            causeSeq: row.causeSeq,
+            correlationId: row.correlationId,
+            erasedAt: row.erasedAt,
+        });
+    };
+    const loadHistory = async (db, kind, id) => db
+        .select()
+        .from(eventsTable)
+        .where(and(eq(eventsTable.kind, kind), eq(eventsTable.entityId, id)))
+        .orderBy(asc(eventsTable.version));
+    const highestVersion = async (db, kind, id) => {
+        const [top] = await db
+            .select({ version: max(eventsTable.version) })
+            .from(eventsTable)
+            .where(and(eq(eventsTable.kind, kind), eq(eventsTable.entityId, id)));
+        return top?.version ?? 0;
+    };
+    const replayFrom = async (db, entity, id, current, throughVersion) => {
+        // The whole log, so `throughVersion` cannot hide an incomplete history behind an empty result.
+        const rows = await loadHistory(db, entity.kind, id);
+        const first = rows[0];
+        if (first === undefined && current !== null) {
+            throw new JournalError('NO_HISTORY', entity.kind, id, 'the row exists but the log holds no event for it');
+        }
+        // Version 1 is only ever written by a create from no row. A history that starts
+        // later belongs to a row that existed before the journal; folding it from nothing
+        // would pick the wrong reducers.
+        if (first !== undefined && first.version !== 1) {
+            throw new JournalError('NO_HISTORY', entity.kind, id, `the first stored version is ${first.version}`);
+        }
+        assertNoHoles(entity.kind, id, rows);
+        const all = decodeHistory(entity, id, rows);
+        // The whole history decides whether the entity is alive, whatever `throughVersion` says.
+        const full = fold(entity, null, id, all, 'replay').row;
+        assertRowNotAhead(entity.kind, id, full, rows.at(-1)?.version ?? 0, current);
+        const events = throughVersion === undefined ? all : all.filter(event => event.version <= throughVersion);
+        debugReplay.debug('{kind} {id}: {eventsLength} events', { kind: entity.kind, id, eventsLength: events.length });
+        return { row: throughVersion === undefined ? full : fold(entity, null, id, events, 'replay').row, events };
+    };
+    /** Decodes every row. The filter only narrows the type and drops nothing: see `hasDeclaredEventType`. */
+    const decodeHistory = (entity, id, rows) => rows
+        .map(row => decodeStoredEvent(row, entity.events.get(row.type), id))
+        .filter(event => hasDeclaredEventType(entity, event));
+    /**
+     * No row, but a log. Either a create follows a delete, or the row was removed
+     * outside the journal. The log decides: a history that starts at 1 is complete,
+     * and if it folds to a row, that row should be there. Creating over it would make
+     * write and replay pick different reducers for the same event. A history that
+     * starts later belongs to a pre-journal row and cannot be replayed, so it passes.
+     */
+    const assertLogSaysGone = async (db, entity, id, latestLogVersion) => {
+        const rows = await loadHistory(db, entity.kind, id);
+        if (rows[0]?.version !== 1)
+            return;
+        if (fold(entity, null, id, decodeHistory(entity, id, rows), 'replay').row !== null) {
+            throw new JournalError('CONFLICT', entity.kind, id, `the row is missing but its history says it exists at version ${latestLogVersion}; it was removed outside the journal, and repair restores it`);
+        }
+    };
+    const replay = async (db, entity, id, opts) => {
+        assertExactId(entity, id);
+        const current = await loadRow(db, entity, id, false);
+        return replayFrom(db, entity, id, current, opts?.throughVersion);
+    };
+    const verify = async (db, entity, id) => {
+        assertExactId(entity, id);
+        const loaded = await loadRow(db, entity, id, false);
+        assertStoredId(entity, loaded, id);
+        if (loaded !== null && !isRowOf(entity.table, loaded)) {
+            throw new Error(`journal: ${entity.kind} ${id} row is missing columns`);
+        }
+        const actual = loaded;
+        const { row: expected } = await replayFrom(db, entity, id, actual);
+        if (expected === null && actual === null)
+            return { ok: true };
+        if (expected === null || actual === null)
+            return { ok: false, expected, actual };
+        const want = toRecord(expected);
+        const have = toRecord(actual);
+        const ok = Object.keys(want).every(key => sameValue(want[key], have[key]));
+        return ok ? { ok: true } : { ok: false, expected, actual };
+    };
+    const repair = async (db, entity, id) => {
+        assertExactId(entity, id);
+        return db.transaction(async (tx) => {
+            const current = await loadRow(tx, entity, id, true);
+            assertStoredId(entity, current, id);
+            const { row: expected } = await replayFrom(tx, entity, id, current);
+            debugReplay.debug('{kind} {id}: repair -> {value3}', {
+                kind: entity.kind,
+                id,
+                value3: expected === null ? 'delete' : `v${expected.version}`,
+            });
+            const saved = await saveReplayed(tx, entity, id, current, expected);
+            // Throwing rolls the transaction back, so the row stays as it was.
+            if (saved !== null && expected !== null)
+                assertStoredValues(entity, id, expected, saved, Object.keys(expected));
+            return saved;
+        });
+    };
+    const forget = async (db, entity, id) => {
+        assertExactId(entity, id);
+        return db.transaction(async (tx) => {
+            // The row lock first, so no write lands between the rewrite and the repair. Then every
+            // async cursor, so no projection batch in flight commits the data after it was erased.
+            await loadRow(tx, entity, id, true);
+            await tx.select({ name: deps.tables.cursors.name }).from(deps.tables.cursors).for('update');
+            const rows = await loadHistory(tx, entity.kind, id);
+            let erased = 0;
+            for (const row of rows) {
+                const def = entity.events.get(row.type);
+                if (def?.erased === undefined)
+                    continue;
+                // Decode as replay does, so the erased form starts from data the schema accepts.
+                const event = decodeStoredEvent(row, def, id);
+                const form = def.schema.safeParse(def.erased(event.data));
+                if (!form.success) {
+                    throw new JournalError('BAD_DEFINITION', entity.kind, id, `event "${row.type}": its erased form does not fit its own schema: ${form.error.message}`);
+                }
+                await tx
+                    .update(eventsTable)
+                    .set({
+                    data: form.data,
+                    schemaVersion: def.version,
+                    erasedAt: sql `coalesce(${eventsTable.erasedAt}, now())`,
+                })
+                    .where(eq(eventsTable.seq, row.seq));
+                erased += 1;
+            }
+            // The row must match the history it now has. Repair on `tx` is a savepoint.
+            const row = await repair(tx, entity, id);
+            debugReplay.debug('{kind} {id}: forget -> {erased} events erased', { kind: entity.kind, id, erased });
+            return { erased, row };
+        });
+    };
+    const rerun = async (db, projection, opts) => {
+        const batchSize = opts?.batchSize ?? 100;
+        const kinds = projection.entities.map(entity => entity.kind);
+        let cursor = opts?.afterSeq ?? 0;
+        let count = 0;
+        if (kinds.length === 0 || projection.types.size === 0)
+            return { events: 0 };
+        for (;;) {
+            const rows = await db
+                .select()
+                .from(eventsTable)
+                .where(and(gt(eventsTable.seq, cursor), inArray(eventsTable.kind, kinds), inArray(eventsTable.type, [...projection.types])))
+                .orderBy(asc(eventsTable.seq))
+                .limit(batchSize);
+            if (rows.length === 0)
+                break;
+            await db.transaction(async (tx) => {
+                for (const row of rows) {
+                    await projection.run(tx, decodeStoredEvent(row, findEventDefinition(projection.entities, row.kind, row.type), row.entityId));
+                }
+            });
+            count += rows.length;
+            cursor = rows.at(-1)?.seq ?? cursor;
+            if (rows.length < batchSize)
+                break;
+        }
+        debugReplay.debug('rerun {projectionName}: {count} events', { projectionName: projection.name, count });
+        return { events: count };
+    };
+    return { decodeStoredEvent, highestVersion, assertLogSaysGone, replay, verify, repair, forget, rerun };
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

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

package/dist/hooks.d.ts

@@ -0,0 +1,14 @@
+/** A hook. `next` runs the rest of the chain and the work itself. It gives no result and takes no input. */
+export type Around<Ctx> = (ctx: Ctx, next: () => Promise<void>) => Promise<void>;
+/** What the app sees: register only. */
+export type HookPoint<Ctx> = {
+    /** Wrap every run. Throws `BAD_DEFINITION` once the journal has run a command, a drain or a worker. */
+    around(hook: Around<Ctx>): void;
+};
+export declare function createHookPoint<Ctx extends object>(what: 'command' | 'effect'): {
+    point: HookPoint<Ctx>;
+    freeze: () => void;
+    run: <T>(ctx: Ctx, work: () => Promise<T>) => Promise<T>;
+};
+export type HookPointInternal<Ctx extends object> = ReturnType<typeof createHookPoint<Ctx>>;
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAWA,4GAA4G;AAC5G,MAAM,MAAM,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjF,wCAAwC;AACxC,MAAM,MAAM,SAAS,CAAC,GAAG,IAAI;IAC3B,uGAAuG;IACvG,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;CACjC,CAAC;AAEF,wBAAgB,eAAe,CAAC,GAAG,SAAS,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,QAAQ;;kBAmBzD,IAAI;UAKJ,CAAC,OAAO,GAAG,QAAQ,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC;EAsCpE;AAED,MAAM,MAAM,iBAAiB,CAAC,GAAG,SAAS,MAAM,IAAI,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,CAAC,CAAC,CAAC"}

package/dist/hooks.js

@@ -0,0 +1,67 @@
+/**
+ * Around-hooks: the one way to extend a command run or an effect run from the
+ * outside. A hook receives the context and `next`, and runs inside the same
+ * transaction (commands) or lease (effects). The rules, all enforced here:
+ * `next` exactly once, or throw before it to stop; a rejection of `next` is the
+ * hook's rejection too; the context is frozen; hooks run in registration order,
+ * the first one outermost; registration is frozen once the journal has done work.
+ * Leaf file: may import `errors` only.
+ */
+import { JournalError } from './errors.js';
+export function createHookPoint(what) {
+    const hooks = [];
+    let frozen = false;
+    const point = {
+        around(hook) {
+            if (frozen) {
+                throw new JournalError('BAD_DEFINITION', 'hook', what, `journal: ${what} hooks are frozen once the journal has run a command, a drain or a worker; register hooks at boot, before any work`);
+            }
+            hooks.push(hook);
+        },
+    };
+    /** From now on, `around` throws. Called by the first `run` or `drain`. */
+    const freeze = () => {
+        frozen = true;
+    };
+    /** Run `work` inside every registered hook. The result is the work's own; no hook can change it. */
+    const run = async (ctx, work) => {
+        if (hooks.length === 0)
+            return work();
+        const frozenCtx = Object.freeze(ctx);
+        let result;
+        const layer = async (index) => {
+            const hook = hooks[index];
+            if (hook === undefined) {
+                result = { value: await work() };
+                return;
+            }
+            let calls = 0;
+            let failure;
+            const next = async () => {
+                calls += 1;
+                if (calls > 1)
+                    throw new Error(`journal: a ${what} hook called next twice; next runs the ${what} and may run once`);
+                try {
+                    await layer(index + 1);
+                }
+                catch (error) {
+                    failure = { error };
+                    throw error;
+                }
+            };
+            await hook(frozenCtx, next);
+            // A hook that swallowed the failure would turn a rolled-back command into a success for the caller.
+            if (failure !== undefined)
+                throw failure.error;
+            if (calls === 0) {
+                throw new Error(`journal: a ${what} hook returned without calling next; call next to run the ${what}, or throw to stop it`);
+            }
+        };
+        await layer(0);
+        if (result === undefined)
+            throw new Error(`journal: the ${what} did not run`);
+        return result.value;
+    };
+    return { point, freeze, run };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAW3C,MAAM,UAAU,eAAe,CAAqB,IAA0B;IAC5E,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,IAAI,MAAM,GAAG,KAAK,CAAC;IAEnB,MAAM,KAAK,GAAmB;QAC5B,MAAM,CAAC,IAAI;YACT,IAAI,MAAM,EAAE,CAAC;gBACX,MAAM,IAAI,YAAY,CACpB,gBAAgB,EAChB,MAAM,EACN,IAAI,EACJ,YAAY,IAAI,oHAAoH,CACrI,CAAC;YACJ,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;IAEF,0EAA0E;IAC1E,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,MAAM,GAAG,IAAI,CAAC;IAChB,CAAC,CAAC;IAEF,oGAAoG;IACpG,MAAM,GAAG,GAAG,KAAK,EAAK,GAAQ,EAAE,IAAsB,EAAc,EAAE;QACpE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,MAAyC,CAAC;QAC9C,MAAM,KAAK,GAAG,KAAK,EAAE,KAAa,EAAiB,EAAE;YACnD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBACvB,MAAM,GAAG,EAAE,KAAK,EAAE,MAAM,IAAI,EAAE,EAAE,CAAC;gBACjC,OAAO;YACT,CAAC;YACD,IAAI,KAAK,GAAG,CAAC,CAAC;YACd,IAAI,OAAgD,CAAC;YACrD,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;gBACrC,KAAK,IAAI,CAAC,CAAC;gBACX,IAAI,KAAK,GAAG,CAAC;oBACX,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,0CAA0C,IAAI,mBAAmB,CAAC,CAAC;gBACvG,IAAI,CAAC;oBACH,MAAM,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;gBACzB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,GAAG,EAAE,KAAK,EAAE,CAAC;oBACpB,MAAM,KAAK,CAAC;gBACd,CAAC;YACH,CAAC,CAAC;YACF,MAAM,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC5B,oGAAoG;YACpG,IAAI,OAAO,KAAK,SAAS;gBAAE,MAAM,OAAO,CAAC,KAAK,CAAC;YAC/C,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,MAAM,IAAI,KAAK,CACb,cAAc,IAAI,6DAA6D,IAAI,uBAAuB,CAC3G,CAAC;YACJ,CAAC;QACH,CAAC,CAAC;QACF,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACf,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,cAAc,CAAC,CAAC;QAC9E,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC,CAAC;IAEF,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;AAChC,CAAC"}

package/dist/id.d.ts

@@ -0,0 +1,18 @@
+export declare const eventId: () => `evt_${string}`;
+export declare const jobId: () => `job_${string}`;
+export declare const commandId: () => `cmd_${string}`;
+export declare const correlationId: () => `cor_${string}`;
+export declare const leaseToken: () => string;
+declare const NAME_KINDS: {
+    readonly 'entity kind': 64;
+    readonly 'event type': 128;
+    readonly 'effect name': 128;
+};
+/**
+ * Throws unless `name` fits the `varchar` column the journal stores it in: non-empty,
+ * well-formed UTF-16 (a lone surrogate would be stored as U+FFFD and alias another name),
+ * and at most the column length in code points. Hermes-safe: no `isWellFormed`, no lookbehind.
+ */
+export declare function assertStoredName(what: keyof typeof NAME_KINDS, name: string): void;
+export {};
+//# sourceMappingURL=id.d.ts.map

package/dist/id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,OAAO,uBAAyB,CAAC;AAC9C,eAAO,MAAM,KAAK,uBAAyB,CAAC;AAC5C,eAAO,MAAM,SAAS,uBAAyB,CAAC;AAChD,eAAO,MAAM,aAAa,uBAAyB,CAAC;AACpD,eAAO,MAAM,UAAU,cAAmB,CAAC;AAE3C,QAAA,MAAM,UAAU;aACd,aAAa,EAAE,EAAE;aACjB,YAAY,EAAE,GAAG;aACjB,aAAa,EAAE,GAAG;CACV,CAAC;AAEX;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,OAAO,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAyBlF"}

package/dist/id.js

@@ -0,0 +1,41 @@
+import { createId } from '@paralleldrive/cuid2';
+import { JournalError } from './errors.js';
+/**
+ * Same shape as `createPrefixedId` in `@arki/db/id`. That module is not
+ * imported because its value export pulls `drizzle-orm/pg-core` and
+ * `@arki/contracts` into browser bundles.
+ */
+const prefixed = (prefix) => `${prefix}${createId()}`;
+export const eventId = () => prefixed('evt_');
+export const jobId = () => prefixed('job_');
+export const commandId = () => prefixed('cmd_');
+export const correlationId = () => prefixed('cor_');
+export const leaseToken = () => createId();
+const NAME_KINDS = {
+    'entity kind': 64,
+    'event type': 128,
+    'effect name': 128,
+};
+/**
+ * Throws unless `name` fits the `varchar` column the journal stores it in: non-empty,
+ * well-formed UTF-16 (a lone surrogate would be stored as U+FFFD and alias another name),
+ * and at most the column length in code points. Hermes-safe: no `isWellFormed`, no lookbehind.
+ */
+export function assertStoredName(what, name) {
+    const limit = NAME_KINDS[what];
+    const shown = JSON.stringify(name);
+    if (name === '')
+        throw new JournalError('BAD_DEFINITION', what, shown, `journal: ${what} must not be empty`);
+    let length = 0;
+    for (const ch of name) {
+        const point = ch.codePointAt(0);
+        if (point !== undefined && point >= 55_296 && point <= 57_343) {
+            throw new JournalError('BAD_DEFINITION', what, shown, `journal: ${what} ${shown} has an unpaired surrogate; the database would store it as U+FFFD`);
+        }
+        length++;
+    }
+    if (length > limit) {
+        throw new JournalError('BAD_DEFINITION', what, shown, `journal: ${what} ${shown} is ${length} characters; the limit is ${limit}`);
+    }
+}
+//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAEhD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;GAIG;AACH,MAAM,QAAQ,GAAG,CAAmB,MAAS,EAAmB,EAAE,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,EAAE,CAAC;AAE5F,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC9C,MAAM,CAAC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAC5C,MAAM,CAAC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AAChD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;AACpD,MAAM,CAAC,MAAM,UAAU,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;AAE3C,MAAM,UAAU,GAAG;IACjB,aAAa,EAAE,EAAE;IACjB,YAAY,EAAE,GAAG;IACjB,aAAa,EAAE,GAAG;CACV,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA6B,EAAE,IAAY;IAC1E,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,IAAI,KAAK,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,gBAAgB,EAAE,IAAI,EAAE,KAAK,EAAE,YAAY,IAAI,oBAAoB,CAAC,CAAC;IAC7G,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAChC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,MAAM,EAAE,CAAC;YAC9D,MAAM,IAAI,YAAY,CACpB,gBAAgB,EAChB,IAAI,EACJ,KAAK,EACL,YAAY,IAAI,IAAI,KAAK,mEAAmE,CAC7F,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,CAAC;IACX,CAAC;IACD,IAAI,MAAM,GAAG,KAAK,EAAE,CAAC;QACnB,MAAM,IAAI,YAAY,CACpB,gBAAgB,EAChB,IAAI,EACJ,KAAK,EACL,YAAY,IAAI,IAAI,KAAK,OAAO,MAAM,6BAA6B,KAAK,EAAE,CAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { initJournal } from './journal.js';
+export { need } from './handlers.js';
+export type { Command, CommandContext, CommandRunner, Journal, JournalDefinitions, ReplayResult, RootCommandRunner, RunOptions, CallOptions, VerifyResult, ForgetResult, NextEvents, WriteInput, WriteOptions, WriteResult, } from './api.js';
+export { CommandError, JournalError, isCommandError, isJournalError } from './errors.js';
+export type { CommandErrorCode, JournalErrorCode } from './errors.js';
+export type { GuaranteedCreateKeys, EntityBuilder, OnReducerRow, OnOnlyEntityBuilder } from './entity.js';
+export type { AnyEntity, AnyEventDef, CreateReducer, DbHandle, Effect, EffectContext, EffectHandlers, EntityDef, EntityId, EntityIdOf, EntityInfo, EntityTable, EventDef, EventOptions, Upcaster, UpcasterSteps, ProjectionOptions, Tap, TapContext, TapHandlers, Unlisten, WakeListener, CommandHookContext, EffectHookContext, EventsOf, IdTable, KeyColumn, Need, Needed, Needs, ReducerValues, OnReducer, Patch, Pending, PendingOf, Projection, ProjectionHandlers, Recorded, RecordedOf, Reducers, ReducerRow, RootDb, Row, Services, ServicesFor, TransactionSource, JournalWorker, StrandedJobs, } from './types.js';
+export type { JournalTables } from './pg.js';
+export type { Around, HookPoint } from './hooks.js';
+export { listenOnPool } from './listen.js';
+export type { ListenClient, ListenPool } from './listen.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AACrC,YAAY,EACV,OAAO,EACP,cAAc,EACd,aAAa,EACb,OAAO,EACP,kBAAkB,EAClB,YAAY,EACZ,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,UAAU,EACV,YAAY,EACZ,WAAW,GACZ,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzF,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACtE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAC1G,YAAY,EACV,SAAS,EACT,WAAW,EACX,aAAa,EACb,QAAQ,EACR,MAAM,EACN,aAAa,EACb,cAAc,EACd,SAAS,EACT,QAAQ,EACR,UAAU,EACV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,GAAG,EACH,UAAU,EACV,WAAW,EACX,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,QAAQ,EACR,OAAO,EACP,SAAS,EACT,IAAI,EACJ,MAAM,EACN,KAAK,EACL,aAAa,EACb,SAAS,EACT,KAAK,EACL,OAAO,EACP,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,UAAU,EACV,MAAM,EACN,GAAG,EACH,QAAQ,EACR,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7C,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { initJournal } from './journal.js';
+export { need } from './handlers.js';
+export { CommandError, JournalError, isCommandError, isJournalError } from './errors.js';
+export { listenOnPool } from './listen.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAkBrC,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAuDzF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}

package/dist/journal.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import type { JournalDefinitions } from './api.js';
+import type { DbHandle, RootDb, TransactionSource } from './types.js';
+/**
+ * `initJournal({ meta })` types `write`'s `tx`, `events`' `{ tx }` and
+ * projection handlers with the structural `DbHandle`. `initJournal.tx<AppTx>()
+ * .create({ meta })` uses the app's own Drizzle transaction type instead, so
+ * repositories typed against it fit. `initJournal.db<AppDb>()` names the
+ * app's root database type: effects get it as `ctx.db`, and `drain` and
+ * `worker` then need it. Both are type-only steps and chain in either order.
+ */
+export declare const initJournal: {
+    (): JournalDefinitions<z.ZodObject<{}, z.core.$strip>, DbHandle, RootDb>;
+    <Meta extends z.ZodObject>(options: {
+        readonly meta: Meta;
+    }): JournalDefinitions<Meta, DbHandle, RootDb>;
+} & {
+    tx: <Tx extends TransactionSource<Tx>>() => {
+        create: {
+            (): JournalDefinitions<z.ZodObject<{}, z.core.$strip>, Tx, RootDb>;
+            <Meta extends z.ZodObject>(options: {
+                readonly meta: Meta;
+            }): JournalDefinitions<Meta, Tx, RootDb>;
+        };
+        db: <AppDb extends RootDb>() => {
+            create: {
+                (): JournalDefinitions<z.ZodObject<{}, z.core.$strip>, Tx, AppDb>;
+                <Meta extends z.ZodObject>(options: {
+                    readonly meta: Meta;
+                }): JournalDefinitions<Meta, Tx, AppDb>;
+            };
+        };
+    };
+    db: <AppDb extends RootDb>() => {
+        create: {
+            (): JournalDefinitions<z.ZodObject<{}, z.core.$strip>, DbHandle, AppDb>;
+            <Meta extends z.ZodObject>(options: {
+                readonly meta: Meta;
+            }): JournalDefinitions<Meta, DbHandle, AppDb>;
+        };
+        tx: <Tx extends TransactionSource<Tx>>() => {
+            create: {
+                (): JournalDefinitions<z.ZodObject<{}, z.core.$strip>, Tx, AppDb>;
+                <Meta extends z.ZodObject>(options: {
+                    readonly meta: Meta;
+                }): JournalDefinitions<Meta, Tx, AppDb>;
+            };
+        };
+    };
+};
+//# sourceMappingURL=journal.d.ts.map

package/dist/journal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"journal.d.ts","sourceRoot":"","sources":["../src/journal.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAW,kBAAkB,EAAqB,MAAM,UAAU,CAAC;AAG/E,OAAO,KAAK,EAGV,QAAQ,EAOR,MAAM,EAGN,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAkCpB;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;;KAnBR,IAAI,SAAS,CAAC,CAAC,SAAS;;;;SAoBjC,EAAE,SAAS,iBAAiB,CAAC,EAAE,CAAC;;;aApBvB,IAAI,SAAS,CAAC,CAAC,SAAS;;;;aAsB/B,KAAK,SAAS,MAAM;;;iBAtBb,IAAI,SAAS,CAAC,CAAC,SAAS;;;;;;SAwBjC,KAAK,SAAS,MAAM;;;aAxBX,IAAI,SAAS,CAAC,CAAC,SAAS;;;;aA0B/B,EAAE,SAAS,iBAAiB,CAAC,EAAE,CAAC;;;iBA1BzB,IAAI,SAAS,CAAC,CAAC,SAAS;;;;;;CA4BtC,CAAC"}