absurd-sdk 0.0.4 → 0.0.5

package/README.md

@@ -13,7 +13,7 @@ Durable execution (or durable workflows) is a way to run long-lived, reliable fu
 ## Installation
 
 ```bash
-npm install absurd-sdk
+npm install absurd-sdk pg
 ```
 
 ## Prerequisites
@@ -31,9 +31,7 @@ absurdctl create-queue -d your-database-name default
 ```typescript
 import { Absurd } from "absurd-sdk";
 
-const app = new Absurd({
-  connectionString: "postgresql://localhost/mydb",
-});
+const app = new Absurd({ db: "postgresql://localhost/mydb" });
 
 // Register a task
 app.registerTask({ name: "order-fulfillment" }, async (params, ctx) => {

package/dist/cjs/index.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Absurd = exports.TaskContext = exports.TimeoutError = exports.SuspendTask = void 0;
+exports.Absurd = exports.TaskContext = exports.TimeoutError = exports.CancelledTask = exports.SuspendTask = void 0;
 /**
  * Absurd SDK for TypeScript and JavaScript
  */
@@ -50,6 +50,17 @@ class SuspendTask extends Error {
     }
 }
 exports.SuspendTask = SuspendTask;
+/**
+ * Internal exception that is thrown to cancel a run.  As a user
+ * you should never see this exception.
+ */
+class CancelledTask extends Error {
+    constructor() {
+        super("Task cancelled");
+        this.name = "CancelledTask";
+    }
+}
+exports.CancelledTask = CancelledTask;
 /**
  * This error is thrown when awaiting an event ran into a timeout.
  */
@@ -61,36 +72,48 @@ class TimeoutError extends Error {
 }
 exports.TimeoutError = TimeoutError;
 class TaskContext {
+    log;
     taskID;
-    pool;
+    con;
     queueName;
     task;
     checkpointCache;
     claimTimeout;
     stepNameCounter = new Map();
-    constructor(taskID, pool, queueName, task, checkpointCache, claimTimeout) {
+    constructor(log, taskID, con, queueName, task, checkpointCache, claimTimeout) {
+        this.log = log;
         this.taskID = taskID;
-        this.pool = pool;
+        this.con = con;
         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
+        const { log, taskID, con, queueName, task, claimTimeout } = args;
+        const result = await con.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);
+        return new TaskContext(log, taskID, con, queueName, task, cache, claimTimeout);
+    }
+    async queryWithCancelCheck(sql, params) {
+        try {
+            return await this.con.query(sql, params);
+        }
+        catch (err) {
+            if (err?.code === "AB001") {
+                throw new CancelledTask();
+            }
+            throw err;
+        }
     }
     /**
-     * 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`.
+     * Runs an idempotent step identified by name; caches and reuses its result across retries.
+     * @param name Unique checkpoint name for this step.
+     * @param fn Async function computing the step result (must be JSON-serializable).
      */
     async step(name, fn) {
         const checkpointName = this.getCheckpointName(name);
@@ -103,16 +126,17 @@ class TaskContext {
         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.
+     * Suspends the task until the given duration (seconds) elapses.
+     * @param stepName Checkpoint name for this wait.
+     * @param duration Duration to wait in seconds.
      */
     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.
+     * Suspends the task until the specified time.
+     * @param stepName Checkpoint name for this wait.
+     * @param wakeAt Absolute time when the task should resume.
      */
     async sleepUntil(stepName, wakeAt) {
         const checkpointName = this.getCheckpointName(stepName);
@@ -137,7 +161,7 @@ class TaskContext {
         if (cached !== undefined) {
             return cached;
         }
-        const result = await this.pool.query(`SELECT checkpoint_name, state, status, owner_run_id, updated_at
+        const result = await this.con.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;
@@ -147,7 +171,7 @@ class TaskContext {
         return undefined;
     }
     async persistCheckpoint(checkpointName, value) {
-        await this.pool.query(`SELECT absurd.set_task_checkpoint_state($1, $2, $3, $4, $5, $6)`, [
+        await this.queryWithCancelCheck(`SELECT absurd.set_task_checkpoint_state($1, $2, $3, $4, $5, $6)`, [
             this.queueName,
             this.task.task_id,
             checkpointName,
@@ -158,15 +182,18 @@ class TaskContext {
         this.checkpointCache.set(checkpointName, value);
     }
     async scheduleRun(wakeAt) {
-        await this.pool.query(`SELECT absurd.schedule_run($1, $2, $3)`, [
+        await this.con.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).
+     * Waits for an event by name and returns its payload; optionally sets a custom step name and timeout (seconds).
+     * @param eventName Event identifier to wait for.
+     * @param options.stepName Optional checkpoint name (defaults to $awaitEvent:<eventName>).
+     * @param options.timeout Optional timeout in seconds.
+     * @throws TimeoutError If the event is not received before the timeout.
      */
     async awaitEvent(eventName, options) {
         // the default step name is derived from the event name.
@@ -189,8 +216,8 @@ class TaskContext {
             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)`, [
+        const result = await this.queryWithCancelCheck(`SELECT should_suspend, payload
+        FROM absurd.await_event($1, $2, $3, $4, $5, $6)`, [
             this.queueName,
             this.task.task_id,
             this.task.run_id,
@@ -210,61 +237,90 @@ class TaskContext {
         throw new SuspendTask();
     }
     /**
-     * Emits an event that can be awaited.
+     * Extends the current run's lease by the given seconds (defaults to the original claim timeout).
+     * @param seconds Lease extension in seconds.
+     */
+    async heartbeat(seconds) {
+        await this.queryWithCancelCheck(`SELECT absurd.extend_claim($1, $2, $3)`, [
+            this.queueName,
+            this.task.run_id,
+            seconds ?? this.claimTimeout,
+        ]);
+    }
+    /**
+     * Emits an event to this task's queue with an optional payload.
+     * @param eventName Non-empty event name.
+     * @param payload Optional JSON-serializable payload.
      */
     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)`, [
+        await this.con.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;
+/**
+ * The Absurd SDK Client.
+ *
+ * Instanciate this class and keep it around to interact with Absurd.
+ */
 class Absurd {
-    pool;
+    con;
     ownedPool;
     queueName;
     defaultMaxAttempts;
     registry = new Map();
+    log;
     worker = null;
-    constructor(poolOrUrl, queueName = "default", defaultMaxAttempts = 5) {
-        if (!poolOrUrl) {
-            poolOrUrl =
+    constructor(options = {}) {
+        if (typeof options === "string" || isQueryable(options)) {
+            options = { db: options };
+        }
+        let connectionOrUrl = options.db;
+        if (!connectionOrUrl) {
+            connectionOrUrl =
                 process.env.ABSURD_DATABASE_URL || "postgresql://localhost/absurd";
         }
-        if (typeof poolOrUrl === "string") {
-            this.pool = new pg.Pool({ connectionString: poolOrUrl });
+        if (typeof connectionOrUrl === "string") {
+            this.con = new pg.Pool({ connectionString: connectionOrUrl });
             this.ownedPool = true;
         }
         else {
-            this.pool = poolOrUrl;
+            this.con = connectionOrUrl;
             this.ownedPool = false;
         }
-        this.queueName = queueName;
-        this.defaultMaxAttempts = defaultMaxAttempts;
+        this.queueName = options?.queueName ?? "default";
+        this.defaultMaxAttempts = options?.defaultMaxAttempts ?? 5;
+        this.log = options?.log ?? console;
+    }
+    /**
+     * Returns a new client that uses the provided connection for queries; set owned=true to close it with close().
+     * @param con Connection to bind to.
+     * @param owned If true, the bound client will close this connection on close().
+     */
+    bindToConnection(con, owned = false) {
+        const bound = new Absurd({
+            db: con, // this is okay because we ensure the invariant later
+            queueName: this.queueName,
+            defaultMaxAttempts: this.defaultMaxAttempts,
+            log: this.log,
+        });
+        bound.registry = this.registry;
+        bound.ownedPool = owned;
+        return bound;
     }
     /**
-     * This registers a given function as task.
+     * Registers a task handler by name (optionally specifying queue, defaultMaxAttempts, and defaultCancellation).
+     * @param options.name Task name.
+     * @param options.queue Optional queue name (defaults to client queue).
+     * @param options.defaultMaxAttempts Optional default max attempts.
+     * @param options.defaultCancellation Optional default cancellation policy.
+     * @param handler Async task handler.
      */
     registerTask(options, handler) {
         if (!options?.name) {
@@ -289,16 +345,28 @@ class Absurd {
             handler: handler,
         });
     }
+    /**
+     * Creates a queue (defaults to this client's queue).
+     * @param queueName Queue name to create.
+     */
     async createQueue(queueName) {
         const queue = queueName ?? this.queueName;
-        await this.pool.query(`SELECT absurd.create_queue($1)`, [queue]);
+        await this.con.query(`SELECT absurd.create_queue($1)`, [queue]);
     }
+    /**
+     * Drops a queue (defaults to this client's queue).
+     * @param queueName Queue name to drop.
+     */
     async dropQueue(queueName) {
         const queue = queueName ?? this.queueName;
-        await this.pool.query(`SELECT absurd.drop_queue($1)`, [queue]);
+        await this.con.query(`SELECT absurd.drop_queue($1)`, [queue]);
     }
+    /**
+     * Lists all queue names.
+     * @returns Array of queue names.
+     */
     async listQueues() {
-        const result = await this.pool.query(`SELECT * FROM absurd.list_queues()`);
+        const result = await this.con.query(`SELECT * FROM absurd.list_queues()`);
         const rv = [];
         for (const row of result.rows) {
             rv.push(row.queue_name);
@@ -306,7 +374,17 @@ class Absurd {
         return rv;
     }
     /**
-     * Spawns a specific task.
+     * Spawns a task execution by enqueueing it for processing. The task will be picked up by a worker
+     * and executed with the provided parameters. Returns identifiers that can be used to track or cancel the task.
+     *
+     * For registered tasks, the queue and defaults are inferred from registration. For unregistered tasks,
+     * you must provide options.queue.
+     *
+     * @param taskName Name of the task to spawn (must be registered or provide options.queue).
+     * @param params JSON-serializable parameters passed to the task handler.
+     * @param options Configure queue, maxAttempts, retryStrategy, headers, and cancellation policies.
+     * @returns Object containing taskID (unique task identifier), runID (current attempt identifier), and attempt number.
+     * @throws Error If the task is unregistered without a queue, or if the queue mismatches registration.
      */
     async spawn(taskName, params, options = {}) {
         const registration = this.registry.get(taskName);
@@ -334,7 +412,7 @@ class Absurd {
             maxAttempts: effectiveMaxAttempts,
             cancellation: effectiveCancellation,
         });
-        const result = await this.pool.query(`SELECT task_id, run_id, attempt
+        const result = await this.con.query(`SELECT task_id, run_id, attempt
        FROM absurd.spawn_task($1, $2, $3, $4)`, [
             queue,
             taskName,
@@ -352,28 +430,45 @@ class Absurd {
         };
     }
     /**
-     * Emits an event from outside of a task.
+     * Emits an event with an optional payload on the specified or default queue.
+     * @param eventName Non-empty event name.
+     * @param payload Optional JSON-serializable payload.
+     * @param queueName Queue to emit to (defaults to this client's queue).
      */
     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)`, [
+        await this.con.query(`SELECT absurd.emit_event($1, $2, $3)`, [
             queueName || this.queueName,
             eventName,
             JSON.stringify(payload ?? null),
         ]);
     }
+    /**
+     * Cancels a task by ID on the specified or default queue; running tasks stop at the next checkpoint/heartbeat.
+     * @param taskID Task identifier to cancel.
+     * @param queueName Queue name (defaults to this client's queue).
+     */
+    async cancelTask(taskID, queueName) {
+        await this.con.query(`SELECT absurd.cancel_task($1, $2)`, [
+            queueName || this.queueName,
+            taskID,
+        ]);
+    }
     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,
+        const result = await this.con.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.
+     * Claims up to batchSize tasks and processes them sequentially using the given workerId and claimTimeout.
+     * @param workerId Worker identifier.
+     * @param claimTimeout Lease duration in seconds.
+     * @param batchSize Maximum number of tasks to process.
+     * Note: For parallel processing, use startWorker().
      */
     async workBatch(workerId = "worker", claimTimeout = 120, batchSize = 1) {
         const tasks = await this.claimTasks({ batchSize, claimTimeout, workerId });
@@ -382,18 +477,37 @@ class Absurd {
         }
     }
     /**
-     * Starts a worker that continuously polls for tasks and processes them.
-     * Returns a Worker instance with a close() method for graceful shutdown.
+     * Starts a background worker that continuously polls for and processes tasks from the queue.
+     * The worker will claim tasks up to the configured concurrency limit and process them in parallel.
+     *
+     * Tasks are claimed with a lease (claimTimeout) that prevents other workers from processing them.
+     * The lease is automatically extended when tasks write checkpoints or call heartbeat(). If a worker
+     * crashes or stops making progress, the lease expires and another worker can claim the task.
+     *
+     * @param options Configure worker behavior:
+     *   - concurrency: Max parallel tasks (default: 1)
+     *   - claimTimeout: Task lease duration in seconds (default: 120)
+     *   - batchSize: Tasks to claim per poll (default: concurrency)
+     *   - pollInterval: Seconds between polls when idle (default: 0.25)
+     *   - workerId: Worker identifier for tracking (default: hostname:pid)
+     *   - onError: Error handler called for execution failures
+     *   - fatalOnLeaseTimeout: Terminate process if task exceeds 2x claimTimeout (default: true)
+     * @returns Worker instance with 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("[absurd] Worker error:", err), fatalOnLeaseTimeout = true, } = options;
+        const { workerId = `${os.hostname?.() || "host"}:${process.pid}`, claimTimeout = 120, concurrency = 1, batchSize, pollInterval = 0.25, onError = (err) => console.error("Worker error:", err), fatalOnLeaseTimeout = true, } = options;
         const effectiveBatchSize = batchSize ?? concurrency;
         let running = true;
         let workerLoopPromise;
         const executing = new Set();
         let availabilityPromise = null;
         let availabilityResolve = null;
+        let sleepTimer = null;
         const notifyAvailability = () => {
+            if (sleepTimer) {
+                clearTimeout(sleepTimer);
+                sleepTimer = null;
+            }
             if (availabilityResolve) {
                 availabilityResolve();
                 availabilityResolve = null;
@@ -401,16 +515,18 @@ class Absurd {
             }
         };
         const waitForAvailability = async () => {
-            if (executing.size === 0) {
-                await sleep(pollInterval);
-                return;
-            }
             if (!availabilityPromise) {
                 availabilityPromise = new Promise((resolve) => {
                     availabilityResolve = resolve;
+                    sleepTimer = setTimeout(() => {
+                        sleepTimer = null;
+                        availabilityResolve = null;
+                        availabilityPromise = null;
+                        resolve();
+                    }, pollInterval * 1000);
                 });
             }
-            await Promise.race([availabilityPromise, sleep(pollInterval)]);
+            await availabilityPromise;
         };
         const worker = {
             close: async () => {
@@ -462,12 +578,15 @@ class Absurd {
         })();
         return worker;
     }
+    /**
+     * Stops any running worker and closes the underlying pool if owned.
+     */
     async close() {
         if (this.worker) {
             await this.worker.close();
         }
         if (this.ownedPool) {
-            await this.pool.end();
+            await this.con.end();
         }
     }
     async executeTask(task, claimTimeout, options) {
@@ -475,8 +594,9 @@ class Absurd {
         let fatalTimer;
         const registration = this.registry.get(task.task_name);
         const ctx = await TaskContext.create({
+            log: this.log,
             taskID: task.task_id,
-            pool: this.pool,
+            con: this.con,
             queueName: registration?.queue ?? "unknown",
             task: task,
             claimTimeout,
@@ -485,11 +605,11 @@ class Absurd {
             if (claimTimeout > 0) {
                 const taskLabel = `${task.task_name} (${task.task_id})`;
                 warnTimer = setTimeout(() => {
-                    console.warn(`[absurd] task ${taskLabel} exceeded claim timeout of ${claimTimeout}s`);
+                    this.log.warn(`task ${taskLabel} exceeded claim timeout of ${claimTimeout}s`);
                 }, claimTimeout * 1000);
                 if (options?.fatalOnLeaseTimeout) {
                     fatalTimer = setTimeout(() => {
-                        console.error(`[absurd] task ${taskLabel} exceeded claim timeout of ${claimTimeout}s by more than 100%; terminating process`);
+                        this.log.error(`task ${taskLabel} exceeded claim timeout of ${claimTimeout}s by more than 100%; terminating process`);
                         process.exit(1);
                     }, claimTimeout * 1000 * 2);
                 }
@@ -501,14 +621,15 @@ class Absurd {
                 throw new Error("Misconfigured task (queue mismatch)");
             }
             const result = await registration.handler(task.params, ctx);
-            await ctx.complete(result);
+            await completeTaskRun(this.con, this.queueName, task.run_id, result);
         }
         catch (err) {
-            if (err instanceof SuspendTask) {
-                // Task suspended (sleep or await), don't complete or fail
+            if (err instanceof SuspendTask || err instanceof CancelledTask) {
+                // Task suspended or cancelled (sleep or await), don't complete or fail
                 return;
             }
-            await ctx.fail(err);
+            this.log.error("[absurd] task execution failed:", err);
+            await failTaskRun(this.con, this.queueName, task.run_id, err);
         }
         finally {
             if (warnTimer) {
@@ -521,6 +642,11 @@ class Absurd {
     }
 }
 exports.Absurd = Absurd;
+function isQueryable(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.query === "function");
+}
 function serializeError(err) {
     if (err instanceof Error) {
         return {
@@ -531,6 +657,21 @@ function serializeError(err) {
     }
     return { message: String(err) };
 }
+async function completeTaskRun(con, queueName, runID, result) {
+    await con.query(`SELECT absurd.complete_run($1, $2, $3)`, [
+        queueName,
+        runID,
+        JSON.stringify(result ?? null),
+    ]);
+}
+async function failTaskRun(con, queueName, runID, err) {
+    await con.query(`SELECT absurd.fail_run($1, $2, $3, $4)`, [
+        queueName,
+        runID,
+        JSON.stringify(serializeError(err)),
+        null,
+    ]);
+}
 function normalizeSpawnOptions(options) {
     const normalized = {};
     if (options.headers !== undefined) {
@@ -576,6 +717,3 @@ function normalizeCancellation(policy) {
     }
     return Object.keys(normalized).length > 0 ? normalized : undefined;
 }
-async function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms * 1000));
-}