flint-orm 0.6.0 → 0.7.1

package/skills/batch-transactions/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: batch-transactions
+description: >
+  Run multiple queries atomically in a single transaction. Covers db.batch(),
+  Executable interface, and transaction safety. Load when combining multiple
+  writes that must succeed or fail together, or when debugging transaction
+  issues.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/flint.ts'
+  - 'kavenlabs/flint-orm:src/query/builder.ts'
+  - 'kavenlabs/flint-orm:README.md'
+  - 'kavenlabs/flint-orm:API.md'
+---
+
+# flint-orm — Batch Transactions
+
+## Setup
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+import { table, text, integer } from 'flint-orm/table';
+import { eq } from 'flint-orm/expressions';
+
+const users = table('users', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  totalOrders: integer('totalOrders').default(0),
+});
+
+const posts = table('posts', {
+  id: text('id').primaryKey(),
+  userId: text('userId').notNull().references(users.id),
+  title: text('title').notNull(),
+});
+
+const db = flint({ url: './app.db' });
+```
+
+## Core Patterns
+
+### Run multiple inserts atomically
+
+```ts
+await db.batch([
+  db.insert(users).values({ id: 'u1', name: 'Alice' }),
+  db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' }),
+]);
+```
+
+### Combine reads and writes
+
+```ts
+await db.batch([
+  db.update(users).set({ totalOrders: 1 }).where(eq(users.id, 'u1')),
+  db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' }),
+]);
+```
+
+### All-or-nothing execution
+
+If any query in the batch fails, all queries are rolled back:
+
+```ts
+// If the second insert fails, the first insert is also rolled back
+await db.batch([
+  db.insert(users).values({ id: 'u1', name: 'Alice' }),
+  db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' }), // If this fails...
+]);
+// ...the user insert is also rolled back
+```
+
+## Common Mistakes
+
+### HIGH Not awaiting the batch call
+
+Wrong:
+
+```ts
+db.batch([
+  db.insert(users).values({ id: 'u1', name: 'Alice' }),
+  db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' }),
+]); // Not awaited!
+```
+
+Correct:
+
+```ts
+await db.batch([
+  db.insert(users).values({ id: 'u1', name: 'Alice' }),
+  db.insert(posts).values({ id: 'p1', userId: 'u1', title: 'Hello' }),
+]);
+```
+
+`batch()` returns a Promise — without `await`, the transaction may not complete.
+
+Source: src/flint.ts
+
+### MEDIUM Passing non-Executable objects to batch()
+
+Wrong:
+
+```ts
+db.batch([{ sql: 'INSERT ...', params: [] }]); // Not an Executable
+```
+
+Correct:
+
+```ts
+db.batch([
+  db.insert(users).values({ id: 'u1', name: 'Alice' }),
+]);
+```
+
+`batch()` only accepts objects with a `.toSQL()` method (query builders), not raw SQL objects.
+
+Source: src/flint.ts

package/skills/define-schema/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: define-schema
+description: >
+  Create tables with columns, indexes, constraints, and foreign keys. Covers
+  table(), snakeCase.table(), column constructors (text, integer, boolean,
+  json, real, date), column modifiers (primaryKey, notNull, unique, default,
+  references, onDelete, onUpdate, autoIncrement, defaultNow, onUpdateTimestamp),
+  index builder, and InferRow/InsertRow types. Load when defining or modifying
+  database schemas.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/schema/columns.ts'
+  - 'kavenlabs/flint-orm:src/schema/table.ts'
+  - 'kavenlabs/flint-orm:README.md'
+  - 'kavenlabs/flint-orm:API.md'
+---
+
+# flint-orm — Schema Definition
+
+## Setup
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+  name: d.text().notNull(),
+  email: d.text().unique(),
+  age: d.integer(),
+  active: d.boolean().default(true),
+  createdAt: d.date().defaultNow(),
+});
+```
+
+## Core Patterns
+
+### Define a table with snake_case columns
+
+Use `snakeCase.table()` to auto-convert camelCase keys to snake_case SQL names:
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+  firstName: d.text().notNull(),    // SQL: first_name
+  lastName: d.text().notNull(),     // SQL: last_name
+  createdAt: d.date().defaultNow(), // SQL: created_at
+});
+```
+
+### Add indexes
+
+Define indexes via the table callback:
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table(
+  'users',
+  {
+    id: d.integer().autoIncrement().primaryKey(),
+    email: d.text().notNull(),
+    name: d.text().notNull(),
+  },
+  (t) => [
+    d.index('idx_users_email').on(t.email).unique(),
+    d.index('idx_users_name').on(t.name),
+  ],
+);
+```
+
+### Define foreign keys
+
+Use `.references()` to link columns across tables:
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+  name: d.text().notNull(),
+});
+
+const posts = d.snakeCase.table('posts', {
+  id: d.integer().autoIncrement().primaryKey(),
+  userId: d.integer().notNull().references(users.id),
+  title: d.text().notNull(),
+});
+```
+
+### Derive TypeScript types
+
+```ts
+import type { InferRow, InsertRow } from 'flint-orm/table';
+
+type User = InferRow<typeof users>;
+// { id: number; name: string; email: string | null; active: boolean; createdAt: Date }
+
+type NewUser = InsertRow<typeof users>;
+// { id?: number; name: string; email?: string; active?: boolean; createdAt?: Date }
+```
+
+## Column Types
+
+| Function | TS Type | SQLite Storage | Notes |
+|----------|---------|----------------|-------|
+| `text()` | `string` | TEXT | |
+| `integer()` | `number` | INTEGER | Supports `.autoIncrement()` |
+| `boolean()` | `boolean` | INTEGER (0/1) | Encodes/decodes automatically |
+| `json<T>()` | `T` | TEXT (JSON) | Generic, encodes/decodes automatically |
+| `real()` | `number` | REAL | |
+| `date()` | `Date` | INTEGER (epoch ms) | Supports `.defaultNow()`, `.onUpdateTimestamp()` |
+
+## Column Modifiers
+
+| Modifier | Applies to | Description |
+|----------|------------|-------------|
+| `.primaryKey()` | All | Mark as primary key |
+| `.notNull()` | All | Disallow NULL values |
+| `.unique()` | All | Add unique constraint |
+| `.default(value)` | All | Static default value |
+| `.defaultFn(fn)` | All | Dynamic default (called on insert) |
+| `.references(col)` | All | Foreign key reference |
+| `.onDelete(action)` | All | ON DELETE action (requires `.references()`) |
+| `.onUpdate(action)` | All | ON UPDATE action (requires `.references()`) |
+| `.autoIncrement()` | integer only | Auto-increment |
+| `.defaultNow()` | date only | Use `Date.now()` as default |
+| `.onUpdateTimestamp()` | date only | Always set to `Date.now()` on update |
+
+## Common Mistakes
+
+### HIGH Using table() with camelCase keys
+
+Wrong:
+
+```ts
+import { table, text } from 'flint-orm/table';
+
+const users = table('users', {
+  id: text('id').primaryKey(),
+  firstName: text('firstName'), // SQL: firstName, not first_name
+});
+```
+
+Correct:
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+  firstName: d.text().notNull(), // SQL: first_name
+});
+```
+
+`table()` uses the object key as the SQL column name — camelCase keys produce camelCase SQL columns. Use `snakeCase.table()` for automatic conversion.
+
+Source: maintainer interview
+
+### HIGH Using .__internal in application code
+
+Wrong:
+
+```ts
+const typeName = users.name.__internal._type; // DON'T DO THIS
+```
+
+Correct:
+
+```ts
+import type { InferRow } from 'flint-orm/table';
+type User = InferRow<typeof users>;
+```
+
+`.__internal` is for ORM internals — its shape can change between versions without notice.
+
+Source: maintainer interview
+
+### MEDIUM Calling .references() before table() stamps it
+
+Wrong:
+
+```ts
+import { text } from 'flint-orm/table';
+const col = text('userId').references(users.id); // ERROR: users not yet defined
+```
+
+Correct:
+
+```ts
+import * as d from 'flint-orm/table';
+
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+});
+
+const posts = d.snakeCase.table('posts', {
+  userId: d.integer().notNull().references(users.id),
+});
+```
+
+TypeScript prevents this — `.references()` requires a column that has been attached to a table via `table()`.
+
+Source: src/schema/columns.ts
+
+## References
+
+- [Full column modifiers reference](references/column-modifiers.md)

package/skills/define-schema/references/column-modifiers.md

@@ -0,0 +1,176 @@
+# Column Modifiers Reference
+
+Detailed reference for all column modifiers in flint-orm.
+
+## .primaryKey()
+
+Mark a column as the primary key.
+
+```ts
+const id = d.integer().primaryKey();
+// SQL: id INTEGER PRIMARY KEY
+```
+
+**Notes:**
+- Only one column per table can be primary key
+- Primary keys are implicitly NOT NULL
+
+## .notNull()
+
+Disallow NULL values.
+
+```ts
+const name = d.text().notNull();
+// SQL: name TEXT NOT NULL
+```
+
+**Notes:**
+- Adding NOT NULL to an existing column requires a default value (triggers table rebuild otherwise)
+- Removing NOT NULL is an unsafe migration (triggers table rebuild)
+
+## .unique()
+
+Add a unique constraint.
+
+```ts
+const email = d.text().unique();
+// SQL: email TEXT UNIQUE
+```
+
+**Notes:**
+- Adding or removing UNIQUE triggers a table rebuild
+
+## .default(value)
+
+Set a static default value.
+
+```ts
+const active = d.boolean().default(true);
+// SQL: active INTEGER DEFAULT 1
+
+const status = d.text().default('active');
+// SQL: status TEXT DEFAULT 'active'
+```
+
+**Notes:**
+- The value must match the column's TypeScript type
+- Removing a default is an unsafe migration (SQLite has no DROP DEFAULT syntax)
+
+## .defaultFn(fn)
+
+Set a dynamic default function called on insert when the value is omitted.
+
+```ts
+const id = d.text().defaultFn(() => crypto.randomUUID());
+```
+
+**Notes:**
+- The function is called at insert time, not at schema definition time
+- Useful for UUIDs, timestamps, or computed values
+
+## .references(target)
+
+Define a foreign key reference to another table's column.
+
+```ts
+const users = d.snakeCase.table('users', {
+  id: d.integer().autoIncrement().primaryKey(),
+});
+
+const posts = d.snakeCase.table('posts', {
+  userId: d.integer().notNull().references(users.id),
+});
+// SQL: userId INTEGER NOT NULL REFERENCES users(id)
+```
+
+**Notes:**
+- The target column must be from a table defined with `table()`
+- TypeScript prevents calling `.references()` before the target table exists
+- Changing the FK target triggers a table rebuild
+
+## .onDelete(action)
+
+Set the ON DELETE action for a foreign key. Requires `.references()` to be called first.
+
+```ts
+const posts = d.snakeCase.table('posts', {
+  userId: d.integer().notNull().references(users.id).onDelete('cascade'),
+});
+// SQL: userId INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE
+```
+
+**Valid actions:** `'cascade'`, `'set null'`, `'set default'`, `'restrict'`, `'no action'`
+
+**Notes:**
+- Changing ON DELETE action triggers a table rebuild
+
+## .onUpdate(action)
+
+Set the ON UPDATE action for a foreign key. Requires `.references()` to be called first.
+
+```ts
+const posts = d.snakeCase.table('posts', {
+  userId: d.integer().notNull().references(users.id).onUpdate('cascade'),
+});
+// SQL: userId INTEGER NOT NULL REFERENCES users(id) ON UPDATE CASCADE
+```
+
+**Valid actions:** `'cascade'`, `'set null'`, `'set default'`, `'restrict'`, `'no action'`
+
+**Notes:**
+- Changing ON UPDATE action triggers a table rebuild
+
+## .autoIncrement() (integer only)
+
+Mark an integer column as auto-increment (SQLite ROWID alias).
+
+```ts
+const id = d.integer().primaryKey().autoIncrement();
+// SQL: id INTEGER PRIMARY KEY AUTOINCREMENT
+```
+
+**Notes:**
+- Only works with integer columns
+- Changing autoincrement triggers a table rebuild
+
+## .defaultNow() (date only)
+
+Use `Date.now()` as the default when the value is omitted during insert.
+
+```ts
+const createdAt = d.date().defaultNow();
+// SQL: created_at INTEGER DEFAULT (unixepoch * 1000)
+```
+
+**Notes:**
+- Only works with date columns
+- Makes the column non-nullable in query results (guaranteed to have a value)
+
+## .onUpdateTimestamp() (date only)
+
+Always set to `Date.now()` on update, regardless of the provided value.
+
+```ts
+const updatedAt = d.date().onUpdateTimestamp();
+```
+
+**Notes:**
+- Only works with date columns
+- The value is set automatically on every UPDATE operation
+- Not reflected in SQL schema — handled by the ORM at runtime
+
+## Migration Safety
+
+| Change | Safe? | Notes |
+|--------|-------|-------|
+| Adding NOT NULL with default | ✅ | Safe |
+| Adding NOT NULL without default | ❌ | Triggers rebuild |
+| Removing NOT NULL | ❌ | Triggers rebuild |
+| Adding UNIQUE | ❌ | Triggers rebuild |
+| Removing UNIQUE | ❌ | Triggers rebuild |
+| Adding/changing DEFAULT | ✅ | Safe |
+| Removing DEFAULT | ❌ | SQLite has no DROP DEFAULT |
+| Adding/changing FK | ❌ | Triggers rebuild |
+| Removing FK | ❌ | Triggers rebuild |
+| Changing FK actions | ❌ | Triggers rebuild |
+| Changing autoincrement | ❌ | Triggers rebuild |

package/skills/driver-selection/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: driver-selection
+description: >
+  Choose the right driver for your environment: local file, in-memory,
+  serverless, or remote. Covers bun:sqlite, better-sqlite3, @libsql/client,
+  @libsql/client/web, @tursodatabase/database, @tursodatabase/sync. Load
+  when deciding which driver to use or when troubleshooting driver-specific
+  issues.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/entries/bun-sqlite.ts'
+  - 'kavenlabs/flint-orm:src/entries/better-sqlite3.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql.ts'
+  - 'kavenlabs/flint-orm:src/entries/libsql-web.ts'
+  - 'kavenlabs/flint-orm:src/entries/turso.ts'
+  - 'kavenlabs/flint-orm:src/entries/turso-sync.ts'
+---
+
+# flint-orm — Driver Selection
+
+## Setup
+
+```ts
+// bun:sqlite — Bun runtime only, local file
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: './app.db' });
+
+// better-sqlite3 — Node.js, local file
+import { flint } from 'flint-orm/better-sqlite3';
+const db = flint({ url: './app.db' });
+
+// libsql — local file or remote (Turso)
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// libsql-web — serverless/edge, remote only (no native binary)
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// turso — Turso database
+import { flint } from 'flint-orm/turso';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+
+// turso-sync — Turso with sync support
+import { flint } from 'flint-orm/turso-sync';
+const db = flint({ url: 'libsql://your-db.turso.io', authToken: '...' });
+```
+
+## Core Patterns
+
+### Local file database
+
+Use bun:sqlite (Bun) or better-sqlite3 (Node.js) for local SQLite files:
+
+```ts
+// Bun runtime
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: './app.db' });
+
+// Node.js
+import { flint } from 'flint-orm/better-sqlite3';
+const db = flint({ url: './app.db' });
+```
+
+### Remote database (Turso)
+
+Use libsql or turso for remote Turso databases:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### Serverless/edge environment
+
+Use libsql-web for serverless or edge runtimes (no native binary):
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({
+  url: 'libsql://your-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+### In-memory database
+
+All drivers support in-memory databases via `:memory:`:
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+const db = flint({ url: ':memory:' });
+```
+
+## Driver Comparison
+
+| Driver | Runtime | File URLs | Remote URLs | Serverless | Auth Token |
+|--------|---------|-----------|-------------|------------|------------|
+| bun:sqlite | Bun only | ✅ | ❌ | ❌ | ❌ |
+| better-sqlite3 | Node.js | ✅ | ❌ | ❌ | ❌ |
+| libsql | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+| libsql-web | Any | ❌ | ✅ | ✅ | ✅ |
+| turso | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+| turso-sync | Bun/Node | ✅ | ✅ | ✅ | ✅ |
+
+## Common Mistakes
+
+### HIGH libsql requires file: prefix for local paths
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'app.db' }); // ERROR: URL_INVALID
+```
+
+Correct:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'file:./app.db' });
+```
+
+Unlike bun:sqlite and better-sqlite3, the libsql driver requires the `file:` prefix for local file paths.
+
+Source: maintainer interview
+
+### HIGH Using libsql-web with file: URLs
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql-web';
+const db = flint({ url: 'file:./app.db' }); // ERROR
+```
+
+Correct:
+
+```ts
+// For local files, use libsql or bun-sqlite
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'file:./app.db' });
+```
+
+libsql-web only supports HTTP/WebSocket URLs — it has no native binary and cannot access local files.
+
+Source: src/entries/libsql-web.ts
+
+### HIGH Missing authToken for remote databases
+
+Wrong:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({ url: 'libsql://my-db.turso.io' }); // Missing authToken
+```
+
+Correct:
+
+```ts
+import { flint } from 'flint-orm/libsql';
+const db = flint({
+  url: 'libsql://my-db.turso.io',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+});
+```
+
+Remote Turso/libsql databases require authentication.
+
+Source: maintainer interview
+
+## References
+
+- [Full driver comparison](references/driver-comparison.md)