@ingram-tech/nk-db 0.8.0 → 0.9.0

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+/** SQLSTATE `23505` — `unique_violation`. */
+export declare const PG_UNIQUE_VIOLATION = "23505";
+/**
+ * True when `error`, or anything in its `.cause` chain, is a Postgres error
+ * whose SQLSTATE equals `code`.
+ *
+ * Prefer `INSERT … ON CONFLICT` over catch-and-branch where you can (it avoids
+ * the pooled-connection-destroy footgun — see `docs/db-package.md`), but use
+ * this for the cases that genuinely must inspect the failure.
+ */
+export declare const isPgError: (error: unknown, code: string) => boolean;
+/** Convenience for the most common check: a `23505` unique violation. */
+export declare const isUniqueViolation: (error: unknown) => boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAKA,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,UAAU,CAAC;AAE3C;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,EAAE,MAAM,MAAM,KAAG,OASxD,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,OACb,CAAC"}

package/dist/errors.js

@@ -0,0 +1,27 @@
+// Inspect Postgres driver errors by SQLSTATE without hand-rolling the `.cause`
+// chain walk at every call site. `pg` puts the SQLSTATE on `error.code`, but
+// wrappers (Drizzle, our own helpers) often re-throw with the original error
+// nested under `.cause`, so a flat `err.code === …` check silently misses it.
+/** SQLSTATE `23505` — `unique_violation`. */
+export const PG_UNIQUE_VIOLATION = "23505";
+/**
+ * True when `error`, or anything in its `.cause` chain, is a Postgres error
+ * whose SQLSTATE equals `code`.
+ *
+ * Prefer `INSERT … ON CONFLICT` over catch-and-branch where you can (it avoids
+ * the pooled-connection-destroy footgun — see `docs/db-package.md`), but use
+ * this for the cases that genuinely must inspect the failure.
+ */
+export const isPgError = (error, code) => {
+    let current = error;
+    while (current !== null && current !== undefined) {
+        if (typeof current === "object" && "code" in current && current.code === code) {
+            return true;
+        }
+        current = current instanceof Error ? current.cause : undefined;
+    }
+    return false;
+};
+/** Convenience for the most common check: a `23505` unique violation. */
+export const isUniqueViolation = (error) => isPgError(error, PG_UNIQUE_VIOLATION);
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAE9E,6CAA6C;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,KAAc,EAAE,IAAY,EAAW,EAAE;IAClE,IAAI,OAAO,GAAY,KAAK,CAAC;IAC7B,OAAO,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAClD,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,MAAM,IAAI,OAAO,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;YAC/E,OAAO,IAAI,CAAC;QACb,CAAC;QACD,OAAO,GAAG,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAChE,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC,CAAC;AAEF,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAc,EAAW,EAAE,CAC5D,SAAS,CAAC,KAAK,EAAE,mBAAmB,CAAC,CAAC"}

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { pgNumericToNumber, pgTimestampToIso } from "./coerce.js";
 export { createDb, withRlsTransaction } from "./drizzle.js";
+export { isPgError, isUniqueViolation, PG_UNIQUE_VIOLATION } from "./errors.js";
 export { type DbEnv, dbEnv, getDatabaseUrl, isConfigured } from "./keys.js";
 export { type CreatePoolConfig, createPool } from "./pool.js";
-export { createQueries, type PoolQueries, type Queries } from "./queries.js";
+export { createQueries, parseMaybeRow, parseOneRow, parseRows, type PoolQueries, type Queries, type RowsResult, } from "./queries.js";
 export { RLS_CLAIMS_SETTING, RLS_DEFAULT_ROLE, type ResolvedRlsConfig, type RlsClaims, type RlsOptions, resolveRlsConfig, rlsPreamble, } from "./rls.js";
 export { configureTimestampsAsStrings } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,gBAAgB,EAChB,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,KAAK,gBAAgB,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EACN,aAAa,EACb,aAAa,EACb,WAAW,EACX,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,UAAU,GACf,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,gBAAgB,EAChB,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -3,9 +3,10 @@
 // production bundle.
 export { pgNumericToNumber, pgTimestampToIso } from "./coerce.js";
 export { createDb, withRlsTransaction } from "./drizzle.js";
+export { isPgError, isUniqueViolation, PG_UNIQUE_VIOLATION } from "./errors.js";
 export { dbEnv, getDatabaseUrl, isConfigured } from "./keys.js";
 export { createPool } from "./pool.js";
-export { createQueries } from "./queries.js";
+export { createQueries, parseMaybeRow, parseOneRow, parseRows, } from "./queries.js";
 export { RLS_CLAIMS_SETTING, RLS_DEFAULT_ROLE, resolveRlsConfig, rlsPreamble, } from "./rls.js";
 export { configureTimestampsAsStrings } from "./types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,qBAAqB;AAErB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAc,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAyB,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAkC,MAAM,cAAc,CAAC;AAC7E,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAIhB,gBAAgB,EAChB,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,8EAA8E;AAC9E,qBAAqB;AAErB,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAc,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAyB,UAAU,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EACN,aAAa,EACb,aAAa,EACb,WAAW,EACX,SAAS,GAIT,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAIhB,gBAAgB,EAChB,WAAW,GACX,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC"}

package/dist/queries.d.ts

@@ -1,15 +1,53 @@
 import type { Pool, QueryResultRow } from "pg";
+import { z } from "zod";
 import { type RlsClaims, type RlsOptions } from "./rls.js";
+/**
+ * A raw result shaped like pg's `QueryResult` or Drizzle's `tx.execute()` output
+ * — just the `rows`. Consumed by {@link parseRows} / {@link parseMaybeRow} /
+ * {@link parseOneRow}, which validate that array against a Zod schema.
+ */
+export interface RowsResult {
+    rows: readonly unknown[];
+}
 export interface Queries {
-    /** Run a query and return all rows. */
-    query: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T[]>;
+    /**
+     * Run a query and return all rows. Pass a Zod row `schema` as the third
+     * argument to validate (and coerce) every row instead of trusting a `<T>`
+     * cast — the schema is also where `numeric`/timestamp coercion belongs
+     * (`z.coerce.number()`, an ISO transform), per the no-`as`-on-external-input
+     * rule.
+     */
+    query: {
+        <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<T[]>;
+        <S extends z.ZodType>(text: string, params: unknown[] | undefined, schema: S): Promise<z.output<S>[]>;
+    };
     /** Run a query expected to return at most one row; `null` when none. */
-    maybeOne: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T | null>;
+    maybeOne: {
+        <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<T | null>;
+        <S extends z.ZodType>(text: string, params: unknown[] | undefined, schema: S): Promise<z.output<S> | null>;
+    };
     /** Run a query that must return exactly one row; throws otherwise. */
-    one: <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]) => Promise<T>;
+    one: {
+        <T extends QueryResultRow = QueryResultRow>(text: string, params?: unknown[]): Promise<T>;
+        <S extends z.ZodType>(text: string, params: unknown[] | undefined, schema: S): Promise<z.output<S>>;
+    };
     /** Run a write and return the affected row count. */
     execute: (text: string, params?: unknown[]) => Promise<number>;
 }
+/**
+ * Validate the `rows` of a raw result (a pg `QueryResult` or the output of
+ * Drizzle's `tx.execute()`) against a Zod row schema, returning the parsed rows.
+ *
+ * This is the result-side counterpart to {@link Queries.query}'s `schema` arg,
+ * for the Drizzle RLS path: inside `withRlsTransaction`, `tx.execute()` hands
+ * back an untyped `{ rows }`, and this gives it the same validated/coerced
+ * result the pool helpers have. The schema doubles as the coercion layer.
+ */
+export declare const parseRows: <S extends z.ZodType>(result: RowsResult, schema: S) => z.output<S>[];
+/** Like {@link parseRows} but for at most one row; `null` when none. */
+export declare const parseMaybeRow: <S extends z.ZodType>(result: RowsResult, schema: S) => z.output<S> | null;
+/** Like {@link parseRows} but requires exactly one row; throws otherwise. */
+export declare const parseOneRow: <S extends z.ZodType>(result: RowsResult, schema: S) => z.output<S>;
 export interface PoolQueries extends Queries {
     /**
      * Run `fn` inside a single transaction on a dedicated client (`begin` /

package/dist/queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAc,cAAc,EAAE,MAAM,IAAI,CAAC;AAC3D,OAAO,EACN,KAAK,SAAS,EACd,KAAK,UAAU,EAGf,MAAM,UAAU,CAAC;AAKlB,MAAM,WAAW,OAAO;IACvB,uCAAuC;IACvC,KAAK,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAChD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAClB,wEAAwE;IACxE,QAAQ,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EACnD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,sEAAsE;IACtE,GAAG,EAAE,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,EAC9C,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,OAAO,EAAE,KACd,OAAO,CAAC,CAAC,CAAC,CAAC;IAChB,qDAAqD;IACrD,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC/D;AAoCD,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC3C;;;;;OAKG;IACH,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3D;;;;;;;OAOG;IACH,OAAO,EAAE,CAAC,CAAC,EACV,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,EAC/B,OAAO,CAAC,EAAE,UAAU,KAChB,OAAO,CAAC,CAAC,CAAC,CAAC;CAChB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,WAkC1C,CAAC"}
+{"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../src/queries.ts"],"names":[],"mappings":"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"}

package/dist/queries.js

@@ -1,29 +1,58 @@
 import { resolveRlsConfig, rlsPreamble, } from "./rls.js";
 const bind = (executor) => {
-    const query = async (text, params = []) => {
+    async function query(text, params = [], schema) {
         const result = await executor.query(text, params);
-        return result.rows;
-    };
-    const maybeOne = async (text, params = []) => {
-        const rows = await query(text, params);
-        return rows[0] ?? null;
-    };
-    const one = async (text, params = []) => {
-        const rows = await query(text, params);
-        const row = rows[0];
-        if (!row)
+        return schema ? result.rows.map((row) => schema.parse(row)) : result.rows;
+    }
+    async function maybeOne(text, params = [], schema) {
+        const result = await executor.query(text, params);
+        const first = result.rows[0];
+        if (first === undefined)
+            return null;
+        return schema ? schema.parse(first) : first;
+    }
+    async function one(text, params = [], schema) {
+        const result = await executor.query(text, params);
+        if (result.rows.length === 0) {
             throw new Error("Expected exactly one row, got none");
-        if (rows.length > 1) {
-            throw new Error(`Expected exactly one row, got ${rows.length}`);
         }
-        return row;
-    };
+        if (result.rows.length > 1) {
+            throw new Error(`Expected exactly one row, got ${result.rows.length}`);
+        }
+        const row = result.rows[0];
+        return schema ? schema.parse(row) : row;
+    }
     const execute = async (text, params = []) => {
         const result = await executor.query(text, params);
         return result.rowCount ?? 0;
     };
     return { query, maybeOne, one, execute };
 };
+/**
+ * Validate the `rows` of a raw result (a pg `QueryResult` or the output of
+ * Drizzle's `tx.execute()`) against a Zod row schema, returning the parsed rows.
+ *
+ * This is the result-side counterpart to {@link Queries.query}'s `schema` arg,
+ * for the Drizzle RLS path: inside `withRlsTransaction`, `tx.execute()` hands
+ * back an untyped `{ rows }`, and this gives it the same validated/coerced
+ * result the pool helpers have. The schema doubles as the coercion layer.
+ */
+export const parseRows = (result, schema) => result.rows.map((row) => schema.parse(row));
+/** Like {@link parseRows} but for at most one row; `null` when none. */
+export const parseMaybeRow = (result, schema) => {
+    const first = result.rows[0];
+    return first === undefined ? null : schema.parse(first);
+};
+/** Like {@link parseRows} but requires exactly one row; throws otherwise. */
+export const parseOneRow = (result, schema) => {
+    if (result.rows.length === 0) {
+        throw new Error("Expected exactly one row, got none");
+    }
+    if (result.rows.length > 1) {
+        throw new Error(`Expected exactly one row, got ${result.rows.length}`);
+    }
+    return schema.parse(result.rows[0]);
+};
 /**
  * Bind the raw-SQL helpers (`query` / `one` / `maybeOne` / `execute` / `withTx`)
  * to a pool. Signatures match what apps hand-rolled, so adopting

package/dist/queries.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ingram-tech/nk-db",
-	"version": "0.8.0",
+	"version": "0.9.0",
 	"description": "The Ingram Postgres data layer: one TLS-aware pg pool, raw-SQL helpers, Drizzle wiring, and a PGlite (no-Docker) dev/test harness for Next.js sites.",
 	"license": "MIT",
 	"type": "module",