@arki/journal 0.1.0 → 0.2.1

package/src/handlers.ts

@@ -6,6 +6,7 @@ import type {
   EffectContext,
   EffectHandlers,
   EffectSchedule,
+  HandlerServices,
   Need,
   Needed,
   Needs,
@@ -217,19 +218,32 @@ export function tapFor<Meta, AppDb>() {
   return tap;
 }
 
-/** Give one tap its services, as `bindEffect` does for an effect. */
-export function bindTap<Meta, AppDb>(tap: Tap<Meta, AppDb, Needs>, services: Services): Tap<Meta, AppDb> {
+/**
+ * The value of each need of one handler, read from `services` by name. `services` may hold more.
+ * Throws when one is missing: without this check the handler would start, and fail on `undefined`.
+ */
+export function givenServices(
+  kind: 'effect' | 'tap',
+  handler: { readonly name: string; readonly needs: Needs },
+  services: Services,
+): Services {
   const given: Record<string, unknown> = {};
-  for (const key of Object.keys(tap.needs)) {
+  for (const key of Object.keys(handler.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`,
+        kind,
+        handler.name,
+        `journal: ${kind} "${handler.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 ${kind}`,
       );
     given[key] = services[key];
   }
+  return given;
+}
+
+/** Give one tap its services, as `bindEffect` does for an effect. */
+export function bindTap<Meta, AppDb>(tap: Tap<Meta, AppDb, Needs>, services: Services): Tap<Meta, AppDb> {
+  const given = givenServices('tap', tap, services);
   return { ...tap, needs: {}, run: (event, ctx) => tap.run(event, { ...given, ...ctx }) };
 }
 
@@ -237,26 +251,34 @@ export function bindTap<Meta, AppDb>(tap: Tap<Meta, AppDb, Needs>, services: Ser
  * 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.
+ * `services`; a worker calls it with the services it was given (`HandlerServices`).
  */
 export function bindEffect<Meta, AppDb, Run>(
   effect: Effect<Meta, AppDb, Run, Needs>,
   services: Services,
 ): Effect<Meta, AppDb, Run> {
-  const given: Record<string, unknown> = {};
-  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];
-  }
+  const given = givenServices('effect', effect, services);
   return withSchedule(
     { ...effect, needs: {}, run: (event, ctx) => effect.run(event, { ...given, ...ctx }) },
     effect.schedule,
   );
 }
+
+/**
+ * The effects and taps as they run: each bound to its services from `services`.
+ * A handler `j.compose` already bound needs nothing, so it gets nothing. Throws on the first
+ * missing service, so a worker refuses to start instead of failing job after job.
+ */
+export function bindHandlers<Meta, AppDb, Run>(
+  handlers: {
+    readonly effects: readonly Effect<Meta, AppDb, Run, Needs>[];
+    readonly taps: readonly Tap<Meta, AppDb, Needs>[];
+  },
+  services: HandlerServices | undefined,
+): { readonly effects: readonly Effect<Meta, AppDb, Run>[]; readonly taps: readonly Tap<Meta, AppDb>[] } {
+  const of = (kind: 'effect' | 'tap', name: string): Services => services?.({ kind, name }) ?? {};
+  return {
+    effects: handlers.effects.map(effect => bindEffect(effect, of('effect', effect.name))),
+    taps: handlers.taps.map(tap => bindTap(tap, of('tap', tap.name))),
+  };
+}

package/src/index.ts

@@ -2,7 +2,9 @@ export { initJournal } from './journal.js';
 export { need } from './handlers.js';
 export type {
   Command,
+  CommandAuthorize,
   CommandContext,
+  CommandOptions,
   CommandRunner,
   Journal,
   JournalDefinitions,
@@ -66,6 +68,8 @@ export type {
   Row,
   Services,
   ServicesFor,
+  HandlerRef,
+  HandlerServices,
   TransactionSource,
   JournalWorker,
   StrandedJobs,

package/src/journal.ts

@@ -20,6 +20,7 @@ import type {
   EntityTable,
   IdTable,
   KeyName,
+  Needs,
   Projection,
   RootDb,
   SingleKey,
@@ -30,7 +31,7 @@ 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 { bindEffect, bindHandlers, bindTap, defineProjection, effectFor, tapFor } from './handlers.js';
 import { createHistory } from './history.js';
 import { createHookPoint } from './hooks.js';
 import {
@@ -114,13 +115,20 @@ function createInit<Meta extends z.ZodObject, Tx extends TransactionSource<Tx>,
   return {
     event: defineEvent,
     entity,
-    command: (name, input, handler) => ({ name, input, handler }),
+    command: (name, input, handler, options) =>
+      options?.authorize === undefined
+        ? { name, input, handler }
+        : { name, input, handler, authorize: options.authorize },
     projection: (name, entity, on, opts) => defineProjection(name, entity, on, opts),
     effect: effectFor<MetaOut, AppDb, RootCommandRunner<Meta, Tx>>(),
     tap: tapFor<MetaOut, AppDb>(),
     compose: config => {
-      const effects = (config.effects ?? []).map(effect => bindEffect(effect, config.services ?? {}));
-      const taps = (config.taps ?? []).map(tap => bindTap(tap, config.services ?? {}));
+      // `'worker'`: the handlers keep their needs, and each worker or drain gives the services.
+      const services = config.services === 'worker' ? undefined : (config.services ?? {});
+      const effects = (config.effects ?? []).map(effect =>
+        services === undefined ? effect : bindEffect(effect, services),
+      );
+      const taps = (config.taps ?? []).map(tap => (services === undefined ? tap : bindTap(tap, services)));
       return createJournal<Meta, Tx, AppDb>(metaSchema, config.tables, config.projections ?? [], effects, taps);
     },
   };
@@ -143,8 +151,9 @@ function createJournal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx
   metaSchema: Meta,
   tables: JournalTables,
   projections: readonly Projection<z.output<Meta>, Tx>[],
-  effects: readonly Effect<z.output<Meta>, AppDb, RootCommandRunner<Meta, Tx>>[],
-  taps: readonly Tap<z.output<Meta>, AppDb>[] = [],
+  /** An effect or a tap may still have needs (`services: 'worker'`): only the worker runs them, with its `services`. */
+  effects: readonly Effect<z.output<Meta>, AppDb, RootCommandRunner<Meta, Tx>, Needs>[],
+  taps: readonly Tap<z.output<Meta>, AppDb, Needs>[] = [],
 ): Journal<Meta, Tx, AppDb> {
   assertUniqueNames('tap', taps);
   const eventsSchema = getTableConfig(tables.events).schema;
@@ -196,6 +205,7 @@ function createJournal<Meta extends z.ZodObject, Tx extends TransactionSource<Tx
     drain: (db, opts) => journal.drain(db, opts),
     catchUp: (db, opts) => journal.catchUp(db, opts),
     dispatch,
+    checkServices: services => void bindHandlers({ effects, taps }, services),
     tapNames: taps.map(tap => tap.name),
   });
   const strandedJobs = createStrandedJobs({ tables, effectNames: effects.map(effect => effect.name) });

package/src/transaction-guard.ts

@@ -34,7 +34,6 @@ export function oneAtATime<T>(handle: object, what: string, work: () => Promise<
       );
     });
   }
-  // eslint-disable-next-line drizzle/enforce-delete-with-where -- WeakMap#delete, not a Drizzle query
   const running = work().finally(() => inFlight.delete(handle));
   inFlight.set(handle, running);
   return running;

package/src/types.ts

@@ -327,6 +327,15 @@ export type NoNeeds = Readonly<Record<never, Need<unknown>>>;
 export type Needed<N extends Needs> = { readonly [K in keyof N]: N[K] extends Need<infer T> ? T : never };
 /** Real services by name, as an app or a Dot feature hands them over. */
 export type Services = Readonly<Record<string, unknown>>;
+/** Names one effect or one tap. Effect names and tap names are two separate sets. */
+export type HandlerRef = { readonly kind: 'effect' | 'tap'; readonly name: string };
+/**
+ * The services of each effect and tap, given where they run instead of where the journal
+ * is composed: `j.compose({ ..., services: 'worker' })`, then `journal.worker(db, { services })`.
+ * One function, so each handler can get its own services: two Dot features may use one need
+ * name for two different services.
+ */
+export type HandlerServices = (handler: HandlerRef) => Services;
 
 type UnionToIntersection<U> = (U extends unknown ? (member: U) => void : never) extends (all: infer I) => void
   ? I

package/src/worker.ts

@@ -15,7 +15,9 @@ import type {
   DbHandle,
   Effect,
   EffectHookContext,
+  HandlerServices,
   JournalWorker,
+  Needs,
   Projection,
   RootDb,
   StrandedJobs,
@@ -27,6 +29,7 @@ import type {
 import { debugDrain, debugWorker } from './debug.js';
 import { JournalError } from './errors.js';
 import { findEventDefinition } from './fold.js';
+import { bindHandlers } from './handlers.js';
 import { leaseToken } from './id.js';
 import { assertRootDb } from './storage.js';
 
@@ -57,7 +60,8 @@ export type DrainDeps<Meta extends z.ZodObject, AppDb extends RootDb, Run> = {
   readonly tables: JournalTables;
   /** The effect hooks. Frozen by the first drain. */
   readonly hooks: HookPointInternal<EffectHookContext<z.output<Meta>>>;
-  readonly effects: readonly Effect<z.output<Meta>, AppDb, Run>[];
+  /** As composed: an effect may still have needs. Each drain binds them from its `services`. */
+  readonly effects: readonly Effect<z.output<Meta>, AppDb, Run, Needs>[];
   readonly history: Pick<History<Meta>, 'decodeStoredEvent'>;
   /** Makes an effect's `ctx.run`: the journal's `run`, bound to the root database this drain was given and to the event the job is for. */
   readonly runOn: (db: AppDb & RootDb, cause: { readonly seq: number; readonly correlationId: string | null }) => Run;
@@ -66,9 +70,7 @@ export type DrainDeps<Meta extends z.ZodObject, AppDb extends RootDb, Run> = {
 export function createDrain<Meta extends z.ZodObject, AppDb extends RootDb, Run>(deps: DrainDeps<Meta, AppDb, Run>) {
   const { events: eventsTable, jobs: jobsTable } = deps.tables;
   const { decodeStoredEvent } = deps.history;
-  const effectsByName = new Map(deps.effects.map(effect => [effect.name, effect]));
-
-  const known = [...effectsByName.keys()];
+  const known = deps.effects.map(effect => effect.name);
 
   // Every time here is database time, so a worker with a skewed clock
   // cannot take a live lease or push a retry into the far future.
@@ -149,7 +151,13 @@ export function createDrain<Meta extends z.ZodObject, AppDb extends RootDb, Run>
     };
   };
 
-  const runJob = async (db: AppDb & RootDb, job: JobRow, signal: AbortSignal, leaseSeconds: number): Promise<void> => {
+  const runJob = async (
+    db: AppDb & RootDb,
+    job: JobRow,
+    signal: AbortSignal,
+    leaseSeconds: number,
+    effectsByName: ReadonlyMap<string, Effect<z.output<Meta>, AppDb, Run>>,
+  ): Promise<void> => {
     const effect = effectsByName.get(job.effect);
     const lost = new AbortController();
     const stopRenewing = renewWhile(db, job, leaseSeconds, lost);
@@ -194,9 +202,17 @@ export function createDrain<Meta extends z.ZodObject, AppDb extends RootDb, Run>
 
   return async (
     db: AppDb & RootDb,
-    opts?: { readonly batchSize?: number; readonly signal?: AbortSignal; readonly leaseSeconds?: number },
+    opts?: {
+      readonly batchSize?: number;
+      readonly signal?: AbortSignal;
+      readonly leaseSeconds?: number;
+      readonly services?: HandlerServices;
+    },
   ): Promise<number> => {
     assertRootDb(db, 'drain');
+    // Before any claim: a missing service refuses the drain, not one job after another.
+    const { effects } = bindHandlers({ effects: deps.effects, taps: [] }, opts?.services);
+    const effectsByName = new Map(effects.map(effect => [effect.name, effect]));
     deps.hooks.freeze();
     const batchSize = opts?.batchSize ?? 20;
     const leaseSeconds = opts?.leaseSeconds ?? DEFAULT_LEASE_SECONDS;
@@ -213,7 +229,7 @@ export function createDrain<Meta extends z.ZodObject, AppDb extends RootDb, Run>
       const job = await claimOne(db, leaseSeconds);
       if (job === undefined) break;
       claimed += 1;
-      await runJob(db, job, signal, leaseSeconds);
+      await runJob(db, job, signal, leaseSeconds, effectsByName);
     }
     return claimed;
   };
@@ -293,7 +309,12 @@ export type WorkerDeps<AppDb extends RootDb> = {
   /** Runs one batch. The journal passes its own `drain` method, looked up on each call. */
   readonly drain: (
     db: AppDb & RootDb,
-    opts?: { readonly batchSize?: number; readonly signal?: AbortSignal; readonly leaseSeconds?: number },
+    opts?: {
+      readonly batchSize?: number;
+      readonly signal?: AbortSignal;
+      readonly leaseSeconds?: number;
+      readonly services?: HandlerServices;
+    },
   ) => Promise<number>;
   /** One batch per async projection. Returns how many events were scanned. */
   readonly catchUp: (
@@ -301,7 +322,9 @@ export type WorkerDeps<AppDb extends RootDb> = {
     opts?: { readonly batchSize?: number },
   ) => Promise<{ readonly scanned: number }>;
   /** Fire the taps for one wake payload. */
-  readonly dispatch: (db: AppDb & RootDb, payload: string) => Promise<void>;
+  readonly dispatch: (db: AppDb & RootDb, payload: string, services: HandlerServices | undefined) => Promise<void>;
+  /** Throws when an effect or a tap is missing a service in `services`. */
+  readonly checkServices: (services: HandlerServices | undefined) => void;
   readonly tapNames: readonly string[];
 };
 
@@ -427,7 +450,8 @@ export function createCatchUp<Meta extends z.ZodObject, Tx extends TransactionSo
 /** What tap dispatch needs from the journal. */
 export type TapDispatchDeps<Meta extends z.ZodObject, AppDb extends RootDb> = {
   readonly tables: Pick<JournalTables, 'events'>;
-  readonly taps: readonly Tap<z.output<Meta>, AppDb>[];
+  /** As composed: a tap may still have needs. Each dispatch binds them from its `services`. */
+  readonly taps: readonly Tap<z.output<Meta>, AppDb, Needs>[];
   readonly history: Pick<History<Meta>, 'decodeStoredEvent'>;
 };
 
@@ -451,10 +475,15 @@ export function createTapDispatch<Meta extends z.ZodObject, AppDb extends RootDb
   const types = [...new Set(deps.taps.flatMap(tap => [...tap.types]))];
 
   /** Load the committed events in the range that some tap wants, and run each matching tap. Errors are logged, never thrown. */
-  const dispatch = async (db: AppDb & RootDb, payload: string): Promise<void> => {
+  const dispatch = async (
+    db: AppDb & RootDb,
+    payload: string,
+    services: HandlerServices | undefined,
+  ): Promise<void> => {
     if (deps.taps.length === 0) return;
     const range = parseRange(payload);
     if (range === undefined) return;
+    const { taps } = bindHandlers({ effects: [], taps: deps.taps }, services);
     const rows = await db
       .select()
       .from(eventsTable)
@@ -468,7 +497,7 @@ export function createTapDispatch<Meta extends z.ZodObject, AppDb extends RootDb
       )
       .orderBy(asc(eventsTable.seq));
     for (const row of rows) {
-      for (const tap of deps.taps) {
+      for (const tap of taps) {
         if (!tap.types.has(row.type) || !tap.entities.some(entity => entity.kind === row.kind)) continue;
         try {
           const event = deps.history.decodeStoredEvent(
@@ -507,9 +536,11 @@ export function createWorkers<AppDb extends RootDb>(deps: WorkerDeps<AppDb>) {
       readonly leaseSeconds?: number;
       readonly listen?: WakeListener;
       readonly taps?: boolean;
+      readonly services?: HandlerServices;
     },
   ): JournalWorker => {
     assertRootDb(db, 'worker');
+    deps.checkServices(opts?.services);
     if (deps.tapNames.length > 0 && opts?.listen === undefined && opts?.taps !== false)
       throw new Error(
         `journal: this journal has taps (${deps.tapNames.join(', ')}) but the worker has no \`listen\`; taps fire only from the wake channel. Wire LISTEN on journal.wakeChannel, or pass { taps: false } for a worker that runs jobs only`,
@@ -551,6 +582,7 @@ export function createWorkers<AppDb extends RootDb>(deps: WorkerDeps<AppDb>) {
             batchSize: opts?.batchSize,
             signal: stopping.signal,
             leaseSeconds: opts?.leaseSeconds,
+            services: opts?.services,
           });
           if (isRunning()) {
             const caught = await deps.catchUp(db);
@@ -577,7 +609,7 @@ export function createWorkers<AppDb extends RootDb>(deps: WorkerDeps<AppDb>) {
           unlisten = await opts.listen(payload => {
             wake();
             if (opts.taps === false) return;
-            dispatching = dispatching.then(() => deps.dispatch(db, payload)).catch(quiet);
+            dispatching = dispatching.then(() => deps.dispatch(db, payload, opts.services)).catch(quiet);
           });
         }
         debugWorker.debug('start (poll {pollMs}ms{value2})', {
@@ -589,7 +621,6 @@ export function createWorkers<AppDb extends RootDb>(deps: WorkerDeps<AppDb>) {
       async stop() {
         running = false;
         stopping.abort();
-        // eslint-disable-next-line drizzle/enforce-delete-with-where -- Set#delete, not a Drizzle query
         wakers.delete(wake);
         endSleep?.();
         await unlisten?.();

package/src/write.ts

@@ -87,7 +87,7 @@ function dueAt(
 
 /** Insert order is the version order. `RETURNING` does not promise it, so restore it. */
 export function sortedByVersion<Row extends { readonly version: number }>(rows: readonly Row[]): Row[] {
-  return rows.toSorted((a, b) => a.version - b.version);
+  return [...rows].sort((a, b) => a.version - b.version);
 }
 
 /** What a write needs from the journal. */