linkgress-orm 0.0.3 → 0.1.1

package/README.md

@@ -9,14 +9,14 @@ A type-safe ORM for PostgreSQL and TypeScript with automatic type inference and
 
 **LINQ-Inspired Query Syntax:** The query API is designed to feel familiar to developers coming from C# LINQ, with chainable methods like `select()`, `where()`, `orderBy()`, and `groupBy()`. You also get magic SQL string interpolation for when you need raw SQL power without sacrificing type safety.
 
-**PostgreSQL-First Philosophy:** While other ORMs aim high and try to support all platforms, Linkgress is built exclusively for PostgreSQL. This allows it to leverage PostgreSQL's advanced features to the maximum—particularly in how collections and aggregations are retrieved using CTEs, JSON aggregations, and native PostgreSQL optimizations.
+**PostgreSQL-First Philosophy:** While other ORMs aim high and try to support all platforms, Linkgress is built exclusively for PostgreSQL. This allows it to leverage PostgreSQL's advanced features to the maximum—particularly in how collections and aggregations are retrieved using CTEs, LATERAL joins, JSON aggregations, and native PostgreSQL optimizations.
 
 ## Features
 
 - **Entity-First Approach** - Define entities with `DbColumn<T>`, no decorators needed
 - **Fluent Configuration API** - Intuitive `DbContext` pattern with method chaining
 - **Automatic Type Inference** - Full TypeScript support without manual type annotations
-- **Nested Collection Queries** - Query one-to-many relationships with automatic CTE optimization
+- **Nested Collection Queries** - Query one-to-many relationships with CTE, LATERAL, or temp table strategies
 - **Type-Safe Aggregations** - `count()`, `sum()`, `max()`, `min()` return proper types
 - **Powerful Filtering** - Type-checked query conditions
 - **Transaction Support** - Safe, type-checked transactions
@@ -168,7 +168,7 @@ Array<{
 - **[Insert/Update/Upsert/BULK](./docs/guides/insert-update-guide.md)** - Insert, update, delete, and bulk operations
 
 ### Advanced
-- **[Collection Strategies](./docs/collection-strategies.md)** - JSONB vs temp table strategies, performance optimization, and multi-statement execution
+- **[Collection Strategies](./docs/collection-strategies.md)** - CTE, LATERAL, and temp table strategies for one-to-many queries
 - **[Subqueries](./docs/guides/subquery-guide.md)** - Using subqueries in your queries
 - **[Custom Types](./docs/guides/schema-configuration.md#custom-types)** - Create custom type mappers
 

package/dist/entity/db-column.d.ts

@@ -22,10 +22,47 @@ export declare class DbColumn<TValue> {
      */
     valueOf(): TValue;
 }
+/**
+ * Type helper to detect if a type is a class instance (has prototype methods)
+ * vs a plain data object. See conditions.ts for detailed explanation.
+ * Excludes DbColumn and SqlFragment which have valueOf but are not value types.
+ */
+type IsClassInstance<T> = T extends {
+    __isDbColumn: true;
+} ? false : T extends {
+    mapWith: any;
+    as: any;
+    buildSql: any;
+} ? false : T extends {
+    valueOf(): infer V;
+} ? V extends T ? true : V extends number | string | boolean | bigint | symbol ? true : false : false;
+/**
+ * Check for types with known class method signatures
+ */
+type HasClassMethods<T> = T extends {
+    getTime(): number;
+} ? true : T extends {
+    size: number;
+    has(value: any): boolean;
+} ? true : T extends {
+    byteLength: number;
+} ? true : T extends {
+    then(onfulfilled?: any): any;
+} ? true : T extends {
+    message: string;
+    name: string;
+} ? true : T extends {
+    exec(string: string): any;
+} ? true : false;
+/**
+ * Combined check for value types that should not be recursively processed
+ */
+type IsValueType<T> = IsClassInstance<T> extends true ? true : HasClassMethods<T> extends true ? true : false;
 /**
  * Type helper to unwrap DbColumn types to their underlying values
+ * Preserves class instances (Date, Map, Set, Temporal, etc.) as-is
  */
-export type UnwrapDbColumns<T> = T extends DbColumn<infer V> ? V : T extends object ? {
+export type UnwrapDbColumns<T> = T extends DbColumn<infer V> ? V : T extends object ? IsValueType<T> extends true ? T : {
     [K in keyof T]: T[K] extends DbColumn<infer V> ? V : T[K] extends (infer U)[] | undefined ? U extends DbEntity ? UnwrapDbColumns<U>[] : T[K] : T[K] extends DbEntity | undefined ? UnwrapDbColumns<NonNullable<T[K]>> : T[K];
 } : T;
 /**

package/dist/entity/db-column.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-column.d.ts","sourceRoot":"","sources":["../../src/entity/db-column.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,MAAM;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,YAAY,QAAQ;IAE7B,gBAAgB;IAChB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gBAAgB;IAChB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,gBAAgB;IAChB,QAAQ,CAAC,WAAW,EAAG,MAAM,CAAC;;IAG5B,gBAAgB;IAChB,UAAU,EAAE,MAAM;IAMpB;;;OAGG;IACH,OAAO,IAAI,MAAM;CAGlB;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GACxD,CAAC,GACD,CAAC,SAAS,MAAM,GAChB;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAC1C,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,GACpC,CAAC,SAAS,QAAQ,GAChB,eAAe,CAAC,CAAC,CAAC,EAAE,GACpB,CAAC,CAAC,CAAC,CAAC,GACN,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,SAAS,GACjC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAClC,CAAC,CAAC,CAAC,CAAC;CACT,GACD,CAAC,CAAC;AAEN;;GAEG;AACH,KAAK,gBAAgB,CAAC,CAAC,IACrB,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,GAC9B,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,IAAI,GAC1C,CAAC,SAAS,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,GAC1C,KAAK,CAAC;AAER;;GAEG;AACH,KAAK,sBAAsB,CAAC,CAAC,IAC3B,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,GAC3C,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAC/B,KAAK,CAAC;AAER;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;KAC/B,CAAC,IAAI,MAAM,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChG,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;AAErE;;GAEG;AACH,UAAU,QAAQ;CAEjB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,QAAQ,CAAC,GAAG,CAAC,CAE7D"}
+{"version":3,"file":"db-column.d.ts","sourceRoot":"","sources":["../../src/entity/db-column.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,QAAQ,CAAC,MAAM;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,YAAY,QAAQ;IAE7B,gBAAgB;IAChB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,gBAAgB;IAChB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC,gBAAgB;IAChB,QAAQ,CAAC,WAAW,EAAG,MAAM,CAAC;;IAG5B,gBAAgB;IAChB,UAAU,EAAE,MAAM;IAMpB;;;OAGG;IACH,OAAO,IAAI,MAAM;CAGlB;AAED;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,YAAY,EAAE,IAAI,CAAA;CAAE,GACtD,KAAK,GACL,CAAC,SAAS;IAAE,OAAO,EAAE,GAAG,CAAC;IAAC,EAAE,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,GAAG,CAAA;CAAE,GAClD,KAAK,GACL,CAAC,SAAS;IAAE,OAAO,IAAI,MAAM,CAAC,CAAA;CAAE,GAChC,CAAC,SAAS,CAAC,GACT,IAAI,GACJ,CAAC,SAAS,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GACrD,IAAI,GACJ,KAAK,GACP,KAAK,CAAC;AAEV;;GAEG;AACH,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,OAAO,IAAI,MAAM,CAAA;CAAE,GACrD,IAAI,GACJ,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAA;CAAE,GACpD,IAAI,GACJ,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAChC,IAAI,GACJ,CAAC,SAAS;IAAE,IAAI,CAAC,WAAW,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;CAAE,GAC1C,IAAI,GACJ,CAAC,SAAS;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C,IAAI,GACJ,CAAC,SAAS;IAAE,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,GACvC,IAAI,GACJ,KAAK,CAAC;AAEV;;GAEG;AACH,KAAK,WAAW,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,SAAS,IAAI,GACjD,IAAI,GACJ,eAAe,CAAC,CAAC,CAAC,SAAS,IAAI,GAC/B,IAAI,GACJ,KAAK,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GACxD,CAAC,GACD,CAAC,SAAS,MAAM,GAChB,WAAW,CAAC,CAAC,CAAC,SAAS,IAAI,GACzB,CAAC,GACD;KACG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAC1C,CAAC,GACD,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,SAAS,GACpC,CAAC,SAAS,QAAQ,GAChB,eAAe,CAAC,CAAC,CAAC,EAAE,GACpB,CAAC,CAAC,CAAC,CAAC,GACN,CAAC,CAAC,CAAC,CAAC,SAAS,QAAQ,GAAG,SAAS,GACjC,eAAe,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAClC,CAAC,CAAC,CAAC,CAAC;CACT,GACH,CAAC,CAAC;AAEN;;GAEG;AACH,KAAK,gBAAgB,CAAC,CAAC,IACrB,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,GAC9B,CAAC,SAAS,QAAQ,CAAC,GAAG,CAAC,GAAG,SAAS,GAAG,IAAI,GAC1C,CAAC,SAAS,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI,GAC1C,KAAK,CAAC;AAER;;GAEG;AACH,KAAK,sBAAsB,CAAC,CAAC,IAC3B,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC,GAC3C,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAC/B,KAAK,CAAC;AAER;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;KAC/B,CAAC,IAAI,MAAM,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAChG,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAC;AAErE;;GAEG;AACH,UAAU,QAAQ;CAEjB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,QAAQ,CAAC,GAAG,CAAC,CAE7D"}

package/dist/entity/db-column.js.map

@@ -1 +1 @@
-{"version":3,"file":"db-column.js","sourceRoot":"","sources":["../../src/entity/db-column.ts"],"names":[],"mappings":";;;AAgGA,gCAEC;AAlGD;;;;;GAKG;AACH,MAAa,QAAQ;IAanB;IACE,gBAAgB;IAChB,UAAkB;QAdpB,gBAAgB;QACP,iBAAY,GAAG,IAAI,CAAC;QAe3B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;CACF;AA5BD,4BA4BC;AA2DD;;GAEG;AACH,SAAgB,UAAU,CAAC,KAAU;IACnC,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;AAC3E,CAAC"}
+{"version":3,"file":"db-column.js","sourceRoot":"","sources":["../../src/entity/db-column.ts"],"names":[],"mappings":";;;AA8IA,gCAEC;AAhJD;;;;;GAKG;AACH,MAAa,QAAQ;IAanB;IACE,gBAAgB;IAChB,UAAkB;QAdpB,gBAAgB;QACP,iBAAY,GAAG,IAAI,CAAC;QAe3B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC;IACnC,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,MAAM,IAAI,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC1E,CAAC;CACF;AA5BD,4BA4BC;AAyGD;;GAEG;AACH,SAAgB,UAAU,CAAC,KAAU;IACnC,OAAO,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;AAC3E,CAAC"}