station-signal 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 porkytheblack
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# station-signal
+
+A lightweight, type-safe background job framework for TypeScript. Define signals with Zod schemas, trigger them from anywhere, and let the runner execute each one in an isolated child process with timeout enforcement and automatic retries.
+
+## Install
+
+```bash
+pnpm add station-signal
+```
+
+## Defining signals
+
+Use the `signal()` builder to define a named signal with a Zod input schema and a handler function.
+
+```ts
+import { signal, z } from "station-signal";
+
+export const sendEmail = signal("send-email")
+  .input(z.object({ to: z.string().email(), subject: z.string(), body: z.string() }))
+  .timeout(30_000)
+  .retries(3)
+  .run(async (input) => {
+    await emailService.send(input.to, input.subject, input.body);
+  });
+```
+
+The full builder chain is:
+
+```ts
+signal("name")
+  .input(schema)       // Required. Zod schema that validates the input.
+  .timeout(ms)         // Optional. Max execution time in milliseconds (default: 300000).
+  .retries(n)          // Optional. Number of retries after the first failure (default: 0).
+  .every("5m")         // Optional. Makes this a recurring signal on an interval.
+  .run(fn)             // Required. The async handler function. Returns a Signal object.
+```
+
+| Method | Required | Description |
+|---|---|---|
+| `.input(schema)` | Yes | A Zod schema used to validate input at trigger time and before execution. |
+| `.timeout(ms)` | No | Override the default 5-minute timeout, in milliseconds. |
+| `.retries(n)` | No | Number of retries after the first attempt fails. Total attempts = `n + 1`. |
+| `.every(interval)` | No | Schedule the signal to run on a recurring interval (e.g. `"every 5m"`). |
+| `.run(fn)` | Yes | The async function that executes the signal. Finalizes and returns the `Signal` object. |
+
+## Triggering signals
+
+There are two ways to trigger a signal.
+
+### Type-safe trigger
+
+Call `.trigger()` directly on a signal object. The input is validated against the Zod schema before being enqueued.
+
+```ts
+import { sendEmail } from "./signals/send-email.js";
+
+const entryId = await sendEmail.trigger({
+  to: "alice@example.com",
+  subject: "Welcome",
+  body: "Thanks for signing up.",
+});
+// entryId is a unique string identifying this queue entry
+```
+
+### Dynamic trigger
+
+Use `SignalQueue` to trigger signals by name. This is useful when the signal name comes from a variable or external source. No schema validation is performed.
+
+```ts
+import { SignalQueue } from "station-signal";
+
+const queue = new SignalQueue();
+const entryId = await queue.trigger("send-email", {
+  to: "alice@example.com",
+  subject: "Welcome",
+  body: "Thanks for signing up.",
+});
+```
+
+Both approaches return a `Promise<string>` containing the queue entry ID.
+
+## Running signals
+
+`SignalRunner` polls the adapter for due entries and spawns an isolated child process for each one.
+
+### Minimal example
+
+```ts
+import { SignalRunner } from "station-signal";
+
+const runner = new SignalRunner({
+  signalsDir: "./src/signals",
+});
+
+await runner.start();
+```
+
+### Full options
+
+```ts
+import { SignalRunner } from "station-signal";
+import { SQLiteAdapter } from "station-adapter-sqlite";
+
+const runner = new SignalRunner({
+  // Auto-discover all .ts/.js files in this directory (recursive).
+  signalsDir: "./src/signals",
+
+  // Custom adapter for persistence. Defaults to MemoryAdapter.
+  adapter: new SQLiteAdapter("jobs.db"),
+
+  // How often to check for due entries, in milliseconds. Default: 1000.
+  pollIntervalMs: 2000,
+
+  // Default max attempts for signals that don't specify their own. Default: 1.
+  maxAttempts: 3,
+
+  // Path to a module that calls configure(). Imported by the runner on startup
+  // AND by every spawned child process before the signal file.
+  configModule: "/absolute/path/to/adapter.config.ts",
+});
+
+await runner.start();
+```
+
+### Manual registration
+
+If you are not using `signalsDir`, you can register signals individually:
+
+```ts
+const runner = new SignalRunner();
+runner.register("send-email", "/absolute/path/to/signals/send-email.ts");
+runner.register("generate-report", "/absolute/path/to/signals/generate-report.ts");
+await runner.start();
+```
+
+The `register()` method takes a signal name and the absolute file path to the module that exports the signal.
+
+## Recurring signals
+
+### Using the builder
+
+Add `.every()` to any signal definition to make it recurring. The runner automatically schedules the first run on startup and reschedules after each execution.
+
+```ts
+export const healthCheck = signal("health-check")
+  .input(z.object({}))
+  .every("every 30s")
+  .run(async () => {
+    await pingAllServices();
+  });
+```
+
+### Using SignalQueue
+
+Schedule a recurring signal dynamically:
+
+```ts
+const queue = new SignalQueue();
+await queue.schedule("cleanup-temp-files", "every 1h", {});
+```
+
+### Interval format
+
+The interval string must match the format `"every <number><unit>"`.
+
+| Unit | Meaning | Example |
+|---|---|---|
+| `s` | Seconds | `"every 30s"` |
+| `m` | Minutes | `"every 5m"` |
+| `h` | Hours | `"every 1h"` |
+| `d` | Days | `"every 7d"` |
+
+## Timeout and retries
+
+Every signal has a timeout and a maximum number of attempts.
+
+| Setting | Default | Builder method |
+|---|---|---|
+| Timeout | 300,000ms (5 minutes) | `.timeout(ms)` |
+| Retries | 0 (1 total attempt) | `.retries(n)` |
+
+When a signal times out or throws an error and has remaining retry attempts, the runner resets it to "pending" for another try.
+
+**Trigger signals**: After exhausting all attempts, the entry is marked as `"failed"` with a `completedAt` timestamp.
+
+**Recurring signals**: After exhausting all attempts for a given run, the entry resets its attempt counter to 0 and reschedules the next run based on its interval. Recurring signals never permanently fail.
+
+## Adapters
+
+Adapters control how queue entries are stored and retrieved.
+
+### Setting the global adapter
+
+```ts
+import { configure } from "station-signal";
+import { SQLiteAdapter } from "station-adapter-sqlite";
+
+configure({ adapter: new SQLiteAdapter("jobs.db") });
+```
+
+The default adapter is `MemoryAdapter`, which stores entries in-process. It requires no configuration but does not persist data across restarts and cannot share state between the runner and its spawned child processes.
+
+### The configModule pattern
+
+Because `SignalRunner` spawns each signal in a separate child process, you need a way to ensure both the runner and every child process use the same adapter. The `configModule` option solves this:
+
+```ts
+// src/adapter.config.ts
+import { configure } from "station-signal";
+import { SQLiteAdapter } from "station-adapter-sqlite";
+
+configure({ adapter: new SQLiteAdapter("jobs.db") });
+```
+
+```ts
+// src/runner.ts
+import { fileURLToPath } from "node:url";
+import { SignalRunner } from "station-signal";
+
+const runner = new SignalRunner({
+  signalsDir: "./src/signals",
+  configModule: fileURLToPath(new URL("./adapter.config.ts", import.meta.url)),
+});
+
+await runner.start();
+```
+
+The runner imports `configModule` on startup. Every spawned child process imports it before loading the signal file. This guarantees a consistent adapter everywhere.
+
+## Writing a custom adapter
+
+Implement the `SignalQueueAdapter` interface:
+
+```ts
+interface SignalQueueAdapter {
+  add(entry: QueueEntry): Promise<void>;
+  remove(id: string): Promise<void>;
+  getDue(): Promise<QueueEntry[]>;
+  getRunning(): Promise<QueueEntry[]>;
+  update(id: string, patch: Partial<QueueEntry>): Promise<void>;
+  ping(): Promise<boolean>;
+  generateId(): string;
+}
+```
+
+| Method | Contract |
+|---|---|
+| `add(entry)` | Store a new queue entry. |
+| `remove(id)` | Delete an entry by its ID. |
+| `getDue()` | Return all pending entries where `nextRunAt` is `null`/`undefined` or `<= now`. |
+| `getRunning()` | Return all entries with status `"running"`. |
+| `update(id, patch)` | Merge the partial patch into the existing entry. |
+| `ping()` | Health check. Return `true` if the adapter is operational. |
+| `generateId()` | Produce a unique string ID for a new queue entry. |
+
+## How it works
+
+1. `SignalRunner` polls the adapter at a configurable interval, calling `getDue()` to find entries that are ready to execute.
+2. For each due entry, the runner marks it as `"running"` and spawns an isolated child process via `node --import tsx bootstrap.js`.
+3. The child process first imports the `configModule` (if provided) to set up the shared adapter, then imports the signal file.
+4. The bootstrap script finds the matching signal export, validates the input against the signal's Zod schema, and rejects with a `"failed"` status if validation fails.
+5. The signal handler runs under timeout enforcement via `Promise.race`. If it completes in time, the entry is marked `"completed"`. If it throws, the entry is marked `"failed"`.
+6. Back in the runner, `checkTimeouts()` runs each tick to detect entries that have been `"running"` longer than their configured timeout. Timed-out entries are either reset to `"pending"` for a retry or marked `"failed"` (trigger) / rescheduled (recurring) depending on remaining attempts.
+
+## Types reference
+
+### QueueEntry
+
+```ts
+interface QueueEntry {
+  id: string;
+  signalName: string;
+  kind: QueueEntryKind;
+  input: string;            // JSON-serialized
+  status: EntryStatus;
+  attempts: number;
+  maxAttempts: number;
+  timeout: number;          // milliseconds
+  interval?: string;        // e.g. "every 5m" (recurring only)
+  nextRunAt?: Date;
+  lastRunAt?: Date;
+  startedAt?: Date;
+  completedAt?: Date;
+  createdAt: Date;
+}
+```
+
+### EntryStatus
+
+```ts
+type EntryStatus = "pending" | "running" | "completed" | "failed";
+```
+
+### QueueEntryKind
+
+```ts
+type QueueEntryKind = "trigger" | "recurring";
+```
+
+### Constants
+
+```ts
+const DEFAULT_TIMEOUT_MS = 300_000;   // 5 minutes
+const DEFAULT_MAX_ATTEMPTS = 1;       // no retry by default
+```

package/dist/adapters/http-trigger.d.ts

@@ -0,0 +1,19 @@
+import type { TriggerAdapter } from "./trigger.js";
+export interface HttpTriggerOptions {
+    endpoint: string;
+    apiKey?: string;
+    timeout?: number;
+    fetch?: typeof globalThis.fetch;
+}
+export declare class HttpTriggerAdapter implements TriggerAdapter {
+    private endpoint;
+    private apiKey?;
+    private timeout;
+    private fetchFn;
+    constructor(options: HttpTriggerOptions);
+    trigger(signalName: string, input: unknown): Promise<string>;
+    triggerBroadcast(broadcastName: string, input: unknown): Promise<string>;
+    ping(): Promise<boolean>;
+    private headers;
+}
+//# sourceMappingURL=http-trigger.d.ts.map

package/dist/adapters/http-trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-trigger.d.ts","sourceRoot":"","sources":["../../src/adapters/http-trigger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAYnD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;CACjC;AAED,qBAAa,kBAAmB,YAAW,cAAc;IACvD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAC,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAA0B;gBAE7B,OAAO,EAAE,kBAAkB;IAOjC,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB5D,gBAAgB,CAAC,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAgBxE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAa9B,OAAO,CAAC,OAAO;CAKhB"}

package/dist/adapters/http-trigger.js

@@ -0,0 +1,63 @@
+import { StationRemoteError } from "../errors.js";
+export class HttpTriggerAdapter {
+    endpoint;
+    apiKey;
+    timeout;
+    fetchFn;
+    constructor(options) {
+        this.endpoint = options.endpoint.replace(/\/+$/, "");
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout ?? 10_000;
+        this.fetchFn = options.fetch ?? globalThis.fetch;
+    }
+    async trigger(signalName, input) {
+        const url = `${this.endpoint}/api/v1/trigger`;
+        const response = await this.fetchFn(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ signalName, input }),
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new StationRemoteError(response.status, body.error, body.message);
+        }
+        const body = await response.json();
+        return body.data.id;
+    }
+    async triggerBroadcast(broadcastName, input) {
+        const url = `${this.endpoint}/api/v1/trigger-broadcast`;
+        const response = await this.fetchFn(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify({ broadcastName, input }),
+            signal: AbortSignal.timeout(this.timeout),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new StationRemoteError(response.status, body.error, body.message);
+        }
+        const body = await response.json();
+        return body.data.id;
+    }
+    async ping() {
+        try {
+            const url = `${this.endpoint}/api/v1/health`;
+            const response = await this.fetchFn(url, {
+                headers: this.headers(),
+                signal: AbortSignal.timeout(5000),
+            });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    headers() {
+        const h = { "Content-Type": "application/json" };
+        if (this.apiKey)
+            h["Authorization"] = `Bearer ${this.apiKey}`;
+        return h;
+    }
+}
+//# sourceMappingURL=http-trigger.js.map

package/dist/adapters/http-trigger.js.map

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

package/dist/adapters/index.d.ts

@@ -0,0 +1,49 @@
+import type { Run, RunPatch, RunStatus, Step, StepPatch } from "../types.js";
+export interface SignalQueueAdapter {
+    addRun(run: Run): Promise<void>;
+    removeRun(id: string): Promise<void>;
+    getRunsDue(): Promise<Run[]>;
+    getRunsRunning(): Promise<Run[]>;
+    getRun(id: string): Promise<Run | null>;
+    updateRun(id: string, patch: RunPatch): Promise<void>;
+    listRuns(signalName: string): Promise<Run[]>;
+    /** Check if any run for the given signal has one of the specified statuses. */
+    hasRunWithStatus(signalName: string, statuses: RunStatus[]): Promise<boolean>;
+    /** Purge runs in terminal statuses older than the given date. Returns count deleted. */
+    purgeRuns(olderThan: Date, statuses: RunStatus[]): Promise<number>;
+    addStep(step: Step): Promise<void>;
+    updateStep(id: string, patch: StepPatch): Promise<void>;
+    getSteps(runId: string): Promise<Step[]>;
+    removeSteps(runId: string): Promise<void>;
+    generateId(): string;
+    ping(): Promise<boolean>;
+    close?(): Promise<void>;
+}
+/**
+ * Metadata an adapter carries so child processes can reconstruct it.
+ * Adapters that implement SerializableAdapter are fully automatic —
+ * no extra runner config needed.
+ */
+export interface AdapterManifest {
+    /** Registry name (e.g. "sqlite"). Matches registerAdapter() name. */
+    name: string;
+    /** Serializable options to pass to the factory. */
+    options: Record<string, unknown>;
+    /**
+     * Resolved absolute path/URL to the module that registers this adapter.
+     * Only needed for external (non-built-in) adapters.
+     */
+    moduleUrl?: string;
+}
+/**
+ * Adapters that can be reconstructed in child processes implement this.
+ * MemoryAdapter intentionally does NOT implement this since it cannot
+ * share state across processes.
+ */
+export interface SerializableAdapter extends SignalQueueAdapter {
+    toManifest(): AdapterManifest;
+}
+export declare function isSerializableAdapter(adapter: SignalQueueAdapter): adapter is SerializableAdapter;
+export { MemoryAdapter } from "./memory.js";
+export { registerAdapter, createAdapter, hasAdapter } from "./registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IAEjC,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7B,cAAc,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IACxC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAE7C,+EAA+E;IAC/E,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE9E,wFAAwF;IACxF,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAGnE,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAG1C,UAAU,IAAI,MAAM,CAAC;IACrB,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACzB,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,UAAU,IAAI,eAAe,CAAC;CAC/B;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,kBAAkB,GAC1B,OAAO,IAAI,mBAAmB,CAEhC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/adapters/index.js

@@ -0,0 +1,6 @@
+export function isSerializableAdapter(adapter) {
+    return typeof adapter.toManifest === "function";
+}
+export { MemoryAdapter } from "./memory.js";
+export { registerAdapter, createAdapter, hasAdapter } from "./registry.js";
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAwDA,MAAM,UAAU,qBAAqB,CACnC,OAA2B;IAE3B,OAAO,OAAQ,OAA+B,CAAC,UAAU,KAAK,UAAU,CAAC;AAC3E,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC"}

package/dist/adapters/memory.d.ts

@@ -0,0 +1,33 @@
+import type { SignalQueueAdapter } from "./index.js";
+import type { Run, RunPatch, RunStatus, Step, StepPatch } from "../types.js";
+/**
+ * In-process memory adapter. Useful for single-process scripts and testing.
+ * Does NOT implement SerializableAdapter — child processes get their own
+ * independent MemoryAdapter. Use SqliteAdapter for cross-process persistence.
+ */
+export declare class MemoryAdapter implements SignalQueueAdapter {
+    private runs;
+    private steps;
+    private maxRuns;
+    constructor(options?: {
+        maxRuns?: number;
+    });
+    addRun(run: Run): Promise<void>;
+    private evictCompleted;
+    removeRun(id: string): Promise<void>;
+    getRunsDue(): Promise<Run[]>;
+    getRunsRunning(): Promise<Run[]>;
+    getRun(id: string): Promise<Run | null>;
+    updateRun(id: string, patch: RunPatch): Promise<void>;
+    listRuns(signalName: string): Promise<Run[]>;
+    hasRunWithStatus(signalName: string, statuses: RunStatus[]): Promise<boolean>;
+    purgeRuns(olderThan: Date, statuses: RunStatus[]): Promise<number>;
+    addStep(step: Step): Promise<void>;
+    updateStep(id: string, patch: StepPatch): Promise<void>;
+    getSteps(runId: string): Promise<Step[]>;
+    removeSteps(runId: string): Promise<void>;
+    ping(): Promise<boolean>;
+    generateId(): string;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/adapters/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/adapters/memory.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7E;;;;GAIG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IACtD,OAAO,CAAC,IAAI,CAA0B;IACtC,OAAO,CAAC,KAAK,CAA2B;IACxC,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE;IAIpC,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrC,OAAO,CAAC,cAAc;IAwBhB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKpC,UAAU,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAW5B,cAAc,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAMhC,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC;IAIvC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAM5C,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ7E,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAalE,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,UAAU,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAcvD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAMxC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQzC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAI9B,UAAU,IAAI,MAAM;IAId,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/adapters/memory.js

@@ -0,0 +1,144 @@
+import { randomUUID } from "node:crypto";
+import { registerAdapter } from "./registry.js";
+/**
+ * In-process memory adapter. Useful for single-process scripts and testing.
+ * Does NOT implement SerializableAdapter — child processes get their own
+ * independent MemoryAdapter. Use SqliteAdapter for cross-process persistence.
+ */
+export class MemoryAdapter {
+    runs = new Map();
+    steps = new Map();
+    maxRuns;
+    constructor(options) {
+        this.maxRuns = options?.maxRuns ?? 10_000;
+    }
+    async addRun(run) {
+        this.runs.set(run.id, run);
+        if (this.runs.size > this.maxRuns) {
+            this.evictCompleted();
+        }
+    }
+    evictCompleted() {
+        const terminal = [];
+        for (const [id, run] of this.runs) {
+            if (run.status === "completed" || run.status === "failed" || run.status === "cancelled") {
+                terminal.push(id);
+            }
+        }
+        // Sort oldest first by completedAt
+        terminal.sort((a, b) => {
+            const ra = this.runs.get(a);
+            const rb = this.runs.get(b);
+            return (ra.completedAt?.getTime() ?? 0) - (rb.completedAt?.getTime() ?? 0);
+        });
+        // Evict oldest 10%
+        const evictCount = Math.max(1, Math.floor(terminal.length * 0.1));
+        for (let i = 0; i < evictCount && i < terminal.length; i++) {
+            const id = terminal[i];
+            this.runs.delete(id);
+            for (const [stepId, step] of this.steps) {
+                if (step.runId === id)
+                    this.steps.delete(stepId);
+            }
+        }
+    }
+    async removeRun(id) {
+        this.runs.delete(id);
+        await this.removeSteps(id);
+    }
+    async getRunsDue() {
+        const now = new Date();
+        return Array.from(this.runs.values())
+            .filter((run) => {
+            if (run.status !== "pending")
+                return false;
+            if (!run.nextRunAt)
+                return true;
+            return run.nextRunAt <= now;
+        })
+            .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
+    }
+    async getRunsRunning() {
+        return Array.from(this.runs.values()).filter((run) => run.status === "running");
+    }
+    async getRun(id) {
+        return this.runs.get(id) ?? null;
+    }
+    async updateRun(id, patch) {
+        const run = this.runs.get(id);
+        if (run) {
+            const rec = run;
+            for (const [key, value] of Object.entries(patch)) {
+                if (value === undefined) {
+                    delete rec[key];
+                }
+                else {
+                    rec[key] = value;
+                }
+            }
+        }
+    }
+    async listRuns(signalName) {
+        return Array.from(this.runs.values()).filter((run) => run.signalName === signalName);
+    }
+    async hasRunWithStatus(signalName, statuses) {
+        const statusSet = new Set(statuses);
+        for (const run of this.runs.values()) {
+            if (run.signalName === signalName && statusSet.has(run.status))
+                return true;
+        }
+        return false;
+    }
+    async purgeRuns(olderThan, statuses) {
+        const statusSet = new Set(statuses);
+        let purged = 0;
+        for (const [id, run] of this.runs) {
+            if (statusSet.has(run.status) && run.completedAt && run.completedAt < olderThan) {
+                this.runs.delete(id);
+                await this.removeSteps(id);
+                purged++;
+            }
+        }
+        return purged;
+    }
+    async addStep(step) {
+        this.steps.set(step.id, step);
+    }
+    async updateStep(id, patch) {
+        const step = this.steps.get(id);
+        if (step) {
+            const rec = step;
+            for (const [key, value] of Object.entries(patch)) {
+                if (value === undefined) {
+                    delete rec[key];
+                }
+                else {
+                    rec[key] = value;
+                }
+            }
+        }
+    }
+    async getSteps(runId) {
+        return Array.from(this.steps.values()).filter((step) => step.runId === runId);
+    }
+    async removeSteps(runId) {
+        for (const [id, step] of this.steps) {
+            if (step.runId === runId) {
+                this.steps.delete(id);
+            }
+        }
+    }
+    async ping() {
+        return true;
+    }
+    generateId() {
+        return randomUUID();
+    }
+    async close() {
+        this.runs.clear();
+        this.steps.clear();
+    }
+}
+// Register in the adapter factory for cross-process reconstruction
+registerAdapter("memory", () => new MemoryAdapter());
+//# sourceMappingURL=memory.js.map