@fuguejs/pg 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @fuguejs/pg
+
+PostgreSQL capability adapter for Fugue workflows.
+
+## Installation
+
+```bash
+bun add @fuguejs/pg pg zod
+```
+
+`pg` and `zod` are peer dependencies — `pg` provides the connection pool,
+`zod` the schemas every `query`/`queryOne` call validates against.
+
+## Usage
+
+### Register with the host
+
+```ts
+import { createPgAdapter } from "@fuguejs/pg";
+
+const pgHandle = createPgAdapter({
+  connectionString: process.env.DATABASE_URL!,
+  poolSize: 20,
+  statementTimeoutMs: 15_000,
+});
+
+// Pass to SharedInfra capabilities:
+const sharedInfra = {
+  // ... other infra ...
+  capabilities: [pgHandle],
+};
+```
+
+### Use in a node
+
+```ts
+import { createFetchNode } from "@fuguejs/framework";
+import { z } from "zod";
+
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+const fetchUser = createFetchNode({
+  id: "fetch-user",
+  inputSchema: z.object({ userId: z.string() }),
+  outputSchema: UserSchema,
+  requires: ["db"] as const,
+  fetch: async (input, ctx) => {
+    // ctx.db is typed as PgCapability — non-null, schema-validated
+    return ctx.db.queryOne(
+      UserSchema,
+      "SELECT id, name, email FROM users WHERE id = $1",
+      [input.userId],
+    );
+  },
+});
+```
+
+### Testing with the fake
+
+```ts
+import { createFakePgCapability } from "@fuguejs/pg";
+
+const fakeDb = createFakePgCapability({
+  "SELECT * FROM users WHERE id": [
+    { id: "1", name: "Alice", email: "alice@example.com" },
+  ],
+  "INSERT INTO orders": { rowCount: 1 },
+});
+
+// Use in tests via makeNodeContext:
+const ctx = makeNodeContext({
+  runId: "test-run",
+  dagId: "test-dag",
+  capabilities: { db: fakeDb.client },
+});
+```
+
+## API
+
+### `PgCapability`
+
+| Method | Description |
+|--------|-------------|
+| `query<T>(schema, sql, params?)` | Execute query, validate all rows against Zod schema |
+| `queryOne<T>(schema, sql, params?)` | Execute query, validate first row (or null) |
+| `execute(sql, params?)` | Execute write, return `{ rowCount }` |
+| `queryRaw(sql, params?)` | Escape hatch: raw `unknown[]` rows, no validation — prefer `query` with a schema |
+
+All methods return `Result<T, FrameworkError>` — no exceptions escape.
+
+### `createPgAdapter(config)`
+
+Creates a `CapabilityHandle<"db">` with lifecycle management:
+- `connect()`: validates connectivity with SELECT 1
+- `close()`: drains the connection pool
+- `healthCheck()`: SELECT 1, racing a 5s timeout (a hung pool reports unhealthy)
+
+Config options: `poolSize` (default 10), `statementTimeoutMs` (default 30000, applied as the pool's `statement_timeout`), `connectionTimeoutMs` (default 5000), `idleTimeoutMs` (default 10000).
+
+### `createFakePgCapability(routes)`
+
+In-memory fake for testing. Routes are matched by exact SQL or longest prefix match.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@fuguejs/pg",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@fuguejs/framework": "0.1.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": false
+    },
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/pg": "^8.0.0",
+    "@types/bun": "latest",
+    "pg": "^8.13.0",
+    "zod": "^4.3.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/__tests__"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,408 @@
+/**
+ * @fuguejs/pg — PostgreSQL capability adapter for Fugue.
+ *
+ * Provides a typed `PgCapability` interface that nodes access via
+ * `requires: ["db"]` and `ctx.db`. Wraps the `pg` Pool with:
+ *
+ * - Zod schema validation of query results
+ * - Result-based error handling (no exceptions escape)
+ * - Connection pool lifecycle management via CapabilityHandle
+ * - Health check (SELECT 1) for degraded-state detection
+ *
+ * ## Usage
+ *
+ * ```ts
+ * import { createPgAdapter } from "@fuguejs/pg";
+ *
+ * const pgHandle = createPgAdapter({
+ *   connectionString: process.env.DATABASE_URL,
+ *   poolSize: 10,
+ * });
+ *
+ * // Register with the host:
+ * const sharedInfra = { ..., capabilities: [pgHandle] };
+ *
+ * // In a node:
+ * createFetchNode({
+ *   id: "fetch-users",
+ *   requires: ["db"] as const,
+ *   fetch: async (input, ctx) => {
+ *     return ctx.db.query(UserSchema, "SELECT * FROM users WHERE active = $1", [true]);
+ *   },
+ * });
+ * ```
+ *
+ * ## Module Augmentation
+ *
+ * This package augments `@fuguejs/framework`'s `CapabilityRegistry` to add the
+ * `"db"` capability. After importing this package, `requires: ["db"]` becomes
+ * valid and `ctx.db` is typed as `PgCapability`.
+ *
+ * @satisfies ADR-0051 — Extensible capability registry
+ */
+
+import { createRequire } from "node:module";
+import type { z } from "zod";
+import type { Result, FrameworkError, CapabilityHandle } from "@fuguejs/framework";
+import { ok, err, nodeId } from "@fuguejs/framework";
+import type { Pool as PgPool, PoolConfig } from "pg";
+
+// ---------------------------------------------------------------------------
+// Capability Interface
+// ---------------------------------------------------------------------------
+
+/** Sentinel node ID for pg capability errors */
+const PG_NODE_ID = nodeId("pg-capability");
+
+/**
+ * PostgreSQL capability interface — what nodes see on `ctx.db`.
+ *
+ * All methods return `Result` — no exceptions escape. Query results are
+ * validated against the provided Zod schema.
+ */
+export interface PgCapability {
+  /**
+   * Execute a query and validate all rows against the schema.
+   * Returns an empty array if no rows match.
+   */
+  query<T>(schema: z.ZodType<T>, sql: string, params?: unknown[]): Promise<Result<T[], FrameworkError>>;
+
+  /**
+   * Execute a query expecting at most one row. Returns `null` if no rows match.
+   * Validates the row against the schema if present.
+   */
+  queryOne<T>(schema: z.ZodType<T>, sql: string, params?: unknown[]): Promise<Result<T | null, FrameworkError>>;
+
+  /**
+   * Execute a write statement (INSERT, UPDATE, DELETE).
+   * Returns the number of affected rows.
+   */
+  execute(sql: string, params?: unknown[]): Promise<Result<{ rowCount: number }, FrameworkError>>;
+
+  /**
+   * Escape hatch: execute a query and return raw rows as `unknown[]` with NO
+   * schema validation. This bypasses parse-don't-validate — every row must be
+   * narrowed manually before use. Reach for `query` with a Zod schema first;
+   * use this only for genuinely dynamic schemas (e.g. `information_schema`
+   * introspection) or pass-through tooling.
+   */
+  queryRaw(sql: string, params?: unknown[]): Promise<Result<unknown[], FrameworkError>>;
+}
+
+// ---------------------------------------------------------------------------
+// Module Augmentation
+// ---------------------------------------------------------------------------
+
+declare module "@fuguejs/framework" {
+  interface CapabilityRegistry {
+    /** PostgreSQL database capability. Access via `ctx.db` in nodes. */
+    db: PgCapability;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration for the PostgreSQL adapter.
+ */
+export interface PgAdapterConfig {
+  /** PostgreSQL connection string (e.g., "postgresql://user:pass@host:5432/db") */
+  readonly connectionString: string;
+  /** Maximum number of connections in the pool. Default: 10. */
+  readonly poolSize?: number;
+  /** Statement timeout in milliseconds. Default: 30000 (30s). */
+  readonly statementTimeoutMs?: number;
+  /** Connection timeout in milliseconds. Default: 5000 (5s). */
+  readonly connectionTimeoutMs?: number;
+  /** Idle timeout in milliseconds before a connection is closed. Default: 10000 (10s). */
+  readonly idleTimeoutMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a `pg` error to a `FrameworkError`. Connection-class SQLSTATEs
+ * (08xxx), insufficient-resources (53xxx), and admin shutdown (57P01) are
+ * `transient` (retriable); everything else (syntax, constraint, etc.) is a
+ * non-retriable `node-crash`. Exported for testing — this classification
+ * drives retry behavior.
+ */
+export const mapPgError = (error: unknown, sql: string): FrameworkError => {
+  const message = error instanceof Error ? error.message : String(error);
+  // Determine if the error is transient (connection issues) or permanent (syntax, constraint).
+  // Guard the SQLSTATE on its runtime type — a non-string `code` (a driver that
+  // sets it numeric, or an unrelated object carrying a `code` field) must not
+  // make `.startsWith` throw out of this function and escape the client's catch.
+  if (error instanceof Error && "code" in error) {
+    const pgCode = (error as { code?: unknown }).code;
+    // Connection-class errors (08xxx) and insufficient resources (53xxx) are transient
+    if (
+      typeof pgCode === "string" &&
+      (pgCode.startsWith("08") || pgCode.startsWith("53") || pgCode === "57P01")
+    ) {
+      return { kind: "transient", nodeId: PG_NODE_ID, message: `PG transient: ${message} (${pgCode})` };
+    }
+  }
+  return {
+    kind: "node-crash",
+    nodeId: PG_NODE_ID,
+    message: `PG error: ${message} [sql: ${sql.slice(0, 100)}]`,
+    retriability: "non-retriable",
+  };
+};
+
+/**
+ * The slice of `pg.Pool` the capability client actually uses. Tests inject a
+ * fake; production passes the real pool (structurally compatible).
+ */
+export interface PgQueryable {
+  query(sql: string, params?: unknown[]): Promise<{ rows: unknown[]; rowCount: number | null }>;
+}
+
+/**
+ * Build a `PgCapability` over an injected pool. Exported for testing —
+ * `createPgAdapter` is the production entry point that owns pool
+ * construction and lifecycle.
+ */
+export const createPgClient = (pool: PgQueryable): PgCapability => ({
+  query: async <T,>(schema: z.ZodType<T>, sql: string, params?: unknown[]): Promise<Result<T[], FrameworkError>> => {
+    try {
+      const result = await pool.query(sql, params);
+      const validated: T[] = [];
+      for (const row of result.rows) {
+        const parsed = schema.safeParse(row);
+        if (!parsed.success) {
+          return err({
+            kind: "node-crash",
+            nodeId: PG_NODE_ID,
+            message: `Row validation failed: ${parsed.error.message}`,
+            retriability: "non-retriable",
+          });
+        }
+        validated.push(parsed.data);
+      }
+      return ok(validated);
+    } catch (error) {
+      return err(mapPgError(error, sql));
+    }
+  },
+
+  queryOne: async <T,>(schema: z.ZodType<T>, sql: string, params?: unknown[]): Promise<Result<T | null, FrameworkError>> => {
+    try {
+      const result = await pool.query(sql, params);
+      if (result.rows.length === 0) return ok(null);
+      const parsed = schema.safeParse(result.rows[0]);
+      if (!parsed.success) {
+        return err({
+          kind: "node-crash",
+          nodeId: PG_NODE_ID,
+          message: `Row validation failed: ${parsed.error.message}`,
+          retriability: "non-retriable",
+        });
+      }
+      return ok(parsed.data);
+    } catch (error) {
+      return err(mapPgError(error, sql));
+    }
+  },
+
+  execute: async (sql: string, params?: unknown[]): Promise<Result<{ rowCount: number }, FrameworkError>> => {
+    try {
+      const result = await pool.query(sql, params);
+      return ok({ rowCount: result.rowCount ?? 0 });
+    } catch (error) {
+      return err(mapPgError(error, sql));
+    }
+  },
+
+  queryRaw: async (sql: string, params?: unknown[]): Promise<Result<unknown[], FrameworkError>> => {
+    try {
+      const result = await pool.query(sql, params);
+      return ok(result.rows);
+    } catch (error) {
+      return err(mapPgError(error, sql));
+    }
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Adapter Factory
+// ---------------------------------------------------------------------------
+
+/** Health checks are bounded by this timeout so a hung pool reports unhealthy. */
+const HEALTH_CHECK_TIMEOUT_MS = 5_000;
+
+/**
+ * Create a PostgreSQL capability handle.
+ *
+ * The handle manages the connection pool lifecycle:
+ * - `connect()`: validates connectivity with a SELECT 1 query
+ * - `close()`: drains the pool
+ * - `healthCheck()`: runs SELECT 1, racing a 5s timeout
+ *
+ * @example
+ * ```ts
+ * const pg = createPgAdapter({
+ *   connectionString: process.env.DATABASE_URL!,
+ *   poolSize: 20,
+ *   statementTimeoutMs: 15_000,
+ * });
+ *
+ * // Register with host
+ * const sharedInfra = { ..., capabilities: [pg] };
+ * ```
+ */
+export const createPgAdapter = (config: PgAdapterConfig): CapabilityHandle<"db"> => {
+  // Lazy pool creation — constructed at handle creation, connected at boot.
+  // `createRequire` keeps the lazy-CJS load working under both Bun and plain
+  // Node ESM (a bare `require` is undefined in Node ESM module scope).
+  const requireModule = createRequire(import.meta.url);
+  const { Pool } = requireModule("pg") as typeof import("pg");
+
+  const poolConfig: PoolConfig = {
+    connectionString: config.connectionString,
+    max: config.poolSize ?? 10,
+    connectionTimeoutMillis: config.connectionTimeoutMs ?? 5_000,
+    idleTimeoutMillis: config.idleTimeoutMs ?? 10_000,
+    statement_timeout: config.statementTimeoutMs ?? 30_000,
+  };
+
+  const pool = new Pool(poolConfig);
+
+  return {
+    name: "db",
+    client: createPgClient(pool),
+
+    connect: async () => {
+      // Validate connectivity
+      const client = await pool.connect();
+      try {
+        await client.query("SELECT 1");
+      } finally {
+        client.release();
+      }
+    },
+
+    close: async () => {
+      await pool.end();
+    },
+
+    healthCheck: () => healthCheckWithTimeout(pool, HEALTH_CHECK_TIMEOUT_MS),
+  };
+};
+
+/**
+ * Race SELECT 1 against a timeout. A pool that hangs (e.g. exhausted
+ * connections, dead network) reports unhealthy instead of stalling the
+ * caller. Exported for testing.
+ */
+export const healthCheckWithTimeout = async (
+  pool: PgQueryable,
+  timeoutMs: number,
+): Promise<Result<void, string>> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      pool.query("SELECT 1"),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`health check timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        );
+      }),
+    ]);
+    return ok(undefined);
+  } catch (e) {
+    return err(e instanceof Error ? e.message : String(e));
+  } finally {
+    if (timer != null) clearTimeout(timer);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Fake for Testing
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory fake PgCapability for unit testing nodes that use `ctx.db`.
+ *
+ * Accepts a response map that returns canned results for SQL patterns.
+ *
+ * @example
+ * ```ts
+ * const fakeDb = createFakePgCapability({
+ *   "SELECT * FROM users": [{ id: "1", name: "Alice" }],
+ *   "INSERT INTO orders": { rowCount: 1 },
+ * });
+ * ```
+ */
+export interface FakePgRoute {
+  readonly rows?: unknown[];
+  readonly rowCount?: number;
+}
+
+export const createFakePgCapability = (
+  routes: Readonly<Record<string, unknown[] | FakePgRoute>>,
+): CapabilityHandle<"db"> => {
+  const matchRoute = (sql: string): FakePgRoute | null => {
+    // Try exact match first, then longest prefix match
+    const direct = routes[sql];
+    if (direct) {
+      return Array.isArray(direct) ? { rows: direct } : direct;
+    }
+    // Find the longest prefix match
+    let bestMatch: FakePgRoute | null = null;
+    let bestLength = 0;
+    for (const [pattern, value] of Object.entries(routes)) {
+      if (sql.startsWith(pattern) && pattern.length > bestLength) {
+        bestMatch = Array.isArray(value) ? { rows: value } : value;
+        bestLength = pattern.length;
+      }
+    }
+    return bestMatch;
+  };
+
+  const client: PgCapability = {
+    query: async <T,>(schema: z.ZodType<T>, sql: string, _params?: unknown[]): Promise<Result<T[], FrameworkError>> => {
+      const route = matchRoute(sql);
+      if (!route || !route.rows) {
+        return ok([] as T[]);
+      }
+      const validated: T[] = [];
+      for (const row of route.rows) {
+        const parsed = schema.safeParse(row);
+        if (!parsed.success) {
+          return err({ kind: "node-crash", nodeId: PG_NODE_ID, message: `Fake row validation: ${parsed.error.message}`, retriability: "non-retriable" });
+        }
+        validated.push(parsed.data);
+      }
+      return ok(validated);
+    },
+
+    queryOne: async <T,>(schema: z.ZodType<T>, sql: string, _params?: unknown[]): Promise<Result<T | null, FrameworkError>> => {
+      const route = matchRoute(sql);
+      if (!route || !route.rows || route.rows.length === 0) return ok(null);
+      const parsed = schema.safeParse(route.rows[0]);
+      if (!parsed.success) {
+        return err({ kind: "node-crash", nodeId: PG_NODE_ID, message: `Fake row validation: ${parsed.error.message}`, retriability: "non-retriable" });
+      }
+      return ok(parsed.data);
+    },
+
+    execute: async (sql: string, _params?: unknown[]): Promise<Result<{ rowCount: number }, FrameworkError>> => {
+      const route = matchRoute(sql);
+      return ok({ rowCount: route?.rowCount ?? 0 });
+    },
+
+    queryRaw: async (sql: string, _params?: unknown[]): Promise<Result<unknown[], FrameworkError>> => {
+      const route = matchRoute(sql);
+      return ok(route?.rows ?? []);
+    },
+  };
+
+  return { name: "db", client };
+};