@venizia/ignis-docs 0.0.2 → 0.0.4-0

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

@@ -0,0 +1,428 @@
+---
+title: Default Filter
+description: Automatically apply filter conditions to all repository queries
+difficulty: intermediate
+lastUpdated: 2026-01-02
+---
+
+# Default Filter <Badge type="tip" text="v0.0.5+" />
+
+Automatically apply filter conditions to all repository queries at the model level.
+
+::: info Added in v0.0.5
+This feature was introduced in IGNIS v0.0.5 to support soft delete, multi-tenancy, and other automatic filtering patterns.
+:::
+
+> [!NOTE]
+> Default filters are ideal for:
+> - **Soft Delete**: Automatically exclude deleted records
+> - **Multi-Tenancy**: Isolate data by tenant
+> - **Active Records**: Filter to active/non-expired records
+> - **Query Limits**: Prevent unbounded queries
+
+
+## Quick Start
+
+Configure a default filter in your model:
+
+```typescript
+import { model, BaseEntity } from '@venizia/ignis';
+import { userTable } from '@/schemas';
+
+@model({
+  type: 'entity',
+  settings: {
+    // Applied to all repository queries
+    defaultFilter: {
+      where: { isDeleted: false },
+      limit: 100,
+    },
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {
+  static override schema = userTable;
+}
+```
+
+Now all queries automatically include the default filter:
+
+```typescript
+// Your code
+await userRepo.find({
+  filter: { where: { status: 'active' } }
+});
+
+// Actual query executed
+// WHERE isDeleted = false AND status = 'active' LIMIT 100
+```
+
+
+## Configuration
+
+### Default Filter Properties
+
+All standard filter properties are supported:
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      // WHERE conditions
+      where: { isDeleted: false, tenantId: 'tenant-123' },
+
+      // Maximum results (prevents unbounded queries)
+      limit: 100,
+
+      // Default pagination offset
+      offset: 0,
+
+      // Default sort order
+      order: ['createdAt DESC'],
+
+      // Default field selection
+      fields: ['id', 'name', 'email', 'createdAt'],
+
+      // Default relations to include
+      include: [{ relation: 'profile' }],
+    },
+  },
+})
+export class User extends BaseEntity<typeof User.schema> {}
+```
+
+
+## Merge Behavior
+
+When a user provides a filter, it is merged with the default filter:
+
+| Property | Merge Strategy |
+|----------|----------------|
+| `where` | **Deep merge** - user values override matching keys |
+| `limit` | User replaces default (if provided) |
+| `offset`/`skip` | User replaces default (if provided) |
+| `order` | User replaces default (if provided) |
+| `fields` | User replaces default (if provided) |
+| `include` | User replaces default (if provided) |
+
+### Where Clause Merging
+
+The `where` clause uses deep merge with user values taking precedence:
+
+```typescript
+// Default filter
+{ where: { isDeleted: false, status: 'pending' }, limit: 100 }
+
+// User filter
+{ where: { status: 'active', role: 'admin' }, limit: 10 }
+
+// Merged result
+{
+  where: {
+    isDeleted: false,    // From default (preserved)
+    status: 'active',    // User overrides default
+    role: 'admin'        // From user (added)
+  },
+  limit: 10              // User overrides default
+}
+```
+
+### Complex Where Conditions
+
+```typescript
+// Default: soft delete and tenant isolation
+const defaultFilter = {
+  where: {
+    isDeleted: false,
+    tenantId: 'tenant-123',
+  }
+};
+
+// User: OR conditions
+const userFilter = {
+  where: {
+    or: [{ status: 'active' }, { priority: 'high' }]
+  }
+};
+
+// Result: AND of default + OR from user
+// WHERE isDeleted = false AND tenantId = 'tenant-123'
+//   AND (status = 'active' OR priority = 'high')
+```
+
+### Operator Object Merging
+
+Operator objects are deep merged, allowing range combinations:
+
+```typescript
+// Default: created after 2024
+const defaultFilter = {
+  where: {
+    createdAt: { gte: '2024-01-01' }
+  }
+};
+
+// User: created before end of 2024
+const userFilter = {
+  where: {
+    createdAt: { lte: '2024-12-31' }
+  }
+};
+
+// Result: date range
+{
+  where: {
+    createdAt: { gte: '2024-01-01', lte: '2024-12-31' }
+  }
+}
+```
+
+
+## Bypassing Default Filter
+
+Use `shouldSkipDefaultFilter: true` to bypass the default filter:
+
+```typescript
+// Normal query - default filter applies
+await repo.find({
+  filter: { where: { role: 'admin' } }
+});
+// WHERE isDeleted = false AND role = 'admin'
+
+// Admin query - bypass default filter
+await repo.find({
+  filter: { where: { role: 'admin' } },
+  options: { shouldSkipDefaultFilter: true }
+});
+// WHERE role = 'admin' (includes deleted records)
+```
+
+### Supported Operations
+
+`shouldSkipDefaultFilter` works with all repository methods:
+
+```typescript
+// Read operations
+await repo.find({ filter, options: { shouldSkipDefaultFilter: true } });
+await repo.findOne({ filter, options: { shouldSkipDefaultFilter: true } });
+await repo.findById({ id, options: { shouldSkipDefaultFilter: true } });
+await repo.count({ where, options: { shouldSkipDefaultFilter: true } });
+
+// Update operations
+await repo.updateById({ id, data, options: { shouldSkipDefaultFilter: true } });
+await repo.updateAll({ where, data, options: { shouldSkipDefaultFilter: true } });
+
+// Delete operations
+await repo.deleteById({ id, options: { shouldSkipDefaultFilter: true } });
+await repo.deleteAll({ where, options: { shouldSkipDefaultFilter: true, force: true } });
+```
+
+### Use Cases for Bypassing
+
+| Scenario | Example |
+|----------|---------|
+| Admin dashboard | View all records including deleted |
+| Data recovery | Restore soft-deleted records |
+| Analytics | Count across all tenants |
+| Data migration | Update records regardless of status |
+| Audit logs | Access historical data |
+
+
+## Common Patterns
+
+### Soft Delete
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { deletedAt: null },  // or { isDeleted: false }
+    },
+  },
+})
+export class Post extends BaseEntity<typeof Post.schema> {}
+
+// All queries exclude deleted posts
+await postRepo.find({ filter: {} });
+// WHERE deletedAt IS NULL
+
+// Restore a deleted post
+await postRepo.updateById({
+  id: postId,
+  data: { deletedAt: null },
+  options: { shouldSkipDefaultFilter: true }
+});
+```
+
+### Multi-Tenant Isolation
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: { tenantId: 'current-tenant' },
+    },
+  },
+})
+export class Document extends BaseEntity<typeof Document.schema> {}
+
+// Queries scoped to tenant
+await docRepo.find({ filter: { where: { type: 'invoice' } } });
+// WHERE tenantId = 'current-tenant' AND type = 'invoice'
+
+// Cross-tenant admin query
+await docRepo.find({
+  filter: { where: { type: 'invoice' } },
+  options: { shouldSkipDefaultFilter: true }
+});
+// WHERE type = 'invoice'
+```
+
+### Active Records
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      where: {
+        isActive: true,
+        expiresAt: { gt: new Date().toISOString() },
+      },
+      limit: 50,
+    },
+  },
+})
+export class Subscription extends BaseEntity<typeof Subscription.schema> {}
+```
+
+### Query Limit Protection
+
+```typescript
+@model({
+  type: 'entity',
+  settings: {
+    defaultFilter: {
+      limit: 1000,  // Prevent unbounded queries
+    },
+  },
+})
+export class LogEntry extends BaseEntity<typeof LogEntry.schema> {}
+
+// User can override limit, but there's always a sensible default
+await logRepo.find({ filter: {} });           // LIMIT 1000
+await logRepo.find({ filter: { limit: 50 } }); // LIMIT 50
+```
+
+
+## IExtraOptions Interface
+
+The `shouldSkipDefaultFilter` option is part of the `IExtraOptions` interface:
+
+```typescript
+interface IExtraOptions extends IWithTransaction {
+  /**
+   * If true, bypass the default filter configured in model settings.
+   */
+  shouldSkipDefaultFilter?: boolean;
+}
+
+interface IWithTransaction {
+  transaction?: ITransaction;
+}
+```
+
+This allows combining with transactions:
+
+```typescript
+const tx = await repo.beginTransaction();
+
+try {
+  // Both transaction and shouldSkipDefaultFilter
+  await repo.updateAll({
+    where: { status: 'archived' },
+    data: { isDeleted: true },
+    options: {
+      transaction: tx,
+      shouldSkipDefaultFilter: true,
+    }
+  });
+
+  await tx.commit();
+} catch (e) {
+  await tx.rollback();
+  throw e;
+}
+```
+
+
+## How It Works
+
+### Architecture
+
+```
++------------------+     +------------------+     +------------------+
+|  Model Settings  | --> | DefaultFilterMixin | --> | Repository Method |
+|  defaultFilter   |     | applyDefaultFilter |     | find/count/etc   |
++------------------+     +------------------+     +------------------+
+                                |
+                                v
+                         +------------------+
+                         |  FilterBuilder   |
+                         |  mergeFilter()   |
+                         +------------------+
+```
+
+### DefaultFilterMixin
+
+The `DefaultFilterMixin` provides:
+
+```typescript
+// Check if default filter is configured
+hasDefaultFilter(): boolean
+
+// Get the raw default filter from model metadata
+getDefaultFilter(): TFilter | undefined
+
+// Merge default filter with user filter
+applyDefaultFilter(opts: {
+  userFilter?: TFilter;
+  shouldSkipDefaultFilter?: boolean;
+}): TFilter
+```
+
+### FilterBuilder.mergeFilter()
+
+The merge logic is implemented in `FilterBuilder`:
+
+```typescript
+const filterBuilder = new FilterBuilder();
+
+const merged = filterBuilder.mergeFilter({
+  defaultFilter: { where: { isDeleted: false }, limit: 100 },
+  userFilter: { where: { status: 'active' }, limit: 10 }
+});
+
+// Result:
+// { where: { isDeleted: false, status: 'active' }, limit: 10 }
+```
+
+
+## Quick Reference
+
+| Want to... | Code |
+|------------|------|
+| Configure default filter | `@model({ settings: { defaultFilter: { ... } } })` |
+| Bypass default filter | `options: { shouldSkipDefaultFilter: true }` |
+| Combine with transaction | `options: { transaction: tx, shouldSkipDefaultFilter: true }` |
+| Check if model has default | `repo.hasDefaultFilter()` |
+| Get raw default filter | `repo.getDefaultFilter()` |
+
+
+## Next Steps
+
+- [Filter System Overview](./index.md) - Filter structure and operators
+- [Repository Mixins](../repositories/mixins.md) - Mixin architecture
+- [Advanced Features](../repositories/advanced.md) - Transactions, hidden properties

package/wiki/references/base/filter-system/fields-order-pagination.md

@@ -0,0 +1,155 @@
+---
+title: Fields, Ordering & Pagination
+description: Control field selection, sorting, and pagination
+difficulty: intermediate
+---
+
+# Fields, Ordering & Pagination
+
+Control which fields are returned, how results are sorted, and how to paginate.
+
+
+## Field Selection
+
+Control which fields are returned using `fields`:
+
+### Array Format (Recommended)
+
+```typescript
+await repo.find({
+  filter: {
+    where: { status: 'active' },
+    fields: ['id', 'email', 'name']
+  }
+});
+// Returns only: { id, email, name }
+```
+
+### Object Format
+
+```typescript
+// Include specific fields
+await repo.find({
+  filter: {
+    fields: { id: true, email: true, name: true }
+  }
+});
+
+// Exclude specific fields
+await repo.find({
+  filter: {
+    fields: { password: false, secret: false }
+  }
+});
+```
+
+
+## Ordering
+
+### Basic Ordering
+
+```typescript
+// Single column, descending
+await repo.find({
+  filter: { order: ['createdAt DESC'] }
+});
+
+// Multiple columns
+await repo.find({
+  filter: { order: ['status ASC', 'createdAt DESC'] }
+});
+
+// Default direction is ASC
+await repo.find({
+  filter: { order: ['name'] }  // Same as 'name ASC'
+});
+```
+
+### JSON Path Ordering
+
+Order by nested fields in JSON columns:
+
+```typescript
+await repo.find({
+  filter: { order: ['metadata.priority DESC'] }
+});
+// SQL: ORDER BY "metadata" #> '{priority}' DESC
+
+await repo.find({
+  filter: { order: ['settings.display.theme ASC'] }
+});
+```
+
+### JSONB Sort Order
+
+| JSONB Type | Sort Order |
+|------------|------------|
+| `null` | First (lowest) |
+| `boolean` | `false` < `true` |
+| `number` | Numeric order |
+| `string` | Lexicographic |
+| `array` | Element-wise |
+| `object` | Key-value |
+
+
+## Pagination
+
+### Limit and Skip
+
+```typescript
+// First 10 results
+await repo.find({
+  filter: { limit: 10 }
+});
+
+// Page 2 (skip first 10, get next 10)
+await repo.find({
+  filter: { limit: 10, skip: 10 }
+});
+
+// Page N formula: skip = (page - 1) * limit
+const page = 3;
+const pageSize = 20;
+await repo.find({
+  filter: {
+    limit: pageSize,
+    skip: (page - 1) * pageSize
+  }
+});
+```
+
+> [!TIP]
+> Always use `limit` for public-facing endpoints to prevent memory exhaustion.
+
+### Pagination Helper
+
+```typescript
+function getPaginationFilter(page: number, pageSize: number = 20) {
+  return {
+    limit: pageSize,
+    skip: (page - 1) * pageSize
+  };
+}
+
+// Usage
+const filter = {
+  where: { status: 'active' },
+  ...getPaginationFilter(3, 20)
+};
+// { where: {...}, limit: 20, skip: 40 }
+```
+
+
+## Combined Example
+
+```typescript
+await repo.find({
+  filter: {
+    where: { status: 'active' },
+    fields: ['id', 'name', 'price', 'createdAt'],
+    order: ['price ASC', 'createdAt DESC'],
+    limit: 20,
+    skip: 0
+  }
+});
+```

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

@@ -0,0 +1,127 @@
+---
+title: Filter System Overview
+description: Complete reference for the IGNIS filter system
+difficulty: intermediate
+---
+
+# Filter System
+
+Complete reference for the Ignis filter system - operators, JSON filtering, array operators, default filters, and query patterns.
+
+> [!NOTE]
+> If you're new to Ignis, start with:
+> - [5-Minute Quickstart](/guides/get-started/5-minute-quickstart) - Get up and running
+> - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Learn the basics
+> - [Repositories](/references/base/repositories) - Repository overview
+
+## Prerequisites
+
+Before reading this document, you should understand:
+
+- [Repositories](../repositories/) - Basic repository operations (find, create, update, delete)
+- [Models](../models.md) - Entity definitions and schemas
+- SQL basics - Understanding of WHERE clauses and operators
+- TypeScript type system - Type safety and inference
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [**⚡ Quick Reference**](./quick-reference.md) | **Single-page cheat sheet of all operators** |
+| [Comparison Operators](./comparison-operators.md) | Equality, range, null checks |
+| [Pattern Matching](./pattern-matching.md) | LIKE, ILIKE, regex |
+| [Logical Operators](./logical-operators.md) | AND, OR combinations |
+| [List Operators](./list-operators.md) | IN, NOT IN |
+| [Range Operators](./range-operators.md) | BETWEEN, NOT BETWEEN |
+| [Null Operators](./null-operators.md) | IS NULL, IS NOT NULL |
+| [Array Operators](./array-operators.md) | PostgreSQL array operations |
+| [JSON Filtering](./json-filtering.md) | JSON/JSONB path queries |
+| [Fields, Order, Pagination](./fields-order-pagination.md) | SELECT, ORDER BY, LIMIT |
+| [**Default Filter**](./default-filter.md) | Automatic filter application |
+| [Application Usage](./application-usage.md) | Filter flow in applications |
+| [Tips & Best Practices](./tips.md) | Performance and patterns |
+| [Use Cases](./use-cases.md) | Real-world examples |
+
+
+## Filter Structure
+
+The `Filter<T>` object is the core mechanism for querying data in Ignis. It provides a structured, type-safe way to express complex queries without writing raw SQL.
+
+```typescript
+type TFilter<T> = {
+  where?: TWhere<T>;      // Query conditions (SQL WHERE)
+  fields?: TFields<T>;    // Column selection (SQL SELECT)
+  order?: string[];       // Sorting (SQL ORDER BY)
+  limit?: number;         // Max results (SQL LIMIT)
+  skip?: number;          // Pagination offset (SQL OFFSET)
+  offset?: number;        // Alias for skip
+  include?: TInclusion[]; // Related data (SQL JOIN / subqueries)
+};
+```
+
+
+## SQL Mapping Overview
+
+| Filter Property | SQL Equivalent | Purpose |
+|-----------------|----------------|---------|
+| `where` | `WHERE` | Filter rows by conditions |
+| `fields` | `SELECT col1, col2` | Select specific columns |
+| `order` | `ORDER BY` | Sort results |
+| `limit` | `LIMIT` | Restrict number of results |
+| `skip` / `offset` | `OFFSET` | Skip rows for pagination |
+| `include` | `JOIN` / subquery | Include related data |
+
+
+## Basic Example
+
+```typescript
+// Filter object
+const filter = {
+  where: { status: 'active', role: 'admin' },
+  fields: ['id', 'name', 'email'],
+  order: ['createdAt DESC'],
+  limit: 10,
+  skip: 0
+};
+
+// Equivalent SQL
+// SELECT "id", "name", "email"
+// FROM "User"
+// WHERE "status" = 'active' AND "role" = 'admin'
+// ORDER BY "created_at" DESC
+// LIMIT 10 OFFSET 0
+```
+
+
+## Quick Reference
+
+| Want to... | Filter Syntax |
+|------------|---------------|
+| Equals | `{ field: value }` or `{ field: { eq: value } }` |
+| Not equals | `{ field: { ne: value } }` |
+| Greater than | `{ field: { gt: value } }` |
+| Greater or equal | `{ field: { gte: value } }` |
+| Less than | `{ field: { lt: value } }` |
+| Less or equal | `{ field: { lte: value } }` |
+| Is null | `{ field: null }` or `{ field: { is: null } }` |
+| Is not null | `{ field: { isn: null } }` |
+| In list | `{ field: { in: [a, b, c] } }` |
+| Not in list | `{ field: { nin: [a, b, c] } }` |
+| Range | `{ field: { between: [min, max] } }` |
+| Outside range | `{ field: { notBetween: [min, max] } }` |
+| Contains pattern | `{ field: { like: '%pattern%' } }` |
+| Case-insensitive | `{ field: { ilike: '%pattern%' } }` |
+| Regex match | `{ field: { regexp: '^pattern$' } }` |
+| Array contains all | `{ arrayField: { contains: [a, b] } }` |
+| Array is subset | `{ arrayField: { containedBy: [a, b, c] } }` |
+| Array overlaps | `{ arrayField: { overlaps: [a, b] } }` |
+| JSON nested | `{ 'jsonField.nested.path': value }` |
+| JSON with operator | `{ 'jsonField.path': { gt: 10 } }` |
+| AND conditions | `{ a: 1, b: 2 }` or `{ and: [{a: 1}, {b: 2}] }` |
+| OR conditions | `{ or: [{ a: 1 }, { b: 2 }] }` |
+| Include relation | `{ include: [{ relation: 'name' }] }` |
+| Nested include | `{ include: [{ relation: 'a', scope: { include: [{ relation: 'b' }] } }] }` |
+| Select fields | `{ fields: ['id', 'name'] }` |
+| Order by | `{ order: ['field DESC'] }` |
+| Order by JSON | `{ order: ['jsonField.path DESC'] }` |
+| Paginate | `{ limit: 10, skip: 20 }` |