typhex 0.1.0-alpha.0

package/docs/guide/filtering-by-relations.md

@@ -0,0 +1,166 @@
+# Filtering by Relations
+
+When a `where()` predicate references a relation property, Typhex generates a SQL `JOIN` (for `manyToOne`) or an `EXISTS` subquery (for `oneToMany`) rather than loading data in application code.
+
+## Basic manyToOne WHERE
+
+Filter rows by a property of a related entity:
+
+```ts
+// contacts with a where on their company name
+const acmeContacts = await Contact.query()
+  .where((c) => c.company.name === "Acme Corp") // [!code highlight]
+  .select((c) => ({ id: c.id, name: c.name }))
+  .orderBy((c) => c.id, "asc")
+  .toArray();
+```
+
+```sql
+SELECT contacts.id AS id, contacts.name AS name
+FROM contacts
+LEFT JOIN companies ON companies.id = contacts.companyId
+WHERE companies.name = ?
+ORDER BY contacts.id ASC
+-- params: ["Acme Corp"]
+```
+
+::: tip Default JOIN type
+Typhex emits a `LEFT JOIN` by default. Use [join hints](/reference/api#innerjoin-keysorfn-leftjoin-rightjoin-fulljoin-crossjoin) (`.innerJoin()`, `.rightJoin()`, etc.) to override.
+:::
+
+## JOIN Reuse: WHERE + SELECT on the Same Relation
+
+When both `where()` and `select()` reference the same `manyToOne` relation, Typhex reuses the JOIN — no duplicate fetch:
+
+```ts
+const acmeContactsWithCompany = await Contact.query()
+  .where((c) => c.company.name === "Acme Corp")
+  .select((c) => ({
+    id: c.id,
+    name: c.name,
+    company: { id: c.company.id, name: c.company.name }, // [!code highlight]
+  }))
+  .orderBy((c) => c.id, "asc")
+  .toArray();
+```
+
+```sql
+SELECT contacts.id AS id, contacts.name AS name,
+       companies.id AS "company.id", companies.name AS "company.name"
+FROM contacts
+LEFT JOIN companies ON companies.id = contacts.companyId
+WHERE companies.name = ?
+ORDER BY contacts.id ASC
+-- params: ["Acme Corp"]
+```
+
+## Different Relations in WHERE and SELECT
+
+You can filter by one relation and load another — each is handled independently. The `where` relation generates a JOIN; the `select` relation loads via a separate `WHERE id IN (...)` fetch:
+
+```ts
+const acmeContactsWithCategory = await Contact.query()
+  .where((c) => c.company.name === "Acme Corp")
+  .select((c) => ({
+    id: c.id,
+    name: c.name,
+    category: { id: c.category.id, name: c.category.name },
+  }))
+  .toArray();
+```
+
+```sql
+-- 1. Main query — JOIN on companies (for WHERE), but select category FK
+SELECT contacts.id AS id, contacts.name AS name, contacts.categoryId AS categoryId
+FROM contacts
+LEFT JOIN companies ON companies.id = contacts.companyId
+WHERE companies.name = ?
+
+-- 2. Category fetch
+SELECT id, name FROM categories WHERE id IN (?, ?, ...)
+```
+
+## Spread All Columns + a Relation
+
+Use spread syntax to include all own columns alongside a relation:
+
+```ts
+const contactsWithCompany = await Contact.query()
+  .select((c) => ({ ...c, company: c.company })) // [!code highlight]
+  .orderBy((c) => c.id, "asc")
+  .toArray();
+```
+
+```sql
+SELECT id AS id, name AS name, companyId AS companyId, categoryId AS categoryId
+FROM contacts ORDER BY id ASC
+
+SELECT id, name FROM companies WHERE id IN (?, ?, ...)
+```
+
+## oneToMany EXISTS: `.some()`
+
+For `oneToMany` relations, use `.some()` inside `where()` to generate an `EXISTS` subquery:
+
+```ts
+// departments that have at least one employee named "Alice"
+const deptsWithAlice = await Department.query()
+  .where((d) => d.employees.some((e) => e.name === "Alice")) // [!code highlight]
+  .select((d) => ({ id: d.id, name: d.name }))
+  .toArray();
+```
+
+Typhex emits:
+
+```sql
+SELECT departments.id, departments.name
+FROM departments
+WHERE EXISTS (
+  SELECT 1 FROM employees
+  WHERE employees.departmentId = departments.id
+    AND employees.name = ?
+)
+```
+
+## oneToMany NOT EXISTS: `.every()`
+
+Use `.every()` when every related row must satisfy a predicate. Typhex compiles this to `NOT EXISTS` over rows that fail the predicate:
+
+```ts
+// departments where every employee is active
+const activeDepartments = await Department.query()
+  .where((d) => d.employees.every((e) => e.active === true)) // [!code highlight]
+  .select((d) => ({ id: d.id, name: d.name }))
+  .toArray();
+```
+
+Typhex emits:
+
+```sql
+SELECT departments.id, departments.name
+FROM departments
+WHERE NOT EXISTS (
+  SELECT 1 FROM employees
+  WHERE employees.departmentId = departments.id
+    AND NOT (employees.active = ?)
+)
+```
+
+## Count with Relation WHERE
+
+`.count()` works with any `where()` predicate, including those that reference relations:
+
+```ts
+const acmeCount = await Contact.query()
+  .where((c) => c.company.name === "Acme Corp")
+  .count();
+```
+
+```sql
+SELECT COUNT(*) AS c FROM (
+  SELECT ... FROM "contacts" AS "t0"
+  LEFT JOIN "companies" AS "t1" ON "t1"."id" = "t0"."companyId"
+  WHERE ("t1"."name" = ?)
+) AS "_count"
+-- params: ["Acme Corp"]
+```

package/docs/guide/getting-started.md

@@ -0,0 +1,277 @@
+# Getting Started
+
+## Installation
+
+```bash
+npm install typhex better-sqlite3
+npm install --save-dev ts-patch
+```
+
+For PostgreSQL: `npm install typhex pg`
+
+> Native addon? See the [SQLite driver](/drivers/sqlite#installation) page if `better-sqlite3` fails to build.
+
+Then enable the [TypeScript transformer](/guide/typescript-transformer) — it auto-captures closure variables and eliminates runtime parsing overhead. Without it, Typhex falls back to runtime parsing with Acorn (you pass closure variables manually).
+
+## Define a Schema
+
+Use `Entity()` to define a table. Column types are SQL type strings passed through to `CREATE TABLE`.
+
+```ts
+import { Db, Entity, createSqliteDriver } from "typhex";
+
+const User = Entity("users", {
+  id: "integer primary key autoincrement",
+  name: "text not null",
+  age: "integer not null",
+  country: "text not null",
+});
+```
+
+TypeScript infers the row type from the schema — no separate interface needed.
+
+## Connect and Migrate
+
+```ts
+const db = new Db(createSqliteDriver({ path: "./app.db" }));
+await db.migrate(); // creates tables that don't exist yet
+```
+
+Use `":memory:"` for tests and one-off scripts.
+
+## Insert Rows
+
+```ts
+await User.query().insert({ name: "Alice", age: 30, country: "US" });
+```
+
+```sql
+INSERT INTO users (name, age, country) VALUES (?, ?, ?)
+-- params: ["Alice", 30, "US"]
+```
+
+`insert()` returns the inserted row with the auto-generated `id`.
+
+## Query with Arrow Functions
+
+With the transformer active, write predicates as plain TypeScript — closure variables are captured automatically:
+
+```ts
+const adults = await User.query()
+  .where((u) => u.age > 18)
+  .toArray();
+```
+
+```sql
+SELECT id, name, age, country FROM users WHERE age > ?
+-- params: [18]
+```
+
+Closure variables work without a second argument:
+
+```ts
+const country = "US";
+const fromUS = await User.query()
+  .where((u) => u.country === country)
+  .toArray();
+```
+
+```sql
+SELECT id, name, age, country FROM users WHERE country = ?
+-- params: ["US"]
+```
+
+Multiple closure variables compose into `AND`:
+
+```ts
+const minAge = 25;
+const maxAge = 35;
+const inRange = await User.query()
+  .where((u) => u.age >= minAge && u.age <= maxAge)
+  .toArray();
+```
+
+```sql
+SELECT id, name, age, country FROM users WHERE age >= ? AND age <= ?
+-- params: [25, 35]
+```
+
+## Fluent Chaining
+
+```ts
+const oldest = await User.query()
+  .where((u) => u.age >= 25)
+  .orderBy((u) => u.age, "desc")
+  .first();
+
+const top10 = await User.query()
+  .where((u) => u.age >= 25)
+  .orderBy((u) => u.age, "desc")
+  .limit(10)
+  .toArray();
+```
+
+```sql
+SELECT id, name, age, country FROM users
+WHERE age >= ? ORDER BY age DESC LIMIT ?
+-- first():    params: [25, 1]
+-- toArray():  params: [25, 10]
+```
+
+`.first()` returns the first matching row or `undefined` (it sets `LIMIT 1` automatically). `.toArray()` returns all rows.
+
+## Select Columns
+
+```ts
+// Column-name array
+const names = await User.query().select(["name", "country"]).toArray();
+```
+
+```sql
+SELECT name AS name, country AS country FROM users
+```
+
+```ts
+// Lambda projection (with aliases)
+const projected = await User.query()
+  .select((u) => ({ userId: u.id, fullName: u.name }))
+  .toArray();
+```
+
+```sql
+SELECT id AS userId, name AS fullName FROM users
+```
+
+```ts
+// Shorthand: select all
+const all = await User.query()
+  .select((u) => u)
+  .toArray();
+
+// Shorthand: single column
+const ages = await User.query()
+  .select((u) => u.age)
+  .toArray();
+```
+
+Projection fields can also be computed expressions:
+
+```ts
+const labels = await User.query()
+  .select((u) => ({
+    name: u.name,
+    decade: (u.age / 10) * 10,
+    label: u.age >= 18 ? "adult" : "minor",
+  }))
+  .toArray();
+```
+
+In runtime mode, pass closure variables used inside `.select()` as the second argument. With the transformer enabled, they are captured automatically.
+
+## String Predicates
+
+`.startsWith()`, `.endsWith()`, and `.includes()` compile to SQL `LIKE`:
+
+```ts
+const a = await User.query()
+  .where((u) => u.name.startsWith("A"))
+  .toArray();
+const al = await User.query()
+  .where((u) => u.name.includes("al"))
+  .toArray();
+```
+
+```sql
+SELECT ... FROM users WHERE name LIKE ? || '%'   -- startsWith → params: ["A"]
+SELECT ... FROM users WHERE name LIKE '%' || ? || '%'  -- includes → params: ["al"]
+```
+
+## Array Membership
+
+```ts
+const selected = await User.query()
+  .where((u) => u.id in [1, 3])
+  .toArray();
+const excluded = await User.query()
+  .where((u) => !(u.id in [2]))
+  .toArray();
+```
+
+```sql
+SELECT ... FROM users WHERE id IN (?, ?)    -- params: [1, 3]
+SELECT ... FROM users WHERE id NOT IN (?)   -- params: [2]
+```
+
+Variable arrays work too — captured automatically with the transformer:
+
+```ts
+const ids = [1, 2];
+const byIds = await User.query()
+  .where((u) => u.id in ids)
+  .toArray();
+```
+
+## Find by ID and Count
+
+```ts
+const user = await User.query().findById(1);
+const n = await User.query()
+  .where((u) => u.country === "US")
+  .count();
+```
+
+```sql
+SELECT ... FROM users WHERE id = ? LIMIT 1           -- params: [1]
+SELECT COUNT(*) AS c FROM (
+  SELECT ... FROM "users" AS "t0" WHERE ("t0"."country" = ?)
+) AS "_count"                                        -- params: ["US"]
+```
+
+## Update, Patch, and Delete
+
+```ts
+const updated = await User.query()
+  .where((u) => u.name === "Bob")
+  .update({ age: 26 });
+```
+
+```sql
+UPDATE users SET age = ? WHERE name = ?
+-- params: [26, "Bob"]
+```
+
+```ts
+const patched = await User.query()
+  .where((u) => u.name === "Bob")
+  .patch({ age: 26 });
+// Same UPDATE as above, then a SELECT ... WHERE name = ? LIMIT 1 to return the row
+```
+
+```ts
+const deleted = await User.query()
+  .where((u) => u.country === "UK")
+  .delete();
+```
+
+```sql
+DELETE FROM users WHERE country = ?
+-- params: ["UK"]
+```
+
+## Instance Save and Delete
+
+```ts
+const dave = new User({ name: "Dave", age: 35, country: "US" });
+await dave.query().save(); // INSERT — populates dave.id
+await dave.query().delete(); // DELETE WHERE id = ?
+```
+
+`save()` inserts when the primary key is unset and updates when it's already set.
+
+## Debug Mode
+
+```bash
+TYPHEX_DEBUG=1 npx tsx your-script.ts
+```
+
+Logs every SQL statement and its parameters to the console — exactly the SQL shown alongside each example on this page. Accepts `1`, `true`, or `yes`.

package/docs/guide/querying-relations.md

@@ -0,0 +1,133 @@
+# Querying Relations
+
+Once you've [defined relations](/guide/entities-relations) on your entities, you can include related data in query results using a lambda passed to `.select()`.
+
+## manyToOne in `select()`
+
+When you select a `manyToOne` relation, Typhex fetches the related rows using a single `WHERE id IN (...)` query — not N+1 individual queries.
+
+```ts
+const Post = Entity(
+  "posts",
+  {
+    id: "integer primary key autoincrement",
+    title: "text not null",
+    body: "text",
+    authorId: "integer not null",
+    published: "boolean",
+  },
+  { author: rel.manyToOne(() => User, { foreignKey: "authorId" }) },
+);
+
+const postsWithAuthor = await Post.query()
+  .select((p) => ({ id: p.id, title: p.title, author: p.author })) // [!code highlight]
+  .orderBy((p) => p.id, "asc")
+  .toArray();
+```
+
+```sql
+-- 1. Main query
+SELECT id AS id, title AS title, authorId AS authorId FROM posts ORDER BY id ASC
+
+-- 2. Author fetch (one query for all authors, regardless of how many posts)
+SELECT id, name FROM users WHERE id IN (?, ?, ...)
+```
+
+## Partial Relation Select
+
+Select only specific fields from the related entity by using an inline object literal:
+
+```ts
+const postsPartialAuthor = await Post.query()
+  .select((p) => ({
+    id: p.id,
+    title: p.title,
+    author: { id: p.author.id, name: p.author.name }, // [!code highlight]
+  }))
+  .toArray();
+```
+
+```sql
+SELECT id AS id, title AS title, authorId AS authorId FROM posts
+SELECT id, name FROM users WHERE id IN (?, ?, ...)  -- only id and name fetched
+```
+
+This keeps the result shape small when you don't need all columns from the related entity.
+
+## oneToMany in `select()`
+
+For `oneToMany` relations, call `.query()` on the relation to get a sub-query builder:
+
+```ts
+const User = Entity(
+  "users",
+  { id: "integer primary key autoincrement", name: "text not null", email: "text" },
+  { posts: rel.oneToMany(() => Post, { foreignKey: "authorId" }) },
+);
+
+const usersWithPosts = await User.query()
+  .select((u) => ({
+    id: u.id,
+    name: u.name,
+    posts: u.posts.query().select((p) => ({ id: p.id, title: p.title })), // [!code highlight]
+  }))
+  .orderBy((p) => p.id, "asc")
+  .toArray();
+```
+
+```sql
+-- 1. Main query
+SELECT id AS id, name AS name FROM users ORDER BY id ASC
+
+-- 2. Posts fetched in one round-trip — all posts for all returned users
+SELECT id AS id, title AS title, authorId AS authorId
+FROM posts WHERE authorId IN (?, ?, ...)
+```
+
+Each user's `posts` field is populated in-memory by grouping the second result on `authorId`.
+
+## Filtering + Relations Combined
+
+Chain `.where()` before `.select()` — they compose naturally:
+
+```ts
+const publishedWithAuthor = await Post.query()
+  .where((p) => p.published === true)
+  .select((p) => ({ id: p.id, title: p.title, author: p.author }))
+  .toArray();
+```
+
+```sql
+SELECT id AS id, title AS title, authorId AS authorId
+FROM posts WHERE published = ?
+-- params: [1]
+
+SELECT id, name FROM users WHERE id IN (?, ?, ...)  -- only authors of matching posts
+```
+
+::: tip No N+1 queries
+Relation selects always use a single `WHERE foreignKey IN (...)` query to load all related rows in one round-trip — never per-row queries.
+:::
+
+## Circular References
+
+The `() => Target` thunk in relation definitions handles lazy evaluation at query time, so circular relations work out of the box at runtime. When two entities reference each other across files, TypeScript needs help with the types — declare the relation property explicitly and use `createRequire` to break the import cycle:
+
+```ts
+// models/user.ts
+import { createRequire } from "node:module";
+import { Entity, rel, type OneToMany } from "typhex";
+import type { Post } from "./post.js";
+
+const _require = createRequire(import.meta.url);
+
+export class User extends Entity(
+  "users",
+  { id: "integer primary key autoincrement", name: "text not null" },
+  { posts: rel.oneToMany(() => _require("./post.js").Post, { foreignKey: "authorId" }) },
+) {
+  declare posts: OneToMany<Post>;
+}
+```
+
+If your relations aren't circular, neither `declare` nor `createRequire` is needed — types flow directly from `rel.manyToOne(() => Company, ...)`.