@simplysm/orm-common 13.0.81 → 13.0.83

package/docs/queryable.md

@@ -0,0 +1,420 @@
+# Queryable
+
+Chainable query builder for constructing type-safe SELECT, INSERT, UPDATE, DELETE, JOIN, GROUP BY, UNION, and recursive CTE queries.
+
+## API Reference
+
+### `Queryable<TData, TFrom>`
+
+The core query builder class. Created automatically from DbContext table/view accessors (e.g., `db.user()`).
+
+- `TData` -- Data type of the query result
+- `TFrom` -- Source table builder (required for CUD operations; `never` for views/subqueries)
+
+---
+
+### SELECT / Projection
+
+#### `.select(fn)`
+
+Specify columns to SELECT with optional transformations.
+
+```typescript
+select<R>(fn: (columns) => R): Queryable<UnwrapQueryableRecord<R>, never>
+```
+
+```typescript
+db.user().select((u) => ({
+  userName: u.name,
+  upperEmail: expr.upper(u.email),
+}))
+```
+
+#### `.distinct()`
+
+Apply DISTINCT to remove duplicate rows.
+
+```typescript
+db.user().select((u) => ({ name: u.name })).distinct()
+```
+
+#### `.lock()`
+
+Apply row lock (`FOR UPDATE`) within a transaction.
+
+```typescript
+db.user().where((u) => [expr.eq(u.id, 1)]).lock()
+```
+
+---
+
+### Filtering
+
+#### `.where(predicate)`
+
+Add WHERE conditions. Multiple calls are combined with AND.
+
+```typescript
+where(predicate: (columns) => WhereExprUnit[]): Queryable<TData, TFrom>
+```
+
+```typescript
+db.user()
+  .where((u) => [expr.eq(u.status, "active")])
+  .where((u) => [expr.gte(u.age, 18)])
+```
+
+#### `.search(fn, searchText)`
+
+Full-text search using LIKE patterns. Supports `+required`, `-excluded`, `"exact phrase"`, and `*wildcard` syntax.
+
+```typescript
+db.user().search((u) => [u.name, u.email], 'John +active -deleted')
+```
+
+---
+
+### Sorting and Pagination
+
+#### `.orderBy(fn, direction?)`
+
+Add ORDER BY. Multiple calls add additional sort columns.
+
+```typescript
+db.user()
+  .orderBy((u) => u.name)
+  .orderBy((u) => u.createdAt, "DESC")
+```
+
+#### `.top(count)`
+
+Select only top N rows. Can be used without ORDER BY.
+
+```typescript
+db.user().top(10)
+```
+
+#### `.limit(skip, take)`
+
+Set LIMIT/OFFSET for pagination. Requires `orderBy()` first.
+
+```typescript
+db.user()
+  .orderBy((u) => u.createdAt)
+  .limit(0, 20) // first 20 rows
+```
+
+---
+
+### Grouping
+
+#### `.groupBy(fn)`
+
+Add GROUP BY clause.
+
+```typescript
+db.order()
+  .select((o) => ({
+    userId: o.userId,
+    totalAmount: expr.sum(o.amount),
+  }))
+  .groupBy((o) => [o.userId])
+```
+
+#### `.having(predicate)`
+
+Add HAVING clause (filter after GROUP BY).
+
+```typescript
+db.order()
+  .select((o) => ({
+    userId: o.userId,
+    totalAmount: expr.sum(o.amount),
+  }))
+  .groupBy((o) => [o.userId])
+  .having((o) => [expr.gte(o.totalAmount, 10000)])
+```
+
+---
+
+### JOIN
+
+#### `.join(as, fn)` -- 1:N JOIN
+
+LEFT OUTER JOIN that adds results as an array property.
+
+```typescript
+db.user().join("posts", (qr, u) =>
+  qr.from(Post).where((p) => [expr.eq(p.authorId, u.id)])
+)
+// Result: { id, name, posts: [{ id, title }, ...] }
+```
+
+#### `.joinSingle(as, fn)` -- N:1 / 1:1 JOIN
+
+LEFT OUTER JOIN that adds results as a single object property.
+
+```typescript
+db.post().joinSingle("author", (qr, p) =>
+  qr.from(User).where((u) => [expr.eq(u.id, p.authorId)])
+)
+// Result: { id, title, author: { id, name } | undefined }
+```
+
+#### `.include(fn)` -- Automatic Relation JOIN
+
+Automatically JOIN based on relations defined in `TableBuilder.relations()`.
+
+```typescript
+// Single relation
+db.post().include((p) => p.author)
+
+// Nested relation
+db.post().include((p) => p.author.company)
+
+// Multiple relations (chain include calls)
+db.user()
+  .include((u) => u.company)
+  .include((u) => u.posts)
+```
+
+---
+
+### Subquery and UNION
+
+#### `.wrap()`
+
+Wrap current Queryable as a subquery. Required before `count()` after `distinct()` or `groupBy()`.
+
+```typescript
+const count = await db.user()
+  .select((u) => ({ name: u.name }))
+  .distinct()
+  .wrap()
+  .count();
+```
+
+#### `Queryable.union(...queries)`
+
+Combine multiple Queryables with UNION ALL.
+
+```typescript
+const combined = Queryable.union(
+  db.user().where((u) => [expr.eq(u.type, "admin")]),
+  db.user().where((u) => [expr.eq(u.type, "manager")]),
+);
+```
+
+---
+
+### Recursive CTE
+
+#### `.recursive(fn)`
+
+Build recursive Common Table Expressions for hierarchical data.
+
+```typescript
+db.employee()
+  .where((e) => [expr.null(e.managerId)]) // base case: root nodes
+  .recursive((cte) =>
+    cte.from(Employee)
+      .where((e) => [expr.eq(e.managerId, e.self[0].id)])
+  )
+```
+
+---
+
+### Execution -- SELECT
+
+#### `.execute()`
+
+Execute SELECT and return result array.
+
+```typescript
+const users: User[] = await db.user()
+  .where((u) => [expr.eq(u.isActive, true)])
+  .execute();
+```
+
+#### `.single()`
+
+Return single result. Throws if more than one result.
+
+```typescript
+const user = await db.user()
+  .where((u) => [expr.eq(u.id, 1)])
+  .single();
+// returns User | undefined
+```
+
+#### `.first()`
+
+Return first result (ignores additional results).
+
+```typescript
+const latest = await db.user()
+  .orderBy((u) => u.createdAt, "DESC")
+  .first();
+```
+
+#### `.count(fn?)`
+
+Return row count. Cannot be used directly after `distinct()` or `groupBy()` (use `wrap()` first).
+
+```typescript
+const count = await db.user()
+  .where((u) => [expr.eq(u.isActive, true)])
+  .count();
+```
+
+#### `.exists()`
+
+Check if any matching rows exist.
+
+```typescript
+const hasAdmin = await db.user()
+  .where((u) => [expr.eq(u.role, "admin")])
+  .exists();
+```
+
+---
+
+### Execution -- INSERT
+
+#### `.insert(records, outputColumns?)`
+
+Insert records. Automatically chunks into batches of 1000 (MSSQL limit).
+
+```typescript
+// Simple insert
+await db.user().insert([
+  { name: "Alice", email: "alice@test.com" },
+  { name: "Bob" },
+]);
+
+// Insert with output (get auto-generated IDs)
+const inserted = await db.user().insert(
+  [{ name: "Alice" }],
+  ["id"],
+);
+// inserted[0].id
+```
+
+#### `.insertIfNotExists(record, outputColumns?)`
+
+Insert only if WHERE condition matches no rows.
+
+```typescript
+await db.user()
+  .where((u) => [expr.eq(u.email, "test@test.com")])
+  .insertIfNotExists({ name: "Test", email: "test@test.com" });
+```
+
+#### `.insertInto(targetTable, outputColumns?)`
+
+INSERT INTO ... SELECT (copy current query results into another table).
+
+```typescript
+await db.user()
+  .select((u) => ({ name: u.name, createdAt: u.createdAt }))
+  .where((u) => [expr.eq(u.isArchived, false)])
+  .insertInto(ArchivedUser);
+```
+
+---
+
+### Execution -- UPDATE
+
+#### `.update(recordFn, outputColumns?)`
+
+Update matching rows. The callback receives current column values for reference.
+
+```typescript
+await db.user()
+  .where((u) => [expr.eq(u.id, 1)])
+  .update(() => ({
+    name: expr.val("string", "New Name"),
+  }));
+```
+
+---
+
+### Execution -- DELETE
+
+#### `.delete(outputColumns?)`
+
+Delete matching rows.
+
+```typescript
+await db.user()
+  .where((u) => [expr.eq(u.status, "deleted")])
+  .delete();
+```
+
+---
+
+### Execution -- UPSERT
+
+#### `.upsert(record, outputColumns?)`
+
+INSERT or UPDATE (MERGE pattern). Requires a WHERE condition to check existence.
+
+```typescript
+await db.user()
+  .where((u) => [expr.eq(u.email, "test@test.com")])
+  .upsert({
+    insert: { name: "Test", email: "test@test.com" },
+    update: { name: expr.val("string", "Updated") },
+  });
+```
+
+---
+
+### QueryDef Accessors
+
+Each execution method has a corresponding `get*QueryDef()` method that returns the raw `QueryDef` without executing it:
+
+- `getSelectQueryDef()` -- Returns `SelectQueryDef`
+- `getInsertQueryDef(records, outputColumns?)` -- Returns `InsertQueryDef`
+- `getInsertIfNotExistsQueryDef(record, outputColumns?)` -- Returns `InsertIfNotExistsQueryDef`
+- `getInsertIntoQueryDef(targetTable, outputColumns?)` -- Returns `InsertIntoQueryDef`
+- `getResultMeta(outputColumns?)` -- Returns `ResultMeta` for type parsing
+
+---
+
+## Usage Examples
+
+### Complex Query with Multiple Features
+
+```typescript
+const result = await db.order()
+  .include((o) => o.customer)
+  .where((o) => [
+    expr.gte(o.createdAt, expr.val("DateTime", startDate)),
+    expr.eq(o.status, "completed"),
+  ])
+  .select((o) => ({
+    orderId: o.id,
+    customerName: o.customer.name,
+    total: o.totalAmount,
+  }))
+  .orderBy((o) => o.total, "DESC")
+  .limit(0, 50)
+  .execute();
+```
+
+### Aggregation with GROUP BY
+
+```typescript
+const stats = await db.order()
+  .select((o) => ({
+    month: expr.month(o.createdAt),
+    year: expr.year(o.createdAt),
+    totalRevenue: expr.sum(o.amount),
+    orderCount: expr.count(),
+  }))
+  .groupBy((o) => [o.month, o.year])
+  .orderBy((o) => o.year)
+  .orderBy((o) => o.month)
+  .execute();
+```

package/docs/schema-builders.md

@@ -0,0 +1,216 @@
+# 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");
+```