@truto/sqlite-builder 2.0.2-canary.10 → 2.0.2-canary.13

package/README.md

@@ -1,225 +1,225 @@
-# 🏗️ truto-sqlite-builder
 
-[![npm version](https://badge.fury.io/js/%40truto%2Fsqlite-builder.svg)](https://badge.fury.io/js/%40truto%2Fsqlite-builder)
-[![CI](https://github.com/trutohq/truto-sqlite-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/trutohq/truto-sqlite-builder/actions/workflows/ci.yml)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-**Safe, zero-dependency template-literal tag for SQLite queries in any JS environment.**
-
-`@truto/sqlite-builder` provides a secure and ergonomic way to build SQLite queries using tagged template literals. It prevents SQL injection attacks through parameterized queries while offering convenient helper functions for common SQL patterns.
-
-## ✨ Features
-
-- 🔒 **Injection-safe**: All values are parameterized, preventing SQL injection
-- 🚫 **Defense in depth**: Multiple security layers including stacked query detection
-- 🪶 **Zero dependencies**: Pure TypeScript/JavaScript with no runtime dependencies
-- 🌍 **Universal**: Works in Bun, Node.js, Deno, and modern browsers
-- 🎯 **TypeScript-first**: Full type safety with excellent IDE support
-- 🔧 **Helper functions**: Built-in utilities for identifiers, IN clauses, and more
-- 🔍 **JSON Filter Language**: MongoDB-style JSON filters for WHERE clauses
-- 🔗 **Qualified Filters**: Table/alias scoping for complex JOINs using `$alias` blocks
-- ⚡ **Lightweight**: Minimal bundle size with tree-shaking support
-
-## 📦 Installation
-
-```bash
-bun add @truto/sqlite-builder
-```
-
-```bash
-npm install @truto/sqlite-builder
-```
-
-```bash
-yarn add @truto/sqlite-builder
-```
+// Dynamic column selection (simplified with array support)
+const columns = ['id', 'name', 'email']
+const selectQuery = sql`SELECT ${sql.ident(columns)} FROM users`
 
-```bash
-pnpm add @truto/sqlite-builder
+// Alternative approach for more complex column expressions
+const complexColumns = [
+  sql.ident('id'),
+  sql.ident('name'),
+  sql.raw('UPPER(email) as email_upper'),
+]
+const complexQuery = sql`SELECT ${sql.join(complexColumns)} FROM users`
 ```
 
-## 🚀 Quick Start
+### Dynamic Queries with JSON Filters
 
 ```typescript
-import sqlite3 from 'better-sqlite3'
 import { sql, compileFilter } from '@truto/sqlite-builder'
 
-const db = new sqlite3('database.db')
-
-// Simple query
-const name = 'Alice'
-const { text, values } = sql`SELECT * FROM users WHERE name = ${name}`
-const users = db.prepare(text).all(...values)
-
-// JSON Filter queries
-const filter = {
-  name: { like: 'John%' },
-  age: { gte: 18, lt: 65 },
-  or: [{ email: { regex: '.*@example.com$' } }, { phone: { exists: false } }],
-}
-
-// Interpolate the compiled filter directly: its placeholders and values are
-// collected automatically, so query.values is always correctly aligned.
-const query = sql`
-  SELECT * FROM users
-  WHERE ${compileFilter(filter)}
-`
-
-const results = db.prepare(query.text).all(...query.values)
-
-// Qualified filters for JOINs with alias blocks
-const joinFilter = {
-  status: 'ACTIVE', // Main table
-  $profiles: {
-    // Profile table alias
-    verified: true,
-    'settings.theme': 'dark', // JSON path in profile
-  },
-  $orders: {
-    // Orders table alias
-    total: { gt: 100 },
-  },
-}
-
-const joinQuery = sql`
-  SELECT u.name, p.verified, o.total
-  FROM users u
-  JOIN profiles p ON u.id = p.user_id
-  JOIN orders o ON u.id = o.user_id  
-  WHERE ${compileFilter(joinFilter)}
-`
-```
-
-## 📖 API Reference
-
-### `sql` Tagged Template
-
-The main function for building SQL queries.
-
-```typescript
-const query = sql`SELECT * FROM users WHERE id = ${userId}`
-// Returns: { text: "SELECT * FROM users WHERE id = ?", values: [userId] }
+// API endpoint that accepts JSON filter
+app.get('/api/users', (req, res) => {
+  // User sends filter as JSON
+  const filter = req.body.filter || {}
+
+  // Safely compile to SQL and interpolate directly. Filter values and the
+  // LIMIT value are collected in order into query.values.
+  const query = sql`
+    SELECT id, name, email, created_at
+    FROM users
+    WHERE ${compileFilter(filter)}
+    ORDER BY created_at DESC
+    LIMIT ${req.query.limit || 20}
+  `
+
+  const users = db.prepare(query.text).all(...query.values)
+  res.json(users)
+})
+
+// Example API calls:
+// POST /api/users { "filter": { "status": "ACTIVE", "age": { "gte": 18 } } }
+// POST /api/users { "filter": { "or": [{ "role": "ADMIN" }, { "verified": true }] } }
 ```
 
-**Parameters:**
-
-- Template strings and interpolated values
-- Returns a frozen `SqlQuery` object with `text` and `values` properties
-
-### `sql.ident(identifier: string | readonly (string | SqlFragment)[])`
+### Array Identifiers & Qualified Identifiers
 
-Safely quotes SQL identifiers (table names, column names, etc.). Accepts single identifiers, arrays of identifiers, or mixed arrays containing both identifiers and SQL fragments.
+The `sql.ident()` function supports simple identifiers, qualified identifiers (table.column), arrays, and mixed arrays with SQL fragments:
 
 ```typescript
-// Single identifier
+// ✅ Simple identifiers
 const table = 'users'
-const query = sql`SELECT * FROM ${sql.ident(table)}`
-// Returns: { text: 'SELECT * FROM "users"', values: [] }
-
-// Qualified identifiers (table.column)
-const qualifiedQuery = sql`SELECT ${sql.ident('u.name')}, ${sql.ident('u.email')} FROM users u`
-// Returns: { text: 'SELECT "u"."name", "u"."email" FROM users u', values: [] }
-
-// Array of identifiers (useful for column lists)
-const columns = ['name', 'email', 'created_at']
-const selectQuery = sql`SELECT ${sql.ident(columns)} FROM users`
-// Returns: { text: 'SELECT "name", "email", "created_at" FROM users', values: [] }
-
-// Mixed arrays with qualified and simple identifiers
-const mixedColumns = ['u.id', 'name', 'u.email', 'p.title']
-const joinQuery = sql`SELECT ${sql.ident(mixedColumns)} FROM users u JOIN posts p ON u.id = p.user_id`
-// Returns: { text: 'SELECT "u"."id", "name", "u"."email", "p"."title" FROM users u JOIN posts p ON u.id = p.user_id', values: [] }
-
-// Mixed arrays with identifiers and SQL fragments
-const mixedColumns = ['id', 'name', sql.raw('UPPER(email) as email_upper')]
-const mixedQuery = sql`SELECT ${sql.ident(mixedColumns)} FROM users`
-// Returns: { text: 'SELECT "id", "name", UPPER(email) as email_upper FROM users', values: [] }
+const column = 'name'
+const simpleQuery = sql`SELECT ${sql.ident(column)} FROM ${sql.ident(table)}`
+// Result: SELECT "name" FROM "users"
+
+// ✅ Qualified identifiers (table.column)
+const qualifiedQuery = sql`SELECT ${sql.ident('u.name')}, ${sql.ident('p.title')} FROM users u JOIN posts p ON u.id = p.user_id`
+// Result: SELECT "u"."name", "p"."title" FROM users u JOIN posts p ON u.id = p.user_id
+
+// ✅ Pure identifier arrays (clean and concise)
+const columns = ['id', 'name', 'email', 'created_at']
+const arrayQuery = sql`SELECT ${sql.ident(columns)} FROM users`
+// Result: SELECT "id", "name", "email", "created_at" FROM users
+
+// ✅ Mixed qualified and simple identifiers in arrays
+const mixedColumns = ['u.id', 'name', 'u.email', 'p.title', 'created_at']
+const mixedQuery = sql`SELECT ${sql.ident(mixedColumns)} FROM users u LEFT JOIN posts p ON u.id = p.user_id`
+// Result: SELECT "u"."id", "name", "u"."email", "p"."title", "created_at" FROM users u LEFT JOIN posts p ON u.id = p.user_id
+
+// ✅ NEW: Mixed arrays with identifiers and SQL fragments
+const mixedColumns = [
+  'id',
+  'name',
+  sql.raw('UPPER(email) as email_upper'),
+  sql.raw('COUNT(*) as total'),
+]
+const mixedQuery = sql`SELECT ${sql.ident(mixedColumns)} FROM users GROUP BY id, name, email`
+// Result: SELECT "id", "name", UPPER(email) as email_upper, COUNT(*) as total FROM users GROUP BY id, name, email
 
-// Mixed arrays with parameterized fragments
+// ✅ Mixed arrays with parameterized fragments
 const status = 'premium'
 const dynamicColumns = [
   'id',
   'name',
-  sql`CASE WHEN status = ${status} THEN 'Premium' ELSE 'Regular' END as user_type`,
+  sql`CASE WHEN status = ${status} THEN 'Premium User' ELSE 'Regular User' END as user_type`,
+  sql.raw('created_at'),
 ]
-const dynamicQuery = sql`SELECT ${sql.ident(dynamicColumns)} FROM users`
-// Returns: { text: 'SELECT "id", "name", CASE WHEN status = ? THEN \'Premium\' ELSE \'Regular\' END as user_type FROM users', values: ['premium'] }
+const parameterizedQuery = sql`SELECT ${sql.ident(dynamicColumns)} FROM users WHERE active = ${true}`
+// Combines identifiers, raw SQL, and parameterized values seamlessly
 
-// In INSERT statements
-const insertColumns = ['name', 'email', 'age']
+// ✅ Works great for INSERT statements
+const insertData = { name: 'John', email: 'john@example.com', age: 30 }
+const insertColumns = Object.keys(insertData)
+const insertValues = Object.values(insertData)
 const insertQuery = sql`
   INSERT INTO users (${sql.ident(insertColumns)}) 
-  VALUES (${name}, ${email}, ${age})
+  VALUES (${insertValues[0]}, ${insertValues[1]}, ${insertValues[2]})
 `
-// Returns: { text: 'INSERT INTO users ("name", "email", "age") VALUES (?, ?, ?)', values: [name, email, age] }
+
+// ✅ Dynamic column selection
+const userFields = ['name', 'email']
+const includeTimestamps = true
+if (includeTimestamps) {
+  userFields.push('created_at', 'updated_at')
+}
+const dynamicQuery = sql`SELECT ${sql.ident(userFields)} FROM users`
+
+// 🆚 OLD: Manual joining approach (still works, but much more verbose)
+const oldWay = sql`SELECT ${sql.join([
+  sql.ident('id'),
+  sql.ident('name'),
+  sql.raw('UPPER(email) as email_upper'),
+])} FROM users`
 ```
 
-**Security:** Only accepts valid ANSI identifiers (simple: `name`, qualified: `table.column`) for string elements, each capped at 255 characters. SQL fragments are passed through as-is, but **only fragments minted by this library** (e.g. `sql.raw`, nested `sql\`\``) are accepted — a plain `{ text, values }`object (for example from`JSON.parse`) is rejected, so untrusted data can never masquerade as raw SQL.
+### Complex Joins
+
+```typescript
+const getUsersWithPosts = sql`
+  SELECT 
+    ${sql.ident('u')}.id,
+    ${sql.ident('u')}.name,
+    COUNT(${sql.ident('p')}.id) as post_count
+  FROM ${sql.ident('users')} u
+  LEFT JOIN ${sql.ident('posts')} p ON u.id = p.user_id
+  WHERE u.created_at > ${startDate}
+    AND u.status IN ${sql.in(['active', 'premium'])}
+  GROUP BY u.id
+  HAVING post_count > ${minPosts}
+  ORDER BY post_count DESC
+  LIMIT ${limit}
+`
 
-### `sql.in(array: readonly unknown[])`
+// For simpler cases, you can use array identifiers directly
+const getUsers = sql`
+  SELECT ${sql.ident(['id', 'name', 'email', 'created_at'])}
+  FROM ${sql.ident('users')}
+  WHERE status = ${'active'}
+`
+```
 
-Creates parameterized IN clauses from arrays.
+### Transactions
 
 ```typescript
-const ids = [1, 2, 3]
-const query = sql`SELECT * FROM users WHERE id IN ${sql.in(ids)}`
-// Returns: { text: "SELECT * FROM users WHERE id IN (?,?,?)", values: [1, 2, 3] }
+// Works great with better-sqlite3 transactions
+const insertUsers = db.transaction((users) => {
+  const stmt = db.prepare(
+    sql`
+    INSERT INTO users (name, email) 
+    VALUES (?, ?)
+  `.text,
+  )
+
+  for (const user of users) {
+    const { values } = sql`${user.name}, ${user.email}`
+    stmt.run(...values)
+  }
+})
+
+insertUsers([
+  { name: 'Alice', email: 'alice@example.com' },
+  { name: 'Bob', email: 'bob@example.com' },
+])
 ```
 
-**Features:**
+## 🧪 Testing
 
-- Rejects empty arrays (would create invalid SQL)
-- Warns for arrays with >1000 items (performance consideration)
+```bash
+# Run tests
+bun run test
 
-### `sql.raw(rawSql: string)`
+# Run tests in watch mode
+bun run dev
 
-Embeds raw SQL without parameterization. **⚠️ Use with extreme caution!**
+# Run tests with coverage
+bun run test:coverage
 
-```typescript
-const query = sql`SELECT * FROM users WHERE created_at > ${sql.raw('datetime("now", "-1 day")')}`
-// Returns: { text: 'SELECT * FROM users WHERE created_at > datetime("now", "-1 day")', values: [] }
+# Run tests with UI
+bun run test:ui
 ```
 
-**⚠️ Warning:** `sql.raw()` is the library's single, explicit trust boundary — its argument becomes SQL verbatim. Never pass user input to it. For dynamic WHERE clauses use `compileFilter()`; for identifiers use `sql.ident()`. As a safety net, the `sql` tag verifies that the number of `?` placeholders in the final query exactly matches the number of bound values, so a raw fragment that smuggles a stray `?` (or forgets to carry its value) throws instead of producing a misaligned query.
+## 🤝 Contributing
 
-### `sql.join(fragments: SqlFragment[], separator?: string | SqlFragment)`
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
-Joins multiple SQL fragments with a separator.
+### Development Setup
 
-```typescript
-const conditions = [
-  sql`name = ${'John'}`,
-  sql`age = ${30}`,
-  sql`active = ${true}`,
-]
-
-const query = sql`SELECT * FROM users WHERE ${sql.join(conditions, ' AND ')}`
-// Returns: { text: "SELECT * FROM users WHERE name = ? AND age = ? AND active = ?", values: ['John', 30, true] }
+```bash
+git clone https://github.com/truto/truto-sqlite-builder.git
+cd truto-sqlite-builder
+bun install
+bun run dev  # Start tests in watch mode
 ```
 
-**Fragments** must be library-minted fragments (forged `{ text, values }` objects are rejected).
+### Release Process
 
-**Separators** support any structural connector safely:
+We use [changesets](https://github.com/changesets/changesets) for version management:
 
-- A **string** separator (e.g. `', '`, `' AND '`, `' UNION ALL '`) is validated to be a pure connector. Separators containing string/identifier quotes (`'`, `"`, `` ` ``, `[`, `]`), statement terminators (`;`), comment markers (`--`, `/*`, `*/`), `NUL`, backslashes, or unbalanced parentheses are rejected — so even an untrusted separator cannot break out of the expression.
-- A **`SqlFragment`** separator (e.g. `sql\` OR weight = ${w} OR \``) lets you parameterize the connector itself; its values are interleaved between fragments automatically.
+```bash
+# Add a changeset
+bunx changeset
+
+# Release
+bunx changeset version
+bun run build
+git commit -am "Release"
+git push --follow-tags
+```
 
-## 🔍 JSON Filter Language
+## 🔒 Security Policy
 
-Build complex WHERE clauses using MongoDB-style JSON filters. Perfect for APIs and dynamic queries.
+If you discover a security vulnerability, please email eng@truto.one or create an issue.
 
-### `compileFilter(filter: JsonFilter): FilterResult`
+## 📄 License
 
-Compiles a JSON filter object into a parameterized SQL WHERE clause.
+MIT © [Truto](https://github.com/trutohq)
 
-```typescript
-import { compileFilter } from '@truto/sqlite-builder'
+## 💡 Inspiration
 
-const filter = {
-  status: 'ACTIVE',
-  age: { gte: 18, lt: 65 },
-}
+This library was inspired by:
+
+- [sql-template-strings](https://github.com/felixfbecker/sql-template-strings)
+- [slonik](https://github.com/gajus/slonik)
+- [Postgres.js](https://github.com/porsager/postgres)
 
-const result = compileFilter(filter)
-// Returns a branded SQL fragment: { text: '(("status" = ?) AND ("age" >= ?) AND ("age" < ?))', values: ['ACTIVE', 18, 65] }
+Built with ❤️ for the SQLite community.

package/package.json

@@ -1 +1 @@
-{"name":"@truto/sqlite-builder","version":"2.0.2-canary.10","description":"debug canary","license":"MIT","main":"index.js"}
+{"name":"@truto/sqlite-builder","version":"2.0.2-canary.13","description":"debug canary","license":"MIT","main":"index.js"}