flint-orm 0.2.0 → 0.3.0

package/API.md

@@ -33,12 +33,12 @@ const user = db.select().from(users).where(eq(users.id, 'u1')).single().execute(
 
 ## Schema
 
-### `table(name, columns)`
+### `table(name, columns, indexFn?)`
 
 Define a table. Columns live as direct properties. SQL metadata is under `._`.
 
 ```ts
-import { table, text, integer, boolean } from 'flint-orm';
+import { table, text, integer, boolean, index } from 'flint-orm';
 
 const users = table('users', {
   id: text('id').primaryKey(),
@@ -49,7 +49,7 @@ const users = table('users', {
 });
 ```
 
-### `snakeCase.table(name, columns)`
+### `snakeCase.table(name, columns, indexFn?)`
 
 Auto-converts camelCase keys to snake_case SQL names.
 
@@ -122,6 +122,28 @@ type UserInsert = InsertRow<typeof users>;
 
 ---
 
+## Indexes
+
+### `index(name).on(columns).unique()`
+
+Define indexes via the table callback. Chainable API.
+
+```ts
+const users = table(
+  'users',
+  {
+    id: text('id').primaryKey(),
+    email: text('email'),
+    name: text('name'),
+  },
+  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_name').on(t.name), index('idx_users_email_name').on(t.email, t.name)],
+);
+```
+
+The callback receives the table definition and returns an array of `IndexBuilder` objects. Indexes are attached to the table automatically and serialized for migrations.
+
+---
+
 ## Query Builder
 
 ### `db.select().from(table)`
@@ -333,7 +355,7 @@ const deleted = db.delete(users).where(eq(users.id, 'u1')).returning(['id', 'nam
 
 ### `db.leftJoin(parent).on(child, condition?)`
 
-LEFT JOIN. Returns all parent rows, with matching child data or null.
+LEFT JOIN. Returns all parent rows, with matching child data nested under `__children`.
 
 ```ts
 const orders = table('orders', {
@@ -367,7 +389,7 @@ Joins return **nested** results, not flat-merged:
   {
     id: 'u1',
     name: 'Alice',
-    orders: [
+    __children: [
       { id: 'o1', userId: 'u1', total: 100 },
       { id: 'o2', userId: 'u1', total: 200 },
     ],
@@ -381,14 +403,23 @@ Narrow parent columns with `.columns()`:
 
 ```ts
 db.leftJoin(orders).on(users, eq(orders.userId, users.id)).columns(['id', 'name']).execute();
-// Returns: { id: string; name: string; orders: OrderRow[] }[]
+// Returns: { id: string; name: string; __children: OrderRow[] }[]
 ```
 
 ### `.single()` on Joins
 
 ```ts
 db.leftJoin(orders).on(users, eq(orders.userId, users.id)).single().execute();
-// Returns: { id: string; name: string; orders: OrderRow[] } | null
+// Returns: { id: string; name: string; __children: OrderRow[] } | null
+```
+
+### Multi-Join
+
+Chain multiple joins:
+
+```ts
+db.leftJoin(orders).on(users).leftJoin(orderItems).on(orders).execute();
+// Returns nested: { ...userFields, __children: [{ ...orderFields, __children: [...items] }] }
 ```
 
 ---
@@ -557,14 +588,21 @@ All queries succeed or all roll back.
 
 ## Raw SQL
 
-Access the underlying `bun:sqlite` client directly for raw queries.
+### `db.$run(sql, ...params)`
+
+Execute raw SQL directly against the database.
 
 ```ts
-// Simple query
-const users = db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
+db.$run('CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT)');
+db.$run('INSERT INTO test VALUES (?, ?)', 1, 'Alice');
+```
+
+### `db.$client`
 
-// With type annotation
-const rows = db.$client.prepare('SELECT count(*) as cnt FROM users').all() as { cnt: number }[];
+Direct access to the underlying `bun:sqlite` client.
+
+```ts
+const rows = db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
 ```
 
 ---
@@ -579,20 +617,142 @@ import { sql } from 'flint-orm';
 const expr = sql`SELECT * FROM users WHERE name = ${'Alice'} AND age > ${18}`;
 // { sql: "SELECT * FROM users WHERE name = ? AND age > ?", params: ["Alice", 18] }
 
-// Execute with db.$client
+// Use with db.$client
 const rows = db.$client.prepare(expr.sql).all(...expr.params);
 ```
 
 ---
 
-## Escape Hatch
+## Migration System
+
+### `flint generate` (CLI)
+
+Generate a migration from schema changes.
+
+```bash
+# Generate migration
+flint generate --name init_schema
+
+# Preview SQL without writing files
+flint generate --name init_schema --preview
+```
+
+### `flint migrate` (CLI)
+
+Apply pending migrations to the database.
+
+```bash
+# Apply all pending migrations
+flint migrate
+
+# Show which migrations are pending/applied
+flint migrate --status
+```
+
+### Config
+
+Create `flint.config.ts` in your project root:
+
+```ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  schema: './src/schema', // folder or file with table() definitions
+  migrations: './flint', // where migration folders are stored
+  database: {
+    url: './app.db', // SQLite database path
+  },
+});
+```
+
+### Programmatic API
+
+```ts
+import { generate, migrate, getMigrationStatus, serializeSchema, diffSchemas, generateSQL } from 'flint-orm/migration';
+
+// Serialize table definitions to JSON
+const state = serializeSchema([users, orders]);
+
+// Diff two schema states
+const operations = diffSchemas(previousState, currentState);
+
+// Generate SQL from operations
+const sql = generateSQL(operations);
+
+// Generate a migration folder
+const result = generate([users, orders], './flint', 'init_schema');
+
+// Apply pending migrations
+const result = migrate({ url: './app.db' }, './flint');
+
+// Check migration status
+const status = getMigrationStatus(client, './flint');
+```
+
+### Migration Operations
+
+Named, pre-vetted operations:
+
+```ts
+import { addTable, dropTable, renameTable, addColumn, dropColumn, renameColumn, createIndex, dropIndex } from 'flint-orm/migration';
+```
+
+| Operation      | SQL Generated                          |
+| -------------- | -------------------------------------- |
+| `addTable`     | `CREATE TABLE ...`                     |
+| `dropTable`    | `DROP TABLE ...`                       |
+| `renameTable`  | `ALTER TABLE ... RENAME TO ...`        |
+| `addColumn`    | `ALTER TABLE ... ADD COLUMN ...`       |
+| `dropColumn`   | `ALTER TABLE ... DROP COLUMN ...`      |
+| `renameColumn` | `ALTER TABLE ... RENAME COLUMN ... TO` |
+| `createIndex`  | `CREATE [UNIQUE] INDEX ...`            |
+| `dropIndex`    | `DROP INDEX ...`                       |
+
+### Migration File Shape
+
+```ts
+import { defineMigration } from 'flint-orm/migration';
+import { addTable, addColumn } from 'flint-orm/migration';
+
+export default defineMigration({
+  name: 'init_schema',
+  operations: [
+    addTable({ name: 'users', columns: [...], indexes: [...] }),
+    addColumn('users', { name: 'email', sqlType: 'text', ... }),
+  ],
+});
+```
+
+### Tracking
+
+Applied migrations are recorded in `__flint_migrations` (per-database). The table is created on first `migrate()` call — never with `IF NOT EXISTS`.
+
+### FK Ordering
+
+Tables are topologically sorted (Kahn's algorithm) before generating `CREATE TABLE` statements. Referenced tables are created first.
+
+---
+
+## SQLite Introspection
 
-Access the underlying `bun:sqlite` client directly.
+### `introspectSchema(client)`
+
+Read the live database schema and return a `SchemaState` that can be diffed against code-defined tables.
 
 ```ts
-db.$client; // Database instance
+import { introspectSchema } from 'flint-orm/sqlite';
+import { diffSchemas } from 'flint-orm/migration';
+
+const client = new Database('./app.db');
+const liveState = introspectSchema(client);
+
+// Compare live DB against code schema
+const codeState = serializeSchema([users, orders]);
+const operations = diffSchemas(liveState, codeState);
 ```
 
+Normalizes SQLite type aliases (VARCHAR → TEXT, BIGINT → INTEGER, etc.) and parses default values.
+
 ---
 
 ## Types
@@ -603,6 +763,8 @@ db.$client; // Database instance
 | `ColumnDef<T, S>`   | Column definition with phantom type `T` and storage class `S` |
 | `InferRow<T>`       | Derives row type from table definition                        |
 | `InsertRow<T>`      | Derives insert type (defaults are optional)                   |
+| `IndexDef`          | Index definition: `{ name, columns, unique }`                 |
+| `IndexBuilder`      | Chainable index builder: `.on(cols).unique()`                 |
 | `Condition`         | Condition node for WHERE clauses                              |
 | `Executable`        | Anything with a `.toSQL()` method (for `batch()`)             |
 | `ConnectionDetails` | `{ url: string }`                                             |

package/README.md

@@ -0,0 +1,238 @@
+# flint-orm
+
+A minimal, type-safe SQLite ORM. One dialect, one runtime, no abstraction overhead.
+
+## Why
+
+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.
+
+## Install
+
+```bash
+npm install flint-orm
+bun add flint-orm
+```
+
+## Quick Start
+
+```ts
+import { flint, table, text, integer, eq } from 'flint-orm';
+
+const users = table('users', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  email: text('email').unique(),
+  age: integer('age'),
+});
+
+const db = flint({ url: 'app.db' });
+
+// Insert
+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 }
+
+// Update
+db.update(users).set({ name: 'Alice Updated' }).where(eq(users.id, 'u1')).execute();
+
+// Delete
+db.delete(users).where(eq(users.id, 'u1')).execute();
+```
+
+## Features
+
+### Schema
+
+```ts
+import { table, text, integer, boolean, json, date, real, index } from 'flint-orm';
+
+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),
+  },
+  (t) => [index('idx_users_email').on(t.email).unique(), index('idx_users_org').on(t.orgId)],
+);
+```
+
+| 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    |                                                                           |
+
+### Query Builder
+
+Two-phase builders prevent invalid queries at compile time:
+
+```ts
+// SELECT
+db.select().from(users).columns(['id', 'name']).where(eq(users.active, true)).orderBy('name').limit(10).execute();
+
+// INSERT
+db.insert(users).values({ id: 'u1', name: 'Alice' }).returning().execute();
+
+// UPSERT
+db.insert(users)
+  .values({ id: 'u1', name: 'Alice' })
+  .onConflictDoUpdate({ target: users.id, set: { name: 'Bob' } })
+  .execute();
+
+// UPDATE
+db.update(users).set({ name: 'Bob' }).where(eq(users.id, 'u1')).returning().execute();
+
+// DELETE
+db.delete(users).where(eq(users.id, 'u1')).returning().execute();
+```
+
+### Joins
+
+```ts
+const orders = table('orders', {
+  id: text('id').primaryKey(),
+  userId: text('userId').references(users.id),
+  total: integer('total').notNull(),
+});
+
+// Left join — nested result shape
+const result = db.leftJoin(orders).on(users).execute();
+// [{ id: "u1", name: "Alice", __children: [{ id: "o1", total: 100 }] }]
+
+// Multi-join
+db.leftJoin(orders).on(users).leftJoin(orderItems).on(orders).execute();
+```
+
+### Aggregates
+
+```ts
+db.count(users);
+db.sum(orders, orders.total);
+db.avg(orders, orders.total, eq(orders.userId, 'u1'));
+```
+
+### Batch
+
+```ts
+db.batch([db.insert(orders).values({ id: 'o1', userId: 'u1', total: 100 }), db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1'))]);
+```
+
+### Raw SQL
+
+```ts
+db.$client.prepare('SELECT * FROM users WHERE id = ?').all('u1');
+```
+
+## Conditions
+
+```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();
+```
+
+## Types
+
+```ts
+import type { InferRow, InsertRow } from 'flint-orm';
+
+type UserRow = InferRow<typeof users>;
+type UserInsert = InsertRow<typeof users>; // defaults are optional
+```
+
+## Migration System
+
+### CLI
+
+```bash
+# Generate migration from schema changes
+flint generate --name init_schema
+
+# Preview SQL without writing files
+flint generate --preview
+
+# Apply pending migrations
+flint migrate
+
+# Check status
+flint migrate --status
+```
+
+### Config
+
+```ts
+// flint.config.ts
+import { defineConfig } from 'flint-orm/config';
+
+export default defineConfig({
+  schema: './src/schema',
+  migrations: './flint',
+  database: { url: './app.db' },
+});
+```
+
+### How It Works
+
+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
+
+### Programmatic
+
+```ts
+import { generate, migrate, getMigrationStatus, serializeSchema, diffSchemas, generateSQL } from 'flint-orm/migration';
+```
+
+## CLI
+
+```
+flint <command> [options]
+
+Commands:
+  generate   Generate a new migration from schema changes
+  migrate    Apply pending migrations
+  status     Show migration status
+
+Options:
+  --name, -n    Migration name
+  --preview, -p Show SQL without writing files
+  --status      Show which migrations are pending/applied
+```
+
+## Error Handling
+
+```ts
+import { FlintValidationError, FlintQueryError } from 'flint-orm';
+```
+
+| Error                  | When                          |
+| ---------------------- | ----------------------------- |
+| `FlintValidationError` | Invalid query construction    |
+| `FlintQueryError`      | Runtime SQL execution failure |
+
+## Philosophy
+
+- **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
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flint-orm",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "bin": {
     "flint": "./src/cli.ts"
   },
@@ -40,6 +40,10 @@
     "lint": "oxlint",
     "format": "oxfmt"
   },
+  "dependencies": {
+    "@clack/prompts": "1.7.0",
+    "picocolors": "1.1.1"
+  },
   "devDependencies": {
     "@types/bun": "1.3.14",
     "oxfmt": "0.57.0",

package/src/cli.ts

@@ -3,12 +3,15 @@
 // flint CLI — migration generation for flint-orm
 // ---------------------------------------------------------------------------
 
-import { parseArgs } from 'node:util';
+import { parseArgs, styleText } from 'node:util';
 import { statSync, readdirSync, existsSync, readFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import type { AnyTable, TableDef } from './schema/table.js';
 import type { SchemaState } from './migration/types.js';
+import { intro, outro, log, cancel, isCancel, select, pc, note } from './cli/ui.js';
+import { CancellationError } from './migration/diff.js';
+import type { RenamePrompt } from './migration/diff.js';
 
 // ---------------------------------------------------------------------------
 // Config loading
@@ -93,24 +96,22 @@ async function importTableFolder(folderPath: string): Promise<unknown[]> {
 async function cmdGenerate(args: ReturnType<typeof parseArgs>['values'], config: FlintConfig): Promise<void> {
   const name = typeof args.name === 'string' ? args.name : undefined;
   const preview = args.preview === true;
+  const promptRename: RenamePrompt = (message, options) => select({ message: pc.bold(message), options }) as Promise<string | symbol>;
 
-  console.log(`🔍 Discovering schema from: ${config.schema}`);
+  log.info(`Discovering schema from: ${config.schema}`);
   const tables = await discoverTables(config.schema);
 
   if (tables.length === 0) {
-    console.error('❌ No table() definitions found in schema path.');
+    cancel('No table() definitions found in schema path.');
     process.exit(1);
   }
 
-  console.log(`📦 Found ${tables.length} table(s):`);
-  for (const t of tables) {
-    console.log(`   - ${(t as Record<string, Record<string, unknown>>)._?.name ?? 'unknown'}`);
-  }
+  log.info(`Found ${tables.length} table(s): ${tables.map((t) => (t as Record<string, Record<string, unknown>>)._?.name ?? 'unknown').join(', ')}`);
 
   if (preview) {
     // Dynamic import of migration functions
     const { serializeSchema } = await import('./migration/serialize.js');
-    const { diffSchemas, emptyState } = await import('./migration/diff.js');
+    const { diffSchemas, emptyState, resolveRenames } = await import('./migration/diff.js');
     const { generateSQL } = await import('./migration/sql.js');
 
     // Find latest state
@@ -132,20 +133,20 @@ async function cmdGenerate(args: ReturnType<typeof parseArgs>['values'], config:
     if (!previousState) previousState = emptyState();
 
     const currentState = serializeSchema(tables as AnyTable[]);
-    const operations = diffSchemas(previousState, currentState);
+    const rawOps = diffSchemas(previousState, currentState);
 
-    if (operations.length === 0) {
-      console.log('\n✅ No changes detected — schema is already up to date.');
+    if (rawOps.length === 0) {
+      outro('Schema is already up to date.');
       return;
     }
 
+    // Resolve renames interactively
+    const operations = await resolveRenames(rawOps, { interactive: true, prompt: promptRename });
+
     const sql = generateSQL(operations);
-    const previewLabel = name ? `${name}` : 'unnamed';
-    console.log(`\n--- Preview: ${previewLabel} ---`);
-    console.log(`   Operations: ${operations.length}`);
-    console.log(`   Migrations dir: ${config.migrations}`);
-    console.log(`\n--- SQL ---\n${sql}\n`);
-    console.log('(dry run, no files written)');
+    log.info(`Operations: ${operations.length}`);
+    note(sql, 'SQL', { format: (text) => styleText('dim', text) });
+    log.info('(dry run, no files written)');
     return;
   }
 
@@ -153,13 +154,18 @@ async function cmdGenerate(args: ReturnType<typeof parseArgs>['values'], config:
   const { generate } = await import('./migration/generate.js');
 
   try {
-    const result = generate(tables as TableDef<any>[], resolve(process.cwd(), (config.migrations ?? './flint') as string), name);
-    console.log(`\n✅ Migration generated: ${result.folderName}`);
-    console.log(`   Operations: ${result.operations.length}`);
-    console.log(`\n--- SQL Preview ---\n${result.sql}`);
+    const migrationsDir = resolve(process.cwd(), config.migrations ?? './flint');
+    const result = await generate(tables as TableDef<any>[], migrationsDir, {
+      name,
+      interactive: true,
+      prompt: promptRename,
+    });
+    log.info(`Operations: ${result.operations.length}`);
+    note(result.sql, 'SQL', { format: (text) => styleText('dim', text) });
+    log.success(`Migration generated: ${migrationsDir}/${result.folderName}`);
   } catch (err: unknown) {
     if (err instanceof Error && err.message.includes('No changes detected')) {
-      console.log('\n✅ No changes detected — schema is already up to date.');
+      outro('Schema is already up to date.');
     } else {
       throw err;
     }
@@ -184,25 +190,25 @@ async function cmdMigrate(args: ReturnType<typeof parseArgs>['values'], config:
       const status = getMigrationStatus(db, migrationsDir);
 
       if (status.applied.length === 0 && status.pending.length === 0) {
-        console.log('✅ No migrations found.');
+        outro('No migrations found.');
         return;
       }
 
       if (status.applied.length > 0) {
-        console.log('\n📋 Applied migrations:');
+        log.info('Applied migrations:');
         for (const m of status.applied) {
-          console.log(`   ✓ ${m.name} (${m.folderName})`);
+          log.success(`${m.name} (${m.folderName})`);
         }
       }
 
       if (status.pending.length > 0) {
-        console.log('\n⏳ Pending migrations:');
+        log.warn('Pending migrations:');
         for (const m of status.pending) {
-          console.log(`   ○ ${m.name} (${m.folderName})`);
+          log.message(`  ○ ${m.name} (${m.folderName})`);
         }
       }
 
-      console.log(`\n   ${status.applied.length} applied, ${status.pending.length} pending`);
+      log.info(`${status.applied.length} applied, ${status.pending.length} pending`);
       return;
     }
 
@@ -212,16 +218,16 @@ async function cmdMigrate(args: ReturnType<typeof parseArgs>['values'], config:
     });
 
     if (result.applied.length === 0) {
-      console.log('\n✅ No pending migrations — database is up to date.');
+      outro('No pending migrations — database is up to date.');
     } else {
-      console.log(`\n🚀 ${dryRun ? 'Would apply' : 'Applied'} ${result.applied.length} migration(s):`);
-      for (const name of result.applied) {
-        console.log(`   ✓ ${name}`);
+      log.info(`${dryRun ? 'Would apply' : 'Applied'} ${result.applied.length} migration(s):`);
+      for (const appliedName of result.applied) {
+        log.success(appliedName);
       }
     }
 
     if (result.skipped.length > 0 && !dryRun) {
-      console.log(`\n⏭  Skipped ${result.skipped.length} already applied migration(s)`);
+      log.info(`Skipped ${result.skipped.length} already applied migration(s)`);
     }
   } finally {
     db.close();
@@ -233,9 +239,7 @@ async function cmdMigrate(args: ReturnType<typeof parseArgs>['values'], config:
 // ---------------------------------------------------------------------------
 
 function printHelp(): void {
-  console.log(`
-flint — migration CLI for flint-orm
-
+  log.message(`
 Usage:
   flint <command> [options]
 
@@ -294,13 +298,17 @@ async function main(): Promise<void> {
       await cmdMigrate(values, config);
       break;
     default:
-      console.error(`❌ Unknown command: ${command}`);
+      cancel(`Unknown command: ${command}`);
       printHelp();
       process.exit(1);
   }
 }
 
 main().catch((err) => {
-  console.error(err);
+  if (isCancel(err) || err instanceof CancellationError) {
+    cancel('Operation cancelled.');
+  } else {
+    cancel(err.message ?? 'An error occurred');
+  }
   process.exit(1);
 });