@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/references/base/controllers.md

@@ -1,3 +1,9 @@
+---
+title: Controllers Reference
+description: Technical reference for controller classes and API endpoints
+difficulty: beginner
+---
+
 # Deep Dive: Controllers
 
 Technical reference for controller classes - the foundation for creating API endpoints in Ignis.
@@ -86,8 +92,8 @@ For convenience, `Ignis` provides decorator shortcuts for each HTTP method: Thes
 import { get, post, z, jsonContent, jsonResponse, Authentication, TRouteContext, HTTP } from '@venizia/ignis';
 
 // Define route configs as const for full type inference
-const USER_ROUTES = {
-  listUsers: {
+const UserRoutes = {
+  LIST_USERS: {
     path: '/',
     method: 'get',
     responses: jsonResponse({
@@ -95,7 +101,7 @@ const USER_ROUTES = {
       schema: z.array(z.object({ id: z.string(), name: z.string() })),
     }),
   },
-  getUser: {
+  GET_USER: {
     path: '/:id',
     method: 'get',
     request: {
@@ -106,7 +112,7 @@ const USER_ROUTES = {
       schema: z.object({ id: z.string(), name: z.string() }),
     }),
   },
-  createUser: {
+  CREATE_USER: {
     path: '/',
     method: 'post',
     authStrategies: [Authentication.STRATEGY_JWT], // Secure this endpoint
@@ -123,26 +129,26 @@ const USER_ROUTES = {
 
 // ... inside a controller class
 
-  @get({ configs: USER_ROUTES.listUsers })
-  getAllUsers(c: TRouteContext<typeof USER_ROUTES.listUsers>) { // Return type is automatically inferred
+  @get({ configs: UserRoutes.LIST_USERS })
+  getAllUsers(c: TRouteContext<typeof UserRoutes.LIST_USERS>) { // Return type is automatically inferred
     return c.json([{ id: '1', name: 'John Doe' }], HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @get({ configs: USER_ROUTES.getUser })
-  getUserById(c: TRouteContext<typeof USER_ROUTES.getUser>) { // Return type is automatically inferred
+  @get({ configs: UserRoutes.GET_USER })
+  getUserById(c: TRouteContext<typeof UserRoutes.GET_USER>) { // Return type is automatically inferred
     const { id } = c.req.valid('param'); // id is typed as string
     return c.json({ id, name: 'John Doe' }, HTTP.ResultCodes.RS_2.Ok);
   }
 
-  @post({ configs: USER_ROUTES.createUser })
-  createUser(c: TRouteContext<typeof USER_ROUTES.createUser>) { // Return type is automatically inferred
+  @post({ configs: UserRoutes.CREATE_USER })
+  createUser(c: TRouteContext<typeof UserRoutes.CREATE_USER>) { // Return type is automatically inferred
     const { name } = c.req.valid('json'); // name is typed as string
     const newUser = { id: '2', name };
     return c.json(newUser, HTTP.ResultCodes.RS_2.Created); // Return type is validated
   }
 ```
 
-**Example using shared `ROUTE_CONFIGS`:**
+**Example using shared `RouteConfigs`:**
 
 For better organization, you can define all your route configurations in a constant and reference them in your decorators. This approach also allows you to get a typed context for your handler.
 
@@ -150,8 +156,8 @@ For better organization, you can define all your route configurations in a const
 import { api, BaseController, controller, TRouteContext, jsonContent, jsonResponse, HTTP } from '@venizia/ignis';
 import { z } from 'hono/zod-openapi';
 
-const HEALTH_CHECK_ROUTES = {
-  '/ping': {
+const RouteConfigs = {
+  PING: {
     method: HTTP.Methods.POST,
     path: '/ping',
     request: {
@@ -167,9 +173,9 @@ const HEALTH_CHECK_ROUTES = {
 
 @controller({ path: '/health' })
 export class HealthCheckController extends BaseController {
-  
-  @api({ configs: HEALTH_CHECK_ROUTES['/ping'] })
-  ping(c: TRouteContext<typeof HEALTH_CHECK_ROUTES['/ping']>) { // Return type is automatically inferred
+
+  @api({ configs: RouteConfigs.PING })
+  ping(c: TRouteContext<typeof RouteConfigs.PING>) { // Return type is automatically inferred
     const { message } = c.req.valid('json');
     return c.json({ pong: message }, HTTP.ResultCodes.RS_2.Ok);
   }
@@ -258,17 +264,17 @@ request: {
 The `defineRouteConfigs` function is a simple helper for creating a typed object containing multiple route configurations. This is particularly useful for organizing all of a controller's route definitions in a single, type-checked constant.
 
 ```typescript
-import { defineRouteConfigs, HTTP, jsonResponse, z } from '@venizia/ignis';
+import { defineRouteConfigs, HTTP, jsonResponse, jsonContent, z } from '@venizia/ignis';
 
-const ROUTE_CONFIGS = defineRouteConfigs({
-  '/': {
+const RouteConfigs = defineRouteConfigs({
+  ROOT: {
     method: HTTP.Methods.GET,
     path: '/',
     responses: jsonResponse({
       schema: z.object({ status: z.string() }),
     }),
   },
-  '/ping': {
+  PING: {
     method: HTTP.Methods.POST,
     path: '/ping',
     request: {
@@ -452,3 +458,27 @@ export class ConfigurationController extends _ConfigurationController {
 ```
 
 By leveraging these structured configuration options and the `ControllerFactory`, you ensure that your API is not only functional but also well-documented, easy to validate, and rapidly deployable for standard CRUD operations.
+
+---
+
+## See Also
+
+- **Related References:**
+  - [Services](./services.md) - Business logic layer called by controllers
+  - [Repositories](./repositories/) - Data access layer for CRUD operations
+  - [Middlewares](./middlewares.md) - Request/response middleware
+  - [Application](./application.md) - Application setup and controller mounting
+  - [Dependency Injection](./dependency-injection.md) - DI patterns and injection
+
+- **Guides:**
+  - [Controllers Guide](/guides/core-concepts/controllers)
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
+
+- **Best Practices:**
+  - [API Usage Examples](/best-practices/api-usage-examples)
+  - [Troubleshooting Tips](/best-practices/troubleshooting-tips)
+  - [Security Guidelines](/best-practices/security-guidelines)
+
+- **External Resources:**
+  - [OpenAPI Specification](https://swagger.io/specification/)
+  - [HTTP Methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods)

package/wiki/references/base/datasources.md

@@ -1,3 +1,9 @@
+---
+title: DataSources Reference
+description: Technical reference for DataSource classes and database connections
+difficulty: intermediate
+---
+
 # Deep Dive: DataSources
 
 Technical reference for DataSource classes - managing database connections in Ignis.
@@ -338,3 +344,27 @@ try {
 > **Note:** For most use cases, prefer using `repository.beginTransaction()` which provides a higher-level API. See [Repositories Reference](./repositories.md#transactions) for details.
 
 This architecture ensures that datasources are configured consistently and that the fully-initialized Drizzle connector, aware of all schemas and relations, is available to repositories for querying.
+
+## See Also
+
+- **Related Concepts:**
+  - [DataSources Guide](/guides/core-concepts/persistent/datasources) - Creating DataSources tutorial
+  - [Repositories](/guides/core-concepts/persistent/repositories) - Using DataSources for database access
+  - [Models](/guides/core-concepts/persistent/models) - Entity schemas loaded by DataSource
+  - [Transactions](/guides/core-concepts/persistent/transactions) - Multi-operation database transactions
+
+- **References:**
+  - [Repositories API](/references/base/repositories/) - Data access layer
+  - [Environment Variables](/references/configuration/environment-variables) - Configuration management
+
+- **External Resources:**
+  - [Drizzle ORM Documentation](https://orm.drizzle.team/) - ORM configuration
+  - [node-postgres Documentation](https://node-postgres.com/) - Connection pooling guide
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Connection pool tuning
+  - [Security Guidelines](/best-practices/security-guidelines) - Database credential management
+
+- **Tutorials:**
+  - [Complete Installation](/guides/tutorials/complete-installation) - Database setup
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DataSource configuration

package/wiki/references/base/dependency-injection.md

@@ -1,3 +1,9 @@
+---
+title: Dependency Injection Reference
+description: Technical reference for the DI system in IGNIS
+difficulty: advanced
+---
+
 # Deep Dive: Dependency Injection
 
 Technical reference for the DI system in Ignis - managing resource lifecycles and dependency resolution.
@@ -18,6 +24,15 @@ Technical reference for the DI system in Ignis - managing resource lifecycles an
 | **MetadataRegistry** | Stores decorator metadata | Singleton accessed via `getInstance()` |
 | **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
 
+## Prerequisites
+
+Before reading this document, you should understand:
+
+- [TypeScript Decorators](https://www.typescriptlang.org/docs/handbook/decorators.html) - How decorators work in TypeScript
+- [IGNIS Application basics](./application.md) - Application lifecycle and initialization
+- [Services](./services.md) and [Controllers](./controllers.md) - Basic understanding of IGNIS architecture
+- Inversion of Control (IoC) pattern - [Martin Fowler's article](https://martinfowler.com/articles/injection.html)
+
 ## `Container` Class
 
 Heart of the DI system - registry managing all application resources.
@@ -161,8 +176,8 @@ app.bind({ key: 'controllers.UserController' }).toClass(UserController);
 @injectable()
 class UserController {
   constructor(
-    @inject({ key: 'services.UserService' }) 
-    private userService: UserService  // Auto-injected!
+    @inject({ key: 'services.UserService' })
+    private _userService: UserService  // Auto-injected!
   ) {}
 }
 ```
@@ -174,4 +189,25 @@ class UserController {
 - **Extensible**: Custom booters integrate seamlessly via tags
 - **Type-safe**: Full TypeScript support throughout boot process
 
-> **Learn More:** See [Bootstrapping Concepts](/get-started/core-concepts/bootstrapping.md) and [Boot Package Reference](/references/src-details/boot.md)
+> **Learn More:** See [Bootstrapping Concepts](/guides/core-concepts/application/bootstrapping) and [Boot Package Reference](/references/src-details/boot.md)
+
+## See Also
+
+- **Related Concepts:**
+  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection) - DI fundamentals tutorial
+  - [Application](/guides/core-concepts/application/) - Application extends Container
+  - [Controllers](/guides/core-concepts/controllers) - Use DI for injecting services
+  - [Services](/guides/core-concepts/services) - Use DI for injecting repositories
+  - [Providers](/references/base/providers) - Factory pattern for dynamic injection
+
+- **References:**
+  - [Inversion Helper](/references/helpers/inversion) - DI container utilities
+  - [Bootstrapping API](/references/base/bootstrapping) - Auto-discovery and DI
+  - [Glossary](/guides/reference/glossary#dependency-injection-di) - DI concepts explained
+
+- **Tutorials:**
+  - [Testing](/guides/tutorials/testing) - Unit testing with mocked dependencies
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - DI in practice
+
+- **Best Practices:**
+  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns and anti-patterns

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[]
+});
+```