@venturekit/data 0.0.31 → 0.0.33

package/dist/files/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @venturekit/data — uploaded-object metadata.
+ *
+ * The record of what was uploaded; `@venturekit/storage` holds the bytes. See
+ * `./postgres.ts`.
+ */
+export { recordFileObject, getFileObject, listFileObjects, findFileObjectByChecksum, archiveFileObject, sweepArchivedFiles, DEFAULT_FILE_TABLE, } from './postgres.js';
+export type { FileObject, RecordFileObjectInput, ListFileObjectsOptions, SweepArchivedFilesOptions, SweepResult, ObjectDeleter, FileTableOption, FileQuerierOption, } from './postgres.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,UAAU,EACV,qBAAqB,EACrB,sBAAsB,EACtB,yBAAyB,EACzB,WAAW,EACX,aAAa,EACb,eAAe,EACf,iBAAiB,GAClB,MAAM,eAAe,CAAC"}

package/dist/files/index.js

@@ -0,0 +1,8 @@
+/**
+ * @venturekit/data — uploaded-object metadata.
+ *
+ * The record of what was uploaded; `@venturekit/storage` holds the bytes. See
+ * `./postgres.ts`.
+ */
+export { recordFileObject, getFileObject, listFileObjects, findFileObjectByChecksum, archiveFileObject, sweepArchivedFiles, DEFAULT_FILE_TABLE, } from './postgres.js';
+//# sourceMappingURL=index.js.map

package/dist/files/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/files/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,eAAe,CAAC"}

package/dist/files/postgres.d.ts

@@ -0,0 +1,150 @@
+/**
+ * @venturekit/data — uploaded-object metadata.
+ *
+ * `@venturekit/storage` is complete on the object itself: put, get, head,
+ * presign, copy, image optimisation. What a bucket cannot tell you is anything a
+ * product needs to know about an upload — which tenant owns it, what it is for,
+ * who put it there, whether these exact bytes are already stored, and when it
+ * may be deleted. `ListObjectsV2` plus a key-naming convention is the usual
+ * substitute and it fails at the first "every document for this tenant, newest
+ * first".
+ *
+ * This module is the record; that package is the bytes. They are deliberately
+ * not coupled: `@venturekit/storage` has no `pg` dependency and this has no
+ * `@aws-sdk/client-s3` one, so {@link sweepArchivedFiles} takes the object
+ * deletion as a port and the consumer wires the two together:
+ *
+ * ```ts
+ * await sweepArchivedFiles({
+ *   deleteObjects: (keys) => storage.deleteMany(keys).then(() => undefined),
+ * });
+ * ```
+ */
+import type { Querier } from '../query/index.js';
+/** Default table name, created by `vk_data_004_file_object.sql`. */
+export declare const DEFAULT_FILE_TABLE = "vk_file_object";
+export interface FileObject {
+    id: string;
+    tenantId: string | null;
+    purpose: string;
+    bucket: string;
+    objectKey: string;
+    contentType: string;
+    sizeBytes: number;
+    checksum: string | null;
+    originalName: string | null;
+    uploadedBy: string | null;
+    createdAt: string;
+    archivedAt: string | null;
+}
+export interface RecordFileObjectInput {
+    /** What the file is for. Decides retention and access in your product. */
+    purpose: string;
+    bucket: string;
+    objectKey: string;
+    contentType: string;
+    sizeBytes: number;
+    /** `null` for platform-wide artefacts. */
+    tenantId?: string | null;
+    /** SHA-256 hex, so a re-upload of identical bytes can be recognised. */
+    checksum?: string | null;
+    /** The name the user's file had — never the storage key. */
+    originalName?: string | null;
+    uploadedBy?: string | null;
+}
+export interface FileTableOption {
+    /** Table name. Validated as an identifier, since it is interpolated. */
+    tableName?: string;
+}
+export interface FileQuerierOption extends FileTableOption {
+    /** Runs the statements. Defaults to the pooled `query`. */
+    querier?: Querier;
+}
+/**
+ * Record an uploaded object.
+ *
+ * Call it in the transaction that also stores whatever references the file, so a
+ * rolled-back request cannot leave a row pointing at an object nothing uses —
+ * which is why `querier` is a required first argument here as in
+ * `appendToOutbox` and `enqueueJob`.
+ *
+ * **Record after the upload succeeds, not before.** The reverse ordering (row,
+ * then upload) produces a row whose object never arrived, and nothing
+ * distinguishes that from an object deleted later.
+ */
+export declare function recordFileObject(querier: Querier, input: RecordFileObjectInput, options?: FileTableOption): Promise<string>;
+/** One file by id. Archived rows are returned — callers may need to show them. */
+export declare function getFileObject(id: string, options?: FileQuerierOption): Promise<FileObject | null>;
+export interface ListFileObjectsOptions extends FileQuerierOption {
+    purpose?: string;
+    limit?: number;
+    /** Include archived rows. Default `false`. */
+    includeArchived?: boolean;
+    /**
+     * Confine to the request's tenant scope (`vk_tenant_scope()`). Default
+     * `true`: this table carries no RLS policy by default, because the installer
+     * needs the consumer's role name, so the predicate is applied here instead.
+     */
+    tenantScoped?: boolean;
+}
+/** Live files for the current scope, newest first. */
+export declare function listFileObjects(options?: ListFileObjectsOptions): Promise<FileObject[]>;
+/**
+ * Find a live file with these exact bytes, for de-duplication on re-upload.
+ *
+ * Scoped to the tenant by default and deliberately so: matching a checksum
+ * across tenants would let one tenant's upload resolve to another's object,
+ * which is a cross-tenant read dressed up as an optimisation.
+ */
+export declare function findFileObjectByChecksum(checksum: string, options?: ListFileObjectsOptions): Promise<FileObject | null>;
+/**
+ * Mark a file deleted without touching the object.
+ *
+ * This is what the request path calls. Returns `false` when the row is already
+ * archived or absent, so a double-click is not an error.
+ */
+export declare function archiveFileObject(id: string, options?: FileQuerierOption): Promise<boolean>;
+/** Deletes objects from wherever they live. `@venturekit/storage`'s
+ *  `deleteMany` satisfies this. */
+export type ObjectDeleter = (keys: string[]) => Promise<void>;
+export interface SweepArchivedFilesOptions extends FileQuerierOption {
+    /** Removes the bytes. Called before the rows are deleted. */
+    deleteObjects: ObjectDeleter;
+    /**
+     * Grace period before an archived file is really removed. Default 604800 (7
+     * days) — long enough that "undo" is possible and that a bad bulk-archive can
+     * be caught before the bytes are gone.
+     */
+    retainForSeconds?: number;
+    /** Rows per pass. Default 100. */
+    limit?: number;
+}
+export interface SweepResult {
+    /** Rows whose object and record were both removed. */
+    deleted: number;
+    /** Rows considered but left alone because the object deletion threw. */
+    remaining: number;
+}
+/**
+ * Delete the objects and rows of files archived longer ago than the grace
+ * period.
+ *
+ * **Objects first, then rows**, and the order is the whole design. There is no
+ * transaction spanning S3 and Postgres, so one of two failure modes has to be
+ * chosen:
+ *
+ *   - rows first → an orphaned object nobody can account for, discoverable only
+ *     by diffing the entire bucket against this table;
+ *   - objects first → a row naming a key that 404s, discoverable by walking
+ *     rows, and invisible to users because the row is already archived.
+ *
+ * The second is recoverable and the first is silent, so the sweep takes the
+ * second. It is re-runnable for the same reason: a crash after the delete
+ * re-deletes keys that are already gone, which S3 treats as success.
+ *
+ * If `deleteObjects` throws, the rows are left for the next pass rather than
+ * deleted anyway — which would produce exactly the orphan this ordering exists
+ * to avoid.
+ */
+export declare function sweepArchivedFiles(options: SweepArchivedFilesOptions): Promise<SweepResult>;
+//# sourceMappingURL=postgres.d.ts.map

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

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

package/dist/files/postgres.js

@@ -0,0 +1,194 @@
+/**
+ * @venturekit/data — uploaded-object metadata.
+ *
+ * `@venturekit/storage` is complete on the object itself: put, get, head,
+ * presign, copy, image optimisation. What a bucket cannot tell you is anything a
+ * product needs to know about an upload — which tenant owns it, what it is for,
+ * who put it there, whether these exact bytes are already stored, and when it
+ * may be deleted. `ListObjectsV2` plus a key-naming convention is the usual
+ * substitute and it fails at the first "every document for this tenant, newest
+ * first".
+ *
+ * This module is the record; that package is the bytes. They are deliberately
+ * not coupled: `@venturekit/storage` has no `pg` dependency and this has no
+ * `@aws-sdk/client-s3` one, so {@link sweepArchivedFiles} takes the object
+ * deletion as a port and the consumer wires the two together:
+ *
+ * ```ts
+ * await sweepArchivedFiles({
+ *   deleteObjects: (keys) => storage.deleteMany(keys).then(() => undefined),
+ * });
+ * ```
+ */
+import { query } from '../query/index.js';
+import { assertSqlIdentifier } from '../internal/identifier.js';
+/** Default table name, created by `vk_data_004_file_object.sql`. */
+export const DEFAULT_FILE_TABLE = 'vk_file_object';
+const iso = (v) => v instanceof Date ? v.toISOString() : v;
+function mapRow(r) {
+    return {
+        id: r.id,
+        tenantId: r.tenant_id,
+        purpose: r.purpose,
+        bucket: r.bucket,
+        objectKey: r.object_key,
+        contentType: r.content_type,
+        /* `bigint` arrives as a string from node-postgres. A file over 9 PB would
+           lose precision as a Number; a file over 9 PB is not the problem here. */
+        sizeBytes: typeof r.size_bytes === 'string' ? Number(r.size_bytes) : r.size_bytes,
+        checksum: r.checksum,
+        originalName: r.original_name,
+        uploadedBy: r.uploaded_by,
+        createdAt: iso(r.created_at),
+        archivedAt: r.archived_at === null ? null : iso(r.archived_at),
+    };
+}
+const COLUMNS = `id, tenant_id, purpose, bucket, object_key, content_type,
+                 size_bytes, checksum, original_name, uploaded_by, created_at,
+                 archived_at`;
+function tableOf(options, context) {
+    const table = options.tableName ?? DEFAULT_FILE_TABLE;
+    assertSqlIdentifier(table, context);
+    return table;
+}
+/**
+ * Record an uploaded object.
+ *
+ * Call it in the transaction that also stores whatever references the file, so a
+ * rolled-back request cannot leave a row pointing at an object nothing uses —
+ * which is why `querier` is a required first argument here as in
+ * `appendToOutbox` and `enqueueJob`.
+ *
+ * **Record after the upload succeeds, not before.** The reverse ordering (row,
+ * then upload) produces a row whose object never arrived, and nothing
+ * distinguishes that from an object deleted later.
+ */
+export async function recordFileObject(querier, input, options = {}) {
+    const table = tableOf(options, 'recordFileObject.tableName');
+    const rows = await querier(`INSERT INTO ${table}
+       (tenant_id, purpose, bucket, object_key, content_type, size_bytes,
+        checksum, original_name, uploaded_by)
+     VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9)
+     RETURNING id`, [
+        input.tenantId ?? null,
+        input.purpose,
+        input.bucket,
+        input.objectKey,
+        input.contentType,
+        input.sizeBytes,
+        input.checksum ?? null,
+        input.originalName ?? null,
+        input.uploadedBy ?? null,
+    ]);
+    const id = rows[0]?.id;
+    if (!id) {
+        throw new Error('[venturekit/data] recordFileObject: insert returned no id');
+    }
+    return id;
+}
+/** One file by id. Archived rows are returned — callers may need to show them. */
+export async function getFileObject(id, options = {}) {
+    const table = tableOf(options, 'getFileObject.tableName');
+    const run = options.querier ?? query;
+    const rows = await run(`SELECT ${COLUMNS} FROM ${table} WHERE id = $1`, [id]);
+    const row = rows[0];
+    return row ? mapRow(row) : null;
+}
+/** Live files for the current scope, newest first. */
+export async function listFileObjects(options = {}) {
+    const table = tableOf(options, 'listFileObjects.tableName');
+    const run = options.querier ?? query;
+    const rows = await run(`SELECT ${COLUMNS}
+       FROM ${table}
+      WHERE ($1::text IS NULL OR purpose = $1)
+        AND ($3::boolean OR archived_at IS NULL)
+        AND (NOT $4::boolean OR tenant_id = ANY (vk_tenant_scope()))
+      ORDER BY created_at DESC
+      LIMIT $2`, [
+        options.purpose ?? null,
+        options.limit ?? 50,
+        options.includeArchived === true,
+        options.tenantScoped !== false,
+    ]);
+    return rows.map(mapRow);
+}
+/**
+ * Find a live file with these exact bytes, for de-duplication on re-upload.
+ *
+ * Scoped to the tenant by default and deliberately so: matching a checksum
+ * across tenants would let one tenant's upload resolve to another's object,
+ * which is a cross-tenant read dressed up as an optimisation.
+ */
+export async function findFileObjectByChecksum(checksum, options = {}) {
+    const table = tableOf(options, 'findFileObjectByChecksum.tableName');
+    const run = options.querier ?? query;
+    const rows = await run(`SELECT ${COLUMNS}
+       FROM ${table}
+      WHERE checksum = $1
+        AND archived_at IS NULL
+        AND (NOT $2::boolean OR tenant_id = ANY (vk_tenant_scope()))
+      ORDER BY created_at
+      LIMIT 1`, [checksum, options.tenantScoped !== false]);
+    const row = rows[0];
+    return row ? mapRow(row) : null;
+}
+/**
+ * Mark a file deleted without touching the object.
+ *
+ * This is what the request path calls. Returns `false` when the row is already
+ * archived or absent, so a double-click is not an error.
+ */
+export async function archiveFileObject(id, options = {}) {
+    const table = tableOf(options, 'archiveFileObject.tableName');
+    const run = options.querier ?? query;
+    const rows = await run(`UPDATE ${table}
+        SET archived_at = now(), updated_at = now()
+      WHERE id = $1 AND archived_at IS NULL
+      RETURNING id`, [id]);
+    return rows.length > 0;
+}
+/**
+ * Delete the objects and rows of files archived longer ago than the grace
+ * period.
+ *
+ * **Objects first, then rows**, and the order is the whole design. There is no
+ * transaction spanning S3 and Postgres, so one of two failure modes has to be
+ * chosen:
+ *
+ *   - rows first → an orphaned object nobody can account for, discoverable only
+ *     by diffing the entire bucket against this table;
+ *   - objects first → a row naming a key that 404s, discoverable by walking
+ *     rows, and invisible to users because the row is already archived.
+ *
+ * The second is recoverable and the first is silent, so the sweep takes the
+ * second. It is re-runnable for the same reason: a crash after the delete
+ * re-deletes keys that are already gone, which S3 treats as success.
+ *
+ * If `deleteObjects` throws, the rows are left for the next pass rather than
+ * deleted anyway — which would produce exactly the orphan this ordering exists
+ * to avoid.
+ */
+export async function sweepArchivedFiles(options) {
+    const table = tableOf(options, 'sweepArchivedFiles.tableName');
+    const run = options.querier ?? query;
+    const retain = options.retainForSeconds ?? 604_800;
+    const rows = await run(`SELECT id, object_key
+       FROM ${table}
+      WHERE archived_at IS NOT NULL
+        AND archived_at < now() - make_interval(secs => $1::double precision)
+      ORDER BY archived_at
+      LIMIT $2`, [retain, options.limit ?? 100]);
+    if (rows.length === 0)
+        return { deleted: 0, remaining: 0 };
+    try {
+        await options.deleteObjects(rows.map((r) => r.object_key));
+    }
+    catch {
+        /* Leave every row of this batch. Deleting them now is what creates an
+           object nobody can account for. */
+        return { deleted: 0, remaining: rows.length };
+    }
+    await run(`DELETE FROM ${table} WHERE id = ANY($1::uuid[])`, [rows.map((r) => r.id)]);
+    return { deleted: rows.length, remaining: 0 };
+}
+//# sourceMappingURL=postgres.js.map

package/dist/files/postgres.js.map

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

package/dist/idempotency/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @venturekit/data — Postgres idempotency store.
+ *
+ * Plugs into `@venturekit/runtime`'s `idempotencyMiddleware` for projects whose
+ * only datastore is Postgres. See `./postgres.ts`.
+ */
+export { createPostgresIdempotencyStore, purgeExpiredIdempotencyRecords, DEFAULT_IDEMPOTENCY_TABLE, } from './postgres.js';
+export type { IdempotencyRecord, PostgresIdempotencyStore, PostgresIdempotencyStoreOptions, } from './postgres.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/idempotency/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AAEvB,YAAY,EACV,iBAAiB,EACjB,wBAAwB,EACxB,+BAA+B,GAChC,MAAM,eAAe,CAAC"}

package/dist/idempotency/index.js

@@ -0,0 +1,8 @@
+/**
+ * @venturekit/data — Postgres idempotency store.
+ *
+ * Plugs into `@venturekit/runtime`'s `idempotencyMiddleware` for projects whose
+ * only datastore is Postgres. See `./postgres.ts`.
+ */
+export { createPostgresIdempotencyStore, purgeExpiredIdempotencyRecords, DEFAULT_IDEMPOTENCY_TABLE, } from './postgres.js';
+//# sourceMappingURL=index.js.map

package/dist/idempotency/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/idempotency/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,8BAA8B,EAC9B,8BAA8B,EAC9B,yBAAyB,GAC1B,MAAM,eAAe,CAAC"}

package/dist/idempotency/postgres.d.ts

@@ -0,0 +1,107 @@
+/**
+ * @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 type { Querier } from '../query/index.js';
+/** Default table name. Overridable for projects that prefix or schema-qualify. */
+export declare const DEFAULT_IDEMPOTENCY_TABLE = "vk_idempotency_record";
+/**
+ * One stored request result. Mirrors `@venturekit/runtime`'s
+ * `IdempotencyRecord` field for field, including `expiresAt` as epoch
+ * milliseconds — the column is `timestamptz`, converted on both edges, because
+ * a bigint of millis is unreadable in `psql` and a timestamp is not.
+ */
+export interface IdempotencyRecord {
+    key: string;
+    response: string;
+    status: 'pending' | 'completed';
+    expiresAt: number;
+}
+export interface PostgresIdempotencyStoreOptions {
+    /**
+     * Runs the statements. Defaults to this package's pooled `query`. Pass a
+     * transaction's `query` to make the record commit with the work it guards —
+     * which is the only way "the response was stored" and "the side effect
+     * happened" can be made to agree.
+     */
+    querier?: Querier;
+    /** Table name. Validated as an identifier, since it is interpolated. */
+    tableName?: string;
+    /**
+     * Namespace folded into every key.
+     *
+     * **Read this if the API is multi-tenant.** The middleware's default
+     * `headerKeyExtractor('idempotency-key')` takes the key from a client-supplied
+     * header, and the store is a flat key→response map. So two callers who happen
+     * to send the same key — `"1"`, `"retry"`, a uuid a client reuses — collide,
+     * and the second one is served the first one's cached response body. Across
+     * tenants that is a cross-tenant read.
+     *
+     * Supplying a scope makes the stored key `<scope>:<key>`, so collisions are
+     * confined to whatever the scope names. Pass the acting tenant id, or the
+     * principal, for anything a client can reach:
+     *
+     * ```ts
+     * createPostgresIdempotencyStore({ scope: () => getCurrentTenantId() })
+     * ```
+     *
+     * Left unset the behaviour matches the existing stores — unscoped — which is
+     * safe only when the key is server-generated or the API is single-tenant.
+     */
+    scope?: () => string | null | undefined;
+}
+/** The store's four methods, as the middleware expects them. */
+export interface PostgresIdempotencyStore {
+    get(key: string): Promise<IdempotencyRecord | null>;
+    save(record: IdempotencyRecord): Promise<void>;
+    update(key: string, updates: Partial<IdempotencyRecord>): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * 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 declare function createPostgresIdempotencyStore(options?: PostgresIdempotencyStoreOptions): PostgresIdempotencyStore;
+/**
+ * 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 declare function purgeExpiredIdempotencyRecords(options?: Pick<PostgresIdempotencyStoreOptions, 'querier' | 'tableName'>): Promise<number>;
+//# sourceMappingURL=postgres.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/idempotency/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAGjD,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,SAAS,GAAG,WAAW,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,+BAA+B;IAC9C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACzC;AAWD,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACpD,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAYD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,GAAE,+BAAoC,GAC5C,wBAAwB,CAqF1B;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,OAAO,GAAE,IAAI,CAAC,+BAA+B,EAAE,SAAS,GAAG,WAAW,CAAM,GAC3E,OAAO,CAAC,MAAM,CAAC,CAQjB"}