sqlstack 1.0.3 → 1.0.5

package/dist/index.d.ts

@@ -9,4 +9,5 @@ export * from './decorators/defaults';
 export * from './decorators/resultShape';
 export * from './decorators/validateResult';
 export * from './decorators/transform';
+export * from './utils/dto';
 //# 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":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC"}

package/dist/index.js

@@ -25,4 +25,5 @@ __exportStar(require("./decorators/defaults"), exports);
 __exportStar(require("./decorators/resultShape"), exports);
 __exportStar(require("./decorators/validateResult"), exports);
 __exportStar(require("./decorators/transform"), exports);
+__exportStar(require("./utils/dto"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,gDAA8B;AAC9B,mDAAiC;AACjC,6CAA2B;AAC3B,6CAA2B;AAC3B,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC","sourcesContent":["export * from './binders/sqlBinder';\nexport * from './core/errors';\nexport * from './core/validator';\nexport * from './registry';\nexport * from './adapters';\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sDAAoC;AACpC,gDAA8B;AAC9B,mDAAiC;AACjC,6CAA2B;AAC3B,6CAA2B;AAC3B,2DAAyC;AACzC,qDAAmC;AACnC,wDAAsC;AACtC,2DAAyC;AACzC,8DAA4C;AAC5C,yDAAuC;AACvC,8CAA4B","sourcesContent":["export * from './binders/sqlBinder';\nexport * from './core/errors';\nexport * from './core/validator';\nexport * from './registry';\nexport * from './adapters';\nexport * from './decorators/queryBinder';\nexport * from './decorators/query';\nexport * from './decorators/defaults';\nexport * from './decorators/resultShape';\nexport * from './decorators/validateResult';\nexport * from './decorators/transform';\nexport * from './utils/dto';\n"]}

package/dist/utils/dto.d.ts

@@ -0,0 +1,16 @@
+type KV = Record<string, any>;
+export type NodeSpec = {
+    id: string;
+    name?: string;
+    [collectionKey: string]: any;
+};
+type DTOOptions = {
+    /** If true, return a single root (or null). If false, return an array of roots. Default: true */
+    single?: boolean;
+};
+/**
+ * Build a rows→tree transformer from a nested spec.
+ */
+export declare function DTO(spec: NodeSpec, opts?: DTOOptions): (rows: KV[]) => KV | KV[] | null;
+export {};
+//# sourceMappingURL=dto.d.ts.map

package/dist/utils/dto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.d.ts","sourceRoot":"","sources":["../../src/utils/dto.ts"],"names":[],"mappings":"AAAA,KAAK,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAE9B,MAAM,MAAM,QAAQ,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,CAAC,aAAa,EAAE,MAAM,GAAG,GAAG,CAAC;CAC9B,CAAC;AAEF,KAAK,UAAU,GAAG;IAChB,iGAAiG;IACjG,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AA6CF;;GAEG;AACH,wBAAgB,GAAG,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,GAAE,UAAe,IA4D7B,MAAM,EAAE,EAAE,sBAerC"}

package/dist/utils/dto.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DTO = DTO;
+const CHILD_INDEX = Symbol('childIndex');
+function setDeep(obj, path, value) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const k = parts[i];
+        if (cur[k] == null || typeof cur[k] !== 'object')
+            cur[k] = {};
+        cur = cur[k];
+    }
+    cur[parts[parts.length - 1]] = value;
+}
+function childCollections(spec) {
+    const out = [];
+    for (const key of Object.keys(spec)) {
+        if (key === 'id' || key === 'name')
+            continue;
+        const val = spec[key];
+        if (val && typeof val === 'object' && 'id' in val)
+            out.push([key, val]);
+    }
+    return out;
+}
+function ensureChildInfra(node, collectionKey) {
+    if (!node[collectionKey])
+        node[collectionKey] = [];
+    if (!node[CHILD_INDEX])
+        node[CHILD_INDEX] = {};
+    const idxBag = node[CHILD_INDEX];
+    if (!idxBag[collectionKey])
+        idxBag[collectionKey] = new Map();
+    return { arr: node[collectionKey], index: idxBag[collectionKey] };
+}
+function stripMeta(node) {
+    if (node && typeof node === 'object') {
+        // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+        delete node[CHILD_INDEX];
+        for (const k of Object.keys(node)) {
+            const v = node[k];
+            if (Array.isArray(v))
+                v.forEach(stripMeta);
+        }
+    }
+    return node;
+}
+/**
+ * Build a rows→tree transformer from a nested spec.
+ */
+function DTO(spec, opts = {}) {
+    const single = opts.single ?? false;
+    const mappingsCache = new WeakMap();
+    function getMappings(levelSpec) {
+        const cached = mappingsCache.get(levelSpec);
+        if (cached)
+            return cached;
+        const out = [];
+        for (const [k, v] of Object.entries(levelSpec)) {
+            if (k === 'id' || k === 'name')
+                continue;
+            if (typeof v === 'string')
+                out.push([k, v]);
+        }
+        mappingsCache.set(levelSpec, out);
+        return out;
+    }
+    function upsertAtLevel(rowsIndex, rowsOut, levelSpec, row) {
+        const nodeId = row[levelSpec.id];
+        if (nodeId == null)
+            return null;
+        let node = rowsIndex.get(nodeId);
+        if (!node) {
+            node = {
+                id: nodeId,
+                ...(levelSpec.name ? { name: row[levelSpec.name] } : {}),
+            };
+            for (const [target, source] of getMappings(levelSpec)) {
+                if (source in row)
+                    setDeep(node, target, row[source]);
+            }
+            rowsIndex.set(nodeId, node);
+            rowsOut.push(node);
+        }
+        return node;
+    }
+    function descend(parent, levelSpec, row) {
+        for (const [collectionKey, childSpec] of childCollections(levelSpec)) {
+            const childId = row[childSpec.id];
+            if (childId == null)
+                continue; // skip this branch for this row
+            const { arr, index } = ensureChildInfra(parent, collectionKey);
+            let child = index.get(childId);
+            if (!child) {
+                child = {
+                    id: childId,
+                    ...(childSpec.name ? { name: row[childSpec.name] } : {}),
+                };
+                for (const [target, source] of getMappings(childSpec)) {
+                    if (source in row)
+                        setDeep(child, target, row[source]);
+                }
+                index.set(childId, child);
+                arr.push(child);
+            }
+            // Recurse further for this child (it may host its own collections)
+            descend(child, childSpec, row);
+        }
+    }
+    return function transform(rows) {
+        if (!rows || rows.length === 0)
+            return single ? null : [];
+        const roots = [];
+        const rootIndex = new Map();
+        for (const row of rows) {
+            const root = upsertAtLevel(rootIndex, roots, spec, row);
+            if (!root)
+                continue;
+            descend(root, spec, row);
+        }
+        roots.forEach(stripMeta);
+        return single ? roots[0] ?? null : roots;
+    };
+}
+//# sourceMappingURL=dto.js.map

package/dist/utils/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../../src/utils/dto.ts"],"names":[],"mappings":"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","sourcesContent":["type KV = Record<string, any>;\n\nexport type NodeSpec = {\n  id: string;\n  name?: string;\n  // nested collections: { [collectionKey]: NodeSpec }\n  [collectionKey: string]: any;\n};\n\ntype DTOOptions = {\n  /** If true, return a single root (or null). If false, return an array of roots. Default: true */\n  single?: boolean;\n};\n\nconst CHILD_INDEX = Symbol('childIndex');\n\nfunction setDeep(obj: KV, path: string, value: any) {\n  const parts = path.split('.');\n  let cur: any = obj;\n  for (let i = 0; i < parts.length - 1; i++) {\n    const k = parts[i]!;\n    if (cur[k] == null || typeof cur[k] !== 'object') cur[k] = {};\n    cur = cur[k];\n  }\n  cur[parts[parts.length - 1]!] = value;\n}\n\nfunction childCollections(spec: NodeSpec): Array<[string, NodeSpec]> {\n  const out: Array<[string, NodeSpec]> = [];\n  for (const key of Object.keys(spec)) {\n    if (key === 'id' || key === 'name') continue;\n    const val = (spec as any)[key];\n    if (val && typeof val === 'object' && 'id' in val) out.push([key, val as NodeSpec]);\n  }\n  return out;\n}\n\nfunction ensureChildInfra(node: KV, collectionKey: string) {\n  if (!node[collectionKey]) node[collectionKey] = [];\n  if (!(node as any)[CHILD_INDEX]) (node as any)[CHILD_INDEX] = {} as Record<string, Map<any, KV>>;\n  const idxBag = (node as any)[CHILD_INDEX] as Record<string, Map<any, KV>>;\n  if (!idxBag[collectionKey]) idxBag[collectionKey] = new Map<any, KV>();\n  return { arr: node[collectionKey] as KV[], index: idxBag[collectionKey] as Map<any, KV> };\n}\n\nfunction stripMeta(node: KV) {\n  if (node && typeof node === 'object') {\n    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete\n    delete (node as any)[CHILD_INDEX];\n    for (const k of Object.keys(node)) {\n      const v = node[k];\n      if (Array.isArray(v)) v.forEach(stripMeta);\n    }\n  }\n  return node;\n}\n\n/**\n * Build a rows→tree transformer from a nested spec.\n */\nexport function DTO(spec: NodeSpec, opts: DTOOptions = {}) {\n  const single = opts.single ?? false;\n  type IndexMap = Map<any, KV>;\n  const mappingsCache = new WeakMap<NodeSpec, Array<[string, string]>>();\n\n  function getMappings(levelSpec: NodeSpec): Array<[string, string]> {\n    const cached = mappingsCache.get(levelSpec);\n    if (cached) return cached;\n    const out: Array<[string, string]> = [];\n    for (const [k, v] of Object.entries(levelSpec)) {\n      if (k === 'id' || k === 'name') continue;\n      if (typeof v === 'string') out.push([k, v]);\n    }\n    mappingsCache.set(levelSpec, out);\n    return out;\n  }\n\n  function upsertAtLevel(rowsIndex: IndexMap, rowsOut: KV[], levelSpec: NodeSpec, row: KV) {\n    const nodeId = row[levelSpec.id];\n    if (nodeId == null) return null;\n\n    let node = rowsIndex.get(nodeId);\n    if (!node) {\n      node = {\n        id: nodeId,\n        ...(levelSpec.name ? { name: row[levelSpec.name] } : {}),\n      };\n      for (const [target, source] of getMappings(levelSpec)) {\n        if (source in row) setDeep(node, target, (row as any)[source]);\n      }\n      rowsIndex.set(nodeId, node);\n      rowsOut.push(node);\n    }\n    return node;\n  }\n\n  function descend(parent: KV, levelSpec: NodeSpec, row: KV) {\n    for (const [collectionKey, childSpec] of childCollections(levelSpec)) {\n      const childId = row[childSpec.id];\n      if (childId == null) continue; // skip this branch for this row\n\n      const { arr, index } = ensureChildInfra(parent, collectionKey);\n      let child = index.get(childId);\n      if (!child) {\n        child = {\n          id: childId,\n          ...(childSpec.name ? { name: row[childSpec.name] } : {}),\n        };\n        for (const [target, source] of getMappings(childSpec)) {\n          if (source in row) setDeep(child, target, (row as any)[source]);\n        }\n        index.set(childId, child);\n        arr.push(child);\n      }\n\n      // Recurse further for this child (it may host its own collections)\n      descend(child, childSpec, row);\n    }\n  }\n\n  return function transform(rows: KV[]) {\n    if (!rows || rows.length === 0) return single ? null : [];\n\n    const roots: KV[] = [];\n    const rootIndex: IndexMap = new Map();\n\n    for (const row of rows) {\n      const root = upsertAtLevel(rootIndex, roots, spec, row);\n      if (!root) continue;\n      descend(root, spec, row);\n    }\n\n    roots.forEach(stripMeta);\n    return single ? roots[0] ?? null : roots;\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sqlstack",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "",
   "license": "ISC",
   "author": "",

package/readme.md

@@ -427,6 +427,62 @@ if (!Array.isArray(pgWrite) && pgWrite.returning) {
 }
 ```
 
+## DTO Helper
+
+Turn flat SQL rows into nested objects using a simple spec and the `@Transform` decorator.
+
+```ts
+import { DTO, Transform, Query, QueryBinder } from 'sqlstack';
+
+// Define a nesting spec using column names
+const toMuscleGroup = DTO(
+  {
+    id: 'group_id',
+    name: 'group_name',
+    muscles: {
+      id: 'muscle_id',
+      name: 'muscle_name',
+      exercises: {
+        id: 'exercise_id',
+        name: 'exercise_name',
+      },
+    },
+  },
+  { single: true } // default returns an array; set { single: true } to return a single root (or null)
+);
+
+@QueryBinder()
+class Repo {
+  @Transform(toMuscleGroup)
+  @Query({ sql: `
+    SELECT
+      g.id   AS group_id,   g.name   AS group_name,
+      m.id   AS muscle_id,  m.name   AS muscle_name,
+      e.id   AS exercise_id,e.name   AS exercise_name
+    FROM groups g
+    LEFT JOIN muscles m   ON m.group_id = g.id
+    LEFT JOIN exercises e ON e.muscle_id = m.id
+    WHERE g.id = :id
+    ORDER BY m.name, e.name
+  ` })
+  async getGroup(_a: { id: string }): Promise<any | null> { throw new Error('replaced'); }
+}
+```
+
+You can also project flat columns into nested properties directly in the spec:
+
+```ts
+// If a row has: { id: '1', muscle: 'biceps', group: 'arms' }
+const toSimple = DTO({ id: 'id', name: 'muscle', 'group.name': 'group' } as any, { single: true });
+// Result root: { name: 'biceps', group: { name: 'arms' } }
+```
+
+- Arbitrary depth: nest collections by adding objects under new keys.
+- Dedupe: nodes are de-duplicated by their `id` at each level.
+- Null-safe: branches with `NULL` child ids are skipped for that row.
+- Order: sibling order follows your SQL `ORDER BY`.
+- Mapping: put `'target.path': 'source_key'` entries directly in your spec to populate nested properties from flat columns.
+
 ## Underlying Connections
 
 Every `Database` exposes its driver via `conn` so you can drop down to the raw client when needed: