@venizia/ignis-docs 0.0.1-1

package/wiki/references/src-details/dev-configs.md

@@ -0,0 +1,302 @@
+# Package: `@venizia/dev-configs`
+
+## Overview
+
+The `@venizia/dev-configs` package provides centralized, shared development configurations for all packages in the Venizia/Ignis monorepo. This ensures consistent code style, linting rules, and TypeScript configurations across the entire project.
+
+## Package Information
+
+| Property | Value |
+|----------|-------|
+| **Package Name** | `@venizia/dev-configs` |
+| **Location** | `packages/dev-configs/` |
+| **Purpose** | Centralized development configurations |
+| **Dependencies** | `@minimaltech/eslint-node` |
+
+## Exports
+
+| Export Path | Type | Description |
+|-------------|------|-------------|
+| `@venizia/dev-configs` | Module | Named exports: `eslintConfigs`, `prettierConfigs` |
+| `@venizia/dev-configs/tsconfig.base.json` | JSON | Base TypeScript configuration |
+| `@venizia/dev-configs/tsconfig.common.json` | JSON | Common TypeScript config for packages |
+
+### Named Exports
+
+```typescript
+import { eslintConfigs, prettierConfigs } from '@venizia/dev-configs';
+```
+
+- **`eslintConfigs`**: `Linter.Config[]` - ESLint flat config array
+- **`prettierConfigs`**: `Config` - Prettier configuration object
+
+---
+
+## ESLint Configuration
+
+### Usage
+
+Create an `eslint.config.mjs` file in your package:
+
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default eslintConfigs;
+```
+
+### Extending the Config
+
+To add package-specific rules:
+
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+const configs = [
+  ...eslintConfigs,
+  {
+    // Add custom ignores
+    ignores: ['custom-folder/**'],
+  },
+  {
+    // Add custom rules
+    rules: {
+      'no-console': 'warn',
+    },
+  },
+];
+
+export default configs;
+```
+
+### Included Rules
+
+| Rule | Setting | Description |
+|------|---------|-------------|
+| `@typescript-eslint/no-explicit-any` | `off` | Allows `any` type usage |
+| *Base rules* | *inherited* | All rules from `@minimaltech/eslint-node` |
+
+---
+
+## Prettier Configuration
+
+### Usage
+
+Create a `.prettierrc.mjs` file in your package:
+
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default prettierConfigs;
+```
+
+### Configuration Options
+
+| Option | Value | Description |
+|--------|-------|-------------|
+| `bracketSpacing` | `true` | Spaces inside object braces: `{ foo: bar }` |
+| `singleQuote` | `false` | Use double quotes (changed from single) |
+| `printWidth` | `100` | Maximum line width |
+| `tabWidth` | `2` | Spaces per indentation level |
+| `trailingComma` | `'all'` | Trailing commas everywhere possible |
+| `arrowParens` | `'avoid'` | Omit parens for single arrow function params |
+| `semi` | `true` | Add semicolons at statement ends |
+
+### Prettier Ignore
+
+Create a `.prettierignore` file in your package:
+
+```
+dist
+node_modules
+*.log
+.*-audit.json
+```
+
+Recommended ignore patterns:
+- `dist` - Build output
+- `node_modules` - Dependencies
+- `*.log` - Log files
+- `.*-audit.json` - Audit files
+- `coverage` - Test coverage (if applicable)
+- `*.min.js` - Minified files (if applicable)
+
+---
+
+## TypeScript Configuration
+
+### Base Configuration (`tsconfig.base.json`)
+
+The base configuration includes all compiler options suitable for Node.js/Bun TypeScript projects.
+
+#### Usage
+
+```json
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@venizia/dev-configs/tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+#### Compiler Options Summary
+
+| Category | Options |
+|----------|---------|
+| **Target** | ES2022, lib: ES2022 |
+| **Modules** | Node16, resolveJsonModule, esModuleInterop |
+| **Decorators** | experimentalDecorators, emitDecoratorMetadata |
+| **Emit** | declaration, declarationMap, sourceMap |
+| **Strict** | strict (with selective relaxations) |
+| **Performance** | incremental, skipLibCheck |
+
+#### Strict Mode Configuration
+
+| Option | Value | Rationale |
+|--------|-------|-----------|
+| `strict` | `true` | Enable all strict checks |
+| `noImplicitAny` | `false` | Allow implicit any for flexibility |
+| `strictNullChecks` | `true` | Enforce null safety |
+| `strictPropertyInitialization` | `false` | Allow uninitialized properties (for DI) |
+| `useUnknownInCatchVariables` | `false` | Use `any` in catch blocks |
+
+### Common Configuration (`tsconfig.common.json`)
+
+Extends the base config with settings for standard packages:
+
+```json
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@venizia/dev-configs/tsconfig.common.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**Note:** Path-related options (`outDir`, `rootDir`, `baseUrl`, `paths`, `include`, `exclude`) must be defined in each package's tsconfig.json as they are resolved relative to the config file location.
+
+---
+
+## Project Structure
+
+```
+packages/dev-configs/
+├── package.json
+├── tsconfig.json
+├── src/
+│   ├── index.ts          # Re-exports all configs
+│   ├── eslint.ts         # ESLint configuration
+│   └── prettier.ts       # Prettier configuration
+├── tsconfig/
+│   ├── tsconfig.base.json    # Base TypeScript config
+│   └── tsconfig.common.json  # Common package config
+├── prettier/
+│   └── .prettierignore   # Prettier ignore patterns
+├── scripts/
+│   ├── build.sh
+│   ├── clean.sh
+│   └── rebuild.sh
+└── dist/                 # Built output
+    ├── index.js / .d.ts
+    ├── eslint.js / .d.ts
+    └── prettier.js / .d.ts
+```
+
+---
+
+## Integration Guide
+
+### Adding to a New Package
+
+1. Add the dependency to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@venizia/dev-configs": "latest",
+    "eslint": "^9.36.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.3"
+  }
+}
+```
+
+2. Create configuration files:
+
+**`tsconfig.json`:**
+```json
+{
+  "$schema": "http://json.schemastore.org/tsconfig",
+  "extends": "@venizia/dev-configs/tsconfig.common.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+**`eslint.config.mjs`:**
+```javascript
+import { eslintConfigs } from '@venizia/dev-configs';
+
+export default eslintConfigs;
+```
+
+**`.prettierrc.mjs`:**
+```javascript
+import { prettierConfigs } from '@venizia/dev-configs';
+
+export default prettierConfigs;
+```
+
+**`.prettierignore`:**
+```
+dist
+node_modules
+*.log
+.*-audit.json
+```
+
+3. Add lint scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint --report-unused-disable-directives . && prettier \"**/*.{js,ts}\" -l",
+    "lint:fix": "eslint --report-unused-disable-directives . --fix && prettier \"**/*.{js,ts}\" --write"
+  }
+}
+```
+
+---
+
+## Building the Package
+
+```bash
+cd packages/dev-configs
+
+# Build
+bun run build
+
+# Clean
+bun run clean
+
+# Rebuild (clean + build)
+bun run rebuild
+```

package/wiki/references/src-details/docs.md

@@ -0,0 +1,61 @@
+# Package: `@venizia/ignis-docs`
+
+Documentation package housing guides, references, and MCP server for the Ignis framework.
+
+## Quick Reference
+
+**Package:** Documentation built with VitePress + MCP server for external tool integration.
+
+### Main Components
+
+| Component | Technology | Purpose |
+|-----------|------------|---------|
+| **Wiki** | VitePress | Main documentation site (guides + references) |
+| **MCP Server** | Model Context Protocol | External tool documentation discovery |
+
+### Wiki Structure
+
+| Section | Content |
+|---------|---------|
+| `get-started/` | Tutorials, quickstart, core concepts, best practices |
+| `references/` | API reference, components, helpers, base classes |
+| `.vitepress/` | Site configuration and theme |
+
+## Project Structure Overview
+
+Top-level breakdown of the `@packages/docs/` directory:
+
+| Folder     | Purpose                                                                            |
+| :--------- | :--------------------------------------------------------------------------------- |
+| **`mcp`**  | Contains the Model Context Protocol (MCP) server implementation for documentation. |
+| **`wiki`** | The main documentation content, built using VitePress.                             |
+
+---
+
+## Detailed Sections
+
+### `mcp`
+
+This directory contains the implementation of a Model Context Protocol (MCP) server, which allows external tools to discover and read documentation resources.
+
+| File/Folder | Purpose/Key Details                                                                                                                                                              |
+| :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+
+### `wiki`
+
+This directory holds the actual documentation content and the VitePress configuration for building the documentation website.
+
+| File/Folder             | Purpose/Key Details                                                                                                            |
+| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
+| `.vitepress/`           | VitePress-specific configuration and theme files.                                                                              |
+| `.vitepress/config.mts` | The main configuration file for VitePress, defining the documentation's title, description, navigation, and sidebar structure. |
+| `.vitepress/theme/`     | Custom theme files for the VitePress documentation.                                                                            |
+| `get-started/`          | Guides and tutorials for getting started with `Ignis`.                                                                           |
+| `references/`           | Detailed reference documentation for various aspects of the framework.                                                         |
+| `index.md`              | The homepage content for the documentation site.                                                                               |
+| `logo.svg`              | The logo used in the documentation.                                                                                            |
+
+---
+
+This detailed breakdown illustrates the modular and layered design of the `Ignis` framework, emphasizing its extensibility and adherence to robust architectural patterns.

package/wiki/references/src-details/helpers.md

@@ -0,0 +1,211 @@
+# Package: `@venizia/ignis-helpers`
+
+## Helpers Package Directory: Detailed Breakdown
+
+The `@venizia/ignis-helpers` package consolidates a wide array of reusable helper classes and utility functions designed to support various cross-cutting concerns within the Ignis framework. This package promotes modularity by extracting common functionalities into a standalone, easily consumable library.
+
+## Project Structure Overview
+
+Here's the top-level breakdown of the `src` directory within `@packages/helpers/`:
+
+| Folder          | Purpose                                                                                                      |
+| :-------------- | :----------------------------------------------------------------------------------------------------------- |
+| **`__tests__`** | Contains unit and integration tests for the helper utilities.                                                |
+| **`base`**      | Provides foundational helper classes, such as `BaseHelper`.                                                  |
+| **`common`**    | Stores shared constants and types used across the helpers.                                                   |
+| **`helpers`**   | A collection of specialized helper modules for various functionalities (e.g., cron, crypto, network, queue). |
+| **`utilities`** | Contains pure, standalone utility functions for common tasks (e.g., parsing, date manipulation).             |
+
+---
+
+## Detailed Sections
+
+### `__tests__`
+
+This directory is dedicated to the test suite for the `@venizia/ignis-helpers` package.
+
+| File/Folder             | Purpose/Key Details                                                        |
+| :---------------------- | :------------------------------------------------------------------------- |
+| `index.ts`              | Entry point for running tests within the helpers package.                  |
+| `jwt/`                  | Contains test cases specifically for JWT-related helper functions, if any. |
+| `jwt/test-cases/jwt.ts` | Example: defines `TestCase001` to check JWT creation in a helper context.  |
+
+### `base`
+
+This foundational layer provides base classes that other helpers extend.
+
+#### `base/helpers`
+
+| File/Folder | Purpose/Key Details                                                                                                                      |
+| :---------- | :--------------------------------------------------------------------------------------------------------------------------------------- |
+| `base.ts`   | Defines `BaseHelper`, a generic base class providing common utilities like a logger instance and scope management for all other helpers. |
+
+### `common`
+
+This directory holds various shared definitions and constants used throughout the helpers package.
+
+| File/Folder  | Purpose/Key Details                                                                                                                         |
+| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------ |
+| `constants/` | Contains application-wide constants such as `HTTP` methods and status codes, `MimeTypes`, `RuntimeModules` (Bun, Node.js), and `DataTypes`. |
+| `types.ts`   | Contains general TypeScript utility types like `ValueOrPromise`, `AnyObject`, `IClass`, `TMixinTarget`, and `IProvider`.                    |
+
+### `helpers`
+
+This directory groups specialized helper modules by their functionality.
+
+#### `helpers/cron/`
+
+| File/Folder      | Purpose/Key Details                                                          |
+| :--------------- | :--------------------------------------------------------------------------- |
+| `cron.helper.ts` | `CronHelper` for scheduling and managing cron jobs using the `cron` library. |
+
+#### `helpers/crypto/`
+
+Cryptographic utilities.
+
+| File/Folder   | Purpose/Key Details                               |
+| :------------ | :------------------------------------------------ |
+| `algorithms/` | AES and RSA encryption/decryption algorithms.     |
+| `common/`     | Common types and constants for crypto operations. |
+
+#### `helpers/env/`
+
+| File/Folder  | Purpose/Key Details                                                      |
+| :----------- | :----------------------------------------------------------------------- |
+| `app-env.ts` | `ApplicationEnvironment` for structured access to environment variables. |
+
+#### `helpers/error/`
+
+| File/Folder    | Purpose/Key Details                                       |
+| :------------- | :-------------------------------------------------------- |
+| `app-error.ts` | `ApplicationError` class for standardized error handling. |
+
+#### `helpers/inversion/`
+
+Application-enhanced Dependency Injection (DI) module that extends `@venizia/ignis-inversion`.
+
+> **Note:** The core DI functionality (Container, Binding, MetadataRegistry base classes) has been extracted to the standalone `@venizia/ignis-inversion` package. This module extends and re-exports that functionality with application-specific enhancements.
+
+| File/Folder    | Purpose/Key Details                                                                                           |
+| :------------- | :------------------------------------------------------------------------------------------------------------ |
+| `container.ts` | Extended `Container` class with `ApplicationLogger` integration.                                              |
+| `registry.ts`  | Extended `MetadataRegistry` with framework-specific metadata (controllers, models, repositories, datasources).|
+| `common/keys.ts`| Framework-specific `MetadataKeys` (CONTROLLER, MODEL, REPOSITORY, etc.) merged with base keys.               |
+| `common/types.ts`| Framework-specific interfaces (`IControllerMetadata`, `IModelMetadata`, `IRepositoryMetadata`, etc.).        |
+| `index.ts`     | Re-exports core classes from `@venizia/ignis-inversion` plus application extensions.                              |
+
+**Re-exported from `@venizia/ignis-inversion`:**
+- `Binding`, `BindingKeys`, `BindingScopes`, `BindingValueTypes`
+
+**Application-specific additions:**
+- `Container` with `ApplicationLogger` integration
+- `MetadataRegistry` with `setControllerMetadata`, `setModelMetadata`, `setRepositoryMetadata`, etc.
+- Framework metadata interfaces for controllers, models, repositories, and data sources
+
+For standalone DI usage without framework features, import directly from `@venizia/ignis-inversion`.
+
+#### `helpers/logger/`
+
+Logging solution built on Winston.
+
+| File/Folder                     | Purpose/Key Details                                                    |
+| :------------------------------ | :--------------------------------------------------------------------- |
+| `application-logger.ts`         | `ApplicationLogger` for structured logging with scopes.                |
+| `default-logger.ts`             | Default Winston logger configuration with console and file transports. |
+| `factory.ts`                    | `LoggerFactory` for obtaining logger instances.                        |
+| `transports/dgram.transport.ts` | UDP transport for log aggregation.                                     |
+| `types.ts`                      | Log level definitions.                                                 |
+
+#### `helpers/network/`
+
+Utilities for network communication.
+
+| File/Folder     | Purpose/Key Details                                                             |
+| :-------------- | :------------------------------------------------------------------------------ |
+| `http-request/` | HTTP client implementations (`AxiosNetworkRequest`, `NodeFetchNetworkRequest`). |
+| `tcp-socket/`   | TCP and TLS socket client/server helpers.                                       |
+| `udp-socket/`   | UDP client helper.                                                              |
+
+#### `helpers/queue/`
+
+Message queuing solutions.
+
+| File/Folder | Purpose/Key Details                             |
+| :---------- | :---------------------------------------------- |
+| `bullmq/`   | `BullMQHelper` for Redis-backed message queues. |
+| `mqtt/`     | `MQTTClientHelper` for MQTT broker interaction. |
+| `internal/` | `QueueHelper` for simple in-memory queues.      |
+| `common/`   | Common types for queue operations.              |
+
+#### `helpers/redis/`
+
+Redis client helpers.
+
+| File/Folder         | Purpose/Key Details                                                |
+| :------------------ | :----------------------------------------------------------------- |
+| `cluster.helper.ts` | `RedisClusterHelper` for Redis cluster connections.                |
+| `default.helper.ts` | `DefaultRedisHelper` providing a unified API for Redis operations. |
+| `single.helper.ts`  | `RedisHelper` for single Redis instance connections.               |
+| `types.ts`          | Interfaces and types for Redis helpers.                            |
+
+#### `helpers/socket-io/`
+
+Socket.IO client and server helpers.
+
+| File/Folder | Purpose/Key Details                                           |
+| :---------- | :------------------------------------------------------------ |
+| `client/`   | `SocketIOClientHelper` for client-side Socket.IO connections. |
+| `server/`   | `SocketIOServerHelper` for server-side Socket.IO management.  |
+| `common/`   | Common types and constants for Socket.IO.                     |
+
+#### `helpers/storage/`
+
+Storage utilities.
+
+| File/Folder  | Purpose/Key Details                                    |
+| :----------- | :----------------------------------------------------- |
+| `in-memory/` | `MemoryStorageHelper` for in-memory key-value storage. |
+| `minio/`     | `MinioHelper` for S3-compatible object storage.        |
+
+#### `helpers/testing/`
+
+Framework for writing and executing tests using `node:test`.
+
+| File/Folder         | Purpose/Key Details                                         |
+| :------------------ | :---------------------------------------------------------- |
+| `base-test-plan.ts` | Abstract base for test plans.                               |
+| `common/`           | Common types and constants for testing utilities.           |
+| `describe.ts`       | `TestDescribe` integrates with `node:test` lifecycle hooks. |
+| `test-case.ts`      | Defines individual test cases.                              |
+| `test-handler.ts`   | Base class for test case handlers.                          |
+| `test-plan.ts`      | `TestPlan` for organizing test suites.                      |
+
+#### `helpers/worker-thread/`
+
+Utilities for Node.js worker threads.
+
+| File/Folder      | Purpose/Key Details                                         |
+| :--------------- | :---------------------------------------------------------- |
+| `base.ts`        | Base classes for workers and worker threads.                |
+| `types.ts`       | Interfaces and types for worker threads.                    |
+| `worker-bus.ts`  | Helpers for inter-thread communication using `MessagePort`. |
+| `worker-pool.ts` | `WorkerPoolHelper` for managing a pool of worker threads.   |
+
+### `utilities`
+
+This directory contains pure, standalone utility functions that perform common, stateless operations.
+
+| File/Folder              | Purpose/Key Details                                                                                                                                                                                                                                                     |
+| :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `crypto.utility.ts`      | Provides a `hash()` function for cryptographic hashing (SHA256, MD5).                                                                                                                                                                                                   |
+| `date.utility.ts`        | Date and time manipulation functions (`dayjs` integration, `sleep`, `isWeekday`, `getDateTz`, `hrTime`).                                                                                                                                                                |
+| `module.utility.ts`      | `validateModule()` to check for module existence at runtime.                                                                                                                                                                                                            |
+| `parse.utility.ts`       | Functions for type checking (`isInt`, `isFloat`), type conversion (`int`, `float`, `toBoolean`), string/object transformation (`toCamel`, `keysToCamel`), array transformations (`parseArrayToRecordWithKey`, `parseArrayToMapWithKey`), and `getUID()` for unique IDs. |
+| `performance.utility.ts` | Utilities for measuring code execution time (`executeWithPerformanceMeasure`, `getPerformanceCheckpoint`, `getExecutedPerformance`).                                                                                                                                    |
+| `promise.utility.ts`     | Helper functions for Promises (`executePromiseWithLimit`, `isPromiseLike`, `transformValueOrPromise`, `getDeepProperty`).                                                                                                                                               |
+| `request.utility.ts`     | Utilities for handling HTTP request data, such as `parseMultipartBody` for multipart form data.                                                                                                                                                                         |
+| `schema.utility.ts`      | Helper functions and predefined schemas for `zod` and `@hono/zod-openapi` (`jsonContent`, `jsonResponse`, `requiredString`, `AnyObjectSchema`, `IdParamsSchema`, `UUIDParamsSchema`).                                                                                   |
+
+---
+
+This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.