@venizia/ignis-docs 0.0.7 → 0.0.8-0

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

@@ -2,7 +2,7 @@
 title: Filter Operators Quick Reference
 description: Single-page cheat sheet of all filter operators
 difficulty: intermediate
-lastUpdated: 2026-01-03
+lastUpdated: 2026-03-15
 ---
 
 # Filter Operators Quick Reference
@@ -14,7 +14,8 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 | Operator | SQL | TypeScript Example | Description |
 |----------|-----|-------------------|-------------|
 | `eq` | `=` | `{ status: { eq: 'active' } }` | Equal to |
-| `neq` | `!=` | `{ status: { neq: 'deleted' } }` | Not equal to |
+| `ne` | `!=` | `{ status: { ne: 'deleted' } }` | Not equal to |
+| `neq` | `!=` | `{ status: { neq: 'deleted' } }` | Not equal to (alias for `ne`) |
 | `gt` | `>` | `{ age: { gt: 18 } }` | Greater than |
 | `gte` | `>=` | `{ age: { gte: 18 } }` | Greater than or equal |
 | `lt` | `<` | `{ price: { lt: 100 } }` | Less than |
@@ -37,8 +38,9 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 
 | 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 |
+| `in` | `IN` | `{ status: { in: ['active', 'pending'] } }` | Value matches any in array |
+| `inq` | `IN` | `{ status: { inq: ['active', 'pending'] } }` | Alias for `in` |
+| `nin` | `NOT IN` | `{ status: { nin: ['deleted', 'banned'] } }` | Value doesn't match any in array |
 
 **See:** [List Operators Guide](./list-operators.md)
 
@@ -48,11 +50,9 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 | Operator | SQL | TypeScript Example | Description |
 |----------|-----|-------------------|-------------|
 | `like` | `LIKE` | `{ name: { like: '%john%' } }` | Pattern match (case-sensitive) |
+| `nlike` | `NOT LIKE` | `{ name: { nlike: '%test%' } }` | Inverse 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 |
+| `nilike` | `NOT ILIKE` | `{ email: { nilike: '%spam%' } }` | Inverse pattern match (case-insensitive) |
 | `regexp` | `~` | `{ code: { regexp: '^[A-Z]{3}$' } }` | Regular expression (PostgreSQL) |
 | `iregexp` | `~*` | `{ code: { iregexp: '^[a-z]{3}$' } }` | Case-insensitive regex (PostgreSQL) |
 
@@ -67,14 +67,22 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 
 | 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 |
+| `is` | `IS NULL` / `=` | `{ deletedAt: { is: null } }` | IS NULL when value is `null`, equality otherwise |
+| `isn` | `IS NOT NULL` / `!=` | `{ email: { isn: null } }` | IS NOT NULL when value is `null`, not-equal otherwise |
 
-**Alternative Syntax:**
+**Shorthand Syntax:**
 ```typescript
-// Using 'is' operator
-{ deletedAt: { is: null } }     // IS NULL
-{ email: { is: { not: null } } } // IS NOT NULL
+// Direct null assignment (implicit IS NULL)
+{ deletedAt: null }
+// SQL: WHERE "deleted_at" IS NULL
+
+// Using eq with null
+{ deletedAt: { eq: null } }
+// SQL: WHERE "deleted_at" IS NULL
+
+// Using ne with null
+{ deletedAt: { ne: null } }
+// SQL: WHERE "deleted_at" IS NOT NULL
 ```
 
 **See:** [Null Operators Guide](./null-operators.md)
@@ -86,7 +94,6 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 |----------|-----|-------------------|-------------|
 | `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
@@ -99,6 +106,8 @@ Complete single-page reference for all IGNIS filter operators. For detailed expl
 // WHERE status = 'active' AND age >= 18 AND role = 'user'
 ```
 
+**NOT logic** is expressed via negation operators (`ne`, `neq`, `nin`, `nlike`, `nilike`, `notBetween`, `isn`).
+
 **See:** [Logical Operators Guide](./logical-operators.md)
 
 
@@ -112,50 +121,57 @@ These operators work with PostgreSQL array columns (`varchar[]`, `text[]`, `inte
 | `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.
+**Important:** These are array-specific operators, not to be confused with `in`/`nin` 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.
+Query nested fields within JSON/JSONB columns using dot notation as the key.
 
-### Basic JSON Path
+### JSON Path Syntax
 
 | 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 |
+| Dot notation | `{ 'metadata.user.name': 'John' }` | Access nested properties |
+| Array index | `{ 'metadata.tags[0]': 'urgent' }` | Access array elements |
+| Combined | `{ 'metadata.users[0].email': value }` | Nested arrays and objects |
 
-### JSON Path with Filters
+### JSON Path with Operators
 
 ```typescript
-// Query JSON field
-{
-  metadata: {
-    jsonPath: '$.user.name',
-    eq: 'John'
-  }
-}
+// Equality (string comparison via #>>)
+{ 'metadata.user.role': 'admin' }
+// SQL: "metadata" #>> '{user,role}' = 'admin'
+
+// Numeric comparison (safe casting via CASE/numeric)
+{ 'metadata.score': { gt: 80 } }
+
+// Pattern matching
+{ 'metadata.level': { ilike: '%high%' } }
+// SQL: "metadata" #>> '{level}' ILIKE '%high%'
 
 // Multiple JSON conditions
 {
   and: [
-    { metadata: { jsonPath: '$.user.age', gt: 18 } },
-    { metadata: { jsonPath: '$.user.country', eq: 'US' } }
+    { 'metadata.user.age': { gt: 18 } },
+    { 'metadata.user.country': 'US' }
   ]
 }
 ```
 
-### Supported Operators with JSON
+### Supported Operators with JSON Paths
 
 All comparison operators work with JSON path queries:
-- `eq`, `neq`, `gt`, `gte`, `lt`, `lte`
-- `in`, `notIn`
-- `like`, `ilike` (for string fields)
-- `isNull`, `isNotNull`
+- `eq`, `ne`, `neq`, `gt`, `gte`, `lt`, `lte`
+- `in`, `inq`, `nin`
+- `like`, `nlike`, `ilike`, `nilike`
+- `between`, `notBetween`
+- `regexp`, `iregexp`
+- `is`, `isn`
+
+Numeric operators (`gt`, `gte`, `lt`, `lte`, `between`, `notBetween`) use safe numeric casting to handle mixed JSON value types.
 
 **See:** [JSON Filtering Guide](./json-filtering.md)
 
@@ -166,8 +182,10 @@ All comparison operators work with JSON path queries:
 
 ```typescript
 const users = await userRepo.find({
-  where: { isActive: true },
-  fields: ['id', 'name', 'email'], // Only return these fields
+  filter: {
+    where: { isActive: true },
+    fields: ['id', 'name', 'email'], // Only return these fields
+  }
 });
 ```
 
@@ -175,29 +193,30 @@ const users = await userRepo.find({
 
 ```typescript
 // Single field
-{ orderBy: { createdAt: 'desc' } }
+{ order: ['createdAt DESC'] }
 
 // Multiple fields
-{ orderBy: [
-  { createdAt: 'desc' },
-  { name: 'asc' }
-]}
+{ order: ['status ASC', 'createdAt DESC'] }
+
+// Default direction is ASC
+{ order: ['name'] }  // Same as 'name ASC'
+
+// JSON path ordering
+{ order: ['metadata.priority DESC'] }
 ```
 
 ### Pagination
 
 ```typescript
 {
-  limit: 10,   // Max records to return
-  offset: 20,  // Skip first 20 records
-  orderBy: { id: 'asc' }
+  limit: 10,   // Max records to return (default: 10)
+  skip: 20,    // Skip first 20 records (alias: offset)
 }
 
 // Page 3 with 10 items per page
 {
   limit: 10,
-  offset: 20, // (page - 1) * limit = (3 - 1) * 10
-  orderBy: { createdAt: 'desc' }
+  skip: 20, // (page - 1) * limit = (3 - 1) * 10
 }
 ```
 
@@ -209,209 +228,29 @@ const users = await userRepo.find({
 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
-    };
-  }
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { isDeleted: false },
+      limit: 100,
+    },
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
 }
 
-// All queries automatically exclude deleted users
-await userRepo.find({});
-// WHERE is_deleted = false
+// All queries automatically include the default filter
+await userRepo.find({ filter: {} });
+// WHERE isDeleted = false LIMIT 100
 
 // Skip default filter for admin operations
 await userRepo.find({
-  where: {},
+  filter: {},
   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

@@ -34,7 +34,10 @@ Find values within a range (inclusive):
 ```
 
 > [!WARNING]
-> The value MUST be an array with exactly 2 elements `[min, max]`. Invalid values throw an error.
+> The value MUST be an array with exactly 2 elements `[min, max]`. Invalid values throw an error:
+> ```
+> Error: [BETWEEN] Invalid value: expected array of 2 elements, got ...
+> ```
 
 
 ## notBetween
@@ -47,6 +50,9 @@ Find values outside a range:
 // Matches: scores < 40 OR scores > 60
 ```
 
+> [!WARNING]
+> Same validation as `between` -- the value MUST be an array with exactly 2 elements.
+
 
 ## Alternative: Using gte/lte
 

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

@@ -13,14 +13,17 @@ Advanced tips and common edge cases when working with filters.
 
 ```typescript
 // JSON field contains: { "priority": "3" } (string)
-// This WON'T match numeric comparison!
-{ where: { 'metadata.priority': { gt: 2 } } }  // NULL due to safe casting
+// Numeric comparison uses safe casting:
+{ where: { 'metadata.priority': { gt: 2 } } }
+// The regex '^-?[0-9]+(\.[0-9]+)?$' matches "3", so it casts to numeric 3
+// Result: 3 > 2 -> matches
 
-// Use string comparison instead
-{ where: { 'metadata.priority': { gt: '2' } } }  // Lexicographic compare
+// But if JSON field contains: { "priority": "high" }
+{ where: { 'metadata.priority': { gt: 2 } } }
+// "high" fails regex -> NULL -> no match
 
-// Or ensure your data stores numbers properly
-{ "priority": 3 }  // Store as number, not string
+// Best practice: ensure your data stores numbers as JSON numbers
+{ "priority": 3 }  // Store as number, not string "3"
 ```
 
 
@@ -73,7 +76,7 @@ for (let i = 0; i < allIds.length; i += chunkSize) {
 ## Tip 5: Order By JSON Fields
 
 ```typescript
-// JSON ordering uses #> (preserves type) not #>> (text)
+// JSON ordering uses #> (returns JSONB, preserves types) not #>> (returns text)
 { order: ['metadata.priority DESC'] }
 // SQL: "metadata" #> '{priority}' DESC
 
@@ -188,3 +191,27 @@ const products = await productRepo.find({
   }
 });
 ```
+
+
+## Tip 11: Array Operators Accept Single Values
+
+```typescript
+// These are equivalent:
+{ where: { tags: { contains: ['featured'] } } }
+{ where: { tags: { contains: 'featured' } } }
+
+// Single values are automatically wrapped in an array
+// This works for contains, containedBy, and overlaps
+```
+
+
+## Tip 12: Field Selection Object Format
+
+```typescript
+// Object format only supports inclusion (true values)
+{ fields: { id: true, name: true, email: true } }
+
+// Setting a field to false does NOT exclude it -- it just ignores that key
+// If you want to exclude fields, list only the ones you want:
+{ fields: ['id', 'name', 'email'] }  // Array format is clearer for this
+```

package/wiki/references/base/filter-system/use-cases.md

@@ -178,7 +178,7 @@ const documents = await documentRepo.find({
 const searchProducts = async (query: string, filters: {
   minRating?: number;
   maxPrice?: number;
-  features?: string[];
+  categories?: string[];
 }) => {
   const where: TWhere<TProductSchema> = {
     status: 'active',
@@ -201,8 +201,9 @@ const searchProducts = async (query: string, filters: {
     where.price = { lte: filters.maxPrice };
   }
 
-  if (filters.features?.length) {
-    where['metadata.features'] = { contains: filters.features };
+  if (filters.categories?.length) {
+    // Use array operator on a PostgreSQL array column
+    where.categories = { contains: filters.categories };
   }
 
   return productRepo.find({
@@ -214,7 +215,7 @@ const searchProducts = async (query: string, filters: {
   });
 };
 
-// Example: searchProducts('wireless', { minRating: 4, maxPrice: 200, features: ['bluetooth'] })
+// Example: searchProducts('wireless', { minRating: 4, maxPrice: 200, categories: ['electronics'] })
 //
 // SQL:
 // SELECT *
@@ -228,7 +229,7 @@ const searchProducts = async (query: string, filters: {
 //   )
 //   AND "rating" >= 4
 //   AND "price" <= 200
-//   AND "metadata" #>> '{features}' @> '["bluetooth"]'
+//   AND "categories"::text[] @> ARRAY['electronics']::text[]
 // ORDER BY "rating" DESC, "created_at" DESC
 // LIMIT 50
 ```