flint-orm 0.6.0 → 0.7.1

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 |