@rwillians/exto 0.1.1 → 0.2.0

package/README.md

@@ -1,18 +1,18 @@
 # exto
 
-A teeny tiny, type-safe and zero-dependency ORM for [Bun](https://bun.sh),
-with adapters for SQLite and PostgreSQL.
+A teeny tiny, type-safe query builder for [Bun](https://bun.sh), with
+adapters for SQLite and PostgreSQL.
 
 ```ts
-import { create, from, into, table } from '@rwillians/exto';
+import { create, from, into, table, t } from '@rwillians/exto';
 import * as sqlite from '@rwillians/exto/bun-sqlite';
 
-const users = table('users', t => ({
-  id: t.sequence().primaryKey(),
+const users = table('users', {
+  id: t.uuidv7().generated().primaryKey(),
   name: t.string(),
   email: t.citext().unique(),
-  createdAt: t.datetime().default(() => new Date()),
-}));
+  createdAt: t.timestamp().default(() => new Date()),
+});
 
 const db = sqlite.connect('./db.sqlite');
 await create.table(users, { ifNotExists: true }).onto(db);
@@ -22,19 +22,16 @@ await into(users)
   .insert(db);
 
 const jane = await from(users)
-  .where('email', '=', 'JANE@example.com')
-  .select(['id', 'name'])
+  .where(users.email, '=', 'JANE@example.com')
+  .select({ id: users.id, name: users.name })
   .one(db);
-// → { id: number, name: string } | null
+// → { id: string, name: string } | null
 ```
 
-- Keys, operators and values are type-checked and autocompleted.
-- Inserted and updated values are validated before any SQL runs.
+- Columns, operators and values are type-checked and autocompleted.
+- Values are validated before any SQL runs.
 - No singletons: you always pass the database explicitly.
 
-> [!NOTE]
-> exto covers single-table queries for now. See [what's not supported yet](#not-supported-yet).
-
 
 ## Install
 
@@ -43,85 +40,96 @@ bun add @rwillians/exto
 ```
 
 
-## Tables
+## Connecting
 
 ```ts
-import { table } from '@rwillians/exto';
-import { z } from 'zod';
+import * as sqlite from '@rwillians/exto/bun-sqlite';
+import * as pg from '@rwillians/exto/bun-postgres';
 
-const tasks = table('tasks', t => ({
-  id: t.uuid().generated().primaryKey(),
-  parentId: t.uuid().nullable(),
-  status: t.enum(['queued', 'running', 'done']),
-  payload: t.json(z.record(z.string(), z.any())),
-  attempts: t.integer().default(0),
-  scheduledAt: t.datetime(),
-}));
-
-type Task = typeof tasks.infer;                // a row
-type TaskInsert = typeof tasks.inferForInsert; // what `.values()` takes
-type TaskUpdate = typeof tasks.inferForUpdate; // what `set` takes
-```
+const db = sqlite.connect(':memory:');
+const db = pg.connect('postgres://user:pass@localhost:5432/app');
 
-Keys are camelCase in TypeScript and snake_case in the database
-(`scheduledAt` → `scheduled_at`).
-
-| builder                            | TS type               | postgres           | sqlite                  |
-| :--------------------------------- | :-------------------- | :----------------- | :---------------------- |
-| `t.bigint()`                       | `bigint`              | `BIGINT`           | `INTEGER`               |
-| `t.binary()`                       | `Uint8Array`          | `BYTEA`            | `BLOB`                  |
-| `t.boolean()`                      | `boolean`             | `BOOLEAN`          | `INTEGER`               |
-| `t.citext()`                       | `string`              | `CITEXT`           | `TEXT COLLATE NOCASE`   |
-| `t.date()`                         | `string` (YYYY-MM-DD) | `DATE`             | `TEXT`                  |
-| `t.datetime()`                     | `Date`                | `TIMESTAMPTZ`      | `INTEGER`               |
-| `t.decimal({ precision, scale }?)` | `number`              | `NUMERIC(p, s)`    | `NUMERIC`               |
-| `t.enum([...values])`              | union of values       | `VARCHAR(n)`       | `TEXT`                  |
-| `t.float()`                        | `number`              | `DOUBLE PRECISION` | `REAL`                  |
-| `t.integer()`                      | `number`              | `BIGINT`           | `INTEGER`               |
-| `t.json(schema)`                   | schema's output       | `JSONB`            | `TEXT`                  |
-| `t.sequence()`                     | `number`              | `BIGINT` identity  | `INTEGER` autoincrement |
-| `t.string({ size? })`              | `string`              | `VARCHAR(size)`    | `TEXT`                  |
-| `t.text()`                         | `string`              | `TEXT`             | `TEXT`                  |
-| `t.uuid()`                         | `string`              | `UUID`             | `TEXT`                  |
-
-| modifier        | effect                                          |
-| :-------------- | :---------------------------------------------- |
-| `.primaryKey()` | primary key                                     |
-| `.nullable()`   | accepts `null`, optional on insert              |
-| `.default(v)`   | value or function used when omitted on insert   |
-| `.unique()`     | unique constraint                               |
-| `.generated()`  | value generated on insert (`t.uuid()` → UUIDv7) |
+// log every statement
+const db = sqlite.connect(':memory:', { loggers: [console] });
+```
 
-`t.json()` takes any [Standard Schema](https://standardschema.dev) (zod,
-valibot, arktype, ...). `t.citext()` needs `CREATE EXTENSION citext` on
-postgres (see [`exec`](#migrations)). `t.decimal()` values are JS numbers;
-precision and scale only shape postgres' column.
 
-### Custom columns
+## Tables
 
 ```ts
-import { column } from '@rwillians/exto';
+import { embedded, table, t, type Infer } from '@rwillians/exto';
 
-const email = () => column({ type: 'CITEXT', schema: z.email() });
+const tasks = table('tasks', {
+  id: t.uuidv7().generated().primaryKey(),
+  parentId: t.uuidv7().optional(),
+  status: t.enum(['queued', 'running', 'done']),
+  attempts: t.integer().unsigned().default(0),
+  maxAttempts: t.integer().unsigned().default(3),
+  payload: embedded.one({
+    kind: t.string(),
+    params: t.record().default({}),
+  }),
+  events: embedded.many({
+    kind: t.string(),
+    timestamp: t.timestamp().default(() => new Date()),
+  }),
+  scheduledTo: t.timestamp().default(() => new Date()),
+});
 
-const users = table('users', t => ({
-  id: t.sequence().primaryKey(),
-  email: email().unique(),
-}));
+type Task = Infer<'select', typeof tasks>;       // a row
+type TaskInsert = Infer<'insert', typeof tasks>; // what `.values()` takes
+type TaskUpdate = Infer<'update', typeof tasks>; // what `set` takes
 ```
 
+Keys are camelCase in TypeScript and snake_case in the database
+(`scheduledTo` → `scheduled_to`).
+
+| builder                            | TS type                   | postgres           | sqlite                  |
+| :--------------------------------- | :------------------------ | :----------------- | :---------------------- |
+| `t.bigint()`                       | `bigint`                  | `BIGINT`           | `INTEGER`               |
+| `t.binary()`                       | `Uint8Array`              | `BYTEA`            | `BLOB`                  |
+| `t.boolean()`                      | `boolean`                 | `BOOLEAN`          | `INTEGER`               |
+| `t.citext()`                       | `string`                  | `CITEXT`           | `TEXT COLLATE NOCASE`   |
+| `t.date()`                         | `string` (YYYY-MM-DD)     | `DATE`             | `TEXT`                  |
+| `t.decimal({ precision, scale }?)` | `number`                  | `NUMERIC(p, s)`    | `NUMERIC`               |
+| `t.enum([...values])`              | union of values           | `VARCHAR(n)`       | `TEXT`                  |
+| `t.float()`                        | `number`                  | `DOUBLE PRECISION` | `REAL`                  |
+| `t.integer()`                      | `number`                  | `BIGINT`           | `INTEGER`               |
+| `t.json(schema)`                   | schema's output           | `JSONB`            | `TEXT`                  |
+| `t.record()`                       | `Record<string, unknown>` | `JSONB`            | `TEXT`                  |
+| `t.sequence()`                     | `number`                  | `BIGINT` identity  | `INTEGER` autoincrement |
+| `t.string({ size? })`              | `string`                  | `VARCHAR(size)`    | `TEXT`                  |
+| `t.text()`                         | `string`                  | `TEXT`             | `TEXT`                  |
+| `t.timestamp()`                    | `Date`                    | `TIMESTAMPTZ`      | `INTEGER`               |
+| `t.uuidv7()`                       | `string`                  | `UUID`             | `TEXT`                  |
+| `embedded.one({ ... })`            | an object                 | `JSONB`            | `TEXT`                  |
+| `embedded.many({ ... })`           | an array of objects       | `JSONB`            | `TEXT`                  |
+
+| modifier        | effect                                        |
+| :-------------- | :-------------------------------------------- |
+| `.primaryKey()` | primary key                                   |
+| `.optional()`   | accepts `null`, optional on insert            |
+| `.default(v)`   | value or function used when omitted on insert |
+| `.unique()`     | unique constraint                             |
+| `.generated()`  | a UUIDv7 generated on insert (`t.uuidv7()`)   |
+| `.unsigned()`   | rejects negatives (`t.integer()`)             |
 
-## Connecting
+`t.json()` takes any [Standard Schema](https://standardschema.dev) (zod,
+valibot, arktype, ...). `t.citext()` needs `CREATE EXTENSION citext` on
+postgres (see [migrations](#migrations)).
+
+### Custom types
 
 ```ts
-import * as sqlite from '@rwillians/exto/bun-sqlite';
-import * as pg from '@rwillians/exto/bun-postgres';
+import { defineType } from '@rwillians/exto';
+import { z } from 'zod';
 
-const db = sqlite.connect(':memory:');
-const db = pg.connect('postgres://user:pass@localhost:5432/app');
+const email = () => defineType({ primitive: 'STRING', schema: z.email() });
 
-// log every statement
-const db = sqlite.connect(':memory:', { loggers: [console] });
+const users = table('users', {
+  id: t.uuidv7().generated().primaryKey(),
+  email: email(),
+});
 ```
 
 
@@ -138,52 +146,48 @@ const migrate = defineMigrations({
   },
   '0002': async (db) => {
     await create.table(tasks).onto(db);
-    await create.index(tasks, ['status', 'scheduledAt']).onto(db);
+    await create.index(tasks, ['status', 'scheduledTo']).onto(db);
   },
 });
 
 await migrate(db);
 ```
 
-Migrations run in key order, each in its own transaction, and only once.
+Migrations run in key order, each in its own transaction, and only once:
+applied ones are tracked in the `schema_migrations` table.
 
 
 ## Insert
 
 ```ts
-import { into } from '@rwillians/exto';
+import { into, parse } from '@rwillians/exto';
 
-const row = { status: 'queued', payload: {}, scheduledAt: new Date() } as const;
+const task: TaskInsert = { status: 'queued', payload: { kind: 'Prune' }, events: [] };
 
 const inserted: Task[] = await into(tasks)
-  .values(row)
-  .values([row, row])
+  .values(task)
+  .values([task, task])
   .insert(db);
 
-await into(tasks).values(row).insert(db, { returning: ['id'] }); // → { id: string }[]
-await into(tasks).values(row).insert(db, { returning: false });  // → undefined
+await into(tasks).values(task).insert(db, { returning: ['id', tasks.status] }); // → Pick<Task, 'id' | 'status'>[]
+await into(tasks).values(task).insert(db, { returning: false });                // → undefined
+
+// validate untrusted input, filling in defaults
+const row: TaskInsert = parse(tasks, JSON.parse(body));
 ```
 
 `insert`, `update` and `delete` all take `returning`. It defaults to `true`,
 except for `delete`, which defaults to `false`:
 
-| `returning` | result                    |
-| :---------- | :------------------------ |
-| `true`      | full rows                 |
-| `[...keys]` | only those fields         |
-| `false`     | `undefined`               |
+| `returning`            | result      |
+| :--------------------- | :---------- |
+| `true`                 | full rows   |
+| `[...keys or columns]` | only those  |
+| `false`                | `undefined` |
 
 ### On conflict
 
 ```ts
-const users = table('users', t => ({
-  id: t.sequence().primaryKey(),
-  email: t.citext().unique(),
-  name: t.string(),
-  logins: t.integer().default(0),
-  banned: t.boolean().default(false),
-}));
-
 const rows = [{ email: 'jane@example.com', name: 'Jane' }];
 
 // skip rows that conflict
@@ -212,53 +216,128 @@ await into(users).values(rows).insert(db, {
 
 ## Select
 
+A table is shaped like its columns: `tasks.status` references a column.
+
 ```ts
 import { expr, from } from '@rwillians/exto';
 
-const rows: Task[] = await from(tasks)
-  .where('status', '=', 'queued')
-  .where('scheduledAt', '<', new Date()) // multiple `where`s are ANDed
-  .orderBy(['scheduledAt', ['attempts', 'DESC']])
+const due: Task[] = await from(tasks)
+  .where(tasks.status, '=', 'queued')
+  .where(tasks.scheduledTo, '<', new Date()) // multiple `where`s are ANDed
+  .orderBy([tasks.scheduledTo, [tasks.attempts, 'DESC']])
   .limit(10)
   .offset(20)
   .all(db);
 
-const queued = from(tasks).where('status', '=', 'queued');
+const queued = from(tasks).where(tasks.status, '=', 'queued');
 
-await queued.one(db);                          // → Task | null (the top row)
-await queued.select(['id', 'status']).all(db); // → Pick<Task, 'id' | 'status'>[]
-await queued.exists(db);                       // → boolean
-await queued.count(db);                        // → number
+await queued.one(db);    // → Task | null
+await queued.exists(db); // → boolean
+await queued.count(db);  // → number
 ```
 
-| operator                               | value                      |
-| :------------------------------------- | :------------------------- |
-| `'='` `'!='` `'<'` `'<='` `'>'` `'>='` | the column's type          |
-| `'like'` `'not like'`                  | `string`                   |
-| `'in'` `'not in'`                      | array of the column's type |
-| `'is'` `'is not'`                      | `null`                     |
+| operator                               | value             |
+| :------------------------------------- | :---------------- |
+| `'='` `'!='` `'<'` `'<='` `'>'` `'>='` | the column's type |
+| `'is'` `'is not'`                      | `null`            |
+
+### Picking columns
+
+```ts
+await from(tasks).select({ id: tasks.id, when: tasks.scheduledTo }).all(db);
+// → { id: string, when: Date }[]
+
+await from(tasks).select({ ...tasks, parent: tasks.parentId }).all(db);
+// → (Task & { parent: string | null })[]
+```
+
+### Comparing columns
+
+```ts
+await from(tasks).where(tasks.attempts, '<', tasks.maxAttempts).all(db);
+```
 
 ### OR and grouping
 
 ```ts
 await from(tasks)
   .where(expr.or([
-    expr('status', '=', 'queued'),
+    expr(tasks.status, '=', 'queued'),
     expr.and([
-      expr('status', '=', 'running'),
-      expr('attempts', '>', 3),
+      expr(tasks.status, '=', 'running'),
+      expr(tasks.attempts, '>', 3),
     ]),
   ]))
   .all(db);
-// WHERE ("status" = ? OR ("status" = ? AND "attempts" > ?))
 ```
 
+### Embedded fields
+
+Fields of `embedded.one()` columns are referenced like columns:
+
+```ts
+await from(tasks)
+  .where(tasks.payload.kind, '=', 'Prune')
+  .select({ kind: tasks.payload.kind, params: tasks.payload.params })
+  .all(db);
+// → { kind: string, params: Record<string, unknown> }[]
+```
+
+### Raw SQL fragments
+
+```ts
+import { f } from '@rwillians/exto';
+
+await from(tasks).where(f`upper(${tasks.payload.kind})`, '=', 'PRUNE').all(db);
+```
+
+Interpolated columns are rendered in place, and any other value is passed as
+a parameter.
+
+
+## Group by
+
+```ts
+await from(tasks)
+  .where(tasks.status, '!=', 'queued')
+  .groupBy([tasks.status])
+  .select({
+    status: tasks.status,
+    tasks: expr.count(tasks.id),
+    attempts: expr.sum(tasks.attempts),
+  })
+  .all(db);
+// → { status: Task['status'], tasks: number, attempts: number }[]
+```
+
+
+## Joins
+
+Alias a table to query it more than once:
+
+```ts
+const parent = tasks.as('parent');
+const child = tasks.as('child');
+
+await from(parent)
+  .leftJoin(child, expr(parent.id, '=', child.parentId))
+  .where(parent.parentId, 'is', null)
+  .groupBy([parent.id])
+  .select({ ...parent, children: expr.count(child.id) })
+  .all(db);
+// → (Task & { children: number })[]
+```
+
+Columns of a left-joined table are nullable: selecting `child.id` gives
+`string | null`. A query only takes columns of the tables it reads from, so
+referencing `child` before joining it is a type error.
+
 
 ## Update
 
 ```ts
 const updated: Pick<Task, 'id'>[] = await from(tasks)
-  .where('status', '=', 'queued')
+  .where(tasks.status, '=', 'queued')
   .update(db, {
     set: { status: 'running' },
     inc: { attempts: 1 },
@@ -270,12 +349,12 @@ const updated: Pick<Task, 'id'>[] = await from(tasks)
 ## Delete
 
 ```ts
-await from(tasks).where('status', '=', 'done').delete(db); // → undefined
-await from(tasks).where('status', '=', 'done').delete(db, { returning: true }); // → Task[]
+await from(tasks).where(tasks.status, '=', 'done').delete(db);                      // → undefined
+await from(tasks).where(tasks.status, '=', 'done').delete(db, { returning: true }); // → Task[]
 ```
 
-`update` and `delete` refuse `orderBy`, `limit` and `offset`, so they never
-touch more rows than the query suggests.
+`update` and `delete` refuse joins, `groupBy`, `orderBy`, `limit` and
+`offset`, so they never touch more rows than the query suggests.
 
 
 ## Transactions
@@ -295,53 +374,28 @@ The transaction rolls back if the callback throws.
 
 ## Validation
 
-Rows and changes are validated against the columns before any SQL runs:
-
 ```ts
 import { ValidationError } from '@rwillians/exto';
 
-const people = table('people', t => ({
-  id: t.sequence().primaryKey(),
+const people = table('people', {
+  id: t.uuidv7().generated().primaryKey(),
   name: t.string({ size: 5 }),
   age: t.integer(),
-}));
+});
 
 try {
   await into(people).values({ name: 'Jane Doe', age: 1.5 }).insert(db);
 } catch (error) {
   if (error instanceof ValidationError) {
     error.message; // Failed validation:
-                   //   - 0.name: must be at most 5 characters long
-                   //   - 0.age: must be an integer
-    error.issues;  // [{ message, path: [0, 'name'] }, ...]
+                   //   - name: must be at most 5 characters long
+                   //   - age: must be an integer
+    error.issues;  // [{ message, path: ['name'] }, ...]
   }
 }
 ```
 
 
-## Not supported yet
-
-exto is young, and it focuses on queries against a single table. Every query
-reads from one table only, so joins aren't possible yet. Neither is nesting one
-query inside another, whether as a subquery (`WHERE id IN (SELECT ...)`) or as
-a common table expression (`WITH ... SELECT`).
-
-Selects return columns as they're stored: `.select()` takes column keys only,
-so computed values such as `attempts * 2` can't be selected. Aggregation stops
-at `.count()`, too. There's no `.groupBy()` to group rows, and no `.having()`
-to filter those groups.
-
-All of these are planned. Until then, `db.execute()` runs raw SQL and returns
-the rows as the driver gives them, without exto's decoding:
-
-```ts
-const totals = await db.execute(
-  'SELECT status, COUNT(*) AS total FROM tasks GROUP BY status',
-  [],
-);
-```
-
-
 ## License
 
 [MIT](LICENSE)

package/dist/cjs/bun-postgres.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dialect = exports.connect = void 0;
+const bun_1 = require("bun");
+const TYPES = {
+    BIGINT: () => 'BIGINT',
+    BINARY: () => 'BYTEA',
+    BOOLEAN: () => 'BOOLEAN',
+    CITEXT: () => 'CITEXT',
+    DATE: () => 'DATE',
+    DECIMAL: ({ precision, scale }) => precision !== undefined && scale !== undefined ? `NUMERIC(${precision}, ${scale})` : 'NUMERIC',
+    FLOAT: () => 'DOUBLE PRECISION',
+    INTEGER: () => 'BIGINT',
+    JSON: () => 'JSONB',
+    SEQUENCE: () => 'BIGINT',
+    STRING: ({ length = 255 }) => `VARCHAR(${length})`,
+    TEXT: () => 'TEXT',
+    TIMESTAMP: () => 'TIMESTAMPTZ',
+    UUID: () => 'UUID',
+};
+const identity = () => ({
+    encode: (value) => value,
+    decode: (value) => value,
+});
+// Bun.SQL reads bigints (BIGINT columns, COUNT and SUM) and NUMERICs as
+// strings
+const numeric = {
+    encode: (value) => value,
+    decode: (value) => Number(value),
+};
+// `#>>` reads text, so fields of other types are cast back to theirs
+const CASTS = {
+    BIGINT: 'BIGINT',
+    BOOLEAN: 'BOOLEAN',
+    DECIMAL: 'NUMERIC',
+    FLOAT: 'DOUBLE PRECISION',
+    INTEGER: 'DOUBLE PRECISION',
+    SEQUENCE: 'BIGINT',
+};
+const jsonPath = (path) => `'{${path.map(key => `"${key.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\'', '\'\'')}"`).join(',')}}'`;
+const json = (sql, path, type) => {
+    if (type === 'JSON')
+        return `${sql} #> ${jsonPath(path)}`;
+    const text = `${sql} #>> ${jsonPath(path)}`;
+    return CASTS[type] ? `(${text})::${CASTS[type]}` : text;
+};
+// Bun.SQL sends objects and arrays as JSON, and reads JSONB already parsed
+const dialect = {
+    name: 'postgres',
+    placeholder: (index) => `$${index}`,
+    type: (col) => TYPES[col.type](col),
+    generated: (col) => col.type === 'SEQUENCE'
+        ? 'GENERATED ALWAYS AS IDENTITY'
+        : undefined,
+    json,
+    codecs: {
+        BIGINT: { encode: (value) => value, decode: (value) => BigInt(value) },
+        BINARY: { encode: (value) => value, decode: (value) => new Uint8Array(value) },
+        BOOLEAN: identity(),
+        CITEXT: identity(),
+        DATE: { encode: (value) => value, decode: (value) => value instanceof Date ? value.toISOString().slice(0, 10) : value },
+        DECIMAL: numeric,
+        FLOAT: numeric,
+        INTEGER: numeric,
+        JSON: identity(),
+        SEQUENCE: numeric,
+        STRING: identity(),
+        TEXT: identity(),
+        TIMESTAMP: { encode: (value) => value, decode: (value) => new Date(value) },
+        UUID: identity(),
+    },
+};
+exports.dialect = dialect;
+class BunPostgres {
+    sql;
+    loggers;
+    inTransaction;
+    dialect = dialect;
+    constructor(sql, loggers = [], inTransaction = false) {
+        this.sql = sql;
+        this.loggers = loggers;
+        this.inTransaction = inTransaction;
+    }
+    async execute(sql, params) {
+        return await this.sql.unsafe(sql, params);
+    }
+    async close() {
+        await this.sql.close();
+    }
+    // nested transactions are savepoints of the outer one
+    async transaction(fn) {
+        const callback = (tx) => fn(new BunPostgres(tx, this.loggers, true));
+        const result = this.inTransaction
+            ? this.sql.savepoint(callback)
+            : this.sql.begin(callback);
+        return await result;
+    }
+}
+const connect = (url, { loggers = [] } = {}) => new BunPostgres(new bun_1.SQL(url), loggers);
+exports.connect = connect;