@venizia/ignis-docs 0.0.5 → 0.0.6-1

package/wiki/references/helpers/testing.md

@@ -1,133 +0,0 @@
-# Testing Helper
-
-Structured test framework integrating with Node.js's native `node:test` module.
-
-## Quick Reference
-
-| Component | Purpose |
-|-----------|---------|
-| **TestPlan** | Organizes test suite with lifecycle hooks and shared context |
-| **TestCase** | Single runnable test unit with metadata |
-| **TestCaseHandler** | Encapsulates test execution and validation logic |
-| **TestDescribe** | Runs test plans |
-
-### Test Lifecycle Hooks
-
-| Hook | When | Purpose |
-|------|------|---------|
-| `before` | Before all tests | Setup (e.g., start server, seed DB) |
-| `after` | After all tests | Cleanup (e.g., close connections) |
-| `beforeEach` | Before each test | Reset state |
-| `afterEach` | After each test | Cleanup per test |
-
-### TestCaseDecisions
-
-| Decision | Meaning |
-|----------|---------|
-| `SUCCESS` | Test passed |
-| `FAIL` | Test failed |
-| `SKIP` | Test skipped |
-
-## Creating a Test Plan
-
-A test plan is the main entry point for a test suite. You define the scope, hooks, and test cases within the plan.
-
-```typescript
-// __tests__/my-feature.test.ts
-import { TestPlan, TestDescribe, TestCase, TestCaseHandler, TestCaseDecisions } from '@venizia/ignis';
-
-// 1. Define a Test Case Handler
-class MyTestHandler extends TestCaseHandler {
-  async execute() {
-    // Perform the action to be tested
-    return { result: 'some-value' };
-  }
-
-  getValidator() {
-    return (opts: { result: string }) => {
-      if (opts.result === 'some-value') {
-        return TestCaseDecisions.SUCCESS;
-      }
-      return TestCaseDecisions.FAIL;
-    };
-  }
-}
-
-// 2. Create a Test Plan
-const myTestPlan = TestPlan.newInstance({
-  scope: 'My Feature',
-  hooks: {
-    before: async () => console.log('Starting My Feature tests...'),
-    after: async () => console.log('Finished My Feature tests.'),
-  },
-  testCases: [
-    TestCase.withOptions({
-      code: 'MY-FEATURE-001',
-      description: 'It should return the correct value',
-      expectation: 'The result should be "some-value"',
-      handler: new MyTestHandler({ context: {} as any }), // Context is provided by the plan
-    }),
-  ],
-});
-
-// 3. Run the Test Plan
-TestDescribe.withTestPlan({ testPlan: myTestPlan }).run();
-```
-
-## Shared Context
-
-The `TestPlan` provides a `context` that can be used to share data between test cases and hooks. This is useful for setup tasks like creating a JWT token or seeding a database.
-
-```typescript
-// __tests__/auth.test.ts
-import { TestPlan, TestDescribe, TestCase, TestCaseHandler, ITestContext } from '@venizia/ignis';
-
-// A handler that uses the context
-class SecureApiHandler extends TestCaseHandler<{ token: string }> {
-  async execute() {
-    const token = this.context.getSync<{ token: string }>({ key: 'token' });
-    const response = await app.request('/api/secure-data', {
-      headers: { Authorization: `Bearer ${token}` },
-    });
-    return { status: response.status };
-  }
-  // ... validator
-}
-
-const authTestPlan = TestPlan.newInstance({
-  scope: 'Authentication',
-  hooks: {
-    before: async (context: ITestContext<{ token: string }>) => {
-      // Generate a token and bind it to the context
-      const token = await generateTestToken();
-      context.bind({ key: 'token', value: token });
-    },
-  },
-  testCases: [
-    TestCase.withOptions({
-      // ...
-      handler: new SecureApiHandler({ context: {} as any }),
-    }),
-  ],
-});
-
-TestDescribe.withTestPlan({ testPlan: authTestPlan }).run();
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Dependency Injection](/guides/core-concepts/dependency-injection) - Testing with DI
-  - [Application](/guides/core-concepts/application/) - Application lifecycle in tests
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-
-- **External Resources:**
-  - [Node.js Test Runner](https://nodejs.org/api/test.html) - Native test module
-
-- **Tutorials:**
-  - [Testing Guide](/guides/tutorials/testing) - Complete testing tutorial
-
-- **Best Practices:**
-  - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Debugging tests

package/wiki/references/helpers/types.md

@@ -1,167 +0,0 @@
-# Common Types
-
-Utility types and helper functions for common TypeScript patterns.
-
-## Value Resolution Types
-
-Types for lazy/deferred value resolution patterns.
-
-### TResolver / TAsyncResolver
-
-```typescript
-type TResolver<T> = (...args: any[]) => T;
-type TAsyncResolver<T> = (...args: any[]) => T | Promise<T>;
-```
-
-Function types that resolve to a value. `TAsyncResolver` supports async functions.
-
-### TValueOrResolver / TValueOrAsyncResolver
-
-```typescript
-type TValueOrResolver<T> = T | TResolver<T>;
-type TValueOrAsyncResolver<T> = T | TAsyncResolver<T>;
-```
-
-Union types allowing either a direct value or a resolver function.
-
-**Usage:**
-
-```typescript
-import { TValueOrAsyncResolver, resolveValueAsync } from '@venizia/ignis-helpers';
-
-interface DatabaseConfig {
-  host: string;
-  port: number;
-}
-
-type ConfigOption = TValueOrAsyncResolver<DatabaseConfig>;
-
-// Direct value
-const config1: ConfigOption = { host: 'localhost', port: 5432 };
-
-// Sync resolver
-const config2: ConfigOption = () => ({ host: 'localhost', port: 5432 });
-
-// Async resolver
-const config3: ConfigOption = async () => {
-  const config = await fetchConfigFromVault();
-  return config;
-};
-
-// Resolve any of the above
-const resolved = await resolveValueAsync(config3);
-```
-
-### resolveValue / resolveValueAsync
-
-```typescript
-const resolveValue: <T>(valueOrResolver: TValueOrResolver<T>) => T;
-const resolveValueAsync: <T>(valueOrResolver: TValueOrAsyncResolver<T>) => Promise<T>;
-```
-
-Helper functions to resolve lazy values. They handle:
-- **Direct values**: returned as-is
-- **Class constructors**: returned as-is (not invoked)
-- **Resolver functions**: invoked and result returned
-
-## Nullable Types
-
-### TNullable
-
-```typescript
-type TNullable<T> = T | undefined | null;
-```
-
-Makes a type nullable (can be `undefined` or `null`).
-
-### ValueOrPromise
-
-```typescript
-type ValueOrPromise<T> = T | Promise<T>;
-```
-
-A value that may or may not be wrapped in a Promise.
-
-## Class Types
-
-### TConstructor / TAbstractConstructor
-
-```typescript
-type TConstructor<T> = new (...args: any[]) => T;
-type TAbstractConstructor<T> = abstract new (...args: any[]) => T;
-```
-
-Types representing class constructors.
-
-### TClass / TAbstractClass
-
-```typescript
-type TClass<T> = TConstructor<T> & { [property: string]: any };
-type TAbstractClass<T> = TAbstractConstructor<T> & { [property: string]: any };
-```
-
-Class types with static properties.
-
-### TMixinTarget / TAbstractMixinTarget
-
-```typescript
-type TMixinTarget<T> = TConstructor<{ [P in keyof T]: T[P] }>;
-type TAbstractMixinTarget<T> = TAbstractConstructor<{ [P in keyof T]: T[P] }>;
-```
-
-Types for mixin pattern targets.
-
-## Object Utility Types
-
-### ValueOf
-
-```typescript
-type ValueOf<T> = T[keyof T];
-```
-
-Extracts the value types from an object type.
-
-### ValueOptional / ValueOptionalExcept
-
-```typescript
-type ValueOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
-type ValueOptionalExcept<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>>;
-```
-
-Make specific keys optional while keeping others required, or vice versa.
-
-### TPrettify
-
-```typescript
-type TPrettify<T> = { [K in keyof T]: T[K] } & {};
-```
-
-Flattens intersection types for better IDE display.
-
-## Const Value Types
-
-### TStringConstValue / TNumberConstValue / TConstValue
-
-```typescript
-type TStringConstValue<T extends TClass<any>> = Extract<ValueOf<T>, string>;
-type TNumberConstValue<T extends TClass<any>> = Extract<ValueOf<T>, number>;
-type TConstValue<T extends TClass<any>> = Extract<ValueOf<T>, string | number>;
-```
-
-Extract constant value types from a class.
-
-## See Also
-
-- **Related Concepts:**
-  - [Dependency Injection](/guides/core-concepts/dependency-injection) - DI types and patterns
-  - [Repositories](/guides/core-concepts/persistent/repositories) - Repository mixins use these types
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-
-- **References:**
-  - [Repository Mixins](/references/base/repositories/mixins) - Uses mixin types
-  - [Utilities Index](/references/utilities/index) - Type utilities
-
-- **Best Practices:**
-  - [Architectural Patterns](/best-practices/architectural-patterns) - TypeScript patterns

package/wiki/references/helpers/uid.md

@@ -1,167 +0,0 @@
-# UID Helper
-
-Snowflake ID generator with Base62 encoding for generating unique, time-sortable IDs suitable for distributed systems.
-
-## Quick Reference
-
-| Class | Purpose | Key Features |
-|-------|---------|--------------|
-| **SnowflakeConfig** | Configuration constants | Bit structure, limits, defaults |
-| **SnowflakeUidHelper** | ID generation | Snowflake IDs, Base62 encoding/decoding |
-
-### Snowflake ID Structure (70 bits)
-
-| Component | Bits | Range | Purpose |
-|-----------|------|-------|---------|
-| Timestamp | 48 | ~8,919 years | Time since epoch |
-| Worker ID | 10 | 0-1023 | Unique worker identifier |
-| Sequence | 12 | 0-4095 | IDs per millisecond |
-
-### Key Specifications
-
-| Spec | Value |
-|------|-------|
-| Base62 Output | 10-12 characters |
-| Throughput | 4,096,000 IDs/second/worker |
-| Max Workers | 1024 |
-| Lifespan | Until ~10,944 AD |
-| Default Epoch | 2025-01-01 00:00:00 UTC |
-
-## Basic Usage
-
-### Creating an Instance
-
-```typescript
-import { SnowflakeUidHelper, SnowflakeConfig } from '@venizia/ignis-helpers';
-
-// Use defaults (workerId: 199, epoch: 2025-01-01 00:00:00 UTC)
-const generator = new SnowflakeUidHelper();
-
-// Or with custom values
-const customGenerator = new SnowflakeUidHelper({
-  workerId: 123,
-  epoch: BigInt(1735689600000),
-});
-```
-
-### Generating IDs
-
-```typescript
-// Generate Base62 encoded ID (recommended for most use cases)
-const id = generator.nextId();
-// => e.g., "9du1sJXO88"
-
-// Generate raw Snowflake ID as bigint
-const snowflakeId = generator.nextSnowflake();
-// => e.g., 130546360012247045n
-```
-
-## Base62 Encoding/Decoding
-
-### Encode a BigInt to Base62
-
-```typescript
-const encoded = generator.encodeBase62(130546360012247045n);
-// => "9du1sJXO88"
-```
-
-### Decode Base62 to BigInt
-
-```typescript
-const decoded = generator.decodeBase62("9du1sJXO88");
-// => 130546360012247045n
-```
-
-## Parsing and Extracting Components
-
-### Parse a Base62 ID
-
-```typescript
-const parsed = generator.parseId("9du1sJXO88");
-// => {
-//   raw: 130546360012247045n,
-//   timestamp: Date,
-//   workerId: 199,
-//   sequence: 0
-// }
-```
-
-### Extract Individual Components
-
-```typescript
-const snowflakeId = generator.nextSnowflake();
-
-// Extract timestamp
-const timestamp = generator.extractTimestamp(snowflakeId);
-// => Date object
-
-// Extract worker ID
-const workerId = generator.extractWorkerId(snowflakeId);
-// => 199
-
-// Extract sequence
-const sequence = generator.extractSequence(snowflakeId);
-// => 0-4095
-```
-
-## Configuration
-
-### SnowflakeConfig Constants
-
-```typescript
-import { SnowflakeConfig } from '@venizia/ignis-helpers';
-
-SnowflakeConfig.DEFAULT_EPOCH      // BigInt(1735689600000) - 2025-01-01 00:00:00 UTC
-SnowflakeConfig.MAX_WORKER_ID      // 1023n
-SnowflakeConfig.MAX_SEQUENCE       // 4095n
-SnowflakeConfig.TIMESTAMP_SHIFT    // 22n
-SnowflakeConfig.WORKER_ID_SHIFT    // 12n
-```
-
-### Constructor Options
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `workerId` | `number` | `199` | Worker ID (0-1023) |
-| `epoch` | `bigint` | `SnowflakeConfig.DEFAULT_EPOCH` | Custom epoch timestamp in milliseconds |
-
-## Error Handling
-
-The helper throws errors in these cases:
-
-- **Invalid Worker ID**: Worker ID outside 0-1023 range
-- **Invalid Epoch**: Epoch is zero, negative, or in the future
-- **Clock Backward**: System clock moved backward by more than 100ms
-- **Invalid Base62**: Decoding a string with invalid characters
-
-```typescript
-try {
-  const generator = new SnowflakeUidHelper({ workerId: 2000 }); // Invalid
-} catch (error) {
-  // Worker ID must be between 0 and 1023
-}
-```
-
-## Best Practices
-
-1. **Use unique worker IDs** in distributed systems to prevent ID collisions
-2. **Keep epoch consistent** across all instances to ensure proper ID ordering
-3. **Use `nextId()`** for most cases (returns compact Base62 string)
-4. **Use `nextSnowflake()`** when you need the raw bigint for arithmetic operations
-
-## See Also
-
-- **Related Concepts:**
-  - [Models](/guides/core-concepts/persistent/models) - Using UIDs as primary keys
-  - [Services](/guides/core-concepts/services) - Generating unique IDs
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Crypto Helper](./crypto) - For cryptographic random values
-
-- **External Resources:**
-  - [Snowflake ID](https://en.wikipedia.org/wiki/Snowflake_ID) - Snowflake algorithm explained
-  - [Base62 Encoding](https://en.wikipedia.org/wiki/Base62) - Base62 encoding overview
-
-- **Best Practices:**
-  - [Data Modeling](/best-practices/data-modeling) - ID generation strategies

package/wiki/references/helpers/worker-thread.md

@@ -1,178 +0,0 @@
-# Worker Thread Helper
-
-Manage Node.js `worker_threads` for concurrent CPU-bound task execution.
-
-## Quick Reference
-
-| Helper | Purpose |
-|--------|---------|
-| **WorkerPoolHelper** | Singleton managing pool of workers (matches CPU cores) |
-| **BaseWorkerHelper** | Create and manage single worker thread lifecycle |
-| **BaseWorkerBusHelper** | Two-way communication via `MessagePort` |
-
-### Use Cases
-
-- CPU-intensive calculations
-- Large data processing
-- Parallel computations
-- Video/image processing
-
-### Worker Communication
-
-| Pattern | Complexity | Use When |
-|---------|------------|----------|
-| **Simple (parentPort)** | Low | One-way or basic messaging |
-| **WorkerBus (MessageChannel)** | High | Complex two-way communication |
-
-### WorkerPoolHelper Methods
-
-| Method | Purpose |
-|--------|---------|
-| `getInstance()` | Get singleton instance |
-| `register({ key, worker })` | Add worker to pool |
-| `unregister({ key })` | Remove and terminate worker |
-
-## `WorkerPoolHelper`
-
-The `WorkerPoolHelper` is a singleton that manages the creation, registration, and termination of worker threads.
-
-### Usage
-
-```typescript
-import { WorkerPoolHelper, BaseWorkerHelper } from '@venizia/ignis';
-
-const workerPool = WorkerPoolHelper.getInstance();
-
-// Create a new worker
-const myWorker = new BaseWorkerHelper({
-  identifier: 'my-cpu-intensive-task',
-  path: './path/to/my-worker.js',
-  options: {
-    workerData: { some: 'data' },
-  },
-});
-
-// Register the worker with the pool
-workerPool.register({ key: 'my-worker-1', worker: myWorker });
-
-// Later, to terminate the worker
-workerPool.unregister({ key: 'my-worker-1' });
-```
-
-## Creating a Worker
-
-You can create a worker from the main thread that executes a separate script file.
-
-### Main Thread (`main.ts`)
-
-```typescript
-import { BaseWorkerHelper } from '@venizia/ignis';
-import path from 'node:path';
-
-const worker = new BaseWorkerHelper({
-  identifier: 'my-worker',
-  path: path.resolve(__dirname, './worker.ts'), // Path to the worker script
-  options: {
-    workerData: { message: 'Hello from main thread!' },
-  },
-  eventHandlers: {
-    onMessage: ({ message }) => {
-      console.log('Received message from worker:', message);
-    },
-    onError: ({ error }) => {
-      console.error('Worker error:', error);
-    },
-  },
-});
-```
-
-### Worker Thread (`worker.ts`)
-
-Inside the worker script, you can perform CPU-intensive tasks and communicate back to the main thread.
-
-```typescript
-import { parentPort, workerData } from 'node:worker_threads';
-
-console.log('Worker started with data:', workerData);
-
-// Perform a CPU-intensive task
-const result = performHeavyCalculation();
-
-// Send the result back to the main thread
-parentPort?.postMessage({ result });
-```
-
-## `WorkerBus` for Two-Way Communication
-
-For more complex scenarios requiring two-way communication, you can use the `WorkerBus` helpers.
-
-### Main Thread (`main.ts`)
-
-```typescript
-// ... (in main thread)
-import { MessageChannel } from 'node:worker_threads';
-import { BaseWorkerBusHelper, ... } from '@venizia/ignis';
-
-const { port1, port2 } = new MessageChannel();
-
-const worker = new BaseWorkerHelper({
-  // ...
-  options: {
-    workerData: { port: port2 }, // Pass one port to the worker
-    transferList: [port2],      // Transfer ownership of the port
-  },
-});
-
-const mainThreadBus = new BaseWorkerBusHelper({
-  scope: 'main-bus',
-  port: port1,
-  busHandler: new BaseWorkerMessageBusHandlerHelper({
-    scope: 'main-bus-handler',
-    onMessage: ({ message }) => {
-      console.log('Main thread received:', message);
-    },
-  }),
-});
-
-mainThreadBus.postMessage({ message: { command: 'start-work' } });
-```
-
-### Worker Thread (`worker.ts`)
-
-```typescript
-// ... (in worker thread)
-import { workerData } from 'node:worker_threads';
-import { BaseWorkerBusHelper, ... } from '@venizia/ignis';
-
-const { port } = workerData;
-
-const workerBus = new BaseWorkerBusHelper({
-  scope: 'worker-bus',
-  port: port,
-  busHandler: new BaseWorkerMessageBusHandlerHelper({
-    scope: 'worker-bus-handler',
-    onMessage: ({ message }) => {
-      console.log('Worker received:', message);
-      if (message.command === 'start-work') {
-        workerBus.postMessage({ message: { status: 'work-done' } });
-      }
-    },
-  }),
-});
-```
-
-## See Also
-
-- **Related Concepts:**
-  - [Services](/guides/core-concepts/services) - CPU-intensive tasks in services
-
-- **Other Helpers:**
-  - [Helpers Index](./index) - All available helpers
-  - [Queue Helper](./queue) - For I/O-bound background tasks
-
-- **External Resources:**
-  - [Node.js Worker Threads](https://nodejs.org/api/worker_threads.html) - Official worker_threads API
-  - [MessageChannel](https://nodejs.org/api/worker_threads.html#class-messagechannel) - Two-way communication
-
-- **Best Practices:**
-  - [Performance Optimization](/best-practices/performance-optimization) - Worker thread strategies