flint-orm 0.7.0 → 0.7.1

package/skills/update-schema/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: update-schema
+description: >
+  Add columns and tables without data loss. Covers safe vs unsafe migrations,
+  rebuildTable operation, additive migration patterns, and which changes
+  trigger table rebuilds. Load when modifying schema after initial migration
+  or when planning schema evolution.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/migration/diff.ts'
+  - 'kavenlabs/flint-orm:src/migration/sql.ts'
+  - 'kavenlabs/flint-orm:src/migration/migrate.ts'
+  - 'kavenlabs/flint-orm:README.md'
+---
+
+# flint-orm — Schema Updates
+
+## Setup
+
+After defining your initial schema, you'll need to evolve it over time. flint-orm detects changes and generates appropriate migrations.
+
+## Core Patterns
+
+### Safe migration: Adding a column with default
+
+```ts
+// Add a new column with a default value — safe, no data loss
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull().default('active'), // NEW: safe to add
+});
+```
+
+### Safe migration: Adding a new table
+
+```ts
+// Add a new table — always safe
+const posts = snakeCase.table('posts', {
+  id: integer().autoIncrement().primaryKey(),
+  userId: integer().notNull().references(users.id),
+  title: text().notNull(),
+});
+```
+
+### Unsafe migration: Changing column type
+
+```ts
+// Changing a column type triggers a table rebuild
+// The old column was: age: text('age')
+// The new column is:  age: integer('age')
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age').notNull().default(0), // TYPE CHANGE: triggers rebuild
+});
+```
+
+### Unsafe migration: Adding NOT NULL without default
+
+```ts
+// Adding NOT NULL without a default triggers a table rebuild
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull(), // NO DEFAULT: triggers rebuild
+});
+```
+
+## Migration Safety Reference
+
+### Safe changes (no rebuild)
+
+| Change | Example |
+|--------|---------|
+| Add column with default | `status: text().default('active')` |
+| Add new table | `snakeCase.table('new_table', {...})` |
+| Add index | `index('idx_name').on(t.name)` |
+| Drop index | Remove from index callback |
+| Change default value | `status: text().default('inactive')` |
+
+### Unsafe changes (triggers rebuild)
+
+| Change | Example |
+|--------|---------|
+| Change column type | `text()` → `integer()` |
+| Add NOT NULL without default | `text().notNull()` (no `.default()`) |
+| Remove NOT NULL | `text().notNull()` → `text()` |
+| Add/remove UNIQUE | `text().unique()` → `text()` |
+| Remove default | `text().default('x')` → `text()` |
+| Add/change/remove foreign key | `.references(col)` changes |
+| Change FK actions | `.onDelete('cascade')` changes |
+| Change autoincrement | `.autoIncrement()` changes |
+
+### What is rebuildTable?
+
+When an unsafe change is detected, flint-orm generates a `rebuildTable` operation that:
+
+1. Creates a temporary table with the new schema
+2. Copies data from the old table
+3. Drops the old table
+4. Renames the temporary table to the original name
+5. Recreates indexes
+
+This happens within a transaction — if anything fails, the original table is preserved.
+
+## Common Mistakes
+
+### HIGH Adding NOT NULL column without a default
+
+Wrong:
+
+```ts
+// After initial migration, adding:
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull(), // No default — triggers rebuild
+});
+```
+
+Correct:
+
+```ts
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  status: text().notNull().default('active'), // Safe: has default
+});
+```
+
+SQLite cannot add NOT NULL columns to existing tables without a default — this triggers a table rebuild.
+
+Source: src/migration/diff.ts
+
+### HIGH Changing a column type
+
+Wrong:
+
+```ts
+// Changing after initial migration:
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age'), // Was: age: text('age')
+});
+```
+
+Correct:
+
+```ts
+// Plan for the type from the start, or accept the rebuild
+const users = snakeCase.table('users', {
+  id: integer().autoIncrement().primaryKey(),
+  name: text().notNull(),
+  age: integer('age').notNull().default(0), // Correct type from start
+});
+```
+
+SQLite has no `ALTER COLUMN TYPE` — this always triggers a table rebuild.
+
+Source: src/migration/diff.ts
+
+### HIGH Dropping a column referenced by foreign keys
+
+Wrong:
+
+```ts
+// Dropping users.id when orders.userId references it
+// Migration fails with: Cannot rebuild "users" — referenced by: orders
+```
+
+Correct:
+
+```bash
+# Migrate dependent tables first, then rebuild the parent
+flint migrate # Apply orders migration first
+flint generate # Then rebuild users
+```
+
+The migration runner checks for incoming foreign keys before rebuild — it will refuse if other tables reference the table being rebuilt.
+
+Source: src/migration/migrate.ts

package/skills/write-queries/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: write-queries
+description: >
+  Read, write, and modify data with type-safe SELECT, INSERT, UPDATE, DELETE,
+  joins, and aggregates. Covers selectFrom, insert, update, delete, leftJoin,
+  innerJoin, where, columns, single, orderBy, limit, offset, distinct,
+  returning, onConflictDoNothing, onConflictDoUpdate, count, sum, avg, min,
+  max, and raw SQL. Load when building queries or troubleshooting query issues.
+metadata:
+  type: core
+  library: flint-orm
+  library_version: 0.7.0
+sources:
+  - 'kavenlabs/flint-orm:src/query/builder.ts'
+  - 'kavenlabs/flint-orm:src/query/conditions.ts'
+  - 'kavenlabs/flint-orm:src/query/aggregates.ts'
+  - 'kavenlabs/flint-orm:src/flint.ts'
+  - 'kavenlabs/flint-orm:README.md'
+  - 'kavenlabs/flint-orm:API.md'
+---
+
+# flint-orm — Queries
+
+## Setup
+
+```ts
+import { flint } from 'flint-orm/bun-sqlite';
+import { table, text, integer } from 'flint-orm/table';
+import { eq, and } from 'flint-orm/expressions';
+
+const users = table('users', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+  age: integer('age'),
+});
+
+const db = flint({ url: './app.db' });
+```
+
+## Core Patterns
+
+### SELECT with conditions
+
+```ts
+const adults = await db
+  .selectFrom(users)
+  .where(eq(users.age, 18))
+  .execute();
+```
+
+### SELECT specific columns
+
+```ts
+const names = await db
+  .selectFrom(users)
+  .columns(['id', 'name'])
+  .execute();
+// Returns: { id: string; name: string }[]
+```
+
+### Get a single row
+
+```ts
+const user = await db
+  .selectFrom(users)
+  .where(eq(users.id, 'u1'))
+  .single()
+  .execute();
+// Returns: User | null
+```
+
+### INSERT with returning
+
+```ts
+// Return all columns
+const inserted = await db
+  .insert(users)
+  .values({ id: 'u1', name: 'Alice', age: 30 })
+  .returning()
+  .execute();
+
+// Return specific columns
+const inserted = await db
+  .insert(users)
+  .values({ id: 'u1', name: 'Alice', age: 30 })
+  .returning(['id', 'name'])
+  .execute();
+```
+
+### UPSERT
+
+```ts
+await db
+  .insert(users)
+  .values({ id: 'u1', name: 'Alice' })
+  .onConflictDoUpdate({
+    target: users.id,
+    set: { name: 'Alice Updated' },
+  })
+  .execute();
+```
+
+### UPDATE with conditions
+
+```ts
+// Update without returning
+await db
+  .update(users)
+  .set({ name: 'Bob' })
+  .where(eq(users.id, 'u1'))
+  .execute();
+
+// Update with returning
+const updated = await db
+  .update(users)
+  .set({ name: 'Bob' })
+  .where(eq(users.id, 'u1'))
+  .returning(['id', 'name'])
+  .execute();
+```
+
+### DELETE with conditions
+
+```ts
+// Delete without returning
+await db
+  .delete(users)
+  .where(eq(users.id, 'u1'))
+  .execute();
+
+// Delete with returning
+const deleted = await db
+  .delete(users)
+  .where(eq(users.id, 'u1'))
+  .returning()
+  .execute();
+```
+
+### LEFT JOIN
+
+```ts
+const posts = table('posts', {
+  id: text('id').primaryKey(),
+  userId: text('userId').notNull().references(users.id),
+  title: text('title').notNull(),
+});
+
+const postsWithAuthors = await db
+  .leftJoin(users)
+  .on(posts)
+  .execute();
+// Returns: { id: string; name: string; posts: Post[] }[]
+```
+
+### Aggregate functions
+
+```ts
+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);
+```
+
+## Building Queries Conditionally
+
+The query builder is immutable — you can compose queries conditionally:
+
+```ts
+let query = db.selectFrom(users);
+
+if (filter.name) {
+  query = query.where(eq(users.name, filter.name));
+}
+if (filter.minAge) {
+  query = query.where(gte(users.age, filter.minAge));
+}
+
+const results = await query.execute();
+```
+
+Call `.execute()` at the terminal state when ready to run the query.
+
+## Common Mistakes
+
+### CRITICAL Not calling .execute() at terminal state
+
+Wrong:
+
+```ts
+const query = db.selectFrom(users).where(eq(users.id, 'u1')); // Builder, not executed
+const data = query; // Missing .execute()
+```
+
+Correct:
+
+```ts
+// Building queries conditionally is fine:
+let query = db.selectFrom(users);
+if (filter) query = query.where(eq(users.active, true));
+// But call .execute() at the terminal state:
+const data = await query.execute();
+```
+
+Queries are builders — you can compose them conditionally, but `.execute()` must be called when ready to run the query.
+
+Source: maintainer interview
+
+### CRITICAL Not awaiting .execute()
+
+Wrong:
+
+```ts
+const users = db.selectFrom(users).where(eq(users.id, 'u1')).execute(); // Promise, not data
+```
+
+Correct:
+
+```ts
+const users = await db.selectFrom(users).where(eq(users.id, 'u1')).execute();
+```
+
+`.execute()` returns a Promise — without `await`, you get the Promise object, not the data.
+
+Source: maintainer interview
+
+### HIGH Mixing Kysely/Drizzle/Supabase API patterns
+
+Wrong:
+
+```ts
+// Supabase-style (wrong)
+const users = await db.from('users').select('id, name');
+```
+
+Correct:
+
+```ts
+// Flint-style
+const users = await db.selectFrom(users).columns(['id', 'name']).execute();
+```
+
+flint-orm has its own API — `selectFrom().columns([...]).single()` is specific to this library.
+
+Source: maintainer interview
+
+### HIGH Using WHERE conditions with columns from wrong table
+
+Wrong:
+
+```ts
+// Using posts column in users query
+await db.selectFrom(users).where(eq(posts.userId, 'u1')).execute(); // ERROR
+```
+
+Correct:
+
+```ts
+await db.selectFrom(users).where(eq(users.id, 'u1')).execute();
+```
+
+The builder validates column ownership — columns in WHERE must belong to the queried table(s).
+
+Source: src/query/builder.ts
+
+## References
+
+- [Full condition operators reference](references/condition-operators.md)

package/skills/write-queries/references/condition-operators.md

@@ -0,0 +1,220 @@
+# Condition Operators Reference
+
+Detailed reference for all condition operators in flint-orm.
+
+All conditions are imported from `flint-orm/expressions`.
+
+## Comparison Operators
+
+### eq(column, value)
+
+Equal comparison.
+
+```ts
+import { eq } from 'flint-orm/expressions';
+
+// Value comparison
+eq(users.name, 'Alice')  // name = 'Alice'
+
+// Column-to-column comparison
+eq(posts.userId, users.id)  // posts.userId = users.id
+```
+
+### neq(column, value)
+
+Not equal comparison.
+
+```ts
+import { neq } from 'flint-orm/expressions';
+
+neq(users.id, 'excluded')  // id != 'excluded'
+```
+
+### gt(column, value)
+
+Greater than.
+
+```ts
+import { gt } from 'flint-orm/expressions';
+
+gt(users.age, 18)  // age > 18
+```
+
+### gte(column, value)
+
+Greater than or equal.
+
+```ts
+import { gte } from 'flint-orm/expressions';
+
+gte(users.age, 18)  // age >= 18
+```
+
+### lt(column, value)
+
+Less than.
+
+```ts
+import { lt } from 'flint-orm/expressions';
+
+lt(users.age, 65)  // age < 65
+```
+
+### lte(column, value)
+
+Less than or equal.
+
+```ts
+import { lte } from 'flint-orm/expressions';
+
+lte(users.age, 65)  // age <= 65
+```
+
+## Range Operator
+
+### between(column, low, high)
+
+Between two values (inclusive).
+
+```ts
+import { between } from 'flint-orm/expressions';
+
+between(users.age, 18, 65)  // age BETWEEN 18 AND 65
+```
+
+## Null Check Operators
+
+### isNull(column)
+
+Check for NULL.
+
+```ts
+import { isNull } from 'flint-orm/expressions';
+
+isNull(users.deletedAt)  // deletedAt IS NULL
+```
+
+### isNotNull(column)
+
+Check for NOT NULL.
+
+```ts
+import { isNotNull } from 'flint-orm/expressions';
+
+isNotNull(users.email)  // email IS NOT NULL
+```
+
+## Array Operators
+
+### isIn(column, values)
+
+Check if value is in array.
+
+```ts
+import { isIn } from 'flint-orm/expressions';
+
+isIn(users.id, ['u1', 'u2', 'u3'])  // id IN ('u1', 'u2', 'u3')
+```
+
+### isNotIn(column, values)
+
+Check if value is not in array.
+
+```ts
+import { isNotIn } from 'flint-orm/expressions';
+
+isNotIn(users.id, ['excluded'])  // id NOT IN ('excluded')
+```
+
+## Pattern Matching Operators
+
+### like(column, pattern)
+
+SQL LIKE pattern matching (% = any characters, _ = single char, case-insensitive).
+
+```ts
+import { like } from 'flint-orm/expressions';
+
+like(users.name, 'A%')  // name LIKE 'A%'
+```
+
+### glob(column, pattern)
+
+SQL GLOB pattern matching (* = any characters, ? = single char, case-sensitive).
+
+```ts
+import { glob } from 'flint-orm/expressions';
+
+glob(users.name, 'A*')  // name GLOB 'A*'
+```
+
+## Logical Operators
+
+### and(...conditions)
+
+Logical AND.
+
+```ts
+import { and, eq, gt } from 'flint-orm/expressions';
+
+and(eq(users.active, true), gt(users.age, 18))
+// active = 1 AND age > 18
+```
+
+### or(...conditions)
+
+Logical OR (wraps in parentheses).
+
+```ts
+import { or, eq } from 'flint-orm/expressions';
+
+or(eq(users.role, 'admin'), eq(users.role, 'moderator'))
+// (role = 'admin' OR role = 'moderator')
+```
+
+## Composing Conditions
+
+Conditions can be nested and combined:
+
+```ts
+import { and, or, eq, gt, lte, isIn } from 'flint-orm/expressions';
+
+// Complex condition
+and(
+  or(eq(users.role, 'admin'), eq(users.role, 'moderator')),
+  gt(users.age, 18),
+  isIn(users.status, ['active', 'pending'])
+)
+// ((role = 'admin' OR role = 'moderator') AND age > 18 AND status IN ('active', 'pending'))
+```
+
+## Column-to-Column Comparisons
+
+`eq` supports comparing two columns:
+
+```ts
+import { eq } from 'flint-orm/expressions';
+
+// Compare columns from different tables (useful for joins)
+eq(posts.userId, users.id)
+```
+
+## Operator Summary
+
+| Operator | SQL | Notes |
+|----------|-----|-------|
+| `eq` | `=` | Supports column-to-column |
+| `neq` | `!=` | |
+| `gt` | `>` | |
+| `gte` | `>=` | |
+| `lt` | `<` | |
+| `lte` | `<=` | |
+| `between` | `BETWEEN` | Inclusive range |
+| `isNull` | `IS NULL` | |
+| `isNotNull` | `IS NOT NULL` | |
+| `isIn` | `IN` | Array of values |
+| `isNotIn` | `NOT IN` | Array of values |
+| `like` | `LIKE` | % and _ wildcards, case-insensitive |
+| `glob` | `GLOB` | * and ? wildcards, case-sensitive |
+| `and` | `AND` | Composable |
+| `or` | `OR` | Wraps in parentheses |