@nymbalhq/doc-store-postgres-jsonb 0.0.0-stage → 1.2.0

package/dist/index.d.ts

@@ -0,0 +1,52 @@
+import { DocumentStoreAdapter, Logger, HealthReport, PutOptions, QueryParams, QueryResult, AdapterContext } from '@nymbalhq/types';
+
+interface PostgresJsonbDocumentStoreOptions {
+    /** The command store's database: the table lives beside the kernel's own. */
+    postgresUrl: string;
+    /** Namespaces every row the store writes, so stores sharing a database never see each other's documents. */
+    prefix: string;
+    logger?: Logger;
+    /** How often expired rows are deleted (they are never returned once expired). 0 turns the sweep off. */
+    sweepIntervalMs?: number;
+    now?: () => number;
+}
+/**
+ * A document store on Postgres JSONB: one table, `nymbal_documents`, owned by the store and created by `initialize()`.
+ * It holds derived data the kernel rebuilds at every start, so it is not a kernel migration.
+ */
+declare class PostgresJsonbDocumentStore implements DocumentStoreAdapter {
+    #private;
+    constructor(options: PostgresJsonbDocumentStoreOptions);
+    capabilities(): readonly string[];
+    /** Creates the table and its indexes when absent, under an advisory lock; safe to call again. */
+    initialize(): Promise<void>;
+    /**
+     * One read on a connection of its own, ended afterwards, so a server that cannot be reached leaves no connect
+     * attempt behind in the pool. `degraded` while the table `initialize()` creates is absent.
+     */
+    healthCheck(): Promise<HealthReport>;
+    get<T>(collection: string, key: string): Promise<T | null>;
+    put<T>(collection: string, key: string, document: T, options?: PutOptions): Promise<void>;
+    delete(collection: string, key: string): Promise<void>;
+    query<T>(collection: string, params: QueryParams): Promise<QueryResult<T>>;
+    batchGet<T>(collection: string, keys: string[]): Promise<Map<string, T>>;
+    batchPut<T>(collection: string, items: Map<string, T>): Promise<void>;
+    /**
+     * One transaction: the collection's rows are deleted and the new ones inserted, so a reader (on another connection)
+     * sees the old rows until the commit and the new ones after it. A source that throws rolls it back.
+     */
+    replaceCollection<T>(collection: string, entries: AsyncIterable<[string, T]>): Promise<void>;
+    /** Deletes this prefix's expired rows. Reads never return them in the meantime. */
+    sweep(): Promise<void>;
+    close(): Promise<void>;
+}
+declare function createPostgresJsonbDocumentStore(options: PostgresJsonbDocumentStoreOptions): PostgresJsonbDocumentStore;
+
+/**
+ * The kernel's entry: `infrastructure.documentStore: 'postgres-jsonb'`, on the command store's connection
+ * (`config.postgresUrl`, then `DATABASE_URL`). The kernel calls `initialize()` before it uses the store.
+ */
+declare function createAdapter(ctx: AdapterContext): PostgresJsonbDocumentStore;
+
+export { PostgresJsonbDocumentStore, createAdapter, createPostgresJsonbDocumentStore };
+export type { PostgresJsonbDocumentStoreOptions };

package/dist/index.js

@@ -0,0 +1,295 @@
+// src/index.ts
+import { ConfigError } from "@nymbalhq/types";
+
+// src/postgres-jsonb-document-store.ts
+import pg from "pg";
+import {
+  AdapterError,
+  boundedHealthCheck,
+  connectionSecrets,
+  HEALTH_CHECK_TIMEOUT_MS,
+  queryDocuments
+} from "@nymbalhq/types";
+var TABLE = "nymbal_documents";
+var DDL_LOCK = 1853451618;
+var DDL = [
+  `CREATE TABLE IF NOT EXISTS ${TABLE} (
+    prefix text NOT NULL,
+    collection text NOT NULL,
+    key text NOT NULL,
+    doc jsonb NOT NULL,
+    expires_at timestamptz,
+    PRIMARY KEY (prefix, collection, key)
+  )`,
+  // Narrows a partition query (`doc @> {"field": value}`) without a scan of the collection.
+  `CREATE INDEX IF NOT EXISTS ${TABLE}_doc_idx ON ${TABLE} USING gin (doc jsonb_path_ops)`,
+  `CREATE INDEX IF NOT EXISTS ${TABLE}_expires_idx ON ${TABLE} (expires_at) WHERE expires_at IS NOT NULL`
+];
+var LIVE = "(expires_at IS NULL OR expires_at > $NOW)";
+var BATCH_ROWS = 500;
+function narrowable(value) {
+  return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+var PostgresJsonbDocumentStore = class {
+  #pool;
+  #url;
+  #prefix;
+  #now;
+  #logger;
+  #sweepIntervalMs;
+  #sweepTimer = null;
+  constructor(options) {
+    this.#pool = new pg.Pool({ connectionString: options.postgresUrl, max: 5 });
+    this.#pool.on("error", (err) => options.logger?.warn({ err }, "postgres jsonb pool error"));
+    this.#url = options.postgresUrl;
+    this.#prefix = options.prefix;
+    this.#now = options.now ?? Date.now;
+    this.#logger = options.logger;
+    this.#sweepIntervalMs = options.sweepIntervalMs ?? 6e4;
+  }
+  capabilities() {
+    return ["get", "put", "delete", "query", "batch", "ttl", "conditional-put"];
+  }
+  /** Creates the table and its indexes when absent, under an advisory lock; safe to call again. */
+  async initialize() {
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT pg_advisory_xact_lock($1)", [DDL_LOCK]);
+      for (const statement of DDL) await client.query(statement);
+      await client.query("COMMIT");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+    if (this.#sweepTimer === null && this.#sweepIntervalMs > 0) {
+      this.#sweepTimer = setInterval(() => void this.sweep(), this.#sweepIntervalMs);
+      this.#sweepTimer.unref();
+    }
+  }
+  /**
+   * One read on a connection of its own, ended afterwards, so a server that cannot be reached leaves no connect
+   * attempt behind in the pool. `degraded` while the table `initialize()` creates is absent.
+   */
+  healthCheck() {
+    const client = new pg.Client({
+      connectionString: this.#url,
+      connectionTimeoutMillis: HEALTH_CHECK_TIMEOUT_MS
+    });
+    client.on("error", () => void 0);
+    return boundedHealthCheck(
+      async () => {
+        await client.connect();
+        const { rows } = await client.query(
+          `SELECT to_regclass('${TABLE}')::text AS table`
+        );
+        return rows[0]?.table == null ? { status: "degraded", detail: "not initialized: run nymbal dev or migrate" } : { status: "healthy" };
+      },
+      { redact: connectionSecrets(this.#url) }
+    ).finally(
+      () => (
+        // A probe that never connected has nothing to end; its failure is already the report.
+        client.end().catch(() => void 0)
+      )
+    );
+  }
+  async get(collection, key) {
+    const { rows } = await this.#pool.query(
+      `SELECT doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3 AND ${this.#live(4)}`,
+      [this.#prefix, collection, key, this.#nowDate()]
+    );
+    return rows[0]?.doc ?? null;
+  }
+  async put(collection, key, document, options = {}) {
+    const expiresAt = options.ttl !== void 0 ? new Date(this.#now() + options.ttl * 1e3) : null;
+    const doc = JSON.stringify(document);
+    if (options.conditionKey === void 0) {
+      await this.#pool.query(
+        `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at) VALUES ($1, $2, $3, $4::jsonb, $5)
+         ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = EXCLUDED.expires_at`,
+        [this.#prefix, collection, key, doc, expiresAt]
+      );
+      return;
+    }
+    const conditionKey = options.conditionKey;
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      const { rows } = await client.query(
+        `SELECT doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3 AND ${this.#live(4)}
+         FOR UPDATE`,
+        [this.#prefix, collection, key, this.#nowDate()]
+      );
+      const current = rows[0]?.doc;
+      const holds = current !== void 0 && current[conditionKey] === options.conditionValue;
+      if (!holds) {
+        await client.query("ROLLBACK");
+        throw new AdapterError(
+          "condition-failed",
+          current === void 0 ? `Condition failed on ${collection}/${key}: document does not exist` : `Condition failed on ${collection}/${key}: ${conditionKey} mismatch`,
+          { context: { collection, key, conditionKey } }
+        );
+      }
+      await client.query(
+        `UPDATE ${TABLE} SET doc = $4::jsonb, expires_at = $5 WHERE prefix = $1 AND collection = $2 AND key = $3`,
+        [this.#prefix, collection, key, doc, expiresAt]
+      );
+      await client.query("COMMIT");
+    } catch (error) {
+      if (!(error instanceof AdapterError)) await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  async delete(collection, key) {
+    await this.#pool.query(
+      `DELETE FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3`,
+      [this.#prefix, collection, key]
+    );
+  }
+  async query(collection, params) {
+    const { field, value } = params.partitionKey;
+    const narrow = value !== "*" && narrowable(value);
+    const { rows } = await this.#pool.query(
+      `SELECT key, doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND ${this.#live(3)}` + (narrow ? " AND doc @> $4::jsonb" : ""),
+      [
+        this.#prefix,
+        collection,
+        this.#nowDate(),
+        ...narrow ? [JSON.stringify({ [field]: value })] : []
+      ]
+    );
+    return queryDocuments(
+      rows.map((r) => [r.key, r.doc]),
+      params
+    );
+  }
+  async batchGet(collection, keys) {
+    const result = /* @__PURE__ */ new Map();
+    if (keys.length === 0) return result;
+    const { rows } = await this.#pool.query(
+      `SELECT key, doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = ANY($3::text[]) AND ${this.#live(4)}`,
+      [this.#prefix, collection, keys, this.#nowDate()]
+    );
+    const byKey = new Map(rows.map((r) => [r.key, r.doc]));
+    for (const key of keys) {
+      const doc = byKey.get(key);
+      if (doc !== void 0) result.set(key, doc);
+    }
+    return result;
+  }
+  async batchPut(collection, items) {
+    const entries = [...items];
+    for (let i = 0; i < entries.length; i += BATCH_ROWS) {
+      const chunk = entries.slice(i, i + BATCH_ROWS);
+      await this.#pool.query(
+        `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at)
+         SELECT $1, $2, k, d, NULL FROM unnest($3::text[], $4::jsonb[]) AS t(k, d)
+         ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = NULL`,
+        [
+          this.#prefix,
+          collection,
+          chunk.map(([key]) => key),
+          chunk.map(([, doc]) => JSON.stringify(doc))
+        ]
+      );
+    }
+  }
+  /**
+   * One transaction: the collection's rows are deleted and the new ones inserted, so a reader (on another connection)
+   * sees the old rows until the commit and the new ones after it. A source that throws rolls it back.
+   */
+  async replaceCollection(collection, entries) {
+    const client = await this.#pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(`DELETE FROM ${TABLE} WHERE prefix = $1 AND collection = $2`, [
+        this.#prefix,
+        collection
+      ]);
+      let chunk = /* @__PURE__ */ new Map();
+      const flush = async () => {
+        if (chunk.size === 0) return;
+        await client.query(
+          `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at)
+           SELECT $1, $2, k, d, NULL FROM unnest($3::text[], $4::jsonb[]) AS t(k, d)
+           ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = NULL`,
+          [this.#prefix, collection, [...chunk.keys()], [...chunk.values()]]
+        );
+        chunk = /* @__PURE__ */ new Map();
+      };
+      for await (const [key, doc] of entries) {
+        chunk.set(key, JSON.stringify(doc));
+        if (chunk.size >= BATCH_ROWS) await flush();
+      }
+      await flush();
+      await client.query("COMMIT");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => void 0);
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+  /** Deletes this prefix's expired rows. Reads never return them in the meantime. */
+  async sweep() {
+    try {
+      await this.#pool.query(`DELETE FROM ${TABLE} WHERE prefix = $1 AND expires_at <= $2`, [
+        this.#prefix,
+        this.#nowDate()
+      ]);
+    } catch (err) {
+      this.#logger?.warn({ err }, "postgres jsonb document store: expired rows were not swept");
+    }
+  }
+  async close() {
+    if (this.#sweepTimer !== null) clearInterval(this.#sweepTimer);
+    this.#sweepTimer = null;
+    await this.#pool.end();
+  }
+  /** The not-expired condition, with "now" as parameter `$n`: the store's clock, not the server's. */
+  #live(n) {
+    return LIVE.replace("$NOW", `$${n}`);
+  }
+  #nowDate() {
+    return new Date(this.#now());
+  }
+};
+function createPostgresJsonbDocumentStore(options) {
+  return new PostgresJsonbDocumentStore(options);
+}
+
+// src/index.ts
+function createAdapter(ctx) {
+  if (ctx.slot !== "documentStore") {
+    throw new ConfigError(
+      `@nymbalhq/doc-store-postgres-jsonb serves documentStore, not ${ctx.slot}`,
+      { code: "adapter.wrong_slot", context: { slot: ctx.slot } }
+    );
+  }
+  const configured = ctx.config["postgresUrl"];
+  const postgresUrl = typeof configured === "string" && configured !== "" ? configured : ctx.env["DATABASE_URL"];
+  const prefix = ctx.config["prefix"];
+  if (postgresUrl === void 0 || postgresUrl === "") {
+    throw new ConfigError(
+      "@nymbalhq/doc-store-postgres-jsonb needs the Postgres connection: set DATABASE_URL",
+      { code: "config.postgres_url_missing", context: { slot: ctx.slot } }
+    );
+  }
+  if (typeof prefix !== "string" || prefix === "") {
+    throw new ConfigError("@nymbalhq/doc-store-postgres-jsonb needs a prefix", {
+      code: "config.invalid",
+      context: { slot: ctx.slot }
+    });
+  }
+  return createPostgresJsonbDocumentStore({ postgresUrl, prefix, logger: ctx.logger });
+}
+export {
+  PostgresJsonbDocumentStore,
+  createAdapter,
+  createPostgresJsonbDocumentStore
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/postgres-jsonb-document-store.ts"],"sourcesContent":["import { ConfigError, type AdapterContext } from '@nymbalhq/types'\nimport {\n  createPostgresJsonbDocumentStore,\n  PostgresJsonbDocumentStore,\n  type PostgresJsonbDocumentStoreOptions,\n} from './postgres-jsonb-document-store.js'\n\nexport {\n  createPostgresJsonbDocumentStore,\n  PostgresJsonbDocumentStore,\n  type PostgresJsonbDocumentStoreOptions,\n}\n\n/**\n * The kernel's entry: `infrastructure.documentStore: 'postgres-jsonb'`, on the command store's connection\n * (`config.postgresUrl`, then `DATABASE_URL`). The kernel calls `initialize()` before it uses the store.\n */\nexport function createAdapter(ctx: AdapterContext): PostgresJsonbDocumentStore {\n  if (ctx.slot !== 'documentStore') {\n    throw new ConfigError(\n      `@nymbalhq/doc-store-postgres-jsonb serves documentStore, not ${ctx.slot}`,\n      { code: 'adapter.wrong_slot', context: { slot: ctx.slot } },\n    )\n  }\n  const configured = ctx.config['postgresUrl']\n  const postgresUrl =\n    typeof configured === 'string' && configured !== '' ? configured : ctx.env['DATABASE_URL']\n  const prefix = ctx.config['prefix']\n  if (postgresUrl === undefined || postgresUrl === '') {\n    throw new ConfigError(\n      '@nymbalhq/doc-store-postgres-jsonb needs the Postgres connection: set DATABASE_URL',\n      { code: 'config.postgres_url_missing', context: { slot: ctx.slot } },\n    )\n  }\n  if (typeof prefix !== 'string' || prefix === '') {\n    throw new ConfigError('@nymbalhq/doc-store-postgres-jsonb needs a prefix', {\n      code: 'config.invalid',\n      context: { slot: ctx.slot },\n    })\n  }\n  return createPostgresJsonbDocumentStore({ postgresUrl, prefix, logger: ctx.logger })\n}\n","import pg from 'pg'\nimport {\n  AdapterError,\n  boundedHealthCheck,\n  connectionSecrets,\n  HEALTH_CHECK_TIMEOUT_MS,\n  queryDocuments,\n  type DocumentStoreAdapter,\n  type HealthReport,\n  type Logger,\n  type PutOptions,\n  type QueryParams,\n  type QueryResult,\n} from '@nymbalhq/types'\n\nexport interface PostgresJsonbDocumentStoreOptions {\n  /** The command store's database: the table lives beside the kernel's own. */\n  postgresUrl: string\n  /** Namespaces every row the store writes, so stores sharing a database never see each other's documents. */\n  prefix: string\n  logger?: Logger\n  /** How often expired rows are deleted (they are never returned once expired). 0 turns the sweep off. */\n  sweepIntervalMs?: number\n  now?: () => number\n}\n\nconst TABLE = 'nymbal_documents'\n/** Serialises the table's DDL across replicas that start together: any constant every replica agrees on. */\nconst DDL_LOCK = 0x6e796d62\n\nconst DDL = [\n  `CREATE TABLE IF NOT EXISTS ${TABLE} (\n    prefix text NOT NULL,\n    collection text NOT NULL,\n    key text NOT NULL,\n    doc jsonb NOT NULL,\n    expires_at timestamptz,\n    PRIMARY KEY (prefix, collection, key)\n  )`,\n  // Narrows a partition query (`doc @> {\"field\": value}`) without a scan of the collection.\n  `CREATE INDEX IF NOT EXISTS ${TABLE}_doc_idx ON ${TABLE} USING gin (doc jsonb_path_ops)`,\n  `CREATE INDEX IF NOT EXISTS ${TABLE}_expires_idx ON ${TABLE} (expires_at) WHERE expires_at IS NOT NULL`,\n]\n\nconst LIVE = '(expires_at IS NULL OR expires_at > $NOW)'\nconst BATCH_ROWS = 500\n\n/** A partition value the GIN index can narrow by: the store still filters with `===` afterwards. */\nfunction narrowable(value: unknown): boolean {\n  return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'\n}\n\n/**\n * A document store on Postgres JSONB: one table, `nymbal_documents`, owned by the store and created by `initialize()`.\n * It holds derived data the kernel rebuilds at every start, so it is not a kernel migration.\n */\nexport class PostgresJsonbDocumentStore implements DocumentStoreAdapter {\n  readonly #pool: pg.Pool\n  readonly #url: string\n  readonly #prefix: string\n  readonly #now: () => number\n  readonly #logger: Logger | undefined\n  readonly #sweepIntervalMs: number\n  #sweepTimer: NodeJS.Timeout | null = null\n\n  constructor(options: PostgresJsonbDocumentStoreOptions) {\n    this.#pool = new pg.Pool({ connectionString: options.postgresUrl, max: 5 })\n    this.#pool.on('error', (err) => options.logger?.warn({ err }, 'postgres jsonb pool error'))\n    this.#url = options.postgresUrl\n    this.#prefix = options.prefix\n    this.#now = options.now ?? Date.now\n    this.#logger = options.logger\n    this.#sweepIntervalMs = options.sweepIntervalMs ?? 60_000\n  }\n\n  capabilities(): readonly string[] {\n    return ['get', 'put', 'delete', 'query', 'batch', 'ttl', 'conditional-put']\n  }\n\n  /** Creates the table and its indexes when absent, under an advisory lock; safe to call again. */\n  async initialize(): Promise<void> {\n    const client = await this.#pool.connect()\n    try {\n      await client.query('BEGIN')\n      await client.query('SELECT pg_advisory_xact_lock($1)', [DDL_LOCK])\n      for (const statement of DDL) await client.query(statement)\n      await client.query('COMMIT')\n    } catch (error) {\n      await client.query('ROLLBACK').catch(() => undefined)\n      throw error\n    } finally {\n      client.release()\n    }\n    if (this.#sweepTimer === null && this.#sweepIntervalMs > 0) {\n      this.#sweepTimer = setInterval(() => void this.sweep(), this.#sweepIntervalMs)\n      this.#sweepTimer.unref()\n    }\n  }\n\n  /**\n   * One read on a connection of its own, ended afterwards, so a server that cannot be reached leaves no connect\n   * attempt behind in the pool. `degraded` while the table `initialize()` creates is absent.\n   */\n  healthCheck(): Promise<HealthReport> {\n    const client = new pg.Client({\n      connectionString: this.#url,\n      connectionTimeoutMillis: HEALTH_CHECK_TIMEOUT_MS,\n    })\n    // connect() rejects with the same error, and the report carries it; without a listener pg would throw it.\n    client.on('error', () => undefined)\n    return boundedHealthCheck(\n      async () => {\n        await client.connect()\n        const { rows } = await client.query<{ table: string | null }>(\n          `SELECT to_regclass('${TABLE}')::text AS table`,\n        )\n        return rows[0]?.table == null\n          ? { status: 'degraded', detail: 'not initialized: run nymbal dev or migrate' }\n          : { status: 'healthy' }\n      },\n      { redact: connectionSecrets(this.#url) },\n    ).finally(() =>\n      // A probe that never connected has nothing to end; its failure is already the report.\n      client.end().catch(() => undefined),\n    )\n  }\n\n  async get<T>(collection: string, key: string): Promise<T | null> {\n    const { rows } = await this.#pool.query<{ doc: T }>(\n      `SELECT doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3 AND ${this.#live(4)}`,\n      [this.#prefix, collection, key, this.#nowDate()],\n    )\n    return rows[0]?.doc ?? null\n  }\n\n  async put<T>(\n    collection: string,\n    key: string,\n    document: T,\n    options: PutOptions = {},\n  ): Promise<void> {\n    const expiresAt = options.ttl !== undefined ? new Date(this.#now() + options.ttl * 1000) : null\n    const doc = JSON.stringify(document)\n    if (options.conditionKey === undefined) {\n      await this.#pool.query(\n        `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at) VALUES ($1, $2, $3, $4::jsonb, $5)\n         ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = EXCLUDED.expires_at`,\n        [this.#prefix, collection, key, doc, expiresAt],\n      )\n      return\n    }\n    const conditionKey = options.conditionKey\n    const client = await this.#pool.connect()\n    try {\n      await client.query('BEGIN')\n      const { rows } = await client.query<{ doc: Record<string, unknown> }>(\n        `SELECT doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3 AND ${this.#live(4)}\n         FOR UPDATE`,\n        [this.#prefix, collection, key, this.#nowDate()],\n      )\n      const current = rows[0]?.doc\n      // `===`, as the reference store compares: an object or array never matches.\n      const holds = current !== undefined && current[conditionKey] === options.conditionValue\n      if (!holds) {\n        await client.query('ROLLBACK')\n        throw new AdapterError(\n          'condition-failed',\n          current === undefined\n            ? `Condition failed on ${collection}/${key}: document does not exist`\n            : `Condition failed on ${collection}/${key}: ${conditionKey} mismatch`,\n          { context: { collection, key, conditionKey } },\n        )\n      }\n      await client.query(\n        `UPDATE ${TABLE} SET doc = $4::jsonb, expires_at = $5 WHERE prefix = $1 AND collection = $2 AND key = $3`,\n        [this.#prefix, collection, key, doc, expiresAt],\n      )\n      await client.query('COMMIT')\n    } catch (error) {\n      if (!(error instanceof AdapterError)) await client.query('ROLLBACK').catch(() => undefined)\n      throw error\n    } finally {\n      client.release()\n    }\n  }\n\n  async delete(collection: string, key: string): Promise<void> {\n    await this.#pool.query(\n      `DELETE FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = $3`,\n      [this.#prefix, collection, key],\n    )\n  }\n\n  async query<T>(collection: string, params: QueryParams): Promise<QueryResult<T>> {\n    const { field, value } = params.partitionKey\n    const narrow = value !== '*' && narrowable(value)\n    const { rows } = await this.#pool.query<{ key: string; doc: unknown }>(\n      `SELECT key, doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND ${this.#live(3)}` +\n        (narrow ? ' AND doc @> $4::jsonb' : ''),\n      [\n        this.#prefix,\n        collection,\n        this.#nowDate(),\n        ...(narrow ? [JSON.stringify({ [field]: value })] : []),\n      ],\n    )\n    return queryDocuments<T>(\n      rows.map((r) => [r.key, r.doc] as const),\n      params,\n    )\n  }\n\n  async batchGet<T>(collection: string, keys: string[]): Promise<Map<string, T>> {\n    const result = new Map<string, T>()\n    if (keys.length === 0) return result\n    const { rows } = await this.#pool.query<{ key: string; doc: T }>(\n      `SELECT key, doc FROM ${TABLE} WHERE prefix = $1 AND collection = $2 AND key = ANY($3::text[]) AND ${this.#live(4)}`,\n      [this.#prefix, collection, keys, this.#nowDate()],\n    )\n    const byKey = new Map(rows.map((r) => [r.key, r.doc]))\n    for (const key of keys) {\n      const doc = byKey.get(key)\n      if (doc !== undefined) result.set(key, doc)\n    }\n    return result\n  }\n\n  async batchPut<T>(collection: string, items: Map<string, T>): Promise<void> {\n    const entries = [...items]\n    for (let i = 0; i < entries.length; i += BATCH_ROWS) {\n      const chunk = entries.slice(i, i + BATCH_ROWS)\n      await this.#pool.query(\n        `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at)\n         SELECT $1, $2, k, d, NULL FROM unnest($3::text[], $4::jsonb[]) AS t(k, d)\n         ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = NULL`,\n        [\n          this.#prefix,\n          collection,\n          chunk.map(([key]) => key),\n          chunk.map(([, doc]) => JSON.stringify(doc)),\n        ],\n      )\n    }\n  }\n\n  /**\n   * One transaction: the collection's rows are deleted and the new ones inserted, so a reader (on another connection)\n   * sees the old rows until the commit and the new ones after it. A source that throws rolls it back.\n   */\n  async replaceCollection<T>(\n    collection: string,\n    entries: AsyncIterable<[string, T]>,\n  ): Promise<void> {\n    const client = await this.#pool.connect()\n    try {\n      await client.query('BEGIN')\n      await client.query(`DELETE FROM ${TABLE} WHERE prefix = $1 AND collection = $2`, [\n        this.#prefix,\n        collection,\n      ])\n      let chunk = new Map<string, string>()\n      const flush = async () => {\n        if (chunk.size === 0) return\n        await client.query(\n          `INSERT INTO ${TABLE} (prefix, collection, key, doc, expires_at)\n           SELECT $1, $2, k, d, NULL FROM unnest($3::text[], $4::jsonb[]) AS t(k, d)\n           ON CONFLICT (prefix, collection, key) DO UPDATE SET doc = EXCLUDED.doc, expires_at = NULL`,\n          [this.#prefix, collection, [...chunk.keys()], [...chunk.values()]],\n        )\n        chunk = new Map()\n      }\n      for await (const [key, doc] of entries) {\n        chunk.set(key, JSON.stringify(doc))\n        if (chunk.size >= BATCH_ROWS) await flush()\n      }\n      await flush()\n      await client.query('COMMIT')\n    } catch (error) {\n      await client.query('ROLLBACK').catch(() => undefined)\n      throw error\n    } finally {\n      client.release()\n    }\n  }\n\n  /** Deletes this prefix's expired rows. Reads never return them in the meantime. */\n  async sweep(): Promise<void> {\n    try {\n      await this.#pool.query(`DELETE FROM ${TABLE} WHERE prefix = $1 AND expires_at <= $2`, [\n        this.#prefix,\n        this.#nowDate(),\n      ])\n    } catch (err) {\n      this.#logger?.warn({ err }, 'postgres jsonb document store: expired rows were not swept')\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#sweepTimer !== null) clearInterval(this.#sweepTimer)\n    this.#sweepTimer = null\n    await this.#pool.end()\n  }\n\n  /** The not-expired condition, with \"now\" as parameter `$n`: the store's clock, not the server's. */\n  #live(n: number): string {\n    return LIVE.replace('$NOW', `$${n}`)\n  }\n\n  #nowDate(): Date {\n    return new Date(this.#now())\n  }\n}\n\nexport function createPostgresJsonbDocumentStore(\n  options: PostgresJsonbDocumentStoreOptions,\n): PostgresJsonbDocumentStore {\n  return new PostgresJsonbDocumentStore(options)\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@nymbalhq/doc-store-postgres-jsonb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "description": "The Postgres JSONB document store for Nymbal: `infrastructure.documentStore: 'postgres-jsonb'`",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nymbalhq/nymbal.git",
+    "directory": "packages/doc-store-postgres-jsonb"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nymbalhq/types": "1.2.0"
+  },
+  "peerDependencies": {
+    "pg": "^8.13.1"
+  },
+  "devDependencies": {
+    "@nymbalhq/contract-tests": "1.2.0",
+    "@types/pg": "^8.11.10",
+    "@typescript/native": "npm:typescript@^7.0.2",
+    "fast-check": "^4.10.2",
+    "pg": "^8.13.1",
+    "tsup": "^9.0.0",
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit --rootDir ../.."
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.