flint-orm 0.7.0 → 0.7.2

package/README.md

@@ -19,6 +19,8 @@ bun add flint-orm
 npm install flint-orm
 ```
 
+**Using an AI agent?** Run `npx @tanstack/intent@latest install` to get agent-friendly skills for this library.
+
 ## Quick Start
 
 ```ts

package/package.json

@@ -1,13 +1,25 @@
 {
   "name": "flint-orm",
-  "version": "0.7.0",
+  "version": "0.7.2",
+  "keywords": [
+    "database",
+    "libsql",
+    "orm",
+    "sqlite",
+    "tanstack-intent",
+    "turso",
+    "typescript"
+  ],
+  "repository": "github:kavenlabs/flint-orm",
   "bin": {
     "flint": "./dist/src/cli.js"
   },
   "files": [
     "dist",
     "API.md",
-    "README.md"
+    "README.md",
+    "skills",
+    "!skills/_artifacts"
   ],
   "type": "module",
   "main": "./dist/src/index.js",
@@ -69,6 +81,7 @@
   "devDependencies": {
     "@clack/prompts": "1.7.0",
     "@libsql/client": "0.17.4",
+    "@tanstack/intent": "0.3.5",
     "@tursodatabase/database": "0.6.1",
     "@tursodatabase/sync": "0.6.1",
     "@types/better-sqlite3": "7.6.13",

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 |