@simplysm/orm-common 14.0.1 → 14.0.5

package/docs/queryable.md

@@ -0,0 +1,261 @@
+# Queryable / Executable
+
+Type-safe query builder and stored procedure executor.
+
+## Queryable
+
+```typescript
+class Queryable<TData extends DataRecord, TFrom extends TableBuilder<any, any> | never> {
+  constructor(readonly meta: QueryableMeta<TData>);
+}
+```
+
+Fluent query builder for composing SELECT, INSERT, UPDATE, DELETE, and UPSERT queries. All methods return new Queryable instances (immutable chaining).
+
+- `TData` - Query result data type
+- `TFrom` - Source table (required for CUD operations, `never` for read-only)
+
+### Option Methods (SELECT / DISTINCT / LOCK)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `select` | `<R>(fn: (cols: QueryableRecord<TData>) => R) => Queryable<UnwrapQueryableRecord<R>, never>` | Specify columns to SELECT |
+| `distinct` | `() => Queryable<TData, never>` | Apply DISTINCT |
+| `lock` | `() => Queryable<TData, TFrom>` | Apply FOR UPDATE row lock |
+
+### Restrict Methods (TOP / LIMIT)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `top` | `(count: number) => Queryable<TData, TFrom>` | Select top N rows |
+| `limit` | `(skip: number, take: number) => Queryable<TData, TFrom>` | Pagination (requires orderBy) |
+
+### Sorting (ORDER BY)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `orderBy` | `(fn: (cols) => ExprUnit, orderBy?: "ASC" \| "DESC") => Queryable<TData, TFrom>` | Add sort condition (stackable) |
+
+### Filtering (WHERE)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `where` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, TFrom>` | Add WHERE conditions (stackable, AND) |
+| `search` | `(fn: (cols) => ExprUnit<string\|undefined>[], searchText: string) => Queryable<TData, TFrom>` | Full-text search across columns |
+
+### Grouping (GROUP BY / HAVING)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `groupBy` | `(fn: (cols) => ExprUnit[]) => Queryable<TData, never>` | Group by columns |
+| `having` | `(predicate: (cols) => WhereExprUnit[]) => Queryable<TData, never>` | Filter groups |
+
+### JOIN
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `join` | `<A, R>(as: A, fn: (qr: JoinQueryable, cols) => Queryable<R, any>) => Queryable<TData & { [K in A]?: R[] }, TFrom>` | LEFT OUTER JOIN (1:N, result as array) |
+| `joinSingle` | `<A, R>(as: A, fn: (qr: JoinQueryable, cols) => Queryable<R, any>) => Queryable<TData & { [K in A]?: R }, TFrom>` | LEFT OUTER JOIN (N:1 or 1:1, result as single object) |
+| `include` | `(fn: (item: PathProxy<TData>) => PathProxy) => Queryable<TData, TFrom>` | Auto-JOIN based on TableBuilder FK/FKT relations |
+
+### Subquery / Union
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `wrap` | `() => Queryable<TData, never>` | Wrap as subquery (needed for count after distinct/groupBy) |
+| `Queryable.union` (static) | `(...queries: Queryable<TData, any>[]) => Queryable<TData, never>` | Combine queries with UNION (min 2) |
+
+### Recursive CTE
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `recursive` | `(fn: (cte: RecursiveQueryable<TData>) => Queryable<TData, any>) => Queryable<TData, never>` | Generate recursive CTE (WITH RECURSIVE) |
+
+### Execution (SELECT)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `execute` | `() => Promise<TData[]>` | Execute SELECT and return results |
+| `single` | `() => Promise<TData \| undefined>` | Return single result (throws if > 1) |
+| `first` | `() => Promise<TData \| undefined>` | Return first result |
+| `count` | `(fn?: (cols) => ExprUnit) => Promise<number>` | Count rows (throws after distinct/groupBy without wrap) |
+| `exists` | `() => Promise<boolean>` | Check if any matching data exists |
+
+### QueryDef Getters (SELECT)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getSelectQueryDef` | `() => SelectQueryDef` | Get the SELECT QueryDef AST |
+| `getResultMeta` | `(outputColumns?: string[]) => ResultMeta` | Get result parsing metadata |
+
+### INSERT
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `insert` | `(records: TFrom["$inferInsert"][]) => Promise<void>` | Insert records (auto-chunks per 1000) |
+| `insert` | `(records, outputColumns: K[]) => Promise<Pick<...>[]>` | Insert with output columns |
+| `insertIfNotExists` | `(record: TFrom["$inferInsert"]) => Promise<void>` | Insert if WHERE condition has no match |
+| `insertIfNotExists` | `(record, outputColumns: K[]) => Promise<Pick<...>>` | Insert if not exists with output |
+| `insertInto` | `(targetTable: TableBuilder) => Promise<void>` | INSERT INTO ... SELECT |
+| `insertInto` | `(targetTable, outputColumns: K[]) => Promise<Pick<...>[]>` | INSERT INTO ... SELECT with output |
+
+### UPDATE / DELETE
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `update` | `(recordFwd: (cols) => QueryableWriteRecord) => Promise<void>` | Update matching rows |
+| `update` | `(recordFwd, outputColumns: K[]) => Promise<Pick<...>[]>` | Update with output |
+| `delete` | `() => Promise<void>` | Delete matching rows |
+| `delete` | `(outputColumns: K[]) => Promise<Pick<...>[]>` | Delete with output |
+
+### UPSERT
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `upsert` | `(updateFn: (cols) => WriteRecord) => Promise<void>` | Update or insert (same data) |
+| `upsert` | `(updateFn, insertFn) => Promise<void>` | Update or insert (different data) |
+| `upsert` | `(updateFn, insertFn?, outputColumns?) => Promise<Pick<...>[] \| void>` | With output columns |
+
+### DDL Helper
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `switchFk` | `(enabled: boolean) => Promise<void>` | Enable/disable FK constraints on this table |
+
+## queryable (factory)
+
+```typescript
+function queryable<TBuilder extends TableBuilder<any, any> | ViewBuilder<any, any, any>>(
+  db: DbContextBase,
+  tableOrView: TBuilder,
+  as?: string,
+): () => Queryable<TBuilder["$inferSelect"], TBuilder extends TableBuilder ? TBuilder : never>
+```
+
+Creates a factory function that returns a new Queryable instance each time it is called. Each call allocates a fresh alias via `db.getNextAlias()`.
+
+## Executable
+
+```typescript
+class Executable<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
+  constructor(db: DbContextBase, builder: ProcedureBuilder<TParams, TReturns>);
+  getExecProcQueryDef(params?: InferColumnExprs<TParams>): { type: "execProc"; ... };
+  async execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
+}
+```
+
+Stored procedure execution wrapper.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getExecProcQueryDef` | `(params?) => ExecProcQueryDef` | Build procedure execution QueryDef |
+| `execute` | `(params) => Promise<T[][]>` | Execute the procedure |
+
+## executable (factory)
+
+```typescript
+function executable<TParams, TReturns>(
+  db: DbContextBase,
+  builder: ProcedureBuilder<TParams, TReturns>,
+): () => Executable<TParams, TReturns>
+```
+
+Creates a factory function that returns a new Executable instance.
+
+## parseSearchQuery
+
+```typescript
+function parseSearchQuery(searchText: string): ParsedSearchQuery
+```
+
+Parses a search query string into SQL LIKE patterns.
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `term1 term2` | OR (match any) | `apple banana` |
+| `+term` | Required (AND) | `+apple +banana` |
+| `-term` | Exclude (NOT) | `apple -banana` |
+| `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
+| `*` | Wildcard | `app*` becomes `app%` |
+
+Escape sequences: `\\` (literal `\`), `\*`, `\%`, `\"`, `\+`, `\-`.
+
+## ParsedSearchQuery
+
+```typescript
+interface ParsedSearchQuery {
+  or: string[];    // OR conditions - LIKE patterns
+  must: string[];  // AND conditions (+ prefix or quotes) - LIKE patterns
+  not: string[];   // NOT conditions (- prefix) - LIKE patterns
+}
+```
+
+## getMatchedPrimaryKeys
+
+```typescript
+function getMatchedPrimaryKeys(
+  fkCols: string[],
+  targetTable: TableBuilder<any, any>,
+): string[]
+```
+
+Match FK column array with the target table's PK. Returns PK column name array. Throws if column counts do not match.
+
+## QueryableRecord
+
+```typescript
+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]> : ...
+}
+```
+
+Maps each field of a DataRecord to its corresponding ExprUnit proxy. Used as the column accessor type in Queryable callbacks.
+
+## QueryableWriteRecord
+
+```typescript
+type QueryableWriteRecord<TData> = {
+  [K in keyof TData]: TData[K] extends ColumnPrimitive ? ExprInput<TData[K]> : never;
+}
+```
+
+Maps each field to ExprInput for write operations (UPDATE, UPSERT).
+
+## NullableQueryableRecord
+
+```typescript
+type NullableQueryableRecord<TData extends DataRecord> = { ... }
+```
+
+Like QueryableRecord but all primitive fields become `ExprUnit<T | undefined>`. Used for LEFT JOIN results where all columns may be NULL.
+
+## UnwrapQueryableRecord
+
+```typescript
+type UnwrapQueryableRecord<R> = {
+  [K in keyof R]: R[K] extends ExprUnit<infer T> ? T : ...
+}
+```
+
+Reverse-maps QueryableRecord back to a plain DataRecord. Used internally by `select()` to infer the resulting data type.
+
+## PathProxy
+
+```typescript
+type PathProxy<TObject> = {
+  [K in keyof TObject as TObject[K] extends ColumnPrimitive ? never : K]-?: PathProxy<UnwrapArray<TObject[K]>>;
+} & { readonly [PATH_SYMBOL]: string[] }
+```
+
+Type-safe proxy for `include()` that only exposes non-primitive (relation) fields. Property access builds a path array internally.
+
+```typescript
+// Only relation fields are accessible:
+db.post().include((p) => p.author)         // OK - author is a relation
+db.post().include((p) => p.author.company) // OK - nested relation
+// db.post().include((p) => p.title)       // Compile error - title is string
+```

package/docs/schema-builders.md

@@ -0,0 +1,294 @@
+# Schema Builders
+
+Fluent API builders for defining tables, views, procedures, columns, indexes, and relations.
+
+## Table (function)
+
+```typescript
+function Table(name: string): TableBuilder<{}, {}>
+```
+
+Creates a new TableBuilder with the given table name.
+
+## TableBuilder
+
+```typescript
+class TableBuilder<TColumns extends ColumnBuilderRecord, TRelations extends RelationBuilderRecord>
+```
+
+Fluent API for defining database table schema including columns, primary key, indexes, and relations.
+
+### Phantom Type Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$columns` | `TColumns` | Column definitions (type inference) |
+| `$relations` | `TRelations` | Relation definitions (type inference) |
+| `$inferSelect` | `InferColumns<TColumns> & InferDeepRelations<TRelations>` | Full SELECT type |
+| `$inferColumns` | `InferColumns<TColumns>` | Column-only type |
+| `$inferInsert` | `InferInsertColumns<TColumns>` | INSERT type (AI/nullable/default optional) |
+| `$inferUpdate` | `InferUpdateColumns<TColumns>` | UPDATE type (all optional) |
+
+### Constructor
+
+```typescript
+constructor(readonly meta: {
+  name: string;
+  description?: string;
+  database?: string;
+  schema?: string;
+  columns?: TColumns;
+  primaryKey?: (keyof TColumns & string)[];
+  relations?: TRelations;
+  indexes?: IndexBuilder<(keyof TColumns & string)[]>[];
+})
+```
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => TableBuilder` | Set table description (DDL comment) |
+| `database` | `(db: string) => TableBuilder` | Set database name |
+| `schema` | `(schema: string) => TableBuilder` | Set schema name (MSSQL/PostgreSQL) |
+| `columns` | `<T>(fn: (c: ColumnFactory) => T) => TableBuilder<T, TRelations>` | Define columns via column factory |
+| `primaryKey` | `(...columns: (keyof TColumns & string)[]) => TableBuilder` | Set primary key (single or composite) |
+| `indexes` | `(fn: (i: IndexFactory) => IndexBuilder[]) => TableBuilder` | Define indexes |
+| `relations` | `<T>(fn: (r: RelationFactory) => T) => TableBuilder<TColumns, T>` | Define FK and relation mappings |
+
+## View (function)
+
+```typescript
+function View(name: string): ViewBuilder<any, any, {}>
+```
+
+Creates a new ViewBuilder with the given view name.
+
+## ViewBuilder
+
+```typescript
+class ViewBuilder<TDbContext extends DbContextBase, TData extends DataRecord, TRelations extends RelationBuilderRecord>
+```
+
+Fluent API for defining database view schema.
+
+### Phantom Type Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$relations` | `TRelations` | Relation definitions |
+| `$inferSelect` | `TData` | Full SELECT type |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => ViewBuilder` | Set view description |
+| `database` | `(db: string) => ViewBuilder` | Set database name |
+| `schema` | `(schema: string) => ViewBuilder` | Set schema name |
+| `query` | `<TViewData, TDb>(viewFn: (db: TDb) => Queryable<TViewData, any>) => ViewBuilder<TDb, TViewData, TRelations>` | Define the view's SELECT query |
+| `relations` | `<T>(fn: (r: RelationFactory) => T) => ViewBuilder` | Define relations (RelationKey only, no FK) |
+
+## Procedure (function)
+
+```typescript
+function Procedure(name: string): ProcedureBuilder<never, never>
+```
+
+Creates a new ProcedureBuilder with the given procedure name.
+
+## ProcedureBuilder
+
+```typescript
+class ProcedureBuilder<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord>
+```
+
+Fluent API for defining stored procedure schema.
+
+### Phantom Type Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `$params` | `TParams` | Parameter definitions |
+| `$returns` | `TReturns` | Return type definitions |
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => ProcedureBuilder` | Set procedure description |
+| `database` | `(db: string) => ProcedureBuilder` | Set database name |
+| `schema` | `(schema: string) => ProcedureBuilder` | Set schema name |
+| `params` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<T, TReturns>` | Define input parameters |
+| `returns` | `<T>(fn: (c: ColumnFactory) => T) => ProcedureBuilder<TParams, T>` | Define return columns |
+| `body` | `(sql: string) => ProcedureBuilder` | Set procedure body SQL |
+
+## ColumnBuilder
+
+```typescript
+class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
+  constructor(readonly meta: TMeta);
+}
+```
+
+Column definition builder with fluent API for type modifiers.
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `autoIncrement` | `() => ColumnBuilder<TValue, TMeta & { autoIncrement: true }>` | Set auto-increment (INSERT optional) |
+| `nullable` | `() => ColumnBuilder<TValue \| undefined, TMeta & { nullable: true }>` | Allow NULL values |
+| `default` | `(value: TValue) => ColumnBuilder<TValue, TMeta & { default: TValue }>` | Set default value (INSERT optional) |
+| `description` | `(desc: string) => ColumnBuilder<TValue, TMeta & { description: string }>` | Set column description (DDL comment) |
+
+## createColumnFactory
+
+```typescript
+function createColumnFactory(): ColumnFactory
+```
+
+Returns a column type factory object. Used inside `TableBuilder.columns()` and `ProcedureBuilder.params()/returns()`.
+
+### Factory Methods
+
+| Method | Signature | SQL Type | TypeScript Type |
+|--------|-----------|----------|-----------------|
+| `int` | `() => ColumnBuilder<number, ...>` | `INT` | `number` |
+| `bigint` | `() => ColumnBuilder<number, ...>` | `BIGINT` | `number` |
+| `float` | `() => ColumnBuilder<number, ...>` | `FLOAT` | `number` |
+| `double` | `() => ColumnBuilder<number, ...>` | `DOUBLE` | `number` |
+| `decimal` | `(precision, scale?) => ColumnBuilder<number, ...>` | `DECIMAL(p,s)` | `number` |
+| `varchar` | `(length) => ColumnBuilder<string, ...>` | `VARCHAR(n)` | `string` |
+| `char` | `(length) => ColumnBuilder<string, ...>` | `CHAR(n)` | `string` |
+| `text` | `() => ColumnBuilder<string, ...>` | `TEXT` | `string` |
+| `binary` | `() => ColumnBuilder<Bytes, ...>` | `LONGBLOB`/`BYTEA` | `Bytes` |
+| `boolean` | `() => ColumnBuilder<boolean, ...>` | `TINYINT(1)`/`BIT`/`BOOLEAN` | `boolean` |
+| `datetime` | `() => ColumnBuilder<DateTime, ...>` | `DATETIME` | `DateTime` |
+| `date` | `() => ColumnBuilder<DateOnly, ...>` | `DATE` | `DateOnly` |
+| `time` | `() => ColumnBuilder<Time, ...>` | `TIME` | `Time` |
+| `uuid` | `() => ColumnBuilder<Uuid, ...>` | `BINARY(16)`/`UNIQUEIDENTIFIER`/`UUID` | `Uuid` |
+
+## IndexBuilder
+
+```typescript
+class IndexBuilder<TKeys extends string[]> {
+  constructor(readonly meta: {
+    columns: TKeys;
+    name?: string;
+    unique?: boolean;
+    orderBy?: { [K in keyof TKeys]: "ASC" | "DESC" };
+    description?: string;
+  });
+}
+```
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `name` | `(name: string) => IndexBuilder<TKeys>` | Set custom index name |
+| `unique` | `() => IndexBuilder<TKeys>` | Mark as unique index |
+| `orderBy` | `(...orderBy: ("ASC" \| "DESC")[]) => IndexBuilder<TKeys>` | Set sort order per column |
+| `description` | `(desc: string) => IndexBuilder<TKeys>` | Set index description |
+
+## createIndexFactory
+
+```typescript
+function createIndexFactory<TColumnKey extends string>(): { index: (...columns: TColumnKey[]) => IndexBuilder }
+```
+
+Returns an index factory. Used inside `TableBuilder.indexes()`.
+
+## ForeignKeyBuilder
+
+```typescript
+class ForeignKeyBuilder<TOwner extends TableBuilder<any, any>, TTargetFn extends () => TableBuilder<any, any>> {
+  constructor(readonly meta: {
+    ownerFn: () => TOwner;
+    columns: string[];
+    targetFn: TTargetFn;
+    description?: string;
+  });
+}
+```
+
+N:1 FK relation builder. Creates an actual DB foreign key constraint.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => ForeignKeyBuilder` | Set relation description |
+
+## ForeignKeyTargetBuilder
+
+```typescript
+class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder<any, any>, TIsSingle extends boolean> {
+  constructor(readonly meta: {
+    targetTableFn: TTargetTableFn;
+    relationName: string;
+    description?: string;
+    isSingle?: TIsSingle;
+  });
+}
+```
+
+1:N FK reverse-reference builder. Loaded as array by default, single object with `.single()`.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => ForeignKeyTargetBuilder` | Set relation description |
+| `single` | `() => ForeignKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
+
+## RelationKeyBuilder
+
+```typescript
+class RelationKeyBuilder<
+  TOwner extends TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TTargetFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+>
+```
+
+Logical N:1 relation builder (no DB FK constraint). Works with both Tables and Views.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => RelationKeyBuilder` | Set relation description |
+
+## RelationKeyTargetBuilder
+
+```typescript
+class RelationKeyTargetBuilder<
+  TTargetTableFn extends () => TableBuilder<any, any> | ViewBuilder<any, any, any>,
+  TIsSingle extends boolean,
+>
+```
+
+Logical 1:N reverse-reference builder (no DB FK constraint). Works with both Tables and Views.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description` | `(desc: string) => RelationKeyTargetBuilder` | Set relation description |
+| `single` | `() => RelationKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
+
+## createRelationFactory
+
+```typescript
+function createRelationFactory<TOwner, TColumnKey extends string>(
+  ownerFn: () => TOwner,
+): RelationFactory
+```
+
+Creates a relation factory. For `TableBuilder`: provides `foreignKey`, `foreignKeyTarget`, `relationKey`, `relationKeyTarget`. For `ViewBuilder`: provides only `relationKey`, `relationKeyTarget`.
+
+### Factory Methods (Table)
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `foreignKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder) => ForeignKeyBuilder` | N:1 FK (creates DB constraint) |
+| `foreignKeyTarget` | `(targetTableFn: () => TableBuilder, relationName: string) => ForeignKeyTargetBuilder` | 1:N FK reverse-reference |
+| `relationKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder \| ViewBuilder) => RelationKeyBuilder` | N:1 logical relation (no DB FK) |
+| `relationKeyTarget` | `(targetTableFn: () => TableBuilder \| ViewBuilder, relationName: string) => RelationKeyTargetBuilder` | 1:N logical reverse-reference |
+
+### Factory Methods (View)
+
+Only `relationKey` and `relationKeyTarget` are available for ViewBuilder.