@venizia/ignis-docs 0.0.7 → 0.0.8-0

package/wiki/{references → extensions}/components/socket-io/index.md

@@ -8,31 +8,33 @@
 |------|-------|
 | **Package** | `@venizia/ignis` (core) |
 | **Class** | `SocketIOComponent` |
-| **Server Helper** | [`SocketIOServerHelper`](/references/helpers/socket-io/) |
-| **Client Helper** | [`SocketIOClientHelper`](/references/helpers/socket-io/) |
+| **Server Helper** | [`SocketIOServerHelper`](/extensions/helpers/socket-io/) |
+| **Client Helper** | [`SocketIOClientHelper`](/extensions/helpers/socket-io/) |
 | **Runtimes** | Node.js (`@hono/node-server`) and Bun (native) |
 | **Scaling** | `@socket.io/redis-adapter` + `@socket.io/redis-emitter` |
 
 #### Import Paths
+
+> [!IMPORTANT]
+> `SocketIOComponent` and `SocketIOBindingKeys` are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/socket-io` subpath.
+
 ```typescript
+// From core -- subpath import (NOT from '@venizia/ignis')
 import {
   SocketIOComponent,
   SocketIOBindingKeys,
-} from '@venizia/ignis';
+} from '@venizia/ignis/socket-io';
 
+// From helpers -- subpath import
 import {
   SocketIOServerHelper,
-  RedisHelper,
-} from '@venizia/ignis-helpers';
-
-import {
   SocketIOClientHelper,
   SocketIOConstants,
   SocketIOClientStates,
 } from '@venizia/ignis-helpers/socket-io';
 
+// Types from helpers subpath
 import type {
-  IServerOptions,
   TSocketIOAuthenticateFn,
   TSocketIOValidateRoomFn,
   TSocketIOClientConnectedFn,
@@ -40,7 +42,7 @@ import type {
   IOptions,
   TSocketIOEventHandler,
   TSocketIOClientState,
-} from '@venizia/ignis';
+} from '@venizia/ignis-helpers/socket-io';
 ```
 
 ### Use Cases
@@ -69,18 +71,17 @@ bun add @socket.io/bun-engine
 In your application's `preConfigure()` method, bind the required services and register the component:
 
 ```typescript
+import { BaseApplication } from '@venizia/ignis';
 import {
-  BaseApplication,
   SocketIOComponent,
   SocketIOBindingKeys,
-  ValueOrPromise,
-} from '@venizia/ignis';
-import { RedisHelper } from '@venizia/ignis-helpers';
+} from '@venizia/ignis/socket-io';
+import { RedisHelper, ValueOrPromise } from '@venizia/ignis-helpers';
 import type {
   TSocketIOAuthenticateFn,
   TSocketIOValidateRoomFn,
   TSocketIOClientConnectedFn,
-} from '@venizia/ignis';
+} from '@venizia/ignis-helpers/socket-io';
 
 export class Application extends BaseApplication {
   private redisHelper: RedisHelper;
@@ -225,10 +226,10 @@ const DEFAULT_SERVER_OPTIONS: Partial<IServerOptions> = {
 Bind custom server options before registering the component:
 
 ```typescript
-import { SocketIOBindingKeys, IServerOptions } from '@venizia/ignis';
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import type { ServerOptions } from 'socket.io';
 
-const customOptions: Partial<IServerOptions> = {
-  identifier: 'my-app-socket',
+const customOptions: Partial<ServerOptions> = {
   path: '/socket.io',
   cors: {
     origin: ['https://myapp.com', 'https://admin.myapp.com'],
@@ -240,20 +241,23 @@ const customOptions: Partial<IServerOptions> = {
   maxHttpBufferSize: 1e6, // 1MB
 };
 
-this.bind<Partial<IServerOptions>>({
+this.bind<Partial<ServerOptions>>({
   key: SocketIOBindingKeys.SERVER_OPTIONS,
 }).toValue(customOptions);
 
 this.component(SocketIOComponent);
 ```
 
+> [!NOTE]
+> The `identifier` field is part of the component's `IServerOptions` interface (which extends `ServerOptions`), not Socket.IO's native options. To set the identifier, include it in the bound options object.
+
 ## Binding Keys
 
 All binding keys are available in `SocketIOBindingKeys`:
 
 | Binding Key | Constant | Type | Required | Default |
 |------------|----------|------|----------|---------|
-| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<IServerOptions>` | No | See defaults above |
+| `@app/socket-io/server-options` | `SERVER_OPTIONS` | `Partial<ServerOptions>` | No | See defaults above |
 | `@app/socket-io/redis-connection` | `REDIS_CONNECTION` | `RedisHelper` / `RedisClusterHelper` / `DefaultRedisHelper` | **Yes** | `null` |
 | `@app/socket-io/authenticate-handler` | `AUTHENTICATE_HANDLER` | `TSocketIOAuthenticateFn` | **Yes** | `null` |
 | `@app/socket-io/validate-room-handler` | `VALIDATE_ROOM_HANDLER` | `TSocketIOValidateRoomFn` | No | `null` |
@@ -404,7 +408,7 @@ interface IHandshake {
 - **Components:**
   - [Components Index](../index) -- All built-in components
 - **Helpers:**
-  - [Socket.IO Helper](/references/helpers/socket-io/) -- Full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
+  - [Socket.IO Helper](/extensions/helpers/socket-io/) -- Full `SocketIOServerHelper` + `SocketIOClientHelper` API reference
 - **External Resources:**
   - [Socket.IO Documentation](https://socket.io/docs/) -- Official docs
   - [Socket.IO Redis Adapter](https://socket.io/docs/v4/redis-adapter/) -- Horizontal scaling guide

package/wiki/{references → extensions}/components/socket-io/usage.md

@@ -12,11 +12,11 @@ Inject `SocketIOServerHelper` to interact with Socket.IO:
 import {
   BaseService,
   inject,
-  SocketIOBindingKeys,
   CoreBindings,
   BaseApplication,
 } from '@venizia/ignis';
-import { SocketIOServerHelper } from '@venizia/ignis-helpers';
+import { SocketIOBindingKeys } from '@venizia/ignis/socket-io';
+import { SocketIOServerHelper } from '@venizia/ignis-helpers/socket-io';
 
 export class NotificationService extends BaseService {
   // Lazy getter pattern -- helper is bound AFTER server starts

package/wiki/{references → extensions}/components/static-asset/api.md

@@ -6,10 +6,11 @@
 
 The `AssetControllerFactory.defineAssetController()` method dynamically creates controller classes at runtime. For each storage backend in the options:
 
-1. A new class extending `BaseController` is created with `@controller({ path: basePath })`
+1. A new class extending `BaseRestController` is created with `@controller({ path: basePath })`
 2. The class name is set dynamically via `Object.defineProperty(_controller, 'name', { value: name })`
 3. Routes are bound in the controller's `binding()` method using `this.bindRoute().to()`
-4. The controller is registered via `this.application.controller()`
+4. Route configs are spread-merged with per-route overrides from `controller.routes` (e.g., `{ ...StaticAssetDefinitions.UPLOAD, ...routes?.upload }`)
+5. The controller is registered via `this.application.controller()`
 
 ```
 StaticAssetComponent.binding()
@@ -17,7 +18,7 @@ StaticAssetComponent.binding()
 AssetControllerFactory.defineAssetController({ controller, storage, helper, ... })
     | creates
 @controller({ path: basePath })
-class _controller extends BaseController { ... }
+class _controller extends BaseRestController { ... }
     | registered via
 this.application.controller(_controller)
 ```
@@ -28,11 +29,7 @@ The factory method accepts the following options:
 
 ```typescript
 interface IAssetControllerOptions {
-  controller: {
-    name: string;
-    basePath: string;
-    isStrict?: boolean;   // Default: true
-  };
+  controller: TStaticAssetsComponentOptions[string]['controller'];
   storage: TStaticAssetStorageType;
   helper: IStorageHelper;
   useMetaLink?: boolean;
@@ -49,8 +46,9 @@ A constants class following the Ignis pattern with `static readonly` fields, a `
 class StaticAssetStorageTypes {
   static readonly DISK = 'disk';
   static readonly MINIO = 'minio';
+  static readonly BUN_S3 = 'bun-s3';
 
-  static readonly SCHEME_SET = new Set([this.DISK, this.MINIO]);
+  static readonly SCHEME_SET = new Set([this.DISK, this.MINIO, this.BUN_S3]);
 
   static isValid(orgType: string): boolean {
     return this.SCHEME_SET.has(orgType);
@@ -58,7 +56,7 @@ class StaticAssetStorageTypes {
 }
 
 type TStaticAssetStorageType = TConstValue<typeof StaticAssetStorageTypes>;
-// Resolves to: 'disk' | 'minio'
+// Resolves to: 'disk' | 'minio' | 'bun-s3'
 ```
 
 ## MultipartBodySchema
@@ -133,7 +131,7 @@ interface IStorageHelper {
   upload(opts: {
     bucket: string;
     files: IUploadFile[];
-    normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
+    normalizeNameFn?: (opts: { originalName: string }) => string;
     normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
   }): Promise<IUploadResult[]>;
 
@@ -157,7 +155,6 @@ interface IUploadFile {
   buffer: Buffer;
   size: number;
   encoding?: string;
-  folderPath?: string;
   [key: string | symbol]: any;
 }
 
@@ -207,6 +204,7 @@ BaseStorageHelper (abstract class)
     |
     +-- DiskHelper (local filesystem)
     +-- MinioHelper (S3-compatible)
+    +-- BunS3Helper (Bun-native S3)
 ```
 
 ## MetaLink SQL Schema
@@ -225,21 +223,22 @@ BaseStorageHelper (abstract class)
 | `size` | INTEGER | No | -- | File size in bytes |
 | `etag` | TEXT | Yes | -- | Entity tag for versioning |
 | `metadata` | JSONB | Yes | -- | Additional file metadata |
-| `storage_type` | TEXT | No | -- | Storage type (`'disk'` or `'minio'`) |
+| `storage_type` | TEXT | No | -- | Storage type (`'disk'`, `'minio'`, or `'bun-s3'`) |
 | `is_synced` | BOOLEAN | No | `false` | Whether MetaLink is synchronized with storage |
+| `variant` | TEXT | Yes | -- | Upload variant tag (e.g., `'thumbnail'`, `'original'`) |
 | `principal_type` | TEXT | Yes | -- | Type of the associated principal (e.g., `'user'`, `'service'`) |
 | `principal_id` | TEXT | Yes | -- | ID of the associated principal (always stored as string) |
 
 **Indexes:** `bucket_name`, `object_name`, `storage_type`, `is_synced`.
 
 > [!NOTE]
-> The `isSynced` field is automatically set to `true` when files are uploaded or synced via the meta-links endpoint. When a file is deleted, the MetaLink record is removed entirely. The `principalType` and `principalId` fields are only populated during upload when the corresponding query parameters are provided.
+> The `isSynced` field is automatically set to `true` when files are uploaded or synced via the meta-links endpoint. When a file is deleted, the MetaLink record is removed entirely. The `principalType`, `principalId`, and `variant` fields are only populated during upload when the corresponding query parameters are provided.
 
 ### MetaLink Tracking
 
 When `useMetaLink: true`, the component:
 
-- **On upload:** Creates a MetaLink database record for each uploaded file after fetching file stats from storage. Stores `principalType` and `principalId` from query parameters (if provided). The `principalId` is always coerced to a string via `String()`. If MetaLink creation fails, the upload still succeeds and the response includes `metaLink: null` with a `metaLinkError` message.
+- **On upload:** Creates a MetaLink database record for each uploaded file after fetching file stats from storage. If a `createMetaLink` callback is provided on `TMetaLinkConfig`, it is used instead of the default creation logic. Stores `principalType`, `principalId`, and `variant` from query parameters (if provided). The `principalId` is always coerced to a string via `String()`. If MetaLink creation fails, the upload still succeeds and the response includes `metaLink: null` with a `metaLinkError` message.
 - **On delete:** Initiates MetaLink record deletion as fire-and-forget (the `.then()/.catch()` promise chain is not awaited). The HTTP response with `{ "success": true }` returns before the database deletion completes. Deletion errors are logged but do not fail the request.
 - **On sync (PUT meta-links):** Checks if a MetaLink exists for the object (matched by `bucketName` + `objectName`). Updates it if found, creates a new one if not. Always sets `isSynced: true`. Returns `{ success: true, metaLink: ... }`.
 

package/wiki/{references → extensions}/components/static-asset/errors.md

@@ -41,10 +41,12 @@ Every endpoint that accepts `bucketName` validates it and returns HTTP 400 `"Inv
 **Fix:** Ensure each storage configuration has all required fields:
 
 ```typescript
+import { StaticAssetStorageTypes } from '@venizia/ignis/static-asset';
+
 {
   [uniqueKey]: {
     controller: { name, basePath, isStrict },
-    storage: 'disk' | 'minio',
+    storage: StaticAssetStorageTypes.DISK | StaticAssetStorageTypes.MINIO | StaticAssetStorageTypes.BUN_S3,
     helper: IStorageHelper,
     extra: {}
   }