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

package/README.md

@@ -0,0 +1,225 @@
+
+// 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}
+`
+```
+
+### Supported Operators
+
+| 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        |
+
+### Filter Examples
+
+#### Basic Operations
+
+```typescript
+// Equality and comparison
+const filter1 = {
+  status: 'ACTIVE',
+  age: { gte: 18, lt: 65 },
+  score: { gt: 80, lte: 100 },
+}
+// SQL: (("status" = ? AND "age" >= ? AND "age" < ? AND "score" > ? AND "score" <= ?))
+
+// Set membership
+const filter2 = {
+  role: { in: ['ADMIN', 'EDITOR'] },
+  department: { nin: ['ARCHIVED', 'DELETED'] },
+}
+// SQL: (("role" IN (?,?) AND "department" NOT IN (?,?)))
+
+// 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))
+```
+
+#### Pattern Matching
+
+```typescript
+// 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))
+
+// 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 ?))
+```
+
+#### Logical Operators
+
+```typescript
+// 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" >= ?)))
+
+// 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" = ?)))
+```
+
+#### JSON Path Querying
+
+For SQLite JSON columns, use dot notation to query nested fields:
+
+```typescript
+// 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 }] },
+  ],
+}
+```
+
+#### Qualified Filters for JOINs
+
+For complex queries involving multiple tables or aliases, use **alias blocks** with keys starting with `$`:
+
+```typescript
+// Basic alias usage
+const joinFilter = {
+  // Main table fields (no prefix)
+  status: 'ACTIVE',
+  age: { gte: 18, lt: 65 },
+
+  // Table alias 't2'
+  $t2: {
+    column_in_table_2: { gte: 100 },
+    'stats.avg': { lt: 10 }, // JSON path in aliased table
+  },
+
+  // Table alias 'orders'
+  $orders: {
+    amount: { gt: 500 },
+    status: { in: ['completed', 'shipped'] },
+  },
+}
+
+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 (?,?)))))
+```
+
+**Alias Block Rules:**
+
+- **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
+
+```typescript
+// Complex alias example with logical operators
+const complexJoinFilter = {
+  // Primary table conditions
+  user_status: 'ACTIVE',
+
+  // User profile table
+  $profile: {
+    verified: true,
+    'preferences.notifications': { ne: false },
+    or: [{ subscription_type: 'premium' }, { credits: { gte: 100 } }],
+  },
+
+  // Orders table with complex conditions
+  $orders: {
+    and: [
+      { created_at: { gte: '2024-01-01' } },
+      { or: [{ total_amount: { gt: 1000 } }, { item_count: { gte: 5 } }] },
+    ],
+  },
+}
+
+// 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)}
+`
+```
+
+**Security & Validation:**
+
+```typescript
+// ✅ 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
+```
+
+**Integration with Complex Queries:**
+
+```typescript
+// Real-world JOIN example
+const userOrderFilter = {
+  // Users table
+  active: true,
+  email: { exists: true },
+
+  // User profiles
+  $profiles: {
+    'settings.email_notifications': true,

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