flint-orm 0.1.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/dist/index.js

@@ -1144,6 +1144,9 @@ function flint(details) {
     avg: (table, column, condition) => avg(client, table, column, condition),
     min: (table, column, condition) => min(client, table, column, condition),
     max: (table, column, condition) => max(client, table, column, condition),
+    $run(sql, ...params) {
+      return client.prepare(sql).run(...params);
+    },
     $client: client
   };
 }
@@ -1329,7 +1332,7 @@ function real(name) {
   });
 }
 // src/schema/table.ts
-function table(name, columns) {
+function table(name, columns, indexFn) {
   const stamped = Object.create(null);
   for (const [key, col] of Object.entries(columns)) {
     const columnName = col.name || key;
@@ -1383,14 +1386,22 @@ function table(name, columns) {
     }
     stamped[key] = stampedCol;
   }
-  return Object.assign(stamped, {
+  const result = Object.assign(stamped, {
     _: { name }
   });
+  if (indexFn) {
+    const raw = indexFn(result);
+    if (raw.length > 0) {
+      const tableObj = result;
+      tableObj.__indexes = raw.map((item) => item.build());
+    }
+  }
+  return result;
 }
 function toSnakeCase(str) {
   return str.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
 }
-function snakeCaseTable(tableName, columns) {
+function snakeCaseTable(tableName, columns, indexFn) {
   const converted = {};
   for (const [key, col] of Object.entries(columns)) {
     const sqlName = toSnakeCase(key);
@@ -1445,11 +1456,141 @@ function snakeCaseTable(tableName, columns) {
     }
     converted[key] = stampedCol;
   }
-  return table(tableName, converted);
+  return table(tableName, converted, indexFn);
 }
 var snakeCase = {
   table: snakeCaseTable
 };
+function index(name) {
+  let columns = [];
+  let isUnique = false;
+  const builder = {
+    on(...cols) {
+      columns = cols;
+      return builder;
+    },
+    unique() {
+      isUnique = true;
+      return builder;
+    },
+    build() {
+      if (columns.length === 0) {
+        throw new Error(`Index "${name}" has no columns \u2014 call .on() before returning`);
+      }
+      return {
+        name,
+        columns: columns.map((c) => c.name),
+        unique: isUnique
+      };
+    }
+  };
+  return builder;
+}
+// src/sqlite/introspect.ts
+var TEXT_TYPES = new Set(["text", "varchar", "character", "char", "clob", "native character", "nvarchar", "nchar", "nyclob", "numeric"]);
+var INTEGER_TYPES = new Set(["integer", "int", "smallint", "tinyint", "bigint", "unsigned big int", "int2", "int8", "mediumint"]);
+var REAL_TYPES = new Set(["real", "float", "double", "double precision", "decimal"]);
+function normalizeType(rawType) {
+  const t = rawType.toLowerCase().trim();
+  const base = t.replace(/\(.*\)/, "").trim();
+  if (INTEGER_TYPES.has(base))
+    return "integer";
+  if (REAL_TYPES.has(base))
+    return "real";
+  if (TEXT_TYPES.has(base))
+    return "text";
+  if (base === "blob")
+    return "blob";
+  return "text";
+}
+function parseDefault(dfltValue) {
+  if (dfltValue === null || dfltValue === undefined) {
+    return { hasDefault: false };
+  }
+  const raw = String(dfltValue);
+  if (raw.toUpperCase() === "NULL") {
+    return { hasDefault: true, defaultValue: null };
+  }
+  if (/^-?\d+$/.test(raw)) {
+    return { hasDefault: true, defaultValue: Number(raw) };
+  }
+  if (/^-?\d+\.\d+$/.test(raw)) {
+    return { hasDefault: true, defaultValue: Number(raw) };
+  }
+  if (raw.startsWith("'") && raw.endsWith("'") || raw.startsWith('"') && raw.endsWith('"')) {
+    return { hasDefault: true, defaultValue: raw.slice(1, -1) };
+  }
+  return { hasDefault: true, defaultValue: raw };
+}
+function introspectColumns(client, tableName) {
+  const rows = client.query(`PRAGMA table_info('${tableName}')`).all();
+  const fkRows = client.query(`PRAGMA foreign_key_list('${tableName}')`).all();
+  const indexRows = client.query(`PRAGMA index_list('${tableName}')`).all();
+  const fkMap = new Map;
+  for (const fk of fkRows) {
+    fkMap.set(fk.from, { referencesTable: fk.table, referencesColumn: fk.to });
+  }
+  const uniqueColumns = new Set;
+  for (const idx of indexRows) {
+    if (idx.unique === 1 && (idx.origin === "u" || idx.origin === "c")) {
+      const colInfo = client.query(`PRAGMA index_info('${idx.name}')`).all();
+      if (colInfo.length === 1) {
+        uniqueColumns.add(colInfo[0].name);
+      }
+    }
+  }
+  const columns = rows.map((row) => {
+    const fk = fkMap.get(row.name);
+    const { hasDefault, defaultValue } = parseDefault(row.dflt_value);
+    const col = {
+      name: row.name,
+      sqlType: normalizeType(row.type),
+      isPrimaryKey: row.pk === 1,
+      isNotNull: row.notnull === 1,
+      isUnique: uniqueColumns.has(row.name),
+      hasDefault,
+      defaultValue
+    };
+    if (fk) {
+      col.referencesTable = fk.referencesTable;
+      col.referencesColumn = fk.referencesColumn;
+    }
+    return col;
+  });
+  return { columns, indexRows };
+}
+function introspectIndexes(client, indexRows) {
+  const indexes = [];
+  for (const idx of indexRows) {
+    if (idx.name.startsWith("sqlite_autoindex_"))
+      continue;
+    const colRows = client.query(`PRAGMA index_info('${idx.name}')`).all();
+    const columns = colRows.map((c) => c.name);
+    indexes.push({
+      name: idx.name,
+      columns,
+      unique: idx.unique === 1
+    });
+  }
+  return indexes;
+}
+function introspect(client) {
+  const tableRows = client.query(`SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' AND name != '__flint_migrations'`).all();
+  const tables = {};
+  for (const { name } of tableRows) {
+    const { columns, indexRows } = introspectColumns(client, name);
+    const indexes = introspectIndexes(client, indexRows);
+    tables[name] = {
+      name,
+      columns,
+      indexes
+    };
+  }
+  return {
+    version: 1,
+    tables
+  };
+}
 export {
   text,
   table,
@@ -1469,7 +1610,9 @@ export {
   isNotNull,
   isNotIn,
   isIn,
+  introspect,
   integer,
+  index,
   gte,
   gt,
   glob,