@strav/durable 0.4.30 → 1.0.0-alpha.8

package/package.json

@@ -1,49 +1,30 @@
 {
   "name": "@strav/durable",
-  "version": "0.4.30",
+  "version": "1.0.0-alpha.8",
+  "description": "Strav durable execution — crash-resumable sequential workflows on top of @strav/queue + Postgres. V1: sequential .step() with retries + saga compensation. V2 adds parallel/route/loop/sleep/waitForSignal.",
   "type": "module",
-  "description": "Durable, crash-resumable workflow execution for the Strav framework",
-  "license": "MIT",
-  "keywords": [
-    "bun",
-    "framework",
-    "typescript",
-    "strav",
-    "durable",
-    "workflow",
-    "orchestration"
-  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./engine": "./src/engine/index.ts",
-    "./engine/*": "./src/engine/*.ts",
-    "./models": "./src/models/index.ts",
-    "./models/*": "./src/models/*.ts",
-    "./providers": "./src/providers/index.ts",
-    "./providers/*": "./src/providers/*.ts",
-    "./*": "./src/*.ts"
+    ".": "./src/index.ts"
   },
   "files": [
-    "src/",
-    "package.json",
-    "tsconfig.json",
-    "CHANGELOG.md"
+    "src",
+    "README.md"
   ],
-  "peerDependencies": {
-    "@strav/kernel": "0.4.30",
-    "@strav/database": "0.4.30"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "dependencies": {
-    "@strav/queue": "0.4.30",
-    "@strav/machine": "0.4.30",
-    "@strav/workflow": "0.4.30",
-    "luxon": "^3.7.2"
+    "@strav/kernel": "1.0.0-alpha.8",
+    "@strav/database": "1.0.0-alpha.8",
+    "@strav/queue": "1.0.0-alpha.8"
   },
-  "devDependencies": {
-    "@types/luxon": "^3.7.1"
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
   },
-  "scripts": {
-    "test": "bun test tests/",
-    "typecheck": "tsc --noEmit"
-  }
+  "devDependencies": null
 }

package/src/define_durable.ts

@@ -0,0 +1,29 @@
+/**
+ * `defineDurable(name, fn)` — declaration-style factory mirroring
+ * `defineSchema(...)` / `defineMachine(...)` / `defineWorkflow(...)`.
+ *
+ * ```ts
+ * export const milestone = defineDurable('milestone', (w) =>
+ *   w.step('discover', async (ctx) => discover(ctx.input))
+ *    .step('plan',     async (ctx) => plan(ctx.results.discover))
+ *    .step('ship',     async (ctx) => ship(ctx.results.plan), {
+ *      compensate: async (ctx) => rollbackShip(ctx.results.ship),
+ *    })
+ * )
+ * ```
+ *
+ * The returned `DurableWorkflow` is what apps register on the runner.
+ * Apps that prefer a more imperative shape can `new DurableWorkflow()`
+ * directly — the factory is sugar.
+ */
+
+import { DurableWorkflow } from './durable_workflow.ts'
+
+export function defineDurable(
+  name: string,
+  build: (workflow: DurableWorkflow) => DurableWorkflow,
+): DurableWorkflow {
+  const workflow = new DurableWorkflow(name)
+  build(workflow)
+  return workflow
+}

package/src/durable_advance_job.ts

@@ -0,0 +1,38 @@
+/**
+ * `DurableAdvanceJob` — queue Job that moves a durable run forward
+ * by one step.
+ *
+ * Payload is just `{ runId }` — the runner reads everything else off
+ * the run row + the registry. Keeping the payload minimal protects
+ * against schema drift between the dispatcher and the worker: a
+ * worker on an older deploy can still process jobs queued by the
+ * latest deploy as long as the registry shape matches.
+ *
+ * `maxAttempts = 1` because retry semantics live INSIDE the runner
+ * (per-step retries with configurable backoff), not at the Job
+ * layer. If the runner throws here it means the engine itself
+ * failed — those should land in the queue's dead-letter via the
+ * standard Worker pipeline, not get silently retried.
+ */
+
+import { inject } from '@strav/kernel'
+import { Job, type JobContext } from '@strav/queue'
+import { DurableRunner } from './durable_runner.ts'
+
+export interface DurableAdvancePayload {
+  runId: string
+}
+
+@inject()
+export class DurableAdvanceJob extends Job<DurableAdvancePayload> {
+  static override readonly jobName = 'durable.advance'
+  static override readonly maxAttempts = 1
+
+  constructor(private readonly runner: DurableRunner) {
+    super()
+  }
+
+  async handle(ctx: JobContext<DurableAdvancePayload>): Promise<void> {
+    await this.runner.advance(ctx.payload.runId)
+  }
+}

package/src/durable_compensate_job.ts

@@ -0,0 +1,33 @@
+/**
+ * `DurableCompensateJob` — queue Job that runs saga compensation for
+ * a terminally-failed run.
+ *
+ * Mirrors `DurableAdvanceJob`'s shape — minimal payload, runner owns
+ * the state. Same rationale for `maxAttempts = 1`: the runner
+ * iterates over compensators internally and swallows their
+ * individual failures so the rollback finishes; if the runner
+ * itself throws (e.g. a DB connection error mid-walk), the queue's
+ * dead-letter is the right place for it.
+ */
+
+import { inject } from '@strav/kernel'
+import { Job, type JobContext } from '@strav/queue'
+import { DurableRunner } from './durable_runner.ts'
+
+export interface DurableCompensatePayload {
+  runId: string
+}
+
+@inject()
+export class DurableCompensateJob extends Job<DurableCompensatePayload> {
+  static override readonly jobName = 'durable.compensate'
+  static override readonly maxAttempts = 1
+
+  constructor(private readonly runner: DurableRunner) {
+    super()
+  }
+
+  async handle(ctx: JobContext<DurableCompensatePayload>): Promise<void> {
+    await this.runner.compensate(ctx.payload.runId)
+  }
+}

package/src/durable_error.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed StravError subclasses for durable execution.
+ *
+ * `DurableError` is the base — generic infrastructure failure. The
+ * two more-specific subclasses cover the common "the caller asked
+ * for something that doesn't exist" cases.
+ */
+
+import { StravError } from '@strav/kernel'
+
+export class DurableError extends StravError {
+  constructor(
+    message: string,
+    options: { context?: Record<string, unknown>; cause?: unknown } = {},
+  ) {
+    super(message, { code: 'durable.error', status: 500 }, options)
+  }
+}
+
+export class RunNotFoundError extends StravError {
+  constructor(runId: string) {
+    super(
+      `Durable run "${runId}" not found.`,
+      { code: 'durable.run-not-found', status: 404 },
+      { context: { runId } },
+    )
+  }
+}
+
+export class WorkflowNotRegisteredError extends StravError {
+  constructor(name: string, known: readonly string[]) {
+    super(
+      `Durable workflow "${name}" is not registered. Known: ${known.length === 0 ? '(none)' : known.join(', ')}.`,
+      { code: 'durable.workflow-not-registered', status: 500 },
+      { context: { name, known: [...known] } },
+    )
+  }
+}

package/src/durable_provider.ts

@@ -0,0 +1,91 @@
+/**
+ * `DurableProvider` — wires the durable runtime into the container.
+ *
+ * `register()`:
+ *   - Binds `WorkflowRegistry` as a singleton — apps wire workflows
+ *     into it from their own provider's `boot()`.
+ *   - Binds `DurableRunner` as a singleton; resolves the Postgres
+ *     pool, the `Queue` driver (passed via constructor options), the
+ *     registry, and (optionally) the `Logger`.
+ *
+ * `boot()`:
+ *   - Registers both schemas on the app's `SchemaRegistry` so they
+ *     show up in `db:migrate:generate` output.
+ *   - Eagerly resolves the runner so a misconfigured app fails at
+ *     boot, not on the first start() call.
+ *
+ * The provider does NOT auto-discover workflows — apps register them
+ * explicitly. The `discover` slice lands when an app needs it.
+ *
+ * `@strav/queue` doesn't ship a `QueueProvider` — apps bind their
+ * queue driver (typically `DatabaseQueue` in production, `SyncQueue`
+ * in tests) in their own provider's `register()`. DurableProvider's
+ * constructor takes the queue class so the runtime knows which
+ * binding to resolve.
+ */
+
+import { type Application, LogManager, ServiceProvider } from '@strav/kernel'
+import { PostgresDatabase, SchemaRegistry } from '@strav/database'
+import type { JobClass, Queue } from '@strav/queue'
+import { DurableAdvanceJob } from './durable_advance_job.ts'
+import { DurableCompensateJob } from './durable_compensate_job.ts'
+import { workflowJournalSchema } from './journal_schema.ts'
+import { workflowRunsSchema } from './runs_schema.ts'
+import { DurableRunner } from './durable_runner.ts'
+import { WorkflowRegistry } from './workflow_registry.ts'
+
+export interface DurableProviderOptions {
+  /**
+   * Concrete `Queue` driver class. Apps bind one (typically
+   * `DatabaseQueue` for production, `SyncQueue` for tests) in their
+   * own provider, then pass the class here so `DurableRunner` can
+   * resolve it from the container.
+   */
+  // biome-ignore lint/suspicious/noExplicitAny: container constructor accepts any[]
+  queue: new (...args: any[]) => Queue
+  /**
+   * Optional Job class overrides. Defaults to the shipped
+   * `DurableAdvanceJob` / `DurableCompensateJob`. Apps that subclass
+   * the Jobs (custom logging, custom dead-letter routing) pass their
+   * subclass here.
+   */
+  advanceJob?: JobClass
+  compensateJob?: JobClass
+}
+
+export class DurableProvider extends ServiceProvider {
+  override readonly name = 'durable'
+  override readonly dependencies = ['database']
+
+  constructor(private readonly options: DurableProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(WorkflowRegistry, () => new WorkflowRegistry())
+    app.singleton(DurableRunner, (c) => {
+      const runnerOptions: ConstructorParameters<typeof DurableRunner>[0] = {
+        db: c.resolve(PostgresDatabase),
+        queue: c.resolve(this.options.queue),
+        registry: c.resolve(WorkflowRegistry),
+        advanceJob: this.options.advanceJob ?? DurableAdvanceJob,
+        compensateJob: this.options.compensateJob ?? DurableCompensateJob,
+      }
+      if (c.has(LogManager)) {
+        runnerOptions.logger = c.resolve(LogManager).channel('durable')
+      }
+      if (c.has(SchemaRegistry)) runnerOptions.schemas = c.resolve(SchemaRegistry)
+      return new DurableRunner(runnerOptions)
+    })
+  }
+
+  override boot(app: Application): void {
+    if (app.has(SchemaRegistry)) {
+      const registry = app.resolve(SchemaRegistry)
+      if (!registry.has(workflowRunsSchema.name)) registry.register(workflowRunsSchema)
+      if (!registry.has(workflowJournalSchema.name)) registry.register(workflowJournalSchema)
+    }
+    // Eager-resolve so misconfiguration fails at boot.
+    app.resolve(DurableRunner)
+  }
+}