typhex 0.1.0-alpha.0

package/docs/guide/cte-and-unions.md

@@ -0,0 +1,270 @@
+# CTEs and Unions
+
+Common table expressions let you name an inner query and reuse it from an outer query. Typhex exposes them through `.withCte()`, `.withRecursiveCte()`, `.from()`, and `.unionAll()`.
+
+## Basic CTE
+
+Register a query with `.withCte(name, query)`, then read from it with `.from(name)`:
+
+```ts
+const adults = User.query().where((u) => u.age >= 18);
+
+const workingAge = await User.query()
+  .withCte("adults", adults)
+  .from("adults")
+  .where((u) => u.age < 65)
+  .toArray();
+```
+
+```sql
+WITH "adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+)
+SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+FROM "adults" AS "t0"
+WHERE ("t0"."age" < ?)
+-- params: [18, 65]
+```
+
+## Referencing Earlier CTEs
+
+Later CTEs can read from earlier CTEs by using `.from("earlier_name")`:
+
+```ts
+const adults = User.query().where((u) => u.age >= 18);
+const ukAdults = User.query()
+  .from("adults")
+  .where((u) => u.country === "UK");
+
+const rows = await User.query()
+  .withCte("adults", adults)
+  .withCte("uk_adults", ukAdults)
+  .from("uk_adults")
+  .toArray();
+```
+
+```sql
+WITH "adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+), "uk_adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "adults" AS "t0"
+  WHERE ("t0"."country" = ?)
+)
+SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+FROM "uk_adults" AS "t0"
+WHERE 1=1
+-- params: [18, "UK"]
+```
+
+Use this when the later CTE is a filtered subset of an earlier one. The inner query reads directly from the earlier CTE name.
+
+## Correlating with `ctes.*` in WHERE
+
+Sometimes the later CTE should scan the **base entity table** and correlate to an earlier CTE in `WHERE`, instead of using `.from("earlier_name")`. Typhex exposes earlier registered CTEs through a `ctes` context.
+
+Typical shape:
+
+```ts
+const adults = User.query().where((u) => u.age >= 18);
+
+await User.query()
+  .withCte("adults", adults)
+  .withCte("uk_adults", (ctes) =>
+    User.query().where((u) => u.country === "UK" && u.id === ctes.adults.id),
+  )
+  .from("uk_adults")
+  .toArray();
+```
+
+```sql
+WITH "adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+), "uk_adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0", "adults"
+  WHERE ("t0"."country" = ?) AND ("t0"."id" = "adults"."id")
+)
+SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+FROM "uk_adults" AS "t0"
+WHERE 1=1
+-- params: [18, "UK"]
+```
+
+The important difference from `.from("adults")`:
+
+| Approach                   | Inner `FROM`             | Typical use                                         |
+| -------------------------- | ------------------------ | --------------------------------------------------- |
+| `.from("adults")`          | `"adults"`               | Filter rows already materialized in the earlier CTE |
+| `ctes.adults.*` in `WHERE` | base table + earlier CTE | Match base-table rows against earlier CTE rows      |
+
+### Transformer: `ctes.*` in a single-arg `where`
+
+When the Typhex transformer is enabled, reference earlier CTE columns directly inside a one-argument `where()` lambda. The transformer captures `ctes` from the `.withCte()` callback:
+
+```ts
+.withCte("uk_adults", (ctes) =>
+  User.query().where((u) => u.country === "UK" && u.id === ctes.adults.id),
+)
+```
+
+This is the pattern used in `examples/cte/cte.ts` section 3b.
+
+### Runtime: two-arg `where((row, ctes) => ...)`
+
+Without the transformer, pass the `ctes` object explicitly as the second parameter to `where()`. This works when building a later CTE body and when correlating mutations on the outer builder:
+
+```ts
+// Later CTE body — runtime-friendly
+.withCte("uk_adults", () =>
+  User.query().where(
+    (u, ctes) => u.country === "UK" && u.id === ctes.adults.id,
+  ),
+)
+
+// Outer UPDATE/DELETE on the same builder
+await User.query()
+  .withCte("adults", adults)
+  .where((u, ctes) => u.age === 35 && u.id === ctes.adults.id)
+  .update({ name: "Robert" });
+```
+
+```sql
+WITH "adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+)
+UPDATE "users" AS "t0"
+SET "name" = ?
+FROM "adults"
+WHERE ("t0"."age" = ?) AND ("t0"."id" = "adults"."id")
+-- params: [18, "Robert", 35]
+```
+
+The two-arg form is the reliable way to correlate registered CTEs at runtime. The single-arg `ctes.adults.id` form inside a `.withCte()` callback requires the transformer.
+
+## `UNION ALL`
+
+Use `.unionAll()` to combine compatible SELECT branches, often inside a CTE:
+
+```ts
+const young = User.query().where((u) => u.age < 25);
+const senior = User.query().where((u) => u.age >= 65);
+
+const rows = await User.query()
+  .withCte("ends", young.unionAll(senior))
+  .from("ends")
+  .orderBy("name", "asc")
+  .toArray();
+```
+
+```sql
+WITH "ends" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" < ?)
+  UNION ALL
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+)
+SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+FROM "ends" AS "t0"
+WHERE 1=1
+ORDER BY "t0"."name" ASC
+-- params: [25, 65]
+```
+
+## Recursive CTEs
+
+Recursive CTEs combine an anchor query with a recursive branch. The recursive branch refers to the CTE name via `.from(name)`:
+
+```ts
+const anchor = Category.query().where((c) => c.parentId === null);
+const recursive = Category.query()
+  .from("tree")
+  .innerJoin(Category, (child, parent) => child.parentId === parent.id);
+
+const tree = await Category.query()
+  .withRecursiveCte("tree", anchor.unionAll(recursive))
+  .from("tree")
+  .toArray();
+```
+
+```sql
+WITH RECURSIVE "tree" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."parentId"
+  FROM "categories" AS "t0"
+  WHERE ("t0"."parentId" IS NULL)
+  UNION ALL
+  SELECT "t0"."id", "t0"."name", "t0"."parentId"
+  FROM "tree" AS "t0"
+  INNER JOIN "categories" AS "t1"
+    ON ("t1"."parentId" = "t0"."id")
+)
+SELECT "t0"."id", "t0"."name", "t0"."parentId"
+FROM "tree" AS "t0"
+WHERE 1=1
+```
+
+Entity-table joins such as `.innerJoin(Category, on)` are useful in recursive branches and self-joins.
+
+## CTEs with Mutations
+
+Registered CTEs can also constrain updates and deletes on the outer builder. Use the two-argument `where((row, ctes) => ...)` form to correlate the mutation target to a registered CTE:
+
+```ts
+const adults = User.query().where((u) => u.age >= 18);
+
+await User.query()
+  .withCte("adults", adults)
+  .where((u, ctes) => u.id === ctes.adults.id && u.age === 35)
+  .update({ name: "Robert" });
+```
+
+```sql
+WITH "adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE ("t0"."age" >= ?)
+)
+UPDATE "users" AS "t0"
+SET "name" = ?
+FROM "adults"
+WHERE ("t0"."age" = ?) AND ("t0"."id" = "adults"."id")
+-- params: [18, "Robert", 35]
+```
+
+For deletes, Typhex correlates through `EXISTS`:
+
+```ts
+const ukAdults = User.query().where((u) => u.country === "UK" && u.age >= 18);
+
+await User.query()
+  .withCte("uk_adults", ukAdults)
+  .where((u, ctes) => u.age >= 65 && u.id === ctes.uk_adults.id)
+  .delete();
+```
+
+```sql
+WITH "uk_adults" AS (
+  SELECT "t0"."id", "t0"."name", "t0"."age", "t0"."country"
+  FROM "users" AS "t0"
+  WHERE (("t0"."country" = ?) AND ("t0"."age" >= ?))
+)
+DELETE FROM "users" AS "t0"
+WHERE EXISTS (
+  SELECT 1 FROM "uk_adults"
+  WHERE ("t0"."age" >= ?) AND ("t0"."id" = "uk_adults"."id")
+)
+-- params: ["UK", 18, 65]
+```
+
+See the [API reference](/reference/api#withcte-name-query) for method signatures and run `npm run cte` from `examples/` for end-to-end output.

package/docs/guide/entities-relations.md

@@ -0,0 +1,208 @@
+# Entities & Relations
+
+## The `Entity()` Factory
+
+`Entity()` creates a base class for a database table. The second argument is the schema — a map from column name to SQL type string.
+
+```ts
+import { Entity, rel } from "typhex";
+
+const User = Entity("users", {
+  id: "integer primary key autoincrement",
+  name: "text not null",
+  email: "text",
+  age: "integer",
+  createdAt: "datetime not null",
+});
+```
+
+TypeScript infers the row shape from the schema, so `User` instances are typed — no separate interface declaration required.
+
+## Defining Relations
+
+Pass a third argument to `Entity()` to declare relations. Use the `rel` helper:
+
+```ts
+const Post = Entity(
+  "posts",
+  {
+    id: "integer primary key autoincrement",
+    title: "text not null",
+    authorId: "integer not null",
+    createdAt: "datetime not null",
+  },
+  {
+    author: rel.manyToOne(() => User, { foreignKey: "authorId" }), // [!code highlight]
+  },
+);
+```
+
+The target entity is passed as a thunk (`() => User`) to allow forward-references when entities are defined in separate files or have circular references.
+
+### Relation helpers
+
+| Helper                                                                 | Direction | What it means                                |
+| ---------------------------------------------------------------------- | --------- | -------------------------------------------- |
+| `rel.manyToOne(() => Target, { foreignKey })`                          | N:1       | This table holds the foreign key             |
+| `rel.oneToMany(() => Target, { foreignKey })`                          | 1:N       | The other table holds the foreign key        |
+| `rel.oneToOne(() => Target, { foreignKey })`                           | 1:1       | FK on this table; loads a single related row |
+| `rel.manyToMany(() => Target, { junction, foreignKey, referenceKey })` | M:N       | Via a junction table                         |
+
+## One-to-One Relations
+
+Use `rel.oneToOne()` when each row has at most one related row. The FK lives on this entity's table:
+
+```ts
+const UserProfile = Entity("user_profiles", {
+  id: "integer primary key autoincrement",
+  userId: "integer not null unique",
+  bio: "text",
+});
+
+const User = Entity(
+  "users",
+  { id: "integer primary key autoincrement", name: "text not null" },
+  { profile: rel.oneToOne(() => UserProfile, { foreignKey: "userId" }) },
+);
+
+// Load the profile alongside the user
+const users = await User.query()
+  .select((u) => ({ id: u.id, name: u.name, profile: u.profile }))
+  .toArray();
+```
+
+```sql
+-- 1. Main query
+SELECT id AS id, name AS name FROM users
+
+-- 2. Relation fetch (one round-trip, regardless of result count)
+SELECT id, userId, bio FROM user_profiles WHERE userId IN (?, ?, ...)
+```
+
+## Many-to-Many Relations
+
+A `manyToMany` relation works through a junction table that you manage directly in SQL (Typhex doesn't auto-migrate junction tables):
+
+```ts
+import { Entity, rel, type ManyToMany } from "typhex";
+import { Tag } from "./tag.js";
+
+export class Post extends Entity(
+  "posts",
+  { id: "integer primary key autoincrement", title: "text not null" },
+  {
+    tags: rel.manyToMany(() => Tag, {
+      junction: "post_tags", // junction table name
+      foreignKey: "postId", // column pointing to this entity
+      referenceKey: "tagId", // column pointing to the target
+    }),
+  },
+) {
+  declare tags: ManyToMany<Tag>; // needed when Post and Tag are in separate files
+}
+```
+
+Create the junction table manually (once):
+
+```ts
+await db.run("CREATE TABLE post_tags (postId INTEGER NOT NULL, tagId INTEGER NOT NULL)");
+```
+
+Then use it like any other relation in `select()`:
+
+```ts
+const posts = await Post.query()
+  .select((p) => ({
+    id: p.id,
+    title: p.title,
+    tags: p.tags
+      .query()
+      .select((t) => ({ name: t.name }))
+      .orderBy((t) => t.name, "asc"),
+  }))
+  .toArray();
+```
+
+```sql
+-- 1. Main query
+SELECT id AS id, title AS title FROM posts
+
+-- 2. Junction + target fetched together
+SELECT post_tags.postId, tags.name AS name
+FROM post_tags
+JOIN tags ON tags.id = post_tags.tagId
+WHERE post_tags.postId IN (?, ?, ...)
+ORDER BY tags.name ASC
+```
+
+## Composite Primary Keys
+
+When a table's primary key spans multiple columns, mark each column with `"primary key"` in the schema. Relations accept an array for composite foreign keys:
+
+```ts
+const Project = Entity(
+  "projects",
+  {
+    tenantId: "text primary key",
+    projectId: "text primary key",
+    name: "text not null",
+  },
+  {
+    tasks: rel.oneToMany(() => Task, { foreignKey: ["tenantId", "projectId"] }),
+  },
+);
+
+const Task = Entity(
+  "tasks",
+  {
+    id: "integer primary key autoincrement",
+    tenantId: "text not null",
+    projectId: "text not null",
+    title: "text not null",
+  },
+  { project: rel.manyToOne(() => Project, { foreignKey: ["tenantId", "projectId"] }) },
+);
+```
+
+`findById` accepts an object for composite keys:
+
+```ts
+const project = await Project.query().findById({ tenantId: "acme", projectId: "p1" });
+```
+
+```sql
+SELECT tenantId, projectId, name FROM projects
+WHERE tenantId = ? AND projectId = ?
+LIMIT 1
+-- params: ["acme", "p1"]
+```
+
+::: warning SQLite DDL
+SQLite doesn't allow two `PRIMARY KEY` column constraints in one `CREATE TABLE`. Use `db.run()` with a table-level `PRIMARY KEY (col1, col2)` clause instead of `db.migrate()` for composite-PK tables.
+:::
+
+## Custom Entity Classes
+
+Subclass the `Entity()` result to add computed properties and lifecycle hooks. The subclass inherits all ORM methods (`.query()`, `.where()`, `.insert()`, etc.) and instances are returned by query methods.
+
+```ts
+class UserEntity extends User {
+  // Computed property
+  get displayName() {
+    return this.name ?? this.email ?? "Anonymous";
+  }
+
+  // Lifecycle hook — called before every save()
+  beforeSave() {
+    if (!this.createdAt) this.createdAt = new Date();
+  }
+}
+
+// Query and use the computed property
+const user = await UserEntity.query()
+  .where((u) => u.age > 18)
+  .first();
+console.log(user?.displayName);
+```
+
+`beforeSave()` is the only lifecycle hook. Use it to set defaults or enforce invariants — it runs before both inserts and updates.

package/docs/guide/expressions.md

@@ -0,0 +1,98 @@
+# Expressions in Queries
+
+Typhex accepts a practical expression subset anywhere a query lambda expects a value: `where()`, `having()`, `select()`, aggregate arguments, and `orderBy()`.
+
+## Conditional and Arithmetic Expressions
+
+Use JavaScript ternaries for SQL `CASE` expressions, and arithmetic operators for derived values:
+
+```ts
+const lineItems = await Order.query()
+  .select((o) => ({
+    id: o.id,
+    revenue: o.price * o.qty,
+    bucket: o.qty < 5 ? "small" : "large",
+  }))
+  .orderBy((o) => (o.qty < 5 ? 1 : 0))
+  .toArray();
+```
+
+```sql
+SELECT id AS id,
+       (price * qty) AS revenue,
+       CASE WHEN qty < ? THEN ? ELSE ? END AS bucket
+FROM orders
+ORDER BY CASE WHEN qty < ? THEN ? ELSE ? END ASC
+```
+
+Supported arithmetic operators are `+`, `-`, `*`, `/`, and `%`. Bitwise operators `&`, `|`, `^`, `<<`, `>>`, and unary `~` are also supported; PostgreSQL emits `#` for XOR.
+
+## Null Checks
+
+Strict null comparisons compile to SQL null semantics:
+
+```ts
+const liveCount = await Order.query()
+  .where((o) => o.deletedAt === null)
+  .count();
+
+const deletedCount = await Order.query()
+  .where((o) => o.deletedAt !== null)
+  .count();
+```
+
+```sql
+WHERE deletedAt IS NULL
+WHERE deletedAt IS NOT NULL
+```
+
+## Computed Select Columns
+
+Projection fields can be expressions, not just direct columns:
+
+```ts
+const prices = await Order.query()
+  .select((o) => ({
+    id: o.id,
+    cents: o.price * 100,
+    activeLabel: o.active ? "active" : "inactive",
+  }))
+  .toArray();
+```
+
+If the lambda returns a single scalar expression, Typhex aliases it as `expr`:
+
+```ts
+const cents = await Order.query()
+  .select((o) => o.price * 100)
+  .toArray();
+```
+
+## Expressions Inside Aggregates
+
+Aggregate arguments can include ternaries and arithmetic, which is useful for conditional counts and revenue totals:
+
+```ts
+import { sum } from "typhex";
+
+const cutoff = 5;
+const buckets = await Order.query()
+  .select(
+    (o) => ({
+      category: o.category,
+      revenue: sum(o.price * o.qty),
+      smalls: sum(o.qty < cutoff ? 1 : 0),
+    }),
+    { cutoff },
+  )
+  .groupBy("category")
+  .toArray();
+```
+
+In runtime mode, pass closure variables used by `.select()` as the second argument. With the TypeScript transformer, those variables are captured automatically.
+
+## Runtime and Transformer Boundaries
+
+Ternaries, arithmetic, bitwise operators, null checks, computed projections, and expression `orderBy()` work in runtime mode and transformer mode.
+
+Scalar correlated subqueries in `.select()`, comparison `.where()` predicates, and `.orderBy()` are transformer-only. See [Subqueries](/guide/subqueries) for those shapes.