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

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
+// Interpolate it directly into a sql template — no sql.raw() needed. The
+// filter's placeholders and values are collected automatically and stay aligned.
+const query = sql`
+  SELECT * FROM users
+  WHERE ${result}
+`
 ```
 
-```bash
-npm install @truto/sqlite-builder
-```
+### Supported Operators
 
-```bash
-yarn add @truto/sqlite-builder
-```
+| Operator Family           | JSON Form                             | SQL Fragment                             | Description                         |
+| ------------------------- | ------------------------------------- | ---------------------------------------- | ----------------------------------- |
+| **Equality**              | `"field": value`                      | `"field" = ?`                            | Direct value comparison             |
+| **Inequality**            | `"field": { "ne": value }`            | `"field" <> ?`                           | Not equal comparison                |
+| **Comparison**            | `"field": { "gt": value }`            | `"field" > ?`                            | Greater than, gte, lt, lte          |
+| **Set Membership**        | `"field": { "in": [1, 2, 3] }`        | `"field" IN (?,?,?)`                     | Value in array                      |
+| **Negative Set**          | `"field": { "nin": [1, 2] }`          | `"field" NOT IN (?,?)`                   | Value not in array                  |
+| **NULL Checks**           | `"field": { "exists": false }`        | `"field" IS NULL`                        | Check for NULL/NOT NULL             |
+| **LIKE Patterns**         | `"field": { "like": "john%" }`        | `"field" LIKE ?`                         | Pattern matching                    |
+| **Case-insensitive LIKE** | `"field": { "ilike": "%DOE%" }`       | `"field" LIKE ? COLLATE NOCASE`          | Case-insensitive patterns           |
+| **Regular Expressions**   | `"field": { "regex": "^[A-Z]+" }`     | `"field" REGEXP ?`                       | Regex patterns (requires extension) |
+| **Logical AND**           | `"and": [filter1, filter2]`           | `(filter1 AND filter2)`                  | All conditions must match           |
+| **Logical OR**            | `"or": [filter1, filter2]`            | `(filter1 OR filter2)`                   | Any condition must match            |
+| **JSON Path**             | `"profile.email": "test@example.com"` | `json_extract("profile", '$.email') = ?` | Query JSON column fields            |
+| **Alias Blocks**          | `"$alias": { "field": value }`        | `alias."field" = ?`                      | Table/alias qualified fields        |
 
-```bash
-pnpm add @truto/sqlite-builder
-```
+### Filter Examples
 
-## 🚀 Quick Start
+#### Basic Operations
 
 ```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%' },
+// Equality and comparison
+const filter1 = {
+  status: 'ACTIVE',
   age: { gte: 18, lt: 65 },
-  or: [{ email: { regex: '.*@example.com$' } }, { phone: { exists: false } }],
+  score: { gt: 80, lte: 100 },
 }
+// SQL: (("status" = ? AND "age" >= ? AND "age" < ? AND "score" > ? AND "score" <= ?))
 
-// 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 },
-  },
+// Set membership
+const filter2 = {
+  role: { in: ['ADMIN', 'EDITOR'] },
+  department: { nin: ['ARCHIVED', 'DELETED'] },
 }
+// SQL: (("role" IN (?,?) AND "department" NOT IN (?,?)))
 
-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)}
-`
+// NULL checks
+const filter3 = {
+  email: { exists: true }, // IS NOT NULL
+  deleted_at: { exists: false }, // IS NULL
+}
+// SQL: (("email" IS NOT NULL AND "deleted_at" IS NULL))
 ```
 
-## 📖 API Reference
-
-### `sql` Tagged Template
-
-The main function for building SQL queries.
+#### Pattern Matching
 
 ```typescript
-const query = sql`SELECT * FROM users WHERE id = ${userId}`
-// Returns: { text: "SELECT * FROM users WHERE id = ?", values: [userId] }
-```
-
-**Parameters:**
-
-- Template strings and interpolated values
-- Returns a frozen `SqlQuery` object with `text` and `values` properties
+// LIKE patterns
+const filter4 = {
+  username: { like: 'john%' }, // Starts with 'john'
+  email: { ilike: '%@EXAMPLE.COM%' }, // Case-insensitive contains
+}
+// SQL: (("username" LIKE ? AND "email" LIKE ? COLLATE NOCASE))
 
-### `sql.ident(identifier: string | readonly (string | SqlFragment)[])`
+// Regular expressions (requires REGEXP extension)
+const filter5 = {
+  email: { regex: '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$' },
+  phone: { regex: '^\\+1[0-9]{10}$' },
+}
+// SQL: (("email" REGEXP ? AND "phone" REGEXP ?))
+```
 
-Safely quotes SQL identifiers (table names, column names, etc.). Accepts single identifiers, arrays of identifiers, or mixed arrays containing both identifiers and SQL fragments.
+#### Logical Operators
 
 ```typescript
-// Single identifier
-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: [] }
-
-// 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`,
-]
-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'] }
-
-// In INSERT statements
-const insertColumns = ['name', 'email', 'age']
-const insertQuery = sql`
-  INSERT INTO users (${sql.ident(insertColumns)}) 
-  VALUES (${name}, ${email}, ${age})
-`
-// Returns: { text: 'INSERT INTO users ("name", "email", "age") VALUES (?, ?, ?)', values: [name, email, age] }
-```
+// AND operator (explicit)
+const filter6 = {
+  and: [
+    { status: 'ACTIVE' },
+    { age: { gte: 18 } },
+    { country: { in: ['US', 'CA', 'GB'] } },
+  ],
+}
+// SQL: ((("status" = ?) AND ("age" >= ?) AND ("country" IN (?,?,?))))
+
+// OR operator
+const filter7 = {
+  or: [
+    { age: { lt: 18 } }, // Minors
+    { age: { gte: 65 } }, // Seniors
+  ],
+}
+// SQL: ((("age" < ?) OR ("age" >= ?)))
 
-**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.
+// Mixed AND/OR logic
+const filter8 = {
+  status: 'ACTIVE', // Implicit AND
+  or: [{ tags: { ilike: '%urgent%' } }, { priority: { gte: 8 } }],
+}
+// SQL: (((("tags" LIKE ? COLLATE NOCASE) OR ("priority" >= ?)) AND ("status" = ?)))
+```
 
-### `sql.in(array: readonly unknown[])`
+#### JSON Path Querying
 
-Creates parameterized IN clauses from arrays.
+For SQLite JSON columns, use dot notation to query nested fields:
 
 ```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] }
+// Query JSON fields
+const filter9 = {
+  'profile.email': { regex: '.*@example\\.org$' },
+  'profile.age': { gte: 21 },
+  'settings.theme': { in: ['dark', 'light'] },
+  'metadata.tags': { exists: true },
+}
+// SQL: ((json_extract("profile", '$.email') REGEXP ? AND
+//        json_extract("profile", '$.age') >= ? AND
+//        json_extract("settings", '$.theme') IN (?,?) AND
+//        json_extract("metadata", '$.tags') IS NOT NULL))
+
+// Complex nested JSON query
+const filter10 = {
+  and: [
+    { 'user.profile.email': { regex: '.*@company\\.com$' } },
+    { or: [{ 'user.role': 'ADMIN' }, { 'user.permissions.canEdit': true }] },
+  ],
+}
 ```
 
-**Features:**
-
-- Rejects empty arrays (would create invalid SQL)
-- Warns for arrays with >1000 items (performance consideration)
-
-### `sql.raw(rawSql: string)`
+#### Qualified Filters for JOINs
 
-Embeds raw SQL without parameterization. **⚠️ Use with extreme caution!**
+For complex queries involving multiple tables or aliases, use **alias blocks** with keys starting with `$`:
 
 ```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: [] }
-```
-
-**⚠️ 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.
+// Basic alias usage
+const joinFilter = {
+  // Main table fields (no prefix)
+  status: 'ACTIVE',
+  age: { gte: 18, lt: 65 },
 
-### `sql.join(fragments: SqlFragment[], separator?: string | SqlFragment)`
+  // Table alias 't2'
+  $t2: {
+    column_in_table_2: { gte: 100 },
+    'stats.avg': { lt: 10 }, // JSON path in aliased table
+  },
 
-Joins multiple SQL fragments with a separator.
+  // Table alias 'orders'
+  $orders: {
+    amount: { gt: 500 },
+    status: { in: ['completed', 'shipped'] },
+  },
+}
 
-```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] }
+const result = compileFilter(joinFilter)
+// SQL: ((("status" = ?) AND ("age" >= ? AND "age" < ?) AND
+//        ((t2."column_in_table_2" >= ?) AND (json_extract(t2."stats", '$.avg') < ?)) AND
+//        ((orders."amount" > ?) AND (orders."status" IN (?,?)))))
 ```
 
-**Fragments** must be library-minted fragments (forged `{ text, values }` objects are rejected).
+**Alias Block Rules:**
 
-**Separators** support any structural connector safely:
+- **Alias names**: Must be valid SQL identifiers (`[A-Za-z_][A-Za-z0-9_]*`)
+- **Prefixing**: All fields in alias blocks get prefixed with `alias.`
+- **JSON paths**: Work seamlessly with aliases: `json_extract(alias."column", '$.path')`
+- **Combination**: Alias blocks are AND-combined with root fields and each other
+- **Order**: Regular fields processed first, then alias blocks
 
-- 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.
+```typescript
+// Complex alias example with logical operators
+const complexJoinFilter = {
+  // Primary table conditions
+  user_status: 'ACTIVE',
 
-## 🔍 JSON Filter Language
+  // User profile table
+  $profile: {
+    verified: true,
+    'preferences.notifications': { ne: false },
+    or: [{ subscription_type: 'premium' }, { credits: { gte: 100 } }],
+  },
 
-Build complex WHERE clauses using MongoDB-style JSON filters. Perfect for APIs and dynamic queries.
+  // Orders table with complex conditions
+  $orders: {
+    and: [
+      { created_at: { gte: '2024-01-01' } },
+      { or: [{ total_amount: { gt: 1000 } }, { item_count: { gte: 5 } }] },
+    ],
+  },
+}
 
-### `compileFilter(filter: JsonFilter): FilterResult`
+// Use in JOIN queries
+const query = sql`
+  SELECT u.id, u.name, p.subscription_type, o.total_amount
+  FROM users u
+  JOIN profiles p ON u.id = p.user_id  
+  JOIN orders o ON u.id = o.user_id
+  WHERE ${compileFilter(complexJoinFilter)}
+`
+```
 
-Compiles a JSON filter object into a parameterized SQL WHERE clause.
+**Security & Validation:**
 
 ```typescript
-import { compileFilter } from '@truto/sqlite-builder'
+// ✅ Valid alias identifiers
+$users: { name: 'John' }        // Simple identifier
+$user_profiles: { age: 25 }     // Underscore allowed
+$_temp: { status: 'active' }    // Starting underscore allowed
+
+// ❌ Invalid alias identifiers (will throw SyntaxError)
+$123invalid: { ... }            // Cannot start with number
+$'invalid-alias': { ... }       // Hyphens not allowed
+$'table.alias': { ... }         // Dots not allowed in alias name
+```
 
-const filter = {
-  status: 'ACTIVE',
-  age: { gte: 18, lt: 65 },
-}
+**Integration with Complex Queries:**
+
+```typescript
+// Real-world JOIN example
+const userOrderFilter = {
+  // Users table
+  active: true,
+  email: { exists: true },
 
-const result = compileFilter(filter)
-// Returns a branded SQL fragment: { text: '(("status" = ?) AND ("age" >= ?) AND ("age" < ?))', values: ['ACTIVE', 18, 65] }
+  // User profiles
+  $profiles: {
+    'settings.email_notifications': true,

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.11","description":"debug canary","license":"MIT","main":"index.js"}