@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/{references → extensions}/components/websocket/index.md

@@ -11,20 +11,24 @@
 |------|-------|
 | **Package** | `@venizia/ignis` (core component) + `@venizia/ignis-helpers` (helper classes) |
 | **Component** | `WebSocketComponent` |
-| **Server Helper** | [`WebSocketServerHelper`](/references/helpers/websocket/) |
+| **Server Helper** | [`WebSocketServerHelper`](/extensions/helpers/websocket/) |
 | **Emitter Helper** | `WebSocketEmitter` (standalone Redis publisher) |
 | **Runtimes** | Bun only (throws on Node.js) |
 | **Scaling** | Redis Pub/Sub (ioredis -- single or Cluster) |
 
 #### Import Paths
+
+> [!IMPORTANT]
+> `WebSocketComponent` and `WebSocketBindingKeys` are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/websocket` subpath.
+
 ```typescript
-// From core -- component + binding keys only
+// From core -- subpath import (NOT from '@venizia/ignis')
 import {
   WebSocketComponent,
   WebSocketBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/websocket';
 
-// From helpers -- types, helpers, constants
+// From helpers -- types, helpers, constants (exported from main entry)
 import {
   WebSocketServerHelper,
   WebSocketEmitter,
@@ -53,7 +57,7 @@ import type {
 ```
 
 > [!NOTE]
-> `IServerOptions` (the core component's subset type) is **not** exported from `@venizia/ignis`. Only `WebSocketBindingKeys` and `WebSocketComponent` are exported from the core package. All helper types, constants, and classes are imported from `@venizia/ignis-helpers`.
+> `IServerOptions` (the core component's subset type) is **not** exported from `@venizia/ignis` or `@venizia/ignis/websocket`. Only `WebSocketBindingKeys` and `WebSocketComponent` are exported from the core subpath. All helper types, constants, and classes are imported from `@venizia/ignis-helpers`.
 
 ### Use Cases
 
@@ -82,11 +86,11 @@ In your application's `preConfigure()` method, bind the required services and re
 
 #### Full Setup Example
 ```typescript
+import { BaseApplication } from '@venizia/ignis';
 import {
-  BaseApplication,
   WebSocketComponent,
   WebSocketBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/websocket';
 import {
   RedisHelper,
 } from '@venizia/ignis-helpers';
@@ -98,7 +102,6 @@ import type {
   TWebSocketMessageHandler,
   TWebSocketOutboundTransformer,
   TWebSocketHandshakeFn,
-  IWebSocketServerOptions,
   IBunWebSocketConfig,
   ValueOrPromise,
 } from '@venizia/ignis-helpers';
@@ -204,7 +207,7 @@ export class Application extends BaseApplication {
     }).toValue(handshakeFn);
 
     // 9. Server options (optional -- customize defaults)
-    this.bind<Partial<IWebSocketServerOptions>>({
+    this.bind({
       key: WebSocketBindingKeys.SERVER_OPTIONS,
     }).toValue({
       identifier: 'my-app-websocket',
@@ -240,11 +243,14 @@ The core component's `IServerOptions` interface controls the WebSocket server se
 }
 ```
 
+> [!NOTE]
+> The `DEFAULT_SERVER_OPTIONS` in the core component only sets `identifier` and `path`. The remaining defaults (`defaultRooms`, `heartbeatInterval`, `heartbeatTimeout`, `serverOptions`) come from `WebSocketDefaults` applied by the helper constructor.
+
 To customize options, bind a partial options object before registering the component:
 
 #### Custom Server Options Example
 ```typescript
-import { WebSocketBindingKeys } from '@venizia/ignis';
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
 
 this.bind({
   key: WebSocketBindingKeys.SERVER_OPTIONS,
@@ -448,6 +454,6 @@ Called during authentication when `requireEncryption` is `true`. Receives the sa
 - [Usage & Examples](./usage) - Server-side usage, emitter, wire protocol, client tracking, and delivery strategy
 - [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
 - [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference

package/wiki/{references → extensions}/components/websocket/usage.md

@@ -10,10 +10,10 @@ Inject `WebSocketServerHelper` to interact with WebSocket:
 import {
   BaseService,
   inject,
-  WebSocketBindingKeys,
   CoreBindings,
   BaseApplication,
 } from '@venizia/ignis';
+import { WebSocketBindingKeys } from '@venizia/ignis/websocket';
 import { WebSocketServerHelper } from '@venizia/ignis-helpers';
 
 export class NotificationService extends BaseService {
@@ -470,6 +470,6 @@ The helper uses a dual delivery strategy depending on whether encryption is acti
 - [Setup & Configuration](./) - Quick reference, imports, setup steps, configuration, and binding keys
 - [API Reference](./api) - Architecture, WebSocketEmitter API, and internals
 - [Error Reference](./errors) - Error conditions table and troubleshooting
-- [WebSocketServerHelper](/references/helpers/websocket/) - Helper API documentation
+- [WebSocketServerHelper](/extensions/helpers/websocket/) - Helper API documentation
 - [Socket.IO Component](../socket-io/) - Node.js-compatible alternative with Socket.IO
 - [Bun WebSocket Documentation](https://bun.sh/docs/api/websockets) - Official Bun WebSocket API reference

package/wiki/{references → extensions}/helpers/crypto/index.md

@@ -531,7 +531,7 @@ const hashed = hash('text', {
 
 - **References:**
   - [Crypto Utility](/references/utilities/crypto) -- Pure crypto utilities
-  - [Authentication Component](/references/components/authentication/) -- JWT and password verification
+  - [Authentication Component](/extensions/components/authentication/) -- JWT and password verification
 
 - **Best Practices:**
   - [Security Guidelines](/best-practices/security-guidelines) -- Cryptographic best practices

package/wiki/{references → extensions}/helpers/env/index.md

@@ -9,14 +9,14 @@ Structured access to application environment variables with prefix filtering, ty
 | **Package** | `@venizia/ignis-helpers` |
 | **Classes** | `ApplicationEnvironment`, `Environment` |
 | **Extends** | `IApplicationEnvironment` (interface) |
-| **Singleton** | `applicationEnvironment` -- auto-initialized at module load |
+| **Singleton** | `applicationEnvironment` (alias `Envs`) -- auto-initialized at module load |
 | **Runtimes** | Both |
 
 #### Import Paths
 
 ```typescript
 // Singleton instance (recommended)
-import { applicationEnvironment } from '@venizia/ignis-helpers';
+import { applicationEnvironment, Envs } from '@venizia/ignis-helpers';
 
 // Classes
 import { ApplicationEnvironment, Environment } from '@venizia/ignis-helpers';
@@ -29,12 +29,15 @@ import type { IApplicationEnvironment } from '@venizia/ignis-helpers';
 
 ### Singleton (Recommended)
 
-A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`).
+A pre-configured `applicationEnvironment` singleton is auto-initialized at module load time. It reads `process.env` and filters keys matching the configured prefix (default: `APP_ENV`). An alias `Envs` is also exported for convenience.
 
 ```typescript
 import { applicationEnvironment } from '@venizia/ignis-helpers';
+// or
+import { Envs } from '@venizia/ignis-helpers';
 
 const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
+const jwtSecret2 = Envs.get<string>('APP_ENV_JWT_SECRET');
 ```
 
 > [!TIP]
@@ -68,13 +71,14 @@ The default singleton uses `process.env.APPLICATION_ENV_PREFIX ?? 'APP_ENV'` as
 
 ### Reading Variables
 
-Use `get<ReturnType>(key)` to retrieve a typed environment variable. Only keys matching the configured prefix are available.
+Use `get<ReturnType>(key, defaultValue?)` to retrieve a typed environment variable. Only keys matching the configured prefix are available. An optional `defaultValue` is returned when the key is not found.
 
 ```typescript
 import { applicationEnvironment } from '@venizia/ignis-helpers';
 
 const jwtSecret = applicationEnvironment.get<string>('APP_ENV_JWT_SECRET');
 const serverPort = applicationEnvironment.get<string>('APP_ENV_SERVER_PORT');
+const timeout = applicationEnvironment.get<number>('APP_ENV_TIMEOUT', 5000);
 ```
 
 > [!WARNING]
@@ -211,4 +215,4 @@ ALLOW_EMPTY_ENV_VALUE=true
 
 - **Other Helpers:**
   - [Helpers Index](../index) -- All available helpers
-  - [Logger](/references/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering
+  - [Logger](/extensions/helpers/logger/) -- Uses `Environment.COMMON_ENVS` for debug log filtering

package/wiki/{references → extensions}/helpers/error/index.md

@@ -19,9 +19,6 @@ import { ErrorSchema } from '@venizia/ignis-helpers';
 import type { TError } from '@venizia/ignis-helpers';
 ```
 
-> [!NOTE]
-> `ApplicationError`, `getError`, `ErrorSchema`, and `TError` are also available from `@venizia/ignis-inversion`. Their types are re-exported through `@venizia/ignis` (via `export type *`), but for runtime usage, import directly from `@venizia/ignis-helpers` or `@venizia/ignis-inversion`.
-
 ## Creating an Instance
 
 `ApplicationError` extends the native `Error` class with an HTTP `statusCode` and an optional `messageCode` for machine-readable error identification.
@@ -226,7 +223,5 @@ throw getError({
 - [Controllers](/references/base/controllers) -- Throwing errors in route handlers
 - [Services](/references/base/services) -- Error handling in business logic
 - [Middlewares](/references/base/middlewares) -- The `appErrorHandler` middleware
-- [Helpers Index](/references/helpers/) -- All available helpers
-- [Logger Helper](/references/helpers/logger/) -- Logging errors
-- [Error Handling Best Practices](/best-practices/error-handling) -- Patterns and anti-patterns
-- [Common Pitfalls](/best-practices/common-pitfalls) -- Frequent error handling mistakes
+- [Helpers Index](/extensions/helpers/) -- All available helpers
+- [Logger Helper](/extensions/helpers/logger/) -- Logging errors

package/wiki/{references → extensions}/helpers/index.md

@@ -14,7 +14,7 @@ Reusable classes and functions providing common functionality - designed for eas
 | [Inversion](./inversion/) | Dependency injection | DI container implementation |
 | [Logger](./logger/) | Logging | Winston-based, multiple transports, scopes |
 | [Network](./network/) | Network requests | HTTP, TCP, UDP helpers |
-| Kafka <Badge type="warning" text="Experimental" /> | Event streaming | Apache Kafka producer/consumer |
+| [Kafka](./kafka/) | Event streaming | Apache Kafka producer/consumer/admin/schema registry |
 | [Queue](./queue/) | Message queues | BullMQ, MQTT support |
 | [Redis](./redis/) | Redis operations | Single/cluster, key-value, hashes, JSON, pub/sub |
 | [Socket.IO](./socket-io/) | Real-time communication | Socket.IO client/server helpers |
@@ -24,15 +24,27 @@ Reusable classes and functions providing common functionality - designed for eas
 | [UID](./uid/) | Unique ID generation | Snowflake IDs, Base62 encoding |
 | [Worker Thread](./worker-thread/) | Worker threads | Node.js worker management |
 
+### Subpath Imports
+
+Some helpers with optional peer dependencies are only available via subpath imports to ensure proper tree-shaking:
+
+| Subpath | Peer Dependency | Description |
+|---------|-----------------|-------------|
+| `@venizia/ignis-helpers/kafka` | `@platformatic/kafka` | Kafka producer/consumer/admin/schema registry |
+| `@venizia/ignis-helpers/bullmq` | `bullmq` | BullMQ job queue |
+| `@venizia/ignis-helpers/mqtt` | `mqtt` | MQTT pub/sub client |
+| `@venizia/ignis-helpers/socket-io` | `socket.io`, `socket.io-client` | Socket.IO server/client |
+| `@venizia/ignis-helpers/minio` | `minio` | MinIO S3-compatible storage |
+| `@venizia/ignis-helpers/bun-s3` | -- | Bun native S3 storage |
+| `@venizia/ignis-helpers/cron` | `cron` | Cron job scheduling |
+| `@venizia/ignis-helpers/axios` | `axios` | Axios HTTP client |
+
 ## See Also
 
 - **Related Concepts:**
   - [Services](/guides/core-concepts/services) - Using helpers in service layer
-  - [Controllers](/guides/core-concepts/controllers) - Using helpers in controllers
+  - [Controllers](/guides/core-concepts/rest-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
+  - [Components](/extensions/components/) - Framework components

package/wiki/{references → extensions}/helpers/kafka/admin.md

@@ -1,13 +1,13 @@
 # Admin
 
-The `KafkaAdminHelper` is a thin wrapper around `@platformatic/kafka`'s `Admin`. It manages creation, logging, and lifecycle.
+The `KafkaAdminHelper` wraps `@platformatic/kafka`'s `Admin` with health tracking, graceful shutdown, and broker event callbacks. Use `getAdmin()` to access the full Admin API directly.
 
 ```typescript
-class KafkaAdminHelper extends BaseHelper
+class KafkaAdminHelper extends BaseKafkaHelper<Admin>
 ```
 
 > [!NOTE]
-> `KafkaAdminHelper` has **no generic type parameters** — the Admin client does not deal with serialized messages.
+> `KafkaAdminHelper` has **no generic type parameters** -- the Admin client does not deal with serialized messages.
 
 ## Helper API
 
@@ -15,13 +15,19 @@ class KafkaAdminHelper extends BaseHelper
 |--------|-----------|-------------|
 | `newInstance(opts)` | `static newInstance(opts): KafkaAdminHelper` | Factory method |
 | `getAdmin()` | `(): Admin` | Access the underlying `Admin` |
-| `close()` | `(): Promise<void>` | Close the admin connection |
+| `isHealthy()` | `(): boolean` | `true` when broker connected |
+| `isReady()` | `(): boolean` | Same as `isHealthy()` |
+| `getHealthStatus()` | `(): TKafkaHealthStatus` | `'connected'` \| `'disconnected'` \| `'unknown'` |
+| `close(opts?)` | `(opts?: { isForce?: boolean }): Promise<void>` | Close the admin connection (default: graceful) |
 
-## IKafkaAdminOpts
+## IKafkaAdminOptions
 
 ```typescript
-interface IKafkaAdminOpts extends IKafkaConnectionOptions {
-  identifier?: string; // Default: 'kafka-admin'
+interface IKafkaAdminOptions extends IKafkaConnectionOptions {
+  identifier?: string;       // Default: 'kafka-admin'
+  shutdownTimeout?: number;  // Default: 30000ms
+  onBrokerConnect?: TKafkaBrokerEventCallback;
+  onBrokerDisconnect?: TKafkaBrokerEventCallback;
 }
 ```
 
@@ -35,23 +41,39 @@ import { KafkaAdminHelper } from '@venizia/ignis-helpers/kafka';
 const helper = KafkaAdminHelper.newInstance({
   bootstrapBrokers: ['localhost:9092'],
   clientId: 'my-admin',
+  onBrokerConnect: ({ broker }) => console.log(`Connected to ${broker.host}:${broker.port}`),
+  onBrokerDisconnect: ({ broker }) => console.log(`Disconnected from ${broker.host}`),
 });
 
 const admin = helper.getAdmin();
 
-// Create a topic with 3 partitions and 2 replicas
+// Create a topic
 await admin.createTopics({ topics: ['orders'], partitions: 3, replicas: 2 });
 
 // List all topics
 const topics = await admin.listTopics();
 
-// Describe a consumer group
-const groups = await admin.describeGroups({ groups: ['order-processing'] });
+// Health check
+helper.isHealthy(); // true when connected
 
+// Graceful close
 await helper.close();
+
+// Or force close
+await helper.close({ isForce: true });
 ```
 
----
+## Graceful Shutdown
+
+`close()` uses the base `closeClient()` (which calls `this.client.close()`) with a graceful timeout. If the graceful close exceeds `shutdownTimeout` (default 30s), it automatically force-closes. After `close()`, `healthStatus` is set to `'disconnected'`.
+
+```typescript
+// Graceful (recommended)
+await helper.close();
+
+// Force
+await helper.close({ isForce: true });
+```
 
 ## API Reference (`@platformatic/kafka`)
 
@@ -110,11 +132,6 @@ for (const [groupId, group] of details) {
   console.log(`Group: ${groupId}, State: ${group.state}`);
   for (const [memberId, member] of group.members) {
     console.log(`  Member: ${member.clientId} (${member.clientHost})`);
-    if (member.assignments) {
-      for (const [topic, assignment] of member.assignments) {
-        console.log(`    ${topic}: partitions ${assignment.partitions.join(', ')}`);
-      }
-    }
   }
 }
 ```