@venizia/ignis-docs 0.2.0 → 0.2.1-1

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

@@ -6,10 +6,33 @@ difficulty: intermediate
 
 # Use Case Gallery
 
-Real-world examples of filter usage with corresponding SQL.
+Runnable `filter` objects, paired with the SQL `FilterBuilder` produces for them. Copy the shape closest to what you need. For the operators themselves, start at the [Filter System Overview](./).
 
+## Soft delete
 
-## E-commerce Product Search
+Goal: return only non-deleted rows, or only deleted ones.
+
+```typescript
+// Active (non-deleted) records
+const activeRecords = await repository.find({
+  filter: { where: { deletedAt: { is: null } } },
+});
+// SQL: SELECT * FROM "Record" WHERE "deleted_at" IS NULL
+
+// ONLY soft-deleted records
+const deletedRecords = await repository.find({
+  filter: { where: { deletedAt: { isn: null } } },
+});
+// SQL: SELECT * FROM "Record" WHERE "deleted_at" IS NOT NULL
+```
+
+Notice: `is`/`isn` against a nullable timestamp is the whole pattern - no separate `deleted: boolean` column needed.
+
+If every query on a model should exclude deleted rows, encode this once as `settings.defaultFilter` instead of repeating it at every call site. See [Default Filter](./default-filter).
+
+## E-commerce product search
+
+Goal: a price range, a minimum quantity, and a status, sorted and paged for a listing page.
 
 ```typescript
 const products = await productRepository.find({
@@ -23,7 +46,7 @@ const products = await productRepository.find({
     order: ['rating DESC', 'reviewCount DESC'],
     fields: ['id', 'name', 'price', 'rating', 'imageUrl'],
     limit: 24,
-  }
+  },
 });
 
 // SQL:
@@ -37,8 +60,11 @@ const products = await productRepository.find({
 // LIMIT 24
 ```
 
+Notice: four `where` keys AND-compose automatically - no explicit `and` needed for a flat condition list.
+
+## Admin dashboard: recent users
 
-## Admin Dashboard: Recent Users
+Goal: users created in the last 30 days, excluding banned or suspended accounts, with a verified email.
 
 ```typescript
 const thirtyDaysAgo = new Date();
@@ -54,7 +80,7 @@ const recentUsers = await userRepository.find({
     order: ['createdAt DESC'],
     fields: ['id', 'email', 'name', 'createdAt', 'status'],
     limit: 50,
-  }
+  },
 });
 
 // SQL:
@@ -67,8 +93,39 @@ const recentUsers = await userRepository.find({
 // LIMIT 50
 ```
 
+Notice: `nin` on `status` silently drops any row where `status` is `NULL`. See [Tips & Edge Cases](./tips) before relying on this for a nullable column.
+
+## Multi-tenant isolation at the call site
 
-## Task Management: Priority Tags
+`settings.defaultFilter` (see [Default Filter](./default-filter)) is the model-level way to enforce a tenant scope. The alternative below is a helper that injects `tenantId` at every call site instead. Use it when tenant isolation is a caller concern, not a per-model constant.
+
+```typescript
+const getTenantProducts = (tenantId: string, filter: TFilter<TProductSchema>) =>
+  productRepository.find({
+    filter: {
+      ...filter,
+      where: { ...filter.where, tenantId, deletedAt: { is: null } },
+    },
+  });
+
+await getTenantProducts('tenant-abc', {
+  where: { category: 'electronics' },
+  order: ['createdAt DESC'],
+  limit: 20,
+});
+
+// SQL:
+// SELECT * FROM "Product"
+// WHERE "category" = 'electronics' AND "tenant_id" = 'tenant-abc' AND "deleted_at" IS NULL
+// ORDER BY "created_at" DESC
+// LIMIT 20
+```
+
+Notice: this is a plain object spread, not `mergeFilter`'s narrowing merge - `tenantId`/`deletedAt` overwrite same-named keys from `filter.where` because they're spread last.
+
+## Task management: priority tags
+
+Goal: open tasks assigned to the current user that carry an urgent or high-priority tag, with the parent project loaded.
 
 ```typescript
 const priorityTasks = await taskRepository.find({
@@ -80,7 +137,7 @@ const priorityTasks = await taskRepository.find({
     },
     order: ['dueDate ASC', 'createdAt ASC'],
     include: [{ relation: 'project' }],
-  }
+  },
 });
 
 // SQL:
@@ -95,35 +152,87 @@ const priorityTasks = await taskRepository.find({
 // SELECT * FROM "Project" WHERE "id" IN (...)
 ```
 
+Notice: `include` runs as a separate query, not a SQL `JOIN` - see [Relations & Includes](../repositories/relations).
 
-## Soft Delete Handling
+## Date range queries
+
+Goal: a closed window (a specific week) versus a rolling window (the last 7 days).
 
 ```typescript
-// Find active records (soft delete pattern)
-const activeRecords = await repository.find({
+const startOfWeek = new Date('2024-12-29');
+const endOfWeek = new Date('2025-01-04');
+
+const weekEvents = await eventRepository.find({
   filter: {
-    where: { deletedAt: { is: null } },
-  }
+    where: { eventDate: { between: [startOfWeek, endOfWeek] } },
+    order: ['eventDate ASC'],
+  },
 });
+// SQL: SELECT * FROM "Event" WHERE "event_date" BETWEEN '2024-12-29' AND '2025-01-04' ORDER BY "event_date" ASC
+```
 
+```typescript
+const sevenDaysAgo = new Date();
+sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
+
+const recentOrders = await orderRepository.find({
+  filter: {
+    where: {
+      createdAt: { gte: sevenDaysAgo },
+      status: { in: ['completed', 'shipped'] },
+      total: { gte: 100 },
+    },
+    order: ['total DESC'],
+    limit: 100,
+  },
+});
 // SQL:
-// SELECT * FROM "Record" WHERE "deleted_at" IS NULL
+// SELECT * FROM "Order"
+// WHERE "created_at" >= '2024-12-24T00:00:00.000Z' AND "status" IN ('completed', 'shipped') AND "total" >= 100
+// ORDER BY "total" DESC LIMIT 100
 ```
 
+Notice: `between` needs exactly two elements - `FilterBuilder` throws on any other array length.
+
+## Inventory low-stock alert
+
+Goal: active products at or under a reorder threshold, flagged critical below 5 units or fast-moving stock at 10 or fewer.
+
 ```typescript
-// Find ONLY soft-deleted records
-const deletedRecords = await repository.find({
+const lowStockProducts = await productRepository.find({
   filter: {
-    where: { deletedAt: { isn: null } },
-  }
+    where: {
+      status: 'active',
+      quantity: { lte: 10 },
+      'metadata.reorderPoint': { isn: null },
+      or: [
+        { quantity: { lt: 5 } }, // Critical: below 5
+        { and: [{ quantity: { lte: 10 } }, { 'metadata.fastMoving': true }] },
+      ],
+    },
+    order: ['quantity ASC'],
+    fields: ['id', 'name', 'quantity', 'metadata'],
+  },
 });
 
 // SQL:
-// SELECT * FROM "Record" WHERE "deleted_at" IS NOT NULL
+// SELECT "id", "name", "quantity", "metadata"
+// FROM "Product"
+// WHERE "status" = 'active'
+//   AND "quantity" <= 10
+//   AND "metadata" #>> '{reorderPoint}' IS NOT NULL
+//   AND (
+//     "quantity" < 5
+//     OR ("quantity" <= 10 AND "metadata" #>> '{fastMoving}' = 'true')
+//   )
+// ORDER BY "quantity" ASC
 ```
 
+Notice: `or` nests an `and` group one level deep - `FilterBuilder` recurses through logical groups, so nesting depth is not limited to one.
+
+## Complex authorization filter
 
-## Complex Authorization Filter
+Goal: an admin sees everything; everyone else sees only what they own, what is public, or what is shared with them.
 
 ```typescript
 const getAuthorizedFilter = (user: User): TWhere<TDocumentSchema> => {
@@ -143,23 +252,11 @@ const getAuthorizedFilter = (user: User): TWhere<TDocumentSchema> => {
 };
 
 const documents = await documentRepository.find({
-  filter: {
-    where: getAuthorizedFilter(currentUser),
-    order: ['updatedAt DESC'],
-    limit: 100,
-  },
+  filter: { where: getAuthorizedFilter(currentUser), order: ['updatedAt DESC'], limit: 100 },
 });
 
-// SQL (for admin):
-// SELECT *
-// FROM "Document"
-// WHERE "deleted_at" IS NULL
-// ORDER BY "updated_at" DESC
-// LIMIT 100
-
-// SQL (for regular user):
-// SELECT *
-// FROM "Document"
+// SQL (regular user):
+// SELECT * FROM "Document"
 // WHERE "deleted_at" IS NULL
 //   AND (
 //     "owner_id" = 'user-123'
@@ -167,23 +264,21 @@ const documents = await documentRepository.find({
 //     OR "shared_with_teams"::text[] && ARRAY['team-1', 'team-2']::text[]
 //     OR "shared_with_users"::text[] @> ARRAY['user-123']::text[]
 //   )
-// ORDER BY "updated_at" DESC
-// LIMIT 100
+// ORDER BY "updated_at" DESC LIMIT 100
 ```
 
+Notice: a plain TypeScript function builds the `where`, branching on role. A filter is a normal object, not a DSL with its own control flow.
+
+## Full-text search with metadata
 
-## Full-Text Search with Metadata
+Goal: assemble a `where` clause from optional caller input, adding a key only when the caller supplied it.
 
 ```typescript
-const searchProducts = async (query: string, filters: {
-  minRating?: number;
-  maxPrice?: number;
-  categories?: string[];
-}) => {
-  const where: TWhere<TProductSchema> = {
-    status: 'active',
-    deletedAt: { is: null },
-  };
+const searchProducts = async (
+  query: string,
+  filters: { minRating?: number; maxPrice?: number; categories?: string[] },
+) => {
+  const where: TWhere<TProductSchema> = { status: 'active', deletedAt: { is: null } };
 
   if (query) {
     where.or = [
@@ -192,50 +287,33 @@ const searchProducts = async (query: string, filters: {
       { 'metadata.keywords': { ilike: `%${query}%` } },
     ];
   }
-
-  if (filters.minRating) {
-    where.rating = { gte: filters.minRating };
-  }
-
-  if (filters.maxPrice) {
-    where.price = { lte: filters.maxPrice };
-  }
-
-  if (filters.categories?.length) {
-    // Use array operator on a PostgreSQL array column
-    where.categories = { contains: filters.categories };
-  }
+  if (filters.minRating) where.rating = { gte: filters.minRating };
+  if (filters.maxPrice) where.price = { lte: filters.maxPrice };
+  if (filters.categories?.length) where.categories = { contains: filters.categories };
 
   return productRepository.find({
-    filter: {
-      where,
-      order: ['rating DESC', 'createdAt DESC'],
-      limit: 50,
-    },
+    filter: { where, order: ['rating DESC', 'createdAt DESC'], limit: 50 },
   });
 };
 
-// Example: searchProducts('wireless', { minRating: 4, maxPrice: 200, categories: ['electronics'] })
+// searchProducts('wireless', { minRating: 4, maxPrice: 200, categories: ['electronics'] })
 //
 // SQL:
-// SELECT *
-// FROM "Product"
+// SELECT * FROM "Product"
 // WHERE "status" = 'active'
 //   AND "deleted_at" IS NULL
-//   AND (
-//     "name" ILIKE '%wireless%'
-//     OR "description" ILIKE '%wireless%'
-//     OR "metadata" #>> '{keywords}' ILIKE '%wireless%'
-//   )
+//   AND ("name" ILIKE '%wireless%' OR "description" ILIKE '%wireless%' OR "metadata" #>> '{keywords}' ILIKE '%wireless%')
 //   AND "rating" >= 4
 //   AND "price" <= 200
 //   AND "categories"::text[] @> ARRAY['electronics']::text[]
-// ORDER BY "rating" DESC, "created_at" DESC
-// LIMIT 50
+// ORDER BY "rating" DESC, "created_at" DESC LIMIT 50
 ```
 
+Notice: `ilike` reaches into a JSON path (`'metadata.keywords'`) the same way it reaches a top-level column.
+
+## Everything at once
 
-## Massive Filter Example
+Every operator family, a JSON path, a three-way `or`, and a scoped relation include - all in one filter. This is the ceiling of what a single `TFilter` can express.
 
 ```typescript
 const massiveFilter: TFilter<TProductSchema> = {
@@ -254,12 +332,9 @@ const massiveFilter: TFilter<TProductSchema> = {
           { isFeatured: true },
           { 'metadata.promotion.active': true },
           { 'metadata.promotion.discount': { gte: 20 } },
-        ]
-      },
-      {
-        createdAt: { gte: new Date('2024-12-01') },
-        'metadata.isNewArrival': true,
+        ],
       },
+      { createdAt: { gte: new Date('2024-12-01') }, 'metadata.isNewArrival': true },
     ],
     category: { nin: ['discontinued', 'recalled'] },
     suppliers: { overlaps: ['supplier-a', 'supplier-b'] },
@@ -270,14 +345,7 @@ const massiveFilter: TFilter<TProductSchema> = {
   skip: 0,
   include: [
     { relation: 'category' },
-    {
-      relation: 'reviews',
-      scope: {
-        where: { rating: { gte: 4 } },
-        order: ['createdAt DESC'],
-        limit: 5,
-      },
-    },
+    { relation: 'reviews', scope: { where: { rating: { gte: 4 } }, order: ['createdAt DESC'], limit: 5 } },
   ],
 };
 
@@ -291,163 +359,36 @@ const products = await productRepository.find({ filter: massiveFilter });
 //   AND "price" >= 50 AND "price" <= 500
 //   AND "quantity" > 0
 //   AND "tags"::text[] @> ARRAY['electronics', 'portable']::text[]
-//   AND CASE
-//     WHEN ("metadata" #>> '{priority}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//     THEN ("metadata" #>> '{priority}')::numeric ELSE NULL
-//   END >= 3
+//   AND CASE WHEN ("metadata" #>> '{priority}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//       THEN ("metadata" #>> '{priority}')::numeric ELSE NULL END >= 3
 //   AND "metadata" #>> '{features,wireless}' = 'true'
 //   AND (
 //     "rating" >= 4.5
-//     OR (
-//       "is_featured" = true
-//       AND "metadata" #>> '{promotion,active}' = 'true'
-//       AND CASE
-//         WHEN ("metadata" #>> '{promotion,discount}') ~ '^-?[0-9]+(\.[0-9]+)?$'
-//         THEN ("metadata" #>> '{promotion,discount}')::numeric ELSE NULL
-//       END >= 20
-//     )
-//     OR (
-//       "created_at" >= '2024-12-01T00:00:00.000Z'
-//       AND "metadata" #>> '{isNewArrival}' = 'true'
-//     )
+//     OR ("is_featured" = true AND "metadata" #>> '{promotion,active}' = 'true'
+//         AND CASE WHEN ("metadata" #>> '{promotion,discount}') ~ '^-?[0-9]+(\.[0-9]+)?$'
+//             THEN ("metadata" #>> '{promotion,discount}')::numeric ELSE NULL END >= 20)
+//     OR ("created_at" >= '2024-12-01T00:00:00.000Z' AND "metadata" #>> '{isNewArrival}' = 'true')
 //   )
 //   AND "category" NOT IN ('discontinued', 'recalled')
 //   AND "suppliers"::text[] && ARRAY['supplier-a', 'supplier-b']::text[]
 // ORDER BY "metadata" #> '{priority}' DESC, "rating" DESC, "created_at" DESC
 // LIMIT 20 OFFSET 0
 //
-// -- Separate query for category relation:
+// -- Separate queries for relations:
 // SELECT * FROM "Category" WHERE "id" IN (...)
-//
-// -- Separate query for reviews relation:
-// SELECT * FROM "Review"
-// WHERE "product_id" IN (...) AND "rating" >= 4
-// ORDER BY "created_at" DESC
-// LIMIT 5
+// SELECT * FROM "Review" WHERE "product_id" IN (...) AND "rating" >= 4 ORDER BY "created_at" DESC LIMIT 5
 ```
 
+Notice: `'metadata.priority': { gte: 3 }` gets the numeric `CASE` cast because the operand is a number. `'metadata.isNewArrival': true` does not, because it compares as text. See [Tips & Edge Cases](./tips) for the full casting rule.
 
-## Date Range Queries
-
-```typescript
-// Events this week
-const startOfWeek = new Date('2024-12-29');
-const endOfWeek = new Date('2025-01-04');
-
-const weekEvents = await eventRepository.find({
-  filter: {
-    where: {
-      eventDate: { between: [startOfWeek, endOfWeek] }
-    },
-    order: ['eventDate ASC']
-  }
-});
-
-// SQL:
-// SELECT *
-// FROM "Event"
-// WHERE "event_date" BETWEEN '2024-12-29' AND '2025-01-04'
-// ORDER BY "event_date" ASC
-```
-
-```typescript
-// Orders in the last 7 days
-const sevenDaysAgo = new Date();
-sevenDaysAgo.setDate(sevenDaysAgo.getDate() - 7);
-
-const recentOrders = await orderRepository.find({
-  filter: {
-    where: {
-      createdAt: { gte: sevenDaysAgo },
-      status: { in: ['completed', 'shipped'] },
-      total: { gte: 100 }
-    },
-    order: ['total DESC'],
-    limit: 100
-  }
-});
-
-// SQL:
-// SELECT *
-// FROM "Order"
-// WHERE "created_at" >= '2024-12-24T00:00:00.000Z'
-//   AND "status" IN ('completed', 'shipped')
-//   AND "total" >= 100
-// ORDER BY "total" DESC
-// LIMIT 100
-```
+## See also
 
+- [Filter System Overview](./) - the `filter` shape and every `where` operator family
+- [Default Filter](./default-filter) - model-level scoping instead of the call-site pattern shown above
+- [Application Usage](./application-usage) - how a filter reaches the repository from an HTTP request
+- [Tips & Edge Cases](./tips) - `NULL` handling, empty-array semantics, and other gotchas that show up in filters like these
 
-## Multi-Tenant Data Isolation
+**Files:**
 
-```typescript
-const getTenantProducts = async (tenantId: string, filter: TFilter<TProductSchema>) => {
-  return productRepository.find({
-    filter: {
-      ...filter,
-      where: {
-        ...filter.where,
-        tenantId,  // Always enforce tenant isolation
-        deletedAt: { is: null },
-      },
-    },
-  });
-};
-
-// Usage
-await getTenantProducts('tenant-abc', {
-  where: { category: 'electronics' },
-  order: ['createdAt DESC'],
-  limit: 20
-});
-
-// SQL:
-// SELECT *
-// FROM "Product"
-// WHERE "category" = 'electronics'
-//   AND "tenant_id" = 'tenant-abc'
-//   AND "deleted_at" IS NULL
-// ORDER BY "created_at" DESC
-// LIMIT 20
-```
-
-
-## Inventory Low Stock Alert
-
-```typescript
-const lowStockProducts = await productRepository.find({
-  filter: {
-    where: {
-      status: 'active',
-      quantity: { lte: 10 },
-      'metadata.reorderPoint': { isn: null },
-      or: [
-        { quantity: { lt: 5 } },  // Critical: below 5
-        {
-          and: [
-            { quantity: { lte: 10 } },
-            { 'metadata.fastMoving': true }
-          ]
-        }
-      ]
-    },
-    order: ['quantity ASC'],
-    fields: ['id', 'name', 'quantity', 'metadata']
-  }
-});
-
-// SQL:
-// SELECT "id", "name", "quantity", "metadata"
-// FROM "Product"
-// WHERE "status" = 'active'
-//   AND "quantity" <= 10
-//   AND "metadata" #>> '{reorderPoint}' IS NOT NULL
-//   AND (
-//     "quantity" < 5
-//     OR (
-//       "quantity" <= 10
-//       AND "metadata" #>> '{fastMoving}' = 'true'
-//     )
-//   )
-// ORDER BY "quantity" ASC
-```
+- [`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/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