typhex 0.1.0-alpha.0

package/dist/utils.js

@@ -0,0 +1,30 @@
+export function toArray(value) {
+    if (value == null)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function groupBy(items, keyFn) {
+    const map = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        const bucket = map.get(key);
+        if (bucket)
+            bucket.push(item);
+        else
+            map.set(key, [item]);
+    }
+    return map;
+}
+export function extractBaseType(def) {
+    const trimmed = def.trim().toLowerCase().replaceAll(/\s+/g, " ");
+    const withoutModifiers = trimmed.replace(/^(?:unsigned|signed)\s+/, "");
+    const multiWord = withoutModifiers.match(/^(?:double\s+precision|character\s+varying|timestamp\s+with\s+time\s+zone|timestamp\s+without\s+time\s+zone)(?:\([^)]*\))?/);
+    if (multiWord)
+        return multiWord[0];
+    const withParams = withoutModifiers.match(/^(\w+(?:\([^)]*\))?)/);
+    return withParams ? withParams[1] : (withoutModifiers.split(/\s/)[0] ?? trimmed);
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,OAAO,CAAI,KAA0B;IACnD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,EAAE,CAAC;IAC7B,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,OAAO,CAAO,KAAkB,EAAE,KAAqB;IACrE,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACxB,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM;YAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;;YACzB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,GAAW;IACzC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACjE,MAAM,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,yBAAyB,EAAE,EAAE,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CACtC,4HAA4H,CAC7H,CAAC;IACF,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,UAAU,GAAG,gBAAgB,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAClE,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC;AACnF,CAAC"}

package/docs/drivers/postgres.md

@@ -0,0 +1,54 @@
+# PostgreSQL Driver
+
+## Setup
+
+```ts
+import { Db, createPostgresDriver } from "typhex";
+
+const db = new Db(
+  createPostgresDriver({
+    connectionString: process.env.TYPHEX_POSTGRES_URL!,
+  }),
+);
+```
+
+## Options
+
+| Option                | Type       | Description                                                              |
+| --------------------- | ---------- | ------------------------------------------------------------------------ |
+| `connectionString`    | `string`   | Standard PostgreSQL URI: `postgresql://user:password@host:port/database` |
+| `url`                 | `string`   | Alias for `connectionString`, useful in config files                     |
+| `host`                | `string`   | Hostname when not using a connection string                              |
+| `port`                | `number`   | Port, default `5432`                                                     |
+| `database`            | `string`   | Database name, default `"postgres"`                                      |
+| `user`                | `string`   | Database user                                                            |
+| `password`            | `string`   | Database password                                                        |
+| `ssl`                 | `pg` value | SSL config forwarded to `pg`                                             |
+| `poolMin`             | `number`   | Minimum pool connections, default `2`                                    |
+| `poolMax`             | `number`   | Maximum pool connections, default `10`                                   |
+| `idleTimeoutMs`       | `number`   | Idle connection timeout in milliseconds, default `30000`                 |
+| `connectionTimeoutMs` | `number`   | Pool connection timeout in milliseconds, default `5000`                  |
+| `statementTimeoutMs`  | `number`   | PostgreSQL `statement_timeout` in milliseconds                           |
+| `logger`              | `object`   | Custom pool error logger with an `error(message, err)` method            |
+
+## Installation
+
+```bash
+npm install pg
+```
+
+The driver uses `pg.Pool` internally; call `db.close()` on shutdown to release pool connections.
+
+## Column Types
+
+Use PostgreSQL-native types in your schema:
+
+```ts
+const User = Entity("users", {
+  id: "SERIAL PRIMARY KEY",
+  name: "VARCHAR(255) NOT NULL",
+  age: "INTEGER NOT NULL",
+});
+```
+
+The query API (`where`, `insert`, `select`, etc.) is identical to SQLite — only the driver and column types differ.

package/docs/drivers/sqlite.md

@@ -0,0 +1,33 @@
+# SQLite Driver
+
+## Setup
+
+```ts
+import { Db, createSqliteDriver } from "typhex";
+
+const db = new Db(createSqliteDriver({ path: "./app.db" }));
+```
+
+Use `":memory:"` for an in-memory database (created fresh, discarded on close — useful for tests):
+
+```ts
+const db = new Db(createSqliteDriver({ path: ":memory:" }));
+```
+
+## Options
+
+| Option | Type     | Description                             |
+| ------ | -------- | --------------------------------------- |
+| `path` | `string` | Path to the `.db` file, or `":memory:"` |
+
+## Installation
+
+```bash
+npm install better-sqlite3
+```
+
+`better-sqlite3` includes a native C++ addon. If installation fails, install the appropriate build tools:
+
+- **macOS:** `xcode-select --install`
+- **Linux:** `apt install build-essential` (or distro equivalent)
+- **Windows:** Visual Studio Build Tools

package/docs/guide/aggregations.md

@@ -0,0 +1,272 @@
+# Aggregations
+
+Typhex supports `GROUP BY`, `HAVING`, and all standard aggregate functions. Import the aggregate helpers alongside your entities.
+
+```ts
+import { Db, Entity, createSqliteDriver, count, sum, avg, min, max, distinct } from "typhex";
+import { groupConcat } from "typhex/sqlite"; // SQLite-specific
+import { stringAgg, arrayAgg, jsonAgg } from "typhex/postgres"; // PostgreSQL-specific
+```
+
+## Aggregate Functions
+
+Use aggregate functions inside a `.select()` lambda:
+
+```ts
+const Order = Entity("orders", {
+  id: "integer primary key autoincrement",
+  category: "text not null",
+  status: "text not null",
+  price: "integer not null",
+});
+
+// Single aggregate — total count
+const total = await Order.query()
+  .select((o) => count(o.id))
+  .toArray();
+```
+
+```sql
+SELECT COUNT(id) AS total FROM orders
+```
+
+```ts
+// Multiple aggregates
+const stats = await Order.query()
+  .select((o) => ({
+    total: count(o.id),
+    minPrice: min(o.price),
+    maxPrice: max(o.price),
+    avgPrice: avg(o.price),
+  }))
+  .toArray();
+```
+
+```sql
+SELECT COUNT(id) AS total, MIN(price) AS minPrice,
+       MAX(price) AS maxPrice, AVG(price) AS avgPrice
+FROM orders
+```
+
+| Function        | SQL            | Notes                         |
+| --------------- | -------------- | ----------------------------- |
+| `count(col?)`   | `COUNT(col)`   | Omit arg for `COUNT(*)`       |
+| `sum(col)`      | `SUM(col)`     |                               |
+| `avg(col)`      | `AVG(col)`     |                               |
+| `min(col)`      | `MIN(col)`     |                               |
+| `max(col)`      | `MAX(col)`     |                               |
+| `distinct(col)` | `DISTINCT col` | Wrap inside another aggregate |
+
+## GROUP BY
+
+Pass an arrow function — the preferred form:
+
+```ts
+// Single column
+const revenueByCategory = await Order.query()
+  .select((o) => ({ category: o.category, revenue: sum(o.price) }))
+  .groupBy((o) => o.category)
+  .toArray();
+```
+
+```sql
+SELECT category AS category, SUM(price) AS revenue
+FROM orders
+GROUP BY category
+```
+
+```ts
+// Multiple columns — chain two groupBy calls
+const byCategoryAndStatus = await Order.query()
+  .select((o) => ({ category: o.category, status: o.status, cnt: count(o.id) }))
+  .groupBy((o) => o.category)
+  .groupBy((o) => o.status)
+  .toArray();
+```
+
+```sql
+SELECT category AS category, status AS status, COUNT(id) AS cnt
+FROM orders
+GROUP BY category, status
+```
+
+`.groupBy()` also accepts a column name string, an array of strings, or positional indices (`1`, `[1, 2]`) when chaining lambdas isn't convenient.
+
+## HAVING
+
+`.having()` accepts the same arrow-function syntax as `.where()`. Closure variables are auto-captured with the transformer:
+
+```ts
+// Only categories with more than 1 order
+const busy = await Order.query()
+  .select((o) => ({ category: o.category, cnt: count(o.id) }))
+  .groupBy((o) => o.category)
+  .having((o) => count(o.id) > 1)
+  .toArray();
+```
+
+```sql
+SELECT category AS category, COUNT(id) AS cnt
+FROM orders
+GROUP BY category
+HAVING COUNT(id) > ?
+-- params: [1]
+```
+
+```ts
+// Closure variable
+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();
+```
+
+```sql
+SELECT category AS category, SUM(price) AS revenue
+FROM orders
+GROUP BY category
+HAVING SUM(price) >= ?
+-- params: [200]
+```
+
+::: info Runtime mode
+In runtime mode, pass closure variables explicitly: `.having((o) => sum(o.price) >= minRevenue, { minRevenue })`.
+:::
+
+## Expression Arguments
+
+Aggregate arguments can be computed expressions. This is useful for totals derived from multiple columns and conditional counts:
+
+```ts
+const cutoff = 5;
+const stats = await Order.query()
+  .select(
+    (o) => ({
+      category: o.category,
+      revenue: sum(o.price * o.qty),
+      smallOrders: sum(o.qty < cutoff ? 1 : 0),
+    }),
+    { cutoff },
+  )
+  .groupBy((o) => o.category)
+  .toArray();
+```
+
+```sql
+SELECT category AS category,
+       SUM(price * qty) AS revenue,
+       SUM(CASE WHEN qty < ? THEN ? ELSE ? END) AS smallOrders
+FROM orders
+GROUP BY category
+-- params: [5, 1, 0]
+```
+
+In runtime mode, pass closure variables used inside `.select()` as the second argument. With the transformer enabled, no second argument is needed.
+
+## Combining WHERE + GROUP BY + HAVING
+
+All three compose naturally:
+
+```ts
+const shippedStats = await Order.query()
+  .where((o) => o.status === "shipped")
+  .select((o) => ({ category: o.category, cnt: count(o.id), total: sum(o.price) }))
+  .groupBy((o) => o.category)
+  .having((o) => count(o.id) > 0)
+  .orderBy((o) => o.category, "asc")
+  .toArray();
+```
+
+```sql
+SELECT category AS category, COUNT(id) AS cnt, SUM(price) AS total
+FROM orders
+WHERE status = ?
+GROUP BY category
+HAVING COUNT(id) > ?
+ORDER BY category ASC
+-- params: ["shipped", 0]
+```
+
+## DISTINCT
+
+Wrap a column with `distinct()` inside another aggregate to deduplicate before aggregating:
+
+```ts
+// COUNT(DISTINCT category)
+const uniqueCategories = await Order.query()
+  .select((o) => ({ uniqueCategories: count(distinct(o.category)) }))
+  .toArray();
+```
+
+```sql
+SELECT COUNT(DISTINCT category) AS uniqueCategories FROM orders
+```
+
+```ts
+// SUM(DISTINCT price)
+const distinctRevenue = await Order.query()
+  .select((o) => ({ revenue: sum(distinct(o.price)) }))
+  .toArray();
+```
+
+```sql
+SELECT SUM(DISTINCT price) AS revenue FROM orders
+```
+
+## Database-Specific Aggregates
+
+### SQLite: `groupConcat`
+
+```ts
+import { groupConcat } from "typhex/sqlite";
+
+// Per status
+const byStatus = await Order.query()
+  .select((o) => ({ status: o.status, categories: groupConcat(o.category, ", ") }))
+  .groupBy((o) => o.status)
+  .toArray();
+```
+
+```sql
+SELECT status AS status, GROUP_CONCAT(category, ?) AS categories
+FROM orders
+GROUP BY status
+-- params: [", "]
+```
+
+### PostgreSQL: `stringAgg`, `arrayAgg`, `jsonAgg`
+
+```ts
+import { stringAgg, arrayAgg, jsonAgg } from "typhex/postgres";
+
+// STRING_AGG — concatenate with separator
+const tagList = await Post.query()
+  .select((p) => ({ category: p.category, tags: stringAgg(p.tag, ", ") }))
+  .groupBy((p) => p.category)
+  .toArray();
+```
+
+```sql
+SELECT "category" AS "category", STRING_AGG("tag", $1) AS "tags"
+FROM "posts"
+GROUP BY "category"
+-- params: [", "]
+```
+
+```ts
+// ARRAY_AGG — collect values into a PostgreSQL array
+const ids = await Post.query()
+  .select((p) => ({ category: p.category, ids: arrayAgg(p.id) }))
+  .groupBy((p) => p.category)
+  .toArray();
+// SQL: ARRAY_AGG("id") AS "ids"
+
+// JSON_AGG — collect values into a JSON array
+const titles = await Post.query()
+  .select((p) => ({ category: p.category, titles: jsonAgg(p.title) }))
+  .groupBy((p) => p.category)
+  .toArray();
+// SQL: JSON_AGG("title") AS "titles"
+```

package/docs/guide/bulk-operations.md

@@ -0,0 +1,204 @@
+# Bulk Operations
+
+## insertMany
+
+Insert multiple rows in a single SQL statement:
+
+```ts
+await Product.query().insertMany([
+  { sku: "W-001", name: "Widget", price: 999, stock: 100 },
+  { sku: "G-001", name: "Gadget", price: 1499, stock: 50 },
+  { sku: "D-001", name: "Doohickey", price: 249, stock: 200 },
+]);
+```
+
+```sql
+INSERT INTO products (sku, name, price, stock)
+VALUES (?, ?, ?, ?), (?, ?, ?, ?), (?, ?, ?, ?)
+-- params: ["W-001", "Widget", 999, 100, "G-001", "Gadget", 1499, 50, "D-001", "Doohickey", 249, 200]
+```
+
+`insertMany` returns the inserted rows on PostgreSQL (where `RETURNING` is available). On SQLite, it returns an empty array — use a follow-up query if you need the inserted rows.
+
+## onConflict
+
+Both `insert()` and `insertMany()` support conflict resolution via `.onConflict(columns)`:
+
+### doNothing
+
+Skip rows that violate a unique constraint:
+
+```ts
+await Product.query()
+  .insertMany([
+    { sku: "W-001", name: "Updated", price: 888, stock: 999 }, // skipped (sku exists)
+    { sku: "T-001", name: "Thingamajig", price: 599, stock: 75 }, // inserted
+  ])
+  .onConflict(["sku"])
+  .doNothing();
+```
+
+```sql
+INSERT INTO products (sku, name, price, stock) VALUES (?, ?, ?, ?), (?, ?, ?, ?)
+ON CONFLICT (sku) DO NOTHING
+```
+
+### doUpdate (upsert)
+
+Update all non-conflict columns when a clash is detected:
+
+```ts
+await Product.query()
+  .insert({ sku: "W-001", name: "Widget v2", price: 1099, stock: 80 })
+  .onConflict(["sku"])
+  .doUpdate();
+```
+
+```sql
+INSERT INTO products (sku, name, price, stock) VALUES (?, ?, ?, ?)
+ON CONFLICT (sku) DO UPDATE SET
+  name = excluded.name,
+  price = excluded.price,
+  stock = excluded.stock
+```
+
+### doUpdate with specific columns
+
+Update only specified columns, leaving the rest unchanged:
+
+```ts
+await Product.query()
+  .insert({ sku: "G-001", name: "Renamed (ignored)", price: 1799, stock: 0 })
+  .onConflict(["sku"])
+  .doUpdate(["price"]); // only price is updated; name stays as-is
+```
+
+```sql
+INSERT INTO products (sku, name, price, stock) VALUES (?, ?, ?, ?)
+ON CONFLICT (sku) DO UPDATE SET price = excluded.price
+```
+
+### Bulk upsert
+
+Combine `insertMany` with `onConflict` for price-list style updates:
+
+```ts
+await Product.query()
+  .insertMany([
+    { sku: "W-001", name: "irrelevant", price: 500, stock: 0 },
+    { sku: "Z-001", name: "Zapper", price: 3999, stock: 10 },
+  ])
+  .onConflict(["sku"])
+  .doUpdate(["price"]);
+// W-001's price is updated to 500; Z-001 is inserted as new
+```
+
+```sql
+INSERT INTO products (sku, name, price, stock) VALUES (?, ?, ?, ?), (?, ?, ?, ?)
+ON CONFLICT (sku) DO UPDATE SET price = excluded.price
+```
+
+## insertGraph
+
+`insertGraph` inserts an entire object graph — related entities and junction rows — in the correct dependency order. You pass a plain object shaped like your entity with its relations nested inside:
+
+### manyToOne parent
+
+Provide the parent as a nested object — Typhex inserts it first and wires the foreign key automatically:
+
+```ts
+const post = await Post.query().insertGraph({
+  title: "Hello",
+  author: { name: "Alice" },
+});
+```
+
+```sql
+-- 1. Parent first
+INSERT INTO users (name) VALUES (?)              -- params: ["Alice"]
+
+-- 2. Root with foreign key wired in
+INSERT INTO posts (title, authorId) VALUES (?, ?) -- params: ["Hello", 1]
+```
+
+### oneToMany children
+
+Provide children as an array — Typhex inserts the root first and back-fills the foreign key on each child:
+
+```ts
+const user = await User.query().insertGraph({
+  name: "Alice",
+  posts: [{ title: "First post" }, { title: "Second post" }],
+});
+```
+
+```sql
+-- 1. Root first
+INSERT INTO users (name) VALUES (?)                  -- params: ["Alice"]
+
+-- 2. Children batched, with authorId auto-filled
+INSERT INTO posts (title, authorId) VALUES (?, ?), (?, ?)
+-- params: ["First post", 1, "Second post", 1]
+```
+
+### manyToMany
+
+Mix new records with references to existing ones using `{ id: existingId }`:
+
+```ts
+const existingTag = await Tag.query().findById(1);
+
+const post = await Post.query().insertGraph({
+  title: "Hello",
+  author: { name: "Alice" },
+  tags: [
+    { id: existingTag.id }, // link existing tag
+    { name: "new-tag" }, // insert new tag
+  ],
+});
+```
+
+```sql
+INSERT INTO users (name) VALUES (?)              -- author
+INSERT INTO posts (title, authorId) VALUES (?, ?) -- root post
+INSERT INTO tags (name) VALUES (?)               -- only the new tag is inserted
+
+-- Junction rows for both existing + new tag
+INSERT INTO post_tags (postId, tagId) VALUES (?, ?), (?, ?)
+```
+
+### Batch insert
+
+Pass an array to insert multiple graphs at once:
+
+```ts
+const users = await User.query().insertGraph([
+  { name: "Alice", posts: [{ title: "A-1" }, { title: "A-2" }] },
+  { name: "Bob", posts: [{ title: "B-1" }] },
+]);
+```
+
+```sql
+-- Roots batched
+INSERT INTO users (name) VALUES (?), (?)         -- ["Alice", "Bob"]
+
+-- All children batched, foreign keys back-filled
+INSERT INTO posts (title, authorId) VALUES (?, ?), (?, ?), (?, ?)
+-- ["A-1", 1, "A-2", 1, "B-1", 2]
+```
+
+### With a transaction
+
+`insertGraph` participates in an existing transaction:
+
+```ts
+await db.transaction(async (trx) => {
+  await Post.query(trx).insertGraph({
+    title: "Atomic post",
+    author: { name: "Dave" },
+    tags: [{ name: "typescript" }],
+  });
+});
+```
+
+If any insert in the graph fails, the transaction rolls back the entire graph.