@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/references/base/filter-system/fields-order-pagination.md

@@ -28,21 +28,17 @@ await repo.find({
 ### Object Format
 
 ```typescript
-// Include specific fields
+// Include specific fields (only keys with `true` are selected)
 await repo.find({
   filter: {
     fields: { id: true, email: true, name: true }
   }
 });
-
-// Exclude specific fields
-await repo.find({
-  filter: {
-    fields: { password: false, secret: false }
-  }
-});
 ```
 
+> [!NOTE]
+> The object format only supports inclusion (`true` values). Keys set to `false` are simply ignored -- they do not exclude fields. To select specific fields, list the ones you want with `true` or use the array format.
+
 
 ## Ordering
 
@@ -65,6 +61,14 @@ await repo.find({
 });
 ```
 
+### Valid Directions
+
+Only `ASC` and `DESC` (case-insensitive) are accepted. Invalid directions throw an error:
+
+```
+Error: Invalid direction: 'RANDOM' | Expected: 'ASC' or 'DESC'
+```
+
 ### JSON Path Ordering
 
 Order by nested fields in JSON columns:
@@ -96,10 +100,10 @@ await repo.find({
 
 ### Limit and Skip/Offset
 
-Both `skip` and `offset` are supported as aliases — they both map to the SQL `OFFSET` clause. When both are provided, `skip` takes precedence.
+Both `skip` and `offset` are supported as aliases -- they both map to the SQL `OFFSET` clause. When both are provided, `skip` takes precedence.
 
 ```typescript
-// First 10 results
+// First 10 results (default limit is 10)
 await repo.find({
   filter: { limit: 10 }
 });
@@ -126,7 +130,7 @@ await repo.find({
 ```
 
 > [!TIP]
-> Always use `limit` for public-facing endpoints to prevent memory exhaustion.
+> Always use `limit` for public-facing endpoints to prevent memory exhaustion. The default limit is 10 if not specified.
 
 ### Pagination Helper
 
@@ -186,7 +190,7 @@ const contentRange = data.length > 0
   : `records */${range.total}`;
 
 res.setHeader('Content-Range', contentRange);
-// → "records 20-29/100"
+// -> "records 20-29/100"
 ```
 
 ### TDataRange Type
@@ -242,5 +246,5 @@ const { data, range } = await repo.find({
 });
 
 console.log(`Showing ${range.start}-${range.end} of ${range.total}`);
-// → "Showing 0-19 of 150"
+// -> "Showing 0-19 of 150"
 ```

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

@@ -45,17 +45,17 @@ Before reading this document, you should understand:
 
 ## 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.
+The `TFilter<T>` object is the core mechanism for querying data in Ignis. It provides a structured 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)
+  order?: string[];        // Sorting (SQL ORDER BY)
+  limit?: number;         // Max results (SQL LIMIT, default: 10)
   skip?: number;          // Pagination offset (SQL OFFSET)
   offset?: number;        // Alias for skip
-  include?: TInclusion[]; // Related data (SQL JOIN / subqueries)
+  include?: TInclusion[]; // Related data (Drizzle relational queries)
 };
 ```
 
@@ -69,7 +69,7 @@ type TFilter<T> = {
 | `order` | `ORDER BY` | Sort results |
 | `limit` | `LIMIT` | Restrict number of results |
 | `skip` / `offset` | `OFFSET` | Skip rows for pagination |
-| `include` | `JOIN` / subquery | Include related data |
+| `include` | Separate relational query | Include related data |
 
 
 ## Basic Example
@@ -86,7 +86,7 @@ const filter = {
 
 // Equivalent SQL
 // SELECT "id", "name", "email"
-// FROM "User"
+// FROM "users"
 // WHERE "status" = 'active' AND "role" = 'admin'
 // ORDER BY "created_at" DESC
 // LIMIT 10 OFFSET 0
@@ -98,20 +98,23 @@ const filter = {
 | Want to... | Filter Syntax |
 |------------|---------------|
 | Equals | `{ field: value }` or `{ field: { eq: value } }` |
-| Not equals | `{ field: { ne: value } }` |
+| Not equals | `{ field: { ne: value } }` or `{ field: { neq: 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] } }` |
+| Is not null | `{ field: { isn: null } }` or `{ field: { ne: null } }` |
+| In list | `{ field: { in: [a, b, c] } }` or `{ field: { inq: [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%' } }` |
+| Not contains pattern | `{ field: { nlike: '%pattern%' } }` |
 | Case-insensitive | `{ field: { ilike: '%pattern%' } }` |
+| Not case-insensitive | `{ field: { nilike: '%pattern%' } }` |
 | Regex match | `{ field: { regexp: '^pattern$' } }` |
+| Case-insensitive regex | `{ field: { iregexp: '^pattern$' } }` |
 | Array contains all | `{ arrayField: { contains: [a, b] } }` |
 | Array is subset | `{ arrayField: { containedBy: [a, b, c] } }` |
 | Array overlaps | `{ arrayField: { overlaps: [a, b] } }` |
@@ -121,7 +124,162 @@ const filter = {
 | 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'] }` |
+| Select fields | `{ fields: ['id', 'name'] }` or `{ fields: { id: true, name: true } }` |
 | Order by | `{ order: ['field DESC'] }` |
 | Order by JSON | `{ order: ['jsonField.path DESC'] }` |
-| Paginate | `{ limit: 10, skip: 20 }` |
+| Paginate | `{ limit: 10, skip: 20 }` or `{ limit: 10, offset: 20 }` |
+
+
+## Common Filter Patterns
+
+### Multi-Condition Search
+
+```typescript
+{
+  where: {
+    and: [
+      { age: { gte: 18, lte: 65 } }, // Between 18 and 65
+      { status: { in: ['active', 'pending'] } },
+      { or: [
+        { email: { ilike: '%@company.com' } },
+        { role: 'admin' }
+      ]}
+    ]
+  }
+}
+```
+
+### Text Search
+
+```typescript
+{
+  where: {
+    or: [
+      { name: { ilike: '%john%' } },
+      { email: { ilike: '%john%' } },
+      { username: { ilike: '%john%' } }
+    ]
+  }
+}
+```
+
+### Date Range
+
+```typescript
+{
+  where: {
+    createdAt: {
+      gte: new Date('2024-01-01'),
+      lt: new Date('2024-02-01')
+    }
+  }
+}
+```
+
+### Exclude Soft Deleted
+
+```typescript
+{
+  where: {
+    and: [
+      { isDeleted: false },
+      { status: 'active' }
+    ]
+  }
+}
+```
+
+### Multi-Tenant Filtering
+
+```typescript
+{
+  where: {
+    and: [
+      { tenantId: currentTenantId },
+      { isActive: true }
+    ]
+  }
+}
+```
+
+
+## Operator Precedence
+
+When combining operators, IGNIS follows standard SQL precedence:
+
+1. **AND** - Higher precedence
+2. **OR** - Lower precedence
+
+Use explicit nesting (via `and`/`or` arrays) for clarity:
+
+```typescript
+// Clear precedence
+{
+  where: {
+    and: [
+      { status: 'active' },
+      { or: [
+        { role: 'admin' },
+        { role: 'moderator' }
+      ]}
+    ]
+  }
+}
+```
+
+
+## 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,
+     skip: 0,
+     order: ['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/json-filtering.md

@@ -11,15 +11,18 @@ Query nested fields within JSON/JSONB columns using dot notation. This is a Post
 
 ## Basic JSON Path Syntax
 
+JSON paths are expressed as dot-notation keys in the `where` clause. A key is recognized as a JSON path if it contains a `.` or `[`.
+
 ```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'
+// SQL: CASE WHEN ("metadata" #>> '{user,id}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//      THEN ("metadata" #>> '{user,id}')::numeric ELSE NULL END = 123
 
-// Deep nesting
+// String field (no numeric casting)
 { where: { 'metadata.user.role': 'admin' } }
 // SQL: "metadata" #>> '{user,role}' = 'admin'
 
@@ -60,18 +63,26 @@ All standard operators work with JSON paths:
 // Between
 { where: { 'metadata.score': { between: [70, 90] } } }
 
-// Pattern matching
+// Pattern matching (text comparison, no numeric casting)
 { where: { 'metadata.level': { ilike: '%high%' } } }
 // SQL: "metadata" #>> '{level}' ILIKE '%high%'
 
-// IN operator
+// IN operator (text comparison)
 { where: { 'metadata.status': { in: ['pending', 'review'] } } }
+
+// Regex
+{ where: { 'metadata.code': { regexp: '^[A-Z]+$' } } }
+// SQL: "metadata" #>> '{code}' ~ '^[A-Z]+$'
+
+// Not equal
+{ where: { 'metadata.type': { ne: 'draft' } } }
+// SQL: "metadata" #>> '{type}' != 'draft'
 ```
 
 
 ## Safe Numeric Casting
 
-JSON fields may contain mixed types. Ignis uses safe casting to prevent database errors:
+When a numeric comparison operator (`gt`, `gte`, `lt`, `lte`, `between`, `notBetween`) is used with a JSON path, Ignis wraps the extraction in a safe CASE expression. This prevents database errors when JSON fields contain mixed types:
 
 ```typescript
 // Data in database:
@@ -82,6 +93,12 @@ JSON fields may contain mixed types. Ignis uses safe casting to prevent database
 // Query with numeric operator
 { where: { 'metadata.score': { gt: 50 } } }
 
+// Generated SQL:
+// CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//   THEN ("metadata" #>> '{score}')::numeric
+//   ELSE NULL
+// END > 50
+
 // Result:
 // Row 1: 85 > 50 -> matched
 // Row 2: "high" -> NULL -> not matched
@@ -91,19 +108,27 @@ JSON fields may contain mixed types. Ignis uses safe casting to prevent database
 | JSON Value | Numeric Operation Result |
 |------------|-------------------------|
 | `{ "score": 85 }` | Compares as `85` |
+| `{ "score": "85" }` | Compares as `85` (string passes regex) |
 | `{ "score": "high" }` | Treated as `NULL` (no match) |
 | `{ "score": null }` | Treated as `NULL` (no match) |
 
+Non-numeric operators (`eq`, `ne`, `like`, `ilike`, `in`, etc.) use text comparison via `#>>` without numeric casting.
 
-## Boolean Values
 
-Booleans are compared as TEXT strings:
+## Numeric Value Equality
+
+When a JSON path is compared to a number using direct equality (not an operator object), numeric casting is also applied:
 
 ```typescript
-// JSON data: { "enabled": true }
+{ where: { 'metadata.user.id': 123 } }
+// Uses numeric CASE expression since value is typeof number
+```
+
+When compared to a string, it uses text comparison:
 
-{ where: { 'metadata.enabled': true } }
-// SQL: "metadata" #>> '{enabled}' = 'true'
+```typescript
+{ where: { 'metadata.user.role': 'admin' } }
+// Uses "metadata" #>> '{user,role}' text comparison
 ```
 
 
@@ -112,13 +137,16 @@ Booleans are compared as TEXT strings:
 Order results by JSON fields:
 
 ```typescript
-{ filter: { order: ['metadata.priority DESC'] } }
+{ order: ['metadata.priority DESC'] }
 // SQL: ORDER BY "metadata" #> '{priority}' DESC
 
 // Multiple JSON fields
-{ filter: { order: ['metadata.priority DESC', 'metadata.score ASC'] } }
+{ order: ['metadata.priority DESC', 'metadata.score ASC'] }
 ```
 
+> [!NOTE]
+> JSON ordering uses `#>` (returns JSONB, preserves native types) unlike where clauses which use `#>>` (returns text). This means JSONB sort order applies.
+
 **Sort Order for JSONB Types:**
 
 | JSONB Type | Sort Order |
@@ -133,7 +161,7 @@ Order results by JSON fields:
 
 ## Path Validation & Security
 
-Path components are validated to prevent SQL injection:
+Path components are validated against the pattern `/^[a-zA-Z_][a-zA-Z0-9_-]*$|^\d+$/` to prevent SQL injection:
 
 ```typescript
 // Valid paths
@@ -145,7 +173,7 @@ Path components are validated to prevent SQL injection:
 
 // Invalid (throws error)
 'metadata.field;DROP TABLE'
-'data.123invalid'
+'data.123invalid'         // starts with digit (not array index context)
 'config.(SELECT * FROM users)'
 ```
 
@@ -158,6 +186,8 @@ Error: Column 'name' is not JSON/JSONB type | dataType: 'text'
 Error: Invalid JSON path component: 'field;DROP'
 ```
 
+The column referenced by the first path segment (before the first `.` or `[`) must be a `json` or `jsonb` column type. Using a JSON path on a non-JSON column throws an error.
+
 
 ## Performance Tips
 
@@ -169,16 +199,16 @@ CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
 
 2. **Use Appropriate Types in JSON:**
 ```json
-// Good
+// Good - numeric operators will work correctly
 { "priority": 3, "enabled": true }
 
-// Bad
+// Bad - numeric operators will need string-to-number casting
 { "priority": "3", "enabled": "true" }
 ```
 
 3. **Keep Paths Shallow:**
 ```typescript
-// Easier to work with
+// Easier to work with and index
 'metadata.priority'
 
 // Harder to optimize
@@ -193,7 +223,10 @@ CREATE INDEX idx_metadata_gin ON "Product" USING GIN ("metadata");
 // This is safe - no errors, just no matches
 { where: { 'metadata.nonexistent.field': 'value' } }
 // SQL: "metadata" #>> '{nonexistent,field}' = 'value'
+// Result: No rows (NULL != 'value')
+```
+
+
 ## See Also
 
 - [Nested JSON Updates](../repositories/advanced.md#nested-json-updates) - Updating JSON fields
-

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

@@ -11,7 +11,7 @@ Operators for matching values against arrays.
 
 ## in / inq - In Array
 
-Matches records where field value is in the provided array.
+Matches records where field value is in the provided array. `in` and `inq` are aliases and behave identically.
 
 ```typescript
 { where: { status: { in: ['active', 'pending', 'review'] } } }
@@ -37,9 +37,10 @@ Matches records where field value is in the provided array.
 
 | Scenario | Behavior |
 |----------|----------|
-| `{ in: [] }` (empty array) | Returns no rows (`false`) |
-| `{ nin: [] }` (empty array) | Returns all rows (`true`) |
+| `{ in: [] }` (empty array) | Returns no rows (`WHERE false`) |
+| `{ nin: [] }` (empty array) | Returns all rows (`WHERE true`) |
 | `{ in: 'value' }` (non-array) | Treated as `{ eq: 'value' }` |
+| `{ nin: 'value' }` (non-array) | Treated as `{ ne: 'value' }` |
 
 > [!WARNING]
 > `NOT IN` excludes rows where the column is `NULL`. If your column can be `NULL`, use `OR` to include them:

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

@@ -107,11 +107,12 @@ Combine AND and OR for complex logic:
 
 ## NOT Logic
 
-Use negation operators for NOT conditions:
+Ignis does not have a standalone `not` logical operator. Instead, use negation operators for NOT conditions:
 
 ```typescript
 // NOT equal
 { where: { status: { ne: 'deleted' } } }
+{ where: { status: { neq: 'deleted' } } }
 
 // NOT IN
 { where: { status: { nin: ['deleted', 'banned'] } } }
@@ -119,8 +120,12 @@ Use negation operators for NOT conditions:
 // NOT LIKE
 { where: { email: { nlike: '%@test.com' } } }
 
-// NOT NULL
+// NOT ILIKE
+{ where: { email: { nilike: '%@test.com' } } }
+
+// IS NOT NULL
 { where: { verifiedAt: { isn: null } } }
+{ where: { verifiedAt: { ne: null } } }
 
 // NOT BETWEEN
 { where: { score: { notBetween: [40, 60] } } }

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

@@ -9,6 +9,42 @@ difficulty: intermediate
 Operators for checking null and non-null values.
 
 
+## Direct Null Assignment
+
+The simplest way to check for NULL:
+
+```typescript
+// IS NULL (implicit)
+{ where: { deletedAt: null } }
+// SQL: WHERE "deleted_at" IS NULL
+```
+
+
+## eq with Null
+
+```typescript
+{ where: { deletedAt: { eq: null } } }
+// SQL: WHERE "deleted_at" IS NULL
+
+{ where: { status: { eq: 'active' } } }
+// SQL: WHERE "status" = 'active'
+```
+
+
+## ne / neq with Null
+
+```typescript
+// IS NOT NULL
+{ where: { deletedAt: { ne: null } } }
+{ where: { deletedAt: { neq: null } } }
+// SQL: WHERE "deleted_at" IS NOT NULL
+
+// Not equal to value
+{ where: { status: { ne: 'deleted' } } }
+// SQL: WHERE "status" != 'deleted'
+```
+
+
 ## is - IS NULL / Equality
 
 ```typescript
@@ -35,6 +71,20 @@ Operators for checking null and non-null values.
 ```
 
 
+## Null Check Summary
+
+| Syntax | SQL | Description |
+|--------|-----|-------------|
+| `{ field: null }` | `IS NULL` | Direct null check |
+| `{ field: { eq: null } }` | `IS NULL` | Explicit null equality |
+| `{ field: { is: null } }` | `IS NULL` | IS operator with null |
+| `{ field: { ne: null } }` | `IS NOT NULL` | Not-equal null check |
+| `{ field: { neq: null } }` | `IS NOT NULL` | Alias for ne with null |
+| `{ field: { isn: null } }` | `IS NOT NULL` | IS NOT operator with null |
+
+All six syntaxes for IS NULL / IS NOT NULL are equivalent -- use whichever reads best in context.
+
+
 ## Common Patterns
 
 ### Soft Delete Pattern