absurd-sdk 0.0.2

package/README.md

@@ -0,0 +1,109 @@
+# Absurd SDK for TypeScript
+
+TypeScript SDK for [Absurd](https://github.com/earendil-works/absurd): a PostgreSQL-based durable task execution system.
+
+Absurd is the simplest durable execution workflow system you can think of.  It's entirely based on Postgres and nothing else.  It's almost as easy to use as a queue, but it handles scheduling and retries, and it does all of that without needing any other services to run in addition to Postgres.
+
+**Warning:** *this is an early experiment and should not be used in production.*
+
+## What is Durable Execution?
+
+Durable execution (or durable workflows) is a way to run long-lived, reliable functions that can survive crashes, restarts, and network failures without losing state or duplicating work. Instead of running your logic in memory, a durable execution system decomposes a task into smaller pieces (step functions) and records every step and decision.
+
+## Installation
+
+```bash
+npm install absurd-sdk
+```
+
+## Prerequisites
+
+Before using the SDK, you need to initialize Absurd in your PostgreSQL database:
+
+```bash
+# Install absurdctl from https://github.com/earendil-works/absurd/releases
+absurdctl init -d your-database-name
+absurdctl create-queue -d your-database-name default
+```
+
+## Quick Start
+
+```typescript
+import { Absurd } from 'absurd-sdk';
+
+const app = new Absurd({
+  connectionString: 'postgresql://localhost/mydb'
+});
+
+// Register a task
+app.registerTask({ name: 'order-fulfillment' }, async (params, ctx) => {
+  // Each step is checkpointed, so if the process crashes, we resume
+  // from the last completed step
+  const payment = await ctx.step('process-payment', async () => {
+    return await processPayment(params.amount);
+  });
+
+  const inventory = await ctx.step('reserve-inventory', async () => {
+    return await reserveItems(params.items);
+  });
+
+  // Wait for an event - the task suspends until the event arrives
+  const shipment = await ctx.awaitEvent(`shipment.packed:${params.orderId}`);
+
+  await ctx.step('send-notification', async () => {
+    return await sendEmail(params.email, shipment);
+  });
+
+  return { orderId: payment.id, trackingNumber: shipment.trackingNumber };
+});
+
+// Start a worker that pulls tasks from Postgres
+await app.startWorker();
+```
+
+## Spawning Tasks
+
+```typescript
+// Spawn a task - it will be executed durably with automatic retries
+await app.spawn('order-fulfillment', {
+  orderId: '42',
+  amount: 9999,
+  items: ['widget-1', 'gadget-2'],
+  email: 'customer@example.com'
+});
+```
+
+## Emitting Events
+
+```typescript
+// Emit an event that a suspended task might be waiting for
+await app.emitEvent('shipment.packed:42', {
+  trackingNumber: 'TRACK123'
+});
+```
+
+## Idempotency Keys
+
+Use the task ID to derive idempotency keys for external APIs:
+
+```typescript
+const payment = await ctx.step('process-payment', async () => {
+  const idempotencyKey = `${ctx.taskID}:payment`;
+  return await stripe.charges.create({
+    amount: params.amount,
+    idempotencyKey,
+  });
+});
+```
+
+## Documentation
+
+For more information, examples, and documentation, visit:
+
+- [Main Repository](https://github.com/earendil-works/absurd)
+- [Examples](https://github.com/earendil-works/absurd/tree/main/sdks/typescript/examples)
+- [Issue Tracker](https://github.com/earendil-works/absurd/issues)
+
+## License
+
+Apache-2.0

package/dist/cjs/index.js

@@ -0,0 +1,527 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Absurd = exports.TaskContext = exports.TimeoutError = exports.SuspendTask = void 0;
+/**
+ * Absurd SDK for TypeScript and JavaScript
+ */
+const pg = __importStar(require("pg"));
+const os = __importStar(require("os"));
+/**
+ * Internal exception that is thrown to suspend a run.  As a user
+ * you should never see this exception.
+ */
+class SuspendTask extends Error {
+    constructor() {
+        super("Task suspended");
+        this.name = "SuspendTask";
+    }
+}
+exports.SuspendTask = SuspendTask;
+/**
+ * This error is thrown when awaiting an event ran into a timeout.
+ */
+class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+exports.TimeoutError = TimeoutError;
+class TaskContext {
+    taskID;
+    pool;
+    queueName;
+    task;
+    checkpointCache;
+    claimTimeout;
+    stepNameCounter = new Map();
+    constructor(taskID, pool, queueName, task, checkpointCache, claimTimeout) {
+        this.taskID = taskID;
+        this.pool = pool;
+        this.queueName = queueName;
+        this.task = task;
+        this.checkpointCache = checkpointCache;
+        this.claimTimeout = claimTimeout;
+    }
+    static async create(args) {
+        const { taskID, pool, queueName, task, claimTimeout } = args;
+        const result = await pool.query(`SELECT checkpoint_name, state, status, owner_run_id, updated_at
+       FROM absurd.get_task_checkpoint_states($1, $2, $3)`, [queueName, task.task_id, task.run_id]);
+        const cache = new Map();
+        for (const row of result.rows) {
+            cache.set(row.checkpoint_name, row.state);
+        }
+        return new TaskContext(taskID, pool, queueName, task, cache, claimTimeout);
+    }
+    /**
+     * Defines a step in the task execution.  Steps are idempotent in
+     * that they are executed exactly once (unless they fail) and their
+     * results are cached.  As a result the return value of this function
+     * must support `JSON.stringify`.
+     */
+    async step(name, fn) {
+        const checkpointName = this.getCheckpointName(name);
+        const state = await this.lookupCheckpoint(checkpointName);
+        if (state !== undefined) {
+            return state;
+        }
+        const rv = await fn();
+        await this.persistCheckpoint(checkpointName, rv);
+        return rv;
+    }
+    /**
+     * Sleeps for a given number of seconds.  Note that this
+     * *always* suspends the task, even if you only wait for a very
+     * short period of time.
+     */
+    async sleepFor(stepName, duration) {
+        return await this.sleepUntil(stepName, new Date(Date.now() + duration * 1000));
+    }
+    /**
+     * Like `sleepFor` but with an absolute time when the task should be
+     * awoken again.
+     */
+    async sleepUntil(stepName, wakeAt) {
+        const checkpointName = this.getCheckpointName(stepName);
+        const state = await this.lookupCheckpoint(checkpointName);
+        let actualWakeAt = typeof state === "string" ? new Date(state) : wakeAt;
+        if (!state) {
+            await this.persistCheckpoint(checkpointName, wakeAt.toISOString());
+        }
+        if (Date.now() < actualWakeAt.getTime()) {
+            await this.scheduleRun(actualWakeAt);
+            throw new SuspendTask();
+        }
+    }
+    getCheckpointName(name) {
+        const count = (this.stepNameCounter.get(name) ?? 0) + 1;
+        this.stepNameCounter.set(name, count);
+        const actualStepName = count === 1 ? name : `${name}#${count}`;
+        return actualStepName;
+    }
+    async lookupCheckpoint(checkpointName) {
+        const cached = this.checkpointCache.get(checkpointName);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = await this.pool.query(`SELECT checkpoint_name, state, status, owner_run_id, updated_at
+       FROM absurd.get_task_checkpoint_state($1, $2, $3)`, [this.queueName, this.task.task_id, checkpointName]);
+        if (result.rows.length > 0) {
+            const state = result.rows[0].state;
+            this.checkpointCache.set(checkpointName, state);
+            return state;
+        }
+        return undefined;
+    }
+    async persistCheckpoint(checkpointName, value) {
+        await this.pool.query(`SELECT absurd.set_task_checkpoint_state($1, $2, $3, $4, $5, $6)`, [
+            this.queueName,
+            this.task.task_id,
+            checkpointName,
+            JSON.stringify(value),
+            this.task.run_id,
+            this.claimTimeout,
+        ]);
+        this.checkpointCache.set(checkpointName, value);
+    }
+    async scheduleRun(wakeAt) {
+        await this.pool.query(`SELECT absurd.schedule_run($1, $2, $3)`, [
+            this.queueName,
+            this.task.run_id,
+            wakeAt,
+        ]);
+    }
+    /**
+     * Awaits the arrival of an event.  Events need to be uniquely
+     * named so fold in the necessary parameters into the name (eg: customer id).
+     */
+    async awaitEvent(eventName, options) {
+        // the default step name is derived from the event name.
+        const stepName = options?.stepName || `$awaitEvent:${eventName}`;
+        let timeout = null;
+        if (options?.timeout !== undefined &&
+            Number.isFinite(options?.timeout) &&
+            options?.timeout >= 0) {
+            timeout = Math.floor(options?.timeout);
+        }
+        const checkpointName = this.getCheckpointName(stepName);
+        const cached = await this.lookupCheckpoint(checkpointName);
+        if (cached !== undefined) {
+            return cached;
+        }
+        if (this.task.wake_event === eventName &&
+            (this.task.event_payload === null ||
+                this.task.event_payload === undefined)) {
+            this.task.wake_event = null;
+            this.task.event_payload = null;
+            throw new TimeoutError(`Timed out waiting for event "${eventName}"`);
+        }
+        const result = await this.pool.query(`SELECT should_suspend, payload
+       FROM absurd.await_event($1, $2, $3, $4, $5, $6)`, [
+            this.queueName,
+            this.task.task_id,
+            this.task.run_id,
+            checkpointName,
+            eventName,
+            timeout,
+        ]);
+        if (result.rows.length === 0) {
+            throw new Error("Failed to await event");
+        }
+        const { should_suspend, payload } = result.rows[0];
+        if (!should_suspend) {
+            this.checkpointCache.set(checkpointName, payload);
+            this.task.event_payload = null;
+            return payload;
+        }
+        throw new SuspendTask();
+    }
+    /**
+     * Emits an event that can be awaited.
+     */
+    async emitEvent(eventName, payload) {
+        if (!eventName) {
+            throw new Error("eventName must be a non-empty string");
+        }
+        await this.pool.query(`SELECT absurd.emit_event($1, $2, $3)`, [
+            this.queueName,
+            eventName,
+            JSON.stringify(payload ?? null),
+        ]);
+    }
+    async complete(result) {
+        await this.pool.query(`SELECT absurd.complete_run($1, $2, $3)`, [
+            this.queueName,
+            this.task.run_id,
+            JSON.stringify(result ?? null),
+        ]);
+    }
+    async fail(err) {
+        console.error("[absurd] task execution failed:", err);
+        await this.pool.query(`SELECT absurd.fail_run($1, $2, $3, $4)`, [
+            this.queueName,
+            this.task.run_id,
+            JSON.stringify(serializeError(err)),
+            null,
+        ]);
+    }
+}
+exports.TaskContext = TaskContext;
+class Absurd {
+    pool;
+    ownedPool;
+    queueName;
+    defaultMaxAttempts;
+    registry = new Map();
+    worker = null;
+    constructor(poolOrUrl, queueName = "default", defaultMaxAttempts = 5) {
+        if (!poolOrUrl) {
+            poolOrUrl =
+                process.env.ABSURD_DATABASE_URL || "postgresql://localhost/absurd";
+        }
+        if (typeof poolOrUrl === "string") {
+            this.pool = new pg.Pool({ connectionString: poolOrUrl });
+            this.ownedPool = true;
+        }
+        else {
+            this.pool = poolOrUrl;
+            this.ownedPool = false;
+        }
+        this.queueName = queueName;
+        this.defaultMaxAttempts = defaultMaxAttempts;
+    }
+    /**
+     * This registers a given function as task.
+     */
+    registerTask(options, handler) {
+        if (!options?.name) {
+            throw new Error("Task registration requires a name");
+        }
+        if (options.defaultMaxAttempts !== undefined &&
+            options.defaultMaxAttempts < 1) {
+            throw new Error("defaultMaxAttempts must be at least 1");
+        }
+        if (options.defaultCancellation) {
+            normalizeCancellation(options.defaultCancellation);
+        }
+        const queue = options.queue ?? this.queueName;
+        if (!queue) {
+            throw new Error(`Task "${options.name}" must specify a queue or use a client with a default queue`);
+        }
+        this.registry.set(options.name, {
+            name: options.name,
+            queue,
+            defaultMaxAttempts: options.defaultMaxAttempts,
+            defaultCancellation: options.defaultCancellation,
+            handler: handler,
+        });
+    }
+    async createQueue(queueName) {
+        const queue = queueName ?? this.queueName;
+        await this.pool.query(`SELECT absurd.create_queue($1)`, [queue]);
+    }
+    async dropQueue(queueName) {
+        const queue = queueName ?? this.queueName;
+        await this.pool.query(`SELECT absurd.drop_queue($1)`, [queue]);
+    }
+    async listQueues() {
+        const result = await this.pool.query(`SELECT * FROM absurd.list_queues()`);
+        const rv = [];
+        console.log(result);
+        for (const row of result.rows) {
+            rv.push(row.queue_name);
+        }
+        return rv;
+    }
+    /**
+     * Spawns a specific task.
+     */
+    async spawn(taskName, params, options = {}) {
+        const registration = this.registry.get(taskName);
+        let queue;
+        if (registration) {
+            queue = registration.queue;
+            if (options.queue !== undefined && options.queue !== registration.queue) {
+                throw new Error(`Task "${taskName}" is registered for queue "${registration.queue}" but spawn requested queue "${options.queue}".`);
+            }
+        }
+        else if (!options.queue) {
+            throw new Error(`Task "${taskName}" is not registered. Provide options.queue when spawning unregistered tasks.`);
+        }
+        else {
+            queue = options.queue;
+        }
+        const effectiveMaxAttempts = options.maxAttempts !== undefined
+            ? options.maxAttempts
+            : (registration?.defaultMaxAttempts ?? this.defaultMaxAttempts);
+        const effectiveCancellation = options.cancellation !== undefined
+            ? options.cancellation
+            : registration?.defaultCancellation;
+        const normalizedOptions = normalizeSpawnOptions({
+            ...options,
+            maxAttempts: effectiveMaxAttempts,
+            cancellation: effectiveCancellation,
+        });
+        const result = await this.pool.query(`SELECT task_id, run_id, attempt
+       FROM absurd.spawn_task($1, $2, $3, $4)`, [
+            queue,
+            taskName,
+            JSON.stringify(params),
+            JSON.stringify(normalizedOptions),
+        ]);
+        if (result.rows.length === 0) {
+            throw new Error("Failed to spawn task");
+        }
+        const row = result.rows[0];
+        return {
+            taskID: row.task_id,
+            runID: row.run_id,
+            attempt: row.attempt,
+        };
+    }
+    /**
+     * Emits an event from outside of a task.
+     */
+    async emitEvent(eventName, payload, queueName) {
+        if (!eventName) {
+            throw new Error("eventName must be a non-empty string");
+        }
+        await this.pool.query(`SELECT absurd.emit_event($1, $2, $3)`, [
+            queueName || this.queueName,
+            eventName,
+            JSON.stringify(payload ?? null),
+        ]);
+    }
+    async claimTasks(options) {
+        const { batchSize: count = 1, claimTimeout = 120, workerId = "worker", } = options ?? {};
+        const result = await this.pool.query(`SELECT run_id, task_id, attempt, task_name, params, retry_strategy, max_attempts,
+              headers, wake_event, event_payload
+       FROM absurd.claim_task($1, $2, $3, $4)`, [this.queueName, workerId, claimTimeout, count]);
+        return result.rows;
+    }
+    /**
+     * Polls and processes a batch of messages sequentially.
+     * For parallel processing, use startWorker with concurrency option.
+     */
+    async workBatch(workerId = "worker", claimTimeout = 120, batchSize = 1) {
+        const tasks = await this.claimTasks({ batchSize, claimTimeout, workerId });
+        for (const task of tasks) {
+            await this.executeTask(task, claimTimeout);
+        }
+    }
+    /**
+     * Starts a worker that continuously polls for tasks and processes them.
+     * Returns a Worker instance with a close() method for graceful shutdown.
+     */
+    async startWorker(options = {}) {
+        const { workerId = `${os.hostname?.() || "host"}:${process.pid}`, claimTimeout = 120, concurrency = 1, batchSize, pollInterval = 0.25, onError = (err) => console.error("Worker error:", err), } = options;
+        const effectiveBatchSize = batchSize ?? concurrency;
+        let running = true;
+        let workerLoopPromise;
+        const worker = {
+            close: async () => {
+                running = false;
+                await workerLoopPromise;
+            },
+        };
+        this.worker = worker;
+        workerLoopPromise = (async () => {
+            while (running) {
+                try {
+                    const messages = await this.claimTasks({
+                        batchSize: effectiveBatchSize,
+                        claimTimeout: claimTimeout,
+                        workerId,
+                    });
+                    if (messages.length === 0) {
+                        await sleep(pollInterval);
+                        continue;
+                    }
+                    const executing = new Set();
+                    for (const task of messages) {
+                        const promise = this.executeTask(task, claimTimeout)
+                            .catch((err) => onError(err))
+                            .finally(() => executing.delete(promise));
+                        executing.add(promise);
+                        if (executing.size >= concurrency) {
+                            await Promise.race(executing);
+                        }
+                    }
+                    await Promise.all(executing);
+                }
+                catch (err) {
+                    onError(err);
+                    await sleep(pollInterval);
+                }
+            }
+        })();
+        return worker;
+    }
+    async close() {
+        if (this.worker) {
+            await this.worker.close();
+        }
+        if (this.ownedPool) {
+            await this.pool.end();
+        }
+    }
+    async executeTask(task, claimTimeout) {
+        const registration = this.registry.get(task.task_name);
+        const ctx = await TaskContext.create({
+            taskID: task.task_id,
+            pool: this.pool,
+            queueName: registration?.queue ?? "unknown",
+            task: task,
+            claimTimeout,
+        });
+        try {
+            if (!registration) {
+                throw new Error("Unknown task");
+            }
+            else if (registration.queue !== this.queueName) {
+                throw new Error("Misconfigured task (queue mismatch)");
+            }
+            const result = await registration.handler(task.params, ctx);
+            await ctx.complete(result);
+        }
+        catch (err) {
+            if (err instanceof SuspendTask) {
+                // Task suspended (sleep or await), don't complete or fail
+                return;
+            }
+            await ctx.fail(err);
+        }
+    }
+}
+exports.Absurd = Absurd;
+function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name,
+            message: err.message,
+            stack: err.stack || null,
+        };
+    }
+    return { message: String(err) };
+}
+function normalizeSpawnOptions(options) {
+    const normalized = {};
+    if (options.headers !== undefined) {
+        normalized.headers = options.headers;
+    }
+    if (options.maxAttempts !== undefined) {
+        normalized.max_attempts = options.maxAttempts;
+    }
+    if (options.retryStrategy) {
+        normalized.retry_strategy = serializeRetryStrategy(options.retryStrategy);
+    }
+    const cancellation = normalizeCancellation(options.cancellation);
+    if (cancellation) {
+        normalized.cancellation = cancellation;
+    }
+    return normalized;
+}
+function serializeRetryStrategy(strategy) {
+    const serialized = {
+        kind: strategy.kind,
+    };
+    if (strategy.baseSeconds !== undefined) {
+        serialized.base_seconds = strategy.baseSeconds;
+    }
+    if (strategy.factor !== undefined) {
+        serialized.factor = strategy.factor;
+    }
+    if (strategy.maxSeconds !== undefined) {
+        serialized.max_seconds = strategy.maxSeconds;
+    }
+    return serialized;
+}
+function normalizeCancellation(policy) {
+    if (!policy) {
+        return undefined;
+    }
+    const normalized = {};
+    if (policy.maxDuration !== undefined) {
+        normalized.max_duration = policy.maxDuration;
+    }
+    if (policy.maxDelay !== undefined) {
+        normalized.max_delay = policy.maxDelay;
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms * 1000));
+}

package/dist/index.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Absurd SDK for TypeScript and JavaScript
+ */
+import * as pg from "pg";
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export interface RetryStrategy {
+    kind: "fixed" | "exponential" | "none";
+    baseSeconds?: number;
+    factor?: number;
+    maxSeconds?: number;
+}
+export interface CancellationPolicy {
+    maxDuration?: number;
+    maxDelay?: number;
+}
+export interface SpawnOptions {
+    maxAttempts?: number;
+    retryStrategy?: RetryStrategy;
+    headers?: JsonObject;
+    queue?: string;
+    cancellation?: CancellationPolicy;
+}
+export interface ClaimedTask {
+    run_id: string;
+    task_id: string;
+    task_name: string;
+    attempt: number;
+    params: JsonValue;
+    retry_strategy: JsonValue;
+    max_attempts: number | null;
+    headers: JsonObject | null;
+    wake_event: string | null;
+    event_payload: JsonValue | null;
+}
+export interface WorkerOptions {
+    workerId?: string;
+    claimTimeout?: number;
+    batchSize?: number;
+    concurrency?: number;
+    pollInterval?: number;
+    onError?: (error: Error) => void;
+}
+export interface Worker {
+    close(): Promise<void>;
+}
+interface SpawnResult {
+    taskID: string;
+    runID: string;
+    attempt: number;
+}
+export type TaskHandler<P = any, R = any> = (params: P, ctx: TaskContext) => Promise<R>;
+/**
+ * Internal exception that is thrown to suspend a run.  As a user
+ * you should never see this exception.
+ */
+export declare class SuspendTask extends Error {
+    constructor();
+}
+/**
+ * This error is thrown when awaiting an event ran into a timeout.
+ */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+export interface TaskRegistrationOptions {
+    name: string;
+    queue?: string;
+    defaultMaxAttempts?: number;
+    defaultCancellation?: CancellationPolicy;
+}
+export declare class TaskContext {
+    readonly taskID: string;
+    private readonly pool;
+    private readonly queueName;
+    private readonly task;
+    private readonly checkpointCache;
+    private readonly claimTimeout;
+    private stepNameCounter;
+    private constructor();
+    static create(args: {
+        taskID: string;
+        pool: pg.Pool;
+        queueName: string;
+        task: ClaimedTask;
+        claimTimeout: number;
+    }): Promise<TaskContext>;
+    /**
+     * Defines a step in the task execution.  Steps are idempotent in
+     * that they are executed exactly once (unless they fail) and their
+     * results are cached.  As a result the return value of this function
+     * must support `JSON.stringify`.
+     */
+    step<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Sleeps for a given number of seconds.  Note that this
+     * *always* suspends the task, even if you only wait for a very
+     * short period of time.
+     */
+    sleepFor(stepName: string, duration: number): Promise<void>;
+    /**
+     * Like `sleepFor` but with an absolute time when the task should be
+     * awoken again.
+     */
+    sleepUntil(stepName: string, wakeAt: Date): Promise<void>;
+    private getCheckpointName;
+    private lookupCheckpoint;
+    private persistCheckpoint;
+    private scheduleRun;
+    /**
+     * Awaits the arrival of an event.  Events need to be uniquely
+     * named so fold in the necessary parameters into the name (eg: customer id).
+     */
+    awaitEvent(eventName: string, options?: {
+        stepName?: string;
+        timeout?: number;
+    }): Promise<JsonValue>;
+    /**
+     * Emits an event that can be awaited.
+     */
+    emitEvent(eventName: string, payload?: JsonValue): Promise<void>;
+    complete(result?: any): Promise<void>;
+    fail(err: unknown): Promise<void>;
+}
+export declare class Absurd {
+    private readonly pool;
+    private readonly ownedPool;
+    private readonly queueName;
+    private readonly defaultMaxAttempts;
+    private readonly registry;
+    private worker;
+    constructor(poolOrUrl?: pg.Pool | string | null, queueName?: string, defaultMaxAttempts?: number);
+    /**
+     * This registers a given function as task.
+     */
+    registerTask<P = any, R = any>(options: TaskRegistrationOptions, handler: TaskHandler<P, R>): void;
+    createQueue(queueName?: string): Promise<void>;
+    dropQueue(queueName?: string): Promise<void>;
+    listQueues(): Promise<Array<string>>;
+    /**
+     * Spawns a specific task.
+     */
+    spawn<P = any>(taskName: string, params: P, options?: SpawnOptions): Promise<SpawnResult>;
+    /**
+     * Emits an event from outside of a task.
+     */
+    emitEvent(eventName: string, payload?: JsonValue, queueName?: string): Promise<void>;
+    claimTasks(options?: {
+        batchSize?: number;
+        claimTimeout?: number;
+        workerId?: string;
+    }): Promise<ClaimedTask[]>;
+    /**
+     * Polls and processes a batch of messages sequentially.
+     * For parallel processing, use startWorker with concurrency option.
+     */
+    workBatch(workerId?: string, claimTimeout?: number, batchSize?: number): Promise<void>;
+    /**
+     * Starts a worker that continuously polls for tasks and processes them.
+     * Returns a Worker instance with a close() method for graceful shutdown.
+     */
+    startWorker(options?: WorkerOptions): Promise<Worker>;
+    close(): Promise<void>;
+    private executeTask;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,488 @@
+/**
+ * Absurd SDK for TypeScript and JavaScript
+ */
+import * as pg from "pg";
+import * as os from "os";
+/**
+ * Internal exception that is thrown to suspend a run.  As a user
+ * you should never see this exception.
+ */
+export class SuspendTask extends Error {
+    constructor() {
+        super("Task suspended");
+        this.name = "SuspendTask";
+    }
+}
+/**
+ * This error is thrown when awaiting an event ran into a timeout.
+ */
+export class TimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "TimeoutError";
+    }
+}
+export class TaskContext {
+    taskID;
+    pool;
+    queueName;
+    task;
+    checkpointCache;
+    claimTimeout;
+    stepNameCounter = new Map();
+    constructor(taskID, pool, queueName, task, checkpointCache, claimTimeout) {
+        this.taskID = taskID;
+        this.pool = pool;
+        this.queueName = queueName;
+        this.task = task;
+        this.checkpointCache = checkpointCache;
+        this.claimTimeout = claimTimeout;
+    }
+    static async create(args) {
+        const { taskID, pool, queueName, task, claimTimeout } = args;
+        const result = await pool.query(`SELECT checkpoint_name, state, status, owner_run_id, updated_at
+       FROM absurd.get_task_checkpoint_states($1, $2, $3)`, [queueName, task.task_id, task.run_id]);
+        const cache = new Map();
+        for (const row of result.rows) {
+            cache.set(row.checkpoint_name, row.state);
+        }
+        return new TaskContext(taskID, pool, queueName, task, cache, claimTimeout);
+    }
+    /**
+     * Defines a step in the task execution.  Steps are idempotent in
+     * that they are executed exactly once (unless they fail) and their
+     * results are cached.  As a result the return value of this function
+     * must support `JSON.stringify`.
+     */
+    async step(name, fn) {
+        const checkpointName = this.getCheckpointName(name);
+        const state = await this.lookupCheckpoint(checkpointName);
+        if (state !== undefined) {
+            return state;
+        }
+        const rv = await fn();
+        await this.persistCheckpoint(checkpointName, rv);
+        return rv;
+    }
+    /**
+     * Sleeps for a given number of seconds.  Note that this
+     * *always* suspends the task, even if you only wait for a very
+     * short period of time.
+     */
+    async sleepFor(stepName, duration) {
+        return await this.sleepUntil(stepName, new Date(Date.now() + duration * 1000));
+    }
+    /**
+     * Like `sleepFor` but with an absolute time when the task should be
+     * awoken again.
+     */
+    async sleepUntil(stepName, wakeAt) {
+        const checkpointName = this.getCheckpointName(stepName);
+        const state = await this.lookupCheckpoint(checkpointName);
+        let actualWakeAt = typeof state === "string" ? new Date(state) : wakeAt;
+        if (!state) {
+            await this.persistCheckpoint(checkpointName, wakeAt.toISOString());
+        }
+        if (Date.now() < actualWakeAt.getTime()) {
+            await this.scheduleRun(actualWakeAt);
+            throw new SuspendTask();
+        }
+    }
+    getCheckpointName(name) {
+        const count = (this.stepNameCounter.get(name) ?? 0) + 1;
+        this.stepNameCounter.set(name, count);
+        const actualStepName = count === 1 ? name : `${name}#${count}`;
+        return actualStepName;
+    }
+    async lookupCheckpoint(checkpointName) {
+        const cached = this.checkpointCache.get(checkpointName);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = await this.pool.query(`SELECT checkpoint_name, state, status, owner_run_id, updated_at
+       FROM absurd.get_task_checkpoint_state($1, $2, $3)`, [this.queueName, this.task.task_id, checkpointName]);
+        if (result.rows.length > 0) {
+            const state = result.rows[0].state;
+            this.checkpointCache.set(checkpointName, state);
+            return state;
+        }
+        return undefined;
+    }
+    async persistCheckpoint(checkpointName, value) {
+        await this.pool.query(`SELECT absurd.set_task_checkpoint_state($1, $2, $3, $4, $5, $6)`, [
+            this.queueName,
+            this.task.task_id,
+            checkpointName,
+            JSON.stringify(value),
+            this.task.run_id,
+            this.claimTimeout,
+        ]);
+        this.checkpointCache.set(checkpointName, value);
+    }
+    async scheduleRun(wakeAt) {
+        await this.pool.query(`SELECT absurd.schedule_run($1, $2, $3)`, [
+            this.queueName,
+            this.task.run_id,
+            wakeAt,
+        ]);
+    }
+    /**
+     * Awaits the arrival of an event.  Events need to be uniquely
+     * named so fold in the necessary parameters into the name (eg: customer id).
+     */
+    async awaitEvent(eventName, options) {
+        // the default step name is derived from the event name.
+        const stepName = options?.stepName || `$awaitEvent:${eventName}`;
+        let timeout = null;
+        if (options?.timeout !== undefined &&
+            Number.isFinite(options?.timeout) &&
+            options?.timeout >= 0) {
+            timeout = Math.floor(options?.timeout);
+        }
+        const checkpointName = this.getCheckpointName(stepName);
+        const cached = await this.lookupCheckpoint(checkpointName);
+        if (cached !== undefined) {
+            return cached;
+        }
+        if (this.task.wake_event === eventName &&
+            (this.task.event_payload === null ||
+                this.task.event_payload === undefined)) {
+            this.task.wake_event = null;
+            this.task.event_payload = null;
+            throw new TimeoutError(`Timed out waiting for event "${eventName}"`);
+        }
+        const result = await this.pool.query(`SELECT should_suspend, payload
+       FROM absurd.await_event($1, $2, $3, $4, $5, $6)`, [
+            this.queueName,
+            this.task.task_id,
+            this.task.run_id,
+            checkpointName,
+            eventName,
+            timeout,
+        ]);
+        if (result.rows.length === 0) {
+            throw new Error("Failed to await event");
+        }
+        const { should_suspend, payload } = result.rows[0];
+        if (!should_suspend) {
+            this.checkpointCache.set(checkpointName, payload);
+            this.task.event_payload = null;
+            return payload;
+        }
+        throw new SuspendTask();
+    }
+    /**
+     * Emits an event that can be awaited.
+     */
+    async emitEvent(eventName, payload) {
+        if (!eventName) {
+            throw new Error("eventName must be a non-empty string");
+        }
+        await this.pool.query(`SELECT absurd.emit_event($1, $2, $3)`, [
+            this.queueName,
+            eventName,
+            JSON.stringify(payload ?? null),
+        ]);
+    }
+    async complete(result) {
+        await this.pool.query(`SELECT absurd.complete_run($1, $2, $3)`, [
+            this.queueName,
+            this.task.run_id,
+            JSON.stringify(result ?? null),
+        ]);
+    }
+    async fail(err) {
+        console.error("[absurd] task execution failed:", err);
+        await this.pool.query(`SELECT absurd.fail_run($1, $2, $3, $4)`, [
+            this.queueName,
+            this.task.run_id,
+            JSON.stringify(serializeError(err)),
+            null,
+        ]);
+    }
+}
+export class Absurd {
+    pool;
+    ownedPool;
+    queueName;
+    defaultMaxAttempts;
+    registry = new Map();
+    worker = null;
+    constructor(poolOrUrl, queueName = "default", defaultMaxAttempts = 5) {
+        if (!poolOrUrl) {
+            poolOrUrl =
+                process.env.ABSURD_DATABASE_URL || "postgresql://localhost/absurd";
+        }
+        if (typeof poolOrUrl === "string") {
+            this.pool = new pg.Pool({ connectionString: poolOrUrl });
+            this.ownedPool = true;
+        }
+        else {
+            this.pool = poolOrUrl;
+            this.ownedPool = false;
+        }
+        this.queueName = queueName;
+        this.defaultMaxAttempts = defaultMaxAttempts;
+    }
+    /**
+     * This registers a given function as task.
+     */
+    registerTask(options, handler) {
+        if (!options?.name) {
+            throw new Error("Task registration requires a name");
+        }
+        if (options.defaultMaxAttempts !== undefined &&
+            options.defaultMaxAttempts < 1) {
+            throw new Error("defaultMaxAttempts must be at least 1");
+        }
+        if (options.defaultCancellation) {
+            normalizeCancellation(options.defaultCancellation);
+        }
+        const queue = options.queue ?? this.queueName;
+        if (!queue) {
+            throw new Error(`Task "${options.name}" must specify a queue or use a client with a default queue`);
+        }
+        this.registry.set(options.name, {
+            name: options.name,
+            queue,
+            defaultMaxAttempts: options.defaultMaxAttempts,
+            defaultCancellation: options.defaultCancellation,
+            handler: handler,
+        });
+    }
+    async createQueue(queueName) {
+        const queue = queueName ?? this.queueName;
+        await this.pool.query(`SELECT absurd.create_queue($1)`, [queue]);
+    }
+    async dropQueue(queueName) {
+        const queue = queueName ?? this.queueName;
+        await this.pool.query(`SELECT absurd.drop_queue($1)`, [queue]);
+    }
+    async listQueues() {
+        const result = await this.pool.query(`SELECT * FROM absurd.list_queues()`);
+        const rv = [];
+        console.log(result);
+        for (const row of result.rows) {
+            rv.push(row.queue_name);
+        }
+        return rv;
+    }
+    /**
+     * Spawns a specific task.
+     */
+    async spawn(taskName, params, options = {}) {
+        const registration = this.registry.get(taskName);
+        let queue;
+        if (registration) {
+            queue = registration.queue;
+            if (options.queue !== undefined && options.queue !== registration.queue) {
+                throw new Error(`Task "${taskName}" is registered for queue "${registration.queue}" but spawn requested queue "${options.queue}".`);
+            }
+        }
+        else if (!options.queue) {
+            throw new Error(`Task "${taskName}" is not registered. Provide options.queue when spawning unregistered tasks.`);
+        }
+        else {
+            queue = options.queue;
+        }
+        const effectiveMaxAttempts = options.maxAttempts !== undefined
+            ? options.maxAttempts
+            : (registration?.defaultMaxAttempts ?? this.defaultMaxAttempts);
+        const effectiveCancellation = options.cancellation !== undefined
+            ? options.cancellation
+            : registration?.defaultCancellation;
+        const normalizedOptions = normalizeSpawnOptions({
+            ...options,
+            maxAttempts: effectiveMaxAttempts,
+            cancellation: effectiveCancellation,
+        });
+        const result = await this.pool.query(`SELECT task_id, run_id, attempt
+       FROM absurd.spawn_task($1, $2, $3, $4)`, [
+            queue,
+            taskName,
+            JSON.stringify(params),
+            JSON.stringify(normalizedOptions),
+        ]);
+        if (result.rows.length === 0) {
+            throw new Error("Failed to spawn task");
+        }
+        const row = result.rows[0];
+        return {
+            taskID: row.task_id,
+            runID: row.run_id,
+            attempt: row.attempt,
+        };
+    }
+    /**
+     * Emits an event from outside of a task.
+     */
+    async emitEvent(eventName, payload, queueName) {
+        if (!eventName) {
+            throw new Error("eventName must be a non-empty string");
+        }
+        await this.pool.query(`SELECT absurd.emit_event($1, $2, $3)`, [
+            queueName || this.queueName,
+            eventName,
+            JSON.stringify(payload ?? null),
+        ]);
+    }
+    async claimTasks(options) {
+        const { batchSize: count = 1, claimTimeout = 120, workerId = "worker", } = options ?? {};
+        const result = await this.pool.query(`SELECT run_id, task_id, attempt, task_name, params, retry_strategy, max_attempts,
+              headers, wake_event, event_payload
+       FROM absurd.claim_task($1, $2, $3, $4)`, [this.queueName, workerId, claimTimeout, count]);
+        return result.rows;
+    }
+    /**
+     * Polls and processes a batch of messages sequentially.
+     * For parallel processing, use startWorker with concurrency option.
+     */
+    async workBatch(workerId = "worker", claimTimeout = 120, batchSize = 1) {
+        const tasks = await this.claimTasks({ batchSize, claimTimeout, workerId });
+        for (const task of tasks) {
+            await this.executeTask(task, claimTimeout);
+        }
+    }
+    /**
+     * Starts a worker that continuously polls for tasks and processes them.
+     * Returns a Worker instance with a close() method for graceful shutdown.
+     */
+    async startWorker(options = {}) {
+        const { workerId = `${os.hostname?.() || "host"}:${process.pid}`, claimTimeout = 120, concurrency = 1, batchSize, pollInterval = 0.25, onError = (err) => console.error("Worker error:", err), } = options;
+        const effectiveBatchSize = batchSize ?? concurrency;
+        let running = true;
+        let workerLoopPromise;
+        const worker = {
+            close: async () => {
+                running = false;
+                await workerLoopPromise;
+            },
+        };
+        this.worker = worker;
+        workerLoopPromise = (async () => {
+            while (running) {
+                try {
+                    const messages = await this.claimTasks({
+                        batchSize: effectiveBatchSize,
+                        claimTimeout: claimTimeout,
+                        workerId,
+                    });
+                    if (messages.length === 0) {
+                        await sleep(pollInterval);
+                        continue;
+                    }
+                    const executing = new Set();
+                    for (const task of messages) {
+                        const promise = this.executeTask(task, claimTimeout)
+                            .catch((err) => onError(err))
+                            .finally(() => executing.delete(promise));
+                        executing.add(promise);
+                        if (executing.size >= concurrency) {
+                            await Promise.race(executing);
+                        }
+                    }
+                    await Promise.all(executing);
+                }
+                catch (err) {
+                    onError(err);
+                    await sleep(pollInterval);
+                }
+            }
+        })();
+        return worker;
+    }
+    async close() {
+        if (this.worker) {
+            await this.worker.close();
+        }
+        if (this.ownedPool) {
+            await this.pool.end();
+        }
+    }
+    async executeTask(task, claimTimeout) {
+        const registration = this.registry.get(task.task_name);
+        const ctx = await TaskContext.create({
+            taskID: task.task_id,
+            pool: this.pool,
+            queueName: registration?.queue ?? "unknown",
+            task: task,
+            claimTimeout,
+        });
+        try {
+            if (!registration) {
+                throw new Error("Unknown task");
+            }
+            else if (registration.queue !== this.queueName) {
+                throw new Error("Misconfigured task (queue mismatch)");
+            }
+            const result = await registration.handler(task.params, ctx);
+            await ctx.complete(result);
+        }
+        catch (err) {
+            if (err instanceof SuspendTask) {
+                // Task suspended (sleep or await), don't complete or fail
+                return;
+            }
+            await ctx.fail(err);
+        }
+    }
+}
+function serializeError(err) {
+    if (err instanceof Error) {
+        return {
+            name: err.name,
+            message: err.message,
+            stack: err.stack || null,
+        };
+    }
+    return { message: String(err) };
+}
+function normalizeSpawnOptions(options) {
+    const normalized = {};
+    if (options.headers !== undefined) {
+        normalized.headers = options.headers;
+    }
+    if (options.maxAttempts !== undefined) {
+        normalized.max_attempts = options.maxAttempts;
+    }
+    if (options.retryStrategy) {
+        normalized.retry_strategy = serializeRetryStrategy(options.retryStrategy);
+    }
+    const cancellation = normalizeCancellation(options.cancellation);
+    if (cancellation) {
+        normalized.cancellation = cancellation;
+    }
+    return normalized;
+}
+function serializeRetryStrategy(strategy) {
+    const serialized = {
+        kind: strategy.kind,
+    };
+    if (strategy.baseSeconds !== undefined) {
+        serialized.base_seconds = strategy.baseSeconds;
+    }
+    if (strategy.factor !== undefined) {
+        serialized.factor = strategy.factor;
+    }
+    if (strategy.maxSeconds !== undefined) {
+        serialized.max_seconds = strategy.maxSeconds;
+    }
+    return serialized;
+}
+function normalizeCancellation(policy) {
+    if (!policy) {
+        return undefined;
+    }
+    const normalized = {};
+    if (policy.maxDuration !== undefined) {
+        normalized.max_duration = policy.maxDuration;
+    }
+    if (policy.maxDelay !== undefined) {
+        normalized.max_delay = policy.maxDelay;
+    }
+    return Object.keys(normalized).length > 0 ? normalized : undefined;
+}
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms * 1000));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "absurd-sdk",
+  "version": "0.0.2",
+  "description": "TypeScript SDK for Absurd - PostgreSQL-based durable task execution",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json && tsc --project tsconfig.cjs.json",
+    "prepare": "npm run build",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "absurd",
+    "postgresql",
+    "queue",
+    "task",
+    "durable",
+    "workflow"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/earendil-works/absurd"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "pg": "^8.13.1",
+    "typescript": "^5.9.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/pg": "^8.11.10"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}