@simplysm/orm-common 14.0.1 → 14.0.4

package/docs/queryable.md

@@ -0,0 +1,236 @@
+# Queryable / Executable
+
+Type-safe query builder and stored procedure executor.
+
+## 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 | never> {
+  constructor(readonly meta: QueryableMeta<TData>);
+}
+```
+
+**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
+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;
+};
+```
+
+## 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(db: DbContextBase, builder: ProcedureBuilder<TParams, TReturns>);
+
+  getExecProcQueryDef(params?: InferColumnExprs<TParams>): ExecProcQueryDef;
+  execute(params: InferColumnExprs<TParams>): Promise<InferColumnExprs<TReturns>[][]>;
+}
+```
+
+**Example:**
+
+```typescript
+const result = await db.getUserById().execute({ userId: 1n });
+```
+
+## executable
+
+Factory function that creates an `Executable` accessor for a `ProcedureBuilder`.
+
+```typescript
+function executable<TParams, TReturns>(
+  db: DbContextBase,
+  builder: ProcedureBuilder<TParams, TReturns>,
+): () => Executable<TParams, TReturns>;
+```
+
+## 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
+
+Parses a search query string into SQL LIKE patterns.
+
+```typescript
+function parseSearchQuery(searchText: string): ParsedSearchQuery;
+```
+
+**Search Syntax:**
+
+| Syntax | Meaning | Example |
+|---|---|---|
+| `term1 term2` | OR (match any) | `apple banana` |
+| `+term` | Required (AND) | `+apple +banana` |
+| `-term` | Excluded (NOT) | `apple -banana` |
+| `"exact phrase"` | Exact phrase match (required) | `"delicious fruit"` |
+| `*` | Wildcard | `app*` produces `app%` |
+
+**Escape Sequences:** `\\` (literal `\`), `\*`, `\%`, `\"`, `\+`, `\-`
+
+**Example:**
+
+```typescript
+parseSearchQuery('apple "delicious fruit" -banana +strawberry');
+// { or: ["%apple%"], must: ["%delicious fruit%", "%strawberry%"], not: ["%banana%"] }
+
+parseSearchQuery('app* test');
+// { or: ["app%", "%test%"], must: [], not: [] }
+```

package/docs/schema-builders.md

@@ -0,0 +1,352 @@
+# Schema Builders
+
+Fluent API builders for defining tables, views, procedures, columns, indexes, and relations.
+
+## Table (function)
+
+Factory function that creates a `TableBuilder`.
+
+```typescript
+function Table(name: string): TableBuilder<{}, {}>;
+```
+
+## TableBuilder
+
+Database table definition builder with fluent API for columns, primary keys, indexes, and relations.
+
+```typescript
+class TableBuilder<TColumns extends ColumnBuilderRecord, TRelations extends RelationBuilderRecord> {
+  readonly $columns: TColumns;
+  readonly $relations: TRelations;
+  readonly $inferSelect: InferColumns<TColumns> & InferDeepRelations<TRelations>;
+  readonly $inferColumns: InferColumns<TColumns>;
+  readonly $inferInsert: InferInsertColumns<TColumns>;
+  readonly $inferUpdate: InferUpdateColumns<TColumns>;
+
+  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` | `(fn: (c: ColumnFactory) => TNewCols) => TableBuilder<TNewCols, TRelations>` | Define columns using the column factory |
+| `primaryKey` | `(...columns: string[]) => TableBuilder` | Set primary key (composite supported) |
+| `indexes` | `(fn: (i: IndexFactory) => IndexBuilder[]) => TableBuilder` | Define indexes |
+| `relations` | `(fn: (r: RelationFactory) => T) => TableBuilder<TColumns, T>` | Define relationships |
+
+**Example:**
+
+```typescript
+const User = Table("User")
+  .database("mydb")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+    status: c.varchar(20).default("active"),
+  }))
+  .primaryKey("id")
+  .indexes((i) => [i.index("email").unique()])
+  .relations((r) => ({
+    posts: r.foreignKeyTarget(() => Post, "author"),
+  }));
+```
+
+## View (function)
+
+Factory function that creates a `ViewBuilder`.
+
+```typescript
+function View(name: string): ViewBuilder<any, {}, {}>;
+```
+
+## ViewBuilder
+
+Database view definition builder.
+
+```typescript
+class ViewBuilder<TDbContext, TData extends DataRecord, TRelations extends RelationBuilderRecord> {
+  readonly $relations: TRelations;
+  readonly $inferSelect: TData;
+
+  constructor(readonly meta: {
+    name: string;
+    description?: string;
+    database?: string;
+    schema?: string;
+    viewFn?: (db: TDbContext) => Queryable<TData, any>;
+    relations?: TRelations;
+  });
+}
+```
+
+### 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` | `(viewFn: (db: TDb) => Queryable) => ViewBuilder` | Define view query |
+| `relations` | `(fn: (r: RelationFactory) => T) => ViewBuilder` | Define relationships |
+
+**Example:**
+
+```typescript
+const ActiveUsers = View("ActiveUsers")
+  .database("mydb")
+  .query((db: MyDb) =>
+    db.user()
+      .where((u) => [expr.eq(u.status, "active")])
+      .select((u) => ({ id: u.id, name: u.name }))
+  );
+```
+
+## Procedure (function)
+
+Factory function that creates a `ProcedureBuilder`.
+
+```typescript
+function Procedure(name: string): ProcedureBuilder<never, never>;
+```
+
+## ProcedureBuilder
+
+Stored procedure definition builder.
+
+```typescript
+class ProcedureBuilder<TParams extends ColumnBuilderRecord, TReturns extends ColumnBuilderRecord> {
+  readonly $params: TParams;
+  readonly $returns: TReturns;
+
+  constructor(readonly meta: {
+    name: string;
+    description?: string;
+    database?: string;
+    schema?: string;
+    params?: TParams;
+    returns?: TReturns;
+    query?: string;
+  });
+}
+```
+
+### 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` | `(fn: (c: ColumnFactory) => T) => ProcedureBuilder<T, TReturns>` | Define input parameters |
+| `returns` | `(fn: (c: ColumnFactory) => T) => ProcedureBuilder<TParams, T>` | Define return columns |
+| `body` | `(sql: string) => ProcedureBuilder` | Set procedure body SQL |
+
+**Example:**
+
+```typescript
+const GetUserById = Procedure("GetUserById")
+  .database("mydb")
+  .params((c) => ({ userId: c.bigint() }))
+  .returns((c) => ({ id: c.bigint(), name: c.varchar(100) }))
+  .body("SELECT id, name FROM User WHERE id = userId");
+```
+
+## ColumnBuilder
+
+Column definition builder used inside `TableBuilder.columns()`.
+
+```typescript
+class ColumnBuilder<TValue extends ColumnPrimitive, TMeta extends ColumnMeta> {
+  constructor(readonly meta: TMeta);
+}
+```
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `autoIncrement` | `() => ColumnBuilder` | Set auto-increment. Makes column optional in INSERT. |
+| `nullable` | `() => ColumnBuilder<TValue \| undefined, ...>` | Allow NULL. Adds `undefined` to value type. |
+| `default` | `(value: TValue) => ColumnBuilder` | Set default value. Makes column optional in INSERT. |
+| `description` | `(desc: string) => ColumnBuilder` | Set column description (DDL comment) |
+
+## createColumnFactory
+
+Returns a column factory object with methods for all supported data types.
+
+```typescript
+function createColumnFactory(): {
+  int(): ColumnBuilder<number, ...>;
+  bigint(): ColumnBuilder<number, ...>;
+  float(): ColumnBuilder<number, ...>;
+  double(): ColumnBuilder<number, ...>;
+  decimal(precision: number, scale?: number): ColumnBuilder<number, ...>;
+  varchar(length: number): ColumnBuilder<string, ...>;
+  char(length: number): ColumnBuilder<string, ...>;
+  text(): ColumnBuilder<string, ...>;
+  binary(): ColumnBuilder<Bytes, ...>;
+  boolean(): ColumnBuilder<boolean, ...>;
+  datetime(): ColumnBuilder<DateTime, ...>;
+  date(): ColumnBuilder<DateOnly, ...>;
+  time(): ColumnBuilder<Time, ...>;
+  uuid(): ColumnBuilder<Uuid, ...>;
+};
+```
+
+## IndexBuilder
+
+Index definition builder used inside `TableBuilder.indexes()`.
+
+```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` | Set custom index name |
+| `unique` | `() => IndexBuilder` | Mark as unique index |
+| `orderBy` | `(...orderBy: ("ASC" \| "DESC")[]) => IndexBuilder` | Set column sort order |
+| `description` | `(description: string) => IndexBuilder` | Set index description |
+
+## createIndexFactory
+
+Returns an index factory with the `index(...columns)` method.
+
+```typescript
+function createIndexFactory<TColumnKey extends string>(): {
+  index<TKeys extends TColumnKey[]>(...columns: TKeys): IndexBuilder<TKeys>;
+};
+```
+
+## ForeignKeyBuilder
+
+Foreign key relation builder (N:1). Creates a real FK constraint in the database.
+
+```typescript
+class ForeignKeyBuilder<TOwner extends TableBuilder, TTargetFn extends () => TableBuilder> {
+  constructor(readonly meta: {
+    ownerFn: () => TOwner;
+    columns: string[];
+    targetFn: TTargetFn;
+    description?: string;
+  });
+
+  description(desc: string): ForeignKeyBuilder;
+}
+```
+
+## ForeignKeyTargetBuilder
+
+Foreign key reverse-reference builder (1:N). Loaded as array by default, call `.single()` for 1:1.
+
+```typescript
+class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder, TIsSingle extends boolean> {
+  constructor(readonly meta: {
+    targetTableFn: TTargetTableFn;
+    relationName: string;
+    description?: string;
+    isSingle?: TIsSingle;
+  });
+
+  description(desc: string): ForeignKeyTargetBuilder;
+  single(): ForeignKeyTargetBuilder<TTargetTableFn, true>;
+}
+```
+
+## RelationKeyBuilder
+
+Logical relation builder (N:1). Same as `ForeignKeyBuilder` but does NOT create a FK constraint in the database. Usable from both Tables and Views.
+
+```typescript
+class RelationKeyBuilder<TOwner, TTargetFn extends () => TableBuilder | ViewBuilder> {
+  constructor(readonly meta: {
+    ownerFn: () => TOwner;
+    columns: string[];
+    targetFn: TTargetFn;
+    description?: string;
+  });
+
+  description(desc: string): RelationKeyBuilder;
+}
+```
+
+## RelationKeyTargetBuilder
+
+Logical reverse-reference builder (1:N). Same as `ForeignKeyTargetBuilder` but without FK constraint. Usable from both Tables and Views.
+
+```typescript
+class RelationKeyTargetBuilder<TTargetTableFn, TIsSingle extends boolean> {
+  constructor(readonly meta: {
+    targetTableFn: TTargetTableFn;
+    relationName: string;
+    description?: string;
+    isSingle?: TIsSingle;
+  });
+
+  description(desc: string): RelationKeyTargetBuilder;
+  single(): RelationKeyTargetBuilder<TTargetTableFn, true>;
+}
+```
+
+## createRelationFactory
+
+Returns a relation factory. Tables get both FK and RelationKey methods; Views get only RelationKey methods.
+
+```typescript
+function createRelationFactory<TOwner, TColumnKey extends string>(
+  ownerFn: () => TOwner,
+): TOwner extends TableBuilder
+  ? RelationFkFactory & RelationRkFactory
+  : RelationRkFactory;
+```
+
+**Factory methods (Table):**
+
+| Method | Description |
+|---|---|
+| `foreignKey(columns, targetFn)` | N:1 FK relation (creates DB constraint) |
+| `foreignKeyTarget(targetTableFn, relationName)` | 1:N FK reverse-reference |
+| `relationKey(columns, targetFn)` | N:1 logical relation (no DB constraint) |
+| `relationKeyTarget(targetTableFn, relationName)` | 1:N logical reverse-reference |
+
+## Type Utilities
+
+| Type | Description |
+|---|---|
+| `ColumnBuilderRecord` | `Record<string, ColumnBuilder<ColumnPrimitive, ColumnMeta>>` |
+| `RelationBuilderRecord` | `Record<string, ForeignKeyBuilder \| ForeignKeyTargetBuilder \| RelationKeyBuilder \| RelationKeyTargetBuilder>` |
+| `InferColumns<T>` | Infer runtime value types from column builders |
+| `InferColumnExprs<T>` | Infer `ExprInput` types from column builders |
+| `InferInsertColumns<T>` | INSERT type: required fields + optional for autoIncrement/nullable/default |
+| `InferUpdateColumns<T>` | UPDATE type: all fields optional |
+| `RequiredInsertKeys<T>` | Extract required INSERT column keys |
+| `OptionalInsertKeys<T>` | Extract optional INSERT column keys |
+| `DataToColumnBuilderRecord<T>` | Convert data record to column builder record |
+| `ExtractRelationTarget<T>` | Extract target type from FK/RelationKey (single object) |
+| `ExtractRelationTargetResult<T>` | Extract target type from FKTarget/RelationKeyTarget (array or single) |
+| `InferDeepRelations<T>` | Deep relation type inference (all optional) |