prisma-ts-select 0.0.34 → 0.1.3

package/README.md

@@ -4,10 +4,21 @@
 ![build](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/CI.yml/badge.svg)
 ![license](https://img.shields.io/github/license/adrianbrowning/prisma-ts-select)
 
+## Test Matrix
+
+|                | SQLite | MySQL | PostgreSQL |
+|----------------|--------|-------|------------|
+| **Prisma v6**  | ![v6-sqlite](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v6-sqlite.yml/badge.svg) | ![v6-mysql](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v6-mysql.yml/badge.svg) | ![v6-postgresql](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v6-pg.yml/badge.svg) |
+| **Prisma v7**  | ![v7-sqlite](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v7-sqlite.yml/badge.svg) | ![v7-mysql](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v7-mysql.yml/badge.svg) | ![v7-postgresql](https://github.com/adrianbrowning/prisma-ts-select/actions/workflows/test-v7-pg.yml/badge.svg) |
+
 <!-- toc -->
 
   * [Summary](#summary)
   * [Installation](#installation)
+  * [Setup](#setup)
+    + [Schema](#schema)
+    + [Client — Prisma v6](#client--prisma-v6)
+    + [Client — Prisma v7](#client--prisma-v7)
   * [Supported DBs](#supported-dbs)
   * [Usage](#usage)
     + [Generator](#generator)
@@ -18,6 +29,13 @@
         * [SQL](#sql)
       - [Example - Inline Alias Syntax](#example---inline-alias-syntax)
         * [SQL](#sql-1)
+    + [`.$with`](#with)
+      - [Example — CTE as joined table](#example--cte-as-joined-table)
+        * [SQL](#sql-2)
+      - [Example — CTE as base table](#example--cte-as-base-table)
+        * [SQL](#sql-3)
+      - [Example — Multiple CTEs](#example--multiple-ctes)
+        * [SQL](#sql-4)
     + [Table Aliases](#table-aliases)
       - [Table Alias Syntax Options](#table-alias-syntax-options)
       - [Basic Table Alias](#basic-table-alias)
@@ -32,6 +50,8 @@
         * [SQL](#sql-5)
         * [SQL](#sql-6)
     + [Joins](#joins)
+      - [Dialect Support](#dialect-support)
+      - [Nullability Semantics](#nullability-semantics)
       - [`.join`](#join)
         * [Example](#example-1)
         * [SQL](#sql-7)
@@ -44,6 +64,15 @@
         * [Example](#example-3)
         * [SQL](#sql-9)
         * [Parameters](#parameters-2)
+      - [`.innerJoin`](#innerjoin)
+      - [`.leftJoin`](#leftjoin)
+      - [`.crossJoin`](#crossjoin)
+      - [`.rightJoin`](#rightjoin) *(MySQL / PostgreSQL)*
+      - [`.fullJoin`](#fulljoin) *(PostgreSQL only)*
+      - [`.manyToManyJoin`](#manytomanyjoin)
+        * [Example](#example-4)
+        * [SQL](#sql-10)
+        * [Parameters](#parameters-3)
     + [Where](#where)
       - [`.where`](#where)
         * [TypeSyntax](#typesyntax)
@@ -75,6 +104,7 @@
         * [SQL](#sql-15)
       - [Example - Join table](#example---join-table)
         * [SQL](#sql-16)
+      - [`.selectAllOmit`](#selectallomit)
       - [`.select`](#select)
       - [Example - `*`](#example---)
         * [SQL](#sql-17)
@@ -102,15 +132,14 @@
     + [Offset](#offset)
       - [Example](#example-12)
         * [SQL](#sql-27)
+  * [Select Functions](#select-functions)
+    + [Shared (all dialects)](#shared-all-dialects)
+    + [MySQL-specific](#mysql-specific)
+    + [PostgreSQL-specific](#postgresql-specific)
+    + [SQLite-specific](#sqlite-specific)
   * [Future updates](#future-updates)
   * [Changelog / Versioning](#changelog--versioning)
   * [License](#license)
-- [prisma-ts-select](#prisma-ts-select)
-  * [Install](#install)
-  * [Setup](#setup)
-    + [Extract](#extract)
-  * [Usage](#usage-1)
-
 <!-- tocstop -->
 
 ## Summary
@@ -119,13 +148,9 @@
 It simplifies the selection of fields in Prisma queries, ensuring type safety and reducing boilerplate when working with nested fields. 
 Ideal for developers seeking an efficient, type-safe way to select data with Prisma in TypeScript.
 
-[!NOTE]
-> This has been built mostly around MySQL. Most methods should work across the board.<br/>
-> Known exceptions include:
-> - HAVING
->   - SQLite 
->     - Requires you to have either an aggregate function in the `SELECT` or make use of `GROUP BY`
->     - Can only use columns that are specified in `SELECT` or `GROUP BY`
+> [!NOTE]
+> Fully tested on SQLite, MySQL, and PostgreSQL. Known exceptions:
+> - HAVING on SQLite requires either an aggregate function in `SELECT` or a `GROUP BY` clause, and can only reference columns from `SELECT` or `GROUP BY`.
 
 
 ## Installation
@@ -137,15 +162,149 @@ npm install prisma-ts-select
 pnpm add prisma-ts-select
 ```
 
+## Setup
+
+### Schema
+
+Add both generators to `prisma/schema.prisma`. The `output` path is relative to the schema file.
+
+```prisma
+generator prisma-ts-select {
+  provider = "prisma-ts-select"
+  output   = "../generated/prisma-ts-select"
+}
+```
+
+#### Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `output` | *(required)* | Output directory, relative to schema file |
+| `packageName` | `prisma-ts-select-<hash>` | Package name in the generated `package.json`. Defaults to a stable hash of the output path — set this when referencing the generated output as a workspace package. |
+
+Example with `packageName`:
+
+```prisma
+generator prisma-ts-select {
+  provider    = "prisma-ts-select"
+  output      = "../generated/prisma-ts-select"
+  packageName = "my-app-prisma-types"
+}
+```
+
+Then register as a workspace package and import by name:
+
+**npm / yarn** — `package.json`:
+```json
+{
+  "workspaces": ["generated/prisma-ts-select"]
+}
+```
+
+**pnpm** — `pnpm-workspace.yaml`:
+```yaml
+packages:
+  - generated/prisma-ts-select
+```
+
+Then add it as a dependency:
+```shell
+pnpm add my-app-prisma-types
+```
+
+```typescript
+import tsSelectExtend from 'my-app-prisma-types/extend-v7.js'
+```
+
+The client generator differs between Prisma versions:
+
+**Prisma v6**
+```prisma
+generator client {
+  provider = "prisma-client-js"
+  output   = "../generated/prisma"
+}
+```
+
+**Prisma v7**
+```prisma
+generator client {
+  provider = "prisma-client"
+  output   = "../generated/prisma"
+}
+```
+
+Then generate:
+
+```shell
+pnpm exec prisma generate
+```
+
+### Client — Prisma v6
+
+No driver adapter needed. Import from the generated `extend-v6.js`:
+
+```typescript
+import { PrismaClient } from './generated/prisma/index.js'
+import tsSelectExtend from './generated/prisma-ts-select/extend-v6.js'
+
+export const prisma = new PrismaClient().$extends(tsSelectExtend)
+```
+
+### Client — Prisma v7
+
+Prisma v7 requires a driver adapter. Install the adapter for your database and import from the generated `extend-v7.js`:
+
+**SQLite**
+```shell
+pnpm add @prisma/adapter-better-sqlite3
+```
+```typescript
+import { PrismaClient } from './generated/prisma/client.ts'
+import tsSelectExtend from './generated/prisma-ts-select/extend-v7.js'
+import { PrismaBetterSqlite3 } from '@prisma/adapter-better-sqlite3'
+
+const adapter = new PrismaBetterSqlite3({ url: process.env.DATABASE_URL })
+export const prisma = new PrismaClient({ adapter }).$extends(tsSelectExtend)
+```
+
+**MySQL**
+```shell
+pnpm add @prisma/adapter-mariadb
+```
+```typescript
+import { PrismaClient } from './generated/prisma/client.ts'
+import tsSelectExtend from './generated/prisma-ts-select/extend-v7.js'
+import { PrismaMariaDb } from '@prisma/adapter-mariadb'
+
+const url = new URL(process.env.DATABASE_URL!)
+const adapter = new PrismaMariaDb({
+  host: url.hostname, port: +url.port,
+  user: url.username, password: url.password,
+  database: url.pathname.slice(1),
+})
+export const prisma = new PrismaClient({ adapter }).$extends(tsSelectExtend)
+```
+
+**PostgreSQL**
+```shell
+pnpm add @prisma/adapter-pg
+```
+```typescript
+import { PrismaClient } from './generated/prisma/client.ts'
+import tsSelectExtend from './generated/prisma-ts-select/extend-v7.js'
+import { PrismaPg } from '@prisma/adapter-pg'
+
+const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL })
+export const prisma = new PrismaClient({ adapter }).$extends(tsSelectExtend)
+```
+
 ## Supported DBs
  
-I have tested this currently on the following databases.
+Fully tested on:
 
 - SQLite
 - MySQL
-
-Most items should also work for
-
 - PostgreSQL
 
 Other DBs will be added when I have chance.
@@ -207,31 +366,101 @@ The way the methods are chained, are heavily inspired by [Dr Milan Milanović](h
 This takes the `base` table to work from.
 
 #### Example
-```typescript
-prisma.$from("User")
+```typescript file=../usage-sqlite-v7/tests/readme/from-basic.ts region=example-$from
+prisma.$from("User");
 ```
 
 #### Example - With Table Alias
-```typescript
-prisma.$from("User", "u")
+```typescript file=../usage-sqlite-v7/tests/readme/from-inline-alias.ts region=example-$from
+prisma.$from("User u");
+```
+##### SQL
+```sql file=../usage-sqlite-v7/tests/readme/from-inline-alias.ts region=inline-alias-sql
+FROM User AS `u`;
+```
+**Note:** Alias can be inline (space-separated) or as second parameter.
+**Note:** Table aliases are particularly useful for self-joins where you need to join a table to itself with different aliases.
+
+
+### `.$with`
+
+Defines one or more Common Table Expressions (CTEs) that can be referenced in `.join()` calls or used directly as the base table via `.from('cteName')`.
+
+| Param | Description |
+|-------|-------------|
+| `name` | CTE name — used to reference the CTE in `join()` or `from()` |
+| `query` | Any query built with `.$from()` |
+
+Chain `.with(name, query)` before `.from()` to define additional CTEs.
+
+#### Example — CTE as joined table
+
+```typescript file=../../shared-tests/readme/with-cte.ts region=join
+const posts = prisma.$from("Post").select("id").select("authorId").select("title");
+
+prisma.$with("pp", posts)
+      .from("User")
+      .join("pp", "authorId", "User.id")
 ```
 
 ##### SQL
-```sql
-FROM User AS u
+
+```sql file=../../shared-tests/readme/with-cte.ts region=join-sql
+WITH pp AS (
+SELECT id, authorId, title 
+FROM Post) 
+FROM User 
+JOIN pp ON pp.authorId = User.id;
 ```
 
-**Note:** Table aliases are particularly useful for self-joins where you need to join a table to itself with different aliases.
+#### Example — CTE as base table
 
-#### Example - Inline Alias Syntax
-```typescript
-prisma.$from("User u")
+Use `.from('cteName')` to query a CTE directly, without a real table as the base.
+
+```typescript file=../../shared-tests/readme/with-cte.ts region=cte-base
+const posts = prisma.$from("Post").select("id").select("title");
+
+prisma.$with("pp", posts)
+      .from("pp")
+      .select("pp.id")
+      .select("pp.title")
 ```
+
 ##### SQL
-```sql
-FROM User AS u
+
+```sql file=../../shared-tests/readme/with-cte.ts region=cte-base-sql
+WITH pp AS (
+SELECT id, title 
+FROM Post) 
+SELECT pp.id AS `pp.id`, pp.title AS `pp.title` 
+FROM pp;
+```
+
+**Type safety:** only CTEs declared in `.$with()` / `.with()` are accepted by `.from()`. Unknown CTE names are rejected at compile time.
+
+#### Example — Multiple CTEs
+
+```typescript file=../../shared-tests/readme/with-cte.ts region=multi-cte
+const posts = prisma.$from("Post").select("id").select("authorId").select("title");
+const users = prisma.$from("User").select("id").select("name");
+
+prisma.$with("pp", posts)
+      .with("uu", users)
+      .from("User")
+      .join("pp", "authorId", "User.id")
+```
+
+##### SQL
+
+```sql file=../../shared-tests/readme/with-cte.ts region=multi-cte-sql
+WITH pp AS (
+SELECT id, authorId, title 
+FROM Post), uu AS (
+SELECT id, name 
+FROM User) 
+FROM User 
+JOIN pp ON pp.authorId = User.id;
 ```
-**Note:** Alias can be inline (space-separated) or as second parameter.
 
 ### Table Aliases
 
@@ -243,49 +472,33 @@ Table aliases allow you to give tables shorter or more meaningful names in your
 #### Table Alias Syntax Options
 
 Multiple syntaxes supported:
-- **Inline in .$from()**: `prisma.$from("User u")``
+- **Inline in .$from()**: `prisma.$from("User u")` - Note: Second parameter syntax `.$from("User", "u")` is NOT supported
 - **Inline in .join()**: `.join("Post p", "authorId", "User.id")`
 - **Object syntax**: `.join({table: "Post", src: "authorId", on: "User.id", alias: "p"})`
 
-#### Basic Table Alias
-
-```typescript
-prisma.$from("User", "u")
-  .select("u.name")
-  .select("u.email")
-  .run();
-```
-
-##### SQL
-```sql
-SELECT name, email FROM User AS u;
-```
-
 #### Table Aliases with Joins
 
 ##### Inline Alias Syntax
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/table-alias.ts region=inline-join
 prisma.$from("User u")
-  .join("Post p", "authorId", "u.id")
-  .select("u.name")
-  .select("p.title")
-  .run();
+      .join("Post p", "authorId", "u.id")
+      .select("u.name")
+      .select("p.title");
 ```
 
 ##### Object Syntax
-```typescript
-prisma.$from("User", "u")
-  .join({table: "Post", src: "authorId", on: "u.id", alias: "p"})
-  .select("u.name")
-  .select("p.title")
-  .run();
+```typescript file=../usage-sqlite-v7/tests/readme/table-alias.ts region=object-join-1
+prisma.$from("User u")
+      .join({table: "Post", src: "authorId", on: "u.id", alias: "p"})
+      .select("u.name")
+      .select("p.title");
 ```
 
 ##### SQL
-```sql
-SELECT name, title
-FROM User AS u
-JOIN Post AS p ON authorId = u.id;
+```sql file=../usage-sqlite-v7/tests/readme/table-alias.ts region=inline-join-sql
+SELECT name, title 
+FROM User AS `u` 
+JOIN Post AS `p` ON p.authorId = u.id;
 ```
 
 **Note:** The object syntax provides a foundation for future enhancements like multiple join conditions and complex WHERE-style conditions in joins.
@@ -294,60 +507,77 @@ JOIN Post AS p ON authorId = u.id;
 
 Self-joins require aliases to distinguish between the different "instances" of the same table:
 
-```typescript
-prisma.$from("User", "u1")
-  .joinUnsafeTypeEnforced("User", "id", "u1.id", "u2")
-  .select("u1.name", "user1Name")
-  .select("u2.name", "user2Name")
-  .run();
+```typescript file=../usage-sqlite-v7/tests/readme/table-alias.ts region=self-join
+prisma.$from("User u1")
+      .joinUnsafeTypeEnforced("User u2", "id", "u1.id")
+      .select("u1.name", "user1Name")
+      .select("u2.name", "user2Name");
 ```
 
 ##### SQL
-```sql
-SELECT u1.name AS `user1Name`, u2.name AS `user2Name`
-FROM User AS u1
-JOIN User AS u2 ON User.id = u1.id;
+```sql file=../usage-sqlite-v7/tests/readme/table-alias.ts region=self-join-sql
+SELECT u1.name AS `user1Name`, u2.name AS `user2Name` 
+FROM User AS `u1` 
+JOIN User AS `u2` ON u2.id = u1.id;
 ```
 
 #### Table.* with Aliases
 
 You can use the `alias.*` syntax to select all columns from an aliased table:
 
-```typescript
-prisma.$from("User", "u")
-  .select("u.*")
-  .run();
+```typescript file=../usage-sqlite-v7/tests/readme/table-alias.ts region=star-single
+prisma.$from("User u")
+      .select("u.*");
 ```
 
 ##### SQL
-```sql
-SELECT u.id, u.email, u.name FROM User AS u;
+```sql file=../usage-sqlite-v7/tests/readme/table-alias.ts region=star-single-sql
+SELECT id, email, name, age 
+FROM User AS `u`;
 ```
 
 With joins:
-```typescript
-prisma.$from("User", "u")
-  .join("Post", "authorId", "u.id", "p")
-  .select("u.*")
-  .select("p.*")
-  .run();
+```typescript file=../usage-sqlite-v7/tests/readme/table-alias.ts region=star-join
+prisma.$from("User u")
+      .join("Post p", "authorId", "u.id")
+      .select("u.*")
+      .select("p.*");
 ```
 
 ##### SQL
-```sql
-SELECT u.id AS `u.id`, u.email AS `u.email`, u.name AS `u.name`,
-       p.id AS `p.id`, p.title AS `p.title`, p.content AS `p.content`
-FROM User AS u
-JOIN Post AS p ON authorId = u.id;
+```sql file=../usage-sqlite-v7/tests/readme/table-alias.ts region=star-join-sql
+SELECT u.id AS `u.id`, u.email AS `u.email`, u.name AS `u.name`, u.age AS `u.age`, p.id AS `p.id`, p.title AS `p.title`, p.content AS `p.content`, p.published AS `p.published`, p.createdAt AS `p.createdAt`, p.authorId AS `p.authorId`, p.lastModifiedById AS `p.lastModifiedById`, p.metadata AS `p.metadata` 
+FROM User AS `u` 
+JOIN Post AS `p` ON p.authorId = u.id;
 ```
 
 ### Joins
+
+#### Dialect Support
+
+| Method | SQLite | MySQL | PostgreSQL |
+|--------|--------|-------|------------|
+| `join` / `innerJoin` / `crossJoin` / `leftJoin` | ✓ | ✓ | ✓ |
+| `rightJoin` | ✗ | ✓ | ✓ |
+| `fullJoin` | ✗ | ✗ | ✓ |
+
+Each method has `*UnsafeTypeEnforced` and `*UnsafeIgnoreType` variants with the same dialect restrictions.
+
+#### Nullability Semantics
+
+| Join type | Effect on result type |
+|-----------|----------------------|
+| `join` / `innerJoin` / `crossJoin` | No nullable change — both sides guaranteed to match |
+| `leftJoin` | Joined table fields become `T \| null` |
+| `rightJoin` | Base table fields become `T \| null` |
+| `fullJoin` | Both sides become `T \| null` |
+
 #### `.join`
 
 Using the defined links (foreign keys) defined in the schema, provides a type-safe way of joining on tables.
 
 ##### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/join-basic.ts region=example
 prisma.$from("User")
       .join("Post", "authorId", "User.id");
 ```
@@ -358,9 +588,9 @@ prisma.$from("User")
 
 The resulting SQL will look like:
 
-```sql
-FROM User
-JOIN Post ON authorId = User.id;
+```sql file=../usage-sqlite-v7/tests/readme/join-basic.ts region=join-basic-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id;
 ```
 
 ##### Parameters
@@ -369,27 +599,107 @@ JOIN Post ON authorId = User.id;
 | `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
 | `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
 | `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a FK that is defined in the schema definition.                           |
+| `where`     | *(optional)* Criteria added to the `ON` clause (`ON a = b AND ...`). Same syntax as `.where()`. Keys scoped to the joined table only.                         |
+| `joinType`  | *(optional)* Join variant. One of `"INNER"`, `"LEFT"`, `"LEFT OUTER"`, `"RIGHT"`, `"RIGHT OUTER"`, `"FULL"`, `"FULL OUTER"`, `"CROSS"`. Default: plain `JOIN`. |
 
 **Alternative Syntaxes:**
 ```typescript
 // Inline alias
 .join("Post p", "authorId", "User.id")
-    
+
 // Object syntax
 .join({
   table: "Post",
   src: "authorId",
   on: "User.id",
-  alias: "p"  // optional
+  alias: "p",           // optional
+  joinType: "LEFT",     // optional
+  where: { "Post.published": true }  // optional
 })
-``` 
+```
+
+##### Join Type
+
+Control the SQL join variant via the `joinType` option:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-left
+prisma.$from("User")
+      .join("Post", "authorId", "User.id", { joinType: "LEFT" })
+```
+
+```sql file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-left-sql
+FROM User 
+LEFT JOIN Post ON Post.authorId = User.id;
+```
+
+`CROSS JOIN` has no `ON` clause — it is suppressed automatically:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-cross
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.id", { joinType: "CROSS" })
+```
+
+```sql file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-cross-sql
+FROM User 
+CROSS JOIN Post;
+```
+
+`joinType` and `where` can be combined — `where` is ignored for `CROSS`:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-with-where
+prisma.$from("User")
+      .join("Post", "authorId", "User.id", {
+        joinType: "LEFT",
+        where: { "Post.published": true }
+      })
+```
+
+```sql file=../usage-sqlite-v7/tests/readme/join-type.ts region=join-type-with-where-sql
+FROM User 
+LEFT JOIN Post ON Post.authorId = User.id AND Post.published = true;
+```
+
+##### Join-level WHERE
+
+Conditions placed on the `ON` clause instead of the top-level `WHERE`:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-where.ts region=join-where-example
+prisma.$from("User")
+      .join("Post", "authorId", "User.id", { where: { "Post.published": true } })
+```
+
+```sql file=../usage-sqlite-v7/tests/readme/join-where.ts region=join-where-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id AND Post.published = true;
+```
+
+Supports the same MongoDB-inspired operators as `.where()` — `$AND`, `$OR`, `$NOT`, `$NOR`:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-where.ts region=join-where-ops-example
+prisma.$from("User")
+      .join("Post", "authorId", "User.id", {
+        where: {
+          $AND: [
+            { "Post.published": true },
+            { "Post.id": { op: ">", value: 0 } }
+          ]
+        }
+      })
+```
+
+```sql file=../usage-sqlite-v7/tests/readme/join-where.ts region=join-where-ops-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id AND (Post.published = true AND Post.id > 0);
+```
+
+> **Type safety**: only `"JoinedTable.field"` keys are accepted — other tables' fields are rejected at compile time.
 
 #### `.joinUnsafeTypeEnforced`
 
 Unlike the `.join` command, this will allow you to join on columns that are not explicitly linked by a FK, but have the same type.
 
 ##### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/join-unsafe.ts region=type-enforced
 prisma.$from("User")
       .joinUnsafeTypeEnforced("Post", "title", "User.name");
 ```
@@ -398,7 +708,7 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/join-unsafe.ts region=type-enforced-sql
 FROM User 
 JOIN Post ON Post.title = User.name;
 ```
@@ -409,13 +719,15 @@ JOIN Post ON Post.title = User.name;
 | `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
 | `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
 | `reference` | `Table.Column` to a previously defined table (either the base, or another join), with a column that is of the same type.                                       |
+| `where`     | *(optional)* Criteria added to the `ON` clause. See [Join-level WHERE](#join-level-where).                                                                    |
+| `joinType`  | *(optional)* Join variant. See [Join Type](#join-type).                                                                                                       |
 
 #### `.joinUnsafeIgnoreType`
 
 Unlike the `.joinUnsafeIgnoreType` command, this will allow you to join on columns that are not explicitly linked by a FK, and do not have the same type.
 
 ##### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/join-unsafe.ts region=ignore-type
 prisma.$from("User")
       .joinUnsafeIgnoreType("Post", "id", "User.name");
 ```
@@ -424,9 +736,9 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/join-unsafe.ts region=ignore-type-sql
 FROM User 
-JOIN Post ON Post.id = User.name
+JOIN Post ON Post.id = User.name;
 ```
 
 ##### Parameters
@@ -435,198 +747,497 @@ JOIN Post ON Post.id = User.name
 | `table`     | The table to join on (supports inline alias: `"Post p"` or `"Post", "p"`). <br/>TS autocomplete will show tables that can join with previously defined tables on. |
 | `field`     | Column on table. <br/>TS autocomplete will show known columns that this table, can join with previously defined tables on.                                     |
 | `reference` | `Table.Column` to a previously defined table (either the base, or another join). Referencing any column, of any type.                                          |
+| `where`     | *(optional)* Criteria added to the `ON` clause. See [Join-level WHERE](#join-level-where).                                                                    |
+| `joinType`  | *(optional)* Join variant. See [Join Type](#join-type).                                                                                                       |
 
-### Where
+#### `.manyToManyJoin`
 
-#### `.where`
+Joins through Prisma's implicit or explicit many-to-many junction tables. Automatically detects the junction table and join columns from the generated schema.
 
-The `where` syntax takes inspiration from how mongoDB does queries.
+##### Example
+```typescript file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-basic
+prisma.$from("M2M_Post")
+      .manyToManyJoin("M2M_Category");
+```
 
-##### TypeSyntax
-```TypeScript
-type WhereClause = {
-  "Table.Column": <value> | { "op": "<condition>", "value": <value> }
-  "$AND": [WhereClause, ...Array<WhereClause>],
-  "$OR": [WhereClause, ...Array<WhereClause>],
-  "$NOT": [WhereClause, ...Array<WhereClause>],
-  "$NOR": [WhereClause, ...Array<WhereClause>]
-}
+##### SQL
+```sql file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-basic-sql
+FROM M2M_Post 
+JOIN _M2M_CategoryToM2M_Post ON _M2M_CategoryToM2M_Post.B = M2M_Post.id 
+JOIN M2M_Category ON M2M_Category.id = _M2M_CategoryToM2M_Post.A;
 ```
 
-##### Operation types
-| Op          | Description | Supported Types       |
-|-------------|-------------|-----------------------|
-| IN          |             | Numbers, String, Date |
-| NOT IN      |             | Numbers, String, Date |
-| BETWEEN     |             | Numbers, Date         |
-| LIKE        |             | String                |
-| NOT LIKE    |             | String                |
-| IS NULL     |             | *                     |
-| IS NOT NULL |             | *                     |
-| \>          |             | Numbers, Date         |
-| \>=         |             | Numbers, Date         |
-| <           |             | Numbers, Date         |
-| <=          |             | Numbers, Date         |
-| !=          |             | Numbers, String, Date |
+##### Parameters
+| Param | Type | Description |
+|-------|------|-------------|
+| `targetTable` | `string` | Target table, optionally with alias: `"M2M_Category"` or `"M2M_Category mc"` |
+| `options.refName` | `string?` | Junction ref name — required when multiple M2M relations point to the same target |
+| `options.source` | `string?` | Explicit source as `"alias.column"` — useful when the source table is aliased |
 
+##### With Alias
+```typescript file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-alias
+prisma.$from("M2M_Post")
+      .manyToManyJoin("M2M_Category mc");
+```
 
-##### Examples
-| Type         | Description                                                              | Example                                                                                                                                                          | SQL                                                               | 
-|--------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
-| Table.Column | A particular Table.Column name                                           | <pre>.where({ <br />  "User.age": 20,<br />  "User.name": {op: "LIKE", value:"Stuart%"},<br />})                                                                 | `(User.age = 20 AND User.name LIKE "Stuart%")`                    |
-| $AND         | Will join all items with a `AND`                                         | <pre>.where({ <br /> $AND:[<br />  {"User.age": {op: ">", value:20}},<br />  {"User.age": {op: "<", value:60}},<br />]})</pre>                                   | `(User.age > 20 AND User.age < 60)`                               |
-| $OR          | Will join all items with a `OR`                                          | <pre>.where({ <br /> $OR:[<br />  {"User.name": {op: "LIKE", value:"a%"}},<br />  {"User.name": {op: "LIKE", value:"d%"}},<br />]})</pre>                        | `(User.name LIKE "a%" OR User.name LIKE "d%")`                    |
-| $NOT         | Will wrap statement in a `NOT (/*...*/)` and join any items with a `AND` | <pre>.where({ <br /> $NOT:[<br />  {"User.age": 20 },<br />  {<br />    "User.age": {op: "=", value:60},<br />    "User.name": "Bob",<br />   },<br />]})</pre>  | `(NOT (User.age = 20 AND (User.age = 60 AND User.name = "Bob")))` |
-| $NOR         | Will wrap statement in a `NOT (/*...*/)` and join any items with a `OR`  | <pre>.where({ <br /> $NOR:[<br />  {"User.age": 20 },<br />  {<br />    "User.age": {op: "!=", value:60},<br />    "User.name": "Bob",<br />   },<br />]})</pre> | `(NOT (User.age = 20 OR (User.age != 60 AND User.name = "Bob")))` |
+```sql file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-alias-sql
+FROM M2M_Post 
+JOIN _M2M_CategoryToM2M_Post ON _M2M_CategoryToM2M_Post.B = M2M_Post.id 
+JOIN M2M_Category AS `mc` ON mc.id = _M2M_CategoryToM2M_Post.A;
+```
 
+##### Named Junction (`refName`)
 
-###### Columns
-```typescript
-prisma.$from("User")
-        .join("Post", "id", "User.name")
-        .where({
-          "User.age": 20,
-          "User.name": {op: "LIKE", value: "Stuart%"},
-        });
+Use `refName` when a model has multiple M2M relations to the same target:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-refname
+prisma.$from("MMM_Post")
+      .manyToManyJoin("MMM_Category", { refName: "M2M_NC_M1" });
 ```
 
-###### $AND
-```typescript
-prisma.$from("User")
-        .join("Post", "id", "User.name")
-        .where({
-          $AND: [
-            {"User.age": {op: ">", value: 20}},
-            {"User.age": {op: "<", value: 60}},
-          ]
-        });
+```sql file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-refname-sql
+FROM MMM_Post 
+JOIN _M2M_NC_M1 ON _M2M_NC_M1.B = MMM_Post.id 
+JOIN MMM_Category ON MMM_Category.id = _M2M_NC_M1.A;
 ```
 
-###### $OR
-```typescript
-prisma.$from("User")
-        .join("Post", "id", "User.name")
-        .where({
-          $OR: [
-            {"User.name": {op: "LIKE", value: "a%"}},
-            {"User.name": {op: "LIKE", value: "d%"}},
-          ]
-        });
+##### Explicit Source (`source`)
+
+Use `source` to pin the source alias and column when the source table is aliased:
+
+```typescript file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-source
+prisma.$from("M2M_Post mp")
+      .manyToManyJoin("M2M_Category mc", { source: "mp.id" });
 ```
 
-###### $NOT
-```typescript
-prisma.$from("User")
-        .join("Post", "id", "User.name")
-        .where({
-          $NOT: [
-            {"User.age": 20},
-            {
-              "User.age": {op: "=", value: 60},
-              "User.name": "Bob",
-            },
-          ]
-        });
+```sql file=../usage-sqlite-v7/tests/readme/join-many-to-many.ts region=m2m-source-sql
+FROM M2M_Post AS `mp` 
+JOIN _M2M_CategoryToM2M_Post ON _M2M_CategoryToM2M_Post.B = mp.id 
+JOIN M2M_Category AS `mc` ON mc.id = _M2M_CategoryToM2M_Post.A;
 ```
 
-###### $NOR
-```typescript
-prisma.$from("User")
-        .join("Post", "id", "User.name")
-        .where({
-          $NOR: [
-            {"User.age": 20},
-            {
-              "User.age": {op: "!=", value: 60},
-              "User.name": "Bob",
-            },
-          ]
-        });
+#### `.innerJoin`
+
+Alias for `.join` — explicitly emits `INNER JOIN`. Same type-safe FK constraints.
+
+##### Example
+```typescript file=../../shared-tests/readme/join-inner.ts region=example
+prisma.$from("User")
+      .innerJoin("Post", "authorId", "User.id")
 ```
 
-#### `.whereNotNull`
+##### SQL
+```sql file=../../shared-tests/readme/join-inner.ts region=sql
+FROM User 
+INNER JOIN Post ON Post.authorId = User.id;
+```
+
+##### `.innerJoinUnsafeTypeEnforced`
+
+Same-type column join, INNER semantics.
+
+```typescript file=../../shared-tests/readme/join-inner.ts region=type-enforced
+prisma.$from("User")
+      .innerJoinUnsafeTypeEnforced("Post", "title", "User.name")
+```
+
+```sql file=../../shared-tests/readme/join-inner.ts region=type-enforced-sql
+FROM User 
+INNER JOIN Post ON Post.title = User.name;
+```
+
+##### `.innerJoinUnsafeIgnoreType`
+
+Any-column join, INNER semantics.
+
+```typescript file=../../shared-tests/readme/join-inner.ts region=ignore-type
+prisma.$from("User")
+      .innerJoinUnsafeIgnoreType("Post", "id", "User.name")
+```
+
+```sql file=../../shared-tests/readme/join-inner.ts region=ignore-type-sql
+FROM User 
+INNER JOIN Post ON Post.id = User.name;
+```
 
-This will remove the `null` type from the union of types of the current table column.
-To use `.whereNotNull`, you need to add it before a `.where`.  
+---
+
+#### `.leftJoin`
+
+FK-safe LEFT JOIN. Joined table fields become `T | null` in the result type.
 
 ##### Example
+```typescript file=../../shared-tests/readme/join-left.ts region=example
+prisma.$from("User")
+      .leftJoin("Post", "authorId", "User.id")
+```
+
+##### SQL
+```sql file=../../shared-tests/readme/join-left.ts region=sql
+FROM User 
+LEFT JOIN Post ON Post.authorId = User.id;
+```
+
+##### `.leftJoinUnsafeTypeEnforced`
+
+Same-type column join, LEFT semantics.
+
+```typescript file=../../shared-tests/readme/join-left.ts region=type-enforced
+prisma.$from("User")
+      .leftJoinUnsafeTypeEnforced("Post", "title", "User.name")
+```
+
+```sql file=../../shared-tests/readme/join-left.ts region=type-enforced-sql
+FROM User 
+LEFT JOIN Post ON Post.title = User.name;
+```
+
+##### `.leftJoinUnsafeIgnoreType`
+
+Any-column join, LEFT semantics.
+
+```typescript file=../../shared-tests/readme/join-left.ts region=ignore-type
+prisma.$from("User")
+      .leftJoinUnsafeIgnoreType("Post", "id", "User.name")
+```
+
+```sql file=../../shared-tests/readme/join-left.ts region=ignore-type-sql
+FROM User 
+LEFT JOIN Post ON Post.id = User.name;
+```
+
+---
+
+#### `.crossJoin`
+
+Produces a cartesian product — no `ON` clause. All dialects supported.
+
+##### Example
+```typescript file=../../shared-tests/readme/join-cross.ts region=example
+prisma.$from("User")
+      .crossJoin("Post")
+```
+
+##### SQL
+```sql file=../../shared-tests/readme/join-cross.ts region=sql
+FROM User 
+CROSS JOIN Post;
+```
+
+##### `.crossJoinUnsafeTypeEnforced` / `.crossJoinUnsafeIgnoreType`
+
+Type-permission variants — still emit `CROSS JOIN` with no `ON` clause (takes only a table argument).
+
+```typescript file=../../shared-tests/readme/join-cross.ts region=type-enforced
+prisma.$from("User")
+      .crossJoinUnsafeTypeEnforced("Post")
+```
+
+```sql file=../../shared-tests/readme/join-cross.ts region=type-enforced-sql
+FROM User 
+CROSS JOIN Post;
+```
+
+---
+
+#### `.rightJoin`
+
+> **MySQL / PostgreSQL only** — not supported by SQLite.
+
+Base table fields become `T | null`. Use when the joined table drives the result set.
+
+##### Example
+```typescript
+prisma.$from("Post")
+      .rightJoin("User", "id", "Post.authorId")
+```
+
+##### SQL
+```sql
+FROM Post RIGHT JOIN User ON User.id = Post.authorId;
+```
+
+##### `.rightJoinUnsafeTypeEnforced`
+```typescript
+prisma.$from("Post")
+      .rightJoinUnsafeTypeEnforced("User", "name", "Post.title")
+```
+
+##### `.rightJoinUnsafeIgnoreType`
+```typescript
+prisma.$from("Post")
+      .rightJoinUnsafeIgnoreType("User", "id", "Post.title")
+```
+
+---
+
+#### `.fullJoin`
+
+> **PostgreSQL only** — not supported by SQLite or MySQL.
+
+Both sides become `T | null`. Use for outer joins where either side may have no match.
+
+##### Example
+```typescript
+prisma.$from("User")
+      .fullJoin("Post", "authorId", "User.id")
+```
+
+##### SQL
+```sql
+FROM User FULL JOIN Post ON Post.authorId = User.id;
+```
+
+##### `.fullJoinUnsafeTypeEnforced`
+```typescript
+prisma.$from("User")
+      .fullJoinUnsafeTypeEnforced("Post", "title", "User.name")
+```
+
+##### `.fullJoinUnsafeIgnoreType`
 ```typescript
 prisma.$from("User")
-        .join("Post", "authorId", "User.id")
-        .whereNotNull("User.name");
+      .fullJoinUnsafeIgnoreType("Post", "id", "User.name")
+```
+
+---
+
+### Where
+
+#### `.where`
+
+The `where` syntax takes inspiration from how mongoDB does queries.
+
+##### TypeSyntax
+```TypeScript
+type WhereClause = {
+  "Table.Column": <value>
+    | [<value>, ...<value>[]]                          // scalar array → IN
+    | { "op": "<condition>", "value": <value> }
+    | [{ "op": "<condition>", "value": <value> }, ...]  // op-array → OR
+  "$AND": [WhereClause, ...Array<WhereClause>],
+  "$OR":  [WhereClause, ...Array<WhereClause>],
+  "$NOT": [WhereClause, ...Array<WhereClause>],
+  "$NOR": [WhereClause, ...Array<WhereClause>]
+}
+```
+
+##### Operation types
+| Op          | Description | Supported Types       |
+|-------------|-------------|-----------------------|
+| IN          |             | Numbers, String, Date |
+| NOT IN      |             | Numbers, String, Date |
+| BETWEEN     |             | Numbers, Date         |
+| LIKE        |             | String                |
+| NOT LIKE    |             | String                |
+| IS NULL     |             | *                     |
+| IS NOT NULL |             | *                     |
+| \>          |             | Numbers, Date         |
+| \>=         |             | Numbers, Date         |
+| <           |             | Numbers, Date         |
+| <=          |             | Numbers, Date         |
+| !=          |             | Numbers, String, Date |
+| =           |             | Numbers, String, Date |
+
+
+##### Examples
+| Type         | Description                                                              | Example                                                                                                                                                          | SQL                                                               | 
+|--------------|--------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
+| Table.Column | A particular Table.Column name                                           | <pre>.where({ <br />  "User.age": 20,<br />  "User.name": {op: "LIKE", value:"Stuart%"},<br />})                                                                 | `(User.age = 20 AND User.name LIKE "Stuart%")`                    |
+| $AND         | Will join all items with a `AND`                                         | <pre>.where({ <br /> $AND:[<br />  {"User.age": {op: ">", value:20}},<br />  {"User.age": {op: "<", value:60}},<br />]})</pre>                                   | `(User.age > 20 AND User.age < 60)`                               |
+| $OR          | Will join all items with a `OR`                                          | <pre>.where({ <br /> $OR:[<br />  {"User.name": {op: "LIKE", value:"a%"}},<br />  {"User.name": {op: "LIKE", value:"d%"}},<br />]})</pre>                        | `(User.name LIKE "a%" OR User.name LIKE "d%")`                    |
+| $NOT         | Will wrap statement in a `NOT (/*...*/)` and join any items with a `AND` | <pre>.where({ <br /> $NOT:[<br />  {"User.age": 20 },<br />  {<br />    "User.age": {op: "=", value:60},<br />    "User.name": "Bob",<br />   },<br />]})</pre>  | `(NOT (User.age = 20 AND (User.age = 60 AND User.name = "Bob")))` |
+| $NOR         | Will wrap statement in a `NOT (/*...*/)` and join any items with a `OR`  | <pre>.where({ <br /> $NOR:[<br />  {"User.age": 20 },<br />  {<br />    "User.age": {op: "!=", value:60},<br />    "User.name": "Bob",<br />   },<br />]})</pre> | `(NOT (User.age = 20 OR (User.age != 60 AND User.name = "Bob")))` |
+| `Array (scalar)` | Non-empty array of values → SQL `IN` | `.where({ "User.name": ["Alice", "Bob"] })` | `User.name IN ('Alice', 'Bob')` |
+| `Array (op-objects)` | Non-empty array of op-objects → `OR` chain | `.where({ "User.name": [{ op: "LIKE", value: "A%" }, { op: "LIKE", value: "B%" }] })` | `(User.name LIKE 'A%' OR User.name LIKE 'B%')` |
+
+
+###### Columns
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=columns
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        "User.age": 20,
+        "User.name": {op: "LIKE", value: "Stuart%"},
+      });
+```
+
+###### $AND
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=and
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        $AND: [
+          {"User.age": {op: ">", value: 20}},
+          {"User.age": {op: "<", value: 60}},
+        ]
+      });
+```
+
+###### $OR
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=or
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        $OR: [
+          {"User.name": {op: "LIKE", value: "a%"}},
+          {"User.name": {op: "LIKE", value: "d%"}},
+        ]
+      });
+```
+
+###### $NOT
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=not
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        $NOT: [
+          {"User.age": 20},
+          {
+            "User.age": {op: "=", value: 60},
+            "User.name": "Bob",
+          },
+        ]
+      });
+```
+
+###### $NOR
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=nor
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        $NOR: [
+          {"User.age": 20},
+          {
+            "User.age": {op: "!=", value: 60},
+            "User.name": "Bob",
+          },
+        ]
+      });
+```
+
+###### Array (Scalar → IN)
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=array-scalar
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        "User.name": ["Alice", "Bob"],
+      });
+```
+
+###### Array (Op-Object → OR)
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=array-op
+prisma.$from("User")
+      .joinUnsafeIgnoreType("Post", "id", "User.name")
+      .where({
+        "User.name": [
+          { op: "LIKE", value: "A%" },
+          { op: "LIKE", value: "B%" },
+        ],
+      });
+```
+
+#### `.whereNotNull`
+
+Removes `null` from the column's type union and adds an `IS NOT NULL` condition to the WHERE clause.
+Type narrowing is reflected in all downstream `.select()` calls.
+
+##### Example
+```typescript file=../usage-sqlite-v7/tests/readme/whereNotNull.ts region=whereNotNull
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .whereNotNull("User.name")
 ```
 ![whereNotNull](./assets/whereNotNull.gif)
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/whereNotNull.ts region=whereNotNull-sql
 FROM User 
-JOIN Post ON authorId = User.id
-WHERE User.name IS NOT NULL;
+JOIN Post ON Post.authorId = User.id 
+WHERE (User.name IS NOT NULL);
 ```
 
 #### `.whereIsNull`
 
-This will remove the NonNull type from the union of types of the current table column.
-To use `.whereIsNull`, you need to add it before a `.where`.
+Narrows the column's type to exactly `null` and adds an `IS NULL` condition to the WHERE clause.
 
 ##### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/whereNotNull.ts region=whereIsNull
 prisma.$from("User")
-        .join("Post", "authorId", "User.id")
-        .whereIsNull("Post.content");
+      .join("Post", "authorId", "User.id")
+      .whereIsNull("Post.content")
 ```
 ![whereIsNull](./assets/whereIsNull.gif)
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/whereNotNull.ts region=whereIsNull-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+WHERE (Post.content IS NULL);
+```
+
+#### `.where` — fn overload (SQL expressions)
+
+Pass a callback instead of a criteria object to apply SQL functions as conditions. The callback receives the same select-fn context as `.select()`, giving access to `upper`, `lower`, `length`, `count`, `avg`, etc.
+
+```typescript file=../../shared-tests/readme/where.ts region=fn-upper-like
+prisma.$from("User")
+      .where(({ upper }) => [[upper('name'), { op: 'LIKE', value: 'John%' }]])
+      .select("name")
+```
+
+```sql file=../../shared-tests/readme/where.ts region=fn-upper-like-sql
+SELECT name 
 FROM User 
-JOIN Post ON authorId = User.id
-WHERE Post.content IS NULL;
+WHERE UPPER(name) LIKE 'John%';
 ```
 
+Each array element is an `[SQLExpr<T>, condition]` pair — multiple pairs are AND-ed. The condition type is inferred from `SQLExpr<T>`: string expressions accept LIKE/NOT LIKE, numeric expressions accept `>`, `<`, BETWEEN, etc.
+
 #### `.whereRaw`
 
-When you want to write a complex `where`, or you just don't want the TypeSafety offered by the other methods, you can use `.whereRaw`. 
+When you want to write a complex `where`, or you just don't want the TypeSafety offered by the other methods, you can use `.whereRaw`.
 
 ##### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/where.ts region=raw
 prisma.$from("User")
-        .join("Post", "authorId", "User.id")
-        .whereRaw("this is a raw where statement");
+      .join("Post", "authorId", "User.id")
+      .whereRaw("this is a raw where statement");
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/where.ts region=raw-sql
 FROM User 
-JOIN Post ON authorId = User.id
-WHERE this is a raw where statement;
+JOIN Post ON Post.authorId = User.id 
+WHERE this is a raw 
+where statement;
 ```
 
 
 ### Group By
 
-Will allow you to pass a list of columns, that haven been specified from the `.$from` and any `.join` methods. 
+Will allow you to pass a list of columns, that haven been specified from the `.$from` and any `.join` methods.
 
 #### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/groupby.ts region=basic
 prisma.$from("User")
-        .join("Post", "authorId", "User.id")
-        .groupBy(["name", "Post.content"]);
+      .join("Post", "authorId", "User.id")
+      .groupBy(["name", "Post.content"]);
 ```
 ![groupBy](./assets/groupBy.gif)
 
 #### SQL
 The resulting SQL will look like:
 
-```sql
+```sql file=../usage-sqlite-v7/tests/readme/groupby.ts region=basic-sql
 FROM User 
-JOIN Post ON authorId = User.id
+JOIN Post ON Post.authorId = User.id 
 GROUP BY name, Post.content;
 ```
 
@@ -637,16 +1248,17 @@ GROUP BY name, Post.content;
 Will add the keyword `DISTINCT` after the select.
 
 #### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=distinct
 prisma.$from("User")
-       .selectDistinct();
+      .selectDistinct()
+      .select("User.name");
 ```
 
 #### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT DISTINCT
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=distinct-sql
+SELECT DISTINCT name 
 FROM User;
 ```
 
@@ -657,71 +1269,100 @@ This method will explicitly list all the tables from the `$from` and `.join`. So
 
 
 #### Example - Single Table
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=all-single
 prisma.$from("User")
-       .selectAll();
+      .selectAll();
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT id, email, name
-FROM User 
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=all-single-sql
+SELECT id, email, name, age 
+FROM User;
 ```
 
 #### Example - Join table
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=all-join
 prisma.$from("User")
-       .join("Post", "authorId", "User.id") 
-       .selectAll();
+      .join("Post", "authorId", "User.id")
+      .selectAll();
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT User.id, User. email, User.name, Post.id, Post.title, Post.content, Post.published, Post.author, Post.authorId, Post.LastModifiedBy, Post.lastModifiedById
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=all-join-sql
+SELECT User.id AS `User.id`, User.email AS `User.email`, User.name AS `User.name`, User.age AS `User.age`, Post.id AS `Post.id`, Post.title AS `Post.title`, Post.content AS `Post.content`, Post.published AS `Post.published`, Post.createdAt AS `Post.createdAt`, Post.authorId AS `Post.authorId`, Post.lastModifiedById AS `Post.lastModifiedById`, Post.metadata AS `Post.metadata` 
 FROM User 
-JOIN Post ON authorId = User.id
+JOIN Post ON Post.authorId = User.id;
+```
+
+#### `.selectAllOmit`
+
+Like `.selectAll`, but excludes specific columns. Accepts `Table.column` or bare `column` references.
+
+#### Example - Single Table
+```typescript file=../usage-sqlite-v7/tests/readme/select-all-omit.ts region=single-omit
+prisma.$from("User")
+      .selectAllOmit(["User.email"]);
+```
+
+##### SQL
+```sql file=../usage-sqlite-v7/tests/readme/select-all-omit.ts region=single-omit-sql
+SELECT `id`, `name`, `age` 
+FROM `User`;
 ```
 
-[//]: # (#### `.selectAllOmit`)
+#### Example - Multiple Columns
+```typescript file=../usage-sqlite-v7/tests/readme/select-all-omit.ts region=multi-omit
+prisma.$from("User")
+      .selectAllOmit(["User.email", "User.age"]);
+```
+
+#### Example - With Join
+```typescript file=../usage-sqlite-v7/tests/readme/select-all-omit.ts region=join-omit
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .selectAllOmit(["User.email", "Post.content"]);
+```
+
+> **Note:** `*` and `Table.*` are not valid arguments — use `Table.column` or bare `column` references.
 
 #### `.select`
 
 You can supply either; `*`, `Table.*` OR `table.field` and then chain them together.
 
 #### Example - `*`
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-star.ts region=example
 prisma.$from("User")
-       .select("*");
+      .select("*");
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT *
+```sql file=../usage-sqlite-v7/tests/readme/select-star.ts region=example-sql
+SELECT * 
 FROM User;
 ```
 
 #### Example - `Table.*` (Single Table)
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=table-star-single
 prisma.$from("User")
-       .select("User.*");
+      .select("User.*");
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT User.id, User.email, User.name
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=table-star-single-sql
+SELECT id, email, name, age 
 FROM User;
 ```
 
 #### Example - `Table.*` (With Join)
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=table-star-join
 prisma.$from("User")
       .join("Post", "authorId", "User.id")
       .select("User.*")
@@ -731,38 +1372,32 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT User.id AS `User.id`,
-       User.email AS `User.email`,
-       User.name AS `User.name`,
-       Post.id AS `Post.id`,
-       Post.title AS `Post.title`,
-       Post.content AS `Post.content`,
-       Post.published AS `Post.published`
-FROM User
-JOIN Post ON authorId = User.id;
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=table-star-join-sql
+SELECT User.id AS `User.id`, User.email AS `User.email`, User.name AS `User.name`, User.age AS `User.age`, Post.id AS `Post.id`, Post.title AS `Post.title`, Post.content AS `Post.content`, Post.published AS `Post.published`, Post.createdAt AS `Post.createdAt`, Post.authorId AS `Post.authorId`, Post.lastModifiedById AS `Post.lastModifiedById`, Post.metadata AS `Post.metadata` 
+FROM User 
+JOIN Post ON Post.authorId = User.id;
 ```
 
-[!NOTE]
+> [!NOTE]
 > When using `Table.*` with joins, all columns are automatically aliased with the table name prefix to avoid column name conflicts.
 
 #### Example - Chained
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-chained.ts region=example
 prisma.$from("User")
-       .select("name")
-       .select("email");
+      .select("name")
+      .select("email");
 ```
 
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT name, email
+```sql file=../usage-sqlite-v7/tests/readme/select-chained.ts region=example-sql
+SELECT name, email 
 FROM User;
 ```
 
 #### Example - Join + Chained
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=join-chained
 prisma.$from("User")
       .join("Post", "authorId", "User.id")
       .select("name")
@@ -772,24 +1407,25 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT name, Post.title
-FROM User
-JOIN Post ON authorId = User.id;
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=join-chained-sql
+SELECT name, title 
+FROM User 
+JOIN Post ON Post.authorId = User.id;
 ```
 
 #### Example - Column Aliases
-```typescript
-// Basic alias
+```typescript file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=basic
 prisma.$from("User")
       .select("User.name", "username");
+```
 
-// Multiple aliases
+```typescript file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=multiple
 prisma.$from("User")
       .select("User.id", "userId")
       .select("User.email", "emailAddress");
+```
 
-// Mixing aliased and non-aliased columns
+```typescript file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=mixed
 prisma.$from("User")
       .select("User.id")
       .select("User.name", "username")
@@ -799,19 +1435,23 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
--- Basic alias
-SELECT User.name AS `username` FROM User;
+```sql file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=basic-sql
+SELECT User.name AS `username` 
+FROM User;
+```
 
--- Multiple aliases
-SELECT User.id AS `userId`, User.email AS `emailAddress` FROM User;
+```sql file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=multiple-sql
+SELECT User.id AS `userId`, User.email AS `emailAddress` 
+FROM User;
+```
 
--- Mixed
-SELECT User.id, User.name AS `username`, User.email FROM User;
+```sql file=../usage-sqlite-v7/tests/readme/select-column-alias.ts region=mixed-sql
+SELECT id, User.name AS `username`, email 
+FROM User;
 ```
 
 #### Example - Aliases with Joins
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=aliases-joins
 prisma.$from("User")
       .join("Post", "authorId", "User.id")
       .select("User.name", "authorName")
@@ -821,77 +1461,115 @@ prisma.$from("User")
 ##### SQL
 The resulting SQL will look like:
 
-```sql
-SELECT User.name AS `authorName`, Post.title AS `postTitle`
-FROM User
-JOIN Post ON authorId = User.id;
+```sql file=../usage-sqlite-v7/tests/readme/select-advanced.ts region=aliases-joins-sql
+SELECT User.name AS `authorName`, Post.title AS `postTitle` 
+FROM User 
+JOIN Post ON Post.authorId = User.id;
 ```
 
-[!NOTE]
+> [!NOTE]
 > When using column aliases, you can reference the alias in `ORDER BY` clauses. The returned type will use the alias names instead of the original column names.
 
 ### Having
 
-`.having` uses the same syntax as [`.where`](#where). Please see the previous section for details.
+`.having` accepts two overloads — a criteria object (same syntax as [`.where`](#where)) or a fn callback for SQL expressions and aggregate functions.
 
-#### Example
+#### Criteria object
 
-```typescript
+```typescript file=../../shared-tests/readme/having.ts region=with-groupby
 prisma.$from("User")
-       .join("Post", "authorId", "User.id")
-       .groupBy(["name", "Post.content"])
-       .having({
-           "User.name": {
-               "op": "LIKE",
-               "value": "bob%"
-           }
-       });
+      .join("Post", "authorId", "User.id")
+      .groupBy(["name", "Post.content"])
+      .having({
+        "User.name": {
+          "op": "LIKE",
+          "value": "bob%"
+        }
+      })
+      .select("email");
+```
+
+```sql file=../../shared-tests/readme/having.ts region=with-groupby-sql
+SELECT email 
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+GROUP BY name, Post.content HAVING User.name LIKE 'bob%';
 ```
 
-```typescript
+#### fn overload — aggregate functions
+
+Pass a callback returning `Array<[SQLExpr<T>, condition]>` pairs. The callback receives the full select-fn context, including all aggregate and string functions.
+
+##### `countAll()` with comparison op
+
+```typescript file=../../shared-tests/readme/having.ts region=agg-fn-tuple-countall
 prisma.$from("User")
-       .join("Post", "authorId", "User.id")
-       .having({
-           "User.name": {
-               "op": "LIKE",
-               "value": "stuart%"
-           }
-       });
+      .join("Post", "authorId", "User.id")
+      .groupBy(["User.name"])
+      .having(({ countAll }) => [[countAll(), { op: '>', value: 1 }]])
+      .select("User.name")
 ```
 
+```sql file=../../shared-tests/readme/having.ts region=agg-fn-tuple-countall-sql
+SELECT name 
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+GROUP BY User.name HAVING COUNT(*) > 1;
+```
 
-##### SQL
+##### `count(col)` with bigint value
 
-```SQL
-FROM User
-JOIN Post ON authorId = User.id
-GROUP BY name, Post.content
-HAVING (User.name LIKE 'bob%');
+```typescript file=../../shared-tests/readme/having.ts region=agg-fn-tuple-count
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .groupBy(["User.name"])
+      .having(({ count }) => [[count('User.id'), { op: '>=', value: 2n }]])
+      .select("User.name")
 ```
 
-```SQL
-FROM User
-JOIN Post ON authorId = User.id
-HAVING (User.name LIKE 'stuart%');
+```sql file=../../shared-tests/readme/having.ts region=agg-fn-tuple-count-sql
+SELECT name 
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+GROUP BY User.name HAVING COUNT(User.id) >= 2;
+```
+
+##### String expr — `upper(col)` LIKE
+
+```typescript file=../../shared-tests/readme/having.ts region=agg-fn-string-upper
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .groupBy(["User.name"])
+      .having(({ upper }) => [[upper('User.name'), { op: 'LIKE', value: 'John%' }]])
+      .select("User.name")
+```
+
+```sql file=../../shared-tests/readme/having.ts region=agg-fn-string-upper-sql
+SELECT name 
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+GROUP BY User.name HAVING UPPER(User.name) LIKE 'John%';
 ```
 
+Multiple pairs in one `.having()` call are AND-ed together. `.having()` can also be chained — each call appends an AND condition.
+
 ### Order By
 
 `.orderBy`, takes an array of column names, with the optional suffix of `ASC` or `DESC`.
 
 #### Example
 
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/orderby.ts region=basic
 prisma.$from("User")
       .join("Post", "authorId", "User.id")
-      .orderBy(["name", "Post.content DESC"]); 
+      .orderBy(["name", "Post.content DESC"]);
 ```
 
 ##### SQL
 
-```sql
-FROM User
-JOIN Post ON authorId = User.id
+```sql file=../usage-sqlite-v7/tests/readme/orderby.ts region=basic-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id 
 ORDER BY name, Post.content DESC;
 ```
 
@@ -901,7 +1579,7 @@ ORDER BY name, Post.content DESC;
 
 #### Example
 
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/pagination.ts region=limit
 prisma.$from("User")
       .join("Post", "authorId", "User.id")
       .limit(1);
@@ -909,9 +1587,9 @@ prisma.$from("User")
 
 ##### SQL
 
-```SQL
-FROM User
-JOIN Post ON authorId = User.id
+```sql file=../usage-sqlite-v7/tests/readme/pagination.ts region=limit-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id 
 LIMIT 1;
 ```
 
@@ -920,71 +1598,374 @@ LIMIT 1;
 `.offSet`, the number of rows to skip. Requires `.limit` to have been used first.
 
 #### Example
-```typescript
+```typescript file=../usage-sqlite-v7/tests/readme/pagination.ts region=offset
 prisma.$from("User")
-        .join("Post", "authorId", "User.id")
-        .limit(1)
-        .offset(1);
+      .join("Post", "authorId", "User.id")
+      .limit(1)
+      .offset(1);
 ```
 
 ##### SQL
 
-```SQL
-FROM User
-JOIN Post ON authorId = User.id
-LIMIT 1
-OFFSET 1
+```sql file=../usage-sqlite-v7/tests/readme/pagination.ts region=offset-sql
+FROM User 
+JOIN Post ON Post.authorId = User.id 
+LIMIT 1 
+OFFSET 1;
 ```
 
-## Future updates
+## Select Functions
 
-- Support specifying `JOIN` type [issue#2](https://github.com/adrianbrowning/prisma-ts-select/issues/2)
-- Support Select Functions
-  - [Aggregation #4](https://github.com/adrianbrowning/prisma-ts-select/issues/4)
-  - [String #5](https://github.com/adrianbrowning/prisma-ts-select/issues/5)
-  - [Date & Time #6](https://github.com/adrianbrowning/prisma-ts-select/issues/6)
-  - [Math #7](https://github.com/adrianbrowning/prisma-ts-select/issues/7)
-  - [Control Flow #8](https://github.com/adrianbrowning/prisma-ts-select/issues/8)
-  - [JSON #9](https://github.com/adrianbrowning/prisma-ts-select/issues/9)
-- [Support a `Many-To-Many` join #19](https://github.com/adrianbrowning/prisma-ts-select/issues/19)
-- [Select column alias #27](https://github.com/adrianbrowning/prisma-ts-select/issues/27)
-- [Table name alias #28](https://github.com/adrianbrowning/prisma-ts-select/issues/28)
-- [whereRaw supporting Prisma.sql](https://github.com/adrianbrowning/prisma-ts-select/issues/29)
+Pass a callback to `.select()` to use SQL expressions and aggregate functions. The callback receives a context object with all available functions for the active dialect.
 
-## Changelog / Versioning
-Changelog is available [here](https://github.com/adrianbrowning/prisma-ts-select/releases). We use [semantic versioning](https://semver.org/) for versioning.
+### Shared (all dialects)
 
-## License
-This project is licensed under the MIT License. See the LICENSE file for details.
+#### `lit(value)` — SQL literal
 
-Things of note!!!!
+Produces a typed SQL literal from a JS value.
 
-- remove typeof from 
-  - `type _db = DeepWriteable<typeof DB>;`
-  - `}[keyof typeof DB];`
-- Merge Items missing //@ts-expect-error - might not be needed
-- groupBy -> having, 
-  - missing @deprecated
-  - ts-exptect-error  - might not be needed
-- GetColsFromTableType missing ts-expect-error - might not be needed
-- DB needs to be in the same file.
+##### Example
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=lit-string
+prisma.$from("User")
+      .select(({ lit }) => lit("hello"), "greeting");
+```
 
+#### `countAll()` — COUNT(*)
 
+The most common aggregate. Always produces `COUNT(*)`.
 
-# prisma-ts-select
+##### Example
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=count-all
+prisma.$from("User")
+      .select(({ countAll }) => countAll(), "total");
+```
 
-## Install
+##### SQL
+```sql file=../usage-sqlite-v7/tests/readme/select-fns.ts region=count-all-sql
+SELECT COUNT(*) AS `total` 
+FROM User;
+```
 
-```shell
-npm i prisma-ts-select
-pnpm add prisma-ts-select
+#### `count(col)` — COUNT(col)
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=count-col
+prisma.$from("User")
+      .select(({ count }) => count("User.id"), "cnt");
 ```
 
-## Setup
+#### `countDistinct(col)` — COUNT(DISTINCT col)
 
-### Extract
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=count-distinct
+prisma.$from("User")
+      .select(({ countDistinct }) => countDistinct("User.id"), "cnt");
+```
 
+#### `sum(col)` / `avg(col)` / `min(col)` / `max(col)`
 
-## Usage
+Standard numeric aggregates. **Return types vary by dialect** — `sum` and `avg` return `Decimal` on MySQL (matching Prisma's numeric precision model), `number` on SQLite and PostgreSQL. `min`/`max` always return `T | null` (NULL for empty sets) where `T` is the column's TypeScript type.
+
+| Function | SQLite | MySQL | PostgreSQL |
+|---|---|---|---|
+| `sum(col)` | `number` | `Decimal` | `number` |
+| `avg(col)` | `number` | `Decimal` | `number` |
+| `min(col)` | `T \| null` | `T \| null` | `T \| null` |
+| `max(col)` | `T \| null` | `T \| null` | `T \| null` |
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=sum
+prisma.$from("User")
+      .select(({ sum }) => sum("User.age"), "total");
+```
+
+#### String Functions (all dialects)
+
+| Function | SQL | Returns |
+|---|---|---|
+| `upper(col)` | `UPPER(col)` | `string` |
+| `lower(col)` | `LOWER(col)` | `string` |
+| `length(col)` | `LENGTH(col)` | `number` |
+| `trim(col)` | `TRIM(col)` | `string` |
+| `ltrim(col)` | `LTRIM(col)` | `string` |
+| `rtrim(col)` | `RTRIM(col)` | `string` |
+| `replace(col, from, to)` | `REPLACE(col, 'from', 'to')` | `string` |
+
+> **Note:** MySQL `LENGTH()` returns byte-length (not char-length). For character-length on multi-byte strings use a dialect-specific fn.
+
+#### DateTime Functions (all dialects)
+
+All dialects provide these functions. Return types differ for `year`/`month`/`day`/`hour`/`minute`/`second` — see note below.
+
+| Function | SQL (MySQL / PG / SQLite) | Returns |
+|---|---|---|
+| `now()` | `NOW()` / `NOW()` / `datetime('now')` | `Date` |
+| `curDate()` | `CURDATE()` / `CURRENT_DATE` / `date('now')` | `Date` |
+| `year(col)` | `YEAR(col)` / `EXTRACT(YEAR FROM col)::integer` / `strftime('%Y', col)` | `number` (SQLite: `string`) |
+| `month(col)` | `MONTH(col)` / `EXTRACT(MONTH FROM col)::integer` / `strftime('%m', col)` | `number` (SQLite: `string`) |
+| `day(col)` | `DAY(col)` / `EXTRACT(DAY FROM col)::integer` / `strftime('%d', col)` | `number` (SQLite: `string`) |
+| `hour(col)` | `HOUR(col)` / `EXTRACT(HOUR FROM col)::integer` / `strftime('%H', col)` | `number` (SQLite: `string`) |
+| `minute(col)` | `MINUTE(col)` / `EXTRACT(MINUTE FROM col)::integer` / `strftime('%M', col)` | `number` (SQLite: `string`) |
+| `second(col)` | `SECOND(col)` / `EXTRACT(SECOND FROM col)::integer` / `strftime('%S', col)` | `number` (SQLite: `string`) |
+
+> **Note:** `year`, `month`, `day`, `hour`, `minute`, and `second` return `string` on SQLite because `strftime()` always returns text (e.g. `'2024'`, `'03'`). MySQL and PostgreSQL return `number`.
+
+DateTime column args also accept `SQLExpr<Date>`, enabling composition:
+
+```typescript
+prisma.$from("Post").select(({ year, now }) => year(now()), "y");
+```
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=upper
+prisma.$from("User")
+      .select(({ upper }) => upper("User.name"), "uname");
+```
+
+String fns accept a `SQLExpr<string>` as input, enabling composition:
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=lower
+prisma.$from("User")
+      .select(({ lower }) => lower("User.name"), "lname");
+```
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=replace
+prisma.$from("User")
+      .select(({ replace }) => replace("User.email", "@example.com", ""), "handle");
+```
+
+#### Math Functions (all dialects)
+
+| Function | SQL | Returns |
+|---|---|---|
+| `abs(col)` | `ABS(col)` | `number` |
+| `ceil(col)` | `CEIL(col)` | `number` |
+| `floor(col)` | `FLOOR(col)` | `number` |
+| `round(col, decimals?)` | `ROUND(col)` / `ROUND(col, n)` | `number` |
+| `power(base, exp)` | `POWER(base, exp)` | `number` |
+| `sqrt(col)` | `SQRT(col)` | `number` |
+| `mod(col, divisor)` | `MOD(col, divisor)` | `number` |
+| `sign(col)` | `SIGN(col)` | `number` |
+| `exp(col)` | `EXP(col)` | `number` |
+
+Math fns accept `SQLExpr<number>` or a column reference, enabling composition:
+
+```typescript
+// Absolute value of a literal
+prisma.$from("User")
+      .select(({ abs, lit }) => abs(lit(-5)), "absVal");
+
+// Round to 2 decimal places
+prisma.$from("User")
+      .select(({ round, lit }) => round(lit(4.567), 2), "val");
+
+// Compose: sqrt(power(x, 2))
+prisma.$from("User")
+      .select(({ sqrt, power }) => sqrt(power("User.age", 2)), "val");
+```
+
+#### Control Flow Functions (all dialects)
+
+| Function | SQL | Returns |
+|---|---|---|
+| `cond(criteria)` | *(WhereCriteria → SQL condition string)* | `SQLExpr<boolean>` |
+| `coalesce(...args)` | `COALESCE(a, b, ...)` | `SQLExpr<T>` |
+| `nullif(expr1, expr2)` | `NULLIF(a, b)` | `SQLExpr<T \| null>` |
+| `caseWhen(cases, elseVal?)` | `CASE WHEN ... THEN ... END` | `SQLExpr<T \| null>` |
+
+`cond()` converts a `WhereCriteria` object into a `SQLExpr<unknown>` — useful when you need a condition expression outside of a dedicated function. Note: `$if()`/`iif()` and `caseWhen()` all accept `WhereCriteria` directly, so `cond()` is rarely needed.
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns-control-flow.ts region=coalesce
+prisma.$from("User")
+      .select(({ coalesce, lit }) => coalesce("User.email", lit("unknown")), "contact")
+```
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns-control-flow.ts region=nullif
+prisma.$from("User")
+      .select(({ nullif, lit }) => nullif(lit(0), lit(0)), "val")
+```
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns-control-flow.ts region=case-when
+prisma.$from("User")
+      .select(({ caseWhen, lit }) => caseWhen([
+        { when: { age: { op: ">=", value: 18 } }, then: lit("adult") },
+      ], lit("minor")), "status")
+```
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns-control-flow.ts region=cond
+prisma.$from("User")
+      .select(({ cond }) => cond({ age: { op: ">", value: 0 } }), "flag")
+```
+
+#### Combining with `.groupBy()`
+
+```typescript file=../usage-sqlite-v7/tests/readme/select-fns.ts region=count-groupby
+prisma.$from("User")
+      .join("Post", "authorId", "User.id")
+      .groupBy(["User.name"])
+      .select("User.name")
+      .select(({ countAll }) => countAll(), "postCount");
+```
+
+##### SQL
+```sql
+SELECT User.name, COUNT(*) AS `postCount`
+FROM User
+JOIN Post ON Post.authorId = User.id
+GROUP BY User.name;
+```
+
+---
+
+### MySQL-specific
+
+| Function | SQL | Returns |
+|---|---|---|
+| `distinct(col)` | `DISTINCT col` | `ColType` (use inside `avg`, `sum`, `count`, `groupConcat`) |
+| `groupConcat(col, sep?)` | `GROUP_CONCAT(col SEPARATOR sep)` | `string` |
+| `bitAnd(col)` | `BIT_AND(col)` | `number` |
+| `bitOr(col)` | `BIT_OR(col)` | `number` |
+| `bitXor(col)` | `BIT_XOR(col)` | `number` |
+| `stddev(col)` | `STDDEV(col)` | `number` |
+| `stddevSamp(col)` | `STDDEV_SAMP(col)` | `number` |
+| `variance(col)` | `VARIANCE(col)` | `number` |
+| `varSamp(col)` | `VAR_SAMP(col)` | `number` |
+| `jsonArrayAgg(col)` | `JSON_ARRAYAGG(col)` | `JSONValue` |
+| `jsonObjectAgg(key, val)` | `JSON_OBJECTAGG(key, val)` | `JSONValue` |
+| `concat(...cols)` | `CONCAT(a, b, ...)` | `string` |
+| `substring(col, start, len?)` | `SUBSTRING(col, start, len)` | `string` |
+| `left(col, n)` | `LEFT(col, n)` | `string` |
+| `right(col, n)` | `RIGHT(col, n)` | `string` |
+| `repeat(col, n)` | `REPEAT(col, n)` | `string` |
+| `reverse(col)` | `REVERSE(col)` | `string` |
+| `lpad(col, len, pad)` | `LPAD(col, len, 'pad')` | `string` |
+| `rpad(col, len, pad)` | `RPAD(col, len, 'pad')` | `string` |
+| `locate(substr, col)` | `LOCATE('substr', col)` | `number` |
+| `space(n)` | `SPACE(n)` | `string` |
+| `$if(cond, trueVal, falseVal)` | `IF(cond, a, b)` | `T` |
+| `ifNull(col, fallback)` | `IFNULL(col, fallback)` | `NonNullable<T>` |
+| `greatest(...args)` | `GREATEST(a, b, ...)` | `T \| null` |
+| `least(...args)` | `LEAST(a, b, ...)` | `T \| null` |
+| `dateAdd(col, n, unit)` | `DATE_ADD(col, INTERVAL n unit)` | `Date` |
+| `dateSub(col, n, unit)` | `DATE_SUB(col, INTERVAL n unit)` | `Date` |
+| `dateFormat(col, fmt)` | `DATE_FORMAT(col, 'fmt')` | `string` |
+| `dateDiff(d1, d2)` | `DATEDIFF(d1, d2)` | `number` |
+| `quarter(col)` | `QUARTER(col)` | `number` |
+| `weekOfYear(col)` | `WEEKOFYEAR(col)` | `number` |
+| `dayName(col)` | `DAYNAME(col)` | `string` |
+| `lastDay(col)` | `LAST_DAY(col)` | `Date` |
+| `pi()` | `PI()` | `number` |
+| `ln(x)` | `LN(x)` | `number` |
+| `log(x)` | `LOG(x)` | `number` |
+| `log2(x)` | `LOG2(x)` | `number` |
+| `log10(x)` | `LOG10(x)` | `number` |
+| `truncate(x, n)` | `TRUNCATE(x, n)` | `number` |
+| `rand(seed?)` | `RAND()` / `RAND(seed)` | `number` |
+
+> **Note:** MySQL `LOG(x)` is natural log (ln). `rand()` returns a float in [0, 1).
+
+`unit` is one of: `'MICROSECOND' | 'SECOND' | 'MINUTE' | 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'QUARTER' | 'YEAR'`
+
+> **Note:** `jsonArrayAgg` and `jsonObjectAgg` require MySQL 5.7.22+.
+
+---
+
+### PostgreSQL-specific
+
+| Function | SQL | Returns |
+|---|---|---|
+| `greatest(...args)` | `GREATEST(a, b, ...)` | `T` |
+| `least(...args)` | `LEAST(a, b, ...)` | `T` |
+| `distinct(col)` | `DISTINCT col` | `ColType` (use inside `avg`, `sum`, `count`, `stringAgg`, `arrayAgg`) |
+| `stringAgg(col, sep)` | `STRING_AGG(col, sep)` | `string` |
+| `arrayAgg(col)` | `ARRAY_AGG(col)` | `unknown[]` |
+| `stddevPop(col)` | `STDDEV_POP(col)` | `number` |
+| `stddevSamp(col)` | `STDDEV_SAMP(col)` | `number` |
+| `varPop(col)` | `VAR_POP(col)` | `number` |
+| `varSamp(col)` | `VAR_SAMP(col)` | `number` |
+| `boolAnd(col)` | `BOOL_AND(col)` | `boolean` |
+| `boolOr(col)` | `BOOL_OR(col)` | `boolean` |
+| `jsonAgg(col)` | `JSON_AGG(col)` | `JSONValue[]` |
+| `bitAnd(col)` | `BIT_AND(col)` | `number` |
+| `bitOr(col)` | `BIT_OR(col)` | `number` |
+| `jsonObjectAgg(key, val)` | `JSON_OBJECT_AGG(key, val)` | `JSONValue` |
+| `concat(...cols)` | `CONCAT(a, b, ...)` | `string` |
+| `substring(col, start, len?)` | `SUBSTRING(col, start, len)` | `string` |
+| `left(col, n)` | `LEFT(col, n)` | `string` |
+| `right(col, n)` | `RIGHT(col, n)` | `string` |
+| `repeat(col, n)` | `REPEAT(col, n)` | `string` |
+| `reverse(col)` | `REVERSE(col)` | `string` |
+| `lpad(col, len, pad)` | `LPAD(col, len, 'pad')` | `string` |
+| `rpad(col, len, pad)` | `RPAD(col, len, 'pad')` | `string` |
+| `initcap(col)` | `INITCAP(col)` | `string` |
+| `strpos(col, substr)` | `STRPOS(col, 'substr')` | `number` |
+| `splitPart(col, delimiter, field)` | `SPLIT_PART(col, 'delimiter', field)` | `string` |
+| `btrim(col, chars?)` | `BTRIM(col)` / `BTRIM(col, 'chars')` | `string` |
+| `md5(col)` | `MD5(col)` | `string` |
+| `extract(field, col)` | `EXTRACT(field FROM col)` | `number` |
+| `dateTrunc(unit, col)` | `DATE_TRUNC('unit', col)` | `Date` |
+| `age(ts1, ts2?)` | `AGE(ts1)` / `AGE(ts1, ts2)` | `string` (PG `interval` mapped to string) |
+| `toDate(text, fmt)` | `TO_DATE(text, 'fmt')` | `Date` |
+| `pi()` | `PI()` | `number` |
+| `ln(x)` | `LN(x)` | `number` |
+| `log(x)` | `LOG(x)` | `number` |
+| `logBase(base, x)` | `LOG(base, x)` | `number` |
+| `trunc(x, n?)` | `TRUNC(x)` / `TRUNC(x, n)` | `number` |
+| `div(x, y)` | `DIV(x, y)` | `number` |
+| `random()` | `RANDOM()` | `number` |
+
+> **Note:** PG `LOG(x)` is log base 10 (unlike MySQL where it is natural log). `random()` returns a float in [0, 1).
+
+`field` for `extract` is one of: `'YEAR' | 'MONTH' | 'DAY' | 'HOUR' | 'MINUTE' | 'SECOND' | 'DOW' | 'DOY' | 'EPOCH' | 'WEEK' | 'QUARTER'`
+
+`unit` for `dateTrunc` is one of: `'microseconds' | 'milliseconds' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' | 'decade' | 'century' | 'millennium'`
+
+---
+
+### SQLite-specific
+
+| Function | SQL | Returns |
+|---|---|---|
+| `iif(cond, trueVal, falseVal)` | `IIF(cond, a, b)` | `T` |
+| `ifNull(col, fallback)` | `IFNULL(col, fallback)` | `NonNullable<T>` |
+| `distinct(col)` | `DISTINCT col` | `ColType` (use inside `avg`, `sum`, `count`, `groupConcat`; sep with ≥ 3.44) |
+| `groupConcat(col, sep?)` | `GROUP_CONCAT(col, sep)` | `string` |
+| `total(col)` | `TOTAL(col)` | `number` |
+| `concat(...cols)` | `a \|\| b \|\| ...` | `string` |
+| `substr(col, start, len?)` | `SUBSTR(col, start, len)` | `string` |
+| `instr(col, substr)` | `INSTR(col, 'substr')` | `number` |
+| `char(...codes)` | `CHAR(n1, n2, ...)` | `string` |
+| `hex(col)` | `HEX(col)` | `string` |
+| `unicode(col)` | `UNICODE(col)` | `number` |
+| `strftime(fmt, col)` | `strftime('fmt', col)` | `string` |
+| `julianday(col)` | `julianday(col)` | `number` |
+| `date(col)` | `date(col)` | `string` |
+| `datetime(col)` | `datetime(col)` | `string` |
+| `random()` | `RANDOM()` | `number` |
+| `log(x)` | `LOG(x)` | `number` |
+| `log2(x)` | `LOG2(x)` | `number` |
+| `log10(x)` | `LOG10(x)` | `number` |
+
+> **Note:** SQLite `random()` returns a random integer (not float). `log`, `log2`, `log10` require SQLite 3.35+. `total()` behaves like `SUM()` but returns `0.0` instead of `NULL` for empty sets. SQLite uses the `||` operator for string concatenation.
+
+> **Note:** SQLite stores `DateTime` differently between Prisma v6 (integer milliseconds) and v7 (ISO 8601 text). All SQLite datetime fns automatically normalise both formats via a `CASE WHEN typeof(...) = 'integer' THEN datetime(.../1000, 'unixepoch') ELSE ... END` wrapper, so they work correctly on both versions.
+
+---
+
+## Security
+
+All queries execute via Prisma's `$queryRawUnsafe`. The `esc()` helper escapes single quotes in string literals, but **never pass user-supplied values directly** to query builder methods — use Prisma's parameterized queries for user input.
+
+`whereRaw()` in particular inserts SQL verbatim. Only use it with trusted, static SQL strings.
+
+## Future updates
+
+- Support specifying `JOIN` type [issue#2](https://github.com/adrianbrowning/prisma-ts-select/issues/2)
+- Support additional Select Functions
+  - [JSON #9](https://github.com/adrianbrowning/prisma-ts-select/issues/9)
+  - [CAST #71](https://github.com/adrianbrowning/prisma-ts-select/issues/71)
+- [whereRaw supporting Prisma.sql](https://github.com/adrianbrowning/prisma-ts-select/issues/29)
+
+## Changelog / Versioning
+Changelog is available [here](https://github.com/adrianbrowning/prisma-ts-select/releases). We use [semantic versioning](https://semver.org/) for versioning.
+
+## License
+This project is licensed under the MIT License. See the LICENSE file for details.