@venizia/ignis-docs 0.0.3 → 0.0.4-0

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 |

package/wiki/references/base/filter-system/quick-reference.md

@@ -0,0 +1,431 @@
+---
+title: Filter Operators Quick Reference
+description: Single-page cheat sheet of all filter operators
+difficulty: intermediate
+lastUpdated: 2026-01-03
+---
+
+# Filter Operators Quick Reference
+
+Complete single-page reference for all IGNIS filter operators. For detailed explanations and examples, see the individual operator guides.
+
+## Comparison Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `eq` | `=` | `{ status: { eq: 'active' } }` | Equal to |
+| `neq` | `!=` | `{ status: { neq: 'deleted' } }` | Not equal to |
+| `gt` | `>` | `{ age: { gt: 18 } }` | Greater than |
+| `gte` | `>=` | `{ age: { gte: 18 } }` | Greater than or equal |
+| `lt` | `<` | `{ price: { lt: 100 } }` | Less than |
+| `lte` | `<=` | `{ price: { lte: 100 } }` | Less than or equal |
+
+**See:** [Comparison Operators Guide](./comparison-operators.md)
+
+---
+
+## Range Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `between` | `BETWEEN` | `{ age: { between: [18, 65] } }` | Value is within range (inclusive) |
+| `notBetween` | `NOT BETWEEN` | `{ age: { notBetween: [0, 18] } }` | Value is outside range |
+
+**See:** [Range Operators Guide](./range-operators.md)
+
+---
+
+## List Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `in` / `inq` | `IN` | `{ status: { in: ['active', 'pending'] } }` | Value matches any in array |
+| `notIn` / `nin` | `NOT IN` | `{ status: { notIn: ['deleted', 'banned'] } }` | Value doesn't match any in array |
+
+**See:** [List Operators Guide](./list-operators.md)
+
+---
+
+## Pattern Matching Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `like` | `LIKE` | `{ name: { like: '%john%' } }` | Pattern match (case-sensitive) |
+| `ilike` | `ILIKE` | `{ email: { ilike: '%@gmail.com' } }` | Pattern match (case-insensitive) |
+| `notLike` | `NOT LIKE` | `{ name: { notLike: '%test%' } }` | Inverse pattern match (case-sensitive) |
+| `notILike` | `NOT ILIKE` | `{ email: { notILike: '%spam%' } }` | Inverse pattern match (case-insensitive) |
+| `startsWith` | `LIKE 'value%'` | `{ name: { startsWith: 'John' } }` | Starts with value |
+| `endsWith` | `LIKE '%value'` | `{ email: { endsWith: '@example.com' } }` | Ends with value |
+| `regexp` | `~` | `{ code: { regexp: '^[A-Z]{3}$' } }` | Regular expression (PostgreSQL) |
+| `iregexp` | `~*` | `{ code: { iregexp: '^[a-z]{3}$' } }` | Case-insensitive regex (PostgreSQL) |
+
+**Wildcard Patterns:**
+- `%` - Matches any sequence of characters
+- `_` - Matches any single character
+
+**See:** [Pattern Matching Guide](./pattern-matching.md)
+
+---
+
+## Null Check Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `isNull` | `IS NULL` | `{ deletedAt: { isNull: true } }` | Value is NULL |
+| `isNotNull` | `IS NOT NULL` | `{ email: { isNotNull: true } }` | Value is not NULL |
+
+**Alternative Syntax:**
+```typescript
+// Using 'is' operator
+{ deletedAt: { is: null } }     // IS NULL
+{ email: { is: { not: null } } } // IS NOT NULL
+```
+
+**See:** [Null Operators Guide](./null-operators.md)
+
+---
+
+## Logical Operators
+
+| Operator | SQL | TypeScript Example | Description |
+|----------|-----|-------------------|-------------|
+| `and` | `AND` | `{ and: [{ age: { gt: 18 } }, { status: 'active' }] }` | All conditions must be true |
+| `or` | `OR` | `{ or: [{ role: 'admin' }, { role: 'moderator' }] }` | At least one condition must be true |
+| `not` | `NOT` | `{ not: { status: 'deleted' } }` | Inverts the condition |
+
+**Implicit AND:**
+```typescript
+// Multiple fields = implicit AND
+{
+  status: 'active',
+  age: { gte: 18 },
+  role: 'user'
+}
+// WHERE status = 'active' AND age >= 18 AND role = 'user'
+```
+
+**See:** [Logical Operators Guide](./logical-operators.md)
+
+---
+
+## PostgreSQL Array Operators
+
+These operators work with PostgreSQL array columns (`varchar[]`, `text[]`, `integer[]`, etc.).
+
+| Operator | PostgreSQL | TypeScript Example | Description |
+|----------|------------|-------------------|-------------|
+| `contains` | `@>` | `{ tags: { contains: ['typescript', 'nodejs'] } }` | Array contains **ALL** specified elements |
+| `containedBy` | `<@` | `{ tags: { containedBy: ['ts', 'js', 'go', 'rust'] } }` | Array is subset of specified array |
+| `overlaps` | `&&` | `{ tags: { overlaps: ['react', 'vue', 'angular'] } }` | Arrays have at least one common element |
+
+**Important:** These are array-specific operators, not to be confused with `in`/`notIn` which match scalar values against an array.
+
+**See:** [Array Operators Guide](./array-operators.md)
+
+---
+
+## JSON/JSONB Operators (PostgreSQL)
+
+Query nested fields within JSON/JSONB columns using dot notation.
+
+### Basic JSON Path
+
+| Syntax | Example | Description |
+|--------|---------|-------------|
+| Dot notation | `metadata.user.name` | Access nested properties |
+| Array index | `metadata.tags[0]` | Access array elements |
+| Combined | `metadata.users[0].email` | Nested arrays and objects |
+
+### JSON Path with Filters
+
+```typescript
+// Query JSON field
+{
+  metadata: {
+    jsonPath: '$.user.name',
+    eq: 'John'
+  }
+}
+
+// Multiple JSON conditions
+{
+  and: [
+    { metadata: { jsonPath: '$.user.age', gt: 18 } },
+    { metadata: { jsonPath: '$.user.country', eq: 'US' } }
+  ]
+}
+```
+
+### Supported Operators with JSON
+
+All comparison operators work with JSON path queries:
+- `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
+- `in`, `notIn`
+- `like`, `ilike` (for string fields)
+- `isNull`, `isNotNull`
+
+**See:** [JSON Filtering Guide](./json-filtering.md)
+
+---
+
+## Fields, Ordering & Pagination
+
+### Select Specific Fields
+
+```typescript
+const users = await userRepo.find({
+  where: { isActive: true },
+  fields: ['id', 'name', 'email'], // Only return these fields
+});
+```
+
+### Ordering
+
+```typescript
+// Single field
+{ orderBy: { createdAt: 'desc' } }
+
+// Multiple fields
+{ orderBy: [
+  { createdAt: 'desc' },
+  { name: 'asc' }
+]}
+```
+
+### Pagination
+
+```typescript
+{
+  limit: 10,   // Max records to return
+  offset: 20,  // Skip first 20 records
+  orderBy: { id: 'asc' }
+}
+
+// Page 3 with 10 items per page
+{
+  limit: 10,
+  offset: 20, // (page - 1) * limit = (3 - 1) * 10
+  orderBy: { createdAt: 'desc' }
+}
+```
+
+**See:** [Fields, Ordering & Pagination Guide](./fields-order-pagination.md)
+
+---
+
+## Default Filters
+
+Automatically apply filters to all repository queries (e.g., soft delete, multi-tenant).
+
+```typescript
+import { model, DefaultFilterMixin } from '@venizia/ignis';
+
+@model()
+class User extends DefaultFilterMixin(BaseEntity) {
+  static readonly schema = pgTable('users', {
+    id: integer('id').primaryKey(),
+    name: text('name'),
+    isDeleted: boolean('is_deleted').default(false),
+  });
+
+  // Define default filter
+  static getDefaultFilter() {
+    return {
+      isDeleted: false, // Exclude deleted users by default
+    };
+  }
+}
+
+// All queries automatically exclude deleted users
+await userRepo.find({});
+// WHERE is_deleted = false
+
+// Skip default filter for admin operations
+await userRepo.find({
+  where: {},
+  options: { shouldSkipDefaultFilter: true },
+});
+// No automatic filter applied
+```
+
+**See:** [Default Filter Guide](./default-filter.md)
+
+---
+
+## Common Filter Patterns
+
+### Multi-Condition Search
+
+```typescript
+{
+  and: [
+    { age: { gte: 18, lte: 65 } }, // Between 18 and 65
+    { status: { in: ['active', 'pending'] } },
+    { or: [
+      { email: { endsWith: '@company.com' } },
+      { role: 'admin' }
+    ]}
+  ]
+}
+```
+
+### Text Search
+
+```typescript
+{
+  or: [
+    { name: { ilike: '%john%' } },
+    { email: { ilike: '%john%' } },
+    { username: { ilike: '%john%' } }
+  ]
+}
+```
+
+### Date Range
+
+```typescript
+{
+  createdAt: {
+    gte: new Date('2024-01-01'),
+    lt: new Date('2024-02-01')
+  }
+}
+```
+
+### Exclude Soft Deleted
+
+```typescript
+{
+  and: [
+    { isDeleted: false },
+    { status: 'active' }
+  ]
+}
+```
+
+### Multi-Tenant Filtering
+
+```typescript
+{
+  and: [
+    { tenantId: currentTenantId },
+    { isActive: true }
+  ]
+}
+```
+
+---
+
+## Operator Precedence
+
+When combining operators, IGNIS follows standard SQL precedence:
+
+1. **NOT** - Highest precedence
+2. **AND** - Medium precedence
+3. **OR** - Lowest precedence
+
+Use explicit parentheses (via nested `and`/`or`) for clarity:
+
+```typescript
+// Clear precedence
+{
+  and: [
+    { status: 'active' },
+    { or: [
+      { role: 'admin' },
+      { role: 'moderator' }
+    ]}
+  ]
+}
+```
+
+---
+
+## Type Safety
+
+All filter operators are fully typed based on your model schema:
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  age: number;
+  email: string;
+  tags: string[];
+}
+
+// ✅ Type-safe filters
+await userRepo.find({
+  where: {
+    age: { gt: 18 },        // number operators
+    name: { like: '%john%' }, // string operators
+    tags: { contains: ['typescript'] } // array operators
+  }
+});
+
+// ❌ TypeScript error: wrong operator for type
+await userRepo.find({
+  where: {
+    age: { like: '%18%' } // Error: 'like' not valid for numbers
+  }
+});
+```
+
+---
+
+## Performance Tips
+
+1. **Index frequently filtered columns:**
+   ```sql
+   CREATE INDEX idx_users_status ON users(status);
+   CREATE INDEX idx_posts_created_at ON posts(created_at DESC);
+   ```
+
+2. **Use `eq` instead of `like` when possible:**
+   ```typescript
+   // ✅ Fast: Uses index
+   { status: { eq: 'active' } }
+
+   // ❌ Slower: Full table scan
+   { status: { like: 'active' } }
+   ```
+
+3. **Limit array contains operations:**
+   ```typescript
+   // Better performance with smaller arrays
+   { tags: { contains: ['typescript'] } } // ✅ Good
+   { tags: { contains: ['tag1', 'tag2', /* ... 100 tags */] } } // ❌ Slow
+   ```
+
+4. **Use pagination for large result sets:**
+   ```typescript
+   {
+     where: { isActive: true },
+     limit: 100,
+     offset: 0,
+     orderBy: { id: 'asc' }
+   }
+   ```
+
+---
+
+## See Also
+
+- **Detailed Guides:**
+  - [Comparison Operators](./comparison-operators.md)
+  - [Logical Operators](./logical-operators.md)
+  - [Pattern Matching](./pattern-matching.md)
+  - [JSON Filtering](./json-filtering.md)
+  - [Array Operators](./array-operators.md)
+
+- **Related References:**
+  - [Repositories](../repositories/) - Using filters in repository queries
+  - [Models](../models.md) - Defining model schemas
+
+- **Usage Guides:**
+  - [Application Usage](./application-usage.md) - Filters in the full stack
+  - [Use Case Gallery](./use-cases.md) - Real-world examples
+  - [Pro Tips & Edge Cases](./tips.md) - Advanced patterns
+
+- **Quick Reference:**
+  - [Main Quick Reference](/references/quick-reference.md) - All IGNIS APIs

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

@@ -0,0 +1,63 @@
+---
+title: Range Operators
+description: Operators for matching values within or outside a range
+difficulty: intermediate
+---
+
+# Range Operators
+
+Operators for matching values within or outside a range.
+
+
+## between
+
+Find values within a range (inclusive):
+
+```typescript
+// Numeric range
+{ where: { price: { between: [100, 500] } } }
+// SQL: WHERE "price" BETWEEN 100 AND 500
+
+// Date range
+{
+  where: {
+    createdAt: {
+      between: [new Date('2024-01-01'), new Date('2024-12-31')]
+    }
+  }
+}
+// SQL: WHERE "created_at" BETWEEN '2024-01-01' AND '2024-12-31'
+
+// String range (lexicographic)
+{ where: { lastName: { between: ['A', 'M'] } } }
+// SQL: WHERE "last_name" BETWEEN 'A' AND 'M'
+```
+
+> [!WARNING]
+> The value MUST be an array with exactly 2 elements `[min, max]`. Invalid values throw an error.
+
+
+## notBetween
+
+Find values outside a range:
+
+```typescript
+{ where: { score: { notBetween: [40, 60] } } }
+// SQL: WHERE NOT ("score" BETWEEN 40 AND 60)
+// Matches: scores < 40 OR scores > 60
+```
+
+
+## Alternative: Using gte/lte
+
+You can also express ranges using comparison operators:
+
+```typescript
+// Equivalent to between: [100, 500]
+{ where: { price: { gte: 100, lte: 500 } } }
+// SQL: WHERE "price" >= 100 AND "price" <= 500
+
+// Exclusive range (not including boundaries)
+{ where: { price: { gt: 100, lt: 500 } } }
+// SQL: WHERE "price" > 100 AND "price" < 500
+```