@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/references/base/filter-system/application-usage.md

@@ -35,7 +35,7 @@ How filters flow through the application layers.
                                  v
 +-----------------------------------------------------------------+
 |                     Repository Layer                             |
-|   - DefaultFilterMixin merges default filter                     |
+|   - applyDefaultFilter() merges the @model default filter         |
 |   - FilterBuilder transforms Filter -> Drizzle query options     |
 |   - Executes query via Drizzle ORM                               |
 |   - Returns typed results                                        |
@@ -68,8 +68,7 @@ const _Controller = ControllerFactory.defineCrudController({
   controller: {
     name: 'ProductController',
     basePath: BASE_PATH,
-    isStrict: true,
-    defaultLimit: 20,
+    isStrict: { path: true, requestSchema: true },
   },
   entity: () => Product,
 });
@@ -95,18 +94,21 @@ export class ProductController extends _Controller {
 | Method | Endpoint | Filter Location |
 |--------|----------|-----------------|
 | GET | `/products` | Query param: `?filter={...}` |
-| GET | `/products/:id` | Query param: `?filter={...}` (for includes) |
-| GET | `/products/one` | Query param: `?filter={...}` |
+| GET | `/products/{id}` | Query param: `?filter={...}` (for includes) |
+| GET | `/products/find-one` | Query param: `?filter={...}` |
 | GET | `/products/count` | Query param: `?where={...}` |
 
 ### Custom Controller with Manual Filter Handling
 
 ```typescript
+import { z } from '@hono/zod-openapi';
+import { BaseRestController, controller, FilterSchema, inject, jsonResponse } from '@venizia/ignis';
+
 @controller({ path: '/products' })
 export class ProductController extends BaseRestController {
   constructor(
     @inject({ key: 'repositories.ProductRepository' })
-    private _productRepo: ProductRepository,
+    private _productRepository: ProductRepository,
   ) {
     super({ scope: 'ProductController', path: '/products' });
   }
@@ -116,13 +118,14 @@ export class ProductController extends BaseRestController {
       configs: {
         path: '/search',
         method: 'get',
-        query: {
-          filter: FilterSchema,
+        request: {
+          query: z.object({ filter: FilterSchema }),
         },
+        responses: jsonResponse({ schema: z.array(z.object({ id: z.string() })) }),
       },
       handler: async (context) => {
         const { filter = {} } = context.req.valid('query');
-        const results = await this._productRepo.find({ filter });
+        const results = await this._productRepository.find({ filter });
         return context.json(results);
       },
     });
@@ -155,7 +158,7 @@ Services can modify filters before passing to repositories:
 export class ProductService {
   constructor(
     @inject({ key: 'repositories.ProductRepository' })
-    private _productRepo: ProductRepository,
+    private _productRepository: ProductRepository,
   ) {}
 
   async findProducts(filter: TFilter<TProductSchema> = {}) {
@@ -168,7 +171,7 @@ export class ProductService {
       },
     };
 
-    return this._productRepo.find({ filter: enhancedFilter });
+    return this._productRepository.find({ filter: enhancedFilter });
   }
 
   async findProductsForTenant(
@@ -183,7 +186,7 @@ export class ProductService {
       },
     };
 
-    return this._productRepo.find({ filter: isolatedFilter });
+    return this._productRepository.find({ filter: isolatedFilter });
   }
 }
 ```
@@ -227,7 +230,7 @@ const response = await axios.get('/api/products', {
 
 ```typescript
 // Enable logging to see generated SQL
-const result = await repo.find({
+const result = await repository.find({
   filter: complexFilter,
   options: {
     log: { use: true, level: 'debug' },
@@ -235,6 +238,6 @@ const result = await repo.find({
 });
 
 // Or use buildQuery to inspect without executing
-const queryOptions = repo.buildQuery({ filter: complexFilter });
+const queryOptions = repository.buildQuery({ filter: complexFilter });
 console.log('Generated query options:', queryOptions);
 ```

package/content/references/base/filter-system/array-operators.md

@@ -86,8 +86,8 @@ Find rows where the arrays share at least one common element.
 
 ## Empty Array Behavior
 
-| Operator | Empty Value `[]` | SQL Generated | Behavior |
-|----------|------------------|---------------|----------|
+| Operator | SQL Generated | Behavior |
+|----------|---------------|----------|
 | `contains: []` | `WHERE true` | Returns **ALL** rows |
 | `containedBy: []` | `WHERE "col" = '{}'` | Returns only rows with **empty arrays** |
 | `overlaps: []` | `WHERE false` | Returns **NO** rows |
@@ -121,6 +121,11 @@ No casting needed for numeric arrays.
 ```
 
 
+## Security: Parameterized Values
+
+Every element of `contains`/`containedBy`/`overlaps` is bound as a query parameter -- only the operator token (`@>`/`<@`/`&&`) is raw SQL. See [The Hardening Round](../../../changelogs/2026-07-13-hardening-round) for the prior injection this closed.
+
+
 ## Defining Array Columns
 
 In your Drizzle schema:

package/content/references/base/filter-system/comparison-operators.md

@@ -56,6 +56,9 @@ Matches records where field does NOT equal the value. Both `ne` and `neq` are al
 // SQL: WHERE "deleted_at" IS NOT NULL
 ```
 
+> [!NOTE]
+> When compared against a **real value** (not `null`), `ne`/`neq` follow SQL three-valued logic: a row whose field is `NULL` never matches `{ field: { neq: value } }`, because `NULL <> value` evaluates to UNKNOWN rather than TRUE. To include NULL rows, add an explicit branch: `{ or: [{ field: { neq: value } }, { field: null }] }`.
+
 
 ## gt - Greater Than
 

package/content/references/base/filter-system/default-filter.md

@@ -47,7 +47,7 @@ Now all queries automatically include the default filter:
 
 ```typescript
 // Your code
-await userRepo.find({
+await userRepository.find({
   filter: { where: { status: 'active' } }
 });
 
@@ -93,41 +93,83 @@ export class User extends BaseEntity<typeof User.schema> {}
 
 ## Merge Behavior
 
-When a user provides a filter, it is merged with the default filter using `FilterBuilder.mergeFilter()`:
+When a user provides a filter, it is merged with the default filter using `FilterBuilder.mergeFilter()`. Non-`where` properties are user-wins; the `where` clause follows a **narrowing** collision law so a default scope can never be widened or dropped.
 
 | Property | Merge Strategy |
 |----------|----------------|
-| `where` | **Deep merge** (via lodash `merge`) -- user values override matching keys |
+| `where` | **Per-key narrowing** -- non-colliding keys carry over; a colliding key is composed so the default condition always survives (see below) |
 | `limit` | User replaces default (if provided) |
 | `offset`/`skip` | User replaces default (if provided) |
 | `order` | User replaces default (if provided) |
 | `fields` | User replaces default (if provided) |
 | `include` | User replaces default (if provided) |
 
-### Where Clause Merging
+A user value of `undefined` **never** overrides a defined default -- a caller cannot blow away a tenant or soft-delete scope by passing `undefined`.
 
-The `where` clause uses deep merge with user values taking precedence:
+### Where Clause Collision Law
+
+Within `where`, keys present on only one side pass through untouched. When the **same key** appears in both the default and the user filter, the outcome depends on the shapes:
+
+| Default | User | Result |
+|---------|------|--------|
+| scalar | scalar | **User wins** (the soft-delete opt-out -- e.g. `isDeleted: false` becomes `isDeleted: true`) |
+| operator | operator | **AND-composed** into an `and: [...]` group (both conditions enforced) |
+| scalar | operator | **AND-composed** |
+| operator | scalar | **AND-composed** |
+
+A colliding `and` key concatenates both conjunct lists (both survive). A colliding `or` key AND-composes the two disjunction groups as separate conjuncts -- the user's `or` cannot swallow the default's `or`. Every AND-composed pair is appended to any existing `and` group.
+
+> [!IMPORTANT]
+> Because operator collisions AND-compose rather than replace, a default scope (a `createdAt` floor, a tenant `inq`) can no longer be widened or dropped by a user filter. Only a bare scalar-over-scalar collision is a true override.
+
+### Narrowing Example
+
+```typescript
+// Default filter: a floor on createdAt plus a tenant scope
+const defaultFilter = {
+  where: { createdAt: { gte: '2024-01-01' }, tenantId: { inq: ['t1', 't2'] } },
+};
+
+// User filter: an upper bound on createdAt
+const userFilter = {
+  where: { createdAt: { lte: '2024-12-31' } },
+};
+```
+
+**Before** (old wholesale-replace law) -- the user key replaced the default's `createdAt`, dropping the floor:
 
 ```typescript
-// Default filter
-{ where: { isDeleted: false, status: 'pending' }, limit: 100 }
+// { where: { createdAt: { lte: '2024-12-31' }, tenantId: { inq: ['t1', 't2'] } } }
+```
 
-// User filter
-{ where: { status: 'active', role: 'admin' }, limit: 10 }
+**After** (narrowing law) -- operator over operator is AND-composed, so the floor survives:
 
-// Merged result
+```typescript
 {
   where: {
-    isDeleted: false,    // From default (preserved)
-    status: 'active',    // User overrides default
-    role: 'admin'        // From user (added)
+    tenantId: { inq: ['t1', 't2'] },
+    and: [
+      { createdAt: { gte: '2024-01-01' } },
+      { createdAt: { lte: '2024-12-31' } },
+    ],
   },
-  limit: 10              // User overrides default
 }
 ```
 
+### Scalar Override (soft-delete opt-out)
+
+A plain scalar on both sides is the one case where the user still wins outright -- this is what lets an admin flip a soft-delete flag:
+
+```typescript
+// Default: { where: { isDeleted: false } }
+// User:    { where: { isDeleted: true } }
+// Result:  { where: { isDeleted: true } }
+```
+
 ### Complex Where Conditions
 
+Keys that do not collide combine with an implicit AND:
+
 ```typescript
 // Default: soft delete and tenant isolation
 const defaultFilter = {
@@ -137,7 +179,7 @@ const defaultFilter = {
   }
 };
 
-// User: OR conditions
+// User: OR conditions (a distinct key, so it carries through)
 const userFilter = {
   where: {
     or: [{ status: 'active' }, { priority: 'high' }]
@@ -149,33 +191,6 @@ const userFilter = {
 //   AND (status = 'active' OR priority = 'high')
 ```
 
-### Operator Object Merging
-
-Operator objects are deep merged, allowing range combinations:
-
-```typescript
-// Default: created after 2024
-const defaultFilter = {
-  where: {
-    createdAt: { gte: '2024-01-01' }
-  }
-};
-
-// User: created before end of 2024
-const userFilter = {
-  where: {
-    createdAt: { lte: '2024-12-31' }
-  }
-};
-
-// Result: date range
-{
-  where: {
-    createdAt: { gte: '2024-01-01', lte: '2024-12-31' }
-  }
-}
-```
-
 
 ## Bypassing Default Filter
 
@@ -183,13 +198,13 @@ Use `shouldSkipDefaultFilter: true` to bypass the default filter:
 
 ```typescript
 // Normal query - default filter applies
-await repo.find({
+await repository.find({
   filter: { where: { role: 'admin' } }
 });
 // WHERE isDeleted = false AND role = 'admin'
 
 // Admin query - bypass default filter
-await repo.find({
+await repository.find({
   filter: { where: { role: 'admin' } },
   options: { shouldSkipDefaultFilter: true }
 });
@@ -202,18 +217,18 @@ await repo.find({
 
 ```typescript
 // Read operations
-await repo.find({ filter, options: { shouldSkipDefaultFilter: true } });
-await repo.findOne({ filter, options: { shouldSkipDefaultFilter: true } });
-await repo.findById({ id, options: { shouldSkipDefaultFilter: true } });
-await repo.count({ where, options: { shouldSkipDefaultFilter: true } });
+await repository.find({ filter, options: { shouldSkipDefaultFilter: true } });
+await repository.findOne({ filter, options: { shouldSkipDefaultFilter: true } });
+await repository.findById({ id, options: { shouldSkipDefaultFilter: true } });
+await repository.count({ where, options: { shouldSkipDefaultFilter: true } });
 
 // Update operations
-await repo.updateById({ id, data, options: { shouldSkipDefaultFilter: true } });
-await repo.updateAll({ where, data, options: { shouldSkipDefaultFilter: true } });
+await repository.updateById({ id, data, options: { shouldSkipDefaultFilter: true } });
+await repository.updateAll({ where, data, options: { shouldSkipDefaultFilter: true } });
 
 // Delete operations
-await repo.deleteById({ id, options: { shouldSkipDefaultFilter: true } });
-await repo.deleteAll({ where, options: { shouldSkipDefaultFilter: true, force: true } });
+await repository.deleteById({ id, options: { shouldSkipDefaultFilter: true } });
+await repository.deleteAll({ where, options: { shouldSkipDefaultFilter: true, force: true } });
 ```
 
 ### Use Cases for Bypassing
@@ -243,11 +258,11 @@ await repo.deleteAll({ where, options: { shouldSkipDefaultFilter: true, force: t
 export class Post extends BaseEntity<typeof Post.schema> {}
 
 // All queries exclude deleted posts
-await postRepo.find({ filter: {} });
+await postRepository.find({ filter: {} });
 // WHERE deletedAt IS NULL
 
 // Restore a deleted post
-await postRepo.updateById({
+await postRepository.updateById({
   id: postId,
   data: { deletedAt: null },
   options: { shouldSkipDefaultFilter: true }
@@ -268,11 +283,11 @@ await postRepo.updateById({
 export class Document extends BaseEntity<typeof Document.schema> {}
 
 // Queries scoped to tenant
-await docRepo.find({ filter: { where: { type: 'invoice' } } });
+await documentRepository.find({ filter: { where: { type: 'invoice' } } });
 // WHERE tenantId = 'current-tenant' AND type = 'invoice'
 
 // Cross-tenant admin query
-await docRepo.find({
+await documentRepository.find({
   filter: { where: { type: 'invoice' } },
   options: { shouldSkipDefaultFilter: true }
 });
@@ -311,8 +326,8 @@ Use the dedicated `settings.defaultLimit` to raise (or lower) the per-model defa
 export class LogEntry extends BaseEntity<typeof LogEntry.schema> {}
 
 // User can override limit, but there's always a sensible default
-await logRepo.find({ filter: {} });           // LIMIT 1000
-await logRepo.find({ filter: { limit: 50 } }); // LIMIT 50
+await logEntryRepository.find({ filter: {} });           // LIMIT 1000
+await logEntryRepository.find({ filter: { limit: 50 } }); // LIMIT 50
 ```
 
 > [!TIP]
@@ -324,7 +339,7 @@ await logRepo.find({ filter: { limit: 50 } }); // LIMIT 50
 When using `include` to load relations, the default filter of the related model is also applied. You can bypass it per-relation:
 
 ```typescript
-await repo.find({
+await repository.find({
   filter: {
     include: [
       // Default filter of related model applies
@@ -361,11 +376,11 @@ interface IWithTransaction {
 This allows combining with transactions:
 
 ```typescript
-const tx = await repo.beginTransaction();
+const tx = await repository.beginTransaction();
 
 try {
   // Both transaction and shouldSkipDefaultFilter
-  await repo.updateAll({
+  await repository.updateAll({
     where: { status: 'archived' },
     data: { isDeleted: true },
     options: {
@@ -387,10 +402,10 @@ try {
 ### Architecture
 
 ```
-+------------------+     +------------------+     +------------------+
-|  Model Settings  | --> | DefaultFilterMixin | --> | Repository Method |
-|  defaultFilter   |     | applyDefaultFilter |     | find/count/etc   |
-+------------------+     +------------------+     +------------------+
++------------------+     +----------------------+     +------------------+
+|  Model Settings  | --> | PostgresBaseRepository | --> | Repository Method |
+|  defaultFilter   |     | applyDefaultFilter()   |     | find/count/etc   |
++------------------+     +----------------------+     +------------------+
                                 |
                                 v
                          +------------------+
@@ -399,9 +414,9 @@ try {
                          +------------------+
 ```
 
-### DefaultFilterMixin
+### PostgresBaseRepository
 
-The `DefaultFilterMixin` provides:
+`PostgresBaseRepository` (`packages/core/src/connectors/postgres/repositories/core/base.ts`) implements the default-filter behavior directly as protected methods - no mixin is composed onto it:
 
 ```typescript
 // Check if default filter is configured
@@ -417,7 +432,10 @@ applyDefaultFilter(opts: {
 }): TFilter
 ```
 
-The default filter is resolved from `MetadataRegistry` on first access and cached for subsequent calls.
+`getDefaultFilter()` reads `this.modelSettings?.defaultFilter`, where `modelSettings` is a protected getter on `AbstractRepository` (`src/base/repositories/core/abstract.ts`) resolved from `MetadataRegistry` keyed by the entity's constructor (not by name string) on first access, and cached for subsequent calls.
+
+> [!NOTE]
+> An older `DefaultFilterMixin` implemented this same behavior via mixin composition. It is no longer composed onto any repository class - see [Repository Mixins (Legacy)](../repositories/mixins.md) for history.
 
 ### FilterBuilder.mergeFilter()
 
@@ -444,12 +462,12 @@ const merged = filterBuilder.mergeFilter({
 | Bypass default filter | `options: { shouldSkipDefaultFilter: true }` |
 | Bypass for relation | `include: [{ relation: 'x', shouldSkipDefaultFilter: true }]` |
 | Combine with transaction | `options: { transaction: tx, shouldSkipDefaultFilter: true }` |
-| Check if model has default | `repo.hasDefaultFilter()` |
-| Get raw default filter | `repo.getDefaultFilter()` |
+| Check if model has default | `repository.hasDefaultFilter()` |
+| Get raw default filter | `repository.getDefaultFilter()` |
 
 
 ## Next Steps
 
 - [Filter System Overview](./index.md) - Filter structure and operators
-- [Repository Mixins](../repositories/mixins.md) - Mixin architecture
+- [Repository Mixins (Legacy)](../repositories/mixins.md) - Historical mixin architecture
 - [Advanced Features](../repositories/advanced.md) - Transactions, hidden properties

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

@@ -16,7 +16,7 @@ Control which fields are returned using `fields`:
 ### Array Format (Recommended)
 
 ```typescript
-await repo.find({
+await repository.find({
   filter: {
     where: { status: 'active' },
     fields: ['id', 'email', 'name']
@@ -29,7 +29,7 @@ await repo.find({
 
 ```typescript
 // Include specific fields (only keys with `true` are selected)
-await repo.find({
+await repository.find({
   filter: {
     fields: { id: true, email: true, name: true }
   }
@@ -46,17 +46,17 @@ await repo.find({
 
 ```typescript
 // Single column, descending
-await repo.find({
+await repository.find({
   filter: { order: ['createdAt DESC'] }
 });
 
 // Multiple columns
-await repo.find({
+await repository.find({
   filter: { order: ['status ASC', 'createdAt DESC'] }
 });
 
 // Default direction is ASC
-await repo.find({
+await repository.find({
   filter: { order: ['name'] }  // Same as 'name ASC'
 });
 ```
@@ -74,12 +74,12 @@ Error: Invalid direction: 'RANDOM' | Expected: 'ASC' or 'DESC'
 Order by nested fields in JSON columns:
 
 ```typescript
-await repo.find({
+await repository.find({
   filter: { order: ['metadata.priority DESC'] }
 });
 // SQL: ORDER BY "metadata" #> '{priority}' DESC
 
-await repo.find({
+await repository.find({
   filter: { order: ['settings.display.theme ASC'] }
 });
 ```
@@ -104,24 +104,24 @@ Both `skip` and `offset` are supported as aliases -- they both map to the SQL `O
 
 ```typescript
 // First 10 results (default limit is 10)
-await repo.find({
+await repository.find({
   filter: { limit: 10 }
 });
 
 // Page 2 (skip first 10, get next 10)
-await repo.find({
+await repository.find({
   filter: { limit: 10, skip: 10 }
 });
 
 // Using offset (equivalent to skip)
-await repo.find({
+await repository.find({
   filter: { limit: 10, offset: 10 }
 });
 
 // Page N formula: skip = (page - 1) * limit
 const page = 3;
 const pageSize = 20;
-await repo.find({
+await repository.find({
   filter: {
     limit: pageSize,
     skip: (page - 1) * pageSize
@@ -140,23 +140,23 @@ When a query omits `limit`, the repository resolves one with this precedence:
 query.limit  ??  model settings.defaultLimit  ??  DEFAULT_LIMIT (10)
 ```
 
-- **`query.limit`** — an explicit `limit` in the filter always wins.
-- **`settings.defaultLimit`** — a per-model default set on the `@model` decorator. Must be a positive integer (validated at decoration time). Applies to top-level `find()` and to every to-many relation (using the related model's own `defaultLimit`).
-- **`DEFAULT_LIMIT`** — the global fallback, `10`.
+- **`query.limit`** - an explicit `limit` in the filter always wins.
+- **`settings.defaultLimit`** - a per-model default set on the `@model` decorator. Must be a positive integer (validated at decoration time). Applies to top-level `find()` and to every to-many relation (using the related model's own `defaultLimit`).
+- **`DEFAULT_LIMIT`** - the global fallback, `10`.
 
 ```typescript
 @model({
   type: 'entity',
-  settings: { defaultLimit: 200 },  // Small lookup table — default to 200 rows
+  settings: { defaultLimit: 200 },  // Small lookup table - default to 200 rows
 })
 export class Country extends BaseEntity<typeof Country.schema> {}
 
-await countryRepo.find({ filter: {} });            // LIMIT 200
-await countryRepo.find({ filter: { limit: 10 } }); // LIMIT 10  (explicit wins)
+await countryRepository.find({ filter: {} });            // LIMIT 200
+await countryRepository.find({ filter: { limit: 10 } }); // LIMIT 10  (explicit wins)
 ```
 
 > [!NOTE]
-> `defaultLimit` is independent of `defaultFilter`: passing `shouldSkipDefaultFilter` to bypass the default `where` clause does **not** drop the default limit. There is no "unbounded" sentinel — to fetch more rows, pass an explicit `limit`.
+> `defaultLimit` is independent of `defaultFilter`: passing `shouldSkipDefaultFilter` to bypass the default `where` clause does **not** drop the default limit. There is no "unbounded" sentinel - to fetch more rows, pass an explicit `limit`.
 
 ### Pagination Helper
 
@@ -184,7 +184,7 @@ When building paginated APIs, you often need to return the total count alongside
 ### Basic Usage
 
 ```typescript
-const result = await repo.find({
+const result = await repository.find({
   filter: { limit: 10, skip: 20 },
   options: { shouldQueryRange: true }
 });
@@ -205,7 +205,7 @@ const result = await repo.find({
 Use the range information to set standard HTTP headers:
 
 ```typescript
-const { data, range } = await repo.find({
+const { data, range } = await repository.find({
   filter: { limit: 10, skip: 20, where: { status: 'active' } },
   options: { shouldQueryRange: true }
 });
@@ -246,7 +246,7 @@ When `shouldQueryRange: true`, the repository executes the data query and count
 ## Combined Example
 
 ```typescript
-await repo.find({
+await repository.find({
   filter: {
     where: { status: 'active' },
     fields: ['id', 'name', 'price', 'createdAt'],
@@ -260,7 +260,7 @@ await repo.find({
 ### With Range Information
 
 ```typescript
-const { data, range } = await repo.find({
+const { data, range } = await repository.find({
   filter: {
     where: { status: 'active' },
     fields: ['id', 'name', 'price', 'createdAt'],

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

@@ -6,10 +6,10 @@ difficulty: intermediate
 
 # Filter System
 
-Complete reference for the Ignis filter system - operators, JSON filtering, array operators, default filters, and query patterns.
+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:
+> 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
@@ -45,7 +45,7 @@ Before reading this document, you should understand:
 
 ## Filter Structure
 
-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.
+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> = {
@@ -105,6 +105,9 @@ const filter = {
 | Less or equal | `{ field: { lte: value } }` |
 | Is null | `{ field: null }` or `{ field: { is: null } }` |
 | Is not null | `{ field: { isn: null } }` or `{ field: { ne: null } }` |
+| Field present (`IS NOT NULL`) | `{ field: { exists: true } }` (or `{ field: { notExists: false } }`) |
+| Field missing/null (`IS NULL`) | `{ field: { exists: false } }` or `{ field: { notExists: true } }` |
+| Negate a condition | `{ field: { not: value } }` (negates `eq`) or `{ field: { not: { gt: 10 } } }` |
 | 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] } }` |

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

@@ -82,7 +82,7 @@ All standard operators work with JSON paths:
 
 ## Safe Numeric Casting
 
-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:
+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:
@@ -114,6 +114,25 @@ When a numeric comparison operator (`gt`, `gte`, `lt`, `lte`, `between`, `notBet
 
 Non-numeric operators (`eq`, `ne`, `like`, `ilike`, `in`, etc.) use text comparison via `#>>` without numeric casting.
 
+The cast is decided **per operator**, not once for the whole operator object -- a mixed object casts only the operators that need it:
+
+```typescript
+// Mixed operator object: gte casts, like does not
+{ where: { 'metadata.score': { gte: 1, like: '%a%' } } }
+// SQL: CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//      THEN ("metadata" #>> '{score}')::numeric ELSE NULL END >= 1
+//   AND "metadata" #>> '{score}' LIKE '%a%'
+```
+
+`not` recurses into whatever it wraps, so a numeric operator nested under `not` still gets cast:
+
+```typescript
+// not wrapping an operator - the nested gt still gets the numeric cast
+{ where: { 'metadata.score': { not: { gt: 50 } } } }
+// SQL: NOT (CASE WHEN ("metadata" #>> '{score}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//           THEN ("metadata" #>> '{score}')::numeric ELSE NULL END > 50)
+```
+
 
 ## Numeric Value Equality
 

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

@@ -64,7 +64,7 @@ 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({
+  const chunkResults = await repository.find({
     filter: { where: { id: { in: chunk } } }
   });
   results.push(...chunkResults);