@usagekit/store-postgres 0.0.0-stage → 0.7.0

package/dist/operations.js

@@ -0,0 +1,73 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { InvalidInput } from "@usagekit/store";
+import { canonical } from "./codec.js";
+import { hydrate } from "./records.js";
+import { SQL } from "./sql.js";
+export function operationsReader(clock, secret) {
+    const sign = (body) => createHmac("sha256", secret).update(`operations:${body}`).digest("base64url");
+    const open = (cursor, identity) => {
+        try {
+            const parts = cursor.split(".");
+            if (parts.length !== 2)
+                throw new Error();
+            const [body, signature] = parts, actual = Buffer.from(signature), expected = Buffer.from(sign(body));
+            if (actual.length !== expected.length || !timingSafeEqual(actual, expected))
+                throw new Error();
+            const snapshot = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+            if (snapshot.query !== identity || snapshot.expiresAt <= clock.now().getTime())
+                throw new Error();
+            return snapshot;
+        }
+        catch {
+            throw new InvalidInput("cursor", "unknown cursor or query mismatch");
+        }
+    };
+    return async (sql, q) => {
+        const { cursor, ...query } = q, identity = canonical(query);
+        const [watermark] = cursor
+            ? []
+            : await sql.query(SQL.sql `SELECT COALESCE(MAX(event_id),0) AS n FROM metering_event`);
+        const snapshot = cursor
+            ? open(cursor, identity)
+            : {
+                query: identity,
+                watermark: String(watermark?.n ?? 0n),
+                offset: 0,
+                asOf: clock.now().toISOString(),
+                expiresAt: clock.now().getTime() + 300000,
+            };
+        const previousState = SQL.sql `(SELECT e.state FROM metering_event e WHERE e.operation_pk=o.operation_pk AND e.event_id<=${BigInt(snapshot.watermark)} ORDER BY e.event_id DESC LIMIT 1)`;
+        const clauses = [
+            SQL.sql `o.namespace=${q.scope.namespace}`,
+            SQL.sql `o.created_at>=${new Date(q.from)}`,
+            SQL.sql `o.created_at<${new Date(q.to)}`,
+            SQL.sql `${previousState} IS NOT NULL`,
+        ];
+        if (q.states)
+            clauses.push(q.states.length ? SQL.sql `${previousState} IN (${SQL.join(q.states)})` : SQL.sql `FALSE`);
+        if (q.scope.kind === "principal")
+            clauses.push(SQL.sql `o.principal=${q.scope.principal}`);
+        if (q.scope.kind === "group")
+            clauses.push(SQL.sql `o.input->'scope'->>'group'=${q.scope.group}`);
+        if (q.scope.kind === "platform_pool")
+            clauses.push(SQL.sql `o.input->'platformPools' @> ${JSON.stringify([q.scope.poolId])}::jsonb`);
+        if (q.connection)
+            clauses.push(SQL.sql `o.input->'scope'->>'connection'=${q.connection}`);
+        const limit = q.limit ?? 1000;
+        const rows = await sql.query(SQL.sql `SELECT o.* FROM metering_operation o WHERE ${SQL.join(clauses, " AND ")} ORDER BY o.created_at,o.operation_id LIMIT ${limit + 1} OFFSET ${snapshot.offset}`);
+        // The 0.4 contract freezes membership/order at the watermark and returns current records.
+        const operations = [];
+        for (const row of rows.slice(0, limit))
+            operations.push(await hydrate(sql, row));
+        const page = {
+            operations,
+            asOf: snapshot.asOf,
+            watermark: snapshot.watermark,
+        };
+        if (rows.length > limit) {
+            const body = Buffer.from(JSON.stringify({ ...snapshot, offset: snapshot.offset + limit })).toString("base64url");
+            page.nextCursor = `${body}.${sign(body)}`;
+        }
+        return page;
+    };
+}

package/dist/reads.d.ts

@@ -0,0 +1,4 @@
+import type { UsagePage, UsageQuery } from "@usagekit/core";
+import type { Clock } from "@usagekit/store";
+import { type Sql } from "./sql.js";
+export declare function usageReader(clock: Clock, secret: string): (sql: Sql, q: UsageQuery) => Promise<UsagePage>;

package/dist/reads.js

@@ -0,0 +1,119 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { InvalidInput } from "@usagekit/store";
+import { aggregate as groupUsage } from "@usagekit/store/reference";
+import { canonical, decode } from "./codec.js";
+import { newState } from "./command-state.js";
+import { SQL } from "./sql.js";
+export function usageReader(clock, secret) {
+    const sign = (body) => createHmac("sha256", secret).update(body).digest("base64url");
+    return async (sql, q) => {
+        const { cursor, ...query } = q, identity = canonical(query);
+        let snapshot;
+        if (cursor) {
+            try {
+                const parts = cursor.split(".");
+                if (parts.length !== 2)
+                    throw new Error();
+                const [body, signature] = parts, a = Buffer.from(signature), b = Buffer.from(sign(body));
+                if (a.length !== b.length || !timingSafeEqual(a, b))
+                    throw new Error();
+                snapshot = JSON.parse(Buffer.from(body, "base64url").toString("utf8"));
+                if (snapshot.query !== identity || snapshot.expiresAt <= clock.now().getTime())
+                    throw new Error();
+            }
+            catch {
+                throw new InvalidInput("cursor", "unknown cursor or query mismatch");
+            }
+        }
+        else {
+            const [row] = await sql.query(SQL.sql `SELECT COALESCE(MAX(event_id),0) AS n FROM metering_event`);
+            snapshot = {
+                query: identity,
+                watermark: String(row?.n ?? 0n),
+                offset: 0,
+                asOf: clock.now().toISOString(),
+                expiresAt: clock.now().getTime() + 300000,
+            };
+        }
+        const clauses = [
+            SQL.sql `e.namespace=${q.scope.namespace}`,
+            SQL.sql `e.occurred_at>=${new Date(q.from)}`,
+            SQL.sql `e.occurred_at<${new Date(q.to)}`,
+            SQL.sql `e.state IN ('pending','settled')`,
+            SQL.sql `e.event_id=(SELECT MAX(n.event_id) FROM metering_event n WHERE n.operation_pk=e.operation_pk AND n.event_id<=${BigInt(snapshot.watermark)})`,
+        ];
+        if (q.scope.kind === "principal")
+            clauses.push(SQL.sql `o.principal=${q.scope.principal}`);
+        if (q.scope.kind === "group")
+            clauses.push(SQL.sql `o.input->'scope'->>'group'=${q.scope.group}`);
+        if (q.scope.kind === "platform_pool")
+            clauses.push(SQL.sql `o.input->'platformPools' @> ${JSON.stringify([q.scope.poolId])}::jsonb`);
+        if (q.connection)
+            clauses.push(SQL.sql `o.input->'scope'->>'connection'=${q.connection}`);
+        const records = await sql.query(SQL.sql `SELECT o.operation_pk,o.input,e.state,r.body,r.cost_units,r.cost_certainty,m.unit,m.value,m.scale,m.certainty
+      FROM metering_event e JOIN metering_operation o USING(operation_pk)
+      JOIN metering_receipt r ON r.receipt_pk=e.receipt_pk LEFT JOIN metering_measurement m ON m.receipt_pk=r.receipt_pk
+      WHERE ${SQL.join(clauses, " AND ")} ORDER BY e.event_id,m.unit`);
+        const state = newState(clock);
+        for (const row of records) {
+            let op = state.operations.get(row.operation_pk);
+            if (!op) {
+                const receipt = decode(row.body);
+                receipt.measurements = [];
+                if (row.cost_certainty !== "unknown" && row.cost_units === null)
+                    throw new Error("Missing stored cost");
+                receipt.cost =
+                    row.cost_certainty === "unknown"
+                        ? { certainty: "unknown", money: null }
+                        : {
+                            certainty: row.cost_certainty,
+                            money: { currency: "USD", units: BigInt(row.cost_units ?? 0n) },
+                        };
+                op = {
+                    ...decode(row.input),
+                    state: row.state,
+                    version: 0,
+                    createdAt: "",
+                    updatedAt: "",
+                    reservationExpiresAt: "",
+                    budgetEpochs: [],
+                    lease: null,
+                    receipts: [receipt],
+                };
+                state.operations.set(row.operation_pk, op);
+            }
+            if (row.unit !== null) {
+                const receipt = op.receipts[0];
+                if (!receipt)
+                    throw new Error("Missing stored receipt");
+                if (row.certainty !== "unknown" && (row.value === null || row.scale === null))
+                    throw new Error("Missing stored quantity");
+                receipt.measurements = [
+                    ...receipt.measurements,
+                    row.certainty === "unknown"
+                        ? { unit: row.unit, certainty: "unknown", quantity: null }
+                        : {
+                            unit: row.unit,
+                            certainty: row.certainty,
+                            quantity: {
+                                unit: row.unit,
+                                value: BigInt(row.value?.toString() ?? "0"),
+                                scale: row.scale ?? 0,
+                            },
+                        },
+                ];
+            }
+        }
+        const all = groupUsage(state, { ...query, limit: Number.MAX_SAFE_INTEGER }).rows, end = snapshot.offset + (q.limit ?? 1000);
+        const page = {
+            rows: all.slice(snapshot.offset, end),
+            watermark: snapshot.watermark,
+            asOf: snapshot.asOf,
+        };
+        if (end < all.length) {
+            const body = Buffer.from(JSON.stringify({ ...snapshot, offset: end })).toString("base64url");
+            page.nextCursor = `${body}.${sign(body)}`;
+        }
+        return page;
+    };
+}

package/dist/records.d.ts

@@ -0,0 +1,32 @@
+import type { AllowanceExceeded, BudgetAlertCrossed, Operation, OperationRef, Receipt } from "@usagekit/core";
+import { type Sql } from "./sql.js";
+export type OperationRow = {
+    operation_pk: string;
+    namespace: string;
+    principal: string;
+    operation_id: string;
+    input: unknown;
+    state: Operation["state"];
+    version: number;
+    budget_epochs: unknown;
+    reservation_expires_at: Date;
+    lease_id: string | null;
+    lease_holder: string | null;
+    lease_expires_at: Date | null;
+    lease_kind: "lease" | "recovery" | null;
+    created_at: Date;
+    updated_at: Date;
+    semantic_hash: string;
+    warnings: unknown;
+    alerts: unknown;
+};
+export declare function operationRow(sql: Sql, namespace: string, id: string): Promise<OperationRow | null>;
+export declare function hydrate(sql: Sql, row: OperationRow): Promise<Operation>;
+export declare function find(sql: Sql, ref: OperationRef): Promise<{
+    row: OperationRow;
+    op: Operation;
+} | null>;
+export declare function insert(sql: Sql, op: Operation, warnings: readonly AllowanceExceeded[], alerts: readonly BudgetAlertCrossed[]): Promise<void>;
+export declare function update(sql: Sql, before: Operation, op: Operation, leaseKind: string | null): Promise<boolean>;
+export declare function appendReceipt(sql: Sql, op: Operation, receipt: Receipt, sequence: number): Promise<void>;
+export declare function event(sql: Sql, op: Operation): Promise<void>;

package/dist/records.js

@@ -0,0 +1,68 @@
+import { decode, effective, encode, hash, identity, key, timestamp } from "./codec.js";
+import { lock, SQL } from "./sql.js";
+export async function operationRow(sql, namespace, id) {
+    const [row] = await sql.query(SQL.sql `SELECT * FROM metering_operation WHERE namespace=${namespace} AND operation_id=${id}`);
+    return row ?? null;
+}
+export async function hydrate(sql, row) {
+    const receipts = await sql.query(SQL.sql `SELECT body FROM metering_receipt WHERE operation_pk=${row.operation_pk} ORDER BY sequence`);
+    let lease = null;
+    if (row.lease_id) {
+        if (!row.lease_holder || !row.lease_expires_at)
+            throw new Error("Incomplete stored lease");
+        lease = {
+            leaseId: row.lease_id,
+            holder: row.lease_holder,
+            expiresAt: timestamp(row.lease_expires_at),
+        };
+    }
+    return {
+        ...decode(row.input),
+        state: row.state,
+        version: row.version,
+        reservationExpiresAt: timestamp(row.reservation_expires_at),
+        budgetEpochs: decode(row.budget_epochs),
+        createdAt: timestamp(row.created_at),
+        updatedAt: timestamp(row.updated_at),
+        receipts: receipts.map((r) => decode(r.body)),
+        lease,
+    };
+}
+export async function find(sql, ref) {
+    const row = await operationRow(sql, ref.namespace, ref.operationId);
+    return row && row.principal === ref.principal ? { row, op: await hydrate(sql, row) } : null;
+}
+export async function insert(sql, op, warnings, alerts) {
+    const { state: _, version: __, receipts: ___, lease: ____, createdAt: _____, updatedAt: ______, budgetEpochs: _______, reservationExpiresAt: ________, ...input } = op;
+    await sql.execute(SQL.sql `INSERT INTO metering_operation
+    (operation_pk, namespace, principal, operation_id, state, version, semantic_hash, budget_epochs,
+     reservation_expires_at, created_at, updated_at, input, warnings, alerts)
+    VALUES (${key(op.scope.namespace, op.operationId)},${op.scope.namespace},${op.scope.principal},${op.operationId},
+      ${op.state},${op.version},${hash(identity(input))},${encode(op.budgetEpochs)}::jsonb,
+      ${new Date(op.reservationExpiresAt)},${new Date(op.createdAt)},${new Date(op.updatedAt)},${encode(input)}::jsonb,${encode(warnings)}::jsonb,${encode(alerts)}::jsonb)`);
+}
+export async function update(sql, before, op, leaseKind) {
+    const count = await sql.execute(SQL.sql `UPDATE metering_operation SET state=${op.state},version=${op.version},
+    lease_id=${op.lease?.leaseId ?? null},lease_holder=${op.lease?.holder ?? null},
+    lease_expires_at=${op.lease ? new Date(op.lease.expiresAt) : null},lease_kind=${leaseKind},updated_at=${new Date(op.updatedAt)}
+    WHERE operation_pk=${key(op.scope.namespace, op.operationId)} AND version=${before.version}`);
+    return count === 1;
+}
+export async function appendReceipt(sql, op, receipt, sequence) {
+    const pk = key(op.scope.namespace, op.operationId), rpk = key(pk, receipt.id);
+    await sql.execute(SQL.sql `INSERT INTO metering_receipt
+    (receipt_pk,operation_pk,receipt_id,supersedes,body,occurred_at,recorded_at,cost_units,cost_certainty,sequence)
+    VALUES(${rpk},${pk},${receipt.id},${receipt.supersedes ?? null},${encode(receipt)}::jsonb,
+      ${new Date(receipt.occurredAt)},${new Date(receipt.recordedAt)},${receipt.cost.money?.units ?? null},${receipt.cost.certainty},${sequence})`);
+    for (const m of receipt.measurements) {
+        await sql.execute(SQL.sql `INSERT INTO metering_measurement(receipt_pk,unit,value,scale,certainty)
+      VALUES(${rpk},${m.unit},${m.quantity?.value.toString() ?? null}::numeric,${m.quantity?.scale ?? null},${m.certainty})`);
+    }
+}
+export async function event(sql, op) {
+    const pk = key(op.scope.namespace, op.operationId), receipt = effective(op);
+    // Keep event IDs in commit order so a later commit cannot enter an existing cursor watermark.
+    await lock(sql, "metering:event-commit-order");
+    await sql.execute(SQL.sql `INSERT INTO metering_event(operation_pk,namespace,state,receipt_pk,occurred_at)
+    VALUES(${pk},${op.scope.namespace},${op.state},${receipt ? key(pk, receipt.id) : null},${receipt ? new Date(receipt.occurredAt) : null})`);
+}

package/dist/schema.d.ts

@@ -0,0 +1 @@
+export declare const schemaStatements: string[];

package/dist/schema.js

@@ -0,0 +1,152 @@
+export const schemaStatements = [
+    `CREATE TABLE metering_operation (
+  operation_pk text PRIMARY KEY,
+  namespace text NOT NULL,
+  principal text NOT NULL,
+  operation_id text NOT NULL,
+  state text NOT NULL CHECK (state IN ('reserved','dispatch_intended','pending','settled','released')),
+  version integer NOT NULL,
+  semantic_hash text NOT NULL,
+  budget_epochs jsonb NOT NULL,
+  reservation_expires_at timestamptz NOT NULL,
+  lease_id text,
+  lease_holder text,
+  lease_expires_at timestamptz,
+  lease_kind text,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  input jsonb NOT NULL,
+  warnings jsonb NOT NULL,
+  UNIQUE(namespace,operation_id)
+)`,
+    `CREATE INDEX metering_operation_expiry_idx ON metering_operation(namespace,state,reservation_expires_at)`,
+    `CREATE TABLE metering_receipt (
+  receipt_pk text PRIMARY KEY,
+  operation_pk text NOT NULL REFERENCES metering_operation(operation_pk),
+  receipt_id text NOT NULL,
+  supersedes text,
+  body jsonb NOT NULL,
+  occurred_at timestamptz NOT NULL,
+  recorded_at timestamptz NOT NULL,
+  cost_units bigint,
+  cost_certainty text NOT NULL,
+  sequence integer NOT NULL,
+  UNIQUE(operation_pk,receipt_id),
+  UNIQUE(operation_pk,sequence)
+)`,
+    `CREATE TABLE metering_measurement (
+  receipt_pk text NOT NULL REFERENCES metering_receipt(receipt_pk),
+  unit text NOT NULL,
+  value numeric(38,0),
+  scale integer,
+  certainty text NOT NULL,
+  PRIMARY KEY(receipt_pk,unit)
+)`,
+    `CREATE TABLE metering_command (
+  operation_pk text NOT NULL REFERENCES metering_operation(operation_pk),
+  command_id text NOT NULL,
+  kind text NOT NULL,
+  input_hash text NOT NULL,
+  input jsonb NOT NULL,
+  result jsonb NOT NULL,
+  PRIMARY KEY(operation_pk,command_id)
+)`,
+    `CREATE TABLE metering_budget (
+  sequence bigserial NOT NULL,
+  namespace text NOT NULL,
+  budget_id text NOT NULL,
+  version integer NOT NULL,
+  scope_kind text NOT NULL,
+  scope_key text NOT NULL,
+  surface text NOT NULL,
+  unit text NOT NULL,
+  limit_value numeric(38,0),
+  limit_scale integer,
+  "window" jsonb NOT NULL,
+  on_exceed text NOT NULL,
+  body jsonb NOT NULL,
+  PRIMARY KEY(namespace,budget_id,version)
+)`,
+    `CREATE INDEX metering_budget_scope_idx ON metering_budget(namespace,scope_key,surface)`,
+    `CREATE TABLE metering_budget_usage (
+  namespace text NOT NULL,
+  budget_id text NOT NULL,
+  epoch text NOT NULL,
+  settled_value numeric(38,0) NOT NULL,
+  outstanding_value numeric(38,0) NOT NULL,
+  scale integer NOT NULL,
+  PRIMARY KEY(namespace,budget_id,epoch)
+)`,
+    `CREATE TABLE metering_event (
+  event_id bigserial PRIMARY KEY,
+  operation_pk text NOT NULL REFERENCES metering_operation(operation_pk),
+  namespace text NOT NULL,
+  state text NOT NULL,
+  receipt_pk text REFERENCES metering_receipt(receipt_pk),
+  occurred_at timestamptz
+)`,
+    `CREATE INDEX metering_event_time_idx ON metering_event(namespace,occurred_at,event_id)`,
+    `CREATE INDEX metering_event_operation_idx ON metering_event(operation_pk,event_id DESC)`,
+    `CREATE TABLE metering_metadata (key text PRIMARY KEY,value text NOT NULL)`,
+    `ALTER TABLE metering_operation ADD COLUMN alerts jsonb NOT NULL DEFAULT '[]'`,
+    `CREATE TABLE metering_alert (
+  alert_key text PRIMARY KEY,
+  namespace text NOT NULL,
+  budget_id text NOT NULL,
+  epoch text NOT NULL,
+  threshold text NOT NULL,
+  UNIQUE(namespace, budget_id, epoch, threshold)
+)`,
+    `CREATE INDEX metering_alert_budget_idx ON metering_alert(namespace, budget_id, epoch)`,
+    `CREATE TABLE metering_request_command (
+  namespace text NOT NULL,
+  command_id text NOT NULL,
+  identity_hash text NOT NULL,
+  PRIMARY KEY(namespace, command_id)
+)`,
+    `CREATE TABLE metering_request_count (
+  bucket_key text PRIMARY KEY,
+  namespace text NOT NULL,
+  day date NOT NULL,
+  body jsonb NOT NULL,
+  count numeric(38,0) NOT NULL CHECK (count > 0)
+)`,
+    `CREATE INDEX metering_request_count_window_idx ON metering_request_count(namespace, day)`,
+    `-- Immutable content-free invoice journal and serialized revision pointer.
+CREATE TABLE metering_import_family (
+  family_id TEXT PRIMARY KEY,
+  latest_import_id TEXT NOT NULL
+)`,
+    `CREATE TABLE metering_import (
+  import_id TEXT PRIMARY KEY,
+  family_id TEXT NOT NULL REFERENCES metering_import_family(family_id),
+  namespace TEXT NOT NULL,
+  principal TEXT NOT NULL,
+  connection TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  file_hash TEXT NOT NULL CHECK (file_hash ~ '^[0-9a-f]{64}$'),
+  window_from TIMESTAMPTZ NOT NULL,
+  window_to TIMESTAMPTZ NOT NULL CHECK (window_to > window_from),
+  recorded_at TIMESTAMPTZ NOT NULL,
+  identity TEXT NOT NULL,
+  body JSONB NOT NULL,
+  UNIQUE (family_id, file_hash)
+)`,
+    `ALTER TABLE metering_import_family ADD CONSTRAINT metering_import_latest_fk
+  FOREIGN KEY (latest_import_id) REFERENCES metering_import(import_id)
+  DEFERRABLE INITIALLY DEFERRED`,
+    `CREATE INDEX metering_import_scope_window_idx
+  ON metering_import(namespace,principal,connection,window_from,window_to)`,
+    `CREATE INDEX metering_operation_connection_created_idx
+  ON metering_operation(namespace,principal,(input->'scope'->>'connection'),created_at)`,
+    `CREATE INDEX metering_receipt_native_id_idx
+  ON metering_receipt((body->>'providerRequestId'))
+  WHERE body->>'providerRequestId' IS NOT NULL`,
+    `CREATE FUNCTION metering_import_immutable() RETURNS TRIGGER LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION 'Meter billing imports are immutable' USING ERRCODE='23514';
+END;
+$$`,
+    `CREATE TRIGGER metering_import_immutable BEFORE UPDATE OR DELETE ON metering_import
+  FOR EACH ROW EXECUTE FUNCTION metering_import_immutable()`,
+];

package/dist/sql.d.ts

@@ -0,0 +1,18 @@
+import type { PostgresDriver, PostgresExecutor } from "./driver.js";
+import { SQL, type Statement } from "./statement.js";
+export type Counters = {
+    statements: number;
+    changes: bigint;
+    rowsRead: number;
+};
+export type Sql = ReturnType<typeof createSql>;
+export declare function createSql(executor: PostgresExecutor, counters: Counters): {
+    query<T>(query: Statement): Promise<T[]>;
+    execute(query: Statement): Promise<number>;
+};
+export declare function transactions(driver: PostgresDriver, schema: string, counters: Counters): {
+    read: <T>(body: (sql: Sql) => Promise<T>) => Promise<T>;
+    write: <T>(body: (sql: Sql) => Promise<T>) => Promise<T>;
+};
+export declare function lock(sql: Sql, value: string, tryOnly?: boolean): Promise<boolean>;
+export { SQL };

package/dist/sql.js

@@ -0,0 +1,38 @@
+import { SQL, schemaIdentifier } from "./statement.js";
+export function createSql(executor, counters) {
+    return {
+        async query(query) {
+            counters.statements++;
+            const result = await executor.query(query.compile());
+            counters.rowsRead += result.length;
+            return result;
+        },
+        async execute(query) {
+            counters.statements++;
+            const count = await executor.execute(query.compile());
+            counters.changes += BigInt(count);
+            return count;
+        },
+    };
+}
+export function transactions(driver, schema, counters) {
+    const identifier = schemaIdentifier(schema);
+    const run = (readOnly, body) => driver.transaction(readOnly, async (executor) => {
+        const sql = createSql(executor, counters);
+        await sql.query(SQL.sql `SELECT set_config('search_path', ${identifier}, true)`);
+        return body(sql);
+    });
+    return {
+        read: (body) => run(true, body),
+        write: (body) => run(false, body),
+    };
+}
+export async function lock(sql, value, tryOnly = false) {
+    if (tryOnly) {
+        const [row] = await sql.query(SQL.sql `SELECT pg_try_advisory_xact_lock(hashtextextended(${value},0)) AS acquired`);
+        return row?.acquired === true;
+    }
+    await sql.query(SQL.sql `SELECT 1 AS acquired FROM pg_advisory_xact_lock(hashtextextended(${value},0))`);
+    return true;
+}
+export { SQL };

package/dist/statement.d.ts

@@ -0,0 +1,22 @@
+/** Compose fragments before numbering parameters; SQL text is never rewritten. */
+declare class Parameter {
+    readonly value: unknown;
+    constructor(value: unknown);
+}
+type Part = string | Parameter;
+export type ParameterizedQuery = {
+    text: string;
+    values: unknown[];
+};
+export declare class Statement {
+    readonly parts: readonly Part[];
+    constructor(parts: readonly Part[]);
+    compile(): ParameterizedQuery;
+}
+export declare const SQL: {
+    sql(strings: TemplateStringsArray, ...values: unknown[]): Statement;
+    join(values: readonly unknown[], separator?: string): Statement;
+    empty: Statement;
+};
+export declare function schemaIdentifier(schema: string): string;
+export {};

package/dist/statement.js

@@ -0,0 +1,40 @@
+/** Compose fragments before numbering parameters; SQL text is never rewritten. */
+class Parameter {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+}
+export class Statement {
+    parts;
+    constructor(parts) {
+        this.parts = parts;
+    }
+    compile() {
+        const values = [];
+        const text = this.parts
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            values.push(part.value);
+            return `$${values.length}`;
+        })
+            .join("");
+        return { text, values };
+    }
+}
+const parts = (value) => value instanceof Statement ? value.parts : [new Parameter(value)];
+export const SQL = {
+    sql(strings, ...values) {
+        return new Statement(strings.flatMap((text, i) => (i < values.length ? [text, ...parts(values[i])] : [text])));
+    },
+    join(values, separator = ",") {
+        return new Statement(values.flatMap((value, i) => (i === 0 ? [...parts(value)] : [separator, ...parts(value)])));
+    },
+    empty: new Statement([]),
+};
+export function schemaIdentifier(schema) {
+    if (!/^[a-z_][a-z0-9_]{0,62}$/.test(schema))
+        throw new TypeError("Invalid metering schema");
+    return `"${schema}"`;
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@usagekit/store-postgres",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.7.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.tsbuildinfo",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "prepublishOnly": "node ../../scripts/publish-guard.mjs",
+    "prepack": "node ../../scripts/package-license.mjs"
+  },
+  "dependencies": {
+    "@usagekit/core": "0.7.0",
+    "@usagekit/store": "0.7.0",
+    "pg": "8.23.1",
+    "@types/pg": "8.23.1"
+  },
+  "description": "Atomic Postgres Store with pg/Prisma drivers, explicit migrations and host transaction composition.",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/msniezynski/usagekit.git",
+    "directory": "packages/store-postgres"
+  },
+  "homepage": "https://usagekit.dev",
+  "bugs": {
+    "url": "https://github.com/msniezynski/usagekit/issues"
+  }
+}

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.