@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/references/base/filter-system/index.md

@@ -0,0 +1,127 @@
+---
+title: Filter System Overview
+description: Complete reference for the IGNIS filter system
+difficulty: intermediate
+---
+
+# Filter System
+
+Complete reference for the Ignis filter system - operators, JSON filtering, array operators, default filters, and query patterns.
+
+> [!NOTE]
+> If you're new to Ignis, start with:
+> - [5-Minute Quickstart](/guides/get-started/5-minute-quickstart) - Get up and running
+> - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Learn the basics
+> - [Repositories](/references/base/repositories) - Repository overview
+
+## Prerequisites
+
+Before reading this document, you should understand:
+
+- [Repositories](../repositories/) - Basic repository operations (find, create, update, delete)
+- [Models](../models.md) - Entity definitions and schemas
+- SQL basics - Understanding of WHERE clauses and operators
+- TypeScript type system - Type safety and inference
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [**⚡ Quick Reference**](./quick-reference.md) | **Single-page cheat sheet of all operators** |
+| [Comparison Operators](./comparison-operators.md) | Equality, range, null checks |
+| [Pattern Matching](./pattern-matching.md) | LIKE, ILIKE, regex |
+| [Logical Operators](./logical-operators.md) | AND, OR combinations |
+| [List Operators](./list-operators.md) | IN, NOT IN |
+| [Range Operators](./range-operators.md) | BETWEEN, NOT BETWEEN |
+| [Null Operators](./null-operators.md) | IS NULL, IS NOT NULL |
+| [Array Operators](./array-operators.md) | PostgreSQL array operations |
+| [JSON Filtering](./json-filtering.md) | JSON/JSONB path queries |
+| [Fields, Order, Pagination](./fields-order-pagination.md) | SELECT, ORDER BY, LIMIT |
+| [**Default Filter**](./default-filter.md) | Automatic filter application |
+| [Application Usage](./application-usage.md) | Filter flow in applications |
+| [Tips & Best Practices](./tips.md) | Performance and patterns |
+| [Use Cases](./use-cases.md) | Real-world examples |
+
+
+## Filter Structure
+
+The `Filter<T>` object is the core mechanism for querying data in Ignis. It provides a structured, type-safe way to express complex queries without writing raw SQL.
+
+```typescript
+type TFilter<T> = {
+  where?: TWhere<T>;      // Query conditions (SQL WHERE)
+  fields?: TFields<T>;    // Column selection (SQL SELECT)
+  order?: string[];       // Sorting (SQL ORDER BY)
+  limit?: number;         // Max results (SQL LIMIT)
+  skip?: number;          // Pagination offset (SQL OFFSET)
+  offset?: number;        // Alias for skip
+  include?: TInclusion[]; // Related data (SQL JOIN / subqueries)
+};
+```
+
+
+## SQL Mapping Overview
+
+| Filter Property | SQL Equivalent | Purpose |
+|-----------------|----------------|---------|
+| `where` | `WHERE` | Filter rows by conditions |
+| `fields` | `SELECT col1, col2` | Select specific columns |
+| `order` | `ORDER BY` | Sort results |
+| `limit` | `LIMIT` | Restrict number of results |
+| `skip` / `offset` | `OFFSET` | Skip rows for pagination |
+| `include` | `JOIN` / subquery | Include related data |
+
+
+## Basic Example
+
+```typescript
+// Filter object
+const filter = {
+  where: { status: 'active', role: 'admin' },
+  fields: ['id', 'name', 'email'],
+  order: ['createdAt DESC'],
+  limit: 10,
+  skip: 0
+};
+
+// Equivalent SQL
+// SELECT "id", "name", "email"
+// FROM "User"
+// WHERE "status" = 'active' AND "role" = 'admin'
+// ORDER BY "created_at" DESC
+// LIMIT 10 OFFSET 0
+```
+
+
+## Quick Reference
+
+| Want to... | Filter Syntax |
+|------------|---------------|
+| Equals | `{ field: value }` or `{ field: { eq: value } }` |
+| Not equals | `{ field: { ne: value } }` |
+| Greater than | `{ field: { gt: value } }` |
+| Greater or equal | `{ field: { gte: value } }` |
+| Less than | `{ field: { lt: value } }` |
+| Less or equal | `{ field: { lte: value } }` |
+| Is null | `{ field: null }` or `{ field: { is: null } }` |
+| Is not null | `{ field: { isn: null } }` |
+| In list | `{ field: { in: [a, b, c] } }` |
+| Not in list | `{ field: { nin: [a, b, c] } }` |
+| Range | `{ field: { between: [min, max] } }` |
+| Outside range | `{ field: { notBetween: [min, max] } }` |
+| Contains pattern | `{ field: { like: '%pattern%' } }` |
+| Case-insensitive | `{ field: { ilike: '%pattern%' } }` |
+| Regex match | `{ field: { regexp: '^pattern$' } }` |
+| Array contains all | `{ arrayField: { contains: [a, b] } }` |
+| Array is subset | `{ arrayField: { containedBy: [a, b, c] } }` |
+| Array overlaps | `{ arrayField: { overlaps: [a, b] } }` |
+| JSON nested | `{ 'jsonField.nested.path': value }` |
+| JSON with operator | `{ 'jsonField.path': { gt: 10 } }` |
+| AND conditions | `{ a: 1, b: 2 }` or `{ and: [{a: 1}, {b: 2}] }` |
+| OR conditions | `{ or: [{ a: 1 }, { b: 2 }] }` |
+| Include relation | `{ include: [{ relation: 'name' }] }` |
+| Nested include | `{ include: [{ relation: 'a', scope: { include: [{ relation: 'b' }] } }] }` |
+| Select fields | `{ fields: ['id', 'name'] }` |
+| Order by | `{ order: ['field DESC'] }` |
+| Order by JSON | `{ order: ['jsonField.path DESC'] }` |
+| Paginate | `{ limit: 10, skip: 20 }` |

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 } } }
+```