typhex 0.1.0-alpha.0

package/docs/guide/subqueries.md

@@ -0,0 +1,152 @@
+# Subqueries
+
+Typhex supports `IN` subqueries in runtime mode and transformer mode. Scalar and correlated subqueries are transformer-only because the compiler needs to capture the outer query reference.
+
+## `IN` Subqueries
+
+In runtime mode, build the inner query first and pass it through the params object:
+
+```ts
+const activePostAuthors = Post.query()
+  .where((p) => p.active === 1)
+  .select((p) => p.authorId);
+
+const authors = await Author.query()
+  .where((a, posts) => a.id in posts, { posts: activePostAuthors })
+  .toArray();
+```
+
+```sql
+SELECT "t0"."id", "t0"."name"
+FROM "authors" AS "t0"
+WHERE "t0"."id" IN (
+  SELECT "t1"."authorId" FROM "posts" AS "t1" WHERE ("t1"."active" = ?)
+)
+-- params: [1]
+```
+
+With the transformer enabled, the inner query can be written inline:
+
+```ts
+const authors = await Author.query()
+  .where(
+    (a) =>
+      a.id in
+      Post.query()
+        .where((p) => p.active === 1)
+        .select((p) => p.authorId),
+  )
+  .toArray();
+```
+
+```sql
+SELECT "t0"."id", "t0"."name"
+FROM "authors" AS "t0"
+WHERE "t0"."id" IN (
+  SELECT "t1"."authorId" FROM "posts" AS "t1" WHERE ("t1"."active" = ?)
+)
+-- params: [1]
+```
+
+Nested inline `IN` subqueries use the same transformer path:
+
+```ts
+const authors = await Author.query()
+  .where(
+    (a) =>
+      a.id in
+      Post.query()
+        .where(
+          (p) =>
+            p.authorId in
+            Author.query()
+              .where((candidate) => candidate.name !== "Carol")
+              .select((candidate) => candidate.id),
+        )
+        .select((p) => p.authorId),
+  )
+  .toArray();
+```
+
+```sql
+SELECT "t0"."id", "t0"."name"
+FROM "authors" AS "t0"
+WHERE "t0"."id" IN (
+  SELECT "t1"."authorId" FROM "posts" AS "t1"
+  WHERE "t1"."authorId" IN (
+    SELECT "t2"."id" FROM "authors" AS "t2" WHERE ("t2"."name" <> ?)
+  )
+)
+-- params: ["Carol"]
+```
+
+## Scalar Subqueries
+
+Use `.select(() => count())` on the inner query when the subquery should return one value:
+
+```ts
+import { count } from "typhex";
+
+const authorsWithCounts = await Author.query()
+  .select((a) => ({
+    name: a.name,
+    postCount: Post.query()
+      .where((p) => p.authorId === a.id)
+      .select(() => count()),
+  }))
+  .toArray();
+```
+
+```sql
+SELECT "t0"."name" AS "name",
+       (SELECT COUNT(*) FROM "posts" AS "t1" WHERE ("t1"."authorId" = "t0"."id")) AS "postCount"
+FROM "authors" AS "t0"
+```
+
+The `a.id` reference is correlated to the outer row, so this form requires the TypeScript transformer.
+
+## Comparing Against Subqueries
+
+Scalar subqueries can appear in `where()` comparisons:
+
+```ts
+const prolificAuthors = await Author.query()
+  .where(
+    (a) =>
+      Post.query()
+        .where((p) => p.authorId === a.id)
+        .select(() => count()) > 1,
+  )
+  .toArray();
+```
+
+```sql
+SELECT "t0"."id", "t0"."name"
+FROM "authors" AS "t0"
+WHERE ((SELECT COUNT(*) FROM "posts" AS "t1" WHERE ("t1"."authorId" = "t0"."id")) > ?)
+-- params: [1]
+```
+
+## Ordering by Subqueries
+
+Correlated scalar subqueries also work in `orderBy()`:
+
+```ts
+const sorted = await Author.query()
+  .orderBy(
+    (a) =>
+      Post.query()
+        .where((p) => p.authorId === a.id)
+        .select(() => count()),
+    "desc",
+  )
+  .toArray();
+```
+
+```sql
+SELECT "t0"."id", "t0"."name"
+FROM "authors" AS "t0"
+ORDER BY (SELECT COUNT(*) FROM "posts" AS "t1" WHERE ("t1"."authorId" = "t0"."id")) DESC
+```
+
+Run `npm run subqueries` from `examples/` for a complete transformer-backed demo.

package/docs/guide/transactions.md

@@ -0,0 +1,146 @@
+# Transactions
+
+Typhex provides two transaction APIs. Both support nested savepoints and configurable isolation levels.
+
+## Callback API (Recommended)
+
+Pass an async callback to `db.transaction()`. Any `Entity.query()` call inside the callback **automatically uses the active transaction** — no need to thread a `trx` argument through your code:
+
+```ts
+import { Db, Entity, createSqliteDriver } from "typhex";
+
+await db.transaction(async () => {
+  const user = await User.query().insert({ name: "Alice" });
+  await Post.query().insert({ title: "Hello", authorId: user.id });
+});
+```
+
+```sql
+BEGIN
+  INSERT INTO users (name) VALUES (?)
+  INSERT INTO posts (title, authorId) VALUES (?, ?)
+COMMIT
+```
+
+If the callback throws, the transaction is rolled back automatically:
+
+```ts
+await db
+  .transaction(async () => {
+    await User.query().insert({ name: "Bob" });
+    throw new Error("oops");
+  })
+  .catch((e) => console.log("rolled back:", e.message));
+```
+
+```sql
+BEGIN
+  INSERT INTO users (name) VALUES (?)
+ROLLBACK
+```
+
+## Explicit API (Service-Layer Pattern)
+
+Use `db.beginTrx()` when you need to pass the transaction handle to functions that shouldn't know about `db`:
+
+```ts
+import { Trx } from "typhex";
+
+async function createUserWithPost(trx: Trx, name: string, title: string) {
+  const user = await User.query(trx).insert({ name });
+  await Post.query(trx).insert({ title, authorId: user.id });
+  return user;
+}
+
+const trx = await db.beginTrx();
+try {
+  const user = await createUserWithPost(trx, "Carol", "Carol's post");
+  await trx.commit();
+} catch {
+  await trx.rollback();
+}
+```
+
+`Entity.query(trx)` routes the query through the given transaction connection.
+
+## Nested Transactions (Savepoints)
+
+Calling `trx.transaction()` (or `db.transaction()` inside an active transaction) creates a **savepoint**. Rolling back the inner transaction only undoes work since the savepoint — the outer transaction is unaffected:
+
+```ts
+await db.transaction(async (outer) => {
+  const dave = await User.query(outer).insert({ name: "Dave" });
+
+  // Inner savepoint — will be rolled back
+  await outer
+    .transaction(async (inner) => {
+      await Post.query(inner).insert({ title: "Draft", authorId: dave.id });
+      throw new Error("discard draft");
+    })
+    .catch(() => {}); // only the draft is lost
+
+  // Dave still exists; publish a different post
+  await Post.query(outer).insert({ title: "Published", authorId: dave.id });
+});
+```
+
+```sql
+BEGIN
+  INSERT INTO users (name) VALUES (?)
+  SAVEPOINT sp_1
+    INSERT INTO posts (title, authorId) VALUES (?, ?)
+  ROLLBACK TO SAVEPOINT sp_1
+  INSERT INTO posts (title, authorId) VALUES (?, ?)
+COMMIT
+```
+
+## Transaction Options
+
+### Isolation Level
+
+```ts
+await db.transaction(
+  async () => {
+    // ...
+  },
+  { isolationLevel: "SERIALIZABLE" },
+);
+```
+
+```sql
+-- SQLite
+BEGIN IMMEDIATE
+  ...
+COMMIT
+
+-- PostgreSQL
+BEGIN ISOLATION LEVEL SERIALIZABLE
+  ...
+COMMIT
+```
+
+SQLite maps `"SERIALIZABLE"` to `BEGIN IMMEDIATE`.
+
+### SQLite Exclusive Mode
+
+```ts
+const trx = await db.beginTrx({ sqliteMode: "exclusive" });
+await User.query(trx).insert({ name: "Frank" });
+await trx.commit();
+```
+
+`sqliteMode` accepts `"deferred"` (default), `"immediate"`, or `"exclusive"`.
+
+## With insertGraph
+
+`insertGraph` respects an active transaction — pass `trx` to keep the whole graph insertion atomic:
+
+```ts
+await db.transaction(async (trx) => {
+  await Post.query(trx).insertGraph({
+    title: "Hello",
+    author: { name: "Alice" },
+    tags: [{ name: "typescript" }, { name: "orm" }],
+  });
+});
+```

package/docs/guide/typescript-transformer.md

@@ -0,0 +1,138 @@
+# TypeScript Transformer
+
+The TypeScript transformer is the **recommended way to use Typhex**. It runs as a compiler plugin during `tsc`, converting arrow-function predicates to IR at build time. The result: no runtime parsing overhead and no closure boilerplate at the call site.
+
+## Setup
+
+### 1. Install ts-patch
+
+```bash
+npm install --save-dev ts-patch
+```
+
+### 2. Configure `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "plugins": [{ "transform": "typhex/transformer" }]
+  }
+}
+```
+
+### 3. Patch TypeScript (one-time)
+
+```bash
+npx ts-patch install
+```
+
+To keep the patch across reinstalls, add it as a `postinstall` script:
+
+```json
+{
+  "scripts": {
+    "postinstall": "ts-patch install -s"
+  }
+}
+```
+
+After this, `tsc` (or `tspc`) automatically applies the transformer whenever it compiles your project.
+
+## What Changes at the Call Site
+
+With the transformer, you **never need a second argument** to `.where()` or `.select()`. Closure variables are detected and injected automatically:
+
+```ts
+// Without transformer — runtime mode
+const country = "US";
+users.where((u) => u.country === country, { country }); // [!code --]
+
+// With transformer — compiler handles it
+const country = "US";
+users.where((u) => u.country === country); // [!code ++]
+```
+
+The same applies to projections and aggregate expressions:
+
+```ts
+const cutoff = 5;
+orders.select((o) => ({ smalls: sum(o.qty < cutoff ? 1 : 0) }));
+```
+
+Multiple variables are all captured at once:
+
+```ts
+const minAge = 25;
+const maxAge = 35;
+
+const inRange = await User.query()
+  .where((u) => u.age >= minAge && u.age <= maxAge)
+  .orderBy((u) => u.name, "asc")
+  .toArray();
+```
+
+## Select, OrderBy, Having
+
+The transformer handles every method that takes an arrow function — `.where()`, `.select()`, `.having()`, `.orderBy()`, `.groupBy()`:
+
+```ts
+const minRevenue = 200;
+
+const highRevenue = await Order.query()
+  .select((o) => ({ category: o.category, revenue: sum(o.price) }))
+  .groupBy((o) => o.category)
+  .having((o) => sum(o.price) >= minRevenue)
+  .toArray();
+```
+
+## Transformer-Only Query Shapes
+
+Some query shapes depend on compile-time closure capture and are transformer-only:
+
+```ts
+// Correlated scalar subquery in SELECT
+Author.query().select((a) => ({
+  name: a.name,
+  postCount: Post.query()
+    .where((p) => p.authorId === a.id)
+    .select(() => count()),
+}));
+
+// Correlated scalar subquery in ORDER BY
+Author.query().orderBy(
+  (a) =>
+    Post.query()
+      .where((p) => p.authorId === a.id)
+      .select(() => count()),
+  "desc",
+);
+```
+
+Runtime mode still supports `IN` subqueries by passing the inner query through the params object. See [Subqueries](/guide/subqueries).
+
+## How It Works
+
+The transformer is a TypeScript compiler plugin. At compile time it:
+
+1. Finds every `.where()`, `.select()`, `.having()`, `.groupBy()`, and `.orderBy()` call with an arrow function
+2. Parses the function body into Typhex IR using the TypeScript AST
+3. Replaces the call with `.where(compiledIr, { capturedVars... })`
+
+The compiled output is standard JavaScript with IR pre-built — no dynamic parsing at runtime.
+
+## Runtime Mode as Fallback
+
+If you run files directly with `tsx` (no build step), or work in a plain JavaScript codebase, Typhex falls back to the runtime Acorn parser. Closure variables must be passed explicitly:
+
+```ts
+const country = "US";
+await User.query()
+  .where((u) => u.country === country, { country })
+  .toArray();
+```
+
+SQL output is identical either way; only the call site differs.
+
+::: warning tsx and ts-node
+`tsx` and `ts-node` do not run the TypeScript compiler pipeline, so the transformer plugin is not invoked even if configured in `tsconfig.json`. Use `tspc` (ts-patch's compiler wrapper) or a `tsc --watch` build step to get the transformer at dev time.
+:::

package/docs/index.md

@@ -0,0 +1,33 @@
+---
+layout: home
+
+hero:
+  name: Typhex
+  text: Arrow-function queries for TypeScript
+  tagline: Type-safe SQL without string templates or verbose builders. Write predicates like TypeScript — Typhex compiles them to safe, parameterized SQL at build time.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /guide/getting-started
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/kalyvasio/typhex
+
+features:
+  - title: Arrow-Function Predicates
+    details: Write `users.where(u => u.age > 18)` — no string templates, no SQL injection, no verbose builder syntax. Predicates compile to SQL at build time via the TypeScript transformer.
+  - title: TypeScript-Native
+    details: Types flow from your schema definition — no decorators, no code generation. The compiler plugin auto-captures closure variables so there's no boilerplate at the call site.
+  - title: Relations & Joins
+    details: Declare `manyToOne`, `oneToMany`, and `manyToMany` relations. Reference them in `where()` for automatic JOINs and `select()` for eager loading — never N+1.
+  - title: Expression Queries
+    details: Use ternaries, arithmetic, bitwise operators, null checks, and computed projections inside `where()`, `select()`, aggregate arguments, `having()`, and `orderBy()`.
+  - title: Aggregations
+    details: Full GROUP BY / HAVING support with `sum()`, `avg()`, `min()`, `max()`, `count()`, `distinct()`, and `groupConcat()`. Filter groups with arrow-function `having()` predicates.
+  - title: CTEs and Subqueries
+    details: Build `WITH` clauses, recursive CTEs, `UNION ALL` branches, `IN` subqueries, and transformer-backed correlated scalar subqueries.
+  - title: Transactions
+    details: Callback API with implicit AsyncLocalStorage propagation. Explicit API for service-layer patterns. Nested savepoints. Configurable isolation levels.
+  - title: SQLite + PostgreSQL
+    details: Built-in drivers for both databases. Bulk inserts, upserts (`onConflict`), and `insertGraph` for nested object graphs. The query API is identical across drivers.
+---

package/docs/migrations/overview.md

@@ -0,0 +1,143 @@
+# Migrations
+
+Typhex includes a schema-diffing migration system. Define your entities, generate SQL migration files, apply them to the database, and inspect their status.
+
+## API
+
+### `db.generateMigrations(dir)`
+
+Diffs current entity definitions against the database and writes new `.js` migration modules for any schema changes.
+
+```ts
+const files = await db.generateMigrations("./migrations");
+// Returns: { name: string, upSql: string, downSql: string, content: string }[]
+```
+
+On first run (no existing migration files), generates `CREATE TABLE` statements for all registered entities. On subsequent runs, generates `ALTER TABLE` statements for any new columns detected.
+
+### `db.runMigrations(dir)`
+
+Applies all pending migration files in `dir`, in lexicographic order by filename.
+
+```ts
+const result = await db.runMigrations("./migrations");
+// Returns: { applied: string[], skipped: string[] }
+```
+
+Files already applied (tracked in a `_typhex_migrations` table) are skipped.
+
+### `db.migrationStatus(dir)`
+
+Inspects which migrations have been applied and which are pending.
+
+```ts
+const status = await db.migrationStatus("./migrations");
+// Returns: { applied: MigrationRecord[], pending: string[] }
+```
+
+## Workflow
+
+A typical migration flow:
+
+```ts
+import { Db, Entity, createSqliteDriver } from "typhex";
+
+const User = Entity("users", {
+  id: "integer primary key autoincrement",
+  name: "text not null",
+  email: "text",
+});
+
+const db = new Db(createSqliteDriver({ path: "./app.db" }));
+
+// 1. Generate any new migrations from current entity definitions
+await db.generateMigrations("./migrations");
+
+// 2. Apply them
+await db.runMigrations("./migrations");
+```
+
+The first run creates files like:
+
+```
+migrations/
+  2026042823220001_add_users_table.js
+```
+
+Each file exports SQL plus executable `up(db)` and `down(db)` functions:
+
+```js
+export const upSql = `CREATE TABLE IF NOT EXISTS "users" ("id" integer primary key autoincrement, "name" text not null, "email" text);`;
+
+export const downSql = `DROP TABLE IF EXISTS "users";`;
+
+export async function up(db) {
+  await db.run(upSql);
+}
+
+export async function down(db) {
+  await db.run(downSql);
+}
+```
+
+When you add a column to your entity (e.g., `age: "integer"`), the next `generateMigrations()` call writes a new file:
+
+```sql
+-- 2026042823230001_add_age_column_on_users.js
+ALTER TABLE users ADD COLUMN age integer;
+```
+
+`runMigrations()` then applies only the new file — already-applied files are skipped.
+
+## PostgreSQL
+
+The migration API is identical for PostgreSQL. Use PostgreSQL column types in your schema:
+
+```ts
+import { Db, Entity, createPostgresDriver } from "typhex";
+
+const User = Entity("users", {
+  id: "SERIAL PRIMARY KEY",
+  name: "VARCHAR(255) NOT NULL",
+  email: "VARCHAR(255)",
+});
+
+const db = new Db(
+  createPostgresDriver({
+    connectionString: process.env.TYPHEX_POSTGRES_URL!,
+  }),
+);
+
+await db.generateMigrations("./migrations");
+await db.runMigrations("./migrations");
+```
+
+## CLI
+
+Typhex ships a CLI that loads a `typhex.config.js` from your project root:
+
+```bash
+npx typhex migrate:generate --entities ./dist/entities.js --db ./app.db --dir ./migrations
+npx typhex migrate:run --db ./app.db --dir ./migrations
+npx typhex migrate:status --db ./app.db --dir ./migrations
+```
+
+The same config can create a `Db` in application code:
+
+```js
+// typhex.config.js
+export default {
+  dialect: "sqlite",
+  database: "./app.db",
+  migrationsFolder: "./migrations",
+  entities: "./dist/entities.js",
+};
+```
+
+```ts
+import { Db } from "typhex";
+
+const db = await Db.fromConfig();
+```
+
+Use `url` instead of `database` for PostgreSQL connection strings.