@venizia/ignis-docs 0.0.2 → 0.0.4-0

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

@@ -0,0 +1,224 @@
+---
+title: Using Filters in Your Application
+description: How filters flow through application layers
+difficulty: intermediate
+---
+
+# Using Filters in Your Application
+
+How filters flow through the application layers.
+
+
+## Architecture Overview
+
+```
++-----------------------------------------------------------------+
+|                        HTTP Request                              |
+|   GET /products?filter={"where":{"status":"active"},"limit":10} |
++--------------------------------+--------------------------------+
+                                 |
+                                 v
++-----------------------------------------------------------------+
+|                     Controller Layer                             |
+|   - Validates filter via Zod schema                              |
+|   - Parses JSON string -> Filter object                          |
+|   - Passes to service/repository                                 |
++-----------------------------------------------------------------+
+                                 |
+                                 v
++-----------------------------------------------------------------+
+|                     Service Layer (Optional)                     |
+|   - Business logic, authorization                                |
+|   - May modify filter before passing                             |
++-----------------------------------------------------------------+
+                                 |
+                                 v
++-----------------------------------------------------------------+
+|                     Repository Layer                             |
+|   - FilterBuilder transforms Filter -> SQL                       |
+|   - Executes query via Drizzle ORM                               |
+|   - Returns typed results                                        |
++-----------------------------------------------------------------+
+```
+
+
+## Controller Layer
+
+### Using ControllerFactory (Recommended)
+
+The `ControllerFactory` automatically handles filter parsing and validation:
+
+```typescript
+// src/controllers/product.controller.ts
+import { Product } from '@/models';
+import { ProductRepository } from '@/repositories';
+import {
+  controller,
+  ControllerFactory,
+  inject,
+  BindingKeys,
+  BindingNamespaces,
+} from '@venizia/ignis';
+
+const BASE_PATH = '/products';
+
+const _Controller = ControllerFactory.defineCrudController({
+  repository: { name: ProductRepository.name },
+  controller: {
+    name: 'ProductController',
+    basePath: BASE_PATH,
+    isStrict: true,
+    defaultLimit: 20,
+  },
+  entity: () => Product,
+});
+
+@controller({ path: BASE_PATH })
+export class ProductController extends _Controller {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.REPOSITORY,
+        key: ProductRepository.name,
+      }),
+    })
+    repository: ProductRepository,
+  ) {
+    super(repository);
+  }
+}
+```
+
+**Generated Endpoints:**
+
+| 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/count` | Query param: `?where={...}` |
+
+### Custom Controller with Manual Filter Handling
+
+```typescript
+@controller({ path: '/products' })
+export class ProductController extends BaseController {
+  constructor(
+    @inject({ key: 'repositories.ProductRepository' })
+    private _productRepo: ProductRepository,
+  ) {
+    super({ scope: 'ProductController', path: '/products' });
+  }
+
+  override binding() {
+    this.defineRoute({
+      configs: {
+        path: '/search',
+        method: 'get',
+        query: {
+          filter: FilterSchema,
+        },
+      },
+      handler: async (context) => {
+        const { filter = {} } = context.req.valid('query');
+        const results = await this._productRepo.find({ filter });
+        return context.json(results);
+      },
+    });
+  }
+}
+```
+
+
+## Service Layer
+
+Services can modify filters before passing to repositories:
+
+```typescript
+@service()
+export class ProductService {
+  constructor(
+    @inject({ key: 'repositories.ProductRepository' })
+    private _productRepo: ProductRepository,
+  ) {}
+
+  async findProducts(filter: TFilter<TProductSchema> = {}) {
+    // Merge user filter with soft-delete condition
+    const enhancedFilter: TFilter<TProductSchema> = {
+      ...filter,
+      where: {
+        ...filter.where,
+        deletedAt: { is: null },
+      },
+    };
+
+    return this._productRepo.find({ filter: enhancedFilter });
+  }
+
+  async findProductsForTenant(
+    tenantId: string,
+    filter: TFilter<TProductSchema> = {},
+  ) {
+    const isolatedFilter: TFilter<TProductSchema> = {
+      ...filter,
+      where: {
+        ...filter.where,
+        tenantId,
+      },
+    };
+
+    return this._productRepo.find({ filter: isolatedFilter });
+  }
+}
+```
+
+
+## HTTP Request Examples
+
+**cURL:**
+```bash
+# Simple filter
+curl "http://localhost:3000/products?filter=%7B%22where%22%3A%7B%22status%22%3A%22active%22%7D%2C%22limit%22%3A10%7D"
+
+# Decoded filter: {"where":{"status":"active"},"limit":10}
+
+# Complex filter with URL encoding
+curl -G "http://localhost:3000/products" \
+  --data-urlencode 'filter={"where":{"price":{"gte":100,"lte":500},"tags":{"contains":["featured"]}},"order":["price ASC"],"limit":20}'
+```
+
+**JavaScript/TypeScript:**
+```typescript
+// Using fetch
+const filter = {
+  where: { status: 'active', price: { lte: 100 } },
+  order: ['createdAt DESC'],
+  limit: 10,
+};
+
+const response = await fetch(
+  `/api/products?filter=${encodeURIComponent(JSON.stringify(filter))}`
+);
+
+// Using axios
+const response = await axios.get('/api/products', {
+  params: { filter: JSON.stringify(filter) },
+});
+```
+
+
+## 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);
+```

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

@@ -0,0 +1,132 @@
+---
+title: PostgreSQL Array Operators
+description: Operators for PostgreSQL array columns
+difficulty: intermediate
+---
+
+# PostgreSQL Array Operators
+
+Operators for PostgreSQL array columns (`varchar[]`, `text[]`, `integer[]`, etc.).
+
+| Operator | PostgreSQL | Description |
+|----------|------------|-------------|
+| `contains` | `@>` | Array contains **ALL** specified elements |
+| `containedBy` | `<@` | Array is a **subset** of specified elements |
+| `overlaps` | `&&` | Array shares **ANY** element with specified |
+
+
+## contains (@>)
+
+Find rows where the array column contains **all** specified elements.
+
+```typescript
+// Schema: tags varchar(100)[]
+// Data: Product A has ['electronics', 'featured', 'sale']
+
+// Find products with BOTH 'electronics' AND 'featured'
+{ where: { tags: { contains: ['electronics', 'featured'] } } }
+// SQL: "tags"::text[] @> ARRAY['electronics', 'featured']::text[]
+
+// Single element
+{ where: { tags: { contains: ['featured'] } } }
+// Matches: ['featured'], ['featured', 'sale'], ['a', 'featured', 'b']
+```
+
+
+## containedBy (<@)
+
+Find rows where **all** array elements are within the specified set.
+
+```typescript
+// Find products where ALL tags are in the allowed list
+{ where: { tags: { containedBy: ['sale', 'featured', 'new', 'popular'] } } }
+// SQL: "tags"::text[] <@ ARRAY['sale', 'featured', 'new', 'popular']::text[]
+
+// Product A ['featured', 'sale'] -> matches (all in list)
+// Product B ['featured', 'clearance'] -> no match ('clearance' not in list)
+// Product C [] -> matches (empty is subset of everything)
+```
+
+
+## overlaps (&&)
+
+Find rows where the arrays share at least one common element.
+
+```typescript
+// Find products with 'premium' OR 'sale' tag
+{ where: { tags: { overlaps: ['premium', 'sale'] } } }
+// SQL: "tags"::text[] && ARRAY['premium', 'sale']::text[]
+
+// Product A ['featured', 'sale'] -> matches (has 'sale')
+// Product B ['premium', 'luxury'] -> matches (has 'premium')
+// Product C ['new', 'featured'] -> no match (no overlap)
+```
+
+
+## Visual Comparison
+
+| Product | tags | `contains ['featured']` | `containedBy ['a','b','featured']` | `overlaps ['sale','premium']` |
+|---------|------|------------------------|-----------------------------------|------------------------------|
+| A | `['featured', 'sale']` | Yes | No (has 'sale') | Yes (has 'sale') |
+| B | `['featured']` | Yes | Yes | No |
+| C | `['a', 'b']` | No | Yes | No |
+| D | `['premium']` | No | No | Yes (has 'premium') |
+| E | `[]` | No | Yes (empty subset) | No |
+
+
+## Decision Guide
+
+| Question | Use |
+|----------|-----|
+| "Must have ALL these tags" | `contains` |
+| "Tags must only be from this list" | `containedBy` |
+| "Must have AT LEAST ONE of these tags" | `overlaps` |
+
+
+## Empty Array Behavior
+
+| Operator | Empty Value `[]` | Behavior |
+|----------|------------------|----------|
+| `contains: []` | Returns **ALL** rows | Everything contains empty set |
+| `containedBy: []` | Returns only rows with **empty arrays** | Only `[]` is subset of `[]` |
+| `overlaps: []` | Returns **NO** rows | Nothing overlaps with empty |
+
+
+## Type Handling
+
+**String Arrays** (`varchar[]`, `text[]`, `char[]`):
+```typescript
+{ where: { tags: { contains: ['a', 'b'] } } }
+// SQL: "tags"::text[] @> ARRAY['a', 'b']::text[]
+```
+
+**Numeric Arrays** (`integer[]`, `numeric[]`):
+```typescript
+{ where: { scores: { contains: [100, 200] } } }
+// SQL: "scores" @> ARRAY[100, 200]
+```
+
+**Boolean Arrays**:
+```typescript
+{ where: { flags: { contains: [true, false] } } }
+// SQL: "flags" @> ARRAY[true, false]
+```
+
+
+## Defining Array Columns
+
+In your Drizzle schema:
+
+```typescript
+import { pgTable, text, varchar, integer } from 'drizzle-orm/pg-core';
+
+export const productTable = pgTable('Product', {
+  id: text('id').primaryKey(),
+  name: text('name').notNull(),
+
+  // Array columns
+  tags: varchar('tags', { length: 100 }).array(),      // varchar(100)[]
+  categories: text('categories').array(),              // text[]
+  scores: integer('scores').array(),                   // integer[]
+});
+```

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

@@ -0,0 +1,109 @@
+---
+title: Comparison Operators
+description: Equality and comparison operators for filtering records
+difficulty: intermediate
+---
+
+# Comparison Operators
+
+Equality and comparison operators for filtering records.
+
+
+## eq - Equal To
+
+Matches records where field equals the value.
+
+```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)
+```
+
+
+## ne / neq - Not Equal To
+
+Matches records where field does NOT equal the value.
+
+```typescript
+{ where: { status: { ne: 'deleted' } } }
+{ where: { status: { neq: 'deleted' } } }  // Alias
+
+// SQL: WHERE "status" != 'deleted'
+
+// Null handling
+{ where: { deletedAt: { ne: null } } }
+// SQL: WHERE "deleted_at" IS NOT NULL
+```
+
+
+## gt - Greater Than
+
+```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'
+```
+
+
+## gte - Greater Than or Equal
+
+```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
+```
+
+
+## lt - Less Than
+
+```typescript
+{ where: { stock: { lt: 5 } } }
+// SQL: WHERE "stock" < 5
+```
+
+
+## lte - Less Than or Equal
+
+```typescript
+{ where: { rating: { lte: 3 } } }
+// SQL: WHERE "rating" <= 3
+```
+
+
+## Summary
+
+| Operator | SQL | Description |
+|----------|-----|-------------|
+| `eq` | `=` | Equal to |
+| `ne` / `neq` | `!=` | Not equal to |
+| `gt` | `>` | Greater than |
+| `gte` | `>=` | Greater than or equal |
+| `lt` | `<` | Less than |
+| `lte` | `<=` | Less than or equal |