@venizia/ignis-docs 0.0.5 → 0.0.6-1

package/wiki/references/helpers/cron.md

@@ -1,108 +0,0 @@
-# Cron Helper
-
-Schedule and manage recurring tasks (cron jobs) using cron patterns.
-
-## Quick Reference
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `cronTime` | `string` | Cron pattern (e.g., `'0 */1 * * * *'` = every minute) |
-| `onTick` | `Function` | Callback executed on schedule |
-| `autoStart` | `boolean` | Start automatically (default: `false`) |
-| `tz` | `string` | Timezone (e.g., `'America/New_York'`) |
-| `errorHandler` | `Function` | Handle errors in `onTick` |
-
-### Common Cron Patterns
-
-| Pattern | Description |
-|---------|-------------|
-| `'0 */1 * * * *'` | Every minute |
-| `'0 */5 * * * *'` | Every 5 minutes |
-| `'0 0 * * * *'` | Every hour |
-| `'0 0 0 * * *'` | Every day at midnight |
-| `'0 0 0 * * 1'` | Every Monday at midnight |
-
-### Key Methods
-
-| Method | Purpose |
-|--------|---------|
-| `start()` | Start the cron job manually |
-| `modifyCronTime({ cronTime })` | Change schedule dynamically |
-| `duplicate({ cronTime })` | Create new job with same config |
-
-## Creating a Cron Job
-
-To create a cron job, you instantiate the `CronHelper` with your desired options.
-
-### `ICronHelperOptions`
-
--   `cronTime` (string): The cron pattern that defines when the job should run (e.g., `'0 */1 * * * *'` for every minute).
--   `onTick` (() => void | Promise<void>): The function to be executed when the cron job triggers.
--   `onCompleted` (CronOnCompleteCommand | null, optional): A function to be executed when the job stops.
--   `autoStart` (boolean, optional): If `true`, the job will start automatically. Defaults to `false`.
--   `tz` (string, optional): The timezone to use for the schedule.
--   `errorHandler` ((error: unknown) => void | null, optional): A function to handle errors that occur during the `onTick` execution.
-
-### Example
-
-Here's how to create a simple cron job that logs a message every minute:
-
-```typescript
-import { CronHelper } from '@venizia/ignis';
-
-const myJob = new CronHelper({
-  cronTime: '0 */1 * * * *', // Every minute
-  onTick: () => {
-    console.log('This message will be logged every minute.');
-  },
-  autoStart: true,
-  tz: 'America/New_York',
-});
-```
-
-## Managing Cron Jobs
-
-The `CronHelper` instance provides several methods for managing the cron job:
-
-### `start()`
-
-Manually starts the cron job if `autoStart` was set to `false`.
-
-```typescript
-myJob.start();
-```
-
-### `modifyCronTime(opts)`
-
-Dynamically changes the schedule of an existing cron job.
-
--   `cronTime` (string): The new cron pattern.
--   `shouldFireOnTick` (boolean, optional): If `true`, the `onTick` function will be executed immediately after the time is changed.
-
-```typescript
-// Change the job to run every 5 minutes
-myJob.modifyCronTime({ cronTime: '0 */5 * * * *' });
-```
-
-### `duplicate(opts)`
-
-Creates a new `CronHelper` instance with the same configuration but a new `cronTime`.
-
-```typescript
-const anotherJob = myJob.duplicate({ cronTime: '0 0 * * *' }); // Runs once at midnight
-anotherJob.start();
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - Scheduling jobs in services
-  - [Application](/guides/core-concepts/application/) - Scheduling on app startup
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Queue Helper](./queue) - Message queue processing
-
-- **External Resources:**
-  - [Cron Expression Guide](https://crontab.guru/) - Cron syntax reference
-  - [node-cron Documentation](https://github.com/node-cron/node-cron) - Cron library

package/wiki/references/helpers/crypto.md

@@ -1,132 +0,0 @@
-# Crypto Helper
-
-Cryptographic utilities for AES symmetric encryption, RSA asymmetric encryption, and hashing.
-
-## Quick Reference
-
-| Class/Function | Algorithm | Use Case |
-|----------------|-----------|----------|
-| **AES** | Symmetric | Fast encryption for data at rest (AES-256-CBC, AES-256-GCM) |
-| **RSA** | Asymmetric | Key exchange, digital signatures (public/private keys) |
-| **hash()** | MD5, SHA256 | Passwords, data integrity (HMAC support) |
-
-### AES Algorithms
-
-| Algorithm | Mode | Features |
-|-----------|------|----------|
-| `aes-256-cbc` | CBC | Standard block cipher mode |
-| `aes-256-gcm` | GCM | Authenticated encryption |
-
-### Common Methods
-
-| Operation | AES | RSA |
-|-----------|-----|-----|
-| Encrypt | `aes.encrypt(message, secret)` | `rsa.encrypt(message, publicKey)` |
-| Decrypt | `aes.decrypt(encrypted, secret)` | `rsa.decrypt(encrypted, privateKey)` |
-| Key Generation | N/A (use secret) | `rsa.generateDERKeyPair()` |
-
-## AES (Symmetric Encryption)
-
-The `AES` class provides an interface for encrypting and decrypting data using the Advanced Encryption Standard.
-
-### Creating an AES Instance
-
-You can create an `AES` instance by specifying the algorithm (`aes-256-cbc` or `aes-256-gcm`).
-
-```typescript
-import { AES } from '@venizia/ignis';
-
-const aes = AES.withAlgorithm('aes-256-cbc');
-```
-
-### Encrypting Data
-
-The `encrypt` method takes a message and a secret key.
-
-```typescript
-const secret = 'a-32-byte-long-secret-key-for-aes';
-const message = 'This is a secret message.';
-
-const encryptedMessage = aes.encrypt(message, secret);
-// => Returns a base64 encoded string containing the IV and encrypted data
-```
-
-### Decrypting Data
-
-The `decrypt` method takes the encrypted message and the same secret key.
-
-```typescript
-const decryptedMessage = aes.decrypt(encryptedMessage, secret);
-// => 'This is a secret message.'
-```
-
-## RSA (Asymmetric Encryption)
-
-The `RSA` class provides an interface for encrypting and decrypting data using the RSA algorithm.
-
-### Creating an RSA Instance
-
-```typescript
-import { RSA } from '@venizia/ignis';
-
-const rsa = RSA.withAlgorithm();
-```
-
-### Generating a Key Pair
-
-The `generateDERKeyPair` method creates a new public/private key pair in DER format.
-
-```typescript
-const { publicKey, privateKey } = rsa.generateDERKeyPair();
-```
-
-### Encrypting Data
-
-Encrypt data using the public key.
-
-```typescript
-const message = 'This is another secret.';
-const encrypted = rsa.encrypt(message, publicKey.toString('base64'));
-```
-
-### Decrypting Data
-
-Decrypt data using the private key.
-
-```typescript
-const decrypted = rsa.decrypt(encrypted, privateKey.toString('base64'));
-// => 'This is another secret.'
-```
-
-## Hash Utility
-
-In addition to the `Crypto` helper, `Ignis` also provides a standalone `hash` utility function for creating hashes (e.g., for passwords or data integrity checks).
-
-```typescript
-import { hash } from '@venizia/ignis';
-
-// MD5 Hash
-const md5Hash = hash('some text', { algorithm: 'MD5', outputType: 'hex' });
-
-// SHA256 HMAC
-const sha256Hash = hash('some text', {
-  algorithm: 'SHA256',
-  secret: 'a-secret-key',
-  outputType: 'hex',
-});
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - Password hashing in user service
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-
-- **References:**
-  - [Crypto Utility](/references/utilities/crypto) - Pure crypto utilities
-  - [Authentication Component](/references/components/authentication) - JWT and password verification
-
-- **Best Practices:**
-  - [Security Guidelines](/best-practices/security-guidelines) - Cryptographic best practices

package/wiki/references/helpers/env.md

@@ -1,83 +0,0 @@
-# Environment Helper
-
-Structured access to application-specific environment variables with prefix filtering.
-
-## Quick Reference
-
-| Feature | Description |
-|---------|-------------|
-| **Singleton** | `applicationEnvironment` - auto-initialized at startup |
-| **Prefix** | Default `APP_ENV_` (customizable via `APPLICATION_ENV_PREFIX`) |
-| **Type-safe** | `get<T>(key)` with type inference |
-| **Isolation** | Filters `process.env` to prevent conflicts |
-
-### Common Methods
-
-| Method | Purpose | Example |
-|--------|---------|---------|
-| `get<T>(key)` | Get typed environment variable | `get<string>(EnvironmentKeys.APP_ENV_JWT_SECRET)` |
-| `isDevelopment()` | Check if dev environment | `if (env.isDevelopment()) { ... }` |
-
-### Key Features
-
--   **Prefix-based Filtering**: Isolates app vars (e.g., `APP_ENV_*`)
--   **Type-safe Access**: `get<T>()` with type inference
--   **Centralized Management**: Single consistent access point
-
-## Usage
-
-You can import the `applicationEnvironment` instance and use it to retrieve your configuration values.
-
-### Getting Environment Variables
-
-```typescript
-import { applicationEnvironment, EnvironmentKeys } from '@venizia/ignis';
-
-// Get the JWT secret
-const jwtSecret = applicationEnvironment.get<string>(EnvironmentKeys.APP_ENV_JWT_SECRET);
-
-// Get the server port, parsing it as a number
-const serverPort = applicationEnvironment.get<number>(EnvironmentKeys.APP_ENV_SERVER_PORT);
-```
-
-### Checking the Current Environment
-
-You can use the `isDevelopment()` method to check if the application is running in a development environment.
-
-```typescript
-import { applicationEnvironment } from '@venizia/ignis';
-
-if (applicationEnvironment.isDevelopment()) {
-  // Do something only in development
-}
-```
-
-## Configuration
-
-The prefix for the environment variables can be configured by setting the `APPLICATION_ENV_PREFIX` variable in your environment.
-
-**Example `.env` file:**
-
-```
-APPLICATION_ENV_PREFIX=MY_APP_ENV
-
-# Now, your application variables should use the new prefix
-MY_APP_ENV_SERVER_HOST=0.0.0.0
-MY_APP_ENV_SERVER_PORT=3000
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Application](/guides/core-concepts/application/) - Environment validation
-  - [DataSources](/guides/core-concepts/persistent/datasources) - Database configuration
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-
-- **References:**
-  - [Environment Variables](/references/configuration/environment-variables) - Complete environment reference
-
-- **Best Practices:**
-  - [Security Guidelines](/best-practices/security-guidelines) - Environment variable security
-  - [Deployment Strategies](/best-practices/deployment-strategies) - Environment management

package/wiki/references/helpers/error.md

@@ -1,97 +0,0 @@
-# Error Helper
-
-Standardized error handling with consistent responses across the application.
-
-## Quick Reference
-
-| Class/Function | Purpose |
-|----------------|---------|
-| **ApplicationError** | Custom error class with `statusCode` and `messageCode` |
-| **getError()** | Utility to create `ApplicationError` instances |
-| **appErrorHandler** | Middleware catching and formatting errors |
-
-### Error Response Format
-
-| Environment | Includes |
-|-------------|----------|
-| **Production** | `message`, `statusCode`, `requestId` |
-| **Development** | Above + `stack`, `cause`, `url`, `path` |
-
-## `ApplicationError`
-
-Extends native `Error` with HTTP status codes and machine-readable message codes.
-
-### Creating an `ApplicationError`
-
-You can create a new `ApplicationError` with a message, status code, and an optional message code.
-
-```typescript
-import { getError, HTTP } from '@venizia/ignis';
-
-// Throw an error for a resource not found
-throw getError({
-  message: 'User not found',
-  statusCode: HTTP.ResultCodes.RS_4.NotFound,
-  messageCode: 'USER_NOT_FOUND',
-});
-```
-
-### `getError()` Utility
-
-For convenience, you can use the `getError()` utility function to create `ApplicationError` instances.
-
-```typescript
-import { getError, HTTP } from '@venizia/ignis';
-
-throw getError({
-  message: 'Invalid credentials',
-  statusCode: HTTP.ResultCodes.RS_4.Unauthorized,
-});
-```
-
-## Error Handling Middleware
-
-`Ignis` provides a default error handling middleware (`appErrorHandler`) that catches instances of `ApplicationError` (and other errors) and formats them into a consistent JSON response.
-
-In development mode, the response will include the stack trace and error cause for easier debugging. In production, these details are omitted.
-
-**Example Error Response (Production):**
-
-```json
-{
-  "message": "User not found",
-  "statusCode": 404,
-  "requestId": "some-request-id"
-}
-```
-
-**Example Error Response (Development):**
-
-```json
-{
-  "message": "User not found",
-  "statusCode": 404,
-  "requestId": "some-request-id",
-  "stack": "Error: User not found\n    at ...",
-  "cause": "...",
-  "url": "/api/users/123",
-  "path": "/api/users/123"
-}
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Controllers](/guides/core-concepts/controllers) - Throwing errors in controllers
-  - [Services](/guides/core-concepts/services) - Error handling in services
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Logger Helper](./logger) - Logging errors
-
-- **References:**
-  - [Middlewares](/references/base/middlewares) - Error handler middleware
-
-- **Best Practices:**
-  - [Common Pitfalls](/best-practices/common-pitfalls) - Error handling anti-patterns
-  - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging errors

package/wiki/references/helpers/inversion.md

@@ -1,176 +0,0 @@
-# Inversion of Control (IoC) and Dependency Injection (DI)
-
-Core DI system enabling loosely coupled, testable, and extensible code.
-
-> **Architecture Update:** The core DI container functionality has been extracted to a standalone package `@venizia/ignis-inversion`.
->
-> *   **Standalone Container:** `@venizia/ignis-inversion` (Generic DI)
-> *   **Framework Integration:** `@venizia/ignis` (extends Core DI with Framework Metadata)
->
-> Previously, this module resided in `@venizia/ignis-helpers`. It has now been moved to **Core** (`@venizia/ignis`) to better align with the framework architecture.
-
-## Quick Reference
-
-| Concept | Description |
-|---------|-------------|
-| **Container** | Central registry for services/dependencies (Application extends Container) |
-| **Binding** | Register class/value with container under a key |
-| **Injection** | Request dependency from container using `@inject` decorator |
-| **MetadataRegistry** | Stores decorator metadata for DI and routing |
-
-### Binding Methods
-
-| Method | Purpose | Default Key |
-|--------|---------|-------------|
-| `app.service(MyService, opts?)` | Bind service | `services.MyService` |
-| `app.controller(MyController, opts?)` | Bind controller | `controllers.MyController` |
-| `app.repository(MyRepo, opts?)` | Bind repository | `repositories.MyRepo` |
-| `app.component(MyComponent, opts?)` | Bind component | `components.MyComponent` |
-| `app.dataSource(MyDS, opts?)` | Bind datasource | `datasources.MyDS` |
-| `bind().toClass()` | Custom class binding | `bind({ key: 'MyClass' }).toClass(MyClass)` |
-| `bind().toValue()` | Bind constant value | `bind({ key: 'API_KEY' }).toValue('secret')` |
-
-All registration methods accept an optional `opts` parameter to customize the binding key:
-
-```typescript
-app.controller(UserController, {
-  binding: { namespace: 'controllers', key: 'CustomUserController' }
-});
-```
-
-### Binding Scopes
-
-| Scope | Behavior |
-|-------|----------|
-| `BindingScopes.TRANSIENT` | New instance each request (default) |
-| `BindingScopes.SINGLETON` | Single instance, reused |
-
-### Injection Styles
-
-| Style | When to Use |
-|-------|-------------|
-| **Constructor Injection** | Recommended - explicit, available at instantiation |
-| **Property Injection** | Alternative - inject as class property |
-
-## Binding Dependencies
-
-Before a dependency can be injected, it must be bound to the container. The `Application` class provides helper methods for binding common resource types:
-
--   `app.component(MyComponent, opts?)`
--   `app.controller(MyController, opts?)`
--   `app.service(MyService, opts?)`
--   `app.repository(MyRepository, opts?)`
--   `app.dataSource(MyDataSource, opts?)`
-
-These methods automatically create a binding for the class with a conventional key (e.g., `services.MyService`). Use the optional `opts` parameter to customize binding keys when needed.
-
-### Advanced Binding
-
-For more advanced use cases, you can create custom bindings using the `bind` method on the container.
-
-```typescript
-// In your application class or a component's binding() method
-
-// Bind a class
-this.bind<MyCustomClass>({ key: 'MyCustomClass' }).toClass(MyCustomClass);
-
-// Bind a constant value
-this.bind<string>({ key: 'API_KEY' }).toValue('my-secret-api-key');
-
-// Bind a provider (for complex creation logic)
-this.bind<DatabaseConnection>({ key: 'DatabaseConnection' }).toProvider(() => {
-  return new DatabaseConnection(process.env.DATABASE_URL);
-});
-```
-
-### Binding Scopes
-
-You can control the lifecycle of a bound dependency using scopes:
-
--   `BindingScopes.TRANSIENT` (default): A new instance is created every time the dependency is requested.
--   `BindingScopes.SINGLETON`: A single instance is created and reused for all subsequent requests.
-
-```typescript
-this.bind<MySingletonService>({ key: 'services.MySingletonService' })
-  .toClass(MySingletonService)
-  .setScope(BindingScopes.SINGLETON);
-```
-
-## Injecting Dependencies
-
-`Ignis` provides an `@inject` decorator to handle dependency injection. You can use it on constructor parameters or class properties.
-
-### Constructor Injection
-
-This is the recommended way to inject dependencies, as it makes them explicit and ensures they are available when the class is instantiated.
-
-```typescript
-import { BaseController, controller, inject } from '@venizia/ignis';
-import { UserService } from '../services/user.service';
-
-@controller({ path: '/users' })
-export class UserController extends BaseController {
-  constructor(
-    @inject({ key: 'services.UserService' })
-    private _userService: UserService
-  ) {
-    super({ scope: UserController.name, path: '/users' });
-  }
-
-  // ... use this._userService
-}
-```
-
-### Property Injection
-
-You can also inject dependencies as class properties.
-
-```typescript
-import { BaseController, controller, inject } from '@venizia/ignis';
-import { UserService } from '../services/user.service';
-
-@controller({ path: '/users' })
-export class UserController extends BaseController {
-  @inject({ key: 'services.UserService' })
-  private _userService: UserService;
-
-  constructor() {
-    super({ scope: UserController.name, path: '/users' });
-  }
-
-  // ... use this._userService
-}
-```
-
-## `MetadataRegistry`
-
-The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a singleton class responsible for storing and retrieving all the metadata attached by decorators like `@inject`, `@controller`, `@get`, etc.
-
--   **Base File:** `packages/inversion/src/registry.ts` (core MetadataRegistry)
--   **Extended File:** `packages/core/src/helpers/inversion/registry.ts` (with framework metadata)
-
-### Role in DI
-
--   When you use a decorator (e.g., `@inject`), it calls a method on the `MetadataRegistry.getInstance()` to store information about the injection (like the binding key and target property/parameter).
--   When the `Container` instantiates a class, it queries the `MetadataRegistry` to find out which dependencies need to be injected and where.
-
-You typically won't interact with the `MetadataRegistry` directly, but it's the underlying mechanism that makes the decorator-based DI and routing systems work seamlessly.
-
-## See Also
-
-- **Related Concepts:**
-  - [Dependency Injection Guide](/guides/core-concepts/dependency-injection) - DI fundamentals
-  - [Application](/guides/core-concepts/application/) - Application extends Container
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-
-- **References:**
-  - [Dependency Injection API](/references/base/dependency-injection) - Complete DI reference
-  - [Glossary](/guides/reference/glossary#dependency-injection-di) - DI concepts
-
-- **Tutorials:**
-  - [Testing](/guides/tutorials/testing) - Unit testing with DI
-
-- **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns) - DI patterns