@arki/journal 0.0.0-stage → 0.1.1

package/dist/journal.js

@@ -0,0 +1,181 @@
+/**
+ * The entry point: `initJournal`, the definition helpers it returns, and
+ * `createJournal`, which checks the handlers, builds each part with its
+ * dependencies and wires the public methods.
+ * May import every other file. No implementation file may import this one.
+ */
+import { getTableColumns, getTableName, is, lt } from 'drizzle-orm';
+import { getTableConfig, PgColumn } from 'drizzle-orm/pg-core';
+import { z } from 'zod';
+import { createCommandRunner } from './command.js';
+import { defineEntity } from './entity.js';
+import { JournalError } from './errors.js';
+import { defineEvent } from './event.js';
+import { bindEffect, bindTap, defineProjection, effectFor, tapFor } from './handlers.js';
+import { createHistory } from './history.js';
+import { createHookPoint } from './hooks.js';
+import { createAdmin, createCatchUp, createDrain, createStrandedJobs, createTapDispatch, createWorkers, } from './worker.js';
+import { createWriter } from './write.js';
+const emptyMeta = z.object({});
+function initFor() {
+    function init(options) {
+        return options?.meta === undefined
+            ? createInit(emptyMeta)
+            : createInit(options.meta);
+    }
+    return init;
+}
+/**
+ * `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 const initJournal = Object.assign(initFor(), {
+    tx: () => ({
+        create: initFor(),
+        db: () => ({ create: initFor() }),
+    }),
+    db: () => ({
+        create: initFor(),
+        tx: () => ({ create: initFor() }),
+    }),
+});
+/** A table with a column called `id`. The check is real; the guard narrows to `IdTable`. */
+function hasIdColumn(table) {
+    const columns = getTableColumns(table);
+    return is(columns.id, PgColumn);
+}
+function createInit(metaSchema) {
+    function entity(kind, table, options) {
+        if (options !== undefined) {
+            return defineEntity(kind, table, options.key);
+        }
+        if (!hasIdColumn(table)) {
+            throw new JournalError('BAD_DEFINITION', 'entity', kind, `journal: entity "${kind}": table "${getTableName(table)}" has no "id" column; pass { key: 'columnName' }`);
+        }
+        return defineEntity(kind, table, 'id');
+    }
+    return {
+        event: defineEvent,
+        entity,
+        command: (name, input, handler) => ({ name, input, handler }),
+        projection: (name, entity, on, opts) => defineProjection(name, entity, on, opts),
+        effect: effectFor(),
+        tap: tapFor(),
+        compose: config => {
+            const effects = (config.effects ?? []).map(effect => bindEffect(effect, config.services ?? {}));
+            const taps = (config.taps ?? []).map(tap => bindTap(tap, config.services ?? {}));
+            return createJournal(metaSchema, config.tables, config.projections ?? [], effects, taps);
+        },
+    };
+}
+/** Throws when two handlers of one kind share a name: the second would silently replace the first. */
+function assertUniqueNames(kind, handlers) {
+    const seen = new Set();
+    for (const { name } of handlers) {
+        if (seen.has(name))
+            throw new JournalError('BAD_DEFINITION', kind, name, `journal: duplicate ${kind} name "${name}"`);
+        seen.add(name);
+    }
+}
+function createJournal(metaSchema, tables, projections, effects, taps = []) {
+    assertUniqueNames('tap', taps);
+    const eventsSchema = getTableConfig(tables.events).schema;
+    const wakeChannel = eventsSchema === undefined ? 'journal_wake' : `${eventsSchema}_journal_wake`;
+    assertUniqueNames('effect', effects);
+    assertUniqueNames('projection', projections);
+    const entitiesByKind = new Map();
+    for (const handler of [...projections, ...effects]) {
+        for (const entity of handler.entities)
+            entitiesByKind.set(entity.kind, entity);
+    }
+    // `journal.drain`, `journal.wake` and `journal.run` are read from the journal object on each
+    // call, so the worker loop, `run`, a bound runner and an effect's `ctx.run` always use the methods the object holds.
+    const history = createHistory({ metaSchema, tables });
+    const inlineProjections = projections.filter(projection => projection.lane === 'inline');
+    const asyncProjections = projections.filter(projection => projection.lane === 'async');
+    const { write, adopt, writeWithValidatedMeta } = createWriter({
+        metaSchema,
+        tables,
+        projections: inlineProjections,
+        asyncProjections,
+        effects,
+        history,
+        wakeChannel,
+    });
+    const commandHooks = createHookPoint('command');
+    const effectHooks = createHookPoint('effect');
+    const run = createCommandRunner({
+        metaSchema,
+        writeWithValidatedMeta,
+        wake: () => journal.wake(),
+        hooks: commandHooks,
+        tables,
+    });
+    const drain = createDrain({
+        tables,
+        hooks: effectHooks,
+        effects,
+        history,
+        runOn: (db, cause) => (command, input, meta, call) => run(db, command, input, meta, call, cause),
+    });
+    const catching = createCatchUp({ tables, projections: asyncProjections, history });
+    const dispatch = createTapDispatch({ tables, taps, history });
+    const workers = createWorkers({
+        drain: (db, opts) => journal.drain(db, opts),
+        catchUp: (db, opts) => journal.catchUp(db, opts),
+        dispatch,
+        tapNames: taps.map(tap => tap.name),
+    });
+    const strandedJobs = createStrandedJobs({ tables, effectNames: effects.map(effect => effect.name) });
+    const admin = createAdmin({ tables, wake: () => journal.wake() });
+    const journal = {
+        write: (tx, entity, id, input) => write(tx, entity, id, input),
+        adopt: (tx, entity, id, input) => adopt(tx, entity, id, input),
+        run: (source, command, input, meta, opts) => run(source, command, input, meta, opts),
+        bind: (source, meta, opts) => (command, input, call) => journal.run(source, command, input, meta, { ...opts, ...call }),
+        replay: (db, entity, id, opts) => history.replay(db, entity, id, opts),
+        verify: (db, entity, id) => history.verify(db, entity, id),
+        repair: (db, entity, id) => history.repair(db, entity, id),
+        forget: (db, entity, id) => history.forget(db, entity, id),
+        pruneReceipts: async (db, opts) => {
+            const gone = await db
+                .delete(tables.receipts)
+                .where(lt(tables.receipts.recordedAt, opts.before))
+                .returning({ key: tables.receipts.key });
+            return gone.length;
+        },
+        rerun: (db, projection, opts) => {
+            if (projection.lane === 'async')
+                throw new JournalError('BAD_DEFINITION', 'projection', projection.name, `journal: projection "${projection.name}" is async; use reset and catchUp instead of rerun`);
+            return history.rerun(db, projection, opts);
+        },
+        catchUp: (db, opts) => catching.catchUp(db, opts),
+        reset: (db, projection, clear) => catching.reset(db, projection, clear),
+        cursors: db => catching.cursors(db),
+        drain: (db, opts) => drain(db, opts),
+        worker: (db, opts) => workers.worker(db, opts),
+        wake: () => workers.wakeAll(),
+        strandedJobs: db => strandedJobs(db),
+        jobs: (db, opts) => admin.jobs(db, opts),
+        retry: (db, jobId) => admin.retry(db, jobId),
+        discard: (db, jobId) => admin.discard(db, jobId),
+        wakeChannel,
+        hooks: { command: commandHooks.point, effect: effectHooks.point },
+        catalog: {
+            entities: [...entitiesByKind.values()].map(entity => ({
+                kind: entity.kind,
+                table: getTableName(entity.table),
+                events: [...entity.events.keys()],
+            })),
+            projections: projections.map(projection => projection.name),
+            effects: effects.map(effect => effect.name),
+            taps: taps.map(tap => tap.name),
+        },
+    };
+    return journal;
+}
+//# sourceMappingURL=journal.js.map

package/dist/journal.js.map

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

package/dist/listen.d.ts

@@ -0,0 +1,37 @@
+/**
+ * `listenOnPool`: the `WakeListener` for a `pg` pool. It borrows one client from
+ * the pool for as long as the worker runs, `LISTEN`s on the channel, and forwards
+ * each payload. A dropped connection is released and replaced after `retryMs`;
+ * notifications sent while it was gone are lost, which taps accept and polling
+ * covers for jobs. Typed by shape, so this file imports no driver.
+ * Leaf file: may import `debug` and `types` only.
+ */
+import type { WakeListener } from './types.js';
+/**
+ * Let the process exit while this timer waits. Node and Bun return a timer object
+ * with `unref`; browsers, Deno's web API and Hermes return a number, which never
+ * holds a process open, so there is nothing to do.
+ */
+export declare function unrefTimer(timer: unknown): void;
+/** The part of a `pg` pool client a listener uses. */
+export type ListenClient = {
+    query(text: string): Promise<unknown>;
+    on(event: 'notification', listener: (message: {
+        readonly channel: string;
+        readonly payload?: string;
+    }) => void): unknown;
+    on(event: 'error', listener: (error: Error) => void): unknown;
+    release(error?: Error | boolean): void;
+};
+/** The part of a `pg` pool a listener uses: `new pg.Pool(...)`, or a Drizzle node-postgres database's `$client`. */
+export type ListenPool = {
+    connect(): Promise<ListenClient>;
+};
+/**
+ * Hear `channel` on a dedicated client of `pool`: `journal.worker(db, { listen: listenOnPool(db.$client, journal.wakeChannel) })`.
+ * The first connection is made when the worker starts; if it fails, `start()` rejects.
+ */
+export declare function listenOnPool(pool: ListenPool, channel: string, opts?: {
+    readonly retryMs?: number;
+}): WakeListener;
+//# sourceMappingURL=listen.d.ts.map

package/dist/listen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listen.d.ts","sourceRoot":"","sources":["../src/listen.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG/C;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAG/C;AAED,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,EAAE,CACA,KAAK,EAAE,cAAc,EACrB,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GACnF,OAAO,CAAC;IACX,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,OAAO,CAAC;IAC9D,OAAO,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;CACxC,CAAC;AAEF,oHAAoH;AACpH,MAAM,MAAM,UAAU,GAAG;IAAE,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;CAAE,CAAC;AAE9D;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAqElH"}

package/dist/listen.js

@@ -0,0 +1,90 @@
+import { debugWorker } from './debug.js';
+/**
+ * Let the process exit while this timer waits. Node and Bun return a timer object
+ * with `unref`; browsers, Deno's web API and Hermes return a number, which never
+ * holds a process open, so there is nothing to do.
+ */
+export function unrefTimer(timer) {
+    if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function')
+        timer.unref();
+}
+/**
+ * Hear `channel` on a dedicated client of `pool`: `journal.worker(db, { listen: listenOnPool(db.$client, journal.wakeChannel) })`.
+ * The first connection is made when the worker starts; if it fails, `start()` rejects.
+ */
+export function listenOnPool(pool, channel, opts) {
+    const retryMs = opts?.retryMs ?? 1000;
+    const quoted = `"${channel.replaceAll('"', '""')}"`;
+    return async (onMessage) => {
+        let stopped = false;
+        let current;
+        let timer;
+        const connect = async () => {
+            const client = await pool.connect();
+            let released = false;
+            const drop = (error) => {
+                if (released)
+                    return;
+                released = true;
+                if (current === client)
+                    current = undefined;
+                client.release(error ?? true);
+            };
+            client.on('notification', message => {
+                if (message.channel === channel && message.payload !== undefined)
+                    onMessage(message.payload);
+            });
+            client.on('error', error => {
+                debugWorker.debug('listen {channel}: connection lost: {lost}', { channel, lost: error.message });
+                drop(error);
+                schedule();
+            });
+            try {
+                await client.query(`LISTEN ${quoted}`);
+            }
+            catch (error) {
+                drop(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            if (stopped) {
+                drop();
+                return;
+            }
+            current = client;
+            debugWorker.debug('listen {channel}: connected', { channel });
+        };
+        const schedule = () => {
+            if (stopped || timer !== undefined)
+                return;
+            timer = setTimeout(() => {
+                timer = undefined;
+                connect().catch((error) => {
+                    debugWorker.debug('listen {channel}: reconnect failed', {
+                        channel,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    schedule();
+                });
+            }, retryMs);
+            unrefTimer(timer);
+        };
+        await connect();
+        return async () => {
+            stopped = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            const client = current;
+            current = undefined;
+            if (client === undefined)
+                return;
+            try {
+                await client.query(`UNLISTEN ${quoted}`);
+                client.release();
+            }
+            catch (error) {
+                client.release(error instanceof Error ? error : true);
+            }
+        };
+    };
+}
+//# sourceMappingURL=listen.js.map

package/dist/listen.js.map

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

package/dist/orpc.d.ts

@@ -0,0 +1,21 @@
+/**
+ * - A `CommandError` becomes the `ORPCError` with the same code and message.
+ * - A `JournalError` with code `CONFLICT` becomes an `ORPCError('CONFLICT')`, a 409 the client can retry.
+ * - Anything else is returned unchanged: the app decides what it means.
+ *
+ * The original error is NOT attached as `cause`. The journal's message names the entity kind and
+ * id, and a host may log or serialize a cause. A host that wants the original logs it itself,
+ * in a middleware placed inside this one.
+ */
+export declare function toORPCError(error: unknown): unknown;
+/**
+ * The middleware form of `toORPCError`. Add it once to the app's procedure
+ * builders, and no procedure needs a try/catch around a command.
+ *
+ * Order: put it INSIDE the app's own error middleware, so after it in the
+ * chain: `os.use(appErrors).use(commandErrors())`. A rejected rule is then
+ * already an `ORPCError` when the app's middleware sees it, and passes. Placed
+ * before it, the app's middleware sees a plain error first and answers 500.
+ */
+export declare function commandErrors(): import("@orpc/server").DecoratedMiddleware<Record<never, never>, Record<never, never>, unknown, any, any, Record<never, never>>;
+//# sourceMappingURL=orpc.d.ts.map

package/dist/orpc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orpc.d.ts","sourceRoot":"","sources":["../src/orpc.ts"],"names":[],"mappings":"AAsBA;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQnD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,oIAQ5B"}

package/dist/orpc.js

@@ -0,0 +1,57 @@
+/**
+ * `@orpc/server` adapter: what an oRPC client sees when a command fails.
+ *
+ * - `toORPCError(error)` maps one error.
+ * - `commandErrors()` is the middleware that maps whatever a procedure throws.
+ *
+ * `@orpc/server` is an optional peer. Import this module only in an app that
+ * serves oRPC. May import `errors` only; this is the one file that may import
+ * `@orpc/server`.
+ */
+import { ORPCError, os } from '@orpc/server';
+import { CommandError, isJournalError } from './errors.js';
+/**
+ * Another request changed the same entity first, or the client's `expectedVersion`
+ * is behind. Nothing was written. Repeating the same request as it stands fails
+ * again when a version was given, so the client reloads first. The journal's own
+ * message names the entity kind and id; the client does not get those.
+ */
+const CONFLICT_MESSAGE = 'This was changed by another request. Reload the current state and try again.';
+/**
+ * - A `CommandError` becomes the `ORPCError` with the same code and message.
+ * - A `JournalError` with code `CONFLICT` becomes an `ORPCError('CONFLICT')`, a 409 the client can retry.
+ * - Anything else is returned unchanged: the app decides what it means.
+ *
+ * The original error is NOT attached as `cause`. The journal's message names the entity kind and
+ * id, and a host may log or serialize a cause. A host that wants the original logs it itself,
+ * in a middleware placed inside this one.
+ */
+export function toORPCError(error) {
+    if (error instanceof CommandError) {
+        return new ORPCError(error.code, { message: error.message });
+    }
+    if (isJournalError(error, 'CONFLICT')) {
+        return new ORPCError('CONFLICT', { message: CONFLICT_MESSAGE });
+    }
+    return error;
+}
+/**
+ * The middleware form of `toORPCError`. Add it once to the app's procedure
+ * builders, and no procedure needs a try/catch around a command.
+ *
+ * Order: put it INSIDE the app's own error middleware, so after it in the
+ * chain: `os.use(appErrors).use(commandErrors())`. A rejected rule is then
+ * already an `ORPCError` when the app's middleware sees it, and passes. Placed
+ * before it, the app's middleware sees a plain error first and answers 500.
+ */
+export function commandErrors() {
+    return os.middleware(async ({ next }) => {
+        try {
+            return await next();
+        }
+        catch (error) {
+            throw toORPCError(error);
+        }
+    });
+}
+//# sourceMappingURL=orpc.js.map

package/dist/orpc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orpc.js","sourceRoot":"","sources":["../src/orpc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,8EAA8E,CAAC;AAExG;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,cAAc,CAAC,KAAK,EAAE,UAAU,CAAC,EAAE,CAAC;QACtC,OAAO,IAAI,SAAS,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE;QACtC,IAAI,CAAC;YACH,OAAO,MAAM,IAAI,EAAE,CAAC;QACtB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,WAAW,CAAC,KAAK,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}