@venizia/ignis-docs 0.0.2 → 0.0.4-0

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

@@ -6,6 +6,7 @@ Reusable classes and functions providing common functionality - designed for eas
 
 | Helper | Purpose | Key Features |
 |--------|---------|--------------|
+| [Common Types](./types.md) | Utility types | Nullable, resolvers, class types |
 | [Cron](./cron.md) | Job scheduling | Cron expressions, task management |
 | [Crypto](./crypto.md) | Cryptographic operations | Hashing, AES/RSA encryption/decryption |
 | [Environment](./env.md) | Environment variables | Centralized config access |
@@ -18,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/real-time-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

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