@venizia/ignis-docs 0.0.8 → 0.2.0

package/content/guides/core-concepts/services.md

@@ -2,101 +2,371 @@
 
 Services contain your application's business logic, orchestrating data flow and executing use cases.
 
-> **Deep Dive:** See [Services Reference](../../references/base/services.md) for advanced patterns.
+> **Deep Dive:** See [Services Reference](../../references/base/services.md) for the full API reference.
 
 ## The Business Logic Layer
 
-Services contain the core business logic of your application. They orchestrate the flow of data and execute the application's use cases. A service's primary responsibilities are:
+Services sit between controllers and repositories. A controller receives an HTTP request and immediately delegates to a service; the service applies business rules, calls one or more repositories, and returns the result.
 
--   **Encapsulating Business Rules**: Centralizing logic such as calculations, data validation, and process workflows.
--   **Coordinating Operations**: Using repositories to fetch and persist data, or orchestrating other services to execute complex business workflows.
--   **Reusing Business Logic**: Services can inject other services to reuse established logic, ensuring "Don't Repeat Yourself" (DRY) principles are maintained across the application.
--   **Isolating Controllers**: Keeping controllers thin by handling all the complex logic, so controllers are only responsible for handling the HTTP request and response.
+Primary responsibilities:
 
-### Creating a Service
+- **Encapsulate business rules** - validation, state-machine transitions, authorization guards, calculations
+- **Coordinate repositories** - fetch related data, combine writes, enforce consistency
+- **Manage transactions** - begin, commit, or roll back across multiple repository calls
+- **Compose services** - inject and call other services to avoid duplicating logic
 
-To create a service, extend the `BaseService` class and inject the repositories or other services it depends on.
+Controllers stay thin. Repositories stay dumb. Everything in between is a service.
+
+---
+
+## Creating a Service
+
+Extend `BaseService` and call `super({ scope: ClassName.name })` in the constructor:
 
 ```typescript
 import { BaseService, inject } from '@venizia/ignis';
-import { ConfigurationRepository } from '../repositories';
+import { getError, HTTP } from '@venizia/ignis-helpers';
 import { UserRepository } from '../repositories';
-import { LoggingService } from './logging.service'; // Example of another service
-import { TConfiguration } from '../models/entities';
 
-export class ConfigurationService extends BaseService {
+export class UserService extends BaseService {
+  constructor(
+    @inject({ key: 'repositories.UserRepository' })
+    private userRepository: UserRepository,
+  ) {
+    super({ scope: UserService.name });
+  }
+
+  async getUser(opts: { id: string }) {
+    const user = await this.userRepository.findById({ id: opts.id });
+
+    if (!user) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.NotFound,
+        message: 'User not found',
+      });
+    }
+
+    return user;
+  }
+}
+```
+
+**`scope`** is the tag written into every log line produced by this service. Use `ClassName.name` - it's the project convention and avoids string drift when renaming the class.
+
+---
+
+## Registering a Service
+
+Registration is always imperative - call `this.service(ClassName)` inside an application lifecycle method. Do not add `@injectable` to services; `this.service()` handles the binding.
+
+```typescript
+import { BaseApplication } from '@venizia/ignis';
+import { PostgresDataSource } from './datasources';
+import { UserRepository } from './repositories';
+import { UserService } from './services';
+
+export class Application extends BaseApplication {
+  preConfigure(): void {
+    // Register dependencies first, then the service
+    this.dataSource(PostgresDataSource);
+    this.repository(UserRepository);
+    this.service(UserService);   // binds as 'services.UserService'
+  }
+}
+```
+
+`this.service(UserService)` binds the class at the key `services.UserService`. Any other binding that injects `@inject({ key: 'services.UserService' })` resolves an instance from this binding. Service bindings are **transient** by default - each resolution creates a new instance. If your service must be shared (e.g., it holds state), set the scope explicitly: `this.service(UserService).setScope(BindingScopes.SINGLETON)`.
+
+---
+
+## Injecting Dependencies
+
+Use `@inject({ key })` on each constructor parameter. Two equivalent forms:
+
+### Plain string keys (concise)
+
+```typescript
+constructor(
+  @inject({ key: 'repositories.UserRepository' })
+  private userRepository: UserRepository,
+
+  @inject({ key: 'services.NotificationService' })
+  private notificationService: NotificationService,
+) {
+  super({ scope: UserService.name });
+}
+```
+
+### `BindingKeys.build` (refactor-safe)
+
+```typescript
+import { BindingKeys, BindingNamespaces } from '@venizia/ignis';
+
+constructor(
+  @inject({
+    key: BindingKeys.build({
+      namespace: BindingNamespaces.REPOSITORY,  // 'repositories'
+      key: UserRepository.name,                 // 'UserRepository'
+    }),
+  })
+  private userRepository: UserRepository,
+) {
+  super({ scope: UserService.name });
+}
+```
+
+Both produce the same runtime key (`repositories.UserRepository`). `BindingKeys.build` is preferred in larger codebases because a class rename caught by the TypeScript compiler automatically updates the key.
+
+---
+
+## Logging
+
+`BaseService` inherits `this.logger` from `BaseHelper`. Scope log lines to the current method:
+
+```typescript
+async signIn(opts: { username: string }): Promise<string> {
+  this.logger.for('signIn').info('SignIn called | username: %s', opts.username);
+
+  const user = await this.userRepository.findByUsername(opts.username);
+
+  if (!user) {
+    this.logger.for('signIn').warn('User not found | username: %s', opts.username);
+    throw getError({ statusCode: HTTP.ResultCodes.RS_4.Unauthorized, message: 'Invalid credentials' });
+  }
+
+  this.logger.for('signIn').info('SignIn successful | userId: %s', user.id);
+  return await this.generateToken({ userId: user.id });
+}
+```
+
+`this.logger.for('signIn')` adds a `[signIn]` tag to each line without creating a new logger object.
+
+---
+
+## Service-to-Service Composition
+
+Services can inject other services the same way they inject repositories. This is the primary mechanism for logic reuse.
+
+```typescript
+export class RepositoryTestService extends BaseService {
+  constructor(
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: CrudTestService.name,
+      }),
+    })
+    private readonly crudTestService: CrudTestService,
+
+    @inject({
+      key: BindingKeys.build({
+        namespace: BindingNamespaces.SERVICE,
+        key: TransactionTestService.name,
+      }),
+    })
+    private readonly transactionTestService: TransactionTestService,
+  ) {
+    super({ scope: RepositoryTestService.name });
+  }
+
+  async runAll(): Promise<void> {
+    await this.crudTestService.run();
+    await this.transactionTestService.run();
+  }
+}
+```
+
+Register all participating services in `preConfigure()`:
+
+```typescript
+this.service(CrudTestService);
+this.service(TransactionTestService);
+this.service(RepositoryTestService);
+```
+
+The DI container resolves the dependency graph automatically - registration order within the same lifecycle phase does not matter.
+
+---
+
+## Worked Example: Authentication Service
+
+The following is representative of `examples/vert/src/services/authentication.service.ts`. It shows the complete pattern: multiple injected dependencies, method-scoped logging, error handling, and calling other services.
+
+```typescript
+import { BaseService, IAuthService, inject, JWKSIssuerTokenService, TContext } from '@venizia/ignis';
+import { getError, HTTP } from '@venizia/ignis-helpers';
+import { compare, genSalt, hash } from 'bcrypt';
+import { Env } from 'hono';
+
+export class AuthenticationService
+  extends BaseService
+  implements IAuthService<Env, TSignInRequest, TSignInResponse, ...>
+{
   constructor(
-    @inject({ key: 'repositories.ConfigurationRepository' })
-    private configurationRepository: ConfigurationRepository,
+    // Inject a repository by string key
     @inject({ key: 'repositories.UserRepository' })
     private userRepository: UserRepository,
-    @inject({ key: 'services.LoggingService' })
-    private loggingService: LoggingService, // Injecting another service for reuse
+
+    // Inject a built-in framework service by string key
+    @inject({ key: 'services.JWKSIssuerTokenService' })
+    private jwksTokenService: JWKSIssuerTokenService,
   ) {
-    super({ scope: ConfigurationService.name });
+    super({ scope: AuthenticationService.name });
+  }
+
+  async signIn(_context: TContext<Env>, opts: TSignInRequest): Promise<TSignInResponse> {
+    this.logger.for('signIn').info('SignIn called | identifier: %j', opts.identifier);
+
+    const user = await this.userRepository.findByUsername(opts.identifier.value);
+
+    if (!user) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+        message: 'Invalid credentials',
+      });
+    }
+
+    const isValid = await compare(opts.credential.value, user.password);
+    if (!isValid) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
+        message: 'Invalid credentials',
+      });
+    }
+
+    const token = await this.jwksTokenService.generate({
+      payload: { userId: user.id, email: user.email },
+    });
+
+    this.logger.for('signIn').info('SignIn successful | userId: %s', user.id);
+    return { token: { value: token, type: 'Bearer' } };
+  }
+
+  async signUp(_context: TContext<Env>, opts: TSignUpRequest): Promise<TSignUpResponse> {
+    this.logger.for('signUp').info('SignUp called | username: %s', opts.username);
+
+    const existing = await this.userRepository.findByUsername(opts.username);
+    if (existing) {
+      throw getError({
+        statusCode: HTTP.ResultCodes.RS_4.Conflict,
+        message: 'Username already exists',
+      });
+    }
+
+    const salt = await genSalt();
+    const hashedPassword = await hash(opts.credential, salt);
+
+    await this.userRepository.create({ data: { username: opts.username, password: hashedPassword } });
+
+    return { message: 'User registered successfully' };
   }
+}
+```
 
-  async createConfigurationForUser(opts: {
-    userId: string;
-    data: Partial<TConfiguration>;
-  }): Promise<TConfiguration> {
-    // Call another service logic
-    await this.loggingService.audit({ message: `Creating config for user: ${opts.userId}` });
+Registration:
 
-    // Business logic: Check if the user exists
-    const user = await this.userRepository.findById({ id: opts.userId });
-// ...
+```typescript
+// application.ts
+preConfigure(): void {
+  this.dataSource(PostgresDataSource);
+  this.repository(UserRepository);
+  this.service(AuthenticationService);  // 'services.AuthenticationService'
+}
 ```
 
-### BaseService API
+---
 
-`BaseService` is intentionally minimal. It extends `BaseHelper` to provide scoped logging:
+## Transaction Orchestration
+
+Use a datasource reference to begin a transaction, then pass the transaction handle through repository `options`:
 
 ```typescript
-export abstract class BaseService extends BaseHelper implements IService {
-  constructor(opts: { scope: string }) {
-    super({ scope: opts.scope });
+export class CheckoutService extends BaseService {
+  constructor(
+    @inject({ key: 'datasources.PostgresDataSource' })
+    private dataSource: PostgresDataSource,
+
+    @inject({ key: 'repositories.OrderRepository' })
+    private orderRepository: OrderRepository,
+
+    @inject({ key: 'repositories.InventoryRepository' })
+    private inventoryRepository: InventoryRepository,
+  ) {
+    super({ scope: CheckoutService.name });
+  }
+
+  async placeOrder(opts: { userId: string; items: OrderItem[] }): Promise<Order> {
+    const log = this.logger.for('placeOrder');
+    const transaction = await this.dataSource.beginTransaction();
+
+    try {
+      const { data: order } = await this.orderRepository.create({
+        data: { userId: opts.userId },
+        options: { transaction },
+      });
+
+      for (const item of opts.items) {
+        await this.inventoryRepository.updateById({
+          id: item.productId,
+          data: { stock: item.quantity },
+          options: { transaction },
+        });
+      }
+
+      await transaction.commit();
+      log.info('Order placed | orderId: %s', order.id);
+      return order;
+    } catch (error) {
+      await transaction.rollback();
+      log.error('Order failed, rolled back | error: %s', error);
+      throw error;
+    }
   }
 }
 ```
 
-There is no built-in CRUD service -- implement business logic directly in your service methods. This keeps the service layer focused on your domain-specific operations rather than generic data access patterns (which belong in repositories).
+Always call `rollback()` in `catch` - an uncommitted transaction holds a database connection until it is released.
 
-## How Services Fit into the Architecture
+---
 
-Services act as the primary layer for business logic, sitting between controllers and repositories. While controllers are the typical entry point, **services can also inject and call other services**. This enables powerful logic reuse and allows you to build complex use cases by composing smaller, specialized services.
+## Architecture Diagram
 
 ```mermaid
 graph LR
-    A[Client Request] --> B(Controller);
-    B --> C1{Service A};
-    C1 --> C2{Service B};
-    C1 --> D1[Repository A];
-    C2 --> D2[Repository B];
-    D1 --> E((Database));
-    D2 --> E;
-
-    subgraph "Presentation Layer"
+    A[HTTP Request] --> B(Controller)
+    B --> C{Service A}
+    C --> D{Service B}
+    C --> E[Repository A]
+    D --> F[Repository B]
+    E --> G((Database))
+    F --> G
+
+    subgraph "Presentation"
         B
     end
-    subgraph "Business Logic Layer"
-        C1
-        C2
-    end
-    subgraph "Data Access Layer"
-        D1
-        D2
+    subgraph "Business Logic"
+        C
+        D
     end
-    subgraph "Data Store"
+    subgraph "Data Access"
         E
+        F
     end
 ```
 
-This layered architecture makes your application:
+Controllers call services. Services call other services and repositories. Repositories call the database. No layer reaches past its immediate neighbor.
+
+---
+
+## Provider vs Service
+
+**Services** contain business logic and are resolved from the DI container (transient scope by default).
+
+**Providers** implement the Factory pattern - their `value(container)` method produces a configured value or instance on demand (mail transport, cache driver, middleware). Use a Provider when you need to select between multiple implementations at runtime.
+
+See [Providers Reference](/references/base/providers) for the full comparison and examples.
 
--   **More Organized:** Each layer has a clear and distinct responsibility.
--   **Easier to Test:** You can test your business logic in isolation by providing mock repositories to your services, without needing a live database.
--   **More Flexible:** You can change your database or data access implementation (e.g., switch from PostgreSQL to MySQL) by only changing the repository and datasource layer, with no changes to your business logic.
+---
 
 ## See Also
 
@@ -107,13 +377,13 @@ This layered architecture makes your application:
 
 - **References:**
   - [BaseService API](/references/base/services) - Complete API reference
-  - [Providers](/references/base/providers) - Factory pattern for runtime instantiation
+  - [Providers](/references/base/providers) - Factory pattern
   - [Logger Helper](/extensions/helpers/logger/) - Logging in services
 
 - **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns) - Service layer design
-  - [Testing](/guides/tutorials/testing) - Unit testing services
+  - [Architectural Patterns](/best-practices/architectural-patterns)
+  - [Testing](/guides/tutorials/testing)
 
 - **Tutorials:**
-  - [Building a CRUD API](/guides/tutorials/building-a-crud-api) - Service examples
-  - [E-commerce API](/guides/tutorials/ecommerce-api) - Complex business logic
+  - [Building a CRUD API](/guides/tutorials/building-a-crud-api)
+  - [E-commerce API](/guides/tutorials/ecommerce-api)

package/content/guides/get-started/5-minute-quickstart.md

@@ -1,6 +1,6 @@
 # 5-Minute Quickstart
 
-Build your first Ignis API endpoint in 5 minutes. No database, no complex setup - just a working "Hello World" API.
+Build your first IGNIS API endpoint in 5 minutes. No database, no complex setup - just a working "Hello World" API.
 
 **Time to Complete:** ~5 minutes
 
@@ -64,7 +64,7 @@ node_modules
 ## Step 3: Write Your API (2 minutes)
 
 :::info What is a Decorator?
-A decorator is a TypeScript feature that adds behavior to classes, methods, or properties. It's the `@something` syntax you see before definitions (like `@controller`, `@get`, `@inject`). Decorators in Ignis handle routing, dependency injection, and API documentation automatically.
+A decorator is a TypeScript feature that adds behavior to classes, methods, or properties. It's the `@something` syntax you see before definitions (like `@controller`, `@get`, `@inject`). Decorators in IGNIS handle routing, dependency injection, and API documentation automatically.
 
 [Learn more →](/guides/reference/glossary#decorators)
 :::
@@ -86,7 +86,7 @@ import {
   get,
   IApplicationInfo,
   jsonContent,
-  SwaggerComponent,
+  ApiReferenceComponent,
 } from "@venizia/ignis";
 import { HTTP } from "@venizia/ignis-helpers";
 import { Context } from "hono";
@@ -115,7 +115,7 @@ class HelloController extends BaseRestController {
     },
   })
   sayHello(c: Context) {
-    return c.json({ message: "Hello from Ignis!" }, HTTP.ResultCodes.RS_2.Ok);
+    return c.json({ message: "Hello from IGNIS!" }, HTTP.ResultCodes.RS_2.Ok);
   }
 }
 
@@ -130,7 +130,7 @@ class App extends BaseApplication {
   }
 
   preConfigure() {
-    this.component(SwaggerComponent);
+    this.component(ApiReferenceComponent);
     this.controller(HelloController);
   }
 
@@ -222,7 +222,7 @@ Visit `http://localhost:3000/api/hello` in your browser!
 **Response:**
 
 ```json
-{ "message": "Hello from Ignis!" }
+{ "message": "Hello from IGNIS!" }
 ```
 
 ## View API Docs
@@ -240,27 +240,27 @@ Open `http://localhost:3000/doc/explorer` to see interactive Swagger UI document
 | `Zod schema` | Validates request/response and auto-generates OpenAPI docs |
 | `BaseRestController` | Provides lifecycle hooks, route binding, and OpenAPI integration for REST controllers |
 | `BaseApplication` | Manages dependency injection, middleware, and server startup |
-| `SwaggerComponent` | Generates interactive API docs at `/doc/explorer` |
+| `ApiReferenceComponent` | Generates interactive API docs at `/doc/explorer` |
 | `app.start()` | Runs the full lifecycle (preConfigure → register resources → middlewares) then starts HTTP server on port 3000 |
 
 ### Why Development Configs?
 
 You might wonder why we set up TypeScript, ESLint, and Prettier configs in a "quickstart". Here's why:
 
-**Ignis is opinionated about code quality.** We believe clean, consistent code from day one prevents technical debt later. The `@venizia/dev-configs` package provides pre-configured settings that:
+**IGNIS is opinionated about code quality.** We believe clean, consistent code from day one prevents technical debt later. The `@venizia/dev-configs` package provides pre-configured settings that:
 
 | Config | Purpose |
 |--------|---------|
-| `tsconfig.json` | Strict TypeScript settings optimized for Ignis decorators and path aliases |
+| `tsconfig.json` | Strict TypeScript settings optimized for IGNIS decorators and path aliases |
 | `eslint.config.mjs` | Catches common errors, enforces best practices, works with TypeScript |
-| `.prettierrc.mjs` | Consistent formatting across your team — no more style debates |
+| `.prettierrc.mjs` | Consistent formatting across your team - no more style debates |
 
-**Benefits of starting with Ignis code style:**
+**Benefits of starting with IGNIS code style:**
 
-- **Consistency** — Same patterns across all Ignis projects
-- **IDE Support** — Better autocomplete, error detection, and refactoring
-- **Team Ready** — New developers can onboard faster with familiar structure
-- **CI/CD Friendly** — Lint and format checks work out of the box
+- **Consistency** - Same patterns across all IGNIS projects
+- **IDE Support** - Better autocomplete, error detection, and refactoring
+- **Team Ready** - New developers can onboard faster with familiar structure
+- **CI/CD Friendly** - Lint and format checks work out of the box
 
 > [!TIP]
 > All configs extend from `@venizia/dev-configs`, so you get updates automatically. Customize by overriding specific rules in your local config files.