@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/references/base/repositories/soft-deletable.md

@@ -15,8 +15,10 @@ A repository that overrides delete operations to set a `deletedAt` timestamp ins
 
 ### 1. Define Model with Soft Delete
 
+Use the `generateTzColumnDefs` enricher with the `deleted` option enabled to add a `deletedAt` column:
+
 ```typescript
-import { pgTable, text, timestamp } from 'drizzle-orm/pg-core';
+import { pgTable, text } from 'drizzle-orm/pg-core';
 import {
   BaseEntity,
   model,
@@ -34,17 +36,19 @@ import {
 export class Category extends BaseEntity<typeof Category.schema> {
   static override schema = pgTable('Category', {
     ...generateIdColumnDefs({ id: { dataType: 'string' } }),
-    ...generateTzColumnDefs(),
+    ...generateTzColumnDefs({
+      deleted: { enable: true, columnName: 'deleted_at', withTimezone: true },
+    }),
     name: text('name').notNull(),
-    deletedAt: timestamp('deleted_at', { mode: 'date', withTimezone: true }),
   });
 }
 ```
 
 > [!IMPORTANT]
-> - The model **must** have a `deletedAt` column (`Date | null`).
-> - Set `defaultFilter: { where: { deletedAt: null } }` so soft-deleted records are excluded by default.
+> - The model **must** have a `deletedAt` column (`Date | null`). The `SoftDeletableRepository` requires `TSoftDeletableTableSchema` which enforces `{ deletedAt: AnyPgColumn<{ data: Date | null }> }`.
+> - Set `defaultFilter: { where: { deletedAt: null } }` in `@model` settings so soft-deleted records are excluded by default.
 > - Optionally add `deletedAt` to `hiddenProperties` to hide it from API responses.
+> - Use `generateTzColumnDefs` with `deleted: { enable: true, ... }` to add the column, or define it manually with `timestamp('deleted_at', { mode: 'date', withTimezone: true })`.
 
 ### 2. Create Repository
 
@@ -60,16 +64,22 @@ export class CategoryRepository extends SoftDeletableRepository<typeof Category.
 
 ## Delete Operations
 
-All delete methods set `deletedAt = new Date()` instead of removing the row. They internally call the corresponding `update` method.
+All delete methods set `deletedAt = new Date()` instead of removing the row. They internally call the corresponding `update` method (`updateById` or `updateAll`).
 
 ### deleteById
 
 ```typescript
-// Soft delete — sets deletedAt timestamp
+// Soft delete - sets deletedAt timestamp
 const result = await repo.deleteById({ id: '123' });
 // { count: 1, data: { id: '123', name: 'Electronics', deletedAt: '2026-03-06T...' } }
 
-// Hard delete — physically removes the row
+// Without returning data
+const result = await repo.deleteById({
+  id: '123',
+  options: { shouldReturn: false },
+});
+
+// Hard delete - physically removes the row
 const result = await repo.deleteById({
   id: '123',
   options: { shouldHardDelete: true },
@@ -95,10 +105,16 @@ const result = await repo.deleteAll({
 ### deleteBy
 
 ```typescript
-// Soft delete by where condition (requires non-empty where)
+// Soft delete by where condition (alias for deleteAll)
 const result = await repo.deleteBy({
   where: { name: 'Obsolete' },
 });
+
+// Hard delete by where condition
+const result = await repo.deleteBy({
+  where: { name: 'Obsolete' },
+  options: { shouldHardDelete: true },
+});
 ```
 
 
@@ -137,7 +153,7 @@ const result = await repo.restoreAll({
 ### restoreBy
 
 ```typescript
-// Alias for restoreAll with required where
+// Alias for restoreAll
 const result = await repo.restoreBy({
   where: { status: 'archived' },
 });
@@ -148,7 +164,7 @@ const result = await repo.restoreBy({
 
 ### findById with isStrict
 
-`SoftDeletableRepository` overrides `findById` to support a `isStrict` option that throws a `404 Not Found` error when the record doesn't exist:
+`SoftDeletableRepository` overrides `findById` to support an `isStrict` option that throws a `404 Not Found` error when the record doesn't exist:
 
 ```typescript
 // Returns null if not found (default)
@@ -159,8 +175,11 @@ const category = await repo.findById({
   id: '123',
   options: { isStrict: true },
 });
+// Throws: [CategoryRepository][findById] Entity with id 123 not found (HTTP 404)
 ```
 
+All other read operations (`find`, `findOne`, `count`, `existsWith`) work as normal. The default filter (`{ deletedAt: null }`) automatically excludes soft-deleted records. Use `shouldSkipDefaultFilter: true` to include them.
+
 
 ## Options Reference
 
@@ -170,30 +189,36 @@ const category = await repo.findById({
 |--------|------|---------|-------------|
 | `shouldHardDelete` | `boolean` | `false` | Bypass soft delete and physically remove the row |
 | `shouldReturn` | `boolean` | `true` | Return the updated/deleted record |
-| `force` | `boolean` | `false` | Allow empty `where` condition (deleteAll/deleteBy) |
-| `transaction` | `ITransaction` | — | Transaction context |
+| `force` | `boolean` | `false` | Allow empty `where` condition (`deleteAll`/`deleteBy`) |
+| `transaction` | `ITransaction` | - | Transaction context |
+| `log` | `{ use: boolean; level?: TLogLevel }` | - | Enable operation logging |
+| `shouldSkipDefaultFilter` | `boolean` | `false` | Bypass the default filter |
 
 ### Restore Options
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `shouldReturn` | `boolean` | `true` | Return the restored record |
-| `force` | `boolean` | `false` | Allow empty `where` condition (restoreAll) |
-| `transaction` | `ITransaction` | — | Transaction context |
+| `force` | `boolean` | `false` | Allow empty `where` condition (`restoreAll`) |
+| `transaction` | `ITransaction` | - | Transaction context |
+
+> [!NOTE]
+> Restore operations automatically set `shouldSkipDefaultFilter: true` internally so they can find soft-deleted records that the default filter would normally hide. You do not need to set this yourself.
 
 
 ## How It Works
 
-| Operation | Behavior |
-|-----------|----------|
-| `deleteById` | `UPDATE SET deletedAt = NOW() WHERE id = ?` |
-| `deleteAll` | `UPDATE SET deletedAt = NOW() WHERE ...` |
-| `restoreById` | `UPDATE SET deletedAt = NULL WHERE id = ?` (skips default filter) |
-| `restoreAll` | `UPDATE SET deletedAt = NULL WHERE ...` (skips default filter) |
-| `find` / `findOne` | Default filter automatically excludes `deletedAt IS NOT NULL` |
+| Operation | SQL Behavior |
+|-----------|-------------|
+| `deleteById` | `UPDATE SET deletedAt = NOW() WHERE id = ?` (via `updateById`) |
+| `deleteAll` / `deleteBy` | `UPDATE SET deletedAt = NOW() WHERE ...` (via `updateAll`) |
+| `restoreById` | `UPDATE SET deletedAt = NULL WHERE id = ?` (via `updateById` with `shouldSkipDefaultFilter: true`) |
+| `restoreAll` / `restoreBy` | `UPDATE SET deletedAt = NULL WHERE ...` (via `updateAll` with `shouldSkipDefaultFilter: true`) |
+| `find` / `findOne` / `count` | Default filter automatically adds `WHERE deletedAt IS NULL` |
+| `deleteById({ shouldHardDelete: true })` | `DELETE FROM ... WHERE id = ?` (delegates to parent `PersistableRepository`) |
 
 > [!TIP]
-> Restore operations automatically set `shouldSkipDefaultFilter: true` so they can find soft-deleted records that would normally be hidden by the default filter.
+> The `shouldHardDelete` option bypasses soft delete entirely and delegates to the parent `DefaultCRUDRepository`'s delete implementation, which performs a real SQL `DELETE`.
 
 
 ## With Transactions
@@ -211,3 +236,59 @@ try {
   await tx.rollback();
 }
 ```
+
+
+## Type Constraint
+
+`SoftDeletableRepository` enforces that the schema includes a `deletedAt` column at the type level:
+
+```typescript
+export type TSoftDeletableTableSchema = TTableSchemaWithId & {
+  deletedAt: AnyPgColumn<{ data: Date | null }>;
+};
+
+export class SoftDeletableRepository<
+  EntitySchema extends TSoftDeletableTableSchema = TSoftDeletableTableSchema,
+  // ...
+> extends DefaultCRUDRepository<EntitySchema, ...> { }
+```
+
+If your schema does not have a `deletedAt` column, you will get a TypeScript compilation error when extending `SoftDeletableRepository`.
+
+
+## Class Hierarchy
+
+```
+AbstractRepository
+  -> ReadableRepository
+    -> PersistableRepository
+      -> DefaultCRUDRepository
+        -> SoftDeletableRepository   <-- you are here
+```
+
+
+## Quick Reference
+
+| Want to... | Code |
+|------------|------|
+| Soft delete by ID | `repo.deleteById({ id })` |
+| Hard delete by ID | `repo.deleteById({ id, options: { shouldHardDelete: true } })` |
+| Soft delete by condition | `repo.deleteAll({ where, options: { force: true } })` |
+| Restore by ID | `repo.restoreById({ id })` |
+| Restore by condition | `repo.restoreAll({ where })` |
+| Find including deleted | `repo.find({ filter, options: { shouldSkipDefaultFilter: true } })` |
+| Strict findById (404) | `repo.findById({ id, options: { isStrict: true } })` |
+
+
+## Next Steps
+
+- [Advanced Features](./advanced.md) - Transactions, hidden properties
+- [Repository Mixins](./mixins.md) - Default filter and fields visibility
+- [Repository Overview](./index.md) - Repository basics
+
+## See Also
+
+- **Related Concepts:**
+  - [Repositories Overview](./index) - Core repository operations
+  - [Default Filter](../filter-system/default-filter) - Automatic filtering
+  - [Models](/guides/core-concepts/persistent/models) - Entity definitions with enrichers

package/wiki/references/base/services.md

@@ -17,34 +17,69 @@ Technical reference for `BaseService` - the foundation for business logic layers
 | **Extends `BaseHelper`** | Auto-configured scoped logger (`this.logger`) |
 | **DI Integration** | Fits into framework's dependency injection system |
 | **Business Logic Layer** | Bridge between Controllers and Repositories |
+| **No built-in CRUD** | Services are for business logic, not data access — that's what Repositories are for |
 
 ## `BaseService` Class
 
-Abstract class that all application services should extend.
+Abstract class that all application services should extend. It implements the `IService` interface (currently a marker interface with no required methods).
+
+### Class Definition
+
+```typescript
+import { BaseHelper } from '@venizia/ignis-helpers';
+import { IService } from './types';
+
+export abstract class BaseService extends BaseHelper implements IService {
+  constructor(opts: { scope: string }) {
+    super({ scope: opts.scope });
+  }
+}
+```
 
 ### Key Features
 
 | Feature | Description |
 | :--- | :--- |
 | **Standardization** | Common base for all services, fits framework architecture |
-| **Logging** | Extends `BaseHelper` - auto-configured logger at `this.logger` (scope = class name) |
+| **Logging** | Extends `BaseHelper` from `@venizia/ignis-helpers` — auto-configured logger at `this.logger` (scope = class name) |
 | **Clarity** | Signals the class contains business logic |
 
-### Class Definition
+### Constructor
 
-The implementation is straightforward:
+The constructor requires an options object with a `scope` string, which is typically set to the class name:
 
 ```typescript
-import { BaseHelper } from '../helpers';
-import { IService } from './types';
-
-export abstract class BaseService extends BaseHelper implements IService {
-  constructor(opts: { scope: string }) {
-    super({ scope: opts.scope });
+class UserService extends BaseService {
+  constructor() {
+    super({ scope: UserService.name });
   }
 }
 ```
 
+## `IService` Interface
+
+The `IService` interface is a marker interface with no required methods. It exists to provide a type-level contract for services.
+
+```typescript
+export interface IService {}
+```
+
+## No Built-in CRUD Service
+
+Ignis intentionally does not provide a `BaseCrudService`. CRUD operations belong in the Repository layer (`DefaultCRUDRepository`). Services are for business logic that orchestrates one or more repositories, performs validation, handles transactions, or coordinates cross-cutting concerns.
+
+## Registration
+
+Services are registered with the DI container using the `app.service()` method or via the boot system's auto-discovery:
+
+```typescript
+// Manual registration (in preConfigure or registerComponents)
+app.service(UserService); // Binds as 'services.UserService'
+
+// Or via boot system auto-discovery:
+// Place file at src/services/user.service.ts → auto-discovered and bound
+```
+
 ## How Services Fit into the Architecture
 
 Services are the core of your application's logic. They act as a bridge between the presentation layer (Controllers) and the data access layer (Repositories).
@@ -64,12 +99,12 @@ Services are the core of your application's logic. They act as a bridge between
 ### Example
 
 ```typescript
-import { BaseService, inject } from '@venizia/ignis';
+import { BaseService, inject, injectable } from '@venizia/ignis';
 import { getError } from '@venizia/ignis-helpers';
 import { UserRepository } from '../repositories/user.repository';
 import { TUser } from '../models/entities';
 
-// 1. Service is decorated with `@injectable` (or registered via `app.service()`)
+// 1. Service is decorated with @injectable (or registered via app.service())
 @injectable()
 export class UserService extends BaseService {
   // 2. Dependencies (like UserRepository) are injected
@@ -94,15 +129,60 @@ export class UserService extends BaseService {
     // 5. Returns transformed data
     return {
       id: user.id,
-      name: user.name, // Assuming a 'name' field exists
+      name: user.name,
       email: user.email,
     };
   }
 }
 ```
 
-By adhering to this pattern, you keep your code organized, testable, and maintainable. You can easily test `UserService` by providing a mock `UserRepository` without needing a real database connection.
+### Transaction Orchestration
+
+A common service pattern is orchestrating transactions across multiple repositories:
+
+```typescript
+@injectable()
+export class OrderService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.OrderRepository' })
+    private orderRepo: OrderRepository,
+
+    @inject({ key: 'repositories.InventoryRepository' })
+    private inventoryRepo: InventoryRepository,
+
+    @inject({ key: 'datasources.PostgresDataSource' })
+    private dataSource: PostgresDataSource,
+  ) {
+    super({ scope: OrderService.name });
+  }
 
+  async placeOrder(opts: { userId: string; items: OrderItem[] }) {
+    const transaction = await this.dataSource.beginTransaction();
+    try {
+      const order = await this.orderRepo.create({
+        data: { userId: opts.userId, items: opts.items },
+        options: { transaction },
+      });
+
+      for (const item of opts.items) {
+        await this.inventoryRepo.updateById({
+          id: item.productId,
+          data: { quantity: item.quantity },
+          options: { transaction },
+        });
+      }
+
+      await transaction.commit();
+      return order;
+    } catch (error) {
+      await transaction.rollback();
+      throw error;
+    }
+  }
+}
+```
+
+By adhering to this pattern, you keep your code organized, testable, and maintainable. You can easily test `UserService` by providing a mock `UserRepository` without needing a real database connection.
 
 ## See Also
 

package/wiki/references/index.md

@@ -9,12 +9,12 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <p>Application, Controller, Service, Repository, Model</p>
 </a>
 
-<a href="./components/" class="guide-card">
+<a href="/ignis/extensions/components/" class="guide-card">
 <h3>Components</h3>
 <p>Auth, Mail, Socket.IO, Swagger, Health Check</p>
 </a>
 
-<a href="./helpers/" class="guide-card">
+<a href="/ignis/extensions/helpers/" class="guide-card">
 <h3>Helpers</h3>
 <p>Logger, Redis, Queue, Storage, Cron, Crypto</p>
 </a>
@@ -29,7 +29,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <p>Environment variables and settings</p>
 </a>
 
-<a href="./src-details/" class="guide-card">
+<a href="/ignis/extensions/src-details/" class="guide-card">
 <h3>Framework Internals</h3>
 <p>Package structure and architecture</p>
 </a>
@@ -63,7 +63,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">3</span>
 <h4>Adding Features</h4>
 </div>
-<p><a href="./components/authentication">Auth</a> → <a href="./components/socket-io">Real-time</a> → <a href="./components/mail">Email</a> → <a href="./components/swagger">API Docs</a></p>
+<p><a href="/ignis/extensions/components/authentication/">Auth</a> → <a href="/ignis/extensions/components/socket-io/">Real-time</a> → <a href="/ignis/extensions/components/mail/">Email</a> → <a href="/ignis/extensions/components/swagger">API Docs</a></p>
 <span class="stage-desc">Pre-built components for common features</span>
 </div>
 
@@ -72,7 +72,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">4</span>
 <h4>Infrastructure</h4>
 </div>
-<p><a href="./helpers/logger">Logging</a> → <a href="./helpers/redis">Caching</a> → <a href="./helpers/queue">Queues</a> → <a href="./helpers/cron">Scheduling</a></p>
+<p><a href="/ignis/extensions/helpers/logger/">Logging</a> → <a href="/ignis/extensions/helpers/redis/">Caching</a> → <a href="/ignis/extensions/helpers/queue/">Queues</a> → <a href="/ignis/extensions/helpers/cron/">Scheduling</a></p>
 <span class="stage-desc">Background jobs, caching, and observability</span>
 </div>
 
@@ -90,7 +90,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">6</span>
 <h4>Production Ready</h4>
 </div>
-<p><a href="./base/middlewares">Error Handling</a> → <a href="./components/health-check">Health Checks</a> → <a href="./configuration/environment-variables">Configuration</a> → <a href="./base/bootstrapping">Auto-Discovery</a></p>
+<p><a href="./base/middlewares">Error Handling</a> → <a href="/ignis/extensions/components/health-check">Health Checks</a> → <a href="./configuration/environment-variables">Configuration</a> → <a href="./base/bootstrapping">Auto-Discovery</a></p>
 <span class="stage-desc">Production deployment, monitoring, and reliability</span>
 </div>
 
@@ -99,7 +99,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 <span class="stage-num">7</span>
 <h4>Testing & Quality</h4>
 </div>
-<p><a href="./helpers/testing">Unit Testing</a> → <a href="./base/repositories/advanced">Mocking & Stubs</a> → <a href="./quick-reference">Best Practices</a></p>
+<p><a href="/ignis/extensions/helpers/testing/">Unit Testing</a> → <a href="./base/repositories/advanced">Mocking & Stubs</a> → <a href="./quick-reference">Best Practices</a></p>
 <span class="stage-desc">Testing strategies, quality assurance, and code review</span>
 </div>
 
@@ -113,7 +113,7 @@ Complete reference documentation for the Ignis framework. Find detailed API docs
 **Define a Controller:**
 ```typescript
 @controller({ path: '/users' })
-class UserController extends BaseController {
+class UserController extends BaseRestController {
   @get({ configs: { path: '/:id' } })
   getUser(c: Context) {
     return c.json({ id: c.req.param('id') });
@@ -143,11 +143,13 @@ CronHelper.schedule('0 * * * *', async () => {
 // Core framework
 import {
   BaseApplication,
-  BaseController,
+  BaseRestController,
+  BaseGrpcController,
   BaseService,
-  BaseRepository,
+  DefaultCRUDRepository,
   controller,
   get, post, put, del,
+  rpc, unary, serverStream,
   inject,
 } from '@venizia/ignis';