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

package/README.md

@@ -0,0 +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
+```
+
+```bash
+pnpm add @truto/sqlite-builder
+```
+
+## 🚀 Quick Start
+
+```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] }
+```
+
+**Parameters:**
+
+- Template strings and interpolated values
+- Returns a frozen `SqlQuery` object with `text` and `values` properties
+
+### `sql.ident(identifier: string | readonly (string | SqlFragment)[])`
+
+Safely quotes SQL identifiers (table names, column names, etc.). Accepts single identifiers, arrays of identifiers, or mixed arrays containing both identifiers and SQL fragments.
+
+```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] }
+```
+
+**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.
+
+### `sql.in(array: readonly unknown[])`
+
+Creates parameterized IN clauses from arrays.
+
+```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] }
+```
+
+**Features:**
+
+- Rejects empty arrays (would create invalid SQL)
+- Warns for arrays with >1000 items (performance consideration)
+
+### `sql.raw(rawSql: string)`
+
+Embeds raw SQL without parameterization. **⚠️ Use with extreme caution!**
+
+```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.
+
+### `sql.join(fragments: SqlFragment[], separator?: string | SqlFragment)`
+
+Joins multiple SQL fragments with a separator.
+
+```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] }
+```
+
+**Fragments** must be library-minted fragments (forged `{ text, values }` objects are rejected).
+
+**Separators** support any structural connector safely:
+
+- 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.
+
+## 🔍 JSON Filter Language
+
+Build complex WHERE clauses using MongoDB-style JSON filters. Perfect for APIs and dynamic queries.
+
+### `compileFilter(filter: JsonFilter): FilterResult`
+
+Compiles a JSON filter object into a parameterized SQL WHERE clause.
+
+```typescript
+import { compileFilter } from '@truto/sqlite-builder'
+
+const filter = {
+  status: 'ACTIVE',
+  age: { gte: 18, lt: 65 },
+}
+
+const result = compileFilter(filter)
+// Returns a branded SQL fragment: { text: '(("status" = ?) AND ("age" >= ?) AND ("age" < ?))', values: ['ACTIVE', 18, 65] }

package/package.json

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