@venizia/ignis-docs 0.0.3 → 0.0.4-1

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

@@ -0,0 +1,190 @@
+---
+title: Pro Tips & Edge Cases
+description: Advanced tips and common edge cases for filters
+difficulty: intermediate
+---
+
+# Pro Tips & Edge Cases
+
+Advanced tips and common edge cases when working with filters.
+
+
+## Tip 1: JSON Numeric vs String Comparison
+
+```typescript
+// JSON field contains: { "priority": "3" } (string)
+// This WON'T match numeric comparison!
+{ where: { 'metadata.priority': { gt: 2 } } }  // NULL due to safe casting
+
+// Use string comparison instead
+{ where: { 'metadata.priority': { gt: '2' } } }  // Lexicographic compare
+
+// Or ensure your data stores numbers properly
+{ "priority": 3 }  // Store as number, not string
+```
+
+
+## Tip 2: Empty Array Handling
+
+```typescript
+// Empty IN -> no results
+{ where: { id: { in: [] } } }  // SQL: WHERE false
+
+// Empty NIN -> all results
+{ where: { id: { nin: [] } } }  // SQL: WHERE true
+
+// Check array length before filtering
+const ids = getUserSelectedIds();
+if (ids.length === 0) {
+  return [];  // Early return instead of empty IN
+}
+```
+
+
+## Tip 3: Null-Safe JSON Paths
+
+```typescript
+// If JSON field doesn't exist, #>> returns NULL
+// This is safe - no errors, just no matches
+{ where: { 'metadata.nonexistent.field': 'value' } }
+// SQL: "metadata" #>> '{nonexistent,field}' = 'value'
+// Result: No rows (NULL != 'value')
+```
+
+
+## Tip 4: Performance with Large IN Arrays
+
+```typescript
+// For very large arrays (1000+ items), consider chunking
+const allIds = getLargeIdList();  // 5000 IDs
+
+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({
+    filter: { where: { id: { in: chunk } } }
+  });
+  results.push(...chunkResults);
+}
+```
+
+
+## Tip 5: Order By JSON Fields
+
+```typescript
+// JSON ordering uses #> (preserves type) not #>> (text)
+{ order: ['metadata.priority DESC'] }
+// SQL: "metadata" #> '{priority}' DESC
+
+// JSONB comparison order:
+// null < boolean < number < string < array < object
+```
+
+
+## Tip 6: Debugging Filters
+
+```typescript
+// Enable logging to see generated SQL
+const result = await repo.find({
+  filter: complexFilter,
+  options: {
+    log: { use: true, level: 'debug' },
+  },
+});
+
+// Or use buildQuery to inspect without executing
+const queryOptions = repo.buildQuery({ filter: complexFilter });
+console.log('Generated query options:', queryOptions);
+```
+
+
+## Tip 7: NOT IN with NULL Columns
+
+```typescript
+// NOT IN excludes NULL values!
+{ where: { status: { nin: ['deleted'] } } }
+// Rows where status IS NULL will NOT be returned
+
+// Include NULL values explicitly
+{
+  where: {
+    or: [
+      { status: { nin: ['deleted'] } },
+      { status: { is: null } }
+    ]
+  }
+}
+```
+
+
+## Tip 8: Combining Multiple Array Conditions
+
+```typescript
+await productRepo.find({
+  filter: {
+    where: {
+      // Must have ALL these categories
+      categories: { contains: ['electronics', 'portable'] },
+      // Tags must be subset of allowed tags
+      tags: { containedBy: ['new', 'sale', 'featured', 'popular'] },
+      // Must have at least one of these suppliers
+      suppliers: { overlaps: ['supplier-a', 'supplier-b'] }
+    }
+  }
+});
+```
+
+
+## Tip 9: Date Range Queries
+
+```typescript
+// This week's events
+const startOfWeek = new Date();
+startOfWeek.setDate(startOfWeek.getDate() - startOfWeek.getDay());
+const endOfWeek = new Date(startOfWeek);
+endOfWeek.setDate(endOfWeek.getDate() + 6);
+
+{
+  where: {
+    eventDate: { between: [startOfWeek, endOfWeek] }
+  }
+}
+
+// Last 30 days
+const thirtyDaysAgo = new Date();
+thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+
+{
+  where: {
+    createdAt: { gte: thirtyDaysAgo }
+  }
+}
+```
+
+
+## Tip 10: Reusable Filter Builders
+
+```typescript
+// Create reusable filter builders
+const createActiveFilter = <T extends { status: string; deletedAt: Date | null }>(): TWhere<T> => ({
+  status: 'active',
+  deletedAt: { is: null },
+} as TWhere<T>);
+
+const createPaginationFilter = (page: number, size: number = 20) => ({
+  limit: size,
+  skip: (page - 1) * size,
+});
+
+// Usage
+const products = await productRepo.find({
+  filter: {
+    where: {
+      ...createActiveFilter(),
+      category: 'electronics',
+    },
+    ...createPaginationFilter(3),
+  }
+});
+```

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

@@ -0,0 +1,452 @@
+---
+title: Use Case Gallery
+description: Real-world filter examples with corresponding SQL
+difficulty: intermediate
+---
+
+# Use Case Gallery
+
+Real-world examples of filter usage with corresponding SQL.
+
+
+## E-commerce Product Search
+
+```typescript
+const products = await productRepo.find({
+  filter: {
+    where: {
+      category: 'electronics',
+      price: { between: [100, 500] },
+      quantity: { gt: 0 },
+      status: 'active',
+    },
+    order: ['rating DESC', 'reviewCount DESC'],
+    fields: ['id', 'name', 'price', 'rating', 'imageUrl'],
+    limit: 24,
+  }
+});
+
+// SQL:
+// SELECT "id", "name", "price", "rating", "image_url"
+// FROM "Product"
+// WHERE "category" = 'electronics'
+//   AND "price" BETWEEN 100 AND 500
+//   AND "quantity" > 0
+//   AND "status" = 'active'
+// ORDER BY "rating" DESC, "review_count" DESC
+// LIMIT 24
+```
+
+
+## Admin Dashboard: Recent Users
+
+```typescript
+const thirtyDaysAgo = new Date();
+thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+
+const recentUsers = await userRepo.find({
+  filter: {
+    where: {
+      createdAt: { gte: thirtyDaysAgo },
+      status: { nin: ['banned', 'suspended'] },
+      emailVerifiedAt: { isn: null },
+    },
+    order: ['createdAt DESC'],
+    fields: ['id', 'email', 'name', 'createdAt', 'status'],
+    limit: 50,
+  }
+});
+
+// SQL:
+// SELECT "id", "email", "name", "created_at", "status"
+// FROM "User"
+// WHERE "created_at" >= '2024-12-01T00:00:00.000Z'
+//   AND "status" NOT IN ('banned', 'suspended')
+//   AND "email_verified_at" IS NOT NULL
+// ORDER BY "created_at" DESC
+// LIMIT 50
+```
+
+
+## Task Management: Priority Tags
+
+```typescript
+const priorityTasks = await taskRepo.find({
+  filter: {
+    where: {
+      status: { nin: ['completed', 'cancelled'] },
+      tags: { overlaps: ['urgent', 'high-priority'] },
+      assigneeId: currentUserId,
+    },
+    order: ['dueDate ASC', 'createdAt ASC'],
+    include: [{ relation: 'project' }],
+  }
+});
+
+// SQL:
+// SELECT "Task".*
+// FROM "Task"
+// WHERE "status" NOT IN ('completed', 'cancelled')
+//   AND "tags"::text[] && ARRAY['urgent', 'high-priority']::text[]
+//   AND "assignee_id" = 'user-123'
+// ORDER BY "due_date" ASC, "created_at" ASC
+//
+// -- Separate query for relation:
+// SELECT * FROM "Project" WHERE "id" IN (...)
+```
+
+
+## Soft Delete Handling
+
+```typescript
+// Find active records (soft delete pattern)
+const activeRecords = await repo.find({
+  filter: {
+    where: { deletedAt: { is: null } },
+  }
+});
+
+// SQL:
+// SELECT * FROM "Record" WHERE "deleted_at" IS NULL
+```
+
+```typescript
+// Find ONLY soft-deleted records
+const deletedRecords = await repo.find({
+  filter: {
+    where: { deletedAt: { isn: null } },
+  }
+});
+
+// SQL:
+// SELECT * FROM "Record" WHERE "deleted_at" IS NOT NULL
+```
+
+
+## Complex Authorization Filter
+
+```typescript
+const getAuthorizedFilter = (user: User): TWhere<TDocumentSchema> => {
+  if (user.role === 'admin') {
+    return { deletedAt: { is: null } };
+  }
+
+  return {
+    deletedAt: { is: null },
+    or: [
+      { ownerId: user.id },
+      { isPublic: true },
+      { sharedWithTeams: { overlaps: user.teamIds } },
+      { sharedWithUsers: { contains: [user.id] } },
+    ],
+  };
+};
+
+const documents = await documentRepo.find({
+  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"
+// WHERE "deleted_at" IS NULL
+//   AND (
+//     "owner_id" = 'user-123'
+//     OR "is_public" = true
+//     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
+```
+
+
+## Full-Text Search with Metadata
+
+```typescript
+const searchProducts = async (query: string, filters: {
+  minRating?: number;
+  maxPrice?: number;
+  features?: string[];
+}) => {
+  const where: TWhere<TProductSchema> = {
+    status: 'active',
+    deletedAt: { is: null },
+  };
+
+  if (query) {
+    where.or = [
+      { name: { ilike: `%${query}%` } },
+      { description: { ilike: `%${query}%` } },
+      { 'metadata.keywords': { ilike: `%${query}%` } },
+    ];
+  }
+
+  if (filters.minRating) {
+    where.rating = { gte: filters.minRating };
+  }
+
+  if (filters.maxPrice) {
+    where.price = { lte: filters.maxPrice };
+  }
+
+  if (filters.features?.length) {
+    where['metadata.features'] = { contains: filters.features };
+  }
+
+  return productRepo.find({
+    filter: {
+      where,
+      order: ['rating DESC', 'createdAt DESC'],
+      limit: 50,
+    },
+  });
+};
+
+// Example: searchProducts('wireless', { minRating: 4, maxPrice: 200, features: ['bluetooth'] })
+//
+// SQL:
+// 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 "rating" >= 4
+//   AND "price" <= 200
+//   AND "metadata" #>> '{features}' @> '["bluetooth"]'
+// ORDER BY "rating" DESC, "created_at" DESC
+// LIMIT 50
+```
+
+
+## Massive Filter Example
+
+```typescript
+const massiveFilter: TFilter<TProductSchema> = {
+  where: {
+    status: 'active',
+    deletedAt: { is: null },
+    price: { gte: 50, lte: 500 },
+    quantity: { gt: 0 },
+    tags: { contains: ['electronics', 'portable'] },
+    'metadata.priority': { gte: 3 },
+    'metadata.features.wireless': true,
+    or: [
+      { rating: { gte: 4.5 } },
+      {
+        and: [
+          { isFeatured: true },
+          { 'metadata.promotion.active': true },
+          { 'metadata.promotion.discount': { gte: 20 } },
+        ]
+      },
+      {
+        createdAt: { gte: new Date('2024-12-01') },
+        'metadata.isNewArrival': true,
+      },
+    ],
+    category: { nin: ['discontinued', 'recalled'] },
+    suppliers: { overlaps: ['supplier-a', 'supplier-b'] },
+  },
+  fields: ['id', 'name', 'price', 'rating', 'tags', 'metadata'],
+  order: ['metadata.priority DESC', 'rating DESC', 'createdAt DESC'],
+  limit: 20,
+  skip: 0,
+  include: [
+    { relation: 'category' },
+    {
+      relation: 'reviews',
+      scope: {
+        where: { rating: { gte: 4 } },
+        order: ['createdAt DESC'],
+        limit: 5,
+      },
+    },
+  ],
+};
+
+const products = await productRepo.find({ filter: massiveFilter });
+
+// SQL:
+// SELECT "id", "name", "price", "rating", "tags", "metadata"
+// FROM "Product"
+// WHERE "status" = 'active'
+//   AND "deleted_at" IS NULL
+//   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 "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'
+//     )
+//   )
+//   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:
+// 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
+```
+
+
+## Date Range Queries
+
+```typescript
+// Events this week
+const startOfWeek = new Date('2024-12-29');
+const endOfWeek = new Date('2025-01-04');
+
+const weekEvents = await eventRepo.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 orderRepo.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
+```
+
+
+## Multi-Tenant Data Isolation
+
+```typescript
+const getTenantProducts = async (tenantId: string, filter: TFilter<TProductSchema>) => {
+  return productRepo.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 productRepo.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
+```