@venturekit/data 0.0.32 → 0.0.33

package/dist/idempotency/postgres.js

@@ -0,0 +1,145 @@
+/**
+ * @venturekit/data — Postgres idempotency store.
+ *
+ * `@venturekit/runtime`'s `idempotencyMiddleware` takes a pluggable
+ * `IdempotencyStore`; the package ships an in-memory one (per-process, so wrong
+ * for Lambda) and a DynamoDB one, and its own docblock has always advertised
+ * "DynamoDB, Postgres, in-memory, etc." without the middle one existing. A
+ * project whose only datastore is Postgres therefore had to add a DynamoDB
+ * table for four columns, or write this adapter itself.
+ *
+ * This is that adapter. It is deliberately typed structurally rather than
+ * against `@venturekit/runtime`'s interface: `runtime` depends on `data`, so
+ * importing the type here would invert the dependency. The shape is asserted by
+ * the tests instead, and `createPostgresIdempotencyStore()` is assignable to
+ * `IdempotencyStore` wherever the middleware wants one.
+ *
+ * ### Schema
+ *
+ * `vk_idempotency_record`, from this package's `vk_data_001_idempotency.sql`.
+ *
+ * ### One thing Postgres does not do for you
+ *
+ * DynamoDB expires rows itself via its TTL attribute. Postgres has no
+ * equivalent, so expired rows accumulate until something deletes them:
+ * {@link purgeExpiredIdempotencyRecords} is that something, and it wants a
+ * schedule. Reads are already correct without it — `get()` filters on
+ * `expires_at` — so a project that forgets pays in disk, not in behaviour.
+ */
+import { query } from '../query/index.js';
+import { assertSqlIdentifier } from '../internal/identifier.js';
+/** Default table name. Overridable for projects that prefix or schema-qualify. */
+export const DEFAULT_IDEMPOTENCY_TABLE = 'vk_idempotency_record';
+/** Structurally compatible with `runtime`'s `IdempotencyConflictError`. */
+class ConflictError extends Error {
+    code = 'IDEMPOTENCY_CONFLICT';
+    constructor(key) {
+        super(`A request with idempotency key '${key}' is already in progress`);
+        this.name = 'IdempotencyConflictError';
+    }
+}
+const toMillis = (v) => v instanceof Date ? v.getTime() : new Date(v).getTime();
+/**
+ * Create a Postgres-backed idempotency store.
+ *
+ * @example
+ * ```ts
+ * import { idempotencyMiddleware } from '@venturekit/runtime';
+ * import { createPostgresIdempotencyStore } from '@venturekit/data/idempotency';
+ *
+ * const idempotency = idempotencyMiddleware({
+ *   store: createPostgresIdempotencyStore({ scope: () => getCurrentTenantId() }),
+ * });
+ * ```
+ */
+export function createPostgresIdempotencyStore(options = {}) {
+    const table = options.tableName ?? DEFAULT_IDEMPOTENCY_TABLE;
+    assertSqlIdentifier(table, 'PostgresIdempotencyStoreOptions.tableName');
+    const run = options.querier ?? query;
+    /* `<scope>:<key>`. The separator is a colon rather than nothing so that
+       scope `a` + key `bc` cannot collide with scope `ab` + key `c`. */
+    const scoped = (key) => {
+        const s = options.scope?.();
+        return s ? `${s}:${key}` : key;
+    };
+    return {
+        async get(key) {
+            /* Expiry is filtered in SQL, not in JS: an expired row must read as
+               absent even if a purge has not run, and `now()` on the server avoids
+               trusting a Lambda's clock. */
+            const rows = await run(`SELECT key, response, status, expires_at
+           FROM ${table}
+          WHERE key = $1 AND expires_at > now()`, [scoped(key)]);
+            const row = rows[0];
+            if (!row)
+                return null;
+            return {
+                /* the caller's key, not the scoped one it is stored under */
+                key,
+                response: row.response,
+                status: row.status,
+                expiresAt: toMillis(row.expires_at),
+            };
+        },
+        async save(record) {
+            /* One statement, so the check and the write cannot be raced.
+               `ON CONFLICT ... DO UPDATE ... WHERE` takes the row only when the
+               existing one is finished or stale; a live `pending` row matches
+               neither, updates nothing, and returns no rows — which is the conflict.
+               Doing this as SELECT-then-INSERT would let two concurrent requests
+               both see "absent" and both proceed. */
+            const rows = await run(`INSERT INTO ${table} (key, response, status, expires_at)
+              VALUES ($1, $2, $3, to_timestamp($4::double precision / 1000))
+         ON CONFLICT (key) DO UPDATE
+                SET response   = EXCLUDED.response,
+                    status     = EXCLUDED.status,
+                    expires_at = EXCLUDED.expires_at,
+                    updated_at = now()
+              WHERE ${table}.status <> 'pending'
+                 OR ${table}.expires_at <= now()
+           RETURNING key`, [scoped(record.key), record.response, record.status, record.expiresAt]);
+            if (rows.length === 0)
+                throw new ConflictError(record.key);
+        },
+        async update(key, updates) {
+            /* Built from whichever fields were supplied — the middleware sends
+               `{ status, response }` on success and nothing else. */
+            const sets = [];
+            const params = [scoped(key)];
+            if (updates.response !== undefined) {
+                params.push(updates.response);
+                sets.push(`response = $${params.length}`);
+            }
+            if (updates.status !== undefined) {
+                params.push(updates.status);
+                sets.push(`status = $${params.length}`);
+            }
+            if (updates.expiresAt !== undefined) {
+                params.push(updates.expiresAt);
+                sets.push(`expires_at = to_timestamp($${params.length}::double precision / 1000)`);
+            }
+            if (sets.length === 0)
+                return;
+            await run(`UPDATE ${table} SET ${sets.join(', ')}, updated_at = now() WHERE key = $1`, params);
+        },
+        async delete(key) {
+            await run(`DELETE FROM ${table} WHERE key = $1`, [scoped(key)]);
+        },
+    };
+}
+/**
+ * Delete expired records. Returns how many went.
+ *
+ * Postgres has no TTL, so this is the counterpart to DynamoDB's automatic
+ * expiry and it needs a caller — a `schedules` intent running nightly is
+ * plenty. Nothing reads an expired row before it is deleted (`get()` filters
+ * on `expires_at`), so the only cost of never calling this is disk.
+ */
+export async function purgeExpiredIdempotencyRecords(options = {}) {
+    const table = options.tableName ?? DEFAULT_IDEMPOTENCY_TABLE;
+    assertSqlIdentifier(table, 'purgeExpiredIdempotencyRecords.tableName');
+    const run = options.querier ?? query;
+    const rows = await run(`DELETE FROM ${table} WHERE expires_at <= now() RETURNING key`);
+    return rows.length;
+}
+//# sourceMappingURL=postgres.js.map

package/dist/idempotency/postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.js","sourceRoot":"","sources":["../../src/idempotency/postgres.ts"],"names":[],"mappings":"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"}

package/dist/internal/identifier.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @venturekit/data — SQL identifier validation.
+ *
+ * Postgres accepts parameter placeholders for *values* only, so a table or
+ * column name that comes from configuration has to be interpolated into the
+ * statement text. Restricting those to a conservative ASCII whitelist makes
+ * injection structurally impossible rather than a matter of trusting the caller.
+ */
+/**
+ * Throw unless `name` is safe to interpolate into a statement as an identifier.
+ *
+ * `context` names the option the value came from, so the error tells the
+ * operator which setting to fix rather than just that something was rejected.
+ */
+export declare function assertSqlIdentifier(name: string, context: string): void;
+//# sourceMappingURL=identifier.d.ts.map

package/dist/internal/identifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.d.ts","sourceRoot":"","sources":["../../src/internal/identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAOvE"}

package/dist/internal/identifier.js

@@ -0,0 +1,23 @@
+/**
+ * @venturekit/data — SQL identifier validation.
+ *
+ * Postgres accepts parameter placeholders for *values* only, so a table or
+ * column name that comes from configuration has to be interpolated into the
+ * statement text. Restricting those to a conservative ASCII whitelist makes
+ * injection structurally impossible rather than a matter of trusting the caller.
+ */
+/** Unquoted-identifier shape: a letter or underscore, then word characters. */
+const SQL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Throw unless `name` is safe to interpolate into a statement as an identifier.
+ *
+ * `context` names the option the value came from, so the error tells the
+ * operator which setting to fix rather than just that something was rejected.
+ */
+export function assertSqlIdentifier(name, context) {
+    if (!SQL_IDENTIFIER.test(name)) {
+        throw new Error(`[venturekit/data] invalid SQL identifier for ${context}: '${name}'. ` +
+            `Must match ${String(SQL_IDENTIFIER)}.`);
+    }
+}
+//# sourceMappingURL=identifier.js.map

package/dist/internal/identifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identifier.js","sourceRoot":"","sources":["../../src/internal/identifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,+EAA+E;AAC/E,MAAM,cAAc,GAAG,0BAA0B,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY,EAAE,OAAe;IAC/D,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,gDAAgD,OAAO,MAAM,IAAI,KAAK;YACpE,cAAc,MAAM,CAAC,cAAc,CAAC,GAAG,CAC1C,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/jobs/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @venturekit/data — durable background jobs in Postgres.
+ *
+ * For work the product talks about, where the SQS `queues` intent is for work it
+ * does not. See `./postgres.ts`.
+ */
+export { enqueueJob, claimJobs, completeJob, failJob, releaseJob, reclaimStuckJobs, listJobs, runJobsOnce, DEFAULT_JOB_TABLE, } from './postgres.js';
+export type { Job, JobStatus, JobHandler, EnqueueJobInput, ClaimJobsOptions, FailJobOptions, ReclaimOptions, ListJobsOptions, RunJobsResult, JobTableOption, JobQuerierOption, } from './postgres.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/jobs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,WAAW,EACX,OAAO,EACP,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,GAAG,EACH,SAAS,EACT,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC"}

package/dist/jobs/index.js

@@ -0,0 +1,8 @@
+/**
+ * @venturekit/data — durable background jobs in Postgres.
+ *
+ * For work the product talks about, where the SQS `queues` intent is for work it
+ * does not. See `./postgres.ts`.
+ */
+export { enqueueJob, claimJobs, completeJob, failJob, releaseJob, reclaimStuckJobs, listJobs, runJobsOnce, DEFAULT_JOB_TABLE, } from './postgres.js';
+//# sourceMappingURL=index.js.map

package/dist/jobs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/jobs/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,SAAS,EACT,WAAW,EACX,OAAO,EACP,UAAU,EACV,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,iBAAiB,GAClB,MAAM,eAAe,CAAC"}

package/dist/jobs/postgres.d.ts

@@ -0,0 +1,197 @@
+/**
+ * @venturekit/data — durable background jobs in Postgres.
+ *
+ * The `queues` intent (SQS) stays the default for opaque, high-throughput
+ * fan-out. This is for the other kind of work: the kind the product talks about.
+ * "Which imports are still geocoding for this tenant" is a screen, and a queue
+ * has no query surface — messages are invisible until received and then
+ * invisible to everyone else. Rebuilding that visibility over SQS means a second
+ * table tracking what you enqueued, at which point the queue is the redundant
+ * half, because the table can be claimed from directly.
+ *
+ * Unlike the outbox, there is no port and no adapter here. The whole value is
+ * that the work lives in queryable rows, and the claim — `FOR UPDATE SKIP
+ * LOCKED` — is SQL rather than portable logic. An abstraction over it would have
+ * exactly one implementation and would hide the one feature worth having.
+ *
+ * ```ts
+ * // enqueue in the transaction that made the work necessary
+ * await withTransaction(async (tx) => {
+ *   const batch = await stageImport(tx, rows);
+ *   await enqueueJob(tx.query, { kind: 'geocode-import', tenantId, payload: { batch: batch.id } });
+ * });
+ *
+ * // drain in a `schedules` cron
+ * await runJobsOnce({
+ *   'geocode-import': async (job) => { await geocode(job.payload); },
+ * });
+ * ```
+ */
+import type { Querier } from '../query/index.js';
+/** Default table name, created by `vk_data_003_jobs.sql`. */
+export declare const DEFAULT_JOB_TABLE = "vk_job";
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled';
+export interface Job<TPayload = unknown> {
+    id: string;
+    tenantId: string | null;
+    kind: string;
+    payload: TPayload;
+    status: JobStatus;
+    runAfter: string;
+    attempts: number;
+    maxAttempts: number;
+    lockedAt: string | null;
+    lockedBy: string | null;
+    lastError: string | null;
+    createdAt: string;
+    finishedAt: string | null;
+}
+export interface EnqueueJobInput<TPayload = unknown> {
+    kind: string;
+    payload?: TPayload;
+    /** `null` (the default) is platform-wide work belonging to no tenant. */
+    tenantId?: string | null;
+    /** Earliest run time. Omit for "as soon as a worker picks it up". */
+    runAfter?: Date | string;
+    /** Failures after which the job is left `failed` for an operator. Default 5. */
+    maxAttempts?: number;
+}
+export interface JobTableOption {
+    /** Table name. Validated as an identifier, since it is interpolated. */
+    tableName?: string;
+}
+export interface JobQuerierOption extends JobTableOption {
+    /** Runs the statements. Defaults to the pooled `query`. */
+    querier?: Querier;
+}
+/**
+ * Enqueue a job **on the caller's transaction**.
+ *
+ * `querier` is required and not defaulted, for the same reason as
+ * `appendToOutbox`: a job enqueued on a pooled connection can commit while the
+ * transaction that needed it rolls back, leaving a worker to act on a state that
+ * does not exist. Pass the transaction's `query`.
+ */
+export declare function enqueueJob<TPayload = unknown>(querier: Querier, input: EnqueueJobInput<TPayload>, options?: JobTableOption): Promise<string>;
+export interface ClaimJobsOptions extends JobQuerierOption {
+    /** How many to take. Default 10. */
+    limit?: number;
+    /** Only these kinds. Omit for any. */
+    kinds?: string[];
+    /**
+     * Identifies the claiming worker in `locked_by`. Default
+     * `AWS_LAMBDA_LOG_STREAM_NAME` or `'worker'` — a value that survives into the
+     * row so a stuck job can be traced to the process that abandoned it.
+     */
+    workerId?: string;
+}
+/**
+ * Claim due jobs, marking them `running`.
+ *
+ * `FOR UPDATE SKIP LOCKED` inside the UPDATE's subquery is what makes several
+ * workers safe on one table: each takes rows nobody else holds and skips the
+ * rest rather than queueing behind them. Without SKIP LOCKED, a second worker
+ * blocks on the first's rows and the pool drains.
+ */
+export declare function claimJobs<TPayload = unknown>(options?: ClaimJobsOptions): Promise<Job<TPayload>[]>;
+/** Mark a claimed job done. */
+export declare function completeJob(id: string, options?: JobQuerierOption): Promise<void>;
+export interface FailJobOptions extends JobQuerierOption {
+    /**
+     * Seconds before the retry becomes due. Omit for exponential backoff from the
+     * attempt count: 2^attempts seconds, capped at an hour.
+     */
+    retryInSeconds?: number;
+}
+/**
+ * Record a failed attempt: re-queue it with a later `run_after`, or leave it
+ * `failed` once the attempts are spent.
+ *
+ * `attempts` was already incremented by the claim, so a crash between claim and
+ * this call still counts — otherwise a job that kills its worker every time
+ * would retry forever.
+ */
+export declare function failJob(id: string, error: unknown, options?: FailJobOptions): Promise<void>;
+/**
+ * Hand a claimed job back **without counting the attempt**.
+ *
+ * For "I cannot run this right now", as distinct from "I ran it and it failed":
+ * no handler is registered yet, a dependency is briefly unavailable, the worker
+ * is shutting down. The claim already incremented `attempts`, so this undoes
+ * that — otherwise a job nobody can run yet would exhaust its attempts while
+ * never actually being attempted, which is how a mid-deploy job ends up `failed`
+ * for no reason.
+ */
+export declare function releaseJob(id: string, reason: string, options?: JobQuerierOption & {
+    retryInSeconds?: number;
+}): Promise<void>;
+export interface ReclaimOptions extends JobQuerierOption {
+    /**
+     * How long a `running` job may hold its lock before it is presumed abandoned.
+     * Default 900 (15 minutes) — comfortably past any Lambda's own timeout, since
+     * reclaiming a job that is merely slow runs it twice.
+     */
+    staleAfterSeconds?: number;
+}
+/**
+ * Re-queue jobs left `running` by a worker that died, and return how many.
+ *
+ * A crashed worker cannot clean up after itself, so nothing else will ever move
+ * these rows: `running` plus an old `locked_at` is indistinguishable from a dead
+ * process, and treating it as one is the only way the work resumes. Worth a
+ * schedule of its own, or a call at the top of each worker pass.
+ *
+ * Jobs whose attempts are spent go to `failed` rather than back to `queued` —
+ * a job that reliably kills its worker must not do so forever.
+ */
+export declare function reclaimStuckJobs(options?: ReclaimOptions): Promise<number>;
+export interface ListJobsOptions extends JobQuerierOption {
+    kind?: string;
+    status?: JobStatus;
+    limit?: number;
+    /**
+     * Confine the result to the request's tenant scope. Default `true`, which is
+     * the safe default for anything serving a request: this table carries no RLS
+     * policy (a worker must see every tenant's work, and platform rows have no
+     * tenant at all), so the scope predicate has to be applied here instead.
+     *
+     * Set `false` only in a worker or an operator tool that is meant to see
+     * everything.
+     */
+    tenantScoped?: boolean;
+}
+/**
+ * The query this table exists to make possible: what work is outstanding.
+ *
+ * With `tenantScoped` (the default) the predicate is
+ * `tenant_id = ANY (vk_tenant_scope())` — the same predicate an RLS policy would
+ * apply, so a caller who goes through this helper cannot see another tenant's
+ * jobs. Platform rows (`tenant_id IS NULL`) fall out naturally, since
+ * `NULL = ANY (...)` is never true.
+ */
+export declare function listJobs<TPayload = unknown>(options?: ListJobsOptions): Promise<Job<TPayload>[]>;
+/** A handler for one `kind`. Throwing marks the attempt failed. */
+export type JobHandler<TPayload = unknown> = (job: Job<TPayload>) => Promise<void>;
+export interface RunJobsResult {
+    claimed: number;
+    succeeded: number;
+    failed: number;
+    /** Claimed jobs whose `kind` had no handler. Re-queued, not failed. */
+    unhandled: number;
+}
+/**
+ * One worker pass: claim, dispatch, settle. The job-queue analogue of the
+ * outbox's `relayOnce`.
+ *
+ * Returns counts rather than throwing on a handler failure — a failing job is
+ * an expected operating condition and the caller's job is to schedule the next
+ * pass. A failing *store* propagates, for the same reason as in the relay: a
+ * worker that cannot record outcomes must stop rather than keep claiming.
+ *
+ * A `kind` with no handler is re-queued with a short delay rather than failed.
+ * A deploy in progress is the usual cause — one version enqueues a kind the
+ * still-running version does not know — and burning an attempt on that would
+ * exhaust a perfectly good job during a rollout.
+ */
+export declare function runJobsOnce(handlers: Record<string, JobHandler<never>>, options?: ClaimJobsOptions): Promise<RunJobsResult>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/jobs/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/jobs/postgres.ts"],"names":[],"mappings":"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"}