@arki/journal 0.0.0-stage → 0.1.1

package/dist/errors.js

@@ -0,0 +1,112 @@
+/** Per code: what happened, and what to do next. The throw site adds the detail (event type, version, column). */
+const MESSAGES = {
+    CONFLICT: {
+        what: 'the row and its event history cannot accept this write',
+        next: 'If another writer appended first, run the command again on the current state. If the row and the history disagree, check with `verify`, and use `repair` only when the history is complete',
+    },
+    NO_ROW: {
+        what: 'no row exists, and this event has no `.create` reducer',
+        next: 'Create the entity first, or declare `.create` for this event on the entity',
+    },
+    ROW_EXISTS: {
+        what: 'a row exists, and this event has no `.on` reducer',
+        next: 'Write an update event instead, or declare `.on` for this event on the entity',
+    },
+    UNKNOWN_EVENT: {
+        what: 'the entity does not declare this event',
+        next: 'Add `.create(Event, ...)` or `.on(Event, ...)` for it on this entity, or write it to the entity that declares it',
+    },
+    VERSION_MISMATCH: {
+        what: 'no row matched the expected version when saving',
+        next: 'The row version changed, or the row was removed, after this write locked it. Look for a statement that does this outside the journal (for example a direct update or delete inside `events`), then run the command again',
+    },
+    NO_HISTORY: {
+        what: 'a complete history that starts at version 1 is not available',
+        next: 'Replay and repair cannot rebuild this row. Check whether the row existed before the journal, or restore the missing events',
+    },
+    HISTORY_GAP: {
+        what: 'the log has a hole, or the row is newer than a log that says it is alive',
+        next: 'An event was lost after it was written. Replay and repair refuse to build a row the real history never produced. Restore the missing event from a backup, or accept the row as it is',
+    },
+    REPLAY_FAILED: {
+        what: 'a stored event cannot be decoded or applied',
+        next: 'Check the event schema and the reducers against the stored history',
+    },
+    UNSTABLE_SCHEMA: {
+        what: 'the value changes or fails across JSON storage and a second parse',
+        next: 'Return JSON-compatible data that the schema accepts unchanged, because replay parses stored data again',
+    },
+    ID_MISMATCH: {
+        what: 'the entity id is not valid, or differs from its stored spelling',
+        next: 'Use a non-empty, well-formed id within the limit, spelled exactly as stored. A uuid must be lower-case and hyphenated',
+    },
+    VALUE_MISMATCH: {
+        what: 'the database stored a different value than the reducer produced',
+        next: 'The write was rolled back. Make the reducer produce the value in the form the column stores',
+    },
+    BAD_DEFINITION: {
+        what: 'a declaration is wrong',
+        next: 'Fix the declaration named in the detail. It is thrown when the module that declares it loads, so no data was touched',
+    },
+};
+/**
+ * An error about one entity's row or history: a write, replay, verify or repair
+ * that the journal refuses. Match on `code`, never on the message.
+ *
+ * Not every error the journal lets out is a `JournalError`:
+ * - A wrong definition is a `JournalError` with code `BAD_DEFINITION`, thrown when the
+ *   declaration runs (a bad name, a bad key column, a duplicate reducer or handler name).
+ * - A misuse at run time is a plain `Error` whose message starts with `journal:` (two
+ *   operations at once on one transaction, `drain` inside a transaction).
+ * - Command input, event data or `meta` that fails its schema is a `ZodError`.
+ * - An error thrown by a command handler, an `events` function, a reducer or a
+ *   projection passes through unchanged. A rejected business rule is one of
+ *   these: a `CommandError`, below.
+ * An error thrown by an effect is caught by `drain` and stored on the job.
+ */
+export class JournalError extends Error {
+    code;
+    kind;
+    entityId;
+    /** The message reads: `CODE: what happened (kind id): detail. What to do next.` */
+    constructor(code, kind, entityId, detail, options) {
+        const { what, next } = MESSAGES[code];
+        const where = `${code}: ${what} (${kind} ${entityId})`;
+        const happened = detail === undefined ? where : `${where}: ${detail}`;
+        super(`${happened}. ${next}.`, options);
+        this.name = 'JournalError';
+        this.code = code;
+        this.kind = kind;
+        this.entityId = entityId;
+    }
+}
+export function isJournalError(error, code) {
+    return error instanceof JournalError && (code === undefined || error.code === code);
+}
+/**
+ * A business rule rejected the request. App code throws it: a command handler,
+ * or the `events` function of a `write`. The code names the kind of answer and
+ * the message is written for the client.
+ *
+ * It is NOT a `JournalError`. A `JournalError` is the library's own failure: a
+ * row or a history it refuses. A `CommandError` is the app's rule saying no.
+ * The library never throws one and never changes one: like every error thrown
+ * by app code, it leaves `journal.run` as the same instance, after the
+ * command's transaction rolled back.
+ *
+ * Nothing here knows HTTP. The host maps the code to its own transport:
+ * `@arki/journal/orpc` does it for oRPC, and any other host matches on the
+ * code with `isCommandError`.
+ */
+export class CommandError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CommandError';
+        this.code = code;
+    }
+}
+export function isCommandError(error, code) {
+    return error instanceof CommandError && (code === undefined || error.code === code);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAcA,kHAAkH;AAClH,MAAM,QAAQ,GAA+E;IAC3F,QAAQ,EAAE;QACR,IAAI,EAAE,wDAAwD;QAC9D,IAAI,EAAE,4LAA4L;KACnM;IACD,MAAM,EAAE;QACN,IAAI,EAAE,wDAAwD;QAC9D,IAAI,EAAE,4EAA4E;KACnF;IACD,UAAU,EAAE;QACV,IAAI,EAAE,mDAAmD;QACzD,IAAI,EAAE,8EAA8E;KACrF;IACD,aAAa,EAAE;QACb,IAAI,EAAE,wCAAwC;QAC9C,IAAI,EAAE,kHAAkH;KACzH;IACD,gBAAgB,EAAE;QAChB,IAAI,EAAE,iDAAiD;QACvD,IAAI,EAAE,0NAA0N;KACjO;IACD,UAAU,EAAE;QACV,IAAI,EAAE,8DAA8D;QACpE,IAAI,EAAE,4HAA4H;KACnI;IACD,WAAW,EAAE;QACX,IAAI,EAAE,0EAA0E;QAChF,IAAI,EAAE,sLAAsL;KAC7L;IACD,aAAa,EAAE;QACb,IAAI,EAAE,6CAA6C;QACnD,IAAI,EAAE,oEAAoE;KAC3E;IACD,eAAe,EAAE;QACf,IAAI,EAAE,mEAAmE;QACzE,IAAI,EAAE,wGAAwG;KAC/G;IACD,WAAW,EAAE;QACX,IAAI,EAAE,iEAAiE;QACvE,IAAI,EAAE,uHAAuH;KAC9H;IACD,cAAc,EAAE;QACd,IAAI,EAAE,iEAAiE;QACvE,IAAI,EAAE,6FAA6F;KACpG;IACD,cAAc,EAAE;QACd,IAAI,EAAE,wBAAwB;QAC9B,IAAI,EAAE,sHAAsH;KAC7H;CACF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IACvB,IAAI,CAAS;IACb,QAAQ,CAAS;IAE1B,mFAAmF;IACnF,YAAY,IAAsB,EAAE,IAAY,EAAE,QAAgB,EAAE,MAAe,EAAE,OAAsB;QACzG,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QACtC,MAAM,KAAK,GAAG,GAAG,IAAI,KAAK,IAAI,KAAK,IAAI,IAAI,QAAQ,GAAG,CAAC;QACvD,MAAM,QAAQ,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,MAAM,EAAE,CAAC;QACtE,KAAK,CAAC,GAAG,QAAQ,KAAK,IAAI,GAAG,EAAE,OAAO,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAuB;IACpE,OAAO,KAAK,YAAY,YAAY,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACtF,CAAC;AAKD;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IAC5B,IAAI,CAAmB;IAEhC,YAAY,IAAsB,EAAE,OAAe;QACjD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAuB;IACpE,OAAO,KAAK,YAAY,YAAY,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;AACtF,CAAC"}

package/dist/event.d.ts

@@ -0,0 +1,9 @@
+import type { z } from 'zod';
+import type { EventDef, EventOptions } from './types.js';
+/**
+ * Declare an event. Calling the result validates the data and returns a pending event.
+ * `opts.erased` gives the event's erased form for `forget`; see the README, Erasure.
+ * `opts.upcasters` lifts data stored under older schemas; see the README, Changing events later.
+ */
+export declare function defineEvent<T extends string, S extends z.ZodType, const U extends readonly z.ZodType[] = readonly []>(type: T, schema: S, opts?: EventOptions<S, U>): EventDef<T, S>;
+//# sourceMappingURL=event.d.ts.map

package/dist/event.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.d.ts","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAqB,MAAM,YAAY,CAAC;AAG5E;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,OAAO,EAAE,GAAG,SAAS,EAAE,EACnH,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,CAAC,EACT,IAAI,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GACxB,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAWhB"}

package/dist/event.js

@@ -0,0 +1,19 @@
+import { assertStoredName } from './id.js';
+/**
+ * Declare an event. Calling the result validates the data and returns a pending event.
+ * `opts.erased` gives the event's erased form for `forget`; see the README, Erasure.
+ * `opts.upcasters` lifts data stored under older schemas; see the README, Changing events later.
+ */
+export function defineEvent(type, schema, opts) {
+    assertStoredName('event type', type);
+    const upcasters = opts?.upcasters ?? [];
+    const make = (data) => ({ type, data: schema.parse(data) });
+    return Object.assign(make, {
+        type,
+        schema,
+        version: upcasters.length + 1,
+        upcasters,
+        ...(opts?.erased === undefined ? {} : { erased: opts.erased }),
+    });
+}
+//# sourceMappingURL=event.js.map

package/dist/event.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event.js","sourceRoot":"","sources":["../src/event.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,IAAO,EACP,MAAS,EACT,IAAyB;IAEzB,gBAAgB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACrC,MAAM,SAAS,GAAwB,IAAI,EAAE,SAAS,IAAI,EAAE,CAAC;IAC7D,MAAM,IAAI,GAAG,CAAC,IAAgB,EAA2B,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjG,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE;QACzB,IAAI;QACJ,MAAM;QACN,OAAO,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;QAC7B,SAAS;QACT,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC"}

package/dist/fold.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The fold that write and replay share: apply recorded events to a row in memory.
+ * Also the two lookups by event type. Pure functions: no database access, no state.
+ * May import `entity` and leaf files. Must not import `journal`, `api`, `write`,
+ * `command`, `history`, `storage` or `worker`.
+ */
+import type { AnyEntity, AnyEventDef, EntityDef, EntityId, EntityTable, Recorded, RecordedOf, ReducerRow, Row } from './types.js';
+type RecordedEvent<MetaOut> = Recorded<string, unknown, MetaOut>;
+export declare const findEventDefinition: <MetaOut>(entities: readonly AnyEntity<MetaOut>[], kind: string, type: string) => AnyEventDef | undefined;
+/**
+ * Fold events onto a starting state. A create event on a row, or a non-create
+ * event with no row, is `ROW_EXISTS` / `NO_ROW` during a write and
+ * `REPLAY_FAILED` when reading the log back. `recreated` is true when the state
+ * passed through `null` and ended non-null: the row is a new incarnation.
+ */
+export declare const fold: <Tbl extends EntityTable, Key extends string, MetaOut>(entity: EntityDef<string, Tbl, AnyEventDef, MetaOut, Key>, start: Row<Tbl> | null, id: EntityId<Tbl, Key>, history: readonly RecordedEvent<MetaOut>[], mode: 'write' | 'replay') => {
+    readonly row: ReducerRow<Tbl, Key> | null;
+    readonly recreated: boolean;
+    /** The columns the reducers set in this fold (since the last create). */
+    readonly reducerColumns: ReadonlySet<string>;
+};
+/**
+ * Narrows a decoded event to the entity's own event union. It is a type guard, not
+ * a filter for bad data: `decodeStoredEvent` has already thrown for a type the
+ * entity does not declare. Do not use it to skip stored events that fail to decode.
+ */
+export declare const hasDeclaredEventType: <E extends AnyEventDef, Id extends string, MetaOut>(entity: EntityDef<string, EntityTable, E, MetaOut, string>, event: Recorded<string, unknown, MetaOut, Id>) => event is RecordedOf<E, MetaOut, Id>;
+export {};
+//# sourceMappingURL=fold.d.ts.map

package/dist/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../src/fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,SAAS,EACT,WAAW,EACX,SAAS,EACT,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,UAAU,EACV,UAAU,EAEV,GAAG,EACJ,MAAM,YAAY,CAAC;AAIpB,KAAK,aAAa,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAEjE,eAAO,MAAM,mBAAmB,GAAI,OAAO,YAC/B,SAAS,SAAS,CAAC,OAAO,CAAC,EAAE,QACjC,MAAM,QACN,MAAM,KACX,WAAW,GAAG,SAA4E,CAAC;AAE9F;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,GAAG,SAAS,WAAW,EAAE,GAAG,SAAS,MAAM,EAAE,OAAO,UAC/D,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,CAAC,SAClD,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,MAClB,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,WACb,SAAS,aAAa,CAAC,OAAO,CAAC,EAAE,QACpC,OAAO,GAAG,QAAQ,KACvB;IACD,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAyC9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,WAAW,EAAE,EAAE,SAAS,MAAM,EAAE,OAAO,UAC5E,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,SACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,KAC5C,KAAK,IAAI,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAkC,CAAC"}

package/dist/fold.js

@@ -0,0 +1,49 @@
+import { reduceOne, withEntityIdentity } from './entity.js';
+import { JournalError } from './errors.js';
+export const findEventDefinition = (entities, kind, type) => entities.find(entity => entity.kind === kind)?.events.get(type);
+/**
+ * Fold events onto a starting state. A create event on a row, or a non-create
+ * event with no row, is `ROW_EXISTS` / `NO_ROW` during a write and
+ * `REPLAY_FAILED` when reading the log back. `recreated` is true when the state
+ * passed through `null` and ended non-null: the row is a new incarnation.
+ */
+export const fold = (entity, start, id, history, mode) => {
+    let state = start;
+    let deleted = false;
+    const reducerColumns = new Set();
+    for (const event of history) {
+        const reducers = entity.reducers.get(event.type);
+        // A write names the exact refusal. A replay reports each one as REPLAY_FAILED and says why.
+        const at = `event "${event.type}" at version ${event.version}`;
+        if (reducers === undefined) {
+            throw mode === 'write'
+                ? new JournalError('UNKNOWN_EVENT', entity.kind, id, at)
+                : new JournalError('REPLAY_FAILED', entity.kind, id, `${at} has no reducer on this entity`);
+        }
+        if (state !== null && reducers.on === undefined) {
+            throw mode === 'write'
+                ? new JournalError('ROW_EXISTS', entity.kind, id, at)
+                : new JournalError('REPLAY_FAILED', entity.kind, id, `${at} has no .on reducer, but the history has a row at that point`);
+        }
+        if (state === null && reducers.create === undefined) {
+            throw mode === 'write'
+                ? new JournalError('NO_ROW', entity.kind, id, at)
+                : new JournalError('REPLAY_FAILED', entity.kind, id, `${at} has no .create reducer, but the history has no row at that point`);
+        }
+        state = reduceOne(entity, state, id, event, reducerColumns);
+        if (state === null)
+            deleted = true;
+    }
+    if (state === null)
+        return { row: null, recreated: false, reducerColumns };
+    const last = history.at(-1);
+    const version = last === undefined ? (start === null ? 0 : start.version) : last.version;
+    return { row: withEntityIdentity(entity, state, id, version), recreated: deleted, reducerColumns };
+};
+/**
+ * Narrows a decoded event to the entity's own event union. It is a type guard, not
+ * a filter for bad data: `decodeStoredEvent` has already thrown for a type the
+ * entity does not declare. Do not use it to skip stored events that fail to decode.
+ */
+export const hasDeclaredEventType = (entity, event) => entity.events.has(event.type);
+//# sourceMappingURL=fold.js.map

package/dist/fold.js.map

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

package/dist/handlers.d.ts

@@ -0,0 +1,26 @@
+import type { AnyEntity, DbHandle, Effect, EffectHandlers, EffectSchedule, Need, Needs, Projection, ProjectionHandlers, ProjectionOptions, Services, Tap, TapHandlers } from './types.js';
+export declare function defineProjection<E extends AnyEntity<Meta>, Meta, Tx extends DbHandle>(name: string, entity: E | readonly E[], on: NoInfer<ProjectionHandlers<E, Meta, Tx>>, opts?: ProjectionOptions): Projection<Meta, Tx>;
+/** Declare one thing an effect needs: `j.effect('order-mail', order, { mailer: need<Mailer>() }, { ... })`. */
+export declare const need: <T>() => Need<T>;
+/** Attach a schedule to an effect, checked once: a job row must be able to hold it. */
+export declare function withSchedule<Meta, AppDb, Run, N extends Needs>(effect: Omit<Effect<Meta, AppDb, Run, N>, 'schedule' | 'withSchedule'>, schedule: EffectSchedule<Meta>): Effect<Meta, AppDb, Run, N>;
+/** `j.effect` for one journal. Three arguments: the effect needs nothing. Four: the third lists its needs. */
+export declare function effectFor<Meta, AppDb, Run>(): {
+    <E extends AnyEntity<Meta>>(name: string, entity: E | readonly E[], on: NoInfer<EffectHandlers<E, Meta, AppDb, Run>>): Effect<Meta, AppDb, Run>;
+    <E extends AnyEntity<Meta>, N extends Needs>(name: string, entity: E | readonly E[], needs: N, on: NoInfer<EffectHandlers<E, Meta, AppDb, Run, N>>): Effect<Meta, AppDb, Run, N>;
+};
+/** `j.tap` for one journal. Three arguments: the tap needs nothing. Four: the third lists its needs. */
+export declare function tapFor<Meta, AppDb>(): {
+    <E extends AnyEntity<Meta>>(name: string, entity: E | readonly E[], on: NoInfer<TapHandlers<E, Meta, AppDb>>): Tap<Meta, AppDb>;
+    <E extends AnyEntity<Meta>, N extends Needs>(name: string, entity: E | readonly E[], needs: N, on: NoInfer<TapHandlers<E, Meta, AppDb, N>>): Tap<Meta, AppDb, N>;
+};
+/** Give one tap its services, as `bindEffect` does for an effect. */
+export declare function bindTap<Meta, AppDb>(tap: Tap<Meta, AppDb, Needs>, services: Services): Tap<Meta, AppDb>;
+/**
+ * Give one effect its services. The result needs nothing more, so the worker can run it.
+ * `services` may hold more than this effect needs: each need is read by its name.
+ * This is the only place a need meets its value. `j.compose` calls it with the app's
+ * `services`; the Dot bridge calls it with the services of the feature that lists the effect.
+ */
+export declare function bindEffect<Meta, AppDb, Run>(effect: Effect<Meta, AppDb, Run, Needs>, services: Services): Effect<Meta, AppDb, Run>;
+//# sourceMappingURL=handlers.d.ts.map

package/dist/handlers.d.ts.map

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

package/dist/handlers.js

@@ -0,0 +1,130 @@
+import { JournalError } from './errors.js';
+import { assertStoredName } from './id.js';
+/** An entity has a `kind`; an array of entities does not. */
+function toList(entity) {
+    return 'kind' in entity ? [entity] : entity;
+}
+/**
+ * Only an own property counts as a handler. A plain object inherits `toString`,
+ * `constructor` and friends from `Object.prototype`; an event type with one of
+ * those names must not find a handler nobody declared.
+ */
+function ownHandler(handlers, type) {
+    return Object.hasOwn(handlers, type) ? handlers[type] : undefined;
+}
+function declaredTypes(handlers) {
+    return new Set(Object.keys(handlers).filter(key => ownHandler(handlers, key) !== undefined));
+}
+export function defineProjection(name, entity, on, opts) {
+    const handlers = on;
+    if (opts?.lane === 'async')
+        assertStoredName('effect name', name);
+    return {
+        name,
+        entities: toList(entity),
+        types: declaredTypes(handlers),
+        lane: opts?.lane ?? 'inline',
+        async run(tx, event) {
+            const handler = ownHandler(handlers, event.type);
+            if (handler !== undefined)
+                await handler(tx, event);
+        },
+    };
+}
+/** Every effect handler gets these. A need must not take one of their names. */
+const builtInContext = new Set(['jobId', 'signal', 'db', 'run']);
+/** Declare one thing an effect needs: `j.effect('order-mail', order, { mailer: need<Mailer>() }, { ... })`. */
+export const need = () => ({});
+function defineEffect(name, entity, needs, on) {
+    assertStoredName('effect name', name);
+    for (const key of Object.keys(needs)) {
+        if (builtInContext.has(key))
+            throw new JournalError('BAD_DEFINITION', 'effect', name, `journal: effect "${name}" has a need named "${key}", but the handler context already has "jobId", "signal", "db" and "run"; give the need another name`);
+    }
+    const handlers = on;
+    return withSchedule({
+        name,
+        entities: toList(entity),
+        types: declaredTypes(handlers),
+        needs,
+        async run(event, ctx) {
+            const handler = ownHandler(handlers, event.type);
+            // A job was queued for this type. Running nothing would acknowledge it silently.
+            if (handler === undefined)
+                throw new Error(`effect "${name}" has no handler for "${event.type}", but a job was queued for it; add a handler for this event to the effect, or delete the job if the event is no longer handled`);
+            await handler(event, ctx);
+        },
+    }, {});
+}
+const INT4_MAX = 2_147_483_647;
+/** Attach a schedule to an effect, checked once: a job row must be able to hold it. */
+export function withSchedule(effect, schedule) {
+    const { priority = 0, delaySeconds = 0 } = schedule;
+    if (!Number.isInteger(priority) || Math.abs(priority) > INT4_MAX)
+        throw new JournalError('BAD_DEFINITION', 'effect', effect.name, `journal: effect "${effect.name}": priority must be an integer within 32 bits, got ${String(priority)}`);
+    if (!Number.isFinite(delaySeconds) || delaySeconds < 0)
+        throw new JournalError('BAD_DEFINITION', 'effect', effect.name, `journal: effect "${effect.name}": delaySeconds must be a finite number of seconds, zero or more, got ${String(delaySeconds)}`);
+    if (schedule.delaySeconds !== undefined && schedule.runAt !== undefined)
+        throw new JournalError('BAD_DEFINITION', 'effect', effect.name, `journal: effect "${effect.name}": give delaySeconds or runAt, not both`);
+    return {
+        ...effect,
+        schedule,
+        withSchedule: next => withSchedule(effect, next),
+    };
+}
+/** `j.effect` for one journal. Three arguments: the effect needs nothing. Four: the third lists its needs. */
+export function effectFor() {
+    function effect(name, entity, ...rest) {
+        return rest.length === 1 ? defineEffect(name, entity, {}, rest[0]) : defineEffect(name, entity, rest[0], rest[1]);
+    }
+    return effect;
+}
+function defineTap(name, entity, needs, on) {
+    assertStoredName('effect name', name);
+    if (Object.hasOwn(needs, 'db'))
+        throw new JournalError('BAD_DEFINITION', 'tap', name, `journal: tap "${name}" has a need named "db", but the handler context already has "db"; give the need another name`);
+    const handlers = on;
+    return {
+        name,
+        entities: toList(entity),
+        types: declaredTypes(handlers),
+        needs,
+        async run(event, ctx) {
+            await ownHandler(handlers, event.type)?.(event, ctx);
+        },
+    };
+}
+/** `j.tap` for one journal. Three arguments: the tap needs nothing. Four: the third lists its needs. */
+export function tapFor() {
+    function tap(name, entity, ...rest) {
+        return rest.length === 1 ? defineTap(name, entity, {}, rest[0]) : defineTap(name, entity, rest[0], rest[1]);
+    }
+    return tap;
+}
+/** Give one tap its services, as `bindEffect` does for an effect. */
+export function bindTap(tap, services) {
+    const given = {};
+    for (const key of Object.keys(tap.needs)) {
+        if (!Object.hasOwn(services, key) || services[key] === undefined)
+            throw new JournalError('BAD_DEFINITION', 'tap', tap.name, `journal: tap "${tap.name}" needs "${key}", but no service with that name was given; pass it as j.compose({ services: { ${key} } }), or in a Dot app add it to the \`needs\` of the feature that lists this tap`);
+        given[key] = services[key];
+    }
+    return { ...tap, needs: {}, run: (event, ctx) => tap.run(event, { ...given, ...ctx }) };
+}
+/**
+ * Give one effect its services. The result needs nothing more, so the worker can run it.
+ * `services` may hold more than this effect needs: each need is read by its name.
+ * This is the only place a need meets its value. `j.compose` calls it with the app's
+ * `services`; the Dot bridge calls it with the services of the feature that lists the effect.
+ */
+export function bindEffect(effect, services) {
+    const given = {};
+    for (const key of Object.keys(effect.needs)) {
+        // Without this check the effect would start, and every job would fail on `undefined`.
+        if (!Object.hasOwn(services, key) || services[key] === undefined)
+            throw new JournalError('BAD_DEFINITION', 'effect', effect.name, `journal: effect "${effect.name}" needs "${key}", but no service with that name was given; pass it as j.compose({ services: { ${key} } }), or in a Dot app add it to the \`needs\` of the feature that lists this effect`);
+        given[key] = services[key];
+    }
+    return withSchedule({ ...effect, needs: {}, run: (event, ctx) => effect.run(event, { ...given, ...ctx }) }, effect.schedule);
+}
+//# sourceMappingURL=handlers.js.map

package/dist/handlers.js.map

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

package/dist/history.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading the log: decoding stored events, the log queries, history-completeness
+ * checks, and `replay`, `verify`, `repair`, `rerun`.
+ * May import `fold`, `storage`, leaf files, and result types from `api`.
+ * Must not import `journal`, `write`, `command` or `worker`.
+ */
+import type { z } from 'zod';
+import type { ForgetResult, ReplayResult, VerifyResult } from './api.js';
+import type { JournalTables } from './pg.js';
+import type { AnyEventDef, DbHandle, EntityDef, EntityId, EntityTable, Projection, Recorded, Row, TransactionSource } from './types.js';
+/** What the log functions need from the journal: the meta schema and the journal tables. */
+export type HistoryDeps<Meta extends z.ZodObject> = {
+    readonly metaSchema: Meta;
+    readonly tables: JournalTables;
+};
+export declare function createHistory<Meta extends z.ZodObject>(deps: HistoryDeps<Meta>): {
+    decodeStoredEvent: <Id extends string>(row: {
+        causeSeq: number | null;
+        commandId: string | null;
+        correlationId: string | null;
+        data: unknown;
+        entityId: string;
+        erasedAt: Date | null;
+        id: string;
+        kind: string;
+        meta: unknown;
+        recordedAt: Date;
+        schemaVersion: number;
+        seq: number;
+        type: string;
+        version: number;
+    }, def: AnyEventDef | undefined, id: Id) => Recorded<string, unknown, z.output<Meta>, Id>;
+    highestVersion: (db: DbHandle, kind: string, id: string) => Promise<number>;
+    assertLogSaysGone: <Tbl extends EntityTable, E extends AnyEventDef, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, E, z.output<Meta>, Key>, id: EntityId<Tbl, Key>, latestLogVersion: number) => Promise<void>;
+    replay: <Tbl extends EntityTable, E extends AnyEventDef, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, E, z.output<Meta>, Key>, id: EntityId<Tbl, Key>, opts?: {
+        readonly throughVersion?: number;
+    }) => Promise<ReplayResult<Tbl, E, z.output<Meta>, Key>>;
+    verify: <Tbl extends EntityTable, E extends AnyEventDef, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, E, z.output<Meta>, Key>, id: EntityId<Tbl, Key>) => Promise<VerifyResult<Tbl, Key>>;
+    repair: <Tbl extends EntityTable, E extends AnyEventDef, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, E, z.output<Meta>, Key>, id: EntityId<Tbl, Key>) => Promise<Row<Tbl> | null>;
+    forget: <Tbl extends EntityTable, E extends AnyEventDef, Key extends string>(db: DbHandle, entity: EntityDef<string, Tbl, E, z.output<Meta>, Key>, id: EntityId<Tbl, Key>) => Promise<ForgetResult<Tbl>>;
+    rerun: <Tx extends TransactionSource<Tx>>(db: TransactionSource<Tx>, projection: Projection<z.output<Meta>, Tx>, opts?: {
+        readonly afterSeq?: number;
+        readonly batchSize?: number;
+    }) => Promise<{
+        readonly events: number;
+    }>;
+};
+export type History<Meta extends z.ZodObject> = ReturnType<typeof createHistory<Meta>>;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

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