@simplysm/orm-common 13.0.97 → 13.0.99

package/docs/query-builder.md

@@ -0,0 +1,93 @@
+# Query Builder
+
+## `createQueryBuilder`
+
+Generate a `QueryBuilderBase` instance matching the given dialect.
+
+```typescript
+function createQueryBuilder(dialect: Dialect): QueryBuilderBase;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dialect` | `Dialect` | Database dialect (`"mysql"`, `"mssql"`, `"postgresql"`) |
+
+## `QueryBuilderBase`
+
+Abstract base class that renders `QueryDef` JSON AST to dialect-specific SQL strings. Implements dispatch logic identical across all dialects; dialect-specific rendering is handled by subclasses.
+
+```typescript
+abstract class QueryBuilderBase {
+  protected abstract expr: ExprRendererBase;
+
+  build(def: QueryDef): QueryBuildResult;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `build()` | Render a `QueryDef` to SQL. Dispatches to the appropriate method by `def.type`. |
+
+## `ExprRendererBase`
+
+Abstract base class for rendering `Expr` and `WhereExpr` JSON AST nodes to dialect-specific SQL strings. Each dialect (MySQL, MSSQL, PostgreSQL) extends this class with its own implementations.
+
+```typescript
+abstract class ExprRendererBase {
+  render(expr: Expr): string;
+  renderWhere(expr: WhereExpr): string;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `render()` | Render a value expression to SQL |
+| `renderWhere()` | Render a WHERE expression to SQL |
+
+## `MysqlQueryBuilder`
+
+MySQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class MysqlQueryBuilder extends QueryBuilderBase { ... }
+```
+
+## `MysqlExprRenderer`
+
+MySQL-specific expression renderer. Extends `ExprRendererBase`.
+
+```typescript
+class MysqlExprRenderer extends ExprRendererBase { ... }
+```
+
+## `MssqlQueryBuilder`
+
+MSSQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class MssqlQueryBuilder extends QueryBuilderBase { ... }
+```
+
+## `MssqlExprRenderer`
+
+MSSQL-specific expression renderer. Extends `ExprRendererBase`.
+
+```typescript
+class MssqlExprRenderer extends ExprRendererBase { ... }
+```
+
+## `PostgresqlQueryBuilder`
+
+PostgreSQL-specific query builder. Extends `QueryBuilderBase`.
+
+```typescript
+class PostgresqlQueryBuilder extends QueryBuilderBase { ... }
+```
+
+## `PostgresqlExprRenderer`
+
+PostgreSQL-specific expression renderer. Extends `ExprRendererBase`.
+
+```typescript
+class PostgresqlExprRenderer extends ExprRendererBase { ... }
+```

package/docs/queryable.md

@@ -0,0 +1,198 @@
+# Queryable / Executable
+
+## `Queryable`
+
+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,
+> {
+  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.
+
+```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>;
+```
+
+## `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>;
+  };
+
+  execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `getExecProcQueryDef()` | Generate procedure execution QueryDef |
+| `execute()` | Execute the stored procedure |
+
+## `executable`
+
+Factory function to create an Executable accessor for DbContext.
+
+```typescript
+function executable<
+  TParams extends ColumnBuilderRecord,
+  TReturns extends ColumnBuilderRecord,
+>(
+  db: DbContextBase,
+  builder: ProcedureBuilder<TParams, TReturns>,
+): () => Executable<TParams, TReturns>;
+```
+
+## `parseSearchQuery`
+
+Parse a search query string and convert to SQL LIKE patterns.
+
+```typescript
+function parseSearchQuery(searchText: string): ParsedSearchQuery;
+```
+
+### Search Syntax
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `term1 term2` | OR (one of them) | `apple banana` |
+| `+term` | Required (AND) | `+apple +banana` |
+| `-term` | Excluded (NOT) | `apple -banana` |
+| `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
+| `*` | Wildcard | `app*` -> `app%` |
+
+## `ParsedSearchQuery`
+
+Search query parsing result.
+
+```typescript
+interface ParsedSearchQuery {
+  or: string[];
+  must: string[];
+  not: string[];
+}
+```
+
+| 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 |