@simplysm/orm-common 13.0.98 → 13.0.100

package/docs/queryable.md

@@ -1,504 +1,155 @@
 # Queryable / Executable
 
-Type-safe query builder and stored procedure executor.
+## `Queryable`
 
-Source: `src/exec/queryable.ts`, `src/exec/executable.ts`, `src/exec/search-parser.ts`
-
-## Queryable
-
-Immutable chaining query builder for SELECT, INSERT, UPDATE, DELETE, and UPSERT operations. Each method returns a new `Queryable` instance.
+Type-safe query builder class. Constructs SELECT, INSERT, UPDATE, DELETE queries on tables/views in a chaining manner.
 
 ```typescript
-class Queryable<TData extends DataRecord, TFrom extends TableBuilder<any, any> | never> {
+class Queryable<
+  TData extends DataRecord,
+  TFrom extends TableBuilder<any, any> | never,
+> {
   constructor(readonly meta: QueryableMeta<TData>);
-  // ... chaining and execution methods
-}
-```
-
-### Column Selection
-
-#### select
-
-Specify columns to SELECT. Returns a new column structure.
-
-```typescript
-select<R extends Record<string, any>>(
-  fn: (columns: QueryableRecord<TData>) => R,
-): Queryable<UnwrapQueryableRecord<R>, never>;
-```
-
-```typescript
-db.user().select((u) => ({
-  userName: u.name,
-  userEmail: u.email,
-}))
-```
-
-#### distinct
-
-Apply DISTINCT to remove duplicate rows.
-
-```typescript
-distinct(): Queryable<TData, never>;
-```
-
-#### lock
-
-Apply row lock (FOR UPDATE) for exclusive access within a transaction.
-
-```typescript
-lock(): Queryable<TData, TFrom>;
-```
-
-### Pagination
-
-#### top
-
-Select only the top N rows (can be used without ORDER BY).
-
-```typescript
-top(count: number): Queryable<TData, TFrom>;
-```
-
-#### limit
-
-Set LIMIT/OFFSET for pagination. Requires a preceding `orderBy()`.
-
-```typescript
-limit(skip: number, take: number): Queryable<TData, TFrom>;
-```
-
-### Sorting
-
-#### orderBy
-
-Add an ORDER BY clause. Multiple calls apply in order.
-
-```typescript
-orderBy(
-  fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>,
-  orderBy?: "ASC" | "DESC",
-): Queryable<TData, TFrom>;
-```
-
-```typescript
-db.user()
-  .orderBy((u) => u.name)
-  .orderBy((u) => u.age, "DESC")
-```
-
-### Filtering
-
-#### where
-
-Add a WHERE condition. Multiple calls are combined with AND.
-
-```typescript
-where(
-  predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[],
-): Queryable<TData, TFrom>;
-```
-
-```typescript
-db.user()
-  .where((u) => [expr.eq(u.isActive, true)])
-  .where((u) => [expr.gte(u.age, 18)])
-```
-
-#### search
-
-Perform text search across multiple columns. Supports OR, +must, and -exclude syntax.
-
-```typescript
-search(
-  fn: (columns: QueryableRecord<TData>) => ExprUnit<string | undefined>[],
-  searchText: string,
-): Queryable<TData, TFrom>;
-```
-
-```typescript
-db.user()
-  .search((u) => [u.name, u.email], "John Doe -withdrawn")
-```
-
-### Grouping
-
-#### groupBy
-
-Add a GROUP BY clause.
-
-```typescript
-groupBy(
-  fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>[],
-): Queryable<TData, never>;
-```
-
-#### having
-
-Add a HAVING clause (filtering after GROUP BY).
-
-```typescript
-having(
-  predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[],
-): Queryable<TData, never>;
-```
-
-```typescript
-db.order()
-  .select((o) => ({
-    userId: o.userId,
-    totalAmount: expr.sum(o.amount),
-  }))
-  .groupBy((o) => [o.userId])
-  .having((o) => [expr.gte(o.totalAmount, 10000)])
-```
-
-### Joins
-
-#### join
-
-LEFT OUTER JOIN for 1:N relations (result added as array).
-
-```typescript
-join<A extends string, R extends DataRecord>(
-  as: A,
-  fn: (qr: JoinQueryable, cols: QueryableRecord<TData>) => Queryable<R, any>,
-): Queryable<TData & { [K in A]?: R[] }, TFrom>;
-```
-
-```typescript
-db.user()
-  .join("posts", (qr, u) =>
-    qr.from(Post).where((p) => [expr.eq(p.userId, u.id)])
-  )
-// Result: { id, name, posts: [{ id, title }, ...] }
-```
-
-#### joinSingle
-
-LEFT OUTER JOIN for N:1 or 1:1 relations (result added as single object).
-
-```typescript
-joinSingle<A extends string, R extends DataRecord>(
-  as: A,
-  fn: (qr: JoinQueryable, cols: QueryableRecord<TData>) => Queryable<R, any>,
-): Queryable<TData & { [K in A]?: R }, TFrom>;
-```
-
-```typescript
-db.post()
-  .joinSingle("user", (qr, p) =>
-    qr.from(User).where((u) => [expr.eq(u.id, p.userId)])
-  )
-// Result: { id, title, user: { id, name } | undefined }
-```
-
-#### include
-
-Automatically JOIN related tables based on FK/FKT relations defined in `TableBuilder`.
-
-```typescript
-include(fn: (item: PathProxy<TData>) => PathProxy<any>): Queryable<TData, TFrom>;
-```
-
-```typescript
-// Single relation
-db.post().include((p) => p.author)
-
-// Nested relation
-db.post().include((p) => p.author.company)
-
-// Multiple relations
-db.user()
-  .include((u) => u.company)
-  .include((u) => u.posts)
-```
-
-### Subqueries
-
-#### wrap
-
-Wrap the current Queryable as a subquery. Required when using `count()` after `distinct()` or `groupBy()`.
-
-```typescript
-wrap(): Queryable<TData, never>;
-```
-
-#### union (static)
-
-Combine multiple Queryables with UNION (removes duplicates). Requires at least 2 queryables.
-
-```typescript
-static union<TData extends DataRecord>(
-  ...queries: Queryable<TData, any>[]
-): Queryable<TData, never>;
-```
-
-```typescript
-const combined = Queryable.union(
-  db.user().where((u) => [expr.eq(u.type, "admin")]),
-  db.user().where((u) => [expr.eq(u.type, "manager")]),
-);
-```
-
-### Recursive CTE
-
-#### recursive
 
-Generate a recursive CTE (Common Table Expression) for hierarchical data.
-
-```typescript
-recursive(
-  fn: (qr: RecursiveQueryable<TData>) => Queryable<TData, any>,
-): Queryable<TData, never>;
-```
-
-```typescript
-db.employee()
-  .where((e) => [expr.null(e.managerId)])
-  .recursive((cte) =>
-    cte.from(Employee)
-      .where((e) => [expr.eq(e.managerId, e.self![0].id)])
-  )
-```
-
-### Execution Methods
-
-#### execute
-
-Execute a SELECT query and return the result array.
-
-```typescript
-async execute(): Promise<TData[]>;
-```
-
-#### single
-
-Return a single result. Throws if more than one result is returned.
-
-```typescript
-async single(): Promise<TData | undefined>;
-```
-
-#### first
-
-Return the first result (only the first even if multiple exist).
-
-```typescript
-async first(): Promise<TData | undefined>;
-```
-
-#### count
-
-Return the number of result rows. Cannot be called directly after `distinct()` or `groupBy()` -- use `wrap()` first.
-
-```typescript
-async count(
-  fn?: (cols: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>,
-): Promise<number>;
-```
-
-#### exists
-
-Check whether any data matching the conditions exists.
-
-```typescript
-async exists(): Promise<boolean>;
-```
-
-### Mutation Methods
-
-#### insert
-
-Execute an INSERT query. Automatically splits into chunks of 1000 for MSSQL.
-
-```typescript
-async insert(records: TFrom["$inferInsert"][]): Promise<void>;
-async insert<K extends keyof TFrom["$inferColumns"] & string>(
-  records: TFrom["$inferInsert"][],
-  outputColumns: K[],
-): Promise<Pick<TFrom["$inferColumns"], K>[]>;
-```
-
-```typescript
-// Simple insert
-await db.user().insert([{ name: "Alice", createdAt: DateTime.now() }]);
-
-// Insert with output
-const [inserted] = await db.user().insert(
-  [{ name: "Alice" }],
-  ["id"],
-);
-```
-
-#### insertIfNotExists
-
-INSERT only if no data matches the current WHERE condition.
-
-```typescript
-async insertIfNotExists(record: TFrom["$inferInsert"]): Promise<void>;
-async insertIfNotExists<K extends keyof TFrom["$inferColumns"] & string>(
-  record: TFrom["$inferInsert"],
-  outputColumns: K[],
-): Promise<Pick<TFrom["$inferColumns"], K>>;
-```
-
-#### insertInto
-
-INSERT INTO ... SELECT -- insert the current SELECT results into another table.
-
-```typescript
-async insertInto<TTable extends TableBuilder<DataToColumnBuilderRecord<TData>, any>>(
-  targetTable: TTable,
-): Promise<void>;
-async insertInto<TTable, TOut extends keyof TTable["$inferColumns"] & string>(
-  targetTable: TTable,
-  outputColumns: TOut[],
-): Promise<Pick<TData, TOut>[]>;
-```
-
-#### update
-
-Execute an UPDATE query.
-
-```typescript
-async update(
-  recordFwd: (cols: QueryableRecord<TData>) => QueryableWriteRecord<TFrom["$inferUpdate"]>,
-): Promise<void>;
-async update<K extends keyof TFrom["$columns"] & string>(
-  recordFwd: (cols: QueryableRecord<TData>) => QueryableWriteRecord<TFrom["$inferUpdate"]>,
-  outputColumns: K[],
-): Promise<Pick<TFrom["$columns"], K>[]>;
-```
-
-```typescript
-await db.user()
-  .where((u) => [expr.eq(u.id, 1)])
-  .update((u) => ({
-    name: expr.val("string", "New Name"),
-  }));
-```
-
-#### delete
-
-Execute a DELETE query.
-
-```typescript
-async delete(): Promise<void>;
-async delete<K extends keyof TFrom["$columns"] & string>(
-  outputColumns: K[],
-): Promise<Pick<TFrom["$columns"], K>[]>;
-```
-
-#### upsert
-
-Execute an UPSERT (UPDATE or INSERT) query.
-
-```typescript
-async upsert(
-  updateFn: (cols: QueryableRecord<TData>) => QueryableWriteRecord<TFrom["$inferUpdate"]>,
-): Promise<void>;
-async upsert<U extends QueryableWriteRecord<TFrom["$inferUpdate"]>>(
-  updateFn: (cols: QueryableRecord<TData>) => U,
-  insertFn: (updateRecord: U) => QueryableWriteRecord<TFrom["$inferInsert"]>,
-): Promise<void>;
-```
-
-```typescript
-// Same data for update and insert
-await db.user()
-  .where((u) => [expr.eq(u.email, "test@test.com")])
-  .upsert(() => ({
-    name: expr.val("string", "Test"),
-    email: expr.val("string", "test@test.com"),
-  }));
-
-// Different data for update vs insert
-await db.user()
-  .where((u) => [expr.eq(u.email, "test@test.com")])
-  .upsert(
-    () => ({ loginCount: expr.val("number", 1) }),
-    (update) => ({ ...update, email: expr.val("string", "test@test.com") }),
-  );
-```
-
-### DDL Helper
-
-#### switchFk
-
-Enable or disable FK constraints on the table (usable within a transaction).
-
-```typescript
-async switchFk(enabled: boolean): Promise<void>;
+  // SELECT / DISTINCT / LOCK
+  select<R extends Record<string, any>>(
+    fn: (columns: QueryableRecord<TData>) => R,
+  ): Queryable<UnwrapQueryableRecord<R>, never>;
+  distinct(): Queryable<TData, never>;
+  lock(): Queryable<TData, TFrom>;
+
+  // TOP / LIMIT
+  top(count: number): Queryable<TData, TFrom>;
+  limit(skip: number, take: number): Queryable<TData, TFrom>;
+
+  // ORDER BY
+  orderBy(
+    fn: (columns: QueryableRecord<TData>) => ExprUnit<ColumnPrimitive>,
+    orderBy?: "ASC" | "DESC",
+  ): Queryable<TData, TFrom>;
+
+  // WHERE
+  where(predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, TFrom>;
+  search(
+    fn: (columns: QueryableRecord<TData>) => ExprUnit<string | undefined>[],
+    searchText: string,
+  ): Queryable<TData, TFrom>;
+
+  // GROUP BY / HAVING
+  groupBy<R extends Record<string, any>>(
+    fn: (columns: QueryableRecord<TData>) => R,
+  ): Queryable<UnwrapQueryableRecord<R>, never>;
+  having(predicate: (columns: QueryableRecord<TData>) => WhereExprUnit[]): Queryable<TData, TFrom>;
+
+  // JOIN
+  join<TKey extends string, TJoinData extends DataRecord>(
+    key: TKey,
+    joinFn: (j: JoinQueryable) => Queryable<TJoinData, any>,
+    on?: (own: QueryableRecord<TData>, join: QueryableRecord<TJoinData>) => WhereExprUnit[],
+  ): Queryable<TData & { [K in TKey]?: TJoinData[] }, TFrom>;
+  joinSingle<TKey extends string, TJoinData extends DataRecord>(
+    key: TKey,
+    joinFn: (j: JoinQueryable) => Queryable<TJoinData, any>,
+    on?: (own: QueryableRecord<TData>, join: QueryableRecord<TJoinData>) => WhereExprUnit[],
+  ): Queryable<TData & { [K in TKey]?: TJoinData }, TFrom>;
+  include<TKey extends string & keyof TData>(key: TKey): Queryable<TData, TFrom>;
+
+  // RECURSIVE
+  recursive<TBaseData extends DataRecord>(
+    baseQueryFn: (q: Queryable<TData, TFrom>) => Queryable<TBaseData, any>,
+    recursiveBodyFn: (cte: RecursiveQueryable<TBaseData>) => Queryable<any, any>,
+  ): Queryable<TBaseData, never>;
+
+  // EXECUTE (SELECT)
+  execute(): Promise<TData[]>;
+  single(): Promise<TData | undefined>;
+  count(): Promise<number>;
+  exists(): Promise<boolean>;
+
+  // QueryDef generation
+  getSelectQueryDef(): SelectQueryDef;
+  getResultMeta(): ResultMeta;
+
+  // CUD (requires TFrom to be TableBuilder)
+  insert(records: TFrom["$inferInsert"][], options?: { overrideIdentity?: boolean }): Promise<TFrom["$inferColumns"][]>;
+  insertIfNotExists(record: TFrom["$inferInsert"][]): Promise<TFrom["$inferColumns"][]>;
+  insertInto(subQuery: Queryable<any, any>, options?: { overrideIdentity?: boolean }): Promise<TFrom["$inferColumns"][]>;
+  update(fn: (columns: QueryableRecord<TData>) => Partial<...>): Promise<TFrom["$inferColumns"][]>;
+  upsert(insertRecord: TFrom["$inferInsert"], updateFn: (columns: ...) => Partial<...>): Promise<TFrom["$inferColumns"][]>;
+  delete(): Promise<TFrom["$inferColumns"][]>;
+}
 ```
 
-### QueryDef Generators
-
-These methods return the raw `QueryDef` JSON AST without executing:
-
-- `getSelectQueryDef(): SelectQueryDef`
-- `getInsertQueryDef(records, outputColumns?): InsertQueryDef`
-- `getInsertIfNotExistsQueryDef(record, outputColumns?): InsertIfNotExistsQueryDef`
-- `getInsertIntoQueryDef(targetTable, outputColumns?): InsertIntoQueryDef`
-- `getUpdateQueryDef(recordFwd, outputColumns?): UpdateQueryDef`
-- `getDeleteQueryDef(outputColumns?): DeleteQueryDef`
-- `getUpsertQueryDef(updateRecordFn, insertRecordFn, outputColumns?): UpsertQueryDef`
-- `getResultMeta(outputColumns?): ResultMeta`
-
----
-
-## queryable (factory function)
-
-Create a Queryable factory function for a table or view. A new alias is assigned on each call.
-
-```typescript
-function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+### Key Methods
+
+| Method | Description |
+|--------|-------------|
+| `select()` | Specify columns to SELECT |
+| `distinct()` | Remove duplicate rows |
+| `lock()` | Apply row lock (FOR UPDATE) |
+| `top()` | Select only top N rows |
+| `limit()` | Set LIMIT/OFFSET for pagination (requires `orderBy()`) |
+| `orderBy()` | Add sorting condition (multiple calls apply in order) |
+| `where()` | Add WHERE condition (multiple calls combined with AND) |
+| `search()` | Perform text search with LIKE patterns |
+| `groupBy()` | Group results |
+| `having()` | Add HAVING condition |
+| `join()` | LEFT JOIN with 1:N result (array) |
+| `joinSingle()` | LEFT JOIN with 1:1 result (single object) |
+| `include()` | Include pre-defined relation from schema |
+| `recursive()` | Build recursive CTE query |
+| `execute()` | Execute SELECT and return results |
+| `single()` | Execute SELECT and return first result |
+| `count()` | Return record count |
+| `exists()` | Check if records exist |
+| `insert()` | INSERT records |
+| `insertIfNotExists()` | INSERT only if not exists |
+| `insertInto()` | INSERT from subquery |
+| `update()` | UPDATE matching records |
+| `upsert()` | INSERT or UPDATE |
+| `delete()` | DELETE matching records |
+
+## `queryable`
+
+Factory function to create a Queryable accessor for DbContext.
+
+```typescript
+function queryable<T extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
   db: DbContextBase,
-  tableOrView: TBuilder,
-  as?: string,
-): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder<any, any> ? TBuilder : never>;
+  builder: T,
+  alias?: string,
+): () => Queryable<T["$inferSelect"], T extends TableBuilder<any, any> ? T : never>;
 ```
 
----
-
-## getMatchedPrimaryKeys
+## `Executable`
 
-Match FK column array with the target table's PK and return PK column name array.
+Stored procedure execution wrapper class.
 
 ```typescript
-function getMatchedPrimaryKeys(
-  fkCols: string[],
-  targetTable: TableBuilder<any, any>,
-): string[];
-```
-
-Throws if FK/PK column count does not match.
-
----
-
-## Executable
+class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
+  constructor(
+    private readonly _db: DbContextBase,
+    private readonly _builder: ProcedureBuilder<TParams, TReturns>,
+  );
 
-Stored procedure execution wrapper.
+  getExecProcQueryDef(params?: InferColumnExprs<TParams>): {
+    type: "execProc";
+    procedure: { database?: string; schema?: string; name: string };
+    params?: Record<string, Expr>;
+  };
 
-```typescript
-class Executable<
-  TParams extends ColumnBuilderRecord,
-  TReturns extends ColumnBuilderRecord,
-> {
-  getExecProcQueryDef(params?: InferColumnExprs<TParams>): ExecProcQueryDef;
-  async execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
+  execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
 }
 ```
 
-```typescript
-const result = await db.getUserById().execute({ userId: 1n });
-```
+| Method | Description |
+|--------|-------------|
+| `getExecProcQueryDef()` | Generate procedure execution QueryDef |
+| `execute()` | Execute the stored procedure |
 
----
+## `executable`
 
-## executable (factory function)
-
-Create an Executable factory function for a procedure.
+Factory function to create an Executable accessor for DbContext.
 
 ```typescript
 function executable<
@@ -510,29 +161,14 @@ function executable<
 ): () => Executable<TParams, TReturns>;
 ```
 
----
-
-## parseSearchQuery
+## `parseSearchQuery`
 
-Parse a search query string into SQL LIKE patterns.
+Parse a search query string and convert to SQL LIKE patterns.
 
 ```typescript
 function parseSearchQuery(searchText: string): ParsedSearchQuery;
 ```
 
-### ParsedSearchQuery
-
-```typescript
-interface ParsedSearchQuery {
-  /** General search terms (OR condition) - LIKE pattern */
-  or: string[];
-  /** Required search terms (AND condition, + prefix or quotes) - LIKE pattern */
-  must: string[];
-  /** Excluded search terms (NOT condition, - prefix) - LIKE pattern */
-  not: string[];
-}
-```
-
 ### Search Syntax
 
 | Syntax | Meaning | Example |
@@ -543,36 +179,20 @@ interface ParsedSearchQuery {
 | `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
 | `*` | Wildcard | `app*` -> `app%` |
 
-### Escape Sequences
-
-| Input | Meaning |
-|-------|---------|
-| `\\` | Literal `\` |
-| `\*` | Literal `*` |
-| `\%` | Literal `%` |
-| `\"` | Literal `"` |
-| `\+` | Literal `+` |
-| `\-` | Literal `-` |
+## `ParsedSearchQuery`
 
-**Example:**
+Search query parsing result.
 
 ```typescript
-parseSearchQuery('apple "delicious fruit" -banana +strawberry')
-// {
-//   or: ["%apple%"],
-//   must: ["%delicious fruit%", "%strawberry%"],
-//   not: ["%banana%"]
-// }
+interface ParsedSearchQuery {
+  or: string[];
+  must: string[];
+  not: string[];
+}
 ```
 
----
-
-## Type Helpers
-
-| Type | Description |
-|------|-------------|
-| `QueryableRecord<TData>` | Maps `TData` fields to `ExprUnit` wrappers (for column references in callbacks) |
-| `QueryableWriteRecord<TData>` | Maps `TData` fields to `ExprInput` (for UPDATE/INSERT value callbacks) |
-| `NullableQueryableRecord<TData>` | Like `QueryableRecord` but all primitives are `| undefined` (LEFT JOIN null propagation) |
-| `UnwrapQueryableRecord<R>` | Reverse-transform from `QueryableRecord` back to `DataRecord` |
-| `PathProxy<TObject>` | Type-safe path proxy for `include()` -- only non-primitive fields are accessible |
+| Field | Type | Description |
+|-------|------|-------------|
+| `or` | `string[]` | General search terms (OR condition) - LIKE pattern |
+| `must` | `string[]` | Required search terms (AND condition, + prefix or quotes) - LIKE pattern |
+| `not` | `string[]` | Excluded search terms (NOT condition, - prefix) - LIKE pattern |