@ts-awesome/orm 2.0.0-alpha.1 → 2.0.0-alpha.2

package/README.md

@@ -1,51 +1,115 @@
 # @ts-awesome/orm
 
-TypeScript friendly minimalistic Object Relation Mapping library
+TypeScript-friendly, minimalistic object relational mapping library.
 
 Key features:
 
 * strong object mapping with [@ts-awesome/model-reader](https://github.com/ts-awesome/model-reader)
-* no relation navigation - intentional
+* no relation navigation (intentional)
 * heavy use of type checks and lambdas
-* support common subset of SQL
+* supports a common subset of SQL
+* built-in unit testing driver
+
+No relation navigation is intentional: relationships are expressed in queries so you always control joins and payload shape.
+
+## Install
+
+```bash
+npm install @ts-awesome/orm @ts-awesome/orm-pg
+```
+
+## Quick start
+
+```ts
+import {dbField, dbTable, IBuildableQuery, IQueryExecutor, Select} from '@ts-awesome/orm';
+import {ISqlQuery, PgCompiler} from '@ts-awesome/orm-pg';
+
+@dbTable('users')
+class User {
+  @dbField({primaryKey: true, autoIncrement: true})
+  public id!: number;
+
+  @dbField
+  public name!: string;
+}
+
+const compiler = new PgCompiler();
+const driver: IQueryExecutor<ISqlQuery> = /* your driver instance */;
+
+const query: IBuildableQuery = Select(User).where({name: 'Alice'}).limit(1);
+const compiled: ISqlQuery = compiler.compile(query);
+const results: User[] = await driver.execute(compiled, User);
+```
+
+## Supported drivers
+
+* PostgreSQL: `@ts-awesome/orm-pg`
+* SQLite: `@ts-awesome/orm-sqlite`
+* Firebird: `@ts-awesome/orm-firebird`
+* Other drivers may be available on request
 
 ## Model declaration
 
-Each model metadata is defined with `dbTable` and `dbField` decorators
+Model metadata is defined with `dbTable` and `dbField` decorators.
 
 ```ts
-import {dbField, dbField} from "@ts-awesome/orm";
-import {DB_JSON} from "@ts-awesome/orm-pg"; // or other driver
+import {dbField, dbTable, Branded} from '@ts-awesome/orm';
+import {DB_JSON} from '@ts-awesome/orm-pg'; // or other driver
+
+type FirstModelId = Branded<number, 'FirstModelId'>;
+type AuthorId = Branded<number, 'AuthorId'>;
+
+class SubDocumentModel {
+  public title!: string;
+}
+
+const enum UserStatus {
+  Active = 1,
+  Inactive = 0,
+}
+
+enum UserRole {
+  Admin = 'admin',
+  User = 'user',
+}
 
 @dbTable('first_table')
 class FirstModel {
   // numeric autoincrement primary key
   @dbField({primaryKey: true, autoIncrement: true})
-  public id!: number;
+  public id!: FirstModelId;
 
   // just another field
   @dbField
   public title!: string;
 
-  // lets map prop to different field
+  // let's map prop to different field
   @dbField({name: 'author_id'})
-  public authorId!: number;
+  public authorId!: AuthorId;
 
   // nullable field requires explicit model and nullable
-  // these are direct match to @ts-awesome/model-reader
+  // these are direct matches to @ts-awesome/model-reader
   @dbField({
     model: String,
     nullable: true,
   })
   public description!: string | null;
 
-  // advanced use case
-  @dbModel({
+  // JSON column with model conversion
+  @dbField({
     kind: DB_JSON, // data will be stored as JSON
     model: SubDocumentModel, // and will be converted to instance of SubDocumentModel
     nullable: true,
   })
-  public document!: SubDocumentModel | null
+  public document!: SubDocumentModel | null;
+
+  // numeric enum support
+  @dbField({model: UserStatus})
+  public status!: UserStatus;
+
+  // string enum support
+  @dbField({model: UserRole})
+  public role!: UserRole;
 
   // readonly field with database default
   @dbField({name: 'created_at', readonly: true})
@@ -53,67 +117,231 @@ class FirstModel {
 }
 ```
 
+### Common decorator options
+
+* `primaryKey`: marks a primary key column
+* `autoIncrement`: enables auto-increment on numeric keys
+* `name`: maps a property to a different column name
+* `readonly`: marks a column as DB-managed (insert/update ignored)
+* `nullable`: allows `null` in the model type
+* `model`: overrides the inferred model type (enums, custom classes)
+* `kind`: custom read/write hooks for DB-specific types
+* `sensitive`: hides field values unless explicitly requested by reader/driver
+* `default`: default DB value (used for metadata and inserts)
+
+### Table indexes for upsert
+
+`@dbTable` can declare unique indexes used by `Upsert().conflict()`.
+
+```ts
+import {dbField, dbTable} from '@ts-awesome/orm';
+
+@dbTable('users', [
+  {name: 'users_email_unique', fields: ['email'], default: true},
+])
+class User {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbField
+  public email!: string;
+}
+```
+
+### Custom field kinds
+
+Use `kind` for custom read/write transformations and query wrapping.
+
+```ts
+import {dbField, dbTable} from '@ts-awesome/orm';
+
+const BoolAsNumber = {
+  reader: (raw: unknown) => raw === 1,
+  writer: (value: boolean) => (value ? 1 : 0),
+};
+
+@dbTable('flags')
+class Flag {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbField({kind: BoolAsNumber})
+  public enabled!: boolean;
+}
+```
+
+### Derived fields
+
+`@dbFilterField` lets you expose subquery-based fields without relation navigation.
+It requires a single-column primary key on the source table.
+
+```ts
+import {dbField, dbFilterField, dbTable, Select} from '@ts-awesome/orm';
+
+@dbTable('roles')
+class Role {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbField
+  public userId!: number;
+
+  @dbField
+  public name!: string;
+}
+
+@dbTable('users')
+class User {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbFilterField((id, _table) => Select(Role)
+    .columns(({name}) => [name])
+    .where(({userId}) => userId.eq(id))
+    .limit(1))
+  public roleName!: string;
+}
+```
+
+`@dbManyField` exists but is deprecated; use `@dbFilterField` instead.
+
+### Sensitive fields
+
+Fields marked as `sensitive` are omitted unless you pass `true` to the reader/driver.
+
+```ts
+import {dbField, dbTable, Select} from '@ts-awesome/orm';
+import {TestCompiler, TestDriver} from '@ts-awesome/orm/test-driver';
+
+@dbTable('users')
+class User {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbField({sensitive: true})
+  public passwordHash!: string;
+}
+
+const driver = new TestDriver();
+const compiler = new TestCompiler();
+const results = await driver.execute(compiler.compile(Select(User)), User, true);
+```
+
 ## Vanilla select
 
 ```ts
-import {IBuildableQuery, IQueryExecutor, Select} from "@ts-awesome/orm";
-import {ISqlQuery, PgCompiler} from "@ts-awesome/orm-pg"; // or other driver
+import {Branded, dbField, dbTable, IBuildableQuery, IQueryExecutor, Select} from '@ts-awesome/orm';
+import {ISqlQuery, PgCompiler} from '@ts-awesome/orm-pg'; // or other driver
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
 
 const compiler = new PgCompiler();
 const driver: IQueryExecutor<ISqlQuery>;
 
-const query: IBuildableQuery = Select(FirstModel).where({authorId: 5}).limit(10);
+const query: IBuildableQuery = Select(FirstModel).where({authorId: 5 as AuthorId}).limit(10);
 const compiled: ISqlQuery = compiler.compile(query);
 const results: FirstModel[] = await driver.execute(compiled, FirstModel);
 ```
 
-For more streamlined use please check [@ts-awesome/entity](https://github.com/ts-awesome/model-reader) 
+For more streamlined use, please check [@ts-awesome/model-reader](https://github.com/ts-awesome/model-reader).
 
 ## Select builder
 
-ORM provides a way to use model declaration to your advantage: TypeScript will check is fields exists.
-And TypeScript will check operands for compatible types.
+ORM provides a way to use model declaration to your advantage: TypeScript will check if fields exist,
+and will check operands for compatible types.
 
 ```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
+
 const query = Select(FirstModel)
   // authorId = 5;
-  .where({authorId: '5'}) // gives error, it can be number only
+  .where({authorId: '5'}) // gives error, it can be number (branded AuthorId) only
   .limit(10);
 ```
 
-For more complex logic ORM provides WhereBuilder
+For more complex logic, ORM provides a WhereBuilder.
 
 ```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
+
 const query = Select(FirstModel)
   // authorId = 5;
-  .where(({authorId}) => authorId.eq(5))
+  .where(({authorId}) => authorId.eq(5 as AuthorId))
   .limit(10);
 ```
 
 ```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+
+  @dbField({model: String, nullable: true})
+  public description!: string | null;
+}
+
 const query = Select(FirstModel)
   // authorId in (5, 6)
-  .where(({authorId, description}) => authorId.in([5, 6])) 
+  .where(({authorId, description}) => authorId.in([5 as AuthorId, 6 as AuthorId]))
   .limit(10);
 ```
 
 ```ts
+import {and, Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+
+  @dbField({model: String, nullable: true})
+  public description!: string | null;
+}
+
 const query = Select(FirstModel)
   // authorId = 5 AND description LIKE 'some%';
-  .where(({authorId, description}) => and(authorId.eq(5), description.like('some%'))) 
+  .where(({authorId, description}) => and(authorId.eq(5 as AuthorId), description.like('some%')))
   .limit(10);
 ```
 
 #### Overview of operators and functions:
     
-* Generic comparable: 
+* Generic comparable:
   * left.`eq`(right) equivalent to left `=` right or left `IS NULL` if right === null
   * left.`neq`(right) equivalent to left `<>` right or left `IS NOT NULL` if right === null
   * left.`gt`(right) equivalent to left `>` right
   * left.`gte`(right) equivalent to left `>=` right
   * left.`lt`(right) equivalent to left `<` right
-  * left.`lte`(right) equivalent to left `<=` right  
-  * left.`between`(a, b) equivalent left BETWEEN (a, b)
+  * left.`lte`(right) equivalent to left `<=` right
+  * left.`between`(a, b) equivalent to left BETWEEN (a, b)
 * Strings
   * left.`like`(right) equivalent to left `LIKE` right
 * Arrays
@@ -142,154 +370,489 @@ const query = Select(FirstModel)
   * `max`(expr) equivalent to `MAX` (expr)
   * `min`(expr) equivalent to `MIN` (expr)
   * `sum`(expr) equivalent to `SUM` (expr)
-  * `count`(expr) equivalent to `count` (expr)
+  * `count`(expr) equivalent to `COUNT` (expr)
+  * `count`(expr, true) equivalent to `COUNT(DISTINCT expr)`
+  * `stddev_pop`, `stddev_samp`, `var_pop`, `var_samp`
+* Date & Time
+  * `now`(), `current_date`(), `current_timestamp`()
+  * `extract`(field, source) equivalent to `EXTRACT(field FROM source)`
+  * `date_trunc`(part, source) equivalent to `DATE_TRUNC(part, source)`
+* String
+  * `concat`(s1, s2, ...), `lower`(s), `upper`(s), `length`(s)
+  * `trim`(s), `ltrim`(s), `rtrim`(s)
+  * `substring`(s, start, len), `position`(sub in str), `replace`(str, from, to)
+  * `lpad`(s, len, pad), `rpad`(s, len, pad), `repeat`(s, n)
+  * `left`(s, n), `right`(s, n), `reverse`(s)
+* Math
+  * `abs`(x), `ceil`(x), `floor`(x), `round`(x, d)
+  * `power`(b, e), `sqrt`(x), `mod`(x, y)
+  * `exp`(x), `ln`(x), `log`(x, base), `trunc`(x, d), `pi`(), `sign`(x), `random`()
+* Conditional
+  * `coalesce`(v1, v2, ...), `nullif`(v1, v2)
+  * `greatest`(v1, v2, ...), `least`(v1, v2, ...)
+  * `case_`({when: cond, then: val}, ..., {else: val})
+* Casting
+  * `cast`(expr, type) equivalent to `CAST(expr AS type)`
+
+### Column references without a model
+
+```ts
+import {of, Select} from '@ts-awesome/orm';
+
+const query = Select(FirstModel)
+  .orderBy(() => [of(null, 'score')]);
+```
 
 ### Joining
 
-Sometimes you may need to perform some joins for filtering
+Sometimes you may need to perform joins for filtering.
 
 ```ts
-import {dbTable, dbField} from "@ts-awesome/orm";
+import {Branded, dbField, dbTable, of, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
 
 @dbTable('second_table')
 class SecondModel {
-  @dbField({primatyKey: true, autoIncrement: true})
-  public id!: number;
-  
+  @dbField({primaryKey: true, autoIncrement: true})
+  public id!: AuthorId;
+
   @dbField
   public name!: string;
 }
 
 const query = Select(FirstModel)
-  // lets join SecondModel by FK
+  // let's join SecondModel by FK
   .join(SecondModel, (root, other) => root.authorId.eq(other.id))
-  // lets filter by author name
+  // let's filter by author name
   .where(() => of(SecondModel, 'name').like('John%'))
-  .limit(10)
+  .limit(10);
 ```
 
-In some cases `TableRef` might be handy, especially of need to join same table multiple times
+In some cases `TableRef` might be handy, especially if you need to join the same table multiple times.
 
 ```ts
-import {dbTable, dbField} from "@ts-awesome/orm";
+import {dbField, dbTable, Branded, of, or, Select, TableRef} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+type ThirdModelId = Branded<number, 'ThirdModelId'>;
 
 @dbTable('second_table')
 class SecondModel {
-  @dbField({primatyKey: true, autoIncrement: true})
-  public id!: number;
-  
+  @dbField({primaryKey: true, autoIncrement: true})
+  public id!: AuthorId;
+
   @dbField
   public name!: string;
 }
 
 @dbTable('third_table')
 class ThirdModel {
-  @dbField({primatyKey: true, autoIncrement: true})
-  public id!: number;
+  @dbField({primaryKey: true, autoIncrement: true})
+  public id!: ThirdModelId;
 
   @dbField
-  public createdBy!: number;
-  
+  public createdBy!: AuthorId;
+
   @dbField
-  public ownedBy!: number;
+  public ownedBy!: AuthorId;
 }
 
 const ownerRef = new TableRef(SecondModel);
 const creatorRef = new TableRef(SecondModel);
 const query = Select(ThirdModel)
-  // lets join SecondModel by FK
+  // let's join SecondModel by FK
   .join(SecondModel, ownerRef, (root, other) => root.ownedBy.eq(other.id))
-  // lets join SecondModel by FK
+  // let's join SecondModel by FK
   .join(SecondModel, creatorRef, (root, other) => root.createdBy.eq(other.id))
-  // lets filter by owner or creator name
+  // let's filter by owner or creator name
   .where(() => or(
     of(ownerRef, 'name').like('John%'),
     of(creatorRef, 'name').like('John%'),
   ))
-  .limit(10)
+  .limit(10);
 ```
 
 ### Grouping
 
 ```ts
-import {Select, min, count, alias} from '@ts-awesome/orm'
+import {alias, Branded, count, dbField, dbTable, min, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+
+  @dbField
+  public title!: string;
 
-const ts: Date; // some timestamp in past
+  @dbField({name: 'created_at'})
+  public createdAt!: Date;
+}
+
+const ts: Date; // some timestamp in the past
 const query = Select(FirstModel)
   // we need titles to contain `key`
   .where(({title}) => title.like('%key%'))
   // group by authors
   .groupBy(['authorId'])
-  // filter to have first publication not before ts 
+  // filter to have first publication not before ts
   .having(({createdAt}) => min(createdAt).gte(ts))
   // result should have 2 columns: authorId and count
-  .columns(({authorId}) => [authorId, alias(count(), 'count')])
+  .columns(({authorId}) => [authorId, alias(count(), 'count')]);
 ```
 
 ### Ordering
 
 ```ts
-import {Select, desc} from '@ts-awesome/orm'
+import {Branded, dbField, dbTable, desc, of, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+
+  @dbField
+  public title!: string;
+}
+
+@dbTable('second_table')
+class SecondModel {
+  @dbField({primaryKey: true})
+  public id!: AuthorId;
+
+  @dbField
+  public name!: string;
+}
+
+const query = Select(FirstModel)
+  // let's join SecondModel by FK
+  .join(SecondModel, (root, other) => root.authorId.eq(other.id))
+  // let's sort by author and title reverse
+  .orderBy(({title}) => [of(SecondModel, 'name'), desc(title)])
+  .limit(10);
+```
+
+### Pagination
+
+```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
+
+const query = Select(FirstModel)
+  .where(({authorId}) => authorId.eq(5 as AuthorId))
+  .limit(10)
+  .offset(20);
+```
+
+### Distinct and FOR UPDATE
+
+```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type FirstModelId = Branded<number, 'FirstModelId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({primaryKey: true})
+  public id!: FirstModelId;
+
+  @dbField({name: 'author_id'})
+  public authorId!: number;
+}
+
+const distinctQuery = Select(FirstModel, true)
+  .columns(({authorId}) => [authorId]);
+
+const lockedQuery = Select(FirstModel, 'UPDATE')
+  .where(({id}) => id.eq(1 as FirstModelId));
+```
+
+Supported `FOR` modes: `'UPDATE' | 'NO KEY UPDATE' | 'SHARE' | 'KEY SHARE'`.
+
+### Set operations
+
+```ts
+import {dbField, dbTable, Select} from '@ts-awesome/orm';
+
+enum UserStatus {
+  Active = 1,
+  Inactive = 0,
+}
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({model: UserStatus})
+  public status!: UserStatus;
+}
+
+const query = Select(FirstModel)
+  .where(({status}) => status.eq(UserStatus.Active))
+  .union(true, Select(FirstModel).where(({status}) => status.eq(UserStatus.Inactive)));
+```
+
+Set operations require compatible column lists; the boolean flag toggles `DISTINCT`.
+
+### Join types
+
+```ts
+import {Branded, dbField, dbTable, Select} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
+
+@dbTable('second_table')
+class SecondModel {
+  @dbField({primaryKey: true})
+  public id!: AuthorId;
+}
 
 const query = Select(FirstModel)
-    // lets join SecondModel by FK
-    .join(SecondModel, (root, other) => root.authorId.eq(other.id))
-    // lets sort by author and title reverse
-    .orderby(({title}) => [of(SecondModel, 'name'), desc(title)])
-    .limit(10)
+  .joinLeft(SecondModel, (root, other) => root.authorId.eq(other.id));
+```
+
+Join variants include `joinLeft`, `joinRight`, and `joinFull`.
+
+### Scalar subqueries
+
+```ts
+import {Select} from '@ts-awesome/orm';
+
+const subquery = Select(FirstModel)
+  .columns(({authorId}) => [authorId])
+  .where(({id}) => id.eq(1 as FirstModelId))
+  .asScalar();
 ```
 
 ## Other builders
 
-ORM provides `Insert`, `Update`, `Upset` and `Delete` builders
+ORM provides `Insert`, `Update`, `Upsert` and `Delete` builders.
 
 ### Insert
 
 ```ts
-import {Insert} from '@ts-awesome/orm';
+import {dbField, dbTable, Insert} from '@ts-awesome/orm';
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField
+  public title!: string;
+}
 
 const query = Insert(FirstModel)
   .values({
     title: 'New book'
-  })
+  });
 ```
 
 ### Update
 
 ```ts
-import {Update} from '@ts-awesome/orm';
+import {Branded, dbField, dbTable, Update} from '@ts-awesome/orm';
+
+type FirstModelId = Branded<number, 'FirstModelId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({primaryKey: true})
+  public id!: FirstModelId;
+
+  @dbField
+  public title!: string;
+}
 
 const query = Update(FirstModel)
   .values({
     title: 'New book'
   })
-  .where(({id}) => id.eq(2))
+  .where(({id}) => id.eq(2 as FirstModelId));
 ```
 
 ### Upsert
 
 ```ts
-import {Upsert} from '@ts-awesome/orm';
+import {Branded, dbField, dbTable, Upsert} from '@ts-awesome/orm';
+
+type FirstModelId = Branded<number, 'FirstModelId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({primaryKey: true})
+  public id!: FirstModelId;
+
+  @dbField
+  public title!: string;
+}
 
 const query = Upsert(FirstModel)
   .values({
     title: 'New book'
   })
-  .where(({id}) => id.eq(2))
+  .where(({id}) => id.eq(2 as FirstModelId))
   // conflict resolution index is defined in @dbTable decorator
-  .conflict('index_name')
+  .conflict('index_name');
 ```
 
 
 ### Delete
 
 ```ts
-import {Delete} from '@ts-awesome/orm';
+import {Branded, dbField, dbTable, Delete} from '@ts-awesome/orm';
+
+type AuthorId = Branded<number, 'AuthorId'>;
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({name: 'author_id'})
+  public authorId!: AuthorId;
+}
 
 const query = Delete(FirstModel)
-  .where(({authorId}) => authorId.eq(2))
+  .where(({authorId}) => authorId.eq(2 as AuthorId));
+```
+
+
+### Window Functions
+
+The ORM supports standard SQL window functions using the `Window` builder.
+
+```typescript
+import {alias, dbField, dbTable, desc, row_number, Select, Window} from '@ts-awesome/orm';
+
+@dbTable('first_table')
+class FirstModel {
+  @dbField({primaryKey: true})
+  public id!: number;
+
+  @dbField({name: 'author_id'})
+  public authorId!: number;
+
+  @dbField({name: 'created_at'})
+  public createdAt!: Date;
+}
+
+// Define the window
+const w = new Window(FirstModel)
+  .partitionBy(['authorId'])
+  .orderBy(desc('createdAt'));
+
+const query = Select(FirstModel)
+  .columns(({id, authorId}) => [
+    id,
+    authorId,
+    // Use the window definition
+    alias(row_number(w), 'row_num')
+  ]);
+```
+
+Supported functions: `row_number`, `rank`, `dense_rank`, `percent_rank`, `cume_dist`, `ntile`, `lag`, `lead`, `first_value`, `last_value`, `nth_value`.
+
+Window framing is supported via `range()`, `rows()`, `groups()`, and `start()/end()/exclusion()`.
+
+```ts
+const framed = new Window(FirstModel)
+  .partitionBy(['authorId'])
+  .orderBy(desc('createdAt'))
+  .rows()
+  .start(1, 'PRECEDING')
+  .end('CURRENT ROW');
+```
+
+
+# Branded Types
+
+To improve type safety for IDs, you can use `Branded<T, Brand>`.
+
+```typescript
+import {Branded, dbField, dbTable} from '@ts-awesome/orm';
+
+// Branded ID types (best practice)
+type UserId = Branded<number, 'UserId'>;
+
+@dbTable('users')
+class User {
+  @dbField({primaryKey: true})
+  public id!: UserId;
+}
+
+// Now you can't accidentally pass a plain number or a different ID type
+// const user: User = ...;
+// const otherId: OrderId = 5;
+// user.id = otherId; // Error
+// user.id = 5 as UserId; // OK
+
+// For string-based UIDs (UUID, NanoID, etc.)
+type OrderUid = Branded<string, 'OrderUid'>;
+
+@dbTable('orders')
+class Order {
+  @dbField({primaryKey: true})
+  public uid!: OrderUid;
+}
+
+// const orderUid = 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11' as OrderUid;
+```
+
+Array models are supported using `model: [Class]`.
+
+```ts
+@dbTable('groups')
+class Group {
+  @dbField({model: [String]})
+  public tags!: string[];
+}
+```
+
+# Test Driver
+
+The `@ts-awesome/orm/test-driver` module provides a powerful mechanism to unit test your services without a real database. It allows you to mock query results and inspect executed queries.
+
+```typescript
+import {dbField, dbTable, Select} from '@ts-awesome/orm';
+import {TestCompiler, TestDriver} from '@ts-awesome/orm/test-driver';
+
+@dbTable('users')
+class User {
+  @dbField({primaryKey: true})
+  public id!: number;
+}
+
+const driver = new TestDriver();
+const compiler = new TestCompiler();
+
+// Mock results
+driver.whenSelect('users').return([{ id: 1, name: 'Alice' }]);
+
+// Assertions
+expect(driver.executedQueries[0].tableName).toBe('users');
+
+// Include sensitive fields when reading
+const results = await driver.execute(compiler.compile(Select(User)), User, true);
 ```
 
+For full documentation, please refer to the [Test Driver README](src/test-driver/README.md).
 
 # License
 May be freely distributed under the [MIT license](https://opensource.org/licenses/MIT).