@venizia/ignis-docs 0.2.0 → 0.2.1-0

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

@@ -9,13 +9,13 @@ difficulty: advanced
 Technical reference for the DI system in IGNIS - managing resource lifecycles and dependency resolution.
 
 **Files:**
-- `packages/inversion/src/container.ts` - Base `Container` and `Binding` classes
-- `packages/inversion/src/registry.ts` - Base `MetadataRegistry`
-- `packages/inversion/src/metadata/injectors.ts` - Base `@inject` and `@injectable` decorators
+- `packages/inversion/src/modules/container/index.ts` - Base `Container` and `Binding` classes
+- `packages/inversion/src/modules/registry/index.ts` - Base `MetadataRegistry`
+- `packages/inversion/src/modules/metadata/injectors.ts` - Base `@inject` decorator
 - `packages/inversion/src/common/types.ts` - `BindingScopes`, `BindingValueTypes`, `BindingKeys`, `IProvider`
 - `packages/core/src/helpers/inversion/container.ts` - Extended `Container` with `ApplicationLogger`
 - `packages/core/src/helpers/inversion/registry.ts` - Extended `MetadataRegistry` (singleton, with model/repository/datasource mixins)
-- `packages/core/src/base/metadata/injectors.ts` - Core `@inject` and `@injectable` (wired to extended registry)
+- `packages/core/src/base/metadata/injectors.ts` - Core `@inject` (wired to extended registry)
 
 ## Quick Reference
 
@@ -24,7 +24,6 @@ Technical reference for the DI system in IGNIS - managing resource lifecycles an
 | **Container** | DI registry managing resource lifecycles | `bind()`, `get()`, `gets()`, `instantiate()`, `resolve()`, `findByTag()`, `isBound()`, `unbind()`, `clear()`, `reset()` |
 | **Binding** | Single registered dependency configuration | `toClass()`, `toValue()`, `toProvider()`, `setScope()`, `setTags()`, `getValue()`, `clearCache()` |
 | **@inject** | Decorator marking injection points | Applied to constructor parameters and class properties |
-| **@injectable** | Decorator marking a class as injectable | Stores scope and tag metadata |
 | **MetadataRegistry** | Stores decorator metadata | Singleton - base via `metadataRegistry` export, core via `MetadataRegistry.getInstance()` |
 | **BindingKeys** | Utility for building namespaced keys | `BindingKeys.build({ namespace, key })` |
 | **Boot System** | Automatic artifact discovery and binding | Integrates with Container via tags and bindings |
@@ -42,7 +41,7 @@ Before reading this document, you should understand:
 
 Heart of the DI system - registry managing all application resources.
 
-**File:** `packages/inversion/src/container.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
+**File:** `packages/inversion/src/modules/container/index.ts` (Base) & `packages/core/src/helpers/inversion/container.ts` (Extended)
 
 The base `Container` extends `BaseHelper` (which provides `scope` and `identifier` properties). The core `Container` extends the base and adds a `Logger` instance.
 
@@ -106,7 +105,7 @@ class UserController {
 
 A `Binding` represents a single registered dependency in the container. It provides a fluent API to configure *how* a dependency should be created and managed.
 
-**File:** `packages/inversion/src/container.ts`
+**File:** `packages/inversion/src/modules/container/index.ts`
 
 The `Binding` class extends `BaseHelper`.
 
@@ -206,7 +205,7 @@ This is also used internally by `container.get()` and `container.getBinding()` w
 
 The `@inject` decorator marks where dependencies should be injected - either on constructor parameters or class properties.
 
-**File:** `packages/inversion/src/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
+**File:** `packages/inversion/src/modules/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
 
 ### Signature
 
@@ -257,30 +256,14 @@ The `@venizia/ignis-inversion` package exports base decorators that use the modu
 
 **Always import from `@venizia/ignis` in application code:**
 ```typescript
-import { inject, injectable } from '@venizia/ignis';
+import { inject } from '@venizia/ignis';
 ```
 
-## `@injectable` Decorator
+## Registering a Class
 
-Marks a class as injectable and attaches optional metadata.
-
-**File:** `packages/inversion/src/metadata/injectors.ts` (base) & `packages/core/src/base/metadata/injectors.ts` (core wrapper)
-
-### Signature
-
-```typescript
-@injectable({ scope?: TBindingScope; tags?: Record<string, any> })
-```
-
-| Parameter | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `scope` | `'singleton' \| 'transient'` | - | Optional scope hint for the binding. |
-| `tags` | `Record<string, any>` | - | Optional metadata tags. |
-
-### Example
+No class decorator is needed to make a class injectable. A class becomes resolvable once a binding exists for it - created either by boot auto-discovery, by a framework helper (`app.controller()`, `app.service()`, `@repository`), or explicitly with `container.bind()`. Scope is configured on the binding, never on the class:
 
 ```typescript
-@injectable({ scope: BindingScopes.SINGLETON })
 class UserService extends BaseService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
@@ -289,15 +272,19 @@ class UserService extends BaseService {
     super({ scope: UserService.name });
   }
 }
+
+app.bind({ key: 'services.UserService' })
+  .toClass(UserService)
+  .setScope(BindingScopes.SINGLETON); // default is TRANSIENT
 ```
 
 ## `MetadataRegistry`
 
-The `MetadataRegistry` stores and retrieves all metadata attached by decorators (`@inject`, `@injectable`, `@controller`, `@model`, etc.).
+The `MetadataRegistry` stores and retrieves all metadata attached by decorators (`@inject`, `@controller`, `@model`, etc.).
 
 ### Base MetadataRegistry
 
-**File:** `packages/inversion/src/registry.ts`
+**File:** `packages/inversion/src/modules/registry/index.ts`
 
 A singleton exported as `metadataRegistry`. Extends `BaseHelper`.
 
@@ -315,8 +302,6 @@ A singleton exported as `metadataRegistry`. Extends `BaseHelper`.
 | `setPropertyMetadata({ target, propertyName, metadata })` | Stores property injection metadata (`IPropertyMetadata`). |
 | `getPropertiesMetadata({ target })` | Returns a `Map<string \| symbol, IPropertyMetadata>` for all injected properties. |
 | `getPropertyMetadata({ target, propertyName })` | Returns property metadata for a specific property. |
-| `setInjectableMetadata({ target, metadata })` | Stores `@injectable` metadata on a class. |
-| `getInjectableMetadata({ target })` | Returns `@injectable` metadata for a class. |
 
 ### Core MetadataRegistry
 
@@ -333,12 +318,11 @@ Additional capabilities include:
 
 ### Metadata Keys
 
-Defined in `packages/inversion/src/common/keys.ts`:
+Defined in `packages/inversion/src/modules/metadata/common/constants.ts`:
 
 ```typescript
 MetadataKeys.PROPERTIES  = Symbol.for('ignis:properties')
 MetadataKeys.INJECT      = Symbol.for('ignis:inject')
-MetadataKeys.INJECTABLE  = Symbol.for('ignis:injectable')
 ```
 
 ### Key Types
@@ -355,11 +339,6 @@ interface IPropertyMetadata {
   isOptional?: boolean;
   [key: string]: any;
 }
-
-interface IInjectableMetadata {
-  scope?: TBindingScope;
-  tags?: Record<string, any>;
-}
 ```
 
 ## Boot System Integration
@@ -436,7 +415,6 @@ The boot system integrates into the application lifecycle:
 app.bind({ key: 'controllers.UserController' }).toClass(UserController);
 
 // 4. Later, when UserController is instantiated:
-@injectable()
 class UserController {
   constructor(
     @inject({ key: 'services.UserService' })

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

@@ -6,48 +6,27 @@ difficulty: intermediate
 
 # Using Filters in Your Application
 
-How filters flow through the application layers.
-
-
-## Architecture Overview
+A `filter` typically starts as a JSON-encoded query string on an HTTP request and ends as a Drizzle query - here is what happens at each layer in between.
 
 ```
-+-----------------------------------------------------------------+
-|                        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                             |
-|   - applyDefaultFilter() merges the @model default filter         |
-|   - FilterBuilder transforms Filter -> Drizzle query options     |
-|   - Executes query via Drizzle ORM                               |
-|   - Returns typed results                                        |
-+-----------------------------------------------------------------+
+HTTP Request         GET /products?filter={"where":{"status":"active"},"limit":10}
+      |
+      v
+Controller Layer      Validates via Zod (FilterSchema), parses JSON string -> Filter object
+      |
+      v
+Service Layer          Optional - business logic, authorization, may edit the filter
+      |
+      v
+Repository Layer       applyDefaultFilter() merges the @model default filter,
+                        FilterBuilder converts Filter -> Drizzle query options, executes
 ```
 
+## Controller layer
 
-## Controller Layer
+### `ControllerFactory` (recommended)
 
-### Using ControllerFactory (Recommended)
-
-The `ControllerFactory` automatically handles filter parsing and validation:
+`ControllerFactory.defineCrudController` generates a full CRUD controller, including filter parsing and validation, from an entity and a repository binding:
 
 ```typescript
 // src/controllers/product.controller.ts
@@ -77,10 +56,7 @@ const _Controller = ControllerFactory.defineCrudController({
 export class ProductController extends _Controller {
   constructor(
     @inject({
-      key: BindingKeys.build({
-        namespace: BindingNamespaces.REPOSITORY,
-        key: ProductRepository.name,
-      }),
+      key: BindingKeys.build({ namespace: BindingNamespaces.REPOSITORY, key: ProductRepository.name }),
     })
     repository: ProductRepository,
   ) {
@@ -89,16 +65,22 @@ export class ProductController extends _Controller {
 }
 ```
 
-**Generated Endpoints:**
+**Filter-bearing endpoints generated:**
+
+| Method | Endpoint | Query param |
+|---|---|---|
+| GET | `/products` | `filter` |
+| GET | `/products/{id}` | `filter` (`where` is ignored - the id is the condition) |
+| GET | `/products/find-one` | `filter` |
+| GET | `/products/count` | `where` |
 
-| Method | Endpoint | Filter Location |
-|--------|----------|-----------------|
-| GET | `/products` | Query param: `?filter={...}` |
-| GET | `/products/{id}` | Query param: `?filter={...}` (for includes) |
-| GET | `/products/find-one` | Query param: `?filter={...}` |
-| GET | `/products/count` | Query param: `?where={...}` |
+- **`isStrict.requestSchema`** controls whether these query params are Zod-required or optional.
+- **`isStrict.path`** controls trailing-slash strictness.
+- **Write endpoints** (`POST /`, `PATCH /{id}`, `DELETE /{id}`, ...) are also generated by the factory, and take no filter.
 
-### Custom Controller with Manual Filter Handling
+### Custom controller with manual filter handling
+
+For a route outside the generated CRUD set, accept `FilterSchema` directly:
 
 ```typescript
 import { z } from '@hono/zod-openapi';
@@ -118,12 +100,10 @@ export class ProductController extends BaseRestController {
       configs: {
         path: '/search',
         method: 'get',
-        request: {
-          query: z.object({ filter: FilterSchema }),
-        },
+        request: { query: z.object({ filter: FilterSchema }) },
         responses: jsonResponse({ schema: z.array(z.object({ id: z.string() })) }),
       },
-      handler: async (context) => {
+      handler: async context => {
         const { filter = {} } = context.req.valid('query');
         const results = await this._productRepository.find({ filter });
         return context.json(results);
@@ -133,25 +113,23 @@ export class ProductController extends BaseRestController {
 }
 ```
 
+## Filter schema validation
 
-## Filter Schema Validation
-
-The `FilterSchema` (Zod) accepts both object and JSON string formats:
+`FilterSchema` and `WhereSchema` are both `z.union([<object shape>, <JSON string>.transform(JSON.parse)])` - they accept either format, so a Hono query param (always a string) and a filter built in code both validate:
 
 ```typescript
-// Object format (from parsed query params)
+// Object format (built in code)
 { where: { status: 'active' }, limit: 10 }
 
-// JSON string format (from URL query string)
+// JSON string format (from a URL query string)
 '{"where":{"status":"active"},"limit":10}'
 ```
 
-The `WhereSchema` also accepts both formats independently, useful for the `count` endpoint which takes `where` directly.
+`WhereSchema` is independent of `FilterSchema` - it backs the `count` endpoint, which takes `where` directly rather than a full filter.
 
+## Service layer
 
-## Service Layer
-
-Services can modify filters before passing to repositories:
+A service can rewrite the filter before it reaches the repository - useful when a constraint is a caller/session concern rather than a per-model constant (see [Default Filter](./default-filter) for the model-level alternative):
 
 ```typescript
 @service()
@@ -161,83 +139,53 @@ export class ProductService {
     private _productRepository: 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._productRepository.find({ filter: enhancedFilter });
-  }
-
-  async findProductsForTenant(
-    tenantId: string,
-    filter: TFilter<TProductSchema> = {},
-  ) {
-    const isolatedFilter: TFilter<TProductSchema> = {
-      ...filter,
-      where: {
-        ...filter.where,
-        tenantId,
-      },
-    };
-
-    return this._productRepository.find({ filter: isolatedFilter });
+  async findProductsForTenant(tenantId: string, filter: TFilter<TProductSchema> = {}) {
+    return this._productRepository.find({
+      filter: { ...filter, where: { ...filter.where, tenantId } },
+    });
   }
 }
 ```
 
-
-## HTTP Request Examples
+## 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:**
+**Fetch/Axios:**
 ```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) },
-});
+const filter = { where: { status: 'active', price: { lte: 100 } }, order: ['createdAt DESC'], limit: 10 };
+
+// fetch
+const response = await fetch(`/api/products?filter=${encodeURIComponent(JSON.stringify(filter))}`);
+
+// axios
+const response = await axios.get('/api/products', { params: { filter: JSON.stringify(filter) } });
 ```
 
+## Debugging a filter
 
-## Debugging Filters
+`buildQuery` compiles a filter into Drizzle query options without executing it - the fastest way to check what a filter actually resolves to:
 
 ```typescript
-// Enable logging to see generated SQL
-const result = await repository.find({
-  filter: complexFilter,
-  options: {
-    log: { use: true, level: 'debug' },
-  },
-});
-
-// Or use buildQuery to inspect without executing
 const queryOptions = repository.buildQuery({ filter: complexFilter });
 console.log('Generated query options:', queryOptions);
 ```
+
+`options.log` also traces repository calls, but only on the write path (`create`/`updateById`/`updateAll`/`deleteById`/`deleteAll`) - `find`/`findOne`/`findById`/`count` never read it. See [Advanced Repository Features -> Log option](../repositories/advanced.md#log-option) for the write-side form.
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and every `where` operator family
+- [Default Filter](./default-filter) - `shouldSkipDefaultFilter`, and the model-level alternative to the service-layer pattern above
+- [Use Case Gallery](./use-cases) - more filter shapes with their generated SQL
+- [Advanced Repository Features](../repositories/advanced.md) - transactions, locking, and the full `log`/`lock` options
+
+**Files:**
+
+- [`packages/core/src/base/controllers/factory/controller.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/controllers/factory/controller.ts) - `ControllerFactory.defineCrudController`
+- [`packages/core/src/base/repositories/query-schemas/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/query-schemas/filter.ts) - `FilterSchema`, `TFilter`, `TInclusion`
+- [`packages/core/src/connectors/postgres/repositories/core/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/core/base.ts) - `RelationalBaseRepository.buildQuery`

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

@@ -143,3 +143,15 @@ export const productTable = pgTable('Product', {
   scores: integer('scores').array(),                   // integer[]
 });
 ```
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [List Operators](./list-operators) - `in`/`nin` match scalar values against an array, the operators these are not to be confused with
+- [Quick Reference](./quick-reference) - every operator, one line each
+
+**Files:**
+
+- [`packages/core/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, `buildPgArrayComparison`
+- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
+- [`packages/core/src/base/repositories/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/operators.ts) - `QueryOperators` constants

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

@@ -116,3 +116,15 @@ Matches records where field does NOT equal the value. Both `ne` and `neq` are al
 | `gte` | `>=` | Greater than or equal |
 | `lt` | `<` | Less than |
 | `lte` | `<=` | Less than or equal |
+
+## See also
+
+- [Filter System Overview](./) - the `filter` shape and the full `where` operator table
+- [Range Operators](./range-operators) - `between`/`notBetween`, and the `gte`/`lte` equivalent shown above
+- [Quick Reference](./quick-reference) - every operator, one line each
+
+**Files:**
+
+- [`packages/core/src/connectors/postgres/repositories/dialect/query.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/query.ts) - `PostgresQueryOperators.FNS`, per-operator SQL builders
+- [`packages/core/src/connectors/postgres/repositories/dialect/filter.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/connectors/postgres/repositories/dialect/filter.ts) - `FilterBuilder`, translates `TFilter` to Drizzle/SQL
+- [`packages/core/src/base/repositories/common/operators.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/base/repositories/common/operators.ts) - `QueryOperators` constants