@simplysm/orm-common 13.0.100 → 14.0.4

package/docs/queryable.md

@@ -1,198 +1,236 @@
 # Queryable / Executable
 
-## `Queryable`
+Type-safe query builder and stored procedure executor.
 
-Type-safe query builder class. Constructs SELECT, INSERT, UPDATE, DELETE queries on tables/views in a chaining manner.
+## Queryable
+
+Chainable query builder class for constructing SELECT, INSERT, UPDATE, DELETE, and UPSERT queries against tables/views.
 
 ```typescript
-class Queryable<
-  TData extends DataRecord,
-  TFrom extends TableBuilder<any, any> | never,
-> {
+class Queryable<TData extends DataRecord, TFrom extends TableBuilder | never> {
   constructor(readonly meta: QueryableMeta<TData>);
-
-  // 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"][]>;
 }
 ```
 
-### 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.
+**Type Parameters:**
+
+| Parameter | Description |
+|---|---|
+| `TData` | Query result data type |
+| `TFrom` | Source table builder type. `never` for views/subqueries (no CUD operations). |
+
+### SELECT / Options
+
+| Method | Signature | Description |
+|---|---|---|
+| `select` | `(fn: (cols) => R) => Queryable<UnwrapQueryableRecord<R>, never>` | Project specific columns. Replaces the default column set. |
+| `distinct` | `() => Queryable<TData, never>` | Apply DISTINCT to remove duplicate rows. |
+| `lock` | `() => Queryable<TData, TFrom>` | Apply row lock (FOR UPDATE) within a transaction. |
+
+### Filtering
+
+| Method | Signature | Description |
+|---|---|---|
+| `where` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, TFrom>` | Add WHERE conditions. Multiple calls are combined with AND. |
+| `search` | `(fn: (cols) => ExprUnit<string>[], searchText: string) => Queryable<TData, TFrom>` | Full-text search across columns. Supports `+required`, `-excluded`, `"exact phrase"`, and `*` wildcards. See `parseSearchQuery`. |
+
+### Sorting / Pagination
+
+| Method | Signature | Description |
+|---|---|---|
+| `orderBy` | `(fn: (cols) => ExprUnit, orderBy?: "ASC" \| "DESC") => Queryable<TData, TFrom>` | Add ORDER BY. Multiple calls append in order. Default: ASC. |
+| `top` | `(count: number) => Queryable<TData, TFrom>` | Limit to N rows (works without ORDER BY). |
+| `limit` | `(skip: number, take: number) => Queryable<TData, TFrom>` | Pagination (OFFSET/LIMIT). Requires `orderBy()` first. |
+
+### Grouping
+
+| Method | Signature | Description |
+|---|---|---|
+| `groupBy` | `(fn: (cols) => ExprUnit[]) => Queryable<TData, never>` | GROUP BY columns. |
+| `having` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, never>` | HAVING filter (after GROUP BY). |
+
+### JOIN
+
+| Method | Signature | Description |
+|---|---|---|
+| `join` | `(as, fn: (qr, cols) => Queryable<R>) => Queryable<TData & { [as]?: R[] }, TFrom>` | LEFT OUTER JOIN (1:N). Result added as array property. |
+| `joinSingle` | `(as, fn: (qr, cols) => Queryable<R>) => Queryable<TData & { [as]?: R }, TFrom>` | LEFT OUTER JOIN (N:1 or 1:1). Result added as single object. |
+| `include` | `(fn: (item: PathProxy) => PathProxy) => Queryable<TData, TFrom>` | Auto-JOIN based on FK/relation definitions. Supports nested paths (e.g., `p.author.company`). |
+
+### Subquery / UNION / Recursive
+
+| Method | Signature | Description |
+|---|---|---|
+| `wrap` | `() => Queryable<TData, never>` | Wrap current query as subquery. Required before `count()` after `distinct()`/`groupBy()`. |
+| `static union` | `(...queries: Queryable[]) => Queryable<TData, never>` | Combine 2+ Queryables with UNION. |
+| `recursive` | `(fn: (cte: RecursiveQueryable) => Queryable) => Queryable<TData, never>` | Generate a recursive CTE (WITH RECURSIVE). For hierarchical data. |
+
+### Execution (SELECT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `execute` | `() => Promise<TData[]>` | Execute SELECT and return result array. |
+| `single` | `() => Promise<TData \| undefined>` | Return single result. Throws if more than one. |
+| `first` | `() => Promise<TData \| undefined>` | Return first result (even if multiple exist). |
+| `count` | `(fn?) => Promise<number>` | Return row count. Throws after `distinct()`/`groupBy()` (use `wrap()` first). |
+| `exists` | `() => Promise<boolean>` | Check if any matching data exists. |
+
+### Execution (INSERT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `insert` | `(records: TFrom["$inferInsert"][]) => Promise<void>` | Insert records. Auto-chunks at 1000 for MSSQL. |
+| `insert` | `(records, outputColumns: K[]) => Promise<Pick<...>[]>` | Insert and return specified output columns. |
+| `insertIfNotExists` | `(record: TFrom["$inferInsert"]) => Promise<void>` | Insert only if WHERE condition matches no rows. |
+| `insertIfNotExists` | `(record, outputColumns: K[]) => Promise<Pick<...>>` | Insert if not exists and return output columns. |
+| `insertInto` | `(targetTable: TableBuilder) => Promise<void>` | INSERT INTO ... SELECT from current query. |
+| `insertInto` | `(targetTable, outputColumns: K[]) => Promise<Pick<...>[]>` | INSERT INTO with output columns. |
+
+### Execution (UPDATE / DELETE)
+
+| Method | Signature | Description |
+|---|---|---|
+| `update` | `(recordFwd: (cols) => WriteRecord) => Promise<void>` | Update matching records. Use `expr.val()` for literal values. |
+| `update` | `(recordFwd, outputColumns: K[]) => Promise<Pick<...>[]>` | Update and return output columns. |
+| `delete` | `() => Promise<void>` | Delete matching records. |
+| `delete` | `(outputColumns: K[]) => Promise<Pick<...>[]>` | Delete and return output columns. |
+
+### Execution (UPSERT)
+
+| Method | Signature | Description |
+|---|---|---|
+| `upsert` | `(updateFn: (cols) => WriteRecord) => Promise<void>` | Update if exists, insert otherwise (same data). |
+| `upsert` | `(updateFn, insertFn) => Promise<void>` | Update/insert with different data. |
+| `upsert` | `(updateFn, insertFn?, outputColumns?: K[]) => Promise<Pick<...>[] \| void>` | Upsert with optional output columns. |
+
+### QueryDef Generators
+
+Each execution method has a corresponding `get*QueryDef` method:
+
+- `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`
+
+## QueryableRecord
+
+Maps data record fields to `ExprUnit` wrappers for type-safe expression building. Nested objects and arrays are recursively mapped.
 
 ```typescript
-function queryable<T extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
-  db: DbContextBase,
-  builder: T,
-  alias?: string,
-): () => Queryable<T["$inferSelect"], T extends TableBuilder<any, any> ? T : never>;
+type QueryableRecord<TData extends DataRecord> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive
+    ? ExprUnit<TData[K]>
+    : TData[K] extends (infer U)[]
+      ? U extends DataRecord ? QueryableRecord<U>[] : never
+      : TData[K] extends DataRecord ? QueryableRecord<TData[K]> : never;
+};
 ```
 
-## `Executable`
+## QueryableWriteRecord
+
+Maps data fields to `ExprInput` for write operations (INSERT/UPDATE).
+
+```typescript
+type QueryableWriteRecord<TData> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprInput<TData[K]> : never;
+};
+```
+
+## NullableQueryableRecord
+
+Same as `QueryableRecord` but all primitive fields include `| undefined` (for LEFT JOIN null propagation).
+
+```typescript
+type NullableQueryableRecord<TData extends DataRecord> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive
+    ? ExprUnit<TData[K] | undefined>
+    : /* recursive for nested records */;
+};
+```
+
+## getMatchedPrimaryKeys
+
+Returns the primary key columns of a target table matched to foreign key columns.
+
+```typescript
+function getMatchedPrimaryKeys(
+  fkCols: string[],
+  targetTable: TableBuilder<any, any>,
+): string[];
+```
+
+## Executable
 
 Stored procedure execution wrapper class.
 
 ```typescript
 class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
-  constructor(
-    private readonly _db: DbContextBase,
-    private readonly _builder: ProcedureBuilder<TParams, TReturns>,
-  );
-
-  getExecProcQueryDef(params?: InferColumnExprs<TParams>): {
-    type: "execProc";
-    procedure: { database?: string; schema?: string; name: string };
-    params?: Record<string, Expr>;
-  };
+  constructor(db: DbContextBase, builder: ProcedureBuilder<TParams, TReturns>);
 
+  getExecProcQueryDef(params?: InferColumnExprs<TParams>): ExecProcQueryDef;
   execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
 }
 ```
 
-| Method | Description |
-|--------|-------------|
-| `getExecProcQueryDef()` | Generate procedure execution QueryDef |
-| `execute()` | Execute the stored procedure |
+**Example:**
 
-## `executable`
+```typescript
+const result = await db.getUserById().execute({ userId: 1n });
+```
 
-Factory function to create an Executable accessor for DbContext.
+## executable
+
+Factory function that creates an `Executable` accessor for a `ProcedureBuilder`.
 
 ```typescript
-function executable<
-  TParams extends ColumnBuilderRecord,
-  TReturns extends ColumnBuilderRecord,
->(
+function executable<TParams, TReturns>(
   db: DbContextBase,
   builder: ProcedureBuilder<TParams, TReturns>,
 ): () => Executable<TParams, TReturns>;
 ```
 
-## `parseSearchQuery`
+## ParsedSearchQuery
+
+Result of `parseSearchQuery()`.
+
+```typescript
+interface ParsedSearchQuery {
+  or: string[];    // OR conditions (LIKE patterns)
+  must: string[];  // AND conditions (+ prefix or quoted)
+  not: string[];   // NOT conditions (- prefix)
+}
+```
+
+## parseSearchQuery
 
-Parse a search query string and convert to SQL LIKE patterns.
+Parses a search query string into SQL LIKE patterns.
 
 ```typescript
 function parseSearchQuery(searchText: string): ParsedSearchQuery;
 ```
 
-### Search Syntax
+**Search Syntax:**
 
 | Syntax | Meaning | Example |
-|--------|---------|---------|
-| `term1 term2` | OR (one of them) | `apple banana` |
+|---|---|---|
+| `term1 term2` | OR (match any) | `apple banana` |
 | `+term` | Required (AND) | `+apple +banana` |
 | `-term` | Excluded (NOT) | `apple -banana` |
-| `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
-| `*` | Wildcard | `app*` -> `app%` |
+| `"exact phrase"` | Exact phrase match (required) | `"delicious fruit"` |
+| `*` | Wildcard | `app*` produces `app%` |
 
-## `ParsedSearchQuery`
+**Escape Sequences:** `\\` (literal `\`), `\*`, `\%`, `\"`, `\+`, `\-`
 
-Search query parsing result.
+**Example:**
 
 ```typescript
-interface ParsedSearchQuery {
-  or: string[];
-  must: string[];
-  not: string[];
-}
-```
+parseSearchQuery('apple "delicious fruit" -banana +strawberry');
+// { or: ["%apple%"], must: ["%delicious fruit%", "%strawberry%"], not: ["%banana%"] }
 
-| 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 |
+parseSearchQuery('app* test');
+// { or: ["app%", "%test%"], must: [], not: [] }
+```