duroxide 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Affan Dar and contributors
+
+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,158 @@
+# duroxide-node
+
+Node.js/TypeScript SDK for the [Duroxide](https://github.com/affandar/duroxide) durable execution runtime. Write reliable, long-running workflows in JavaScript using generator functions — backed by a Rust runtime that handles persistence, replay, and fault tolerance.
+
+> See [CHANGELOG.md](CHANGELOG.md) for release notes.
+
+## Features
+
+- **Durable orchestrations** — generator-based workflows that survive process restarts
+- **Automatic replay** — the Rust runtime replays history on restart, your code picks up where it left off
+- **Activities** — async functions for side effects (API calls, DB writes, etc.)
+- **Timers** — durable delays that persist across restarts
+- **Sub-orchestrations** — compose workflows from smaller workflows
+- **External events** — pause workflows and wait for signals
+- **Fan-out/fan-in** — run tasks in parallel with `ctx.all()` (supports all task types)
+- **Race conditions** — wait for the first of multiple tasks with `ctx.race()` (supports all task types)
+- **Cooperative cancellation** — activities detect when they're no longer needed via `ctx.isCancelled()`
+- **Continue-as-new** — restart orchestrations with fresh history for eternal workflows
+- **Structured tracing** — orchestration and activity logs route through Rust's `tracing` crate
+- **SQLite & PostgreSQL** — pluggable storage backends
+
+## Quick Start
+
+```bash
+npm install duroxide
+```
+
+```javascript
+const { SqliteProvider, Client, Runtime } = require('duroxide');
+
+async function main() {
+  // 1. Open a storage backend
+  const provider = await SqliteProvider.open('sqlite:myapp.db');
+  const client = new Client(provider);
+  const runtime = new Runtime(provider);
+
+  // 2. Register activities (async functions with side effects)
+  runtime.registerActivity('Greet', async (ctx, name) => {
+    ctx.traceInfo(`greeting ${name}`);
+    return `Hello, ${name}!`;
+  });
+
+  // 3. Register orchestrations (generator functions)
+  runtime.registerOrchestration('GreetWorkflow', function* (ctx, input) {
+    const greeting = yield ctx.scheduleActivity('Greet', input.name);
+    ctx.traceInfo(`got: ${greeting}`);
+    return greeting;
+  });
+
+  // 4. Start the runtime
+  await runtime.start();
+
+  // 5. Start an orchestration and wait for it
+  await client.startOrchestration('greet-1', 'GreetWorkflow', { name: 'World' });
+  const result = await client.waitForOrchestration('greet-1');
+  console.log(result.output); // "Hello, World!"
+
+  await runtime.shutdown();
+}
+
+main();
+```
+
+## Why Generators (not async/await)?
+
+Duroxide uses `function*` generators instead of `async function` for orchestrations. This is a deliberate design choice — see [Architecture](docs/architecture.md#yield-vs-await) for the full explanation. The short version: generators give Rust full control over when and how each step executes, which is essential for deterministic replay.
+
+```javascript
+// ✅ Orchestrations use yield
+runtime.registerOrchestration('MyWorkflow', function* (ctx, input) {
+  const result = yield ctx.scheduleActivity('DoWork', input);
+  return result;
+});
+
+// ✅ Activities use async/await (normal async functions)
+runtime.registerActivity('DoWork', async (ctx, input) => {
+  const data = await fetch(`https://api.example.com/${input}`);
+  return data;
+});
+```
+
+## Orchestration Context API
+
+All scheduling methods return descriptors that must be **yielded**:
+
+| Method | Description |
+|--------|-------------|
+| `yield ctx.scheduleActivity(name, input)` | Run an activity |
+| `yield ctx.scheduleActivityWithRetry(name, input, retryPolicy)` | Run with retry |
+| `yield ctx.scheduleTimer(delayMs)` | Durable delay |
+| `yield ctx.waitForEvent(eventName)` | Wait for external signal |
+| `yield ctx.scheduleSubOrchestration(name, input)` | Run child workflow (await result) |
+| `yield ctx.scheduleSubOrchestrationWithId(name, id, input)` | Child with explicit ID |
+| `yield ctx.startOrchestration(name, id, input)` | Fire-and-forget orchestration |
+| `yield ctx.all([task1, task2, ...])` | Parallel execution (like `Promise.all`) |
+| `yield ctx.race(task1, task2)` | First-to-complete (like `Promise.race`) |
+| `yield ctx.utcNow()` | Deterministic timestamp |
+| `yield ctx.newGuid()` | Deterministic GUID |
+| `yield ctx.continueAsNew(newInput)` | Restart with fresh history |
+
+Tracing methods are **fire-and-forget** (no yield needed):
+
+| Method | Description |
+|--------|-------------|
+| `ctx.traceInfo(message)` | INFO log (suppressed during replay) |
+| `ctx.traceWarn(message)` | WARN log |
+| `ctx.traceError(message)` | ERROR log |
+| `ctx.traceDebug(message)` | DEBUG log |
+
+## Storage Backends
+
+### SQLite
+
+```javascript
+const provider = await SqliteProvider.open('sqlite:path/to/db.db');
+// or in-memory:
+const provider = await SqliteProvider.inMemory();
+```
+
+### PostgreSQL
+
+```javascript
+const provider = await PostgresProvider.connectWithSchema(
+  'postgresql://user:pass@host:5432/db',
+  'my_schema'
+);
+```
+
+## Logging
+
+Duroxide uses Rust's `tracing` crate. Control verbosity with `RUST_LOG`:
+
+```bash
+RUST_LOG=info node app.js              # INFO and above
+RUST_LOG=duroxide=debug node app.js    # DEBUG for duroxide only
+RUST_LOG=duroxide::activity=info node app.js  # Activity traces only
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — how the Rust/JS interop works, yield vs await, limitations
+- [User Guide](docs/user-guide.md) — patterns, recipes, and best practices
+
+## Tests
+
+Requires PostgreSQL (see `.env.example`):
+
+```bash
+npm test                 # e2e tests (23 PG + 1 SQLite smoketest)
+npm run test:races       # Race/join composition tests (7 tests)
+npm run test:admin       # Admin API tests (14 tests)
+npm run test:scenarios   # Scenario tests (6 tests)
+npm run test:all         # Everything (50 tests)
+```
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,220 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/** Runtime options configurable from JavaScript. */
+export interface JsRuntimeOptions {
+  /** Orchestration concurrency (default: 4) */
+  orchestrationConcurrency?: number
+  /** Worker/activity concurrency (default: 8) */
+  workerConcurrency?: number
+  /** Dispatcher poll interval in ms (default: 100) */
+  dispatcherPollIntervalMs?: number
+  /**
+   * Worker lock timeout in ms (default: 30000). Controls how often the activity
+   * manager renews locks, which affects cancellation detection speed.
+   */
+  workerLockTimeoutMs?: number
+}
+/** Orchestration status returned to JS. */
+export interface JsOrchestrationStatus {
+  status: string
+  output?: string
+  error?: string
+}
+/** System metrics returned to JS. */
+export interface JsSystemMetrics {
+  totalInstances: number
+  totalExecutions: number
+  runningInstances: number
+  completedInstances: number
+  failedInstances: number
+  totalEvents: number
+}
+/** Queue depths returned to JS. */
+export interface JsQueueDepths {
+  orchestratorQueue: number
+  workerQueue: number
+  timerQueue: number
+}
+/** Instance info returned to JS. */
+export interface JsInstanceInfo {
+  instanceId: string
+  orchestrationName: string
+  orchestrationVersion: string
+  currentExecutionId: number
+  status: string
+  output?: string
+  createdAt: number
+  updatedAt: number
+  parentInstanceId?: string
+}
+/** Execution info returned to JS. */
+export interface JsExecutionInfo {
+  executionId: number
+  status: string
+  output?: string
+  startedAt: number
+  completedAt?: number
+  eventCount: number
+}
+/** Instance tree returned to JS. */
+export interface JsInstanceTree {
+  rootId: string
+  allIds: Array<string>
+  size: number
+}
+/** Delete result returned to JS. */
+export interface JsDeleteInstanceResult {
+  instancesDeleted: number
+  executionsDeleted: number
+  eventsDeleted: number
+  queueMessagesDeleted: number
+}
+/** Prune options from JS. */
+export interface JsPruneOptions {
+  keepLast?: number
+  completedBefore?: number
+}
+/** Prune result returned to JS. */
+export interface JsPruneResult {
+  instancesProcessed: number
+  executionsDeleted: number
+  eventsDeleted: number
+}
+/** Instance filter from JS. */
+export interface JsInstanceFilter {
+  instanceIds?: Array<string>
+  completedBefore?: number
+  limit?: number
+}
+/** A single history event returned to JS. */
+export interface JsEvent {
+  eventId: number
+  kind: string
+  sourceEventId?: number
+  timestampMs: number
+}
+/**
+ * Emit an activity trace through the current Rust ActivityContext.
+ * Delegates to ActivityContext.trace_info/warn/error/debug which includes
+ * all structured fields (instance_id, activity_name, activity_id, worker_id, etc.)
+ */
+export declare function activityTraceLog(token: string, level: string, message: string): void
+/**
+ * Emit an orchestration trace through the Rust OrchestrationContext.
+ * Delegates to OrchestrationContext.trace() which checks is_replaying
+ * and includes all structured fields (instance_id, orchestration_name, etc.)
+ */
+export declare function orchestrationTraceLog(instanceId: string, level: string, message: string): void
+/**
+ * Check if an activity's cancellation token has been triggered.
+ * Returns true if the activity has been cancelled (e.g., due to losing a race/select).
+ */
+export declare function activityIsCancelled(token: string): boolean
+/** Wraps duroxide's Client for use from JavaScript. */
+export declare class JsClient {
+  constructor(provider: JsSqliteProvider)
+  /** Create a client backed by PostgreSQL. */
+  static fromPostgres(provider: JsPostgresProvider): JsClient
+  /** Start a new orchestration instance. */
+  startOrchestration(instanceId: string, orchestrationName: string, input: string): Promise<void>
+  /** Start a new orchestration instance with a specific version. */
+  startOrchestrationVersioned(instanceId: string, orchestrationName: string, input: string, version: string): Promise<void>
+  /** Get the current status of an orchestration instance. */
+  getStatus(instanceId: string): Promise<JsOrchestrationStatus>
+  /** Wait for an orchestration to complete (with timeout in milliseconds). */
+  waitForOrchestration(instanceId: string, timeoutMs: number): Promise<JsOrchestrationStatus>
+  /** Cancel a running orchestration instance. */
+  cancelInstance(instanceId: string, reason?: string | undefined | null): Promise<void>
+  /** Raise an external event to an orchestration instance. */
+  raiseEvent(instanceId: string, eventName: string, data: string): Promise<void>
+  /** Get system metrics (if provider supports management). */
+  getSystemMetrics(): Promise<JsSystemMetrics>
+  /** Get queue depths (if provider supports management). */
+  getQueueDepths(): Promise<JsQueueDepths>
+  /** List all orchestration instance IDs. */
+  listAllInstances(): Promise<Array<string>>
+  /** List orchestration instance IDs by status. */
+  listInstancesByStatus(status: string): Promise<Array<string>>
+  /** Get detailed info about a specific instance. */
+  getInstanceInfo(instanceId: string): Promise<JsInstanceInfo>
+  /** Get detailed info about a specific execution within an instance. */
+  getExecutionInfo(instanceId: string, executionId: number): Promise<JsExecutionInfo>
+  /** List execution IDs for an instance. */
+  listExecutions(instanceId: string): Promise<Array<number>>
+  /** Read the event history for a specific execution. */
+  readExecutionHistory(instanceId: string, executionId: number): Promise<Array<JsEvent>>
+  /** Get the full instance tree (root + all descendants). */
+  getInstanceTree(instanceId: string): Promise<JsInstanceTree>
+  /** Delete an orchestration instance and all its data. */
+  deleteInstance(instanceId: string, force: boolean): Promise<JsDeleteInstanceResult>
+  /** Delete multiple instances matching a filter. */
+  deleteInstanceBulk(filter: JsInstanceFilter): Promise<JsDeleteInstanceResult>
+  /** Prune old executions from a single instance. */
+  pruneExecutions(instanceId: string, options: JsPruneOptions): Promise<JsPruneResult>
+  /** Prune old executions from multiple instances matching a filter. */
+  pruneExecutionsBulk(filter: JsInstanceFilter, options: JsPruneOptions): Promise<JsPruneResult>
+}
+/** Wraps duroxide-pg's PostgresProvider for use from JavaScript. */
+export declare class JsPostgresProvider {
+  /**
+   * Connect to a PostgreSQL database.
+   * Uses the default "public" schema.
+   */
+  static connect(databaseUrl: string): Promise<JsPostgresProvider>
+  /**
+   * Connect to a PostgreSQL database with a custom schema.
+   * The schema will be created if it does not exist.
+   */
+  static connectWithSchema(databaseUrl: string, schema: string): Promise<JsPostgresProvider>
+}
+/** Wraps duroxide's SqliteProvider for use from JavaScript. */
+export declare class JsSqliteProvider {
+  /**
+   * Open a SQLite database at the given file path.
+   * Path should be a sqlite: URL, e.g. "sqlite:./data.db" or "sqlite:/tmp/test.db".
+   * The file will be created if it does not exist.
+   */
+  static open(path: string): Promise<JsSqliteProvider>
+  /** Create an in-memory SQLite database (useful for testing). */
+  static inMemory(): Promise<JsSqliteProvider>
+}
+/** Builder for the duroxide runtime, wrapping registration and startup. */
+export declare class JsRuntime {
+  constructor(provider: JsSqliteProvider, options?: JsRuntimeOptions | undefined | null)
+  /** Create a runtime backed by PostgreSQL. */
+  static fromPostgres(provider: JsPostgresProvider, options?: JsRuntimeOptions | undefined | null): JsRuntime
+  /**
+   * Set the generator driver functions (called once from JS before registering orchestrations).
+   * These three functions handle: creating generators, driving next steps, and disposing.
+   */
+  setGeneratorDriver(createFn: (arg: string) => any, nextFn: (arg: string) => any, disposeFn: (arg: string) => any): void
+  /**
+   * Register a JavaScript activity function.
+   * The JS function receives (contextInfoJson, input) and returns a Promise<string>.
+   */
+  registerActivity(name: string, callback: (arg: string) => any): void
+  /**
+   * Register a JavaScript orchestration (generator function).
+   * The orchestration name is used for both registration and the generator function lookup.
+   */
+  registerOrchestration(name: string): void
+  /** Register a versioned JavaScript orchestration. */
+  registerOrchestrationVersioned(name: string, version: string): void
+  /**
+   * Start the runtime. This processes orchestrations and activities until shutdown.
+   *
+   * # Safety
+   * This is async and takes &mut self. napi-rs requires async &mut methods to be marked unsafe.
+   */
+  start(): Promise<void>
+  /**
+   * Shutdown the runtime gracefully.
+   *
+   * # Safety
+   * Must not be called concurrently from multiple threads.
+   */
+  shutdown(timeoutMs?: number | undefined | null): Promise<void>
+}