@venturekit/data 0.0.0-dev.20260312012510 → 0.0.0-dev.20260329102450

package/dist/query/index.d.ts

@@ -2,6 +2,47 @@
  * Query Module
  *
  * Provides database querying, result mapping, and transaction support.
+ *
+ * ## Result Mapping
+ *
+ * All queries automatically run through `mapResults()` which converts
+ * dot-notation column aliases into nested objects. For example:
+ *
+ * ```sql
+ * SELECT p.id, p.title, u.id AS "author.id", u.name AS "author.name"
+ * FROM posts p JOIN users u ON u.id = p.author_id
+ * ```
+ *
+ * Returns: `[{ id: '1', title: 'Hello', author: { id: '5', name: 'Alice' } }]`
+ *
+ * ## Custom Result Mappers
+ *
+ * The optional third argument to `query()` lets you transform the mapped rows
+ * into any shape. The mapper receives the already-nested rows (after dot-notation
+ * expansion) and must return the final value:
+ *
+ * ```typescript
+ * // Extract a single column
+ * const titles = await query<string[]>(
+ *   'SELECT title FROM posts',
+ *   [],
+ *   (rows) => rows.map(r => r.title as string),
+ * );
+ *
+ * // Return a single row or null
+ * const post = await query<Post | null>(
+ *   'SELECT * FROM posts WHERE id = $1',
+ *   [id],
+ *   (rows) => (rows[0] as Post) ?? null,
+ * );
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Throws the underlying `pg` driver error on connection/query failures.
+ * - If `resultsMapper` throws, that error propagates unchanged.
+ * - An empty result set is **not** an error — it returns `[]` (or whatever
+ *   your mapper produces for an empty array).
  */
 import type { ResultsMapper } from './transaction.js';
 export { getPool } from './pool.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACvD,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAKZ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACvD,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,OAAO,EAAE,EACvB,aAAa,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAKZ"}

package/dist/query/index.js

@@ -2,6 +2,47 @@
  * Query Module
  *
  * Provides database querying, result mapping, and transaction support.
+ *
+ * ## Result Mapping
+ *
+ * All queries automatically run through `mapResults()` which converts
+ * dot-notation column aliases into nested objects. For example:
+ *
+ * ```sql
+ * SELECT p.id, p.title, u.id AS "author.id", u.name AS "author.name"
+ * FROM posts p JOIN users u ON u.id = p.author_id
+ * ```
+ *
+ * Returns: `[{ id: '1', title: 'Hello', author: { id: '5', name: 'Alice' } }]`
+ *
+ * ## Custom Result Mappers
+ *
+ * The optional third argument to `query()` lets you transform the mapped rows
+ * into any shape. The mapper receives the already-nested rows (after dot-notation
+ * expansion) and must return the final value:
+ *
+ * ```typescript
+ * // Extract a single column
+ * const titles = await query<string[]>(
+ *   'SELECT title FROM posts',
+ *   [],
+ *   (rows) => rows.map(r => r.title as string),
+ * );
+ *
+ * // Return a single row or null
+ * const post = await query<Post | null>(
+ *   'SELECT * FROM posts WHERE id = $1',
+ *   [id],
+ *   (rows) => (rows[0] as Post) ?? null,
+ * );
+ * ```
+ *
+ * ## Error Handling
+ *
+ * - Throws the underlying `pg` driver error on connection/query failures.
+ * - If `resultsMapper` throws, that error propagates unchanged.
+ * - An empty result set is **not** an error — it returns `[]` (or whatever
+ *   your mapper produces for an empty array).
  */
 import { getPool } from './pool.js';
 import { mapResults } from './mapper.js';

package/dist/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAU,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,QAAgB,EAChB,WAAuB,EACvB,aAAgC;IAEhC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC;AACxE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAU,MAAM,aAAa,CAAC;AAGjD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,kBAAkB,CAAC;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,QAAgB,EAChB,WAAuB,EACvB,aAAgC;IAEhC,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IACvB,MAAM,GAAG,GAAgB,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpC,OAAO,aAAa,CAAC,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAsB,CAAC;AACxE,CAAC"}

package/dist/query/mapper.d.ts

@@ -2,13 +2,61 @@
  * Result Mapper
  *
  * Maps flat database rows with dot-notation column aliases
- * into nested objects.
+ * into nested objects. This is applied automatically by `query()`.
  *
- * Example:
- *   { "id": 1, "author.id": 5, "author.name": "Alice" }
- *   becomes
- *   { id: 1, author: { id: 5, name: "Alice" } }
+ * ## How it works
+ *
+ * Column aliases containing dots are split and turned into nested objects:
+ *
+ * ```
+ * { "id": 1, "author.id": 5, "author.name": "Alice" }
+ * // becomes
+ * { id: 1, author: { id: 5, name: "Alice" } }
+ * ```
+ *
+ * Deeper nesting is also supported:
+ *
+ * ```
+ * { "author.address.city": "Paris" }
+ * // becomes
+ * { author: { address: { city: "Paris" } } }
+ * ```
+ *
+ * Columns **without** dots are passed through unchanged.
+ *
+ * ## Important notes
+ *
+ * - `mapResults([])` returns `[]` (empty array is a no-op).
+ * - `null` / `undefined` column values are preserved as-is in the output.
+ * - If a dot-notation key conflicts with a plain key (e.g. both `author`
+ *   and `author.id` exist), the nested object wins and the plain value
+ *   is overwritten. Use unambiguous aliases to avoid this.
+ */
+/**
+ * Map a single flat row with dot-notation keys into a nested object.
+ *
+ * @example
+ * ```typescript
+ * mapRow({ id: 1, 'author.id': 5, 'author.name': 'Alice' });
+ * // => { id: 1, author: { id: 5, name: 'Alice' } }
+ * ```
  */
 export declare function mapRow(row: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Map an array of flat database rows into nested objects.
+ *
+ * Returns an empty array when given `null`, `undefined`, or `[]`.
+ * This is called automatically by `query()` — you only need to call
+ * it directly if you are processing raw `pg` results yourself.
+ *
+ * @example
+ * ```typescript
+ * import { mapResults } from '@venturekit/data';
+ *
+ * const raw = await pool.query('SELECT p.id, u.name AS "author.name" FROM ...');
+ * const nested = mapResults(raw.rows);
+ * // => [{ id: 1, author: { name: 'Alice' } }, ...]
+ * ```
+ */
 export declare function mapResults(rows: Record<string, unknown>[]): Record<string, unknown>[];
 //# sourceMappingURL=mapper.d.ts.map

package/dist/query/mapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../src/query/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwB5E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAGrF"}
+{"version":3,"file":"mapper.d.ts","sourceRoot":"","sources":["../../src/query/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwB5E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAGrF"}

package/dist/query/mapper.js

@@ -2,12 +2,44 @@
  * Result Mapper
  *
  * Maps flat database rows with dot-notation column aliases
- * into nested objects.
+ * into nested objects. This is applied automatically by `query()`.
  *
- * Example:
- *   { "id": 1, "author.id": 5, "author.name": "Alice" }
- *   becomes
- *   { id: 1, author: { id: 5, name: "Alice" } }
+ * ## How it works
+ *
+ * Column aliases containing dots are split and turned into nested objects:
+ *
+ * ```
+ * { "id": 1, "author.id": 5, "author.name": "Alice" }
+ * // becomes
+ * { id: 1, author: { id: 5, name: "Alice" } }
+ * ```
+ *
+ * Deeper nesting is also supported:
+ *
+ * ```
+ * { "author.address.city": "Paris" }
+ * // becomes
+ * { author: { address: { city: "Paris" } } }
+ * ```
+ *
+ * Columns **without** dots are passed through unchanged.
+ *
+ * ## Important notes
+ *
+ * - `mapResults([])` returns `[]` (empty array is a no-op).
+ * - `null` / `undefined` column values are preserved as-is in the output.
+ * - If a dot-notation key conflicts with a plain key (e.g. both `author`
+ *   and `author.id` exist), the nested object wins and the plain value
+ *   is overwritten. Use unambiguous aliases to avoid this.
+ */
+/**
+ * Map a single flat row with dot-notation keys into a nested object.
+ *
+ * @example
+ * ```typescript
+ * mapRow({ id: 1, 'author.id': 5, 'author.name': 'Alice' });
+ * // => { id: 1, author: { id: 5, name: 'Alice' } }
+ * ```
  */
 export function mapRow(row) {
     const mapped = {};
@@ -31,6 +63,22 @@ export function mapRow(row) {
     }
     return mapped;
 }
+/**
+ * Map an array of flat database rows into nested objects.
+ *
+ * Returns an empty array when given `null`, `undefined`, or `[]`.
+ * This is called automatically by `query()` — you only need to call
+ * it directly if you are processing raw `pg` results yourself.
+ *
+ * @example
+ * ```typescript
+ * import { mapResults } from '@venturekit/data';
+ *
+ * const raw = await pool.query('SELECT p.id, u.name AS "author.name" FROM ...');
+ * const nested = mapResults(raw.rows);
+ * // => [{ id: 1, author: { name: 'Alice' } }, ...]
+ * ```
+ */
 export function mapResults(rows) {
     if (!rows || rows.length === 0)
         return [];

package/dist/query/mapper.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapper.js","sourceRoot":"","sources":["../../src/query/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,UAAU,MAAM,CAAC,GAA4B;IACjD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,OAAO,GAA4B,MAAM,CAAC;YAC9C,IAAI,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAE1B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACnB,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrB,CAAC;gBACD,OAAO,GAAG,OAAO,CAAC,IAAI,CAA4B,CAAC;gBACnD,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YACxB,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAA+B;IACxD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"mapper.js","sourceRoot":"","sources":["../../src/query/mapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAC,GAA4B;IACjD,MAAM,MAAM,GAA4B,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC7B,IAAI,OAAO,GAA4B,MAAM,CAAC;YAC9C,IAAI,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YAE1B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;oBACnB,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACrB,CAAC;gBACD,OAAO,GAAG,OAAO,CAAC,IAAI,CAA4B,CAAC;gBACnD,IAAI,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;YACxB,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACxB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACtB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,UAAU,CAAC,IAA+B;IACxD,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAC1C,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venturekit/data",
-  "version": "0.0.0-dev.20260312012510",
+  "version": "0.0.0-dev.20260329102450",
   "description": "Database and data layer for VentureKit",
   "type": "module",
   "main": "./dist/index.js",
@@ -25,7 +25,7 @@
     }
   },
   "dependencies": {
-    "@venturekit/core": "0.0.0-dev.20260312012510",
+    "@venturekit/core": "0.0.0-dev.20260329102450",
     "pg": "^8.12.0"
   },
   "devDependencies": {