@simplysm/orm-common 13.0.84 → 13.0.86

package/docs/schema-builders.md

@@ -1,216 +0,0 @@
-# Schema Builders
-
-Define database tables, views, and stored procedures with a fluent, type-safe API.
-
-## API Reference
-
-### `Table(name)`
-
-Factory function that creates a `TableBuilder` for defining table schemas.
-
-```typescript
-function Table(name: string): TableBuilder<{}, {}>
-```
-
-#### TableBuilder Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description(desc)` | `.description(desc: string)` | Set table description (DDL comment) |
-| `database(db)` | `.database(db: string)` | Set database name |
-| `schema(schema)` | `.schema(schema: string)` | Set schema name (MSSQL: `dbo`, PostgreSQL: `public`) |
-| `columns(fn)` | `.columns((c) => ({...}))` | Define columns using column factory |
-| `primaryKey(...cols)` | `.primaryKey("col1", "col2")` | Set primary key (single or composite) |
-| `indexes(fn)` | `.indexes((i) => [...])` | Define indexes |
-| `relations(fn)` | `.relations((r) => ({...}))` | Define relationships (FK, reverse FK, logical relations) |
-
-#### Type Inference Properties
-
-| Property | Description |
-|----------|-------------|
-| `$inferSelect` | Full type (columns + deep relations) |
-| `$inferColumns` | Columns only |
-| `$inferInsert` | Insert type (autoIncrement/nullable/default fields are optional) |
-| `$inferUpdate` | Update type (all fields optional) |
-
----
-
-### `View(name)`
-
-Factory function that creates a `ViewBuilder` for defining database views.
-
-```typescript
-function View(name: string): ViewBuilder<any, {}, {}>
-```
-
-#### ViewBuilder Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description(desc)` | `.description(desc: string)` | Set view description |
-| `database(db)` | `.database(db: string)` | Set database name |
-| `schema(schema)` | `.schema(schema: string)` | Set schema name |
-| `query(viewFn)` | `.query((db) => db.table().select(...))` | Define view SELECT query |
-| `relations(fn)` | `.relations((r) => ({...}))` | Define relationships (logical only, no FK) |
-
----
-
-### `Procedure(name)`
-
-Factory function that creates a `ProcedureBuilder` for defining stored procedures.
-
-```typescript
-function Procedure(name: string): ProcedureBuilder<never, never>
-```
-
-#### ProcedureBuilder Methods
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description(desc)` | `.description(desc: string)` | Set procedure description |
-| `database(db)` | `.database(db: string)` | Set database name |
-| `schema(schema)` | `.schema(schema: string)` | Set schema name |
-| `params(fn)` | `.params((c) => ({...}))` | Define input parameters |
-| `returns(fn)` | `.returns((c) => ({...}))` | Define return columns |
-| `body(sql)` | `.body("SELECT ...")` | Set procedure body SQL |
-
----
-
-### Column Factory
-
-The column factory (`c`) is provided inside `.columns()` and `.params()`/`.returns()` callbacks.
-
-#### Column Types
-
-| Method | SQL Type | TypeScript Type | Notes |
-|--------|----------|-----------------|-------|
-| `c.int()` | INT | `number` | 4 bytes |
-| `c.bigint()` | BIGINT | `number` | 8 bytes |
-| `c.float()` | FLOAT | `number` | Single precision |
-| `c.double()` | DOUBLE | `number` | Double precision |
-| `c.decimal(p, s)` | DECIMAL(p,s) | `number` | Fixed-point |
-| `c.varchar(len)` | VARCHAR(len) | `string` | Variable-length string |
-| `c.char(len)` | CHAR(len) | `string` | Fixed-length string |
-| `c.text()` | TEXT | `string` | Large text |
-| `c.binary()` | BLOB/VARBINARY/BYTEA | `Bytes` | Binary data |
-| `c.boolean()` | TINYINT(1)/BIT/BOOLEAN | `boolean` | |
-| `c.datetime()` | DATETIME | `DateTime` | Date + time |
-| `c.date()` | DATE | `DateOnly` | Date only |
-| `c.time()` | TIME | `Time` | Time only |
-| `c.uuid()` | BINARY(16)/UNIQUEIDENTIFIER/UUID | `Uuid` | |
-
-#### Column Modifiers
-
-| Method | Description |
-|--------|-------------|
-| `.autoIncrement()` | Auto-increment (optional in INSERT inference) |
-| `.nullable()` | Allow NULL (adds `undefined` to type) |
-| `.default(value)` | Set default value (optional in INSERT inference) |
-| `.description(desc)` | Set column comment |
-
----
-
-### Index Factory
-
-The index factory (`i`) is provided inside `.indexes()` callbacks.
-
-```typescript
-i.index("col1", "col2")     // Create index on columns
-  .unique()                  // Make unique
-  .orderBy("ASC", "DESC")   // Set sort order per column
-  .name("IX_Custom_Name")   // Custom index name
-  .description("desc")      // Description
-```
-
----
-
-### Relation Factory
-
-The relation factory (`r`) is provided inside `.relations()` callbacks.
-
-| Method | Type | Description |
-|--------|------|-------------|
-| `r.foreignKey(cols, targetFn)` | N:1 | FK constraint created in DB |
-| `r.foreignKeyTarget(targetFn, relName)` | 1:N | Reverse FK reference (array by default) |
-| `r.relationKey(cols, targetFn)` | N:1 | Logical relation (no DB FK) |
-| `r.relationKeyTarget(targetFn, relName)` | 1:N | Logical reverse reference |
-
-Both `foreignKeyTarget` and `relationKeyTarget` support `.single()` to indicate a 1:1 relationship (returns single object instead of array).
-
----
-
-## Usage Examples
-
-### Complete Table Definition
-
-```typescript
-const User = Table("User")
-  .database("mydb")
-  .description("Application users")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-    status: c.varchar(20).default("active"),
-    createdAt: c.datetime().default("CURRENT_TIMESTAMP"),
-  }))
-  .primaryKey("id")
-  .indexes((i) => [
-    i.index("email").unique(),
-    i.index("status", "createdAt").orderBy("ASC", "DESC"),
-  ]);
-```
-
-### Table with Relations
-
-```typescript
-const Post = Table("Post")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    authorId: c.bigint(),
-    title: c.varchar(200),
-  }))
-  .primaryKey("id")
-  .relations((r) => ({
-    author: r.foreignKey(["authorId"], () => User),
-  }));
-
-const User = Table("User")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-  }))
-  .primaryKey("id")
-  .relations((r) => ({
-    posts: r.foreignKeyTarget(() => Post, "author"),
-    profile: r.foreignKeyTarget(() => Profile, "user").single(),
-  }));
-```
-
-### View Definition
-
-```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, email: u.email }))
-  );
-```
-
-### Procedure Definition
-
-```typescript
-const GetUserById = Procedure("GetUserById")
-  .database("mydb")
-  .params((c) => ({
-    userId: c.bigint(),
-  }))
-  .returns((c) => ({
-    id: c.bigint(),
-    name: c.varchar(100),
-    email: c.varchar(200),
-  }))
-  .body("SELECT id, name, email FROM User WHERE id = userId");
-```

package/docs/types-and-utilities.md

@@ -1,353 +0,0 @@
-# Types and Utilities
-
-Core type definitions, error handling, search parsing, and result parsing utilities.
-
-## API Reference
-
-### Column Types
-
-#### `DataType`
-
-SQL data type definition used in column metadata.
-
-```typescript
-type DataType =
-  | { type: "int" }
-  | { type: "bigint" }
-  | { type: "float" }
-  | { type: "double" }
-  | { type: "decimal"; precision: number; scale?: number }
-  | { type: "varchar"; length: number }
-  | { type: "char"; length: number }
-  | { type: "text" }
-  | { type: "binary" }
-  | { type: "boolean" }
-  | { type: "datetime" }
-  | { type: "date" }
-  | { type: "time" }
-  | { type: "uuid" };
-```
-
-#### `ColumnPrimitive`
-
-All primitive TypeScript types that can be stored in columns. `undefined` represents NULL.
-
-```typescript
-type ColumnPrimitive = string | number | boolean | DateTime | DateOnly | Time | Uuid | Bytes | undefined;
-```
-
-#### `ColumnPrimitiveStr`
-
-String keys for column primitive type mapping.
-
-```typescript
-type ColumnPrimitiveStr = "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes";
-```
-
-#### `ColumnMeta`
-
-Column metadata generated by `ColumnBuilder`.
-
-```typescript
-interface ColumnMeta {
-  type: ColumnPrimitiveStr;
-  dataType: DataType;
-  autoIncrement?: boolean;
-  nullable?: boolean;
-  default?: ColumnPrimitive;
-  description?: string;
-}
-```
-
-#### `inferColumnPrimitiveStr(value)`
-
-Infer `ColumnPrimitiveStr` from a runtime value.
-
-```typescript
-function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr
-```
-
-```typescript
-inferColumnPrimitiveStr("hello")        // "string"
-inferColumnPrimitiveStr(123)            // "number"
-inferColumnPrimitiveStr(new DateTime()) // "DateTime"
-```
-
-#### `dataTypeStrToColumnPrimitiveStr`
-
-Mapping from SQL type strings to TypeScript type names.
-
-```typescript
-dataTypeStrToColumnPrimitiveStr["int"]      // "number"
-dataTypeStrToColumnPrimitiveStr["varchar"]  // "string"
-dataTypeStrToColumnPrimitiveStr["datetime"] // "DateTime"
-```
-
----
-
-### Database Types
-
-#### `Dialect`
-
-Supported database dialects.
-
-```typescript
-type Dialect = "mysql" | "mssql" | "postgresql";
-```
-
-#### `dialects`
-
-Array of all supported dialects (useful for testing).
-
-```typescript
-const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
-```
-
-#### `IsolationLevel`
-
-Transaction isolation levels.
-
-```typescript
-type IsolationLevel =
-  | "READ_UNCOMMITTED"
-  | "READ_COMMITTED"
-  | "REPEATABLE_READ"
-  | "SERIALIZABLE";
-```
-
-#### `DataRecord`
-
-Recursive type for query result records (supports nested relations).
-
-```typescript
-type DataRecord = {
-  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
-};
-```
-
-#### `ResultMeta`
-
-Metadata for transforming raw query results into typed TypeScript objects.
-
-```typescript
-interface ResultMeta {
-  columns: Record<string, ColumnPrimitiveStr>;
-  joins: Record<string, { isSingle: boolean }>;
-}
-```
-
-#### `QueryBuildResult`
-
-Result of building a QueryDef into SQL.
-
-```typescript
-interface QueryBuildResult {
-  sql: string;
-  resultSetIndex?: number;
-  resultSetStride?: number;
-}
-```
-
-#### `Migration`
-
-Database migration definition.
-
-```typescript
-interface Migration {
-  name: string;
-  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
-}
-```
-
----
-
-### Error Handling
-
-#### `DbTransactionError`
-
-Standardized database transaction error with DBMS-independent error codes.
-
-```typescript
-class DbTransactionError extends Error {
-  readonly name = "DbTransactionError";
-  readonly code: DbErrorCode;
-  readonly originalError?: unknown;
-
-  constructor(code: DbErrorCode, message: string, originalError?: unknown);
-}
-```
-
-#### `DbErrorCode`
-
-Transaction-related error codes.
-
-```typescript
-enum DbErrorCode {
-  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
-  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
-  DEADLOCK = "DEADLOCK",
-  LOCK_TIMEOUT = "LOCK_TIMEOUT",
-}
-```
-
-```typescript
-try {
-  await executor.rollbackTransaction();
-} catch (err) {
-  if (err instanceof DbTransactionError) {
-    if (err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) {
-      return; // Already rolled back, safe to ignore
-    }
-  }
-  throw err;
-}
-```
-
----
-
-### Search Parser
-
-#### `parseSearchQuery(searchText)`
-
-Parse a user search string into structured SQL LIKE patterns.
-
-```typescript
-function parseSearchQuery(searchText: string): ParsedSearchQuery
-```
-
-```typescript
-interface ParsedSearchQuery {
-  or: string[];    // General terms (OR condition)
-  must: string[];  // Required terms (AND condition, + prefix or quotes)
-  not: string[];   // Excluded terms (NOT condition, - prefix)
-}
-```
-
-**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 match (required) | `"delicious fruit"` |
-| `*` | Wildcard | `app*` -> `app%` |
-
-**Escape sequences:** `\\` (literal `\`), `\*` (literal `*`), `\%` (literal `%`), `\"` (literal `"`), `\+` (literal `+`), `\-` (literal `-`)
-
-```typescript
-parseSearchQuery('apple "delicious fruit" -banana +strawberry')
-// {
-//   or: ["%apple%"],
-//   must: ["%delicious fruit%", "%strawberry%"],
-//   not: ["%banana%"]
-// }
-
-parseSearchQuery('app* test')
-// {
-//   or: ["app%", "%test%"],
-//   must: [],
-//   not: []
-// }
-```
-
----
-
-### Result Parser
-
-#### `parseQueryResult(rawResults, meta)`
-
-Transform raw database query results into typed TypeScript objects. Handles type conversion, nested JOIN result grouping, and deduplication.
-
-```typescript
-async function parseQueryResult<TRecord>(
-  rawResults: Record<string, unknown>[],
-  meta: ResultMeta,
-): Promise<TRecord[] | undefined>
-```
-
-**Features:**
-- Type conversion (string to number, string to DateTime, etc.)
-- Flat-to-nested object transformation (`"posts.id"` -> `{ posts: { id } }`)
-- JOIN result grouping with deduplication
-- Single vs array relationship handling (`isSingle`)
-- Event loop yielding for large datasets (every 100 records)
-- Returns `undefined` for empty results
-
-```typescript
-// Simple type parsing
-const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
-const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
-const result = await parseQueryResult(raw, meta);
-// [{ id: 1, createdAt: DateTime(...) }]
-
-// JOIN result nesting
-const raw = [
-  { id: 1, name: "Alice", "posts.id": 10, "posts.title": "Post1" },
-  { id: 1, name: "Alice", "posts.id": 11, "posts.title": "Post2" },
-];
-const meta = {
-  columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
-  joins: { posts: { isSingle: false } },
-};
-const result = await parseQueryResult(raw, meta);
-// [{ id: 1, name: "Alice", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
-```
-
----
-
-### QueryDef Types
-
-#### `QueryDefObjectName`
-
-Database object name with optional namespace.
-
-```typescript
-interface QueryDefObjectName {
-  database?: string;
-  schema?: string;
-  name: string;
-}
-```
-
-#### `QueryDef`
-
-Union type of all query definitions (DML + DDL + utility).
-
-Key DML types:
-
-| Type | Interface | Description |
-|------|-----------|-------------|
-| `"select"` | `SelectQueryDef` | SELECT with FROM, WHERE, JOIN, ORDER BY, GROUP BY, HAVING, LIMIT, WITH |
-| `"insert"` | `InsertQueryDef` | INSERT with records, output, overrideIdentity |
-| `"insertIfNotExists"` | `InsertIfNotExistsQueryDef` | Conditional INSERT |
-| `"insertInto"` | `InsertIntoQueryDef` | INSERT INTO ... SELECT |
-| `"update"` | `UpdateQueryDef` | UPDATE with JOIN support |
-| `"delete"` | `DeleteQueryDef` | DELETE with JOIN support |
-| `"upsert"` | `UpsertQueryDef` | INSERT or UPDATE (MERGE) |
-
-#### `DDL_TYPES`
-
-Constant array of all DDL query type strings. Used to prevent DDL execution inside transactions.
-
-```typescript
-const DDL_TYPES: readonly string[]
-// ["clearSchema", "createTable", "dropTable", "renameTable", "truncate",
-//  "addColumn", "dropColumn", "modifyColumn", "renameColumn",
-//  "dropPrimaryKey", "addPrimaryKey", "addForeignKey", "dropForeignKey",
-//  "addIndex", "dropIndex", "createView", "dropView", "createProc", "dropProc"]
-```
-
----
-
-### Type Inference Utilities
-
-| Type | Description |
-|------|-------------|
-| `InferColumns<T>` | Infer value types from ColumnBuilderRecord |
-| `InferInsertColumns<T>` | Infer INSERT type (required + optional fields) |
-| `InferUpdateColumns<T>` | Infer UPDATE type (all fields optional) |
-| `InferColumnExprs<T>` | Infer expression input types |
-| `InferDeepRelations<T>` | Infer nested relation types (all optional) |
-| `ExtractRelationTarget<T>` | Extract N:1 relation target type |
-| `ExtractRelationTargetResult<T>` | Extract 1:N relation target type (array or single) |