cairnq 0.7.0 → 0.9.0

package/src/store/postgres.ts

@@ -1,5 +1,3 @@
-import type * as PG from "pg";
-
 import { loadMigrations, loadStatements } from "../sql.js";
 import {
   checkProtocolVersion,
@@ -9,48 +7,16 @@ import {
   type Params,
   statementParams,
   TaskStore,
+  type WatchSignal,
 } from "./base.js";
-
-// `pg` is an optional dependency: the SDK is SQLite-first, so it's loaded lazily
-// the first time a PostgresStore connects. Absent -> a clear install hint.
-let pgModule: typeof import("pg") | null = null;
-async function loadPg(): Promise<typeof import("pg")> {
-  if (pgModule) return pgModule;
-  let mod: { default?: typeof import("pg") } & typeof import("pg");
-  try {
-    mod = (await import("pg")) as never;
-  } catch {
-    throw new Error("PostgresStore requires the 'pg' package — install it (e.g. `npm i pg`)");
-  }
-  const pg = (mod.default ?? mod) as typeof import("pg");
-  // Postgres returns bigint (int8, OID 20) as a string to avoid precision loss.
-  // Every cairnq bigint is an epoch-ms or a counter, all within Number's safe
-  // integer range, so parse to number once (globally) to match the Task model
-  // (*_ms typed as number, same as the SQLite SDK). Set before any query runs.
-  pg.types.setTypeParser(pg.types.builtins.INT8, (v: string) => (v == null ? null : Number(v)));
-  pgModule = pg;
-  return pg;
-}
-
-/**
- * Roll back on the way out of a failed transaction, without letting the rollback
- * become the error the caller sees. A dropped connection fails both the statement
- * and the rollback, and it is the first one that says what went wrong.
- */
-async function rollbackQuietly(client: PG.PoolClient): Promise<void> {
-  try {
-    await client.query("rollback");
-  } catch {
-    // Already rolled back, or the connection is gone. Either way the original
-    // error is the one worth propagating.
-  }
-}
+import { ListenUnavailable, type PgExecutor, type PgSession } from "./pg-executor.js";
+import { createPoolExecutor } from "./pg-pool.js";
 
 // Notification channels, emitted by the 0003_notify trigger.
 const QUEUED_CHANNEL = "cairnq_queued";
 const DONE_CHANNEL = "cairnq_done";
 
-// Backoff between attempts to (re)connect the LISTEN connection after a
+// Backoff between attempts to (re)establish the LISTEN subscription after a
 // transient failure. Doubles per failure up to the cap; polling covers the gap.
 const LISTENER_RETRY_MS = 1_000;
 const LISTENER_RETRY_MAX_MS = 30_000;
@@ -100,26 +66,38 @@ export function toPositional(
  * PostgresStore — the Postgres dialect of the shared cairnq-protocol SQL.
  *
  * Everything protocol-shaped lives in TaskStore; this file is only what Postgres
- * does differently: a `pg` Pool, `:name` -> `$n` translation, and time taken from
- * the DB clock (`now()`) instead of from the SDK, which is what makes this backend
- * multi-host — unlike SQLite it coordinates API and worker processes across
- * machines, with no shared clock to agree on. claim uses FOR UPDATE SKIP LOCKED
- * and needs no claimable_probe, because PG readers don't block writers. JSON
- * columns are jsonb (bound as JSON text, read back as objects by rowToTask).
+ * does differently: `:name` -> `$n` translation, the migration ledger, LISTEN
+ * policy, and time taken from the DB clock (`now()`) instead of from the SDK,
+ * which is what makes this backend multi-host — unlike SQLite it coordinates API
+ * and worker processes across machines, with no shared clock to agree on. claim
+ * uses FOR UPDATE SKIP LOCKED and needs no claimable_probe, because PG readers
+ * don't block writers. JSON columns are jsonb (bound as JSON text, read back as
+ * objects by rowToTask).
+ *
+ * What it deliberately does NOT own is the connection. Given a DSN it builds a
+ * `pg` pool (see pg-pool.ts); given a PgExecutor it runs inside the caller's
+ * session instead — no second driver, no second pool, and the caller's writes and
+ * cairnq's can share one transaction.
  */
 export class PostgresStore extends TaskStore {
-  private pool: PG.Pool | null = null;
+  private readonly dsn: string | null;
+  /** The caller's executor, if one was injected — never closed by this store. */
+  private readonly provided: PgExecutor | null;
+  /** Set once migrations have run and the protocol version checked out. */
+  private executor: PgExecutor | null = null;
   private connecting: Promise<void> | null = null;
   private readonly statements: Record<string, string>;
 
   // ------------------------------------------------------- LISTEN/NOTIFY state
-  // One dedicated connection LISTENs on both channels (see 0003_notify.sql and
-  // the claimWake/taskDoneWake contract on TaskStore). Failure to establish or
-  // keep it silently degrades the store to the base class's plain polling.
-  private listener: PG.Client | null = null;
+  // The executor subscribes one dedicated connection to both channels (see
+  // 0003_notify.sql and the claimWake/taskDoneWake contract on TaskStore).
+  // Failure to establish or keep it silently degrades the store to the base
+  // class's plain polling. Held as the unsubscribe function, not the connection:
+  // whose connection it is, is the executor's business.
+  private listener: (() => void) | null = null;
   private listenerConnecting: Promise<void> | null = null;
-  /** LISTEN is off for good: the store was closed, or the server accepted a
-   * connection but refused LISTEN (e.g. a transaction-mode pooler) —
+  /** LISTEN is off for good: the store was closed, the executor does not support
+   * it, or the server refused it (e.g. a transaction-mode pooler) —
    * deterministic, so retrying would fail the same way every time. */
   private listenerUnavailable = false;
   /** A failure to even connect is transient (network blip, server restarting):
@@ -132,12 +110,22 @@ export class PostgresStore extends TaskStore {
   private readonly pendingQueues = new Set<string>();
   /** Wake callbacks by key: "queued" (broadcast) or "done:<task id>". */
   private readonly waiters = new Map<string, Set<() => void>>();
+  /** watch() subscribers. Separate from `waiters`: a waiter is one-shot and
+   * consumes the notification, a subscriber is standing and only observes. */
+  private readonly subscribers = new Set<(signal: WatchSignal) => void>();
 
+  /**
+   * `source` is either a libpq connection string — this store then owns a `pg`
+   * pool and requires the optional `pg` package — or a PgExecutor the caller
+   * already has, which this store uses and never closes.
+   */
   constructor(
-    private readonly dsn: string,
-    private readonly opts: { max?: number } = {},
+    source: string | PgExecutor,
+    private readonly opts: { max?: number; schema?: string } = {},
   ) {
     super();
+    this.dsn = typeof source === "string" ? source : null;
+    this.provided = typeof source === "string" ? null : source;
     this.statements = loadStatements("postgres");
   }
 
@@ -148,18 +136,19 @@ export class PostgresStore extends TaskStore {
   async close(): Promise<void> {
     this.listenerUnavailable = true; // no revival after close
     this.dropListener();
-    if (this.pool) {
-      const p = this.pool;
-      this.pool = null;
-      this.connecting = null;
-      await p.end();
-    }
+    const executor = this.executor;
+    this.executor = null;
+    this.connecting = null;
+    // An injected executor belongs to the caller, whose other work would not
+    // survive cairnq closing it.
+    if (executor && !this.provided) await executor.close();
   }
 
   private async ensure(): Promise<void> {
-    if (this.pool) return;
-    // Cache the in-flight connect so concurrent calls share one pool. On failure,
-    // clear it so a later call retries instead of re-awaiting a rejected promise.
+    if (this.executor) return;
+    // Cache the in-flight connect so concurrent calls share one executor. On
+    // failure, clear it so a later call retries instead of re-awaiting a
+    // rejected promise.
     if (!this.connecting) {
       this.connecting = this.doConnect().catch((e) => {
         this.connecting = null;
@@ -170,28 +159,25 @@ export class PostgresStore extends TaskStore {
   }
 
   private async doConnect(): Promise<void> {
-    const pg = await loadPg();
-    const pool = new pg.Pool({ connectionString: this.dsn, max: this.opts.max });
+    const executor =
+      this.provided ??
+      (await createPoolExecutor(this.dsn!, { max: this.opts.max, schema: this.opts.schema }));
     try {
-      const client = await pool.connect();
-      try {
-        await this.applyMigrations(client);
-        checkProtocolVersion(await this.readProtocolVersion(client));
-      } finally {
-        client.release();
-      }
+      await this.applyMigrations(executor);
+      checkProtocolVersion(await this.readProtocolVersion(executor));
     } catch (e) {
-      await pool.end(); // never leak a pool when connect fails
+      // Never leak an executor we created; never close one we were handed.
+      if (!this.provided) await executor.close().catch(() => {});
       throw e;
     }
-    this.pool = pool; // publish only a fully-migrated, version-checked pool
-    // Warm the LISTEN connection in the background so the first idle sleep is
+    this.executor = executor; // publish only a fully-migrated, version-checked executor
+    // Warm the LISTEN subscription in the background so the first idle sleep is
     // already wakeable. Fire-and-forget: failure just means polling.
     this.listenerReady();
   }
 
-  private async applyMigrations(client: PG.PoolClient): Promise<void> {
-    await client.query(
+  private async applyMigrations(executor: PgExecutor): Promise<void> {
+    await executor.exec(
       "create table if not exists cairnq_migrations " +
         "(name text primary key, applied_at_ms bigint not null)",
     );
@@ -199,43 +185,31 @@ export class PostgresStore extends TaskStore {
       // Check and apply inside one transaction, with the table lock taken up
       // front: two processes cold-starting together would otherwise both see a
       // migration as unapplied and both run it.
-      try {
-        await client.query("begin");
-        await client.query("lock table cairnq_migrations in exclusive mode");
-        const applied = await client.query("select 1 from cairnq_migrations where name = $1", [
-          name,
-        ]);
-        if (applied.rowCount === 0) {
-          await client.query(sql); // multi-statement DDL (simple-query, no params)
-          await client.query(
+      await executor.tx(async (s) => {
+        await s.exec("lock table cairnq_migrations in exclusive mode");
+        const applied = await s.query("select 1 from cairnq_migrations where name = $1", [name]);
+        if (applied.length === 0) {
+          await s.exec(sql); // multi-statement DDL (simple-query, no params)
+          await s.query(
             "insert into cairnq_migrations (name, applied_at_ms) values " +
               "($1, (extract(epoch from now()) * 1000)::bigint)",
             [name],
           );
         }
-        await client.query("commit");
-      } catch (e) {
-        await rollbackQuietly(client);
-        throw e;
-      }
+      });
     }
   }
 
-  // Takes an explicit client: during doConnect the pool is not published yet, so
-  // this cannot go through fetch(). The statement binds nothing, so it runs as-is.
-  private async readProtocolVersion(client: PG.PoolClient): Promise<number> {
-    const res = await client.query(this.statements.protocol_version);
-    return res.rows.length ? Number(res.rows[0].value) : 0;
+  // Takes an explicit session: during doConnect the executor is not published
+  // yet, so this cannot go through fetch(). The statement binds nothing.
+  private async readProtocolVersion(s: PgSession): Promise<number> {
+    const rows = await s.query(this.statements.protocol_version, []);
+    return rows.length ? Number(rows[0].value) : 0;
   }
 
   async protocolVersion(): Promise<number> {
     await this.ensure();
-    const client = await this.pool!.connect();
-    try {
-      return await this.readProtocolVersion(client);
-    } finally {
-      client.release();
-    }
+    return this.readProtocolVersion(this.executor!);
   }
 
   // ------------------------------------------------------------ wake channel
@@ -255,6 +229,16 @@ export class PostgresStore extends TaskStore {
     }
   }
 
+  protected subscribePush(onSignal: (signal: WatchSignal) => void): () => void {
+    this.subscribers.add(onSignal);
+    this.listenerReady(); // an API-side watcher is often the only thing asking
+    return () => void this.subscribers.delete(onSignal);
+  }
+
+  protected warmPush(): void {
+    if (this.subscribers.size > 0) this.listenerReady();
+  }
+
   taskDoneWake(taskId: string, timeoutMs: number): Promise<void> {
     if (!this.listenerReady()) return super.taskDoneWake(taskId, timeoutMs);
     return this.wakeOn(`done:${taskId}`, timeoutMs);
@@ -280,7 +264,7 @@ export class PostgresStore extends TaskStore {
     });
   }
 
-  /** True once the LISTEN connection is up; starts connecting it otherwise
+  /** True once the LISTEN subscription is up; starts establishing it otherwise
    * (respecting the transient-failure backoff). Callers fall back to plain
    * polling until it is ready (or forever, if it can't be established) —
    * correctness never depends on it. */
@@ -294,36 +278,39 @@ export class PostgresStore extends TaskStore {
 
   private async startListener(): Promise<void> {
     try {
-      const pg = await loadPg();
-      // Built from the raw DSN: if `opts` ever grows connection-level settings
-      // (ssl, application_name), the listener must receive them too.
-      const client = new pg.Client({ connectionString: this.dsn });
+      const executor = this.executor ?? this.provided;
+      // Not connected yet: transient by definition — doConnect calls back in.
+      if (!executor) return;
+      if (!executor.listen) {
+        this.listenerUnavailable = true; // this executor will never push
+        return;
+      }
+      let stop: () => void;
       try {
-        await client.connect();
-      } catch {
-        // Could not even connect — transient. Schedule a backed-off retry;
+        stop = await executor.listen(
+          [QUEUED_CHANNEL, DONE_CHANNEL],
+          (channel, payload) => this.onNotification(channel, payload),
+          // A dropped listener degrades to polling; the next wake reconnects.
+          () => this.dropListener(),
+        );
+      } catch (e) {
+        if (e instanceof ListenUnavailable) {
+          // Deterministic (e.g. a transaction-mode pooler): off for good rather
+          // than a reconnect loop that cannot succeed. Polling covers it.
+          this.listenerUnavailable = true;
+          return;
+        }
+        // Could not establish it — transient. Schedule a backed-off retry;
         // polling covers the gap.
         this.listenerRetryAt = Date.now() + this.listenerBackoffMs;
         this.listenerBackoffMs = Math.min(LISTENER_RETRY_MAX_MS, this.listenerBackoffMs * 2);
         return;
       }
-      client.on("notification", (msg) => this.onNotification(msg.channel, msg.payload));
-      // A dropped listener degrades to polling; the next wake call reconnects.
-      client.on("error", () => this.dropListener());
-      try {
-        await client.query(`listen ${QUEUED_CHANNEL}; listen ${DONE_CHANNEL}`);
-      } catch {
-        // Connected, but LISTEN was refused (e.g. a transaction-mode pooler) —
-        // deterministic, so off for good. Polling covers it.
-        this.listenerUnavailable = true;
-        void client.end().catch(() => {});
-        return;
-      }
       if (this.listenerUnavailable) {
-        void client.end().catch(() => {}); // closed while we were connecting
+        stop(); // closed while we were subscribing
         return;
       }
-      this.listener = client;
+      this.listener = stop;
       this.listenerBackoffMs = LISTENER_RETRY_MS;
     } catch {
       // Anything unexpected (e.g. `pg` failed to load): off for good rather
@@ -339,8 +326,10 @@ export class PostgresStore extends TaskStore {
     if (channel === QUEUED_CHANNEL && payload) {
       this.pendingQueues.add(payload);
       key = "queued";
+      this.publish({ reason: "queued", queue: payload });
     } else if (channel === DONE_CHANNEL && payload) {
       key = `done:${payload}`;
+      this.publish({ reason: "done", taskId: payload });
     } else {
       return;
     }
@@ -349,10 +338,23 @@ export class PostgresStore extends TaskStore {
     if (set) for (const w of set) w();
   }
 
+  /** Hand a notification to every watch() subscriber. A throwing subscriber is
+   * its own problem: it must not cost the others their signal, nor take down the
+   * listener connection that delivered it. */
+  private publish(signal: WatchSignal): void {
+    for (const s of [...this.subscribers]) {
+      try {
+        s(signal);
+      } catch {
+        // Deliberately swallowed — see above.
+      }
+    }
+  }
+
   private dropListener(): void {
-    const client = this.listener;
+    const stop = this.listener;
     this.listener = null;
-    if (client) void client.end().catch(() => {});
+    stop?.();
     // Release everyone promptly; their fallback poll takes over.
     for (const set of [...this.waiters.values()]) for (const w of [...set]) w();
   }
@@ -361,25 +363,26 @@ export class PostgresStore extends TaskStore {
   protected async fetch(name: string, params: Params): Promise<any[]> {
     await this.ensure();
     const { text, values } = toPositional(this.statements[name], params);
-    return (await this.pool!.query(text, values)).rows;
+    return this.executor!.query(text, values);
   }
 
   protected async tx<T>(fn: (fetch: Fetch) => Promise<T>): Promise<T> {
     await this.ensure();
-    const client = await this.pool!.connect();
-    try {
-      await client.query("begin");
-      const out = await fn(async (name, params) => {
-        const { text, values } = toPositional(this.statements[name], params);
-        return (await client.query(text, values)).rows;
-      });
-      await client.query("commit");
-      return out;
-    } catch (e) {
-      await rollbackQuietly(client);
-      throw e;
-    } finally {
-      client.release();
-    }
+    return this.executor!.tx((s) => fn(this.boundFetch(s)));
+  }
+
+  protected async txWithSession<T>(
+    fn: (fetch: Fetch, session: PgSession) => Promise<T>,
+  ): Promise<T> {
+    await this.ensure();
+    return this.executor!.tx((s) => fn(this.boundFetch(s), s));
+  }
+
+  /** A Fetch that runs the protocol's statements on one particular session. */
+  private boundFetch(s: PgSession): Fetch {
+    return async (name, params) => {
+      const { text, values } = toPositional(this.statements[name], params);
+      return s.query(text, values);
+    };
   }
 }

package/src/store/sqlite.ts

@@ -1,7 +1,9 @@
 import { mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 
-import Database from "better-sqlite3";
+import { createRequire } from "node:module";
+
+import type Database from "better-sqlite3";
 
 import { nowMs } from "../ids.js";
 import { loadMigrations, loadStatements } from "../sql.js";
@@ -14,6 +16,25 @@ import {
   TaskStore,
 } from "./base.js";
 
+// `better-sqlite3` is an optional dependency, matching `pg` on the Postgres side:
+// a Postgres-only deployment should not have to build a native module it never
+// loads, and importing this file must not pull one in. Required (not imported)
+// because ensure() is synchronous — the open path applies migrations and cannot
+// await — and createRequire gives a synchronous load from ESM.
+const require = createRequire(import.meta.url);
+let sqliteModule: typeof Database | null = null;
+function loadSqlite(): typeof Database {
+  if (sqliteModule) return sqliteModule;
+  try {
+    sqliteModule = require("better-sqlite3") as typeof Database;
+  } catch {
+    throw new Error(
+      "SQLiteStore requires the 'better-sqlite3' package — install it (e.g. `npm i better-sqlite3`)",
+    );
+  }
+  return sqliteModule;
+}
+
 type DB = Database.Database;
 type Stmt = Database.Statement;
 
@@ -261,7 +282,7 @@ export class SQLiteStore extends TaskStore {
     if (this.db) return this.db;
     const memory = isMemory(this.path);
     if (!memory) mkdirSync(dirname(this.path), { recursive: true });
-    const db = new Database(this.path);
+    const db = new (loadSqlite())(this.path);
     // Only the synchronous part of the open path gets a real busy_timeout: the WAL
     // switch and the migrations cannot await a retry. See the class comment.
     db.pragma(`busy_timeout = ${this.busyBudgetMs}`);

package/src/wait.ts

@@ -1,8 +1,9 @@
 import { TaskTimeout } from "./errors.js";
 import { nowMs } from "./ids.js";
-import { isTerminal, type Task } from "./models.js";
+import { isTerminal, type Task, type TaskRef } from "./models.js";
 import type { TaskStore } from "./store/base.js";
 
+export const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 export const DEFAULT_POLL_MS = 100;
 export const MAX_POLL_MS = 500;
 const GROWTH = 1.5;
@@ -11,7 +12,11 @@ const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve,
 
 export interface PollOptions {
   timeoutMs: number;
+  /** The first poll interval (default 100). */
   pollMs?: number;
+  /** Ceiling the poll interval backs off to (default 500). Worth raising for a
+   * task known to take minutes — fewer reads — or lowering when shaving the
+   * average half-interval of completion-detection latency matters. */
   maxPollMs?: number;
 }
 
@@ -28,15 +33,25 @@ export function nextPollMs(current: number, maxMs: number): number {
 }
 
 /**
- * Poll `read` until it yields a terminal task, or the timeout elapses.
+ * Poll `probe` until it reports a terminal status, then return the full task
+ * via `read`; or throw once the timeout elapses.
+ *
+ * The loop's repeated read is the status-only `probe` (see get_status.sql): a
+ * waiting caller asks nothing but "is it finished yet", and re-reading the whole
+ * row would drag the payload back — and re-parse it — on every beat for the life
+ * of the wait. The full row is read once, when the probe turns terminal or, on
+ * the timeout beat, for the error's snapshot. Between the probe and that read
+ * the row can vanish (purge) or the key repoint (`replace`); a read that comes
+ * back empty or non-terminal is simply not finished, and the loop keeps polling.
  *
  * `wake` is what the loop sleeps on between reads: a store with a push channel
- * (Postgres) cuts it short when the task goes terminal, but the re-read is the
+ * (Postgres) cuts it short when the task goes terminal, but the re-probe is the
  * source of truth either way, so a plain sleep is always a correct answer.
  */
 async function poll(
+  probe: () => Promise<TaskRef | null>,
   read: () => Promise<Task | null>,
-  wake: (task: Task | null, ms: number) => Promise<void>,
+  wake: (ref: TaskRef | null, ms: number) => Promise<void>,
   subject: string,
   key: string | null,
   { timeoutMs, pollMs = DEFAULT_POLL_MS, maxPollMs = MAX_POLL_MS }: PollOptions,
@@ -44,22 +59,27 @@ async function poll(
   const deadline = nowMs() + timeoutMs;
   let interval = pollMs;
   for (;;) {
-    const task = await read();
-    if (task && isTerminal(task)) return task;
+    const ref = await probe();
     const remaining = deadline - nowMs();
-    if (remaining <= 0) throw new TaskTimeout(task?.id ?? subject, { timeoutMs, task, key });
-    await wake(task, Math.min(interval, remaining));
+    // The one full-read site: when the probe says finished, or on the timeout
+    // beat for the error's stuck-in-what-state snapshot. No ref means no row,
+    // so there is nothing for a read to add to either case.
+    const task = ref && (isTerminal(ref) || remaining <= 0) ? await read() : null;
+    if (task && isTerminal(task)) return task;
+    if (remaining <= 0) throw new TaskTimeout(ref?.id ?? subject, { timeoutMs, task, key });
+    await wake(ref, Math.min(interval, remaining));
     interval = nextPollMs(interval, maxPollMs);
   }
 }
 
-/** Poll get() until terminal or timeout. Returns the terminal Task (any status).
- * Throws TaskTimeout, leaving the task running. `pollMs` is the *first* interval;
- * it backs off towards `maxPollMs`. */
+/** Poll the task's status until terminal or timeout. Returns the terminal Task
+ * (any status). Throws TaskTimeout, leaving the task running. `pollMs` is the
+ * *first* interval; it backs off towards `maxPollMs`. */
 export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): Promise<Task> {
   return poll(
+    () => store.getStatus(taskId),
     () => store.get(taskId),
-    (_task, ms) => store.taskDoneWake(taskId, ms),
+    (_ref, ms) => store.taskDoneWake(taskId, ms),
     taskId,
     null,
     opts,
@@ -69,7 +89,7 @@ export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): P
 /**
  * The same wait, following a key instead of an id.
  *
- * The key is re-resolved on every read, because that is what a key means: a
+ * The key is re-resolved on every probe, because that is what a key means: a
  * pointer to the task that is *current* under it. A `replace` landing mid-wait
  * moves the wait onto the new task rather than reporting the cancellation of the
  * old one, and a key that points at nothing yet is simply not finished — it
@@ -81,8 +101,9 @@ export function pollWait(store: TaskStore, taskId: string, opts: PollOptions): P
  */
 export function pollWaitByKey(store: TaskStore, key: string, opts: PollOptions): Promise<Task> {
   return poll(
+    () => store.getStatusByKey(key),
     () => store.getByKey(key),
-    (task, ms) => (task ? store.taskDoneWake(task.id, ms) : sleep(ms)),
+    (ref, ms) => (ref ? store.taskDoneWake(ref.id, ms) : sleep(ms)),
     key,
     key,
     opts,

package/src/worker.ts

@@ -14,6 +14,7 @@ import { newId } from "./ids.js";
 import { type Task } from "./models.js";
 import { SQLiteStore } from "./store/sqlite.js";
 import { PostgresStore } from "./store/postgres.js";
+import type { PgExecutor } from "./store/pg-executor.js";
 import type { TaskStore } from "./store/base.js";
 import { type TaskDef, taskName } from "./task.js";
 
@@ -291,14 +292,15 @@ export class Worker {
     return worker;
   }
 
-  /** Multi-host backend. `dsn` is a libpq connection string; requires the
-   * optional `pg` package. */
+  /** Multi-host backend. `source` is a libpq connection string — which requires
+   * the optional `pg` package — or a PgExecutor over a driver the application
+   * already runs, which cairnq then shares instead of opening a second pool. */
   static postgres(
-    dsn: string,
-    opts: WorkerOptions & { queues?: string[]; max?: number } = {},
+    source: string | PgExecutor,
+    opts: WorkerOptions & { queues?: string[]; max?: number; schema?: string } = {},
   ): Worker {
-    const { queues = ["default"], max, ...rest } = opts;
-    const worker = new Worker(new PostgresStore(dsn, { max }), queues, rest);
+    const { queues = ["default"], max, schema, ...rest } = opts;
+    const worker = new Worker(new PostgresStore(source, { max, schema }), queues, rest);
     worker.ownsStore = true;
     return worker;
   }