@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -6,113 +6,105 @@ difficulty: intermediate
 
 # Comparison Operators
 
-Equality and comparison operators for filtering records.
+Compares a field against a value: equality, inequality, and ordering.
 
+| Operator | SQL | Meaning |
+|----------|-----|---------|
+| `eq` | `=` / `IS NULL` | Equal to |
+| `ne` | `!=` / `IS NOT NULL` | Not equal to |
+| `neq` | `!=` / `IS NOT NULL` | Alias for `ne` |
+| `gt` | `>` | Greater than |
+| `gte` | `>=` | Greater than or equal |
+| `lt` | `<` | Less than |
+| `lte` | `<=` | Less than or equal |
 
-## eq - Equal To
-
-Matches records where field equals the value.
+## eq
 
 ```typescript
-// Implicit equality
-{ where: { status: 'active' } }
-
-// Explicit form
 { where: { status: { eq: 'active' } } }
-
 // SQL: WHERE "status" = 'active'
 ```
 
-**Special Cases:**
-```typescript
-// Null equality
-{ where: { deletedAt: null } }
-{ where: { deletedAt: { eq: null } } }
-// SQL: WHERE "deleted_at" IS NULL
-
-// Array shorthand (becomes IN)
-{ where: { id: [1, 2, 3] } }
-// SQL: WHERE "id" IN (1, 2, 3)
-
-// Empty array shorthand
-{ where: { id: [] } }
-// SQL: WHERE false (no results)
-```
-
+**Notice:** the bare shorthand `{ status: 'active' }` (no operator key) means the same thing.
 
-## ne / neq - Not Equal To
+**Edge cases:**
+- `{ eq: null }` compiles to `IS NULL`, never `= NULL`.
+- Bare array `{ field: [1, 2, 3] }` (no operator key) compiles to `IN (1, 2, 3)`.
+- An explicit `{ eq: [1, 2, 3] }` does not become `IN` - it compares the column to an array value.
+- Bare empty array `{ field: [] }` matches no rows (`WHERE false`).
 
-Matches records where field does NOT equal the value. Both `ne` and `neq` are aliases and behave identically.
+## ne / neq
 
 ```typescript
 { where: { status: { ne: 'deleted' } } }
-{ where: { status: { neq: 'deleted' } } }  // Alias
-
 // SQL: WHERE "status" != 'deleted'
-
-// Null handling
-{ where: { deletedAt: { ne: null } } }
-{ where: { deletedAt: { neq: null } } }
-// 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 }] }`.
+**Notice:** `ne` and `neq` are the same operator under two names.
 
+**Edge cases:**
+- `{ ne: null }` compiles to `IS NOT NULL`.
+- SQL three-valued logic applies: a `NULL` field never matches `{ ne: value }`, because `NULL <> value` is UNKNOWN.
+- Add an `or` branch to include NULL rows: `{ or: [{ field: { ne: value } }, { field: null }] }`.
 
-## gt - Greater Than
+## gt
 
 ```typescript
-// Numbers
 { where: { price: { gt: 100 } } }
 // SQL: WHERE "price" > 100
-
-// Dates
-{ where: { createdAt: { gt: new Date('2024-01-01') } } }
-// SQL: WHERE "created_at" > '2024-01-01'
-
-// Strings (lexicographic)
-{ where: { name: { gt: 'M' } } }
-// SQL: WHERE "name" > 'M'
 ```
 
+**Notice:** works on numbers, dates, and strings (lexicographic comparison).
+
+**Edge cases:**
+- `{ gt: null }` compiles to `"price" > NULL`, which is never true - no rows match.
+- Use `is`/`exists` instead to check for null.
+- Combine with other operators in the same object: `{ gte: 18, lt: 65 }`.
 
-## gte - Greater Than or Equal
+## gte
 
 ```typescript
 { where: { quantity: { gte: 10 } } }
 // SQL: WHERE "quantity" >= 10
-
-// Combined with other operators
-{ where: { age: { gte: 18, lt: 65 } } }
-// SQL: WHERE "age" >= 18 AND "age" < 65
 ```
 
+**Notice:** inclusive of the boundary value.
+
+**Edge cases:**
+- Same null behavior as `gt`: `{ gte: null }` matches no rows.
 
-## lt - Less Than
+## lt
 
 ```typescript
 { where: { stock: { lt: 5 } } }
 // SQL: WHERE "stock" < 5
 ```
 
+**Notice:** exclusive of the boundary value.
 
-## lte - Less Than or Equal
+**Edge cases:**
+- Same null behavior as `gt`: `{ lt: null }` matches no rows.
+
+## lte
 
 ```typescript
 { where: { rating: { lte: 3 } } }
 // SQL: WHERE "rating" <= 3
 ```
 
+**Notice:** inclusive of the boundary value.
 
-## Summary
+**Edge cases:**
+- Same null behavior as `gt`: `{ lte: null }` matches no rows.
 
-| Operator | SQL | Description |
-|----------|-----|-------------|
-| `eq` | `=` / `IS NULL` | Equal to (handles null) |
-| `ne` | `!=` / `IS NOT NULL` | Not equal to (handles null) |
-| `neq` | `!=` / `IS NOT NULL` | Alias for `ne` |
-| `gt` | `>` | Greater than |
-| `gte` | `>=` | Greater than or equal |
-| `lt` | `<` | Less than |
-| `lte` | `<=` | Less than or equal |
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [Range Operators](./range-operators) - `between`/`notBetween`, and the `gte`/`lte` equivalent shown above
+- [Quick Reference](./quick-reference) - every operator, one line each
+
+**Files:**
+
+- [`packages/core-server/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
+- [`packages/core-server/src/connectors/relational/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core-server/src/connectors/relational/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
+- [`packages/filter/src/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/filter/src/common/operators.ts) - `QueryOperators` constants