@venizia/ignis-docs 0.0.7 → 0.0.8-0

package/wiki/references/quick-reference.md

@@ -1,7 +1,7 @@
 ---
 title: Quick Reference Card
 description: Single-page cheat sheet for IGNIS framework
-lastUpdated: 2026-01-03
+lastUpdated: 2026-03-15
 ---
 
 # Quick Reference Card
@@ -33,25 +33,53 @@ await app.start();
 - `get<T>(key)` - Resolve from DI container
 - `mountControllers()` - Register controllers
 
-### BaseController
+### BaseRestController
 
 ```typescript
-import { BaseController, controller, get } from '@venizia/ignis';
+import { BaseRestController, controller, get } from '@venizia/ignis';
 
 @controller({ path: '/users' })
-class UserController extends BaseController {
-  @get({ configs: { path: '/:id' } })
-  async getUser(@param('id') id: string) {
-    return { id, name: 'John' };
+class UserController extends BaseRestController {
+  constructor() {
+    super({ scope: UserController.name, path: '/users' });
+  }
+
+  override binding() {}
+
+  @get({ configs: { path: '/:id', responses: { 200: { description: 'User' } } } })
+  getUser(c: Context) {
+    const id = c.req.param('id');
+    return c.json({ id, name: 'John' });
   }
 }
 ```
 
 **Key Properties:**
-- `this.context` - Hono context
-- `this.container` - DI container
+- `this.router` - OpenAPIHono instance
+- `this.path` - Controller base path
 - `this.logger` - Scoped logger
 
+### BaseGrpcController
+
+```typescript
+import { BaseGrpcController, controller, unary, ControllerTransports } from '@venizia/ignis';
+import { GreeterService } from '../gen/greeter_connect';
+
+@controller({ path: '/grpc', transport: ControllerTransports.GRPC, service: GreeterService })
+class GreeterController extends BaseGrpcController {
+  constructor() {
+    super({ scope: GreeterController.name, path: '/grpc' });
+  }
+
+  override binding() {}
+
+  @unary({ configs: { name: 'sayHello' } })
+  async sayHello(request: SayHelloRequest) {
+    return { message: `Hello, ${request.name}!` };
+  }
+}
+```
+
 ### BaseService
 
 ```typescript
@@ -133,39 +161,41 @@ class User extends BaseEntity {
 | `@patch()` | PATCH | `@patch({ configs: { path: '/:id' } })` |
 | `@del()` | DELETE | `@del({ configs: { path: '/:id' } })` |
 
-### Parameter Decorators
+### RPC Method Decorators (gRPC)
 
-| Decorator | Extracts | Example |
+| Decorator | RPC Type | Example |
 |-----------|----------|---------|
-| `@param('name')` | Route parameter | `@param('id') id: string` |
-| `@query('name')` | Query string | `@query('page') page: string` |
-| `@body()` | Request body | `@body() data: CreateUserDto` |
-| `@header('name')` | HTTP header | `@header('authorization') auth: string` |
+| `@rpc()` | Generic | `@rpc({ configs: { name: 'myMethod', method: 'unary' } })` |
+| `@unary()` | Unary | `@unary({ configs: { name: 'sayHello' } })` |
+| `@serverStream()` | Server streaming | `@serverStream({ configs: { name: 'listItems' } })` |
+| `@clientStream()` | Client streaming | `@clientStream({ configs: { name: 'uploadData' } })` |
+| `@bidiStream()` | Bidirectional | `@bidiStream({ configs: { name: 'chat' } })` |
 
-### Example
+### REST Example
 
 ```typescript
 @controller({ path: '/users' })
-class UserController extends BaseController {
-  @post({ configs: { path: '/' } })
-  async createUser(
-    @body() data: CreateUserDto,
-    @header('authorization') token: string
+class UserController extends BaseRestController {
+  constructor(
+    @inject({ key: 'services.UserService' }) private userService: UserService,
   ) {
-    return this.userService.create(data);
+    super({ scope: UserController.name, path: '/users' });
   }
 
-  @get({ configs: { path: '/' } })
-  async listUsers(
-    @query('page') page: string,
-    @query('limit') limit: string
-  ) {
-    return this.userService.findAll({ page, limit });
+  override binding() {}
+
+  @post({ configs: { path: '/', responses: { 201: { description: 'Created' } } } })
+  async createUser(c: Context) {
+    const data = await c.req.json();
+    const result = await this.userService.create(data);
+    return c.json(result, 201);
   }
 
-  @get({ configs: { path: '/:id' } })
-  async getUser(@param('id') id: string) {
-    return this.userService.findById(id);
+  @get({ configs: { path: '/:id', responses: { 200: { description: 'User' } } } })
+  async getUser(c: Context) {
+    const id = c.req.param('id');
+    const result = await this.userService.findById(id);
+    return c.json(result);
   }
 }
 ```
@@ -309,15 +339,13 @@ class MyService extends BaseService {
 ```typescript
 import { inject } from '@venizia/ignis';
 
-@injectable()
-class UserController extends BaseController {
+class UserController extends BaseRestController {
   constructor(
     @inject({ key: 'services.UserService' })
-    private userService: UserService
+    private userService: UserService,
   ) {
-    super();
+    super({ scope: UserController.name, path: '/users' });
   }
-}
 ```
 
 ### Manual Resolution
@@ -336,21 +364,24 @@ import {
   // Application
   BaseApplication,
 
-  // Controllers
-  BaseController,
+  // REST Controllers
+  BaseRestController,
   controller,
 
-  // HTTP Methods
-  get, post, put, patch, del,
+  // gRPC Controllers
+  BaseGrpcController,
+  ControllerTransports,
+
+  // REST Route Decorators
+  get, post, put, patch, del, api,
 
-  // Parameters
-  param, query, body, header, context,
+  // gRPC Route Decorators
+  rpc, unary, serverStream, clientStream, bidiStream,
 
   // Services
   BaseService,
 
   // Repositories
-  BaseRepository,
   DefaultCRUDRepository,
 
   // Models
@@ -423,8 +454,9 @@ import { z } from '@hono/zod-openapi';
     }),
   },
 })
-async getUser(@param('id') id: string) {
-  return { id, name: 'John', email: 'john@example.com' };
+getUser(c: Context) {
+  const id = c.req.param('id');
+  return c.json({ id, name: 'John', email: 'john@example.com' });
 }
 ```
 
@@ -441,8 +473,8 @@ import { htmlResponse } from '@venizia/ignis';
     }),
   },
 })
-async getDashboard() {
-  return this.context.html(<DashboardPage />);
+getDashboard(c: Context) {
+  return c.html(<DashboardPage />);
 }
 ```
 
@@ -552,26 +584,28 @@ const apiKey = EnvHelper.getRequired('API_KEY');
 ```typescript
 // Controller
 @controller({ path: '/users' })
-class UserController extends BaseController {
+class UserController extends BaseRestController {
   constructor(
     @inject({ key: 'services.UserService' })
-    private userService: UserService
+    private userService: UserService,
   ) {
-    super();
+    super({ scope: UserController.name, path: '/users' });
   }
 
-  @post({ configs: { path: '/' } })
-  async createUser(@body() data: CreateUserDto) {
-    return this.userService.create(data);
+  override binding() {}
+
+  @post({ configs: { path: '/', responses: { 201: { description: 'Created' } } } })
+  async createUser(c: Context) {
+    const data = await c.req.json();
+    return c.json(await this.userService.create(data), 201);
   }
 }
 
 // Service
-@injectable()
 class UserService extends BaseService {
   constructor(
     @inject({ key: 'repositories.UserRepository' })
-    private userRepo: UserRepository
+    private userRepo: UserRepository,
   ) {
     super({ scope: UserService.name });
   }
@@ -581,19 +615,18 @@ class UserService extends BaseService {
     const hashedPassword = await hash({ value: data.password });
 
     return this.userRepo.create({
-      ...data,
-      password: hashedPassword,
-      status: Statuses.ACTIVATED,
+      data: {
+        ...data,
+        password: hashedPassword,
+      },
     });
   }
 }
 
 // Repository
-@injectable()
-class UserRepository extends DefaultCRUDRepository<User> {
-  constructor() {
-    super(User);
-  }
+@repository({ model: User, dataSource: PostgresDataSource })
+class UserRepository extends DefaultCRUDRepository<typeof User.schema> {
+  // DataSource auto-injected from @repository decorator
 }
 ```
 
@@ -602,8 +635,8 @@ class UserRepository extends DefaultCRUDRepository<User> {
 
 - **Full Documentation:**
   - [Base Abstractions](./base/) - Complete API reference
-  - [Components](./components/) - Pre-built features
-  - [Helpers](./helpers/) - Utility helpers
+  - [Components](/extensions/components/) - Pre-built features
+  - [Helpers](/extensions/helpers/) - Utility helpers
   - [Utilities](./utilities/) - Pure functions
 
 - **Guides:**

package/wiki/references/utilities/crypto.md

@@ -1,6 +1,6 @@
 # Crypto Utility
 
-The Crypto utility provides simple, stateless functions for cryptographic hashing.
+The Crypto utility provides simple, stateless functions for cryptographic hashing using Node.js's built-in `node:crypto` module.
 
 ## `hash`
 
@@ -10,9 +10,15 @@ The `hash` function allows you to create a hash of a string using either `SHA256
 
 -   `text` (string): The input string to hash.
 -   `options` (object):
-    -   `algorithm` ('SHA256' | 'MD5'): The hashing algorithm to use.
-    -   `secret` (string, optional): The secret key for HMAC-SHA256.
-    -   `outputType` (BinaryToTextEncoding): The output encoding (e.g., 'hex', 'base64').
+    -   `algorithm` (`'SHA256'` | `'MD5'`): The hashing algorithm to use.
+    -   `secret` (string, optional): The secret key for HMAC-SHA256. If `algorithm` is `'SHA256'` and no `secret` is provided, the original text is returned unchanged.
+    -   `outputType` (`BinaryToTextEncoding`): The output encoding (e.g., `'hex'`, `'base64'`).
+
+### Behavior
+
+-   **SHA256**: Creates an HMAC using the provided `secret`. Returns the original text if no secret is given.
+-   **MD5**: Creates a standard hash digest (no secret needed).
+-   **Other algorithms**: Returns the original text unchanged.
 
 ### Examples
 
@@ -37,3 +43,14 @@ const sha256Hash = hash('some text', {
 });
 // => 'b8a1c3f2... (64-character hex string)'
 ```
+
+**Base64 output**
+
+```typescript
+import { hash } from '@venizia/ignis-helpers';
+
+const base64Hash = hash('some text', {
+  algorithm: 'MD5',
+  outputType: 'base64',
+});
+```

package/wiki/references/utilities/date.md

@@ -6,6 +6,8 @@ The Date utility provides a set of functions for date and time manipulation, bui
 
 The `dayjs` object is re-exported, so you can use it directly for any date and time operations. It is pre-configured with the following plugins: `CustomParseFormat`, `UTC`, `Timezone`, `Weekday`, and `IsoWeek`.
 
+The default timezone is set to `Asia/Ho_Chi_Minh` and can be overridden via the `APP_ENV_APPLICATION_TIMEZONE` environment variable.
+
 ```typescript
 import { dayjs } from '@venizia/ignis-helpers';
 
@@ -32,21 +34,30 @@ async function myAsyncFunction() {
 
 ## Weekday Functions
 
--   **`isWeekday(date)`**: Checks if a given date is a weekday (Monday to Friday).
--   **`getPreviousWeekday(opts)`**: Returns the previous weekday from a given date.
--   **`getNextWeekday(opts)`**: Returns the next weekday from a given date.
+-   **`isWeekday(date)`**: Checks if a given date is a weekday (Monday to Friday). Accepts a `string` or `dayjs.Dayjs` instance.
+-   **`getPreviousWeekday(opts?)`**: Returns the previous weekday from a given date. If no date is provided, defaults to today.
+-   **`getNextWeekday(opts?)`**: Returns the next weekday from a given date. If no date is provided, defaults to today.
 
 ```typescript
-import { isWeekday, getPreviousWeekday } from '@venizia/ignis-helpers';
+import { isWeekday, getPreviousWeekday, getNextWeekday } from '@venizia/ignis-helpers';
 
-const isTodayWeekday = isWeekday(new Date());
+const isTodayWeekday = isWeekday('2026-03-15');
 
 const lastBusinessDay = getPreviousWeekday();
+const nextBusinessDay = getNextWeekday({ date: '2026-03-13' });
 ```
 
 ## `getDateTz`
 
-The `getDateTz` function allows you to get a `dayjs` object in a specific timezone, with an optional offset.
+The `getDateTz` function allows you to get a `dayjs` object in a specific timezone, with an optional hour offset.
+
+### `getDateTz(opts)`
+
+-   `opts` (object):
+    -   `date` (string): The date string to parse.
+    -   `timezone` (string): The IANA timezone name.
+    -   `useClientTz` (boolean, optional): Whether to keep the client's timezone. Defaults to `false`.
+    -   `timeOffset` (number, optional): Number of hours to add to the result. Defaults to `0`.
 
 ```typescript
 import { getDateTz } from '@venizia/ignis-helpers';
@@ -55,11 +66,18 @@ const tokyoTime = getDateTz({
   date: '2023-10-27T10:00:00Z',
   timezone: 'Asia/Tokyo',
 });
+
+// With hour offset
+const offsetTime = getDateTz({
+  date: '2023-10-27T10:00:00Z',
+  timezone: 'Asia/Tokyo',
+  timeOffset: 2, // Add 2 hours
+});
 ```
 
 ## `hrTime`
 
-The `hrTime` function returns a high-resolution time measurement in seconds, useful for performance benchmarking.
+The `hrTime` function returns a high-resolution time measurement in seconds using `process.hrtime()`, useful for performance benchmarking. The result is rounded to 9 decimal places.
 
 ```typescript
 import { hrTime } from '@venizia/ignis-helpers';

package/wiki/references/utilities/index.md

@@ -4,26 +4,26 @@ Pure, standalone functions providing common, reusable logic for the Ignis framew
 
 ## Quick Reference
 
-| Utility | Purpose | Key Functions |
-|---------|---------|---------------|
-| **Crypto** | Cryptographic operations | `hash()`, `compare()`, `encrypt()`, `decrypt()` |
-| **Date** | Date/time manipulation | `format()`, `parse()`, `diff()`, `add()` |
-| **JSX** | HTML/JSX responses | `htmlContent()`, `htmlResponse()` |
-| **Module** | Module detection | `isInstalled()`, `resolve()` |
-| **Parse** | Data type conversion | `toBoolean()`, `toNumber()`, `toArray()` |
-| **Performance** | Execution timing | `measure()`, `measureAsync()` |
-| **Promise** | Promise helpers | `delay()`, `timeout()`, `retry()` |
-| **Request** | HTTP utilities | `parseMultipart()`, `contentDisposition()` |
-| **Schema** | Zod schema helpers | `jsonContent()`, `jsonResponse()` |
-| **Statuses** | Status code constants | `Statuses`, `UserStatuses`, `CommonStatuses` |
+| Utility | Package | Purpose | Key Functions |
+|---------|---------|---------|---------------|
+| **Crypto** | `ignis-helpers` | Cryptographic hashing | `hash()` |
+| **Date** | `ignis-helpers` | Date/time manipulation | `dayjs`, `sleep()`, `isWeekday()`, `getDateTz()`, `hrTime()` |
+| **JSX** | `ignis` | HTML/JSX responses | `htmlContent()`, `htmlResponse()` |
+| **Module** | `ignis-helpers` | Module validation | `validateModule()` |
+| **Parse** | `ignis-helpers` | Data type conversion | `int()`, `float()`, `toBoolean()`, `toCamel()`, `getNumberValue()` |
+| **Performance** | `ignis-helpers` | Execution timing | `executeWithPerformanceMeasure()`, `getPerformanceCheckpoint()` |
+| **Promise** | `ignis-helpers` | Promise helpers | `executePromiseWithLimit()`, `isPromiseLike()`, `getDeepProperty()` |
+| **Request** | `ignis-helpers` | HTTP utilities | `parseMultipartBody()`, `sanitizeFilename()`, `createContentDispositionHeader()` |
+| **Schema** | `ignis` | Zod schema helpers | `jsonContent()`, `jsonResponse()`, `requiredString()`, `idParamsSchema()` |
+| **Statuses** | `ignis` | Status code constants | `Statuses`, `CommonStatuses`, `UserStatuses`, `RoleStatuses` |
 
 ## What's in This Section
 
 ### Data Processing
 
-- [**Crypto**](./crypto.md) - Simple, stateless cryptographic functions for hashing, comparison, and encryption/decryption operations
-- [**Parse**](./parse.md) - Functions for parsing and converting data types safely with proper type inference
-- [**Schema**](./schema.md) - Helpers for creating and validating Zod schemas, especially for OpenAPI request/response validation
+- [**Crypto**](./crypto.md) - Simple, stateless cryptographic functions for hashing (SHA256 HMAC, MD5)
+- [**Parse**](./parse.md) - Functions for parsing and converting data types safely (integers, floats, booleans, camelCase, locale-aware numbers, array-to-map)
+- [**Schema**](./schema.md) - Helpers for creating Zod schemas for OpenAPI request/response validation
 - [**Statuses**](./statuses.md) - Standardized status code constants for entity lifecycle management
 
 ### Time & Performance
@@ -34,30 +34,32 @@ Pure, standalone functions providing common, reusable logic for the Ignis framew
 ### Async & HTTP
 
 - [**JSX**](./jsx.md) - HTML and JSX response utilities for server-side rendering and OpenAPI documentation
-- [**Promise**](./promise.md) - Helper functions for working with Promises including retry, timeout, and delay
+- [**Promise**](./promise.md) - Helper functions for working with Promises including concurrency limiting and value transformation
 - [**Request**](./request.md) - HTTP request utilities for parsing multipart form data and creating secure Content-Disposition headers
 
 ### Runtime
 
-- [**Module**](./module.md) - Utility for checking if a Node.js module is installed at runtime
+- [**Module**](./module.md) - Utility for validating that required Node.js modules are installed at runtime
 
 ## Usage Pattern
 
 Utilities are imported from `@venizia/ignis` (schema, JSX, and status helpers) or `@venizia/ignis-helpers` (runtime utilities):
 
 ```typescript
-import { jsonContent, jsonResponse, htmlResponse, Statuses } from '@venizia/ignis';
-import { hash, compare, formatDate, toBoolean } from '@venizia/ignis-helpers';
+import { jsonContent, jsonResponse, htmlResponse, requiredString, Statuses } from '@venizia/ignis';
+import { hash, dayjs, sleep, int, float, toBoolean, getNumberValue } from '@venizia/ignis-helpers';
 
 // Crypto
-const hashed = await hash({ value: 'password123' });
-const isMatch = await compare({ value: 'password123', hashed });
+const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });
 
 // Date
-const formatted = formatDate({ date: new Date(), format: 'YYYY-MM-DD' });
+const now = dayjs();
+await sleep(1000);
 
 // Parse
-const boolValue = toBoolean('true'); // true
+const myInt = int('1,000'); // 1000
+const myFloat = float('1,234.567', 2); // 1234.57
+const myBool = toBoolean('true'); // true
 
 // Schema (for OpenAPI JSON routes)
 const responseSchema = jsonResponse({
@@ -77,4 +79,4 @@ if (Statuses.isCompleted(order.status)) {
 }
 ```
 
-> **Related:** [Helpers Reference](../helpers/) | [Core Concepts Guide](../../guides/core-concepts/application/)
+> **Related:** [Helpers Reference](/extensions/helpers/) | [Core Concepts Guide](../../guides/core-concepts/application/)