codeforge-dev 1.4.0

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/sqlite/references/advanced-queries.md

@@ -0,0 +1,314 @@
+# Advanced SQLite Queries -- Deep Dive
+
+## 1. Common Table Expressions (CTEs)
+
+CTEs define named temporary result sets within a single query. They improve readability and allow recursive queries.
+
+### Non-Recursive CTEs
+
+```sql
+WITH active_users AS (
+    SELECT id, email, display_name
+    FROM users
+    WHERE last_login > date('now', '-30 days')
+),
+user_stats AS (
+    SELECT user_id, COUNT(*) AS post_count
+    FROM posts
+    GROUP BY user_id
+)
+SELECT au.email, au.display_name, COALESCE(us.post_count, 0) AS post_count
+FROM active_users au
+LEFT JOIN user_stats us ON au.id = us.user_id
+ORDER BY post_count DESC;
+```
+
+### Recursive CTEs
+
+Recursive CTEs self-reference to traverse hierarchical data:
+
+```sql
+-- Organizational hierarchy
+WITH RECURSIVE org_tree AS (
+    -- Base case: root nodes (no manager)
+    SELECT id, name, manager_id, 0 AS depth, name AS path
+    FROM employees
+    WHERE manager_id IS NULL
+
+    UNION ALL
+
+    -- Recursive case: children of already-found nodes
+    SELECT e.id, e.name, e.manager_id, ot.depth + 1,
+           ot.path || ' > ' || e.name
+    FROM employees e
+    JOIN org_tree ot ON e.manager_id = ot.id
+)
+SELECT * FROM org_tree ORDER BY path;
+```
+
+```sql
+-- Bill of materials (tree of components)
+WITH RECURSIVE bom AS (
+    SELECT component_id, parent_id, quantity, 1 AS level
+    FROM components
+    WHERE parent_id = :root_id
+
+    UNION ALL
+
+    SELECT c.component_id, c.parent_id, c.quantity * bom.quantity, bom.level + 1
+    FROM components c
+    JOIN bom ON c.parent_id = bom.component_id
+)
+SELECT * FROM bom;
+```
+
+### Limit Recursion Depth
+
+SQLite defaults to a maximum recursion depth of 1000. Override with `LIMIT` on the CTE or adjust `SQLITE_MAX_VARIABLE_NUMBER`:
+
+```sql
+WITH RECURSIVE seq(n) AS (
+    SELECT 1
+    UNION ALL
+    SELECT n + 1 FROM seq WHERE n < 100
+)
+SELECT n FROM seq;
+```
+
+---
+
+## 2. Window Functions
+
+Window functions compute values across a set of rows related to the current row, without collapsing the result set.
+
+### ROW_NUMBER, RANK, DENSE_RANK
+
+```sql
+-- Rank users by post count within each category
+SELECT
+    u.name,
+    c.category_name,
+    COUNT(p.id) AS post_count,
+    ROW_NUMBER() OVER (PARTITION BY c.id ORDER BY COUNT(p.id) DESC) AS row_num,
+    RANK() OVER (PARTITION BY c.id ORDER BY COUNT(p.id) DESC) AS rank,
+    DENSE_RANK() OVER (PARTITION BY c.id ORDER BY COUNT(p.id) DESC) AS dense_rank
+FROM users u
+JOIN posts p ON u.id = p.user_id
+JOIN categories c ON p.category_id = c.id
+GROUP BY u.id, c.id;
+```
+
+| Function | Ties | Gaps |
+|----------|------|------|
+| `ROW_NUMBER` | Breaks ties arbitrarily | No gaps |
+| `RANK` | Same rank for ties | Gaps after ties |
+| `DENSE_RANK` | Same rank for ties | No gaps |
+
+### LAG and LEAD
+
+Access previous or next row values without a self-join:
+
+```sql
+-- Compare each sale to the previous day
+SELECT
+    date,
+    revenue,
+    LAG(revenue, 1) OVER (ORDER BY date) AS prev_day_revenue,
+    revenue - LAG(revenue, 1) OVER (ORDER BY date) AS daily_change,
+    LEAD(revenue, 1) OVER (ORDER BY date) AS next_day_revenue
+FROM daily_sales;
+```
+
+### Running Totals and Moving Averages
+
+```sql
+-- Running total of revenue
+SELECT
+    date,
+    revenue,
+    SUM(revenue) OVER (ORDER BY date ROWS UNBOUNDED PRECEDING) AS running_total
+FROM daily_sales;
+
+-- 7-day moving average
+SELECT
+    date,
+    revenue,
+    AVG(revenue) OVER (
+        ORDER BY date
+        ROWS BETWEEN 6 PRECEDING AND CURRENT ROW
+    ) AS moving_avg_7d
+FROM daily_sales;
+```
+
+### NTILE and Percentiles
+
+```sql
+-- Divide users into quartiles by score
+SELECT
+    name,
+    score,
+    NTILE(4) OVER (ORDER BY score DESC) AS quartile
+FROM users;
+
+-- First and last value in partition
+SELECT
+    department,
+    name,
+    salary,
+    FIRST_VALUE(name) OVER (PARTITION BY department ORDER BY salary DESC) AS highest_paid,
+    LAST_VALUE(name) OVER (
+        PARTITION BY department ORDER BY salary DESC
+        ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING
+    ) AS lowest_paid
+FROM employees;
+```
+
+---
+
+## 3. Upsert (INSERT ... ON CONFLICT)
+
+Insert a row or update it if a unique constraint would be violated:
+
+```sql
+-- Update on conflict with specific columns
+INSERT INTO settings (key, value, updated_at)
+VALUES ('theme', 'dark', strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+ON CONFLICT (key) DO UPDATE SET
+    value = excluded.value,
+    updated_at = excluded.updated_at;
+
+-- Ignore duplicates silently
+INSERT INTO tags (name) VALUES ('sqlite')
+ON CONFLICT (name) DO NOTHING;
+
+-- Conditional upsert
+INSERT INTO counters (key, count) VALUES ('visits', 1)
+ON CONFLICT (key) DO UPDATE SET count = count + 1
+WHERE count < 1000000;
+```
+
+`excluded` refers to the row that would have been inserted. Use it to reference the new values in the `DO UPDATE` clause.
+
+---
+
+## 4. RETURNING
+
+`RETURNING` retrieves the affected rows from `INSERT`, `UPDATE`, or `DELETE` without a separate query:
+
+```sql
+-- Get the inserted row with auto-generated id
+INSERT INTO users (email, name) VALUES ('alice@example.com', 'Alice')
+RETURNING id, email, name, created_at;
+
+-- Get old values during update
+UPDATE products SET price = price * 1.1
+WHERE category = 'electronics'
+RETURNING id, name, price AS new_price;
+
+-- Confirm what was deleted
+DELETE FROM sessions WHERE expires_at < datetime('now')
+RETURNING id, user_id;
+```
+
+`RETURNING` is particularly useful with `INSERT` to avoid a round-trip `SELECT` for the auto-generated `rowid`.
+
+---
+
+## 5. EXPLAIN QUERY PLAN
+
+Analyze how SQLite executes a query to identify missing indexes or inefficient scans:
+
+```sql
+EXPLAIN QUERY PLAN
+SELECT u.name, COUNT(p.id)
+FROM users u
+JOIN posts p ON u.id = p.user_id
+WHERE u.created_at > '2024-01-01'
+GROUP BY u.id;
+```
+
+Output interpretation:
+
+| Term | Meaning |
+|------|---------|
+| `SCAN` | Full table scan -- no index used |
+| `SEARCH` | Index lookup -- efficient |
+| `USING INDEX` | Specifies which index |
+| `USING COVERING INDEX` | Index contains all needed columns, no table access |
+| `TEMP B-TREE` | Temporary sort/group structure |
+
+### Optimization Workflow
+
+1. Run `EXPLAIN QUERY PLAN` on slow queries.
+2. Look for `SCAN` on large tables -- this indicates a missing index.
+3. Add an index on the filtered/joined column.
+4. Re-run `EXPLAIN QUERY PLAN` to verify `SEARCH USING INDEX`.
+5. Run `ANALYZE` after adding indexes to update the query planner's statistics.
+
+```sql
+-- Before: SCAN users
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = 'alice@example.com';
+
+-- Add index
+CREATE INDEX idx_users_email ON users(email);
+
+-- After: SEARCH users USING INDEX idx_users_email
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = 'alice@example.com';
+```
+
+---
+
+## 6. Covering Indexes
+
+A covering index includes all columns referenced by a query, eliminating the need to read the main table:
+
+```sql
+-- This query needs id, email, and display_name
+SELECT id, email, display_name FROM users WHERE email LIKE 'a%';
+
+-- Covering index for this query
+CREATE INDEX idx_users_email_covering ON users(email, id, display_name);
+```
+
+After adding the covering index, `EXPLAIN QUERY PLAN` shows `USING COVERING INDEX` instead of `USING INDEX` followed by a table lookup.
+
+### When to Use Covering Indexes
+
+- High-frequency read queries with a known column set.
+- Queries where the table is wide (many columns) but only a few are needed.
+- The tradeoff is increased write overhead and storage for the index.
+
+---
+
+## 7. Partial and Expression Indexes
+
+### Partial Indexes
+
+Index only rows matching a condition, reducing index size and write overhead:
+
+```sql
+-- Index only active users (smaller, faster)
+CREATE INDEX idx_active_users ON users(email) WHERE status = 'active';
+
+-- Index only non-null values
+CREATE INDEX idx_users_display_name ON users(display_name)
+    WHERE display_name IS NOT NULL;
+```
+
+The query planner uses a partial index only when the `WHERE` clause of the query matches the index condition.
+
+### Expression Indexes
+
+Index computed values:
+
+```sql
+-- Case-insensitive email lookup
+CREATE INDEX idx_users_email_lower ON users(lower(email));
+-- SELECT * FROM users WHERE lower(email) = 'alice@example.com';
+
+-- Date extraction from ISO timestamp
+CREATE INDEX idx_posts_date ON posts(date(created_at));
+-- SELECT * FROM posts WHERE date(created_at) = '2024-06-15';
+```
+
+Expression indexes work with any deterministic SQL expression. The query must use the exact same expression for the planner to select the index.

package/.devcontainer/plugins/devs-marketplace/plugins/codedirective-skills/skills/sqlite/references/javascript-patterns.md

@@ -0,0 +1,323 @@
+# JavaScript SQLite Patterns -- Deep Dive
+
+## 1. better-sqlite3 User-Defined Functions
+
+### Scalar Functions
+
+```javascript
+const Database = require("better-sqlite3");
+const db = new Database("app.db");
+
+db.function("reverse", (str) => str.split("").reverse().join(""));
+// SELECT reverse(name) FROM users;
+
+db.function("json_arr_len", (json) => {
+  if (json === null) return 0;
+  return JSON.parse(json).length;
+});
+// SELECT json_arr_len(tags) FROM posts;
+```
+
+### Aggregate Functions
+
+```javascript
+db.aggregate("median", {
+  start: () => [],
+  step: (arr, value) => {
+    if (value !== null) arr.push(value);
+    return arr;
+  },
+  result: (arr) => {
+    if (arr.length === 0) return null;
+    arr.sort((a, b) => a - b);
+    const mid = Math.floor(arr.length / 2);
+    return arr.length % 2 === 0
+      ? (arr[mid - 1] + arr[mid]) / 2
+      : arr[mid];
+  },
+});
+// SELECT median(price) FROM products;
+```
+
+### Table-Valued Functions
+
+```javascript
+db.table("generate_series", {
+  columns: ["value"],
+  parameters: ["start", "stop", "step"],
+  *rows(start, stop, step = 1) {
+    for (let i = start; i <= stop; i += step) {
+      yield { value: i };
+    }
+  },
+});
+// SELECT value FROM generate_series(1, 10, 2);
+```
+
+---
+
+## 2. WAL Checkpoints
+
+WAL files grow until checkpointed. better-sqlite3 enables automatic checkpointing by default, but manual control is available:
+
+```javascript
+// Check WAL size
+const walInfo = db.pragma("wal_checkpoint(PASSIVE)");
+// Returns: { busy: 0, checkpointed: N, log: N }
+
+// Force a full checkpoint (waits for readers)
+db.pragma("wal_checkpoint(TRUNCATE)");
+```
+
+### Checkpoint Strategies
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `PASSIVE` | Checkpoint pages not locked by readers | Background maintenance |
+| `FULL` | Wait for readers, then checkpoint all pages | Before backup |
+| `TRUNCATE` | Like FULL, then truncate WAL to zero | Reduce disk usage |
+| `RESTART` | Like FULL, then reset WAL to beginning | Reclaim WAL file space |
+
+Schedule periodic `PASSIVE` checkpoints in long-running applications. Use `TRUNCATE` before backup or deployment.
+
+---
+
+## 3. Prepared Statement Patterns
+
+### Caching Prepared Statements
+
+better-sqlite3 `prepare()` compiles the SQL once. Store references for reuse:
+
+```javascript
+class UserRepository {
+  constructor(db) {
+    this.db = db;
+    this.stmts = {
+      getById: db.prepare("SELECT * FROM users WHERE id = ?"),
+      getByEmail: db.prepare("SELECT * FROM users WHERE email = ?"),
+      insert: db.prepare(
+        "INSERT INTO users (email, name) VALUES (@email, @name) RETURNING *"
+      ),
+      update: db.prepare(
+        "UPDATE users SET name = @name WHERE id = @id RETURNING *"
+      ),
+      delete: db.prepare("DELETE FROM users WHERE id = ?"),
+    };
+  }
+
+  getById(id) {
+    return this.stmts.getById.get(id);
+  }
+
+  getByEmail(email) {
+    return this.stmts.getByEmail.get(email);
+  }
+
+  create(data) {
+    return this.stmts.insert.get(data);
+  }
+
+  update(id, data) {
+    return this.stmts.update.get({ ...data, id });
+  }
+
+  delete(id) {
+    return this.stmts.delete.run(id);
+  }
+}
+```
+
+### Iterate vs All
+
+Use `.iterate()` for large result sets to avoid loading everything into memory:
+
+```javascript
+const stmt = db.prepare("SELECT * FROM logs WHERE date > ?");
+
+// All at once (small result sets)
+const rows = stmt.all("2024-01-01");
+
+// Iterator (large result sets)
+for (const row of stmt.iterate("2024-01-01")) {
+  processRow(row);
+}
+```
+
+---
+
+## 4. Transaction Patterns
+
+### Basic Transactions
+
+```javascript
+const transferFunds = db.transaction((fromId, toId, amount) => {
+  const from = db.prepare("SELECT balance FROM accounts WHERE id = ?").get(fromId);
+  if (from.balance < amount) {
+    throw new Error("Insufficient funds");
+  }
+  db.prepare("UPDATE accounts SET balance = balance - ? WHERE id = ?").run(amount, fromId);
+  db.prepare("UPDATE accounts SET balance = balance + ? WHERE id = ?").run(amount, toId);
+});
+
+transferFunds(1, 2, 100);
+```
+
+The `db.transaction()` wrapper automatically commits on success and rolls back on error. Nested `db.transaction()` calls use savepoints.
+
+### Deferred vs Immediate
+
+```javascript
+const immediateTransaction = db.transaction(() => {
+  // Acquires write lock immediately
+  db.prepare("INSERT INTO logs (msg) VALUES (?)").run("action");
+});
+
+// Force IMMEDIATE mode for write transactions
+immediateTransaction.immediate();
+```
+
+Use `.immediate()` when the transaction will write, to avoid SQLITE_BUSY errors from lock promotion.
+
+---
+
+## 5. Cloudflare D1 Patterns
+
+### Batch Operations
+
+D1 batches execute all statements in a single round-trip as an implicit transaction:
+
+```javascript
+export default {
+  async fetch(request, env) {
+    const results = await env.DB.batch([
+      env.DB.prepare("INSERT INTO users (email) VALUES (?)").bind("alice@example.com"),
+      env.DB.prepare("INSERT INTO profiles (user_id, bio) VALUES (last_insert_rowid(), ?)").bind("Hello"),
+      env.DB.prepare("SELECT * FROM users WHERE email = ?").bind("alice@example.com"),
+    ]);
+
+    const user = results[2].results[0];
+    return Response.json(user);
+  },
+};
+```
+
+### D1 Query Helpers
+
+```javascript
+// .first() -- single row or null
+const user = await env.DB.prepare("SELECT * FROM users WHERE id = ?")
+  .bind(id)
+  .first();
+
+// .all() -- all rows with metadata
+const { results, meta } = await env.DB.prepare("SELECT * FROM users").all();
+// meta: { duration, rows_read, rows_written, changes }
+
+// .raw() -- array of arrays (no column names)
+const rows = await env.DB.prepare("SELECT id, email FROM users").raw();
+// [[1, "alice@example.com"], [2, "bob@example.com"]]
+
+// .run() -- for INSERT/UPDATE/DELETE
+const { meta } = await env.DB.prepare("DELETE FROM sessions WHERE expired < ?")
+  .bind(Date.now())
+  .run();
+```
+
+---
+
+## 6. D1 Migrations
+
+### File-Based Migrations
+
+D1 uses numbered SQL files in a `migrations/` directory:
+
+```
+migrations/
+├── 0001_create_users.sql
+├── 0002_add_posts.sql
+└── 0003_add_fts.sql
+```
+
+```sql
+-- 0001_create_users.sql
+CREATE TABLE users (
+    id INTEGER PRIMARY KEY,
+    email TEXT NOT NULL UNIQUE,
+    name TEXT,
+    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+```
+
+Apply migrations with Wrangler:
+
+```bash
+npx wrangler d1 migrations apply my-database        # production
+npx wrangler d1 migrations apply my-database --local # local dev
+```
+
+### Migration Best Practices
+
+- Each migration file should be idempotent where possible (use `IF NOT EXISTS`).
+- Never modify an already-applied migration -- create a new one.
+- Test migrations locally before applying to production.
+- D1 tracks applied migrations automatically; manual version tables are unnecessary.
+
+---
+
+## 7. Testing with Miniflare
+
+Miniflare provides a local D1 simulator for testing Workers without deploying:
+
+```javascript
+import { Miniflare } from "miniflare";
+
+const mf = new Miniflare({
+  modules: true,
+  script: `export default { async fetch(request, env) { return new Response("ok"); } }`,
+  d1Databases: ["DB"],
+});
+
+const db = await mf.getD1Database("DB");
+
+// Run migrations
+await db.exec(`
+  CREATE TABLE users (id INTEGER PRIMARY KEY, email TEXT NOT NULL);
+`);
+
+// Test queries
+await db.prepare("INSERT INTO users (email) VALUES (?)").bind("test@example.com").run();
+const user = await db.prepare("SELECT * FROM users WHERE email = ?")
+  .bind("test@example.com")
+  .first();
+console.assert(user.email === "test@example.com");
+
+await mf.dispose();
+```
+
+### Integration Test Pattern
+
+```javascript
+import { describe, it, beforeEach, afterAll } from "vitest";
+import { Miniflare } from "miniflare";
+
+describe("User API", () => {
+  let mf;
+  let db;
+
+  beforeEach(async () => {
+    mf = new Miniflare({ /* config */ });
+    db = await mf.getD1Database("DB");
+    await db.exec(SCHEMA_SQL);
+  });
+
+  afterAll(async () => {
+    await mf?.dispose();
+  });
+
+  it("creates a user", async () => {
+    await db.prepare("INSERT INTO users (email) VALUES (?)").bind("a@b.com").run();
+    const user = await db.prepare("SELECT * FROM users").first();
+    expect(user.email).toBe("a@b.com");
+  });
+});
+```