@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -6,132 +6,75 @@ difficulty: intermediate
 
 # Null Check Operators
 
-Operators for checking null and non-null values.
+Checks whether a field is `NULL` or has a value, without comparing to a specific value.
 
+| Operator | SQL | Meaning |
+|----------|-----|---------|
+| `is` | `IS NULL` / `=` | Null check or equality |
+| `isn` | `IS NOT NULL` / `!=` | Not-null check or inequality |
+| `exists` | `IS NOT NULL` / `IS NULL` | Presence check |
+| `notExists` | `IS NULL` / `IS NOT NULL` | Inverse presence check |
 
-## Direct Null Assignment
-
-The simplest way to check for NULL:
+## is
 
 ```typescript
-// IS NULL (implicit)
-{ where: { deletedAt: null } }
+{ where: { deletedAt: { is: null } } }
 // SQL: WHERE "deleted_at" IS NULL
 ```
 
+**Notice:** `is` behaves exactly like `eq` - `is: null` compiles to `IS NULL`, `is: <value>` compiles to `=`.
 
-## eq with Null
+**Edge cases:**
+- The bare shorthand `{ deletedAt: null }` (no operator key) is identical to `{ deletedAt: { is: null } }`.
+- `{ is: 'active' }` compiles to `"status" = 'active'`, the same as `eq`.
 
-```typescript
-{ where: { deletedAt: { eq: null } } }
-// SQL: WHERE "deleted_at" IS NULL
-
-{ where: { status: { eq: 'active' } } }
-// SQL: WHERE "status" = 'active'
-```
-
-
-## ne / neq with Null
+## isn
 
 ```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'
+{ where: { verifiedAt: { isn: null } } }
+// SQL: WHERE "verified_at" IS NOT NULL
 ```
 
+**Notice:** `isn` behaves exactly like `ne`/`neq` - `isn: null` compiles to `IS NOT NULL`, `isn: <value>` compiles to `!=`.
 
-## 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'
-```
-
+**Edge cases:**
+- Same three-valued-logic caveat as `ne`: `{ isn: value }` for a real `value` never matches a `NULL` row.
 
-## isn - IS NOT NULL / Not Equality
+## exists
 
 ```typescript
-// NOT NULL check
-{ where: { verifiedAt: { isn: null } } }
+{ where: { verifiedAt: { exists: true } } }
 // SQL: WHERE "verified_at" IS NOT NULL
-
-// Value check (same as ne)
-{ where: { status: { isn: 'deleted' } } }
-// SQL: WHERE "status" != 'deleted'
 ```
 
+**Notice:** `exists` takes a boolean, not a value - `exists: false` compiles to `IS NULL`, anything else compiles to `IS NOT NULL`.
 
-## exists / notExists - Presence Check
+**Edge cases:**
+- Only the literal `false` selects the `IS NULL` branch.
+- Any other operand, including `0` or a truthy string, selects `IS NOT NULL`.
+- Also works over a JSON path key, for example `{ 'metadata.score': { exists: true } }`.
 
-`exists` and `notExists` are presence operators - they take a boolean rather than a value, and read more naturally than `is`/`isn` against `null`. They work on the PostgreSQL connector, and `exists` also works over JSON paths there.
+## notExists
 
 ```typescript
-// Field is present (IS NOT NULL)
-{ where: { deletedAt: { exists: false } } }  // no deletedAt -> IS NULL
-{ where: { verifiedAt: { exists: true } } }  // has verifiedAt -> IS NOT NULL
-
-// notExists is the inverse
-{ where: { verifiedAt: { notExists: true } } }  // IS NULL
-
-// exists over a JSON path (PostgreSQL)
-{ where: { 'metadata.score': { exists: true } } }
+{ where: { verifiedAt: { notExists: true } } }
+// SQL: WHERE "verified_at" IS NULL
 ```
 
-| Syntax | SQL | Description |
-|--------|-----|-------------|
-| `{ field: { exists: true } }` | `IS NOT NULL` | Field is present |
-| `{ field: { exists: false } }` | `IS NULL` | Field is missing/null |
-| `{ field: { notExists: true } }` | `IS NULL` | Inverse of exists |
-| `{ field: { notExists: false } }` | `IS NOT NULL` | Inverse of exists |
-
+**Notice:** the inverse of `exists` - `notExists: false` compiles to `IS NOT NULL`, anything else compiles to `IS NULL`.
 
-## Null Check Summary
+**Edge cases:**
+- Same `false`-only branch rule as `exists`.
 
-| 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: { exists: false } }` | `IS NULL` | Presence check (false = missing) |
-| `{ 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 |
-| `{ field: { exists: true } }` | `IS NOT NULL` | Presence check (true = present) |
+## See also
 
-All the IS NULL / IS NOT NULL syntaxes above are equivalent -- use whichever reads best in context.
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [Logical Operators](./logical-operators) - `not`, the general-purpose negation operator
+- [JSON Filtering](./json-filtering) - `exists` also works over a `'column.path'` key
+- [Quick Reference](./quick-reference) - every operator, one line each
 
-> [!NOTE]
-> `ne`/`neq` follow SQL three-valued logic: a row whose field is `NULL` never matches `{ field: { neq: value } }`. This is intentional (`NULL <> value` is UNKNOWN, not TRUE). Reach for `exists`/`notExists` or an explicit `{ field: null }` branch when you want NULL rows included.
+**Files:**
 
-
-## 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 } } }
-```
+- [`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

package/content/references/base/filter-system/pattern-matching.md

@@ -6,103 +6,100 @@ difficulty: intermediate
 
 # Pattern Matching Operators
 
-Operators for string pattern matching and regular expressions.
+Matches string fields against SQL `LIKE` patterns or POSIX regular expressions.
 
+| Operator | SQL | Meaning |
+|----------|-----|---------|
+| `like` | `LIKE` | Case-sensitive pattern match |
+| `nlike` | `NOT LIKE` | Negated case-sensitive pattern match |
+| `ilike` | `ILIKE` | Case-insensitive pattern match (PostgreSQL-only) |
+| `nilike` | `NOT ILIKE` | Negated case-insensitive pattern match (PostgreSQL-only) |
+| `regexp` | `~` | Case-sensitive POSIX regex match |
+| `iregexp` | `~*` | Case-insensitive POSIX regex match |
 
-## like - Pattern Matching (Case-Sensitive)
-
-Matches strings using SQL LIKE patterns.
+## like
 
 ```typescript
-// Starts with
 { where: { email: { like: '%@gmail.com' } } }
 // SQL: WHERE "email" LIKE '%@gmail.com'
-
-// Contains
-{ where: { name: { like: '%john%' } } }
-// SQL: WHERE "name" LIKE '%john%'
-
-// Ends with
-{ where: { filename: { like: '%.pdf' } } }
-// SQL: WHERE "filename" LIKE '%.pdf'
-
-// Single character wildcard
-{ where: { code: { like: 'A_B' } } }  // Matches 'A1B', 'AXB', etc.
-// SQL: WHERE "code" LIKE 'A_B'
 ```
 
-**Pattern Characters:**
-- `%` - Matches any sequence of characters (including empty)
-- `_` - Matches exactly one character
+**Notice:** `%` matches any sequence of characters (including none); `_` matches exactly one character.
 
+**Edge cases:**
+- A `null` operand compiles to `LIKE NULL`, which is never true - no rows match.
+- Case sensitivity follows the column's collation; the default is case-sensitive.
 
-## nlike - Not Like
+## nlike
 
 ```typescript
 { where: { email: { nlike: '%@test.com' } } }
 // SQL: WHERE "email" NOT LIKE '%@test.com'
 ```
 
+**Notice:** `NOT LIKE` excludes rows where the column is `NULL`, the same as `NOT IN`.
 
-## ilike - Case-Insensitive Pattern Matching
+**Edge cases:**
+- Same pattern-character rules as `like`.
 
-PostgreSQL-specific case-insensitive LIKE.
+## ilike
 
 ```typescript
 { where: { name: { ilike: '%john%' } } }
 // SQL: WHERE "name" ILIKE '%john%'
-// Matches: 'John', 'JOHN', 'john', 'JoHn'
-
-{ where: { email: { ilike: '%@GMAIL.COM' } } }
-// Matches: 'user@gmail.com', 'USER@Gmail.Com'
 ```
 
+**Notice:** matches `'John'`, `'JOHN'`, and `'john'` alike.
+
+**Edge cases:**
+- `ILIKE` is a PostgreSQL extension, not standard SQL.
+- Same pattern-character rules as `like`.
 
-## nilike - Not ILike
+## nilike
 
 ```typescript
 { where: { email: { nilike: '%@example%' } } }
 // SQL: WHERE NOT ("email" ILIKE '%@example%')
 ```
 
+**Notice:** built as a negated `ILIKE`, not a dedicated SQL operator.
 
-## regexp - Regular Expression (Case-Sensitive)
+**Edge cases:**
+- Same `NULL`-excludes-nothing behavior as `nlike`.
 
-PostgreSQL POSIX regex matching.
+## regexp
 
 ```typescript
-// Starts with letter
 { where: { code: { regexp: '^[A-Z]' } } }
 // SQL: WHERE "code" ~ '^[A-Z]'
-
-// Email pattern
-{ where: { email: { regexp: '^[a-z]+@[a-z]+\\.[a-z]+$' } } }
-// SQL: WHERE "email" ~ '^[a-z]+@[a-z]+\.[a-z]+$'
-
-// Phone number pattern
-{ where: { phone: { regexp: '^\\+?[0-9]{10,15}$' } } }
 ```
 
-> [!NOTE]
-> Escape backslashes in TypeScript strings: `\\d` for regex `\d`.
+**Notice:** `~` is PostgreSQL's case-sensitive POSIX regex operator.
 
+**Edge cases:**
+- Escape backslashes in TypeScript strings: `\\d` for regex `\d`.
+- No shape validation - any string operand is passed through as the pattern.
 
-## iregexp - Case-Insensitive Regular Expression
+## iregexp
 
 ```typescript
 { where: { name: { iregexp: '^john' } } }
 // SQL: WHERE "name" ~* '^john'
-// Matches: 'John Doe', 'JOHN SMITH', 'john'
 ```
 
+**Notice:** same as `regexp`, but case-insensitive (`~*`).
+
+**Edge cases:**
+- Matches `'John Doe'`, `'JOHN SMITH'`, and `'john'` alike.
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [JSON Filtering](./json-filtering) - pattern operators also work on a `'column.path'` key, with no numeric casting
+- [Quick Reference](./quick-reference) - every operator, one line each
 
-## Summary
+**Files:**
 
-| Operator | SQL | Case | Description |
-|----------|-----|------|-------------|
-| `like` | `LIKE` | Sensitive | Pattern with wildcards |
-| `nlike` | `NOT LIKE` | Sensitive | Negative pattern |
-| `ilike` | `ILIKE` | Insensitive | PostgreSQL only |
-| `nilike` | `NOT ILIKE` | Insensitive | PostgreSQL only |
-| `regexp` | `~` | Sensitive | POSIX regex match |
-| `iregexp` | `~*` | Insensitive | POSIX regex match |
+- [`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