@venizia/ignis-docs 0.0.2 → 0.0.4-0

package/wiki/references/base/filter-system/json-filtering.md

@@ -0,0 +1,197 @@
+---
+title: JSON/JSONB Filtering
+description: Query nested fields within JSON/JSONB columns using dot notation
+difficulty: intermediate
+---
+
+# JSON/JSONB Filtering
+
+Query nested fields within JSON/JSONB columns using dot notation. This is a PostgreSQL-specific feature.
+
+
+## Basic JSON Path Syntax
+
+```typescript
+// Column: metadata jsonb
+// Data: { "user": { "id": 123, "role": "admin" }, "tags": ["urgent"] }
+
+// Simple nested field
+{ where: { 'metadata.user.id': 123 } }
+// SQL: "metadata" #>> '{user,id}' = '123'
+
+// Deep nesting
+{ where: { 'metadata.user.role': 'admin' } }
+// SQL: "metadata" #>> '{user,role}' = 'admin'
+
+// Array index access
+{ where: { 'metadata.tags[0]': 'urgent' } }
+// SQL: "metadata" #>> '{tags,0}' = 'urgent'
+
+// Kebab-case keys
+{ where: { 'metadata.user-id': 'abc123' } }
+// SQL: "metadata" #>> '{user-id}' = 'abc123'
+```
+
+
+## Supported Path Formats
+
+| Format | Example | SQL Path |
+|--------|---------|----------|
+| Simple field | `metadata.name` | `{name}` |
+| Nested field | `metadata.user.email` | `{user,email}` |
+| Array index | `metadata.tags[0]` | `{tags,0}` |
+| Nested with array | `metadata.items[2].name` | `{items,2,name}` |
+| Kebab-case | `metadata.user-id` | `{user-id}` |
+
+
+## JSON with Operators
+
+All standard operators work with JSON paths:
+
+```typescript
+// Numeric comparison (automatic safe casting)
+{ where: { 'metadata.score': { gt: 80 } } }
+// SQL: CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//      THEN ("metadata" #>> '{score}')::numeric ELSE NULL END > 80
+
+// Range comparison
+{ where: { 'metadata.priority': { gte: 1, lte: 5 } } }
+
+// Between
+{ where: { 'metadata.score': { between: [70, 90] } } }
+
+// Pattern matching
+{ where: { 'metadata.level': { ilike: '%high%' } } }
+// SQL: "metadata" #>> '{level}' ILIKE '%high%'
+
+// IN operator
+{ where: { 'metadata.status': { in: ['pending', 'review'] } } }
+```
+
+
+## Safe Numeric Casting
+
+JSON fields may contain mixed types. Ignis uses safe casting to prevent database errors:
+
+```typescript
+// Data in database:
+// Row 1: { "score": 85 }      <- number
+// Row 2: { "score": "high" }  <- string
+// Row 3: { "score": null }    <- null
+
+// Query with numeric operator
+{ where: { 'metadata.score': { gt: 50 } } }
+
+// Result:
+// Row 1: 85 > 50 -> matched
+// Row 2: "high" -> NULL -> not matched
+// Row 3: null -> NULL -> not matched
+```
+
+| JSON Value | Numeric Operation Result |
+|------------|-------------------------|
+| `{ "score": 85 }` | Compares as `85` |
+| `{ "score": "high" }` | Treated as `NULL` (no match) |
+| `{ "score": null }` | Treated as `NULL` (no match) |
+
+
+## Boolean Values
+
+Booleans are compared as TEXT strings:
+
+```typescript
+// JSON data: { "enabled": true }
+
+{ where: { 'metadata.enabled': true } }
+// SQL: "metadata" #>> '{enabled}' = 'true'
+```
+
+
+## JSON Path Ordering
+
+Order results by JSON fields:
+
+```typescript
+{ filter: { order: ['metadata.priority DESC'] } }
+// SQL: ORDER BY "metadata" #> '{priority}' DESC
+
+// Multiple JSON fields
+{ filter: { order: ['metadata.priority DESC', 'metadata.score ASC'] } }
+```
+
+**Sort Order for JSONB Types:**
+
+| JSONB Type | Sort Order |
+|------------|------------|
+| `null` | First (lowest) |
+| `boolean` | `false` < `true` |
+| `number` | Numeric order |
+| `string` | Lexicographic |
+| `array` | Element-wise |
+| `object` | Key-value |
+
+
+## Path Validation & Security
+
+Path components are validated to prevent SQL injection:
+
+```typescript
+// Valid paths
+'metadata.fieldName'
+'metadata.nested.deep.value'
+'data.items[0]'
+'config.user_id'
+'data.meta-data'  // kebab-case allowed
+
+// Invalid (throws error)
+'metadata.field;DROP TABLE'
+'data.123invalid'
+'config.(SELECT * FROM users)'
+```
+
+**Error Messages:**
+```
+// Non-JSON column
+Error: Column 'name' is not JSON/JSONB type | dataType: 'text'
+
+// Invalid path
+Error: Invalid JSON path component: 'field;DROP'
+```
+
+
+## Performance Tips
+
+1. **Index Your JSON Paths:**
+```sql
+CREATE INDEX idx_metadata_priority ON "Product" (("metadata" ->> 'priority'));
+CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
+```
+
+2. **Use Appropriate Types in JSON:**
+```json
+// Good
+{ "priority": 3, "enabled": true }
+
+// Bad
+{ "priority": "3", "enabled": "true" }
+```
+
+3. **Keep Paths Shallow:**
+```typescript
+// Easier to work with
+'metadata.priority'
+
+// Harder to optimize
+'data.level1.level2.level3.level4.value'
+```
+
+
+## Null-Safe JSON Paths
+
+```typescript
+// If JSON field doesn't exist, #>> returns NULL
+// This is safe - no errors, just no matches
+{ where: { 'metadata.nonexistent.field': 'value' } }
+// SQL: "metadata" #>> '{nonexistent,field}' = 'value'
+// Result: No rows (NULL != 'value')
+```

package/wiki/references/base/filter-system/list-operators.md

@@ -0,0 +1,71 @@
+---
+title: List Operators
+description: Operators for matching values against arrays
+difficulty: intermediate
+---
+
+# List Operators
+
+Operators for matching values against arrays.
+
+
+## in / inq - In Array
+
+Matches records where field value is in the provided array.
+
+```typescript
+{ where: { status: { in: ['active', 'pending', 'review'] } } }
+{ where: { status: { inq: ['active', 'pending', 'review'] } } }  // Alias
+
+// SQL: WHERE "status" IN ('active', 'pending', 'review')
+
+// Numeric IDs
+{ where: { categoryId: { in: [1, 2, 3, 4, 5] } } }
+// SQL: WHERE "category_id" IN (1, 2, 3, 4, 5)
+```
+
+
+## nin - Not In Array
+
+```typescript
+{ where: { status: { nin: ['deleted', 'archived', 'banned'] } } }
+// SQL: WHERE "status" NOT IN ('deleted', 'archived', 'banned')
+```
+
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| `{ in: [] }` (empty array) | Returns no rows (`false`) |
+| `{ nin: [] }` (empty array) | Returns all rows (`true`) |
+| `{ in: 'value' }` (non-array) | Treated as `{ eq: 'value' }` |
+
+> [!WARNING]
+> `NOT IN` excludes rows where the column is `NULL`. If your column can be `NULL`, use `OR` to include them:
+> ```typescript
+> where: {
+>   or: [
+>     { status: { nin: ['deleted'] } },
+>     { status: { is: null } }
+>   ]
+> }
+> ```
+
+
+## Performance Tip
+
+```typescript
+// For very large arrays (1000+ items), consider chunking
+const allIds = getLargeIdList();  // 5000 IDs
+
+const chunkSize = 500;
+const results = [];
+for (let i = 0; i < allIds.length; i += chunkSize) {
+  const chunk = allIds.slice(i, i + chunkSize);
+  const chunkResults = await repo.find({
+    filter: { where: { id: { in: chunk } } }
+  });
+  results.push(...chunkResults);
+}
+```

package/wiki/references/base/filter-system/logical-operators.md

@@ -0,0 +1,156 @@
+---
+title: Logical Operators
+description: Combine multiple conditions with AND and OR logic
+difficulty: intermediate
+---
+
+# Logical Operators
+
+Combine multiple conditions with AND and OR logic.
+
+
+## Implicit AND
+
+Multiple conditions in the same object are combined with AND:
+
+```typescript
+{
+  where: {
+    status: 'active',
+    role: 'admin',
+    verified: true,
+  }
+}
+// SQL: WHERE "status" = 'active' AND "role" = 'admin' AND "verified" = true
+```
+
+
+## Explicit AND
+
+Use `and` array for explicit AND conditions:
+
+```typescript
+{
+  where: {
+    and: [
+      { status: 'active' },
+      { role: { in: ['admin', 'moderator'] } },
+      { createdAt: { gte: new Date('2024-01-01') } },
+    ]
+  }
+}
+// SQL: WHERE ("status" = 'active')
+//        AND ("role" IN ('admin', 'moderator'))
+//        AND ("created_at" >= '2024-01-01')
+```
+
+
+## OR Operator
+
+Use `or` array for OR conditions:
+
+```typescript
+{
+  where: {
+    or: [
+      { status: 'active' },
+      { isPublished: true },
+      { featured: true },
+    ]
+  }
+}
+// SQL: WHERE ("status" = 'active')
+//         OR ("is_published" = true)
+//         OR ("featured" = true)
+```
+
+
+## Nested AND/OR
+
+Combine AND and OR for complex logic:
+
+```typescript
+// (status = 'active' AND verified = true) OR (role = 'admin')
+{
+  where: {
+    or: [
+      {
+        and: [
+          { status: 'active' },
+          { verified: true },
+        ]
+      },
+      { role: 'admin' },
+    ]
+  }
+}
+
+// status = 'active' AND (role = 'admin' OR role = 'moderator')
+{
+  where: {
+    status: 'active',
+    or: [
+      { role: 'admin' },
+      { role: 'moderator' },
+    ]
+  }
+}
+// Equivalent to:
+{
+  where: {
+    status: 'active',
+    role: { in: ['admin', 'moderator'] },
+  }
+}
+```
+
+
+## NOT Logic
+
+Use negation operators for NOT conditions:
+
+```typescript
+// NOT equal
+{ where: { status: { ne: 'deleted' } } }
+
+// NOT IN
+{ where: { status: { nin: ['deleted', 'banned'] } } }
+
+// NOT LIKE
+{ where: { email: { nlike: '%@test.com' } } }
+
+// NOT NULL
+{ where: { verifiedAt: { isn: null } } }
+
+// NOT BETWEEN
+{ where: { score: { notBetween: [40, 60] } } }
+```
+
+
+## Complex Example
+
+```typescript
+// Find active products that are either:
+// - Featured with high rating, OR
+// - On sale with good stock
+{
+  where: {
+    status: 'active',
+    deletedAt: { is: null },
+    or: [
+      {
+        and: [
+          { featured: true },
+          { rating: { gte: 4.5 } }
+        ]
+      },
+      {
+        and: [
+          { onSale: true },
+          { stock: { gte: 10 } }
+        ]
+      }
+    ]
+  }
+}
+```

package/wiki/references/base/filter-system/null-operators.md

@@ -0,0 +1,58 @@
+---
+title: Null Check Operators
+description: Operators for checking null and non-null values
+difficulty: intermediate
+---
+
+# Null Check Operators
+
+Operators for checking null and non-null values.
+
+
+## is - IS NULL / Equality
+
+```typescript
+// NULL check
+{ where: { deletedAt: { is: null } } }
+// SQL: WHERE "deleted_at" IS NULL
+
+// Value check (same as eq)
+{ where: { status: { is: 'active' } } }
+// SQL: WHERE "status" = 'active'
+```
+
+
+## isn - IS NOT NULL / Not Equality
+
+```typescript
+// NOT NULL check
+{ where: { verifiedAt: { isn: null } } }
+// SQL: WHERE "verified_at" IS NOT NULL
+
+// Value check (same as ne)
+{ where: { status: { isn: 'deleted' } } }
+// SQL: WHERE "status" != 'deleted'
+```
+
+
+## Common Patterns
+
+### Soft Delete Pattern
+
+```typescript
+// Find active records (not deleted)
+{ where: { deletedAt: { is: null } } }
+
+// Find deleted records only
+{ where: { deletedAt: { isn: null } } }
+```
+
+### Verified Users
+
+```typescript
+// Find verified users
+{ where: { emailVerifiedAt: { isn: null } } }
+
+// Find unverified users
+{ where: { emailVerifiedAt: { is: null } } }
+```

package/wiki/references/base/filter-system/pattern-matching.md

@@ -0,0 +1,108 @@
+---
+title: Pattern Matching Operators
+description: Operators for string pattern matching and regular expressions
+difficulty: intermediate
+---
+
+# Pattern Matching Operators
+
+Operators for string pattern matching and regular expressions.
+
+
+## like - Pattern Matching (Case-Sensitive)
+
+Matches strings using SQL LIKE patterns.
+
+```typescript
+// Starts with
+{ where: { email: { like: '%@gmail.com' } } }
+// SQL: WHERE "email" LIKE '%@gmail.com'
+
+// Contains
+{ where: { name: { like: '%john%' } } }
+// SQL: WHERE "name" LIKE '%john%'
+
+// Ends with
+{ where: { filename: { like: '%.pdf' } } }
+// SQL: WHERE "filename" LIKE '%.pdf'
+
+// Single character wildcard
+{ where: { code: { like: 'A_B' } } }  // Matches 'A1B', 'AXB', etc.
+// SQL: WHERE "code" LIKE 'A_B'
+```
+
+**Pattern Characters:**
+- `%` - Matches any sequence of characters (including empty)
+- `_` - Matches exactly one character
+
+
+## nlike - Not Like
+
+```typescript
+{ where: { email: { nlike: '%@test.com' } } }
+// SQL: WHERE "email" NOT LIKE '%@test.com'
+```
+
+
+## ilike - Case-Insensitive Pattern Matching
+
+PostgreSQL-specific case-insensitive LIKE.
+
+```typescript
+{ where: { name: { ilike: '%john%' } } }
+// SQL: WHERE "name" ILIKE '%john%'
+// Matches: 'John', 'JOHN', 'john', 'JoHn'
+
+{ where: { email: { ilike: '%@GMAIL.COM' } } }
+// Matches: 'user@gmail.com', 'USER@Gmail.Com'
+```
+
+
+## nilike - Not ILike
+
+```typescript
+{ where: { email: { nilike: '%@example%' } } }
+// SQL: WHERE NOT ("email" ILIKE '%@example%')
+```
+
+
+## regexp - Regular Expression (Case-Sensitive)
+
+PostgreSQL POSIX regex matching.
+
+```typescript
+// Starts with letter
+{ where: { code: { regexp: '^[A-Z]' } } }
+// SQL: WHERE "code" ~ '^[A-Z]'
+
+// Email pattern
+{ where: { email: { regexp: '^[a-z]+@[a-z]+\\.[a-z]+$' } } }
+// SQL: WHERE "email" ~ '^[a-z]+@[a-z]+\.[a-z]+$'
+
+// Phone number pattern
+{ where: { phone: { regexp: '^\\+?[0-9]{10,15}$' } } }
+```
+
+> [!NOTE]
+> Escape backslashes in TypeScript strings: `\\d` for regex `\d`.
+
+
+## iregexp - Case-Insensitive Regular Expression
+
+```typescript
+{ where: { name: { iregexp: '^john' } } }
+// SQL: WHERE "name" ~* '^john'
+// Matches: 'John Doe', 'JOHN SMITH', 'john'
+```
+
+
+## Summary
+
+| Operator | SQL | Case | Description |
+|----------|-----|------|-------------|
+| `like` | `LIKE` | Sensitive | Pattern with wildcards |
+| `nlike` | `NOT LIKE` | Sensitive | Negative pattern |
+| `ilike` | `ILIKE` | Insensitive | PostgreSQL only |
+| `nilike` | `NOT ILIKE` | Insensitive | PostgreSQL only |
+| `regexp` | `~` | Sensitive | POSIX regex match |
+| `iregexp` | `~*` | Insensitive | POSIX regex match |