@cleverbrush/knex-schema 3.1.0 → 4.0.0

package/README.md

@@ -214,6 +214,161 @@ const rows = await query(db, UserSchema)
 
 ---
 
+## Scopes
+
+Define **reusable WHERE/ORDER/LIMIT conditions** on the schema. A default scope is applied
+automatically unless bypassed with `.unscoped()`.
+
+```typescript
+const PostSchema = object({
+    id:       number(),
+    title:    string(),
+    status:   string(),
+    isActive: boolean().hasColumnName('is_active'),
+})
+    .hasTableName('posts')
+    .scope('published',  q => q.where(t => t.status, 'published'))
+    .scope('recent',     q => q.orderBy(t => t.id, 'desc').limit(10))
+    .defaultScope(       q => q.where(t => t.isActive, true));
+
+// Apply named scopes
+const posts = await query(db, PostSchema)
+    .scoped('published')
+    .scoped('recent');
+
+// Bypass default scope (also skips soft-delete filter if present)
+const all = await query(db, PostSchema).unscoped();
+```
+
+`scoped()` is statically typed: TypeScript only allows registered scope names.
+
+---
+
+## Projections
+
+Define **named column subsets** on the schema with `.projection(name, columns)`. At query time,
+`.projected(name)` restricts the `SELECT` clause **and** narrows the TypeScript result type to
+`Pick<Row, Keys>` — accessing columns outside the projection is a compile-time error.
+
+### String-tuple form
+
+```typescript
+const PostSchema = object({
+    id:    number().primaryKey(),
+    title: string(),
+    body:  string(),
+    status: string(),
+})
+    .hasTableName('posts')
+    .projection('summary',    ['id', 'title'] as const)
+    .projection('withStatus', ['id', 'title', 'status'] as const);
+
+const rows = await query(db, PostSchema)
+    .scoped('published')
+    .projected('summary');
+
+// rows: Array<Pick<Post, 'id' | 'title'>>
+// rows[0].body  // ← TypeScript error: 'body' not in projection ✓
+```
+
+### Accessor form
+
+```typescript
+.projection('withStatus', t => [t.id, t.title, t.status])
+```
+
+The accessor receives the schema's property-descriptor tree; each element resolves to the
+property name at runtime. This form is more refactor-safe but does not provide the compile-time
+`Pick<>` narrowing that the tuple form offers.
+
+### Conflict rules
+
+`.projected()` cannot be combined with `.select()`, `.distinct()`, or any aggregate
+(`.count()`, `.min()`, etc.) on the same query. Attempting to do so throws at runtime.
+
+### Column-name mapping
+
+`hasColumnName()` is respected: if `isActive` is mapped to `is_active`, the generated SQL
+uses `is_active` automatically.
+
+---
+
+## ORM Extensions
+
+In addition to query building, this package provides the schema-level primitives that
+[`@cleverbrush/orm`](https://www.npmjs.com/package/@cleverbrush/orm) and
+[`@cleverbrush/orm-cli`](https://www.npmjs.com/package/@cleverbrush/orm-cli) build on top of:
+
+### `defineEntity(schema)` — relations
+
+Wrap a schema to declare typed `belongsTo` / `hasOne` / `hasMany` / `belongsToMany`
+relations that downstream packages use for eager-loading joins and ORM navigation properties.
+
+```typescript
+import { defineEntity, object, number, string } from '@cleverbrush/knex-schema';
+
+const UserSchema = object({
+    id:    number().primaryKey(),
+    email: string(),
+}).hasTableName('users');
+
+const PostSchema = object({
+    id:       number().primaryKey(),
+    title:    string(),
+    authorId: number().hasColumnName('author_id'),
+    author:   UserSchema.optional(),
+}).hasTableName('posts');
+
+export const PostEntity = defineEntity(PostSchema)
+    .belongsTo(t => t.author, l => l.authorId, r => r.id);
+```
+
+The returned `Entity` carries the relation map in its type, so downstream `query(db, entity)`
+calls (and `@cleverbrush/orm`'s `DbSet.include()`) get full inference.
+
+### Polymorphism (STI / CTI)
+
+Mark a schema as polymorphic to support single-table or class-table inheritance — variants
+are discoverable via `getVariants()` / `getPolymorphicVariantSchemas()`:
+
+```typescript
+import { POLYMORPHIC_TYPE_BRAND } from '@cleverbrush/knex-schema';
+```
+
+See the `@cleverbrush/orm` docs for the full inheritance API (`.ofVariant()` etc.).
+
+### Migration generation (snapshot-based)
+
+| Function | Purpose |
+|---|---|
+| `entitiesToSnapshot(entities)` | Materialise entity definitions into a JSON-serialisable schema snapshot |
+| `loadSnapshot(path)` / `writeSnapshot(path, snap)` | Read/write the committed snapshot file |
+| `generateMigrationsForContext(entities, prevSnapshot)` | Diff entities against the snapshot and emit a TS migration source plus the next snapshot |
+| `generateMigration(snapshotA, snapshotB)` | Lower-level snapshot-vs-snapshot diff |
+| `diffSchema(schema, dbState)` / `applyDiff(knex, diff, table)` | Live-database diff/apply (used by `cb-orm db push`) |
+| `introspectDatabase(knex, table)` / `tableExistsInDb(knex, table)` | Database introspection helpers |
+| `generateCreateTable(schema)` / `generateCreatePolymorphicTables(schema)` | Knex-statement builders for fresh `CREATE TABLE` |
+
+Most users invoke these indirectly through the [`cb-orm`](https://www.npmjs.com/package/@cleverbrush/orm-cli)
+CLI (`cb-orm migrate generate`, `cb-orm db push`).
+
+### Row-version optimistic concurrency
+
+Mark a column as a row version with `.rowVersion()` to opt-in to optimistic concurrency
+checks in `@cleverbrush/orm`'s change tracker:
+
+```typescript
+const TodoSchema = object({
+    id:         number().primaryKey(),
+    title:      string(),
+    rowVersion: number().rowVersion(),
+}).hasTableName('todos');
+```
+
+`getRowVersionColumn(schema)` returns the marked column at runtime.
+
+---
+
 ## Column Reference Patterns
 
 Both styles are equivalent and resolve to the same SQL column:
@@ -246,7 +401,7 @@ Optionally pass a `baseQuery` (e.g. a scoped `knex('users').where('deleted_at',
 | Ordering | `.orderBy(col, dir?)`, `.orderByRaw(sql)` |
 | Grouping | `.groupBy(...cols)`, `.groupByRaw(sql)`, `.having(col, op, val)`, `.havingRaw(sql)` |
 | Pagination | `.limit(n)`, `.offset(n)` |
-| Selection | `.select(...cols)`, `.distinct(...cols)` |
+| Selection | `.select(...cols)`, `.distinct(...cols)`, `.projected(name)` |
 | Aggregates | `.count(col?)`, `.countDistinct(col?)`, `.min(col)`, `.max(col)`, `.sum(col)`, `.avg(col)` |
 | Writes | `.insert(data)`, `.insertMany(data[])`, `.update(data)`, `.delete()` |
 | Execution | `.execute()`, `.first()`, `await builder` (thenable) |