@venizia/ignis-docs 0.0.3 → 0.0.4-1

package/wiki/references/helpers/cron.md

@@ -92,3 +92,17 @@ Creates a new `CronHelper` instance with the same configuration but a new `cronT
 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

@@ -115,3 +115,18 @@ const sha256Hash = hash('some text', {
   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

@@ -65,3 +65,19 @@ APPLICATION_ENV_PREFIX=MY_APP_ENV
 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

@@ -78,3 +78,20 @@ In development mode, the response will include the stack trace and error cause f
   "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/index.md

@@ -19,4 +19,18 @@ Reusable classes and functions providing common functionality - designed for eas
 | [Socket.IO](./socket-io.md) | Real-time communication | Socket.IO client/server helpers |
 | [Storage](./storage.md) | File storage | In-memory, Minio object storage |
 | [Testing](./testing.md) | Test utilities | Test plan runner, base test classes |
+| [UID](./uid.md) | Unique ID generation | Snowflake IDs, Base62 encoding |
 | [Worker Thread](./worker-thread.md) | Worker threads | Node.js worker management |
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Using helpers in service layer
+  - [Controllers](/guides/core-concepts/controllers) - Using helpers in controllers
+
+- **References:**
+  - [Utilities](/references/utilities/) - Pure utility functions
+  - [Components](/references/components/) - Framework components
+
+- **Best Practices:**
+  - [Code Style Standards](/best-practices/code-style-standards) - Helper usage patterns

package/wiki/references/helpers/inversion.md

@@ -111,12 +111,13 @@ import { UserService } from '../services/user.service';
 @controller({ path: '/users' })
 export class UserController extends BaseController {
   constructor(
-    @inject({ key: 'services.UserService' }) private userService: UserService
+    @inject({ key: 'services.UserService' })
+    private _userService: UserService
   ) {
     super({ scope: UserController.name, path: '/users' });
   }
 
-  // ... use this.userService
+  // ... use this._userService
 }
 ```
 
@@ -131,13 +132,13 @@ import { UserService } from '../services/user.service';
 @controller({ path: '/users' })
 export class UserController extends BaseController {
   @inject({ key: 'services.UserService' })
-  private userService: UserService;
+  private _userService: UserService;
 
   constructor() {
     super({ scope: UserController.name, path: '/users' });
   }
 
-  // ... use this.userService
+  // ... use this._userService
 }
 ```
 
@@ -154,3 +155,22 @@ The `MetadataRegistry` is a crucial part of the DI and routing systems. It's a s
 -   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

package/wiki/references/helpers/logger.md

@@ -96,3 +96,22 @@ const myCustomWinstonLogger = defineCustomLogger({
 const myLogger = new Logger({ customLogger: myCustomWinstonLogger });
 myLogger.withScope('CustomScope').info('This is a custom log message.');
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Logging in services
+  - [Controllers](/guides/core-concepts/controllers) - Logging in controllers
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Error Helper](./error) - Error handling utilities
+
+- **References:**
+  - [Request Tracker Component](/references/components/request-tracker) - Request logging
+
+- **External Resources:**
+  - [Winston Documentation](https://github.com/winstonjs/winston) - Winston logging library
+
+- **Best Practices:**
+  - [Troubleshooting Tips](/best-practices/troubleshooting-tips) - Using logs for debugging

package/wiki/references/helpers/network.md

@@ -141,3 +141,14 @@ const udpClient = new NetworkUdpClient({
 
 udpClient.connect();
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Network operations in services
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+
+- **Best Practices:**
+  - [Security Guidelines](/best-practices/security-guidelines) - Network security

package/wiki/references/helpers/queue.md

@@ -129,3 +129,22 @@ const myQueue = new QueueHelper<string>({
 myQueue.enqueue('message 1');
 myQueue.enqueue('message 2');
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Background job processing
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Cron Helper](./cron) - Scheduled tasks
+  - [Redis Helper](./redis) - Redis pub/sub
+
+- **References:**
+  - [Mail Component](/references/components/mail) - Email queue integration
+
+- **External Resources:**
+  - [BullMQ Documentation](https://docs.bullmq.io/) - BullMQ queue library
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Queue optimization

package/wiki/references/helpers/redis.md

@@ -119,3 +119,24 @@ await redisClient.publish({
   payload: { data: 'some important update' },
 });
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Using Redis in services
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Queue Helper](./queue) - BullMQ uses Redis as backend
+
+- **References:**
+  - [DataSources](/references/base/datasources) - Database connections
+
+- **External Resources:**
+  - [ioredis Documentation](https://github.com/redis/ioredis) - Redis client library
+  - [Redis Commands](https://redis.io/commands/) - Redis command reference
+  - [RedisJSON](https://redis.io/docs/stack/json/) - JSON module documentation
+
+- **Best Practices:**
+  - [Performance Optimization](/best-practices/performance-optimization) - Caching strategies
+  - [Security Guidelines](/best-practices/security-guidelines) - Redis security

package/wiki/references/helpers/socket-io.md

@@ -40,14 +40,14 @@ import { SocketIOServerHelper, SocketIOBindingKeys, inject } from '@venizia/igni
 // ... in a service or controller
 
   @inject({ key: SocketIOBindingKeys.SOCKET_IO_INSTANCE })
-  private io: SocketIOServerHelper;
+  private _io: SocketIOServerHelper;
 
-  sendNotification(userId: string, message: string) {
-    this.io.send({
-      destination: userId, // Room or socket ID
+  sendNotification(opts: { userId: string; message: string }) {
+    this._io.send({
+      destination: opts.userId, // Room or socket ID
       payload: {
         topic: 'notification',
-        data: { message },
+        data: { message: opts.message },
       },
     });
   }
@@ -101,3 +101,22 @@ socketClient.subscribe({
   },
 });
 ```
+
+## See Also
+
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - Real-time communication in services
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+  - [Redis Helper](./redis) - For Socket.IO scaling with Redis adapter
+
+- **References:**
+  - [Socket.IO Component](/references/components/socket-io) - Full component setup
+
+- **External Resources:**
+  - [Socket.IO Documentation](https://socket.io/docs/) - Official Socket.IO docs
+  - [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/) - Scaling guide
+
+- **Tutorials:**
+  - [Real-Time Chat Application](/guides/tutorials/realtime-chat) - Socket.IO tutorial

package/wiki/references/helpers/storage.md

@@ -128,7 +128,6 @@ const allKeys = memoryStore.keys();
 memoryStore.clear();
 ```
 
----
 
 ## `DiskHelper`
 
@@ -345,7 +344,6 @@ const cloudStorage = new MinioHelper({ /* ... */ });
 const localStorage = new DiskHelper({ basePath: './system-files' });
 ```
 
----
 
 ## `MinioHelper`
 
@@ -443,7 +441,6 @@ await minioClient.removeObject({ bucket: 'my-bucket', name: 'my-file.txt' });
 await minioClient.removeObjects({ bucket: 'my-bucket', names: ['file1.txt', 'file2.txt'] });
 ```
 
----
 
 ## DiskHelper vs MinioHelper Comparison
 
@@ -495,7 +492,6 @@ const systemStorage = new DiskHelper({ basePath: './system' });
 const tempStorage = new DiskHelper({ basePath: './temp' });
 ```
 
----
 
 ## Common Patterns
 
@@ -573,15 +569,27 @@ const storage = new ResilientStorage(
 );
 ```
 
----
 
-## Related Documentation
+## See Also
 
-- [Static Asset Component](../components/static-asset.md) - Uses storage helpers
-- [Request Utilities](../utilities/request.md) - `parseMultipartBody`
-- [Base Helpers](./index.md) - Helper architecture
+- **Related Concepts:**
+  - [Services](/guides/core-concepts/services) - File storage in services
+
+- **Other Helpers:**
+  - [Helpers Index](./index) - All available helpers
+
+- **References:**
+  - [Static Asset Component](/references/components/static-asset) - Serving stored files
+  - [Request Utilities](/references/utilities/request) - `parseMultipartBody` for file uploads
+
+- **External Resources:**
+  - [MinIO Documentation](https://min.io/docs/minio/linux/index.html) - MinIO object storage
+  - [AWS S3 API](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html) - S3-compatible API reference
+
+- **Best Practices:**
+  - [Security Guidelines](/best-practices/security-guidelines) - File upload security
+  - [Deployment Strategies](/best-practices/deployment-strategies) - Storage in production
 
----
 
 ## TypeScript Interfaces Reference
 

package/wiki/references/helpers/testing.md

@@ -113,3 +113,21 @@ const authTestPlan = TestPlan.newInstance({
 
 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

@@ -149,3 +149,19 @@ 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

@@ -0,0 +1,167 @@
+# 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

@@ -160,3 +160,19 @@ const workerBus = new BaseWorkerBusHelper({
   }),
 });
 ```
+
+## 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