flint-orm 0.3.0 → 0.4.0

package/README.md

@@ -1,238 +1,341 @@
-# flint-orm
+# Flint ORM
 
-A minimal, type-safe SQLite ORM. One dialect, one runtime, no abstraction overhead.
+A type-safe SQLite ORM for JavaScript. One schema, any driver.
 
-## Why
+## Features
 
-Drizzle is great, but its execution layer (`drizzle-kit migrate`) wasn't built for dynamic, multi-tenant, per-request-connection contexts. Flint is narrower by design: SQLite/libSQL only, no multi-dialect abstraction, no pluggable drivers — just a query builder that does exactly what SQLite supports.
+- **Driver-agnostic** — use `bun:sqlite`, `better-sqlite3`, `@libsql/client`, `@tursodatabase/database`, or `@tursodatabase/sync`
+- **Type-safe queries** — full TypeScript inference for results, inserts, and updates
+- **Schema-first migrations** — define tables in code, generate and apply migrations
+- **Fluent query builder** — chainable API for SELECT, INSERT, UPDATE, DELETE, and JOINs
+- **Aggregate functions** — count, sum, avg, min, max with type inference
+- **Zero runtime dependencies** on the core — drivers are opt-in per subpath
 
 ## Install
 
 ```bash
-npm install flint-orm
 bun add flint-orm
+# or
+npm install flint-orm
 ```
 
 ## Quick Start
 
 ```ts
-import { flint, table, text, integer, eq } from 'flint-orm';
+import { flint } from 'flint-orm/bun-sqlite';
+import { table, text, integer, date } from 'flint-orm/table';
+import { eq, and } from 'flint-orm/expressions';
 
+// Define schema
 const users = table('users', {
   id: text('id').primaryKey(),
   name: text('name').notNull(),
   email: text('email').unique(),
   age: integer('age'),
+  createdAt: date('created_at').defaultNow(),
 });
 
-const db = flint({ url: 'app.db' });
+// Connect
+const db = flint({ url: './app.db' });
 
 // Insert
-db.insert(users).values({ id: 'u1', name: 'Alice', email: 'alice@example.com' }).execute();
+await db.insert(users).values({ id: 'u1', name: 'Alice', email: 'alice@example.com' }).execute();
 
 // Query
-const user = db.select().from(users).where(eq(users.id, 'u1')).single().execute();
-// { id: "u1", name: "Alice", email: "alice@example.com", age: null }
+const adults = await db.select().from(users).where(eq(users.age, 18)).execute();
+//    ^? { id: string; name: string; email: string; age: number; createdAt: Date }[]
 
-// Update
-db.update(users).set({ name: 'Alice Updated' }).where(eq(users.id, 'u1')).execute();
-
-// Delete
-db.delete(users).where(eq(users.id, 'u1')).execute();
+// Single row
+const alice = await db.select().from(users).where(eq(users.id, 'u1')).single().execute();
+//    ^? { id: string; name: string; email: string; age: number; createdAt: Date } | null
 ```
 
-## Features
+## Schema Definition
 
-### Schema
+### Columns
 
 ```ts
-import { table, text, integer, boolean, json, date, real, index } from 'flint-orm';
+import { table, text, integer, boolean, real, json, date, index } from 'flint-orm/table';
+
+const posts = table('posts', {
+  id: text('id').primaryKey(),
+  title: text('title').notNull(),
+  body: text('body'),
+  published: boolean('published').default(false),
+  views: integer('views').default(0).autoIncrement(),
+  price: real('price'),
+  metadata: json('metadata').default({}),
+  createdAt: date('created_at').defaultNow(),
+  updatedAt: date('updated_at').onUpdateTimestamp(),
+});
+```
 
+### Modifiers
+
+- `.primaryKey()` — mark as primary key
+- `.notNull()` — disallow NULL values
+- `.unique()` — add unique constraint
+- `.default(value)` — static default value
+- `.defaultFn(fn)` — dynamic default (called on insert when value is omitted)
+- `.references(target)` — foreign key reference
+- `.autoIncrement()` — integer auto-increment (integer columns only)
+- `.defaultNow()` — use `Date.now()` as default (date columns only)
+- `.onUpdateTimestamp()` — always set to `Date.now()` on update (date columns only)
+
+### Indexes
+
+```ts
 const users = table(
   'users',
   {
     id: text('id').primaryKey(),
-    name: text('name').notNull(),
-    email: text('email').unique(),
-    active: boolean('active').default(true),
-    metadata: json('metadata'),
-    createdAt: date('createdAt').defaultNow().onUpdate(),
-    score: real('score'),
-    age: integer('age'),
-    orgId: text('orgId').references(orgs.id),
+    email: text('email'),
+    name: text('name'),
   },
-  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_org').on(t.orgId)],
+  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_name').on(t.name)],
 );
 ```
 
-| Type      | TS Type   | SQLite  | Modifiers                                                                 |
-| --------- | --------- | ------- | ------------------------------------------------------------------------- |
-| `text`    | `string`  | TEXT    | `.primaryKey()`, `.notNull()`, `.unique()`, `.default()`, `.references()` |
-| `integer` | `number`  | INTEGER | `.autoIncrement()`                                                        |
-| `boolean` | `boolean` | INTEGER | Encodes 0/1                                                               |
-| `json<T>` | `T`       | TEXT    | JSON encode/decode                                                        |
-| `date`    | `Date`    | INTEGER | `.defaultNow()`, `.onUpdate()`                                            |
-| `real`    | `number`  | REAL    |                                                                           |
+### Type Inference
+
+```ts
+import type { InferRow, InsertRow } from 'flint-orm/table';
+
+type User = InferRow<typeof users>;
+// { id: string; name: string; email: string | null; age: number | null; createdAt: Date }
+
+type NewUser = InsertRow<typeof users>;
+// { id: string; name: string; email?: string | null; age?: number | null; createdAt?: Date }
+```
+
+`InsertRow` makes columns with auto-defaults (`integer`, `date`) optional.
 
-### Query Builder
+## Queries
 
-Two-phase builders prevent invalid queries at compile time:
+### SELECT
 
 ```ts
-// SELECT
-db.select().from(users).columns(['id', 'name']).where(eq(users.active, true)).orderBy('name').limit(10).execute();
+// All rows
+const all = await db.select().from(users).execute();
 
-// INSERT
-db.insert(users).values({ id: 'u1', name: 'Alice' }).returning().execute();
+// With conditions
+const active = await db.select().from(users).where(eq(users.active, true)).execute();
 
-// UPSERT
-db.insert(users)
-  .values({ id: 'u1', name: 'Alice' })
-  .onConflictDoUpdate({ target: users.id, set: { name: 'Bob' } })
-  .execute();
+// Narrow columns
+const names = await db.select().from(users).columns(['id', 'name']).execute();
+//    ^? { id: string; name: string }[]
 
-// UPDATE
-db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning().execute();
+// Single row
+const user = await db.select().from(users).where(eq(users.id, 'u1')).single().execute();
+//    ^? { ... } | null
 
-// DELETE
-db.delete(users).where(eq(users.id, 'u1')).returning().execute();
+// Ordering and pagination
+const page = await db.select().from(users).orderBy('name', 'asc').limit(10).offset(20).execute();
+
+// Distinct
+const unique = await db.select().from(users).columns(['email']).distinct().execute();
 ```
 
-### Joins
+### INSERT
 
 ```ts
-const orders = table('orders', {
-  id: text('id').primaryKey(),
-  userId: text('userId').references(users.id),
-  total: integer('total').notNull(),
-});
+// Single row
+await db.insert(users).values({ id: 'u1', name: 'Alice', email: 'alice@example.com' }).execute();
+
+// Multiple rows
+await db
+  .insert(users)
+  .values([
+    { id: 'u1', name: 'Alice' },
+    { id: 'u2', name: 'Bob' },
+  ])
+  .execute();
 
-// Left join — nested result shape
-const result = db.leftJoin(orders).on(users).execute();
-// [{ id: "u1", name: "Alice", __children: [{ id: "o1", total: 100 }] }]
+// Return inserted rows
+const inserted = await db.insert(users).values({ id: 'u1', name: 'Alice' }).returning().execute();
+//    ^? { id: string; name: string; ... }[]
+
+// Upsert
+await db
+  .insert(users)
+  .values({ id: 'u1', name: 'Alice' })
+  .onConflictDoUpdate({ target: users.id, set: { name: 'Alice' } })
+  .execute();
 
-// Multi-join
-db.leftJoin(orders).on(users).leftJoin(orderItems).on(orders).execute();
+// Ignore conflicts
+await db.insert(users).values({ id: 'u1', name: 'Alice' }).onConflictDoNothing().execute();
 ```
 
-### Aggregates
+### UPDATE
 
 ```ts
-db.count(users);
-db.sum(orders, orders.total);
-db.avg(orders, orders.total, eq(orders.userId, 'u1'));
+await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).execute();
+
+// Return updated rows
+const updated = await db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning().execute();
 ```
 
-### Batch
+### DELETE
 
 ```ts
-db.batch([db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }), db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1'))]);
+await db.delete(users).where(eq(users.id, 'u1')).execute();
+
+// Return deleted rows
+const deleted = await db.delete(users).where(eq(users.id, 'u1')).returning().execute();
 ```
 
-### Raw SQL
+### JOINs
 
 ```ts
-db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
+// Auto-join via foreign key (posts.userId references users.id)
+const postsWithAuthors = await db.leftJoin(users).on(posts).execute();
+
+// Explicit join condition
+const result = await db.leftJoin(users).on(posts, eq(posts.userId, users.id)).execute();
+
+// Chain multiple joins
+const complex = await db
+  .leftJoin(users)
+  .on(posts, eq(posts.userId, users.id))
+  .on(comments, eq(comments.postId, posts.id))
+  .where(eq(users.id, 'u1'))
+  .execute();
+
+// Inner join
+const inner = await db.innerJoin(users).on(posts).execute();
 ```
 
-## Conditions
+Join results are nested — each joined table's data appears under its table name:
 
 ```ts
-import { eq, neq, gt, gte, lt, lte, and, or, isIn, isNotIn, isNull, isNotNull, like, glob, between } from 'flint-orm';
-
-db.select()
-  .from(users)
-  .where(and(eq(users.active, true), gt(users.age, 18)))
-  .execute();
+// result shape: { id: string; name: string; posts: { id: string; title: string }[] }
 ```
 
-## Types
+### Aggregates
 
 ```ts
-import type { InferRow, InsertRow } from 'flint-orm';
-
-type UserRow = InferRow<typeof users>;
-type UserInsert = InsertRow<typeof users>; // defaults are optional
+const total = await db.count(users);
+const activeCount = await db.count(users, eq(users.active, true));
+const totalViews = await db.sum(posts, posts.views);
+const avgAge = await db.avg(users, users.age);
+const minAge = await db.min(users, users.age);
+const maxAge = await db.max(users, users.age);
 ```
 
-## Migration System
+### Batch (Transactions)
 
-### CLI
+```ts
+await db.batch([db.insert(users).values({ id: 'u1', name: 'Alice' }), db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' })]);
+```
 
-```bash
-# Generate migration from schema changes
-flint generate --name init_schema
+### Raw SQL
 
-# Preview SQL without writing files
-flint generate --preview
+```ts
+import { sql } from 'flint-orm';
 
-# Apply pending migrations
-flint migrate
+const expr = sql`name = ${'Alice'} AND age > ${18}`;
+const result = await db.select().from(users).where(expr).execute();
 
-# Check status
-flint migrate --status
+// Direct execution
+await db.$run('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
 ```
 
-### Config
+## Conditions
+
+All conditions are composable with `and()` and `or()`:
 
 ```ts
-// flint.config.ts
-import { defineConfig } from 'flint-orm/config';
+import { eq, neq, gt, gte, lt, lte, and, or, isIn, isNotIn, isNull, isNotNull, like, glob, between } from 'flint-orm/expressions';
 
-export default defineConfig({
-  schema: './src/schema',
-  migrations: './flint',
-  database: { url: './app.db' },
-});
-```
+// Equality
+eq(users.name, 'Alice');
+eq(posts.userId, users.id); // column-to-column comparison
 
-### How It Works
+// Comparisons
+gt(users.age, 18);
+gte(users.age, 18);
+lt(users.age, 65);
+lte(users.age, 65);
+neq(users.id, 'excluded');
 
-1. `flint generate` serializes your `table()` definitions, diffs against the last snapshot, and writes a migration folder with TypeScript operations
-2. `flint migrate` reads pending migration folders, executes SQL via `batch()` (atomic), and records applied migrations in `__flint_migrations`
-3. Tables are topologically sorted by foreign key dependencies (Kahn's algorithm) — referenced tables are created first
+// Logical
+and(eq(users.active, true), gt(users.age, 18));
+or(eq(users.role, 'admin'), eq(users.role, 'moderator'));
 
-### Programmatic
+// Sets
+isIn(users.id, ['u1', 'u2', 'u3']);
+isNotIn(users.id, ['excluded']);
 
-```ts
-import { generate, migrate, getMigrationStatus, serializeSchema, diffSchemas, generateSQL } from 'flint-orm/migration';
-```
+// Null checks
+isNull(users.deletedAt);
+isNotNull(users.email);
 
-## CLI
+// Pattern matching
+like(users.name, 'A%'); // SQL LIKE (% = any characters, _ = single char)
+glob(users.name, 'A*'); // SQL GLOB (* = any characters, ? = single char)
 
+// Range
+between(users.age, 18, 65);
 ```
-flint <command> [options]
 
-Commands:
-  generate   Generate a new migration from schema changes
-  migrate    Apply pending migrations
-  status     Show migration status
+## Migrations
 
-Options:
-  --name, -n    Migration name
-  --preview, -p Show SQL without writing files
-  --status      Show which migrations are pending/applied
-```
+Flint uses schema-first migrations. Define your tables in code, and the CLI generates migration files from the diff.
 
-## Error Handling
+### Setup
 
 ```ts
-import { FlintValidationError, FlintQueryError } from 'flint-orm';
+// flint.config.ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  driver: 'bun-sqlite',
+  database: {
+    url: './app.db',
+  },
+  schema: './src/schema',
+  migrations: './flint',
+});
 ```
 
-| Error                  | When                          |
-| ---------------------- | ----------------------------- |
-| `FlintValidationError` | Invalid query construction    |
-| `FlintQueryError`      | Runtime SQL execution failure |
+### Generate
+
+```bash
+flint generate              # auto-detect changes
+flint generate --name init  # name the migration
+flint generate --preview    # dry run, show SQL without writing
+```
 
-## Philosophy
+### Apply
 
-- **SQLite only** — no multi-dialect abstraction, no driver plugins
-- **Type-safe by construction** — two-phase builders, phantom types, `InferRow<T>`
-- **Immutable** — every chain method returns a new instance
-- **No classes** — functions and plain objects only
-- **Parameterized** — all queries use `?` placeholders, never string interpolation
+```bash
+flint migrate               # apply pending migrations
+flint migrate --status      # show applied vs pending
+flint migrate --dry-run     # show what would run
+```
 
-## License
+### How It Works
 
-MIT
+1. `flint generate` serializes your `table()` definitions to JSON
+2. Diffs against the last migration's `state.json`
+3. Detects adds, drops, renames, and safe modifications
+4. Prompts to confirm potential renames
+5. Writes a migration folder with `migration.ts` (operations) + `state.json` (snapshot)
+6. `flint migrate` reads pending migrations and executes them in order
+
+Unsafe changes (type changes, primary key changes) throw an error and must be handled manually.
+
+## Subpath Imports
+
+| Import                     | What's in it                                                    |
+| -------------------------- | --------------------------------------------------------------- |
+| `flint-orm/bun-sqlite`     | `flint()` factory for bun:sqlite                                |
+| `flint-orm/better-sqlite3` | `flint()` factory for better-sqlite3                            |
+| `flint-orm/libsql`         | `flint()` factory for @libsql/client                            |
+| `flint-orm/libsql-web`     | `flint()` factory for @libsql/client/web                        |
+| `flint-orm/turso`          | `flint()` factory for @tursodatabase/database                   |
+| `flint-orm/turso-sync`     | `flint()` factory for @tursodatabase/sync                       |
+| `flint-orm/table`          | `table()`, column constructors, index builder, type utilities   |
+| `flint-orm/expressions`    | `eq`, `and`, `or`, `gt`, `like`, and all condition helpers      |
+| `flint-orm/config`         | `defineConfig()`                                                |
+| `flint-orm/migration`      | `generate()`, `migrate()`, `serializeSchema()`, `diffSchemas()` |