@simplysm/orm-common 13.0.29 → 13.0.30

package/README.md

@@ -38,8 +38,8 @@ See [docs/schema.md](docs/schema.md) for full documentation.
 
 See [docs/queries.md](docs/queries.md) for full documentation.
 
-- **[Connection & Transactions](docs/queries.md#connection-and-transactions)** - `db.connect()`, `db.connectWithoutTransaction()`
-- **[SELECT Queries](docs/queries.md#select-queries)** - `.where()`, `.select()`, `.single()`, `.first()`, `.result()`, `.count()`, `.exists()`
+- **[Connection & Transactions](docs/queries.md#connection-and-transactions)** - `db.connect()`, `db.connectWithoutTransaction()`, `db.trans()`
+- **[SELECT Queries](docs/queries.md#select-queries)** - `.where()`, `.select()`, `.distinct()`, `.orderBy()`, `.single()`, `.first()`, `.result()`, `.count()`, `.exists()`
 - **[JOIN Queries](docs/queries.md#join-queries)** - `.join()`, `.joinSingle()`, `.include()`
 - **[Grouping & Aggregation](docs/queries.md#grouping-and-aggregation)** - `.groupBy()`, `.having()`
 - **[Pagination](docs/queries.md#pagination)** - `.top()`, `.limit()`
@@ -67,7 +67,7 @@ See [docs/expressions.md](docs/expressions.md) for full documentation.
 - **[Date Expressions](docs/expressions.md#date-expressions)** - `expr.year()`, `expr.month()`, `expr.day()`, `expr.dateDiff()`, `expr.dateAdd()`, `expr.formatDate()`
 - **[Conditional Expressions](docs/expressions.md#conditional-expressions)** - `expr.ifNull()`, `expr.nullIf()`, `expr.if()`, `expr.switch()`
 - **[Aggregate Expressions](docs/expressions.md#aggregate-expressions)** - `expr.count()`, `expr.sum()`, `expr.avg()`, `expr.max()`, `expr.min()`, `expr.greatest()`, `expr.least()`
-- **[Window Functions](docs/expressions.md#window-functions)** - `expr.rowNumber()`, `expr.rank()`, `expr.denseRank()`, `expr.lag()`, `expr.lead()`, `expr.sumOver()`, `expr.avgOver()`
+- **[Window Functions](docs/expressions.md#window-functions)** - `expr.rowNumber()`, `expr.rank()`, `expr.denseRank()`, `expr.ntile()`, `expr.lag()`, `expr.lead()`, `expr.firstValue()`, `expr.lastValue()`, `expr.sumOver()`, `expr.avgOver()`, `expr.countOver()`, `expr.minOver()`, `expr.maxOver()`
 - **[Other Expressions](docs/expressions.md#other-expressions)** - `expr.val()`, `expr.raw()`, `expr.cast()`, `expr.subquery()`, `expr.random()`
 
 ## DbContext API
@@ -109,6 +109,32 @@ await db.connect(async () => {
 });
 ```
 
+#### `defineDbContext(config)`
+
+Creates a `DbContextDef` schema blueprint without any runtime state.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config.tables` | `Record<string, TableBuilder>` | Table builders |
+| `config.views` | `Record<string, ViewBuilder>` | View builders |
+| `config.procedures` | `Record<string, ProcedureBuilder>` | Procedure builders |
+| `config.migrations` | `Migration[]` | Migration list |
+
+Returns `DbContextDef<TTables, TViews, TProcedures>`.
+
+#### `createDbContext(def, executor, opt)`
+
+Creates a fully functional `DbContextInstance` from a `DbContextDef`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `def` | `DbContextDef` | Schema definition from `defineDbContext()` |
+| `executor` | `DbContextExecutor` | Query executor (from `orm-node` or service client) |
+| `opt.database` | `string` | Default database name |
+| `opt.schema` | `string?` | Default schema name (MSSQL: `dbo`, PostgreSQL: `public`) |
+
+Returns `DbContextInstance<TDef>`.
+
 #### Type Definitions
 
 | Type | Description |
@@ -116,6 +142,9 @@ await db.connect(async () => {
 | `DbContextDef<TTables, TViews, TProcedures>` | DbContext definition (schema blueprint) |
 | `DbContextInstance<TDef>` | Full DbContext instance with queryable accessors and DDL methods |
 | `DbContextBase` | Core interface used internally (status, executeDefs, etc.) |
+| `DbContextConnectionMethods` | Interface for connection/transaction methods (`connect`, `connectWithoutTransaction`, `trans`) |
+| `DbContextDdlMethods` | Interface for all DDL methods and QueryDef generator methods |
+| `DbContextStatus` | `"ready" \| "connect" \| "transact"` — current connection status |
 
 ### Class-based API (Removed)
 
@@ -193,6 +222,184 @@ async function doSomething(db: MyDb) {
 }
 ```
 
+## Low-Level Utilities
+
+### `queryable(db, tableOrView, as?)`
+
+Factory function that returns a `() => Queryable` accessor. Used internally by `createDbContext` to attach table/view accessors, but can also be used directly when building custom db context wrappers.
+
+```typescript
+import { queryable } from "@simplysm/orm-common";
+
+const getUserQueryable = queryable(db, User);
+const users = await getUserQueryable().where((u) => [expr.eq(u.isActive, true)]).result();
+```
+
+### `executable(db, procedureBuilder)`
+
+Factory function that returns a `() => Executable` accessor. Used internally by `createDbContext`.
+
+```typescript
+import { executable } from "@simplysm/orm-common";
+
+const getUser = executable(db, GetUserById);
+const result = await getUser().execute({ userId: 1 });
+```
+
+### `parseQueryResult(rawResults, meta)`
+
+Parses raw DB query results into typed TypeScript objects. Handles type coercion and JOIN result grouping/nesting.
+
+```typescript
+import { parseQueryResult } from "@simplysm/orm-common";
+
+const meta = {
+  columns: { id: "number", name: "string", createdAt: "DateTime" },
+  joins: {},
+};
+const result = await parseQueryResult(rawResults, meta);
+```
+
+### `parseSearchQuery(searchText)`
+
+Parses a search query string into SQL LIKE patterns for use with `.search()`.
+
+```typescript
+import { parseSearchQuery } from "@simplysm/orm-common";
+
+const parsed = parseSearchQuery('apple "exact phrase" +required -excluded');
+// { or: ["%apple%"], must: ["%exact phrase%", "%required%"], not: ["%excluded%"] }
+```
+
+Returns `ParsedSearchQuery`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `or` | `string[]` | OR conditions (LIKE patterns) |
+| `must` | `string[]` | Required AND conditions (LIKE patterns) |
+| `not` | `string[]` | NOT conditions (LIKE patterns) |
+
+### `createQueryBuilder(dialect)`
+
+Creates a dialect-specific `QueryBuilderBase` instance for converting `QueryDef` JSON AST to SQL strings.
+
+```typescript
+import { createQueryBuilder } from "@simplysm/orm-common";
+
+const builder = createQueryBuilder("mysql"); // "mysql" | "mssql" | "postgresql"
+const { sql } = builder.build(queryDef);
+```
+
+### `createColumnFactory()`
+
+Creates a column type factory used in `TableBuilder.columns()` and `ProcedureBuilder.params()/returns()`. Can also be used standalone for DDL migrations.
+
+```typescript
+import { createColumnFactory } from "@simplysm/orm-common";
+
+const c = createColumnFactory();
+await db.addColumn({ database: "mydb", name: "User" }, "status", c.varchar(20).nullable());
+```
+
+## Expression Types
+
+### `ExprUnit<TPrimitive>`
+
+Type-safe expression wrapper. All `expr.*` methods return `ExprUnit`. The generic parameter tracks the TypeScript return type of the expression.
+
+```typescript
+import { ExprUnit } from "@simplysm/orm-common";
+```
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `dataType` | `ColumnPrimitiveStr` | Runtime type name |
+| `expr` | `Expr` | Raw JSON AST |
+| `n` | `ExprUnit<NonNullable<TPrimitive>>` | Non-nullable accessor (strips `undefined`) |
+
+### `WhereExprUnit`
+
+Wrapper for WHERE condition expressions. All comparison and logical `expr.*` methods return `WhereExprUnit`.
+
+### `ExprInput<TPrimitive>`
+
+Union type that accepts either an `ExprUnit<TPrimitive>` or a plain literal value. Most `expr.*` parameters accept `ExprInput` so you can pass raw values without wrapping in `expr.val()`.
+
+```typescript
+type ExprInput<TPrimitive> = ExprUnit<TPrimitive> | TPrimitive;
+```
+
+### `QueryableRecord<TData>`
+
+Maps a data record type to its expression counterpart. Each primitive field becomes `ExprUnit`, each array field becomes `QueryableRecord[]`, and each nested object becomes `QueryableRecord`.
+
+### `SwitchExprBuilder<TPrimitive>`
+
+Builder interface returned by `expr.switch()`:
+
+| Method | Description |
+|--------|-------------|
+| `.case(condition, then)` | Add WHEN ... THEN branch |
+| `.default(value)` | Add ELSE and finalize to `ExprUnit` |
+
+### `toExpr(value)`
+
+Converts an `ExprInput` to a raw `Expr` JSON AST. Used internally; exposed for custom QueryBuilder extensions.
+
+## Type Reference
+
+### Column Types
+
+| Type | Description |
+|------|-------------|
+| `ColumnPrimitive` | Union of all column-storable TypeScript types (`string \| number \| boolean \| DateTime \| DateOnly \| Time \| Uuid \| Bytes \| undefined`) |
+| `ColumnPrimitiveStr` | String key of `ColumnPrimitiveMap` — `"string" \| "number" \| "boolean" \| "DateTime" \| "DateOnly" \| "Time" \| "Uuid" \| "Bytes"` |
+| `ColumnPrimitiveMap` | Mapping from `ColumnPrimitiveStr` → TypeScript type |
+| `DataType` | SQL data type discriminated union (`{ type: "int" }`, `{ type: "varchar"; length: number }`, etc.) |
+| `ColumnMeta` | Column metadata stored inside `ColumnBuilder` |
+| `InferColumnPrimitiveFromDataType<T>` | TypeScript type from a `DataType` |
+| `dataTypeStrToColumnPrimitiveStr` | Constant object mapping SQL type name → `ColumnPrimitiveStr` |
+| `inferColumnPrimitiveStr(value)` | Runtime function: infer `ColumnPrimitiveStr` from a value |
+
+#### SQL Type to TypeScript Type Mapping
+
+| SQL Type | TypeScript Type | Notes |
+|----------|----------------|-------|
+| `int`, `bigint`, `float`, `double`, `decimal` | `number` | `bigint` means SQL BIGINT (8 bytes), not JS `BigInt` |
+| `varchar`, `char`, `text` | `string` | |
+| `boolean` | `boolean` | MySQL: TINYINT(1), MSSQL: BIT |
+| `datetime` | `DateTime` | From `@simplysm/core-common` |
+| `date` | `DateOnly` | From `@simplysm/core-common` |
+| `time` | `Time` | From `@simplysm/core-common` |
+| `uuid` | `Uuid` | From `@simplysm/core-common` |
+| `binary` | `Bytes` | `Uint8Array` |
+
+### Database Types
+
+| Type/Const | Description |
+|------------|-------------|
+| `Dialect` | `"mysql" \| "mssql" \| "postgresql"` |
+| `dialects` | `Dialect[]` constant — all supported dialects |
+| `IsolationLevel` | `"READ_UNCOMMITTED" \| "READ_COMMITTED" \| "REPEATABLE_READ" \| "SERIALIZABLE"` |
+| `DataRecord` | Recursive query result type: `{ [key: string]: ColumnPrimitive \| DataRecord \| DataRecord[] }` |
+| `DbContextExecutor` | Interface that actual DB connectors implement |
+| `ResultMeta` | Metadata for converting raw query results (`{ columns, joins }`) |
+| `Migration` | `{ name: string; up: (db) => Promise<void> }` |
+| `QueryBuildResult` | `{ sql: string; resultSetIndex?: number; resultSetStride?: number }` |
+
+### Schema Builder Types
+
+| Type | Description |
+|------|-------------|
+| `ColumnBuilderRecord` | `Record<string, ColumnBuilder<...>>` |
+| `RelationBuilderRecord` | Union record of all relation builder types |
+| `InferColumns<T>` | Infer column value types from a `ColumnBuilderRecord` |
+| `InferInsertColumns<T>` | INSERT type (required + optional fields) |
+| `InferUpdateColumns<T>` | UPDATE type (all optional) |
+| `InferColumnExprs<T>` | Expression input type from a `ColumnBuilderRecord` |
+| `InferDeepRelations<T>` | Infer relation types (all optional) |
+| `PathProxy<TObject>` | Type-safe path proxy for `.include()` navigation |
+
 ## Security Notes
 
 orm-common uses **enhanced string escaping** instead of parameter binding due to its dynamic query nature.

package/docs/queries.md

@@ -3,8 +3,10 @@
 ## Connection and Transactions
 
 ```typescript
-// executor is NodeDbContextExecutor from orm-node package, etc.
-const db = new MyDb(executor, { database: "mydb" });
+import { defineDbContext, createDbContext } from "@simplysm/orm-common";
+
+const MyDbDef = defineDbContext({ tables: { user: User } });
+const db = createDbContext(MyDbDef, executor, { database: "mydb" });
 
 // Execute within transaction (auto commit/rollback)
 const users = await db.connect(async () => {
@@ -13,17 +15,33 @@ const users = await db.connect(async () => {
   return result;
 });
 
-// Connect without transaction (for DDL operations)
+// Connect without transaction (for DDL operations or read-only queries)
 await db.connectWithoutTransaction(async () => {
   await db.initialize(); // Code First initialization
 });
 
+// Partial transaction within connectWithoutTransaction
+await db.connectWithoutTransaction(async () => {
+  const report = await db.report().result(); // read without transaction
+  await db.trans(async () => {
+    await db.log().insert([{ message: "accessed" }]); // write with transaction
+  });
+});
+
 // Specify isolation level
 await db.connect(async () => {
   // ...
 }, "SERIALIZABLE");
 ```
 
+### Connection Methods
+
+| Method | Description |
+|--------|-------------|
+| `db.connect(fn, isolationLevel?)` | Open connection, begin transaction, run fn, commit. Auto-rollback on error. |
+| `db.connectWithoutTransaction(fn)` | Open connection without transaction, run fn, close. |
+| `db.trans(fn, isolationLevel?)` | Begin transaction on an already-connected db. Must be called inside `connectWithoutTransaction`. |
+
 ## SELECT Queries
 
 ```typescript
@@ -41,6 +59,12 @@ const names = await db.user()
   }))
   .result();
 
+// Distinct rows
+const uniqueNames = await db.user()
+  .select((u) => ({ name: u.name }))
+  .distinct()
+  .result();
+
 // Single result (error if 2 or more)
 const user = await db.user()
   .where((u) => [expr.eq(u.id, 1)])
@@ -62,6 +86,22 @@ const hasAdmin = await db.user()
   .exists();
 ```
 
+### Queryable Method Reference
+
+| Method | Description |
+|--------|-------------|
+| `.select(fn)` | Map columns to a new shape |
+| `.distinct()` | Remove duplicate rows |
+| `.where(fn)` | Add WHERE condition (multiple calls = AND) |
+| `.orderBy(fn, dir?)` | Add ORDER BY (`"ASC"` or `"DESC"`, default `"ASC"`) |
+| `.top(n)` | Return at most n rows |
+| `.limit(skip, take)` | Paginate (requires `orderBy` first) |
+| `.result()` | Execute and return all rows |
+| `.single()` | Execute, return first row, error if > 1 row |
+| `.first()` | Execute, return first row only |
+| `.count(fn?)` | Execute COUNT query |
+| `.exists()` | Return true if any row matches |
+
 ## JOIN Queries
 
 ```typescript
@@ -277,7 +317,7 @@ await db.connect(async () => {
 
 ## DDL Operations
 
-`DbContext` supports Code First DDL operations.
+`DbContextInstance` supports Code First DDL operations.
 
 ```typescript
 await db.connectWithoutTransaction(async () => {
@@ -296,9 +336,43 @@ await db.connectWithoutTransaction(async () => {
 
   await db.renameTable({ database: "mydb", name: "User" }, "Member");
   await db.truncate({ database: "mydb", name: "User" });
+
+  // Table existence / schema check
+  const exists = await db.schemaExists("mydb");
+
+  // FK management
+  await db.switchFk({ database: "mydb", name: "User" }, "off");
+  await db.switchFk({ database: "mydb", name: "User" }, "on");
 });
 ```
 
+### DDL Method Reference
+
+| Method | Description |
+|--------|-------------|
+| `db.initialize(opts?)` | Create all tables, views, procedures, FKs, indexes per schema. `opts.force` drops before recreating. |
+| `db.createTable(table)` | CREATE TABLE |
+| `db.dropTable(name)` | DROP TABLE |
+| `db.renameTable(name, newName)` | Rename table |
+| `db.createView(view)` | CREATE VIEW |
+| `db.dropView(name)` | DROP VIEW |
+| `db.createProc(proc)` | CREATE PROCEDURE |
+| `db.dropProc(name)` | DROP PROCEDURE |
+| `db.addColumn(table, col, builder)` | ALTER TABLE ADD COLUMN |
+| `db.dropColumn(table, col)` | ALTER TABLE DROP COLUMN |
+| `db.modifyColumn(table, col, builder)` | ALTER TABLE MODIFY COLUMN |
+| `db.renameColumn(table, col, newName)` | Rename column |
+| `db.addPk(table, cols)` | Add primary key constraint |
+| `db.dropPk(table)` | Drop primary key constraint |
+| `db.addFk(table, relName, fkBuilder)` | Add foreign key constraint |
+| `db.dropFk(table, relName)` | Drop foreign key constraint |
+| `db.addIdx(table, idxBuilder)` | Add index |
+| `db.dropIdx(table, cols)` | Drop index |
+| `db.clearSchema(params)` | Drop all objects in schema |
+| `db.schemaExists(database, schema?)` | Check if schema exists |
+| `db.truncate(table)` | TRUNCATE TABLE |
+| `db.switchFk(table, "on"\|"off")` | Enable/disable FK constraints |
+
 ## Query Builder (SQL Generation)
 
 Converts `QueryDef` JSON AST to DBMS-specific SQL strings.
@@ -318,6 +392,16 @@ const queryDef = db.user()
 const { sql } = mysqlBuilder.build(queryDef);
 ```
 
+`QueryBuilderBase.build(def)` accepts any `QueryDef` and returns `QueryBuildResult`:
+
+```typescript
+interface QueryBuildResult {
+  sql: string;
+  resultSetIndex?: number;   // which result set index to use (for multi-result queries)
+  resultSetStride?: number;  // stride for multi-result queries (MySQL INSERT with OUTPUT)
+}
+```
+
 ## Error Handling
 
 ```typescript
@@ -345,7 +429,7 @@ try {
 
 | Code | Description |
 |------|------|
-| `NO_ACTIVE_TRANSACTION` | No active transaction |
+| `NO_ACTIVE_TRANSACTION` | No active transaction (e.g. rollback with no transaction open) |
 | `TRANSACTION_ALREADY_STARTED` | Transaction already started |
 | `DEADLOCK` | Deadlock occurred |
 | `LOCK_TIMEOUT` | Lock timeout |

package/docs/schema.md

@@ -139,32 +139,24 @@ await db.connect(async () => {
 });
 ```
 
-### Class-based API (Deprecated)
+### Low-level Utilities (Advanced)
+
+`queryable()` and `executable()` are the underlying factory functions used internally by `createDbContext()`. They can be used directly when implementing a custom `DbContextBase`.
 
 ```typescript
-import { DbContext, queryable, executable, createColumnFactory } from "@simplysm/orm-common";
+import { queryable, executable, type DbContextBase } from "@simplysm/orm-common";
 
-class MyDb extends DbContext {
-  readonly user = queryable(this, User);
-  readonly post = queryable(this, Post);
-  readonly getUserById = executable(this, GetUserById);
+// queryable(db, tableOrView, as?) - creates a () => Queryable factory
+const getUserQueryable = queryable(db, User);
+const userQueryable = getUserQueryable(); // returns Queryable<UserData, typeof User>
 
-  readonly migrations = [
-    {
-      name: "20260101_add_status",
-      up: async (db: MyDb) => {
-        const c = createColumnFactory();
-        await db.addColumn(
-          { database: "mydb", name: "User" },
-          "status",
-          c.varchar(20).nullable(),
-        );
-      },
-    },
-  ];
-}
+// executable(db, procedure) - creates a () => Executable factory
+const getByIdExecutable = executable(db, GetUserById);
+const exec = getByIdExecutable(); // returns Executable<Params, Returns>
 ```
 
+> For most use cases, `createDbContext()` is preferred and manages `queryable`/`executable` automatically.
+
 ## View Definition
 
 ```typescript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.29",
+  "version": "13.0.30",
   "description": "심플리즘 패키지 - ORM 모듈 (common)",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -19,6 +19,6 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.29"
+    "@simplysm/core-common": "13.0.30"
   }
 }