@specific.dev/spectest 0.38.0 → 0.41.0

package/src/components/postgres.ts

@@ -0,0 +1,132 @@
+import type { ServiceDefinition, ServiceSetupContext } from "../index.js";
+import { SQL, type SqlClient } from "../sql.js";
+
+export interface PostgresOptions {
+  /** Image tag for the official `postgres` image. Default `"18-alpine"`.
+   *  Ignored when {@link image} is set. */
+  version?: string;
+  /**
+   * Full image reference, overriding the default `postgres:<version>`. For a
+   * Bun-SQL-/wire-compatible image (timescaledb, postgis, pgvector, …) you
+   * still get the instrumented client on `ctx.svc.<name>.client`.
+   */
+  image?: string;
+  /** Database created on first boot. */
+  database: string;
+  /** Superuser name created on first boot. */
+  user: string;
+  /** Superuser password. */
+  password: string;
+  /**
+   * Whether postgres data persists across container restarts via a bind
+   * mount under `.spectest/volumes/<name>/`. Default `true`.
+   * Snapshots/forks always preserve state regardless of this flag — the
+   * volume just means a plain `docker rm`/`docker run` cycle keeps data.
+   */
+  persistent?: boolean;
+  /** TCP port the container listens on. Default `5432`. */
+  port?: number;
+  /**
+   * CMD args appended after the image entrypoint (keeps the entrypoint, unlike
+   * `command`). For extension tuning, e.g.
+   * `["postgres", "-c", "timescaledb.max_background_workers=0"]`.
+   */
+  args?: string[];
+  /** Extra environment variables forwarded to the container. */
+  env?: Record<string, string>;
+  /**
+   * One-shot hook that runs after the ready probe passes, before any
+   * dependent service starts and before any test. This is where schema
+   * and seed data go: the daemon captures the result into the
+   * warm-template snapshot, so it never runs again on a warm start or a
+   * fork.
+   *
+   * The argument is the full test context plus this service's `name` and
+   * its {@link PostgresHelpers}, so the instrumented client is already
+   * built:
+   *
+   * ```ts
+   * db: postgres({
+   *   database: "todos", user: "todos", password: "todos",
+   *   setup: async ({ helpers }) => {
+   *     await helpers.client`CREATE TABLE todos (
+   *       id SERIAL PRIMARY KEY, text TEXT NOT NULL)`;
+   *   },
+   * }),
+   * ```
+   */
+  setup?: (args: ServiceSetupContext<PostgresHelpers>) => void | Promise<void>;
+}
+
+/** Helpers a `postgres(...)` service exposes on `ctx.svc.<name>`. */
+export interface PostgresHelpers {
+  /** An instrumented Bun SQL client — each query lands on the test event log
+   *  alongside http/exec/assertion events, and its rows come back
+   *  inspect-wrapped so `expect(...)` on them links to the query. See
+   *  {@link SQL}. */
+  client: SqlClient;
+}
+
+/**
+ * A ready-to-use Postgres service. Drop into `environment.services`:
+ *
+ * ```ts
+ * services: {
+ *   db: postgres({ database: "todos", user: "todos", password: "todos" }),
+ *   ...
+ * }
+ * ```
+ *
+ * Peer services reach it at `<key>:<port>` (e.g. `db:5432` for the
+ * example above). Tests get a wired-up Bun SQL client at
+ * `ctx.svc.<key>.client` — `await ctx.svc.db.client\`SELECT 1\`` — with
+ * every query recorded on the test event log.
+ *
+ * Point it at a wire-compatible image with `image`/`args`:
+ *
+ * ```ts
+ * db: postgres({
+ *   image: "timescale/timescaledb:latest-pg17",
+ *   args: ["postgres", "-c", "timescaledb.max_background_workers=0"],
+ *   database: "app", user: "app", password: "app",
+ * }),
+ * ```
+ */
+export function postgres(opts: PostgresOptions) {
+  const version = opts.version ?? "18-alpine";
+  const reference = opts.image ?? `postgres:${version}`;
+  const port = opts.port ?? 5432;
+  const persistent = opts.persistent ?? true;
+  // `satisfies` (instead of a return-type annotation) preserves the
+  // literal type — in particular, the `helpers` factory's return shape.
+  // The mapped type in `ServiceHandlesFor<S>` reads that to type
+  // `ctx.svc.<name>` as `{ client: SqlClient }`.
+  return {
+    image: { type: "registry", reference },
+    ...(opts.args ? { args: opts.args } : {}),
+    env: {
+      POSTGRES_DB: opts.database,
+      POSTGRES_USER: opts.user,
+      POSTGRES_PASSWORD: opts.password,
+      // PGDATA lives in a subdir so postgres can initialise inside a bind
+      // mount that may not be empty on first boot.
+      PGDATA: "/var/lib/postgresql/data/pgdata",
+      ...(opts.env ?? {}),
+    },
+    volumes: persistent ? [{ target: "/var/lib/postgresql/data" }] : [],
+    ports: [port],
+    readyCheck: { type: "tcp" as const, port, timeoutSecs: 60 },
+    helpers: ({ name }: { name: string }): PostgresHelpers => {
+      const url =
+        `postgres://${encodeURIComponent(opts.user)}` +
+        `:${encodeURIComponent(opts.password)}` +
+        `@${name}:${port}/${encodeURIComponent(opts.database)}`;
+      return { client: new SQL(url, { label: name }) };
+    },
+    // The user's hook, forwarded verbatim — postgres() declares none of
+    // its own. If it ever gains one, CHAIN the user's after it (the way
+    // `serviceGroup` chains a group hook after the primary part's) rather
+    // than letting either one win.
+    ...(opts.setup ? { setup: opts.setup } : {}),
+  } satisfies ServiceDefinition<PostgresHelpers>;
+}