@simplysm/orm-common 13.0.99 → 14.0.1

package/docs/types.md

@@ -1,445 +0,0 @@
-# Types
-
-## `Dialect`
-
-Supported database dialects.
-
-```typescript
-type Dialect = "mysql" | "mssql" | "postgresql";
-```
-
-## `dialects`
-
-List of all supported database dialects.
-
-```typescript
-const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
-```
-
-## `IsolationLevel`
-
-Transaction isolation level.
-
-```typescript
-type IsolationLevel =
-  | "READ_UNCOMMITTED"
-  | "READ_COMMITTED"
-  | "REPEATABLE_READ"
-  | "SERIALIZABLE";
-```
-
-## `DataRecord`
-
-Query result data record type. Supports nested relation (include) results with recursive structure.
-
-```typescript
-type DataRecord = {
-  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
-};
-```
-
-## `DbContextExecutor`
-
-DbContext executor interface. Responsible for actual DB connection and query execution.
-
-```typescript
-interface DbContextExecutor {
-  connect(): Promise<void>;
-  close(): Promise<void>;
-  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
-  commitTransaction(): Promise<void>;
-  rollbackTransaction(): Promise<void>;
-  executeDefs<T = DataRecord>(
-    defs: QueryDef[],
-    resultMetas?: (ResultMeta | undefined)[],
-  ): Promise<T[][]>;
-}
-```
-
-| Method | Description |
-|--------|-------------|
-| `connect()` | Establish DB connection |
-| `close()` | Close DB connection |
-| `beginTransaction()` | Begin transaction with optional isolation level |
-| `commitTransaction()` | Commit transaction |
-| `rollbackTransaction()` | Rollback transaction |
-| `executeDefs()` | Execute QueryDef array and return results |
-
-## `QueryBuildResult`
-
-`QueryBuilder.build()` return type.
-
-```typescript
-interface QueryBuildResult {
-  sql: string;
-  resultSetIndex?: number;
-  resultSetStride?: number;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `sql` | `string` | Built SQL string |
-| `resultSetIndex` | `number` | Result set index to fetch results from |
-| `resultSetStride` | `number` | Extract every Nth result set from multiple results |
-
-## `ResultMeta`
-
-Metadata for query result transformation.
-
-```typescript
-interface ResultMeta {
-  columns: Record<string, ColumnPrimitiveStr>;
-  joins: Record<string, { isSingle: boolean }>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `columns` | `Record<string, ColumnPrimitiveStr>` | Column name to type mapping |
-| `joins` | `Record<string, { isSingle: boolean }>` | JOIN alias to single/array indicator |
-
-## `Migration`
-
-Database migration definition.
-
-```typescript
-interface Migration {
-  name: string;
-  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `name` | `string` | Unique migration name (timestamp recommended) |
-| `up` | `(db) => Promise<void>` | Migration execution function |
-
-## `DataType`
-
-SQL data type definition.
-
-```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" };
-```
-
-## `ColumnPrimitiveMap`
-
-Column primitive type mapping. TypeScript type name (string) to actual type.
-
-```typescript
-type ColumnPrimitiveMap = {
-  string: string;
-  number: number;
-  boolean: boolean;
-  DateTime: DateTime;
-  DateOnly: DateOnly;
-  Time: Time;
-  Uuid: Uuid;
-  Bytes: Bytes;
-};
-```
-
-## `ColumnPrimitiveStr`
-
-Column primitive type name.
-
-```typescript
-type ColumnPrimitiveStr = keyof ColumnPrimitiveMap;
-```
-
-## `ColumnPrimitive`
-
-All primitive types that can be stored in columns. `undefined` represents NULL.
-
-```typescript
-type ColumnPrimitive = ColumnPrimitiveMap[ColumnPrimitiveStr] | undefined;
-```
-
-## `dataTypeStrToColumnPrimitiveStr`
-
-SQL DataType to TypeScript type name mapping.
-
-```typescript
-const dataTypeStrToColumnPrimitiveStr: {
-  int: "number"; bigint: "number"; float: "number"; double: "number"; decimal: "number";
-  varchar: "string"; char: "string"; text: "string";
-  binary: "Bytes"; boolean: "boolean";
-  datetime: "DateTime"; date: "DateOnly"; time: "Time"; uuid: "Uuid";
-};
-```
-
-## `InferColumnPrimitiveFromDataType`
-
-TypeScript type inference from DataType.
-
-```typescript
-type InferColumnPrimitiveFromDataType<TDataType extends DataType> =
-  ColumnPrimitiveMap[(typeof dataTypeStrToColumnPrimitiveStr)[TDataType["type"]]];
-```
-
-## `inferColumnPrimitiveStr`
-
-Infer `ColumnPrimitiveStr` from a runtime value.
-
-```typescript
-function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr;
-```
-
-## `ColumnMeta`
-
-Column metadata. Generated by `ColumnBuilder` and passed to `TableBuilder`.
-
-```typescript
-interface ColumnMeta {
-  type: ColumnPrimitiveStr;
-  dataType: DataType;
-  autoIncrement?: boolean;
-  nullable?: boolean;
-  default?: ColumnPrimitive;
-  description?: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `type` | `ColumnPrimitiveStr` | TypeScript type name |
-| `dataType` | `DataType` | SQL data type |
-| `autoIncrement` | `boolean` | Whether to auto-increment |
-| `nullable` | `boolean` | Whether to allow NULL |
-| `default` | `ColumnPrimitive` | Default value |
-| `description` | `string` | Column description (DDL comment) |
-
-## `DateUnit`
-
-Date operation unit.
-
-```typescript
-type DateUnit = "year" | "month" | "day" | "hour" | "minute" | "second";
-```
-
-## `QueryDefObjectName`
-
-DB object name (table, view, procedure, etc.).
-
-```typescript
-interface QueryDefObjectName {
-  database?: string;
-  schema?: string;
-  name: string;
-}
-```
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `database` | `string` | Database name |
-| `schema` | `string` | Schema name |
-| `name` | `string` | Object name |
-
-## `QueryDef`
-
-All query definition union type. DML + DDL + Utils + Meta.
-
-```typescript
-type QueryDef =
-  | SelectQueryDef | InsertQueryDef | InsertIfNotExistsQueryDef | InsertIntoQueryDef
-  | UpdateQueryDef | DeleteQueryDef | UpsertQueryDef
-  | ClearSchemaQueryDef | CreateTableQueryDef | DropTableQueryDef | RenameTableQueryDef
-  | TruncateQueryDef | AddColumnQueryDef | DropColumnQueryDef | ModifyColumnQueryDef
-  | RenameColumnQueryDef | DropPrimaryKeyQueryDef | AddPrimaryKeyQueryDef
-  | AddForeignKeyQueryDef | DropForeignKeyQueryDef | AddIndexQueryDef | DropIndexQueryDef
-  | CreateViewQueryDef | DropViewQueryDef | CreateProcQueryDef | DropProcQueryDef
-  | ExecProcQueryDef | SwitchFkQueryDef | SchemaExistsQueryDef;
-```
-
-## `SelectQueryDef`
-
-SELECT query definition.
-
-```typescript
-interface SelectQueryDef {
-  type: "select";
-  from?: QueryDefObjectName | SelectQueryDef | SelectQueryDef[] | string;
-  as: string;
-  select?: Record<string, Expr>;
-  distinct?: boolean;
-  top?: number;
-  lock?: boolean;
-  where?: WhereExpr[];
-  joins?: SelectQueryDefJoin[];
-  orderBy?: [Expr, ("ASC" | "DESC")?][];
-  limit?: [number, number];
-  groupBy?: Expr[];
-  having?: WhereExpr[];
-  with?: { name: string; base: SelectQueryDef; recursive: SelectQueryDef };
-}
-```
-
-## `SelectQueryDefJoin`
-
-JOIN query definition. Extends `SelectQueryDef` with `isSingle` flag.
-
-```typescript
-interface SelectQueryDefJoin extends SelectQueryDef {
-  isSingle?: boolean;
-}
-```
-
-## `InsertQueryDef`
-
-INSERT query definition.
-
-```typescript
-interface InsertQueryDef {
-  type: "insert";
-  table: QueryDefObjectName;
-  records: Record<string, ColumnPrimitive>[];
-  overrideIdentity?: boolean;
-  output?: CudOutputDef;
-}
-```
-
-## `InsertIfNotExistsQueryDef`
-
-Conditional INSERT query definition. Insert only if not exists.
-
-```typescript
-interface InsertIfNotExistsQueryDef {
-  type: "insertIfNotExists";
-  table: QueryDefObjectName;
-  record: Record<string, ColumnPrimitive>;
-  existsSelectQuery: SelectQueryDef;
-  overrideIdentity?: boolean;
-  output?: CudOutputDef;
-}
-```
-
-## `InsertIntoQueryDef`
-
-INSERT INTO SELECT query definition. Insert subquery results.
-
-```typescript
-interface InsertIntoQueryDef {
-  type: "insertInto";
-  table: QueryDefObjectName;
-  recordsSelectQuery: SelectQueryDef;
-  overrideIdentity?: boolean;
-  output?: CudOutputDef;
-}
-```
-
-## `UpdateQueryDef`
-
-UPDATE query definition.
-
-```typescript
-interface UpdateQueryDef {
-  type: "update";
-  table: QueryDefObjectName;
-  as: string;
-  record: Record<string, Expr>;
-  top?: number;
-  where?: WhereExpr[];
-  joins?: SelectQueryDefJoin[];
-  limit?: [number, number];
-  output?: CudOutputDef;
-}
-```
-
-## `DeleteQueryDef`
-
-DELETE query definition.
-
-```typescript
-interface DeleteQueryDef {
-  type: "delete";
-  table: QueryDefObjectName;
-  as: string;
-  top?: number;
-  where?: WhereExpr[];
-  joins?: SelectQueryDefJoin[];
-  limit?: [number, number];
-  output?: CudOutputDef;
-}
-```
-
-## `UpsertQueryDef`
-
-UPSERT query definition. INSERT or UPDATE (MERGE pattern).
-
-```typescript
-interface UpsertQueryDef {
-  type: "upsert";
-  table: QueryDefObjectName;
-  existsSelectQuery: SelectQueryDef;
-  insertRecord: Record<string, Expr>;
-  updateRecord: Record<string, Expr>;
-  overrideIdentity?: boolean;
-  output?: CudOutputDef;
-}
-```
-
-## `CudOutputDef`
-
-CUD query OUTPUT clause definition.
-
-```typescript
-interface CudOutputDef {
-  columns: string[];
-  pkColNames: string[];
-  aiColName?: string;
-}
-```
-
-## `DDL_TYPES`
-
-DDL type constants. Used for blocking DDL within transactions.
-
-```typescript
-const DDL_TYPES: readonly string[];
-```
-
-## `DdlType`
-
-DDL type union.
-
-```typescript
-type DdlType = (typeof DDL_TYPES)[number];
-```
-
-## Expression Types (Expr)
-
-Union type `Expr` covers all expression types: value (`ExprColumn`, `ExprValue`, `ExprRaw`), string, numeric, date, conditional, aggregate, window, and subquery expressions.
-
-Union type `WhereExpr` covers comparison (`ExprEq`, `ExprGt`, `ExprLt`, `ExprGte`, `ExprLte`, `ExprBetween`, `ExprIsNull`, `ExprLike`, `ExprRegexp`, `ExprIn`, `ExprInQuery`, `ExprExists`) and logical (`ExprNot`, `ExprAnd`, `ExprOr`) expressions.
-
-## Window Types
-
-`WinFn` is a union of all window function types: `WinFnRowNumber`, `WinFnRank`, `WinFnDenseRank`, `WinFnNtile`, `WinFnLag`, `WinFnLead`, `WinFnFirstValue`, `WinFnLastValue`, `WinFnSum`, `WinFnAvg`, `WinFnCount`, `WinFnMin`, `WinFnMax`.
-
-```typescript
-interface WinSpec {
-  partitionBy?: Expr[];
-  orderBy?: [Expr, ("ASC" | "DESC")?][];
-}
-
-interface ExprWindow {
-  type: "window";
-  fn: WinFn;
-  spec: WinSpec;
-}
-```

package/docs/utilities.md

@@ -1,27 +0,0 @@
-# Utilities
-
-## `parseQueryResult`
-
-Transform raw DB query results to typed TypeScript objects via `ResultMeta`. Handles type parsing, nested object construction from flat JOIN results, and deduplication.
-
-```typescript
-async function parseQueryResult<TRecord>(
-  rawResults: Record<string, unknown>[],
-  meta: ResultMeta,
-): Promise<TRecord[] | undefined>;
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `rawResults` | `Record<string, unknown>[]` | Raw result array from database |
-| `meta` | `ResultMeta` | Type transformation and JOIN structure information |
-
-**Returns:** Type-transformed and nested result array. Returns `undefined` if input is empty or no valid results.
-
-### Behavior
-
-- **Type parsing**: Converts raw values to TypeScript types based on `meta.columns` mapping (e.g., string to `DateTime`, number to boolean).
-- **JOIN nesting**: Converts flat `"posts.id"` keys into nested `{ posts: { id: ... } }` structures.
-- **Deduplication**: Groups records by non-JOIN columns and collects JOIN data into arrays (or single objects for `isSingle: true`).
-- **Async**: Yields to the event loop every 100 records to prevent blocking.
-- **Empty handling**: Returns `undefined` for empty input or all-empty parsed records.

package/tests/db-context/create-db-context.spec.ts

@@ -1,193 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { defineDbContext } from "../../src/define-db-context";
-import { createDbContext } from "../../src/create-db-context";
-import { User } from "../setup/models/User";
-import { Post } from "../setup/models/Post";
-import { MockExecutor } from "../setup/MockExecutor";
-import "../setup/test-utils";
-
-const TestDb = defineDbContext({
-  tables: { user: User, post: Post },
-});
-
-describe("createDbContext", () => {
-  it("creates instance with queryable accessors", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-
-    expect(db.database).toBe("TestDb");
-    expect(db.schema).toBe("TestSchema");
-    expect(db.status).toBe("ready");
-    expect(typeof db.user).toBe("function");
-    expect(typeof db.post).toBe("function");
-  });
-
-  it("queryable functions create correct QueryDef", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-
-    const def = db.user().getSelectQueryDef();
-    expect(def).toEqual({
-      type: "select",
-      as: "T1",
-      from: { database: "TestDb", schema: "TestSchema", name: "User" },
-    });
-  });
-
-  it("alias counter increments between queryable calls", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-
-    const userDef = db.user().getSelectQueryDef();
-    const postDef = db.post().getSelectQueryDef();
-    expect(userDef.as).toBe("T1");
-    expect(postDef.as).toBe("T2");
-  });
-
-  it("DDL QueryDef generators produce correct output", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-
-    const clearDef = db.getClearSchemaQueryDef({ database: "TestDb", schema: "TestSchema" });
-    expect(clearDef).toEqual({
-      type: "clearSchema",
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-  });
-
-  it("connect/transaction methods exist", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    expect(typeof db.connect).toBe("function");
-    expect(typeof db.connectWithoutTransaction).toBe("function");
-    expect(typeof db.transaction).toBe("function");
-  });
-
-  it("connect manages status lifecycle", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    expect(db.status).toBe("ready");
-    await db.connect(async () => {
-      await Promise.resolve();
-      expect(db.status).toBe("transact");
-    });
-    expect(db.status).toBe("ready");
-  });
-
-  it("connectWithoutTransaction manages status lifecycle", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    expect(db.status).toBe("ready");
-    await db.connectWithoutTransaction(async () => {
-      await Promise.resolve();
-      expect(db.status).toBe("connect");
-    });
-    expect(db.status).toBe("ready");
-  });
-
-  it("transaction manages status lifecycle within connectWithoutTransaction", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    await db.connectWithoutTransaction(async () => {
-      await Promise.resolve();
-      expect(db.status).toBe("connect");
-      await db.transaction(async () => {
-        await Promise.resolve();
-        expect(db.status).toBe("transact");
-      });
-      expect(db.status).toBe("connect");
-    });
-    expect(db.status).toBe("ready");
-  });
-
-  it("connect resets alias counter", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    // Use some aliases
-    db.getNextAlias(); // T1
-    db.getNextAlias(); // T2
-
-    await db.connect(async () => {
-      await Promise.resolve();
-      // After connect, alias counter should be reset
-      const userDef = db.user().getSelectQueryDef();
-      expect(userDef.as).toBe("T1");
-    });
-  });
-
-  it("connect rolls back and rethrows on callback error", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    const testError = new Error("test error");
-    await expect(
-      db.connect(async () => {
-        await Promise.resolve();
-        throw testError;
-      }),
-    ).rejects.toThrow("test error");
-
-    expect(db.status).toBe("ready");
-  });
-
-  it("connectWithoutTransaction rethrows on callback error", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    const testError = new Error("test error");
-    await expect(
-      db.connectWithoutTransaction(async () => {
-        await Promise.resolve();
-        throw testError;
-      }),
-    ).rejects.toThrow("test error");
-
-    expect(db.status).toBe("ready");
-  });
-
-  it("transaction throws when already in transaction state", async () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-    });
-
-    await db.connect(async () => {
-      // Already in transact state via connect
-      await expect(db.transaction(async () => {})).rejects.toThrow("Already in TRANSACTION state.");
-    });
-  });
-
-  it("getQueryDefObjectName resolves table with defaults", () => {
-    const db = createDbContext(TestDb, new MockExecutor(), {
-      database: "TestDb",
-      schema: "TestSchema",
-    });
-
-    const objName = db.getQueryDefObjectName(User);
-    expect(objName).toEqual({
-      database: "TestDb",
-      schema: "TestSchema",
-      name: "User",
-    });
-  });
-});

package/tests/db-context/define-db-context.spec.ts

@@ -1,17 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { defineDbContext } from "../../src/define-db-context";
-import { User } from "../setup/models/User";
-import { Post } from "../setup/models/Post";
-
-describe("defineDbContext", () => {
-  it("creates a DbContextDef with tables", () => {
-    const MyDb = defineDbContext({
-      tables: { user: User, post: Post },
-    });
-
-    expect(MyDb.meta.tables.user).toBe(User);
-    expect(MyDb.meta.tables.post).toBe(Post);
-    expect(MyDb.meta.migrations).toEqual([]);
-  });
-
-});