@simplysm/orm-common 13.0.69 → 13.0.71

package/docs/expressions.md

@@ -1,172 +0,0 @@
-# Expressions (expr)
-
-The `expr` object generates Dialect-independent SQL expressions. It creates JSON AST instead of SQL strings, which the `QueryBuilder` converts for each DBMS.
-
-## Comparison Expressions (WHERE)
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.eq(a, b)` | `a = b` (NULL-safe) | Equality comparison |
-| `expr.gt(a, b)` | `a > b` | Greater than |
-| `expr.lt(a, b)` | `a < b` | Less than |
-| `expr.gte(a, b)` | `a >= b` | Greater than or equal |
-| `expr.lte(a, b)` | `a <= b` | Less than or equal |
-| `expr.between(a, from, to)` | `a BETWEEN from AND to` | Range (unbounded in direction if undefined) |
-| `expr.null(a)` | `a IS NULL` | NULL check |
-| `expr.like(a, pattern)` | `a LIKE pattern` | Pattern matching |
-| `expr.regexp(a, pattern)` | `a REGEXP pattern` | Regex matching |
-| `expr.in(a, values)` | `a IN (v1, v2, ...)` | Value list comparison |
-| `expr.inQuery(a, query)` | `a IN (SELECT ...)` | Subquery comparison |
-| `expr.exists(query)` | `EXISTS (SELECT ...)` | Subquery existence |
-
-## Logical Expressions (WHERE)
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.and(conditions)` | `(c1 AND c2 AND ...)` | All conditions met |
-| `expr.or(conditions)` | `(c1 OR c2 OR ...)` | At least one condition met |
-| `expr.not(condition)` | `NOT (condition)` | Negate condition |
-
-## String Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.concat(...args)` | `CONCAT(a, b, ...)` | String concatenation |
-| `expr.left(s, n)` | `LEFT(s, n)` | Extract n chars from left |
-| `expr.right(s, n)` | `RIGHT(s, n)` | Extract n chars from right |
-| `expr.trim(s)` | `TRIM(s)` | Trim whitespace from both sides |
-| `expr.padStart(s, n, fill)` | `LPAD(s, n, fill)` | Left padding |
-| `expr.replace(s, from, to)` | `REPLACE(s, from, to)` | String replacement |
-| `expr.upper(s)` | `UPPER(s)` | Convert to uppercase |
-| `expr.lower(s)` | `LOWER(s)` | Convert to lowercase |
-| `expr.length(s)` | `CHAR_LENGTH(s)` | Character count |
-| `expr.byteLength(s)` | `OCTET_LENGTH(s)` | Byte count |
-| `expr.substring(s, start, len)` | `SUBSTRING(s, start, len)` | Substring extraction (1-based) |
-| `expr.indexOf(s, search)` | `LOCATE(search, s)` | Find position (1-based, 0 if not found) |
-
-## Numeric Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.abs(n)` | `ABS(n)` | Absolute value |
-| `expr.round(n, digits)` | `ROUND(n, digits)` | Round |
-| `expr.ceil(n)` | `CEILING(n)` | Ceiling |
-| `expr.floor(n)` | `FLOOR(n)` | Floor |
-
-## Date Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.year(d)` | `YEAR(d)` | Extract year |
-| `expr.month(d)` | `MONTH(d)` | Extract month (1~12) |
-| `expr.day(d)` | `DAY(d)` | Extract day (1~31) |
-| `expr.hour(d)` | `HOUR(d)` | Extract hour (0~23) |
-| `expr.minute(d)` | `MINUTE(d)` | Extract minute (0~59) |
-| `expr.second(d)` | `SECOND(d)` | Extract second (0~59) |
-| `expr.isoWeek(d)` | `WEEK(d, 3)` | ISO week (1~53) |
-| `expr.isoWeekStartDate(d)` | - | ISO week start date (Monday) |
-| `expr.isoYearMonth(d)` | - | First day of the month |
-| `expr.dateDiff(sep, from, to)` | `DATEDIFF(sep, from, to)` | Date difference |
-| `expr.dateAdd(sep, source, value)` | `DATEADD(sep, value, source)` | Add to date |
-| `expr.formatDate(d, format)` | `DATE_FORMAT(d, format)` | Date formatting |
-
-`DateSeparator`: `"year"`, `"month"`, `"day"`, `"hour"`, `"minute"`, `"second"`
-
-## Conditional Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.ifNull(a, b, ...)` | `COALESCE(a, b, ...)` | Return first non-null value |
-| `expr.nullIf(a, b)` | `NULLIF(a, b)` | NULL if `a === b` |
-| `expr.is(condition)` | `(condition)` | Convert WHERE to boolean |
-| `expr.if(cond, then, else)` | `IF(cond, then, else)` | Ternary condition |
-| `expr.switch()` | `CASE WHEN ... END` | Multiple condition branching |
-
-```typescript
-// CASE WHEN usage example
-db.user().select((u) => ({
-  grade: expr.switch<string>()
-    .case(expr.gte(u.score, 90), "A")
-    .case(expr.gte(u.score, 80), "B")
-    .case(expr.gte(u.score, 70), "C")
-    .default("F"),
-}))
-```
-
-## Aggregate Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.count(col?, distinct?)` | `COUNT(*)` / `COUNT(DISTINCT col)` | Row count |
-| `expr.sum(col)` | `SUM(col)` | Sum |
-| `expr.avg(col)` | `AVG(col)` | Average |
-| `expr.max(col)` | `MAX(col)` | Maximum |
-| `expr.min(col)` | `MIN(col)` | Minimum |
-| `expr.greatest(...args)` | `GREATEST(a, b, ...)` | Greatest among multiple values |
-| `expr.least(...args)` | `LEAST(a, b, ...)` | Least among multiple values |
-
-## Window Functions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.rowNumber(spec)` | `ROW_NUMBER() OVER (...)` | Row number |
-| `expr.rank(spec)` | `RANK() OVER (...)` | Rank (gaps on ties) |
-| `expr.denseRank(spec)` | `DENSE_RANK() OVER (...)` | Dense rank (consecutive) |
-| `expr.ntile(n, spec)` | `NTILE(n) OVER (...)` | Split into n groups |
-| `expr.lag(col, spec, opts?)` | `LAG(col, offset) OVER (...)` | Previous row value |
-| `expr.lead(col, spec, opts?)` | `LEAD(col, offset) OVER (...)` | Next row value |
-| `expr.firstValue(col, spec)` | `FIRST_VALUE(col) OVER (...)` | First value |
-| `expr.lastValue(col, spec)` | `LAST_VALUE(col) OVER (...)` | Last value |
-| `expr.sumOver(col, spec)` | `SUM(col) OVER (...)` | Window sum |
-| `expr.avgOver(col, spec)` | `AVG(col) OVER (...)` | Window average |
-| `expr.countOver(spec, col?)` | `COUNT(*) OVER (...)` | Window count |
-| `expr.minOver(col, spec)` | `MIN(col) OVER (...)` | Window minimum |
-| `expr.maxOver(col, spec)` | `MAX(col) OVER (...)` | Window maximum |
-
-`WinSpec`: `{ partitionBy?: [...], orderBy?: [[col, "ASC"|"DESC"], ...] }`
-
-```typescript
-// Window function usage example
-db.order().select((o) => ({
-  ...o,
-  rowNum: expr.rowNumber({
-    partitionBy: [o.userId],
-    orderBy: [[o.createdAt, "DESC"]],
-  }),
-  runningTotal: expr.sumOver(o.amount, {
-    partitionBy: [o.userId],
-    orderBy: [[o.createdAt, "ASC"]],
-  }),
-}))
-```
-
-## Other Expressions
-
-| Method | SQL | Description |
-|--------|-----|------|
-| `expr.val(dataType, value)` | Literal | Wrap typed value |
-| `expr.col(dataType, ...path)` | Column reference | Create column reference (internal) |
-| `expr.raw(dataType)\`sql\`` | Raw SQL | Escape hatch for DBMS-specific functions |
-| `expr.rowNum()` | - | Total row number |
-| `expr.random()` | `RAND()` / `RANDOM()` | Random number 0~1 |
-| `expr.cast(source, type)` | `CAST(source AS type)` | Type conversion |
-| `expr.subquery(dataType, qr)` | `(SELECT ...)` | Scalar subquery |
-
-```typescript
-// Raw SQL (using DBMS-specific functions)
-db.user().select((u) => ({
-  name: u.name,
-  data: expr.raw("string")`JSON_EXTRACT(${u.metadata}, '$.email')`,
-}))
-
-// Scalar subquery
-db.user().select((u) => ({
-  id: u.id,
-  postCount: expr.subquery(
-    "number",
-    db.post()
-      .where((p) => [expr.eq(p.userId, u.id)])
-      .select(() => ({ cnt: expr.count() }))
-  ),
-}))
-```

package/docs/queries.md

@@ -1,444 +0,0 @@
-# Query Operations
-
-## Connection and Transactions
-
-```typescript
-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 () => {
-  const result = await db.user().result();
-  await db.user().insert([{ name: "John Doe", createdAt: DateTime.now() }]);
-  return result;
-});
-
-// 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
-// Basic query
-const users = await db.user()
-  .where((u) => [expr.eq(u.isActive, true)])
-  .orderBy((u) => u.name)
-  .result();
-
-// Column selection
-const names = await db.user()
-  .select((u) => ({
-    userName: u.name,
-    userEmail: u.email,
-  }))
-  .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)])
-  .single();
-
-// First result only
-const latest = await db.user()
-  .orderBy((u) => u.createdAt, "DESC")
-  .first();
-
-// Row count
-const count = await db.user()
-  .where((u) => [expr.eq(u.isActive, true)])
-  .count();
-
-// Existence check
-const hasAdmin = await db.user()
-  .where((u) => [expr.eq(u.role, "admin")])
-  .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
-// Manual JOIN (1:N - array)
-const usersWithPosts = await db.user()
-  .join("posts", (qr, u) =>
-    qr.from(Post).where((p) => [expr.eq(p.authorId, u.id)])
-  )
-  .result();
-// Result: { id, name, posts: [{ id, title }, ...] }
-
-// Manual JOIN (N:1 - single object)
-const postsWithUser = await db.post()
-  .joinSingle("author", (qr, p) =>
-    qr.from(User).where((u) => [expr.eq(u.id, p.authorId)])
-  )
-  .result();
-// Result: { id, title, author: { id, name } | undefined }
-
-// include (auto JOIN based on relationship definition)
-const postWithAuthor = await db.post()
-  .include((p) => p.author)
-  .single();
-
-// Nested include
-const postWithAuthorCompany = await db.post()
-  .include((p) => p.author.company)
-  .result();
-
-// Multiple includes
-const userWithAll = await db.user()
-  .include((u) => u.posts)
-  .include((u) => u.profile)
-  .result();
-```
-
-## Grouping and Aggregation
-
-```typescript
-const stats = await db.order()
-  .select((o) => ({
-    userId: o.userId,
-    totalAmount: expr.sum(o.amount),
-    orderCount: expr.count(),
-  }))
-  .groupBy((o) => [o.userId])
-  .having((o) => [expr.gte(o.totalAmount, 10000)])
-  .result();
-```
-
-## Pagination
-
-```typescript
-// TOP (no ORDER BY required)
-const topUsers = await db.user().top(10).result();
-
-// LIMIT/OFFSET (ORDER BY required)
-const page = await db.user()
-  .orderBy((u) => u.createdAt, "DESC")
-  .limit(0, 20) // skip 0, take 20
-  .result();
-```
-
-## Text Search
-
-The `search()` method supports structured search syntax.
-
-```typescript
-const users = await db.user()
-  .search((u) => [u.name, u.email], "John -deleted")
-  .result();
-```
-
-### Search Syntax
-
-| Syntax | Description | Example |
-|------|------|------|
-| Space | OR combination | `apple banana` |
-| `""` | Phrase search (required) | `"delicious apple"` |
-| `+` | Required (AND) | `+apple +banana` |
-| `-` | Exclude (NOT) | `apple -banana` |
-| `*` | Wildcard | `app*` |
-| `\*` | Escape | `app\*` (literal `*`) |
-
-## UNION
-
-```typescript
-const allItems = await Queryable.union(
-  db.user()
-    .where((u) => [expr.eq(u.type, "admin")])
-    .select((u) => ({ name: u.name })),
-  db.user()
-    .where((u) => [expr.eq(u.type, "manager")])
-    .select((u) => ({ name: u.name })),
-).result();
-```
-
-## Subquery Wrapping (wrap)
-
-To use `count()` after `distinct()` or `groupBy()`, wrap the query with `wrap()`.
-
-```typescript
-const count = await db.user()
-  .select((u) => ({ name: u.name }))
-  .distinct()
-  .wrap()
-  .count();
-```
-
-## Recursive CTE (recursive)
-
-Use for querying hierarchical data (org charts, category trees, etc.).
-
-```typescript
-const employees = await db.employee()
-  .where((e) => [expr.null(e.managerId)]) // Root node
-  .recursive((cte) =>
-    cte.from(Employee)
-      .where((e) => [expr.eq(e.managerId, e.self[0].id)])
-  )
-  .result();
-```
-
-## INSERT
-
-```typescript
-// Simple insert
-await db.user().insert([
-  { name: "John Doe", createdAt: DateTime.now() },
-  { name: "Jane Smith", createdAt: DateTime.now() },
-]);
-
-// Insert with ID return (outputColumns)
-const [inserted] = await db.user().insert(
-  [{ name: "John Doe", createdAt: DateTime.now() }],
-  ["id"],
-);
-// inserted.id is available
-
-// Conditional insert (insert if not exists)
-await db.user()
-  .where((u) => [expr.eq(u.email, "test@test.com")])
-  .insertIfNotExists({ name: "Test", email: "test@test.com", createdAt: DateTime.now() });
-
-// INSERT INTO ... SELECT
-await db.user()
-  .select((u) => ({ name: u.name, createdAt: u.createdAt }))
-  .where((u) => [expr.eq(u.isArchived, false)])
-  .insertInto(ArchivedUser);
-```
-
-## UPDATE
-
-```typescript
-// Plain values (recommended)
-await db.user()
-  .where((u) => [expr.eq(u.id, 1)])
-  .update(() => ({
-    name: "새이름",
-    updatedAt: DateTime.now(),
-  }));
-
-// Column reference (use ExprUnit from callback parameter)
-await db.product()
-  .update((p) => ({
-    price: expr.mul(p.price, 1.1),
-  }));
-
-// Mixed: plain values + expressions
-await db.user()
-  .where((u) => [expr.eq(u.id, 1)])
-  .update((u) => ({
-    name: "새이름",
-    loginCount: expr.raw("number")`${u.loginCount} + 1`,
-  }));
-```
-
-## DELETE
-
-```typescript
-// Simple delete
-await db.user()
-  .where((u) => [expr.eq(u.id, 1)])
-  .delete();
-
-// Return deleted data
-const deleted = await db.user()
-  .where((u) => [expr.eq(u.isExpired, true)])
-  .delete(["id", "name"]);
-```
-
-## UPSERT
-
-```typescript
-// Same data for UPDATE/INSERT
-await db.user()
-  .where((u) => [expr.eq(u.email, "test@test.com")])
-  .upsert(() => ({
-    name: "Test",
-    email: "test@test.com",
-  }));
-
-// Different data for UPDATE/INSERT
-await db.user()
-  .where((u) => [expr.eq(u.email, "test@test.com")])
-  .upsert(
-    () => ({ loginCount: 1 }),
-    (update) => ({ ...update, email: "test@test.com" }),
-  );
-```
-
-## Row Locking (FOR UPDATE)
-
-```typescript
-await db.connect(async () => {
-  const user = await db.user()
-    .where((u) => [expr.eq(u.id, 1)])
-    .lock()
-    .single();
-});
-```
-
-## DDL Operations
-
-`DbContextInstance` supports Code First DDL operations.
-
-```typescript
-await db.connectWithoutTransaction(async () => {
-  // Initialize database (create tables/views/procedures/FKs/indexes)
-  await db.initialize();
-
-  // Force initialize (drop and recreate existing data)
-  await db.initialize({ force: true });
-
-  // Individual DDL operations
-  const c = createColumnFactory();
-  await db.addColumn({ database: "mydb", name: "User" }, "status", c.varchar(20).nullable());
-  await db.modifyColumn({ database: "mydb", name: "User" }, "status", c.varchar(50).nullable());
-  await db.renameColumn({ database: "mydb", name: "User" }, "status", "userStatus");
-  await db.dropColumn({ database: "mydb", name: "User" }, "userStatus");
-
-  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.
-
-```typescript
-import { createQueryBuilder } from "@simplysm/orm-common";
-
-const mysqlBuilder = createQueryBuilder("mysql");
-const mssqlBuilder = createQueryBuilder("mssql");
-const postgresqlBuilder = createQueryBuilder("postgresql");
-
-// Convert QueryDef to SQL
-const queryDef = db.user()
-  .where((u) => [expr.eq(u.isActive, true)])
-  .getSelectQueryDef();
-
-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
-import { DbTransactionError, DbErrorCode } from "@simplysm/orm-common";
-
-try {
-  await db.connect(async () => {
-    // ...
-  });
-} catch (err) {
-  if (err instanceof DbTransactionError) {
-    switch (err.code) {
-      case DbErrorCode.DEADLOCK:
-        // Deadlock retry logic
-        break;
-      case DbErrorCode.LOCK_TIMEOUT:
-        // Timeout handling
-        break;
-    }
-  }
-}
-```
-
-### DbErrorCode
-
-| Code | Description |
-|------|------|
-| `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 |