@venizia/ignis-docs 0.2.0 → 0.2.1-0

package/content/extensions/components/static-asset/index.md

@@ -1,235 +1,88 @@
-# Static Asset
+---
+title: Static Asset Component
+description: Generates bucket/object CRUD REST endpoints for disk, MinIO, and Bun S3 storage backends, with optional database-backed file tracking via MetaLink
+difficulty: intermediate
+---
 
-> Flexible file management system with support for multiple storage backends (local disk, MinIO/S3-compatible, Bun S3) through a unified interface, featuring factory-based controller generation and optional database file tracking via MetaLink.
+# Static Asset Component
 
-## Quick Reference
-
-| Item | Value |
-|------|-------|
-| **Package** | `@venizia/ignis` |
-| **Class** | `StaticAssetComponent` |
-| **Helper** | [`DiskHelper`](/extensions/helpers/storage/), [`MinioHelper`](/extensions/helpers/storage/), [`BunS3Helper`](/extensions/helpers/storage/) |
-| **Runtimes** | Both |
-
-#### Import Paths
+`StaticAssetComponent` reads a map of storage backend configurations and generates a full bucket/object REST controller for each one - disk, MinIO, or Bun S3 - all through the same [`IStorageHelper`](./api#istoragehelper-interface) contract.
 
 > [!IMPORTANT]
-> `StaticAssetComponent` and its related exports are **not** exported from the `@venizia/ignis` barrel. You must import from the `@venizia/ignis/static-asset` subpath.
-
-```typescript
-// From core -- subpath import (NOT from '@venizia/ignis')
-import {
-  StaticAssetComponent,
-  StaticAssetComponentBindingKeys,
-  StaticAssetStorageTypes,
-  AssetControllerFactory,
-  BaseMetaLinkModel,
-  BaseMetaLinkRepository,
-} from '@venizia/ignis/static-asset';
-
-import { DiskHelper } from '@venizia/ignis-helpers';
-import { MinioHelper } from '@venizia/ignis-helpers/minio';
-import { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
-
-import type {
-  TStaticAssetsComponentOptions,
-  TMetaLinkConfig,
-  TStaticAssetExtraOptions,
-  TStaticAssetStorageType,
-} from '@venizia/ignis/static-asset';
-```
-
-### Key Features
-
-| Feature | Description |
-|---------|-------------|
-| **Unified Storage Interface** | Single API for all storage types |
-| **Multiple Storage Instances** | Configure multiple storage backends simultaneously |
-| **Factory Pattern** | Dynamic controller generation per storage backend |
-| **Built-in Security** | Comprehensive name validation, path traversal protection, header sanitization |
-| **Database Tracking (MetaLink)** | Optional database-backed file tracking with metadata, principal association, variant support, and sync status |
-| **Per-Route Configuration** | Override authentication, middleware, and path for individual routes |
-| **Flexible Configuration** | Environment-based, production-ready setup |
+> `StaticAssetComponent` and its related exports are **not** on the `@venizia/ignis` root barrel. Import from the `@venizia/ignis/static-asset` subpath.
 
-## Setup
-
-### Step 1: Bind Configuration
+## In one example
 
 ```typescript
 import { BaseApplication } from '@venizia/ignis';
 import {
+  StaticAssetComponent,
   StaticAssetComponentBindingKeys,
   StaticAssetStorageTypes,
 } from '@venizia/ignis/static-asset';
-import { DiskHelper } from '@venizia/ignis-helpers';
-import { MinioHelper } from '@venizia/ignis-helpers/minio';
 import type { TStaticAssetsComponentOptions } from '@venizia/ignis/static-asset';
+import { DiskHelper } from '@venizia/ignis-helpers';
 
 export class Application extends BaseApplication {
   preConfigure() {
     this.bind<TStaticAssetsComponentOptions>({
       key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
     }).toValue({
-      // MinIO storage for user uploads
       staticAsset: {
-        controller: {
-          name: 'AssetController',
-          basePath: '/assets',
-          isStrict: true,
-        },
-        storage: StaticAssetStorageTypes.MINIO,
-        helper: new MinioHelper({
-          endPoint: 'localhost',
-          port: 9000,
-          accessKey: 'minioadmin',
-          secretKey: 'minioadmin',
-          useSSL: false,
-        }),
-        extra: {
-          parseMultipartBody: { storage: 'memory' },
-        },
-      },
-      // Local disk storage for temporary files
-      staticResource: {
-        controller: {
-          name: 'ResourceController',
-          basePath: '/resources',
-          isStrict: true,
-        },
+        controller: { name: 'AssetController', basePath: '/assets', isStrict: true },
         storage: StaticAssetStorageTypes.DISK,
-        helper: new DiskHelper({
-          basePath: './app_data/resources',
-        }),
-        extra: {
-          parseMultipartBody: { storage: 'memory' },
-        },
+        helper: new DiskHelper({ basePath: './app_data/assets' }),
+        extra: { parseMultipartBody: { storage: 'memory' } },
       },
     });
-  }
-}
-```
 
-Each storage backend gets a unique key (`staticAsset`, `staticResource`), its own controller configuration, and a helper instance.
-
-### Step 2: Register Component
-
-```typescript
-import { StaticAssetComponent } from '@venizia/ignis/static-asset';
-
-export class Application extends BaseApplication {
-  preConfigure() {
-    // ... Step 1 binding ...
     this.component(StaticAssetComponent);
   }
 }
 ```
 
-### Step 3: Use the Endpoints
+This registers `GET`/`POST`/`DELETE` on `/assets/buckets/:bucketName`, `POST /assets/buckets/:bucketName/upload`, `GET /assets/buckets/:bucketName/objects`, plus stream/download/delete-object routes - no controller class to write by hand.
 
-The component auto-registers REST endpoints for each configured backend. No injection needed in downstream code.
+## How it works
 
-```
-GET    /assets/buckets                                - List all buckets
-GET    /assets/buckets/:bucketName                    - Get bucket details (or null)
-POST   /assets/buckets/:bucketName                    - Create a bucket
-DELETE /assets/buckets/:bucketName                    - Delete a bucket
-POST   /assets/buckets/:bucketName/upload             - Upload files
-GET    /assets/buckets/:bucketName/objects             - List objects in bucket
-GET    /assets/buckets/:bucketName/objects/:obj        - Stream file inline
-GET    /assets/buckets/:bucketName/download/:obj        - Download file (attachment)
-DELETE /assets/buckets/:bucketName/objects/:obj        - Delete file
-PUT    /assets/buckets/:bucketName/meta-links/:obj      - Sync MetaLink (MetaLink only)
-```
-
-Each storage backend gets its own base path (`/assets`, `/resources`, etc.) with the same endpoint structure.
-
-#### Environment Variables
+- **One options key, one generated controller.** `TStaticAssetsComponentOptions` is a record - each key (`staticAsset` above) becomes an independently-configured storage backend with its own `basePath`, built by `AssetControllerFactory.defineAssetController()` inside `StaticAssetComponent.binding()`.
+- **`storage` and `helper` are a discriminated pair.** The options type forces `storage: 'disk'` with a `DiskHelper`, `'minio'` with a `MinioHelper`, or `'bun-s3'` with a `BunS3Helper` - mismatching them fails at compile time, not at runtime.
+- **Every backend implements the same `IStorageHelper` contract.** `DiskHelper`, `MinioHelper`, and `BunS3Helper` all extend `BaseStorageHelper`, so bucket/object operations, name validation (`isValidName`/`isValidPath`), and upload normalization behave identically regardless of backend.
+- **Object names can embed folder paths, encoded as one segment.** `objects/{objectName}` takes the whole `folder/file.ext` string percent-encoded (`encodeURIComponent`, which also escapes `/`) - Hono decodes it once before the handler reads it, so client code must encode but never decode a second time.
+- **MetaLink is opt-in.** Set `useMetaLink: true` and provide `metaLink.repository` to persist a database row (bucket, object, mimetype, size, etag, principal, variant) alongside every upload - useful for querying "which files does user X own" without listing a whole bucket.
+- **The default binding is empty.** `StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS` defaults to `{}` - bind it with at least one storage backend before `this.component(StaticAssetComponent)` produces any routes.
 
-Add these to your `.env` file for MinIO:
+## Common tasks
 
-```bash
-APP_ENV_MINIO_HOST=localhost
-APP_ENV_MINIO_API_PORT=9000
-APP_ENV_MINIO_ACCESS_KEY=minioadmin
-APP_ENV_MINIO_SECRET_KEY=minioadmin
-```
+### Add a second storage backend
 
-#### Environment Keys Configuration
+Each key in the options object is independent - mix disk and MinIO under different base paths in one binding.
 
 ```typescript
-// src/common/environments.ts
-import { EnvironmentKeys as BaseEnv } from '@venizia/ignis';
-
-export class EnvironmentKeys extends BaseEnv {
-  static readonly APP_ENV_MINIO_HOST = 'APP_ENV_MINIO_HOST';
-  static readonly APP_ENV_MINIO_API_PORT = 'APP_ENV_MINIO_API_PORT';
-  static readonly APP_ENV_MINIO_ACCESS_KEY = 'APP_ENV_MINIO_ACCESS_KEY';
-  static readonly APP_ENV_MINIO_SECRET_KEY = 'APP_ENV_MINIO_SECRET_KEY';
-}
-```
-
-#### Docker Compose for MinIO
-
-```yaml
-version: '3.8'
-services:
-  minio:
-    image: minio/minio:latest
-    container_name: minio
-    ports:
-      - "9000:9000"   # API port
-      - "9001:9001"   # Console port
-    environment:
-      MINIO_ROOT_USER: minioadmin
-      MINIO_ROOT_PASSWORD: minioadmin
-    command: server /data --console-address ":9001"
-    volumes:
-      - minio_data:/data
-
-volumes:
-  minio_data:
-```
-
-Start with `docker-compose up -d` and access the console at `http://localhost:9001`.
-
-## Configuration
-
-### Storage Types
-
-| Type | Constant | Helper | Description |
-|------|----------|--------|-------------|
-| `'disk'` | `StaticAssetStorageTypes.DISK` | `DiskHelper` | Local filesystem with bucket-based directory structure |
-| `'minio'` | `StaticAssetStorageTypes.MINIO` | `MinioHelper` | S3-compatible object storage (MinIO, AWS S3, etc.) |
-| `'bun-s3'` | `StaticAssetStorageTypes.BUN_S3` | `BunS3Helper` | Bun-native S3 client (requires Bun runtime) |
-
-The `StaticAssetStorageTypes` class provides a `SCHEME_SET` (a `Set` of all valid storage type strings) and an `isValid(orgType)` method for runtime validation:
+import { MinioHelper } from '@venizia/ignis-helpers/minio';
 
-```typescript
-StaticAssetStorageTypes.isValid('minio');  // true
-StaticAssetStorageTypes.isValid('bun-s3'); // true
-StaticAssetStorageTypes.isValid('s3');     // false
-StaticAssetStorageTypes.SCHEME_SET;        // Set { 'disk', 'minio', 'bun-s3' }
+this.bind<TStaticAssetsComponentOptions>({
+  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
+}).toValue({
+  uploads: {
+    controller: { name: 'UploadsController', basePath: '/uploads' },
+    storage: StaticAssetStorageTypes.MINIO,
+    helper: new MinioHelper({
+      endPoint: 'localhost', port: 9000, useSSL: false,
+      accessKey: 'minioadmin', secretKey: 'minioadmin',
+    }),
+  },
+  tempFiles: {
+    controller: { name: 'TempController', basePath: '/temp' },
+    storage: StaticAssetStorageTypes.DISK,
+    helper: new DiskHelper({ basePath: './temp' }),
+  },
+});
 ```
 
-### `TStaticAssetsComponentOptions`
-
-Each key in the options object defines a separate storage backend with its own controller:
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `controller.name` | `string` | -- | Controller class name |
-| `controller.basePath` | `string` | -- | Base URL path (e.g., `'/assets'`) |
-| `controller.isStrict` | `boolean` | `true` | Strict routing mode |
-| `controller.routes` | `object` | `undefined` | Per-route overrides (authenticate, middleware, path) |
-| `storage` | `'disk' \| 'minio' \| 'bun-s3'` | -- | Storage type |
-| `helper` | `DiskHelper \| MinioHelper \| BunS3Helper` | -- | Storage helper instance |
-| `extra` | `TStaticAssetExtraOptions` | `undefined` | Extra options (multipart parsing, name normalization) |
-| `useMetaLink` | `boolean` | `false` | Enable database file tracking |
-| `metaLink` | `TMetaLinkConfig` | -- | MetaLink configuration (required when `useMetaLink: true`) |
+### Lock down individual routes
 
-#### Per-Route Configuration
-
-Each route can be individually configured with authentication, middleware, and path overrides:
+Each key under `controller.routes` accepts a partial `authenticate`/`authorize`/`middleware`/`path` override; unset routes stay public.
 
 ```typescript
 {
@@ -237,446 +90,64 @@ Each route can be individually configured with authentication, middleware, and p
     name: 'AssetController',
     basePath: '/assets',
     routes: {
-      getBuckets: { authenticate: { strategies: ['jwt'], mode: 'any' } },
-      upload: { authenticate: { strategies: ['jwt'], mode: 'any' }, middleware: [rateLimitMw] },
-      getObjectByName: { /* public -- no authenticate */ },
-      downloadObjectByName: { /* public */ },
-      deleteObject: { authenticate: { strategies: ['jwt'], mode: 'any' } },
-      deleteBucket: { authenticate: { strategies: ['jwt'], mode: 'any' } },
+      upload: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+      deleteObject: { authenticate: { strategies: ['jwt'], mode: 'required' } },
+      deleteBucket: { authenticate: { strategies: ['jwt'], mode: 'required' } },
     },
   },
-  // ...
 }
 ```
 
-Available route keys: `getBuckets`, `getBucketByName`, `createBucket`, `deleteBucket`, `upload`, `listObjects`, `deleteObject`, `getObjectByName`, `downloadObjectByName`, `recreateMetaLink`.
-
-#### TStaticAssetsComponentOptions -- Full Reference
-```typescript
-type TStaticAssetsComponentOptions = {
-  [key: string]: {
-    controller: {
-      name: string;
-      basePath: string;
-      isStrict?: boolean;
-      routes?: {
-        getBuckets?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        getBucketByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        createBucket?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        deleteBucket?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        upload?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        listObjects?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        deleteObject?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        getObjectByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        downloadObjectByName?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-        recreateMetaLink?: Partial<Omit<IAuthRouteConfig, 'method' | 'request' | 'responses'>>;
-      };
-    };
-    extra?: TStaticAssetExtraOptions;
-  } & (
-    | { storage: typeof StaticAssetStorageTypes.BUN_S3; helper: BunS3Helper }
-    | { storage: typeof StaticAssetStorageTypes.DISK; helper: DiskHelper }
-    | { storage: typeof StaticAssetStorageTypes.MINIO; helper: MinioHelper }
-  ) &
-    ({ useMetaLink?: false | undefined } | { useMetaLink: true; metaLink: TMetaLinkConfig });
-};
-
-type TStaticAssetExtraOptions = {
-  parseMultipartBody?: {
-    storage?: 'memory' | 'disk';
-    uploadDir?: string;
-  };
-  normalizeNameFn?: (opts: { originalName: string }) => string;
-  normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
-  /** Maximum folder nesting depth allowed in object paths. Default: 2 */
-  maxFolderDepth?: number;
-  [key: string]: any;
-};
-
-type TMetaLinkConfig<Schema extends TMetaLinkSchema = TMetaLinkSchema> = {
-  model: typeof BasePostgresEntity<Schema>;
-  repository: DefaultCRUDRepository<Schema>;
-  createMetaLink?: (opts: {
-    uploadResult: IUploadResult;
-    fileStat: IFileStat;
-    query: TUploadQuery;
-  }) => ValueOrPromise<{ count: number; data: Schema }>;
-};
-```
-
-> [!NOTE]
-> The `normalizeNameFn` receives only `{ originalName }` -- there is no `folderPath` parameter.
-
-> [!TIP]
-> The `createMetaLink` callback on `TMetaLinkConfig` is optional. When provided, it replaces the default MetaLink creation logic during upload, giving you full control over how file metadata is stored.
-
-### DiskHelper
+### Switch multipart parsing to disk for large uploads
 
-Stores files on the local filesystem using a bucket-based directory structure.
+`parseMultipartBody: { storage: 'memory' }` (the default) buffers the whole file in RAM before writing it to the backend. Switch to `'disk'` to spool it to a temp file instead.
 
 ```typescript
-new DiskHelper({
-  basePath: string;    // Base directory for storage
-  scope?: string;      // Logger scope
-  identifier?: string; // Helper identifier
-})
-```
-
-**Example:**
-
-```typescript
-const diskHelper = new DiskHelper({
-  basePath: './app_data/storage',
-});
-```
-
-**Directory structure:**
-```
-app_data/storage/
-├── bucket-1/
-│   ├── file1.pdf
-│   └── file2.jpg
-├── bucket-2/
-│   └── document.docx
-```
-
-Features: automatic directory creation, built-in path validation, metadata from file stats, stream-based operations.
-
-### MinioHelper
-
-Connects to MinIO or any S3-compatible object storage.
-
-```typescript
-new MinioHelper({
-  endPoint: string;    // MinIO server hostname
-  port: number;        // API port (default: 9000)
-  useSSL: boolean;     // Use HTTPS
-  accessKey: string;   // Access key
-  secretKey: string;   // Secret key
-})
-```
-
-**Example:**
-
-```typescript
-const minioHelper = new MinioHelper({
-  endPoint: 'minio.example.com',
-  port: 9000,
-  useSSL: true,
-  accessKey: process.env.MINIO_ACCESS_KEY,
-  secretKey: process.env.MINIO_SECRET_KEY,
-});
-```
-
-### BunS3Helper
-
-Bun-native S3 client for direct S3/S3-compatible access using Bun's built-in S3 support. Requires Bun runtime.
-
-```typescript
-import { BunS3Helper } from '@venizia/ignis-helpers/bun-s3';
-```
-
-### MetaLink Configuration
-
-MetaLink is an optional feature that tracks uploaded files in a database, storing file location, metadata (mimetype, size, etag), storage type, principal association (`principalType`, `principalId`), variant, timestamps, and custom metadata (JSONB).
-
-#### Benefits
-
-- Query uploaded files by bucket, name, mimetype, variant, etc.
-- Track file history and audit trails
-- Store custom metadata about files
-- Associate files with principals via `principalType` and `principalId` (passed as query parameters on the upload endpoint)
-- Tag uploads with a `variant` query parameter (e.g., `"thumbnail"`, `"original"`)
-- Custom `createMetaLink` callback for full control over MetaLink creation
-- Graceful errors -- upload succeeds even if MetaLink creation fails
-
-#### Setup
-
-**1. Create Model:**
-
-```typescript
-import { BaseMetaLinkModel } from '@venizia/ignis/static-asset';
-import { model } from '@venizia/ignis';
-
-@model({ type: 'entity' })
-export class FileMetaLinkModel extends BaseMetaLinkModel {
-  // Inherits all fields from BaseMetaLinkModel
+extra: {
+  parseMultipartBody: { storage: 'disk', uploadDir: './tmp/uploads' },
 }
 ```
 
-**2. Create Repository:**
+### Enable MetaLink database tracking
 
-```typescript
-import { BaseMetaLinkRepository } from '@venizia/ignis/static-asset';
-import { repository } from '@venizia/ignis';
-import { FileMetaLinkModel } from './file-meta-link.model';
-import { PostgresDataSource } from '../datasources/postgres.datasource';
-
-@repository({ model: FileMetaLinkModel, dataSource: PostgresDataSource })
-export class FileMetaLinkRepository extends BaseMetaLinkRepository {
-  // No constructor needed - dataSource auto-injected from @repository metadata
-}
-```
-
-**3. Create Database Table:**
-
-The model has `skipMigrate: true`, so create the table manually:
-
-```sql
-CREATE TABLE "MetaLink" (
-  id              TEXT PRIMARY KEY,
-  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  modified_at     TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  bucket_name     TEXT NOT NULL,
-  object_name     TEXT NOT NULL,
-  link            TEXT NOT NULL,
-  mimetype        TEXT NOT NULL,
-  size            INTEGER NOT NULL,
-  etag            TEXT,
-  metadata        JSONB,
-  storage_type    TEXT NOT NULL,
-  is_synced       BOOLEAN NOT NULL DEFAULT false,
-  variant         TEXT,
-  principal_type  TEXT,
-  principal_id    TEXT
-);
-
-CREATE INDEX "IDX_MetaLink_bucketName" ON "MetaLink"(bucket_name);
-CREATE INDEX "IDX_MetaLink_objectName" ON "MetaLink"(object_name);
-CREATE INDEX "IDX_MetaLink_storageType" ON "MetaLink"(storage_type);
-CREATE INDEX "IDX_MetaLink_isSynced" ON "MetaLink"(is_synced);
-```
-
-**4. Configure Component:**
-
-```typescript
-import { FileMetaLinkModel, FileMetaLinkRepository } from './your-models';
-import {
-  StaticAssetComponent,
-  StaticAssetComponentBindingKeys,
-  StaticAssetStorageTypes,
-} from '@venizia/ignis/static-asset';
-import type { TStaticAssetsComponentOptions } from '@venizia/ignis/static-asset';
-
-export class Application extends BaseApplication {
-  configureComponents(): void {
-    this.repository(FileMetaLinkRepository);
-
-    this.bind<TStaticAssetsComponentOptions>({
-      key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
-    }).toValue({
-      uploads: {
-        controller: {
-          name: 'UploadController',
-          basePath: '/uploads',
-          isStrict: true,
-        },
-        storage: StaticAssetStorageTypes.MINIO,
-        helper: new MinioHelper({ /* ... */ }),
-        useMetaLink: true,
-        metaLink: {
-          model: FileMetaLinkModel,
-          repository: this.getSync(FileMetaLinkRepository),
-        },
-        extra: {
-          parseMultipartBody: { storage: 'memory' },
-        },
-      },
-    });
-
-    this.component(StaticAssetComponent);
-  }
-}
-```
-
-**5. Upload with Principal Association and Variant:**
-
-When MetaLink is enabled, you can associate uploaded files with a principal and variant by passing query parameters on the upload endpoint:
-
-```typescript
-const formData = new FormData();
-formData.append('file', fileBlob, 'document.pdf');
-
-// Associate the upload with a user and tag as 'original' variant
-const response = await fetch(
-  '/uploads/buckets/user-files/upload?principalType=user&principalId=42&variant=original',
-  { method: 'POST', body: formData },
-);
-```
-
-The `principalId` value is always stored as a string regardless of input type (coerced via `String()`).
-
-#### Custom MetaLink Creation
-
-You can provide a custom `createMetaLink` callback to fully control how MetaLink records are created:
+Bind a repository over `BaseMetaLinkModel` (used directly, no subclass needed) and pass it as `metaLink.repository`.
 
 ```typescript
+useMetaLink: true,
 metaLink: {
-  model: FileMetaLinkModel,
-  repository: this.getSync(FileMetaLinkRepository),
-  createMetaLink: async ({ uploadResult, fileStat, query }) => {
-    // Custom logic -- e.g., add extra fields, validate, transform
-    return metaLinkRepo.create({
-      data: {
-        bucketName: uploadResult.bucketName,
-        objectName: uploadResult.objectName,
-        link: uploadResult.link,
-        mimetype: fileStat.metadata?.['mimetype'],
-        size: fileStat.size,
-        etag: fileStat.etag,
-        metadata: fileStat.metadata,
-        storageType: 'minio',
-        isSynced: true,
-        principalId: query.principalId ? String(query.principalId) : undefined,
-        principalType: query.principalType,
-        variant: query.variant,
-        // ... additional custom fields
-      },
-    });
-  },
+  model: BaseMetaLinkModel,
+  repository: this.get<MetaLinkRepository>({ key: 'repositories.MetaLinkRepository' }),
 },
 ```
 
-When `createMetaLink` is not provided, the component uses a default implementation that stores all standard fields.
-
-#### Querying MetaLinks
-
-```typescript
-// Get all files in a bucket
-const files = await fileMetaLinkRepository.find({
-  where: { bucketName: 'user-uploads' },
-});
-
-// Get files by mimetype
-const pdfs = await fileMetaLinkRepository.find({
-  where: { mimetype: 'application/pdf' },
-});
-
-// Get files by storage type
-const minioFiles = await fileMetaLinkRepository.find({
-  where: { storageType: 'minio' },
-});
-
-// Get files by principal
-const userFiles = await fileMetaLinkRepository.find({
-  where: { principalType: 'user', principalId: '42' },
-});
-
-// Get files by variant
-const thumbnails = await fileMetaLinkRepository.find({
-  where: { variant: 'thumbnail' },
-});
-
-// Get synced files only
-const syncedFiles = await fileMetaLinkRepository.find({
-  where: { isSynced: true },
-});
-```
-
-### Quick Start Options
+See [Enable MetaLink tracking](./usage#enable-metalink-tracking) for the full repository/table/binding setup.
 
-**Option 1: MinIO Only**
-```typescript
-import {
-  StaticAssetComponent,
-  StaticAssetComponentBindingKeys,
-  StaticAssetStorageTypes,
-} from '@venizia/ignis/static-asset';
-
-this.bind({
-  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
-}).toValue({
-  cloudStorage: {
-    controller: { name: 'CloudController', basePath: '/cloud' },
-    storage: StaticAssetStorageTypes.MINIO,
-    helper: new MinioHelper({ /* ... */ }),
-    extra: { parseMultipartBody: { storage: 'memory' } },
-  },
-});
-this.component(StaticAssetComponent);
-```
+### Customize object names and links
 
-**Option 2: Local Disk Only**
-```typescript
-this.bind({
-  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
-}).toValue({
-  localStorage: {
-    controller: { name: 'LocalController', basePath: '/files' },
-    storage: StaticAssetStorageTypes.DISK,
-    helper: new DiskHelper({ basePath: './uploads' }),
-    extra: { parseMultipartBody: { storage: 'disk' } },
-  },
-});
-this.component(StaticAssetComponent);
-```
+`normalizeNameFn` runs before the file is written to storage; `normalizeLinkFn` builds the `link` value returned to the client. Both are optional - omit either to keep the component's defaults.
 
-**Option 3: Multiple Storage Backends (Recommended)**
 ```typescript
-this.bind({
-  key: StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS,
-}).toValue({
-  userUploads: {
-    controller: { name: 'UploadsController', basePath: '/uploads' },
-    storage: StaticAssetStorageTypes.MINIO,
-    helper: new MinioHelper({ /* ... */ }),
-    extra: {},
-  },
-  tempFiles: {
-    controller: { name: 'TempController', basePath: '/temp' },
-    storage: StaticAssetStorageTypes.DISK,
-    helper: new DiskHelper({ basePath: './temp' }),
-    extra: {},
-  },
-  publicAssets: {
-    controller: { name: 'PublicController', basePath: '/public' },
-    storage: StaticAssetStorageTypes.DISK,
-    helper: new DiskHelper({ basePath: './public' }),
-    extra: {},
-  },
-});
-this.component(StaticAssetComponent);
-```
-
-### Custom Filename Normalization
-
-```typescript
-{
-  uploads: {
-    controller: { name: 'UploadController', basePath: '/uploads' },
-    storage: StaticAssetStorageTypes.MINIO,
-    helper: new MinioHelper({ /* ... */ }),
-    extra: {
-      parseMultipartBody: { storage: 'memory' },
-      normalizeNameFn: ({ originalName }) => {
-        return `${Date.now()}_${originalName.toLowerCase().replace(/\s/g, '_')}`;
-      },
-      normalizeLinkFn: ({ bucketName, normalizeName }) => {
-        return `/api/files/${bucketName}/${encodeURIComponent(normalizeName)}`;
-      },
-    },
-  },
-}
+extra: {
+  normalizeNameFn: ({ originalName, folderPath }) =>
+    `${Date.now()}_${originalName.toLowerCase().replace(/\s/g, '_')}`,
+  normalizeLinkFn: ({ bucketName, normalizeName }) =>
+    `/api/files/${bucketName}/${encodeURIComponent(normalizeName)}`,
+},
 ```
 
-The `normalizeNameFn` receives only the `originalName` of the uploaded file.
-
-## Binding Keys
-
-| Key | Constant | Type | Required | Default |
-|-----|----------|------|----------|---------|
-| `@app/static-asset-component/options` | `StaticAssetComponentBindingKeys.STATIC_ASSET_COMPONENT_OPTIONS` | `TStaticAssetsComponentOptions` | Yes | `{}` |
+## See also
 
-> [!NOTE]
-> The component provides an empty default binding. You must bind this key with your storage configuration before registering the component.
+- [Usage & Examples](./usage) - task-oriented walkthroughs for every endpoint and MetaLink setup
+- [Full Reference](./api) - controller factory, `IStorageHelper` interface, MetaLink schema, internals
+- [Error Reference](./errors) - name validation rules and troubleshooting
+- [Storage Helpers](/extensions/helpers/storage/) - `DiskHelper`, `MinioHelper`, `BaseStorageHelper` reference
+- [Components Overview](/guides/core-concepts/components) - component system basics
 
-## See Also
+**Files:**
 
-- [Usage & Examples](./usage) - API Endpoints and Frontend Integration
-- [API Reference](./api) - Controller Factory, Storage Interface, MetaLink Schema
-- [Error Reference](./errors) - Name Validation and Troubleshooting
-- [Storage Helpers](/extensions/helpers/storage/) - DiskHelper, MinioHelper, BaseStorageHelper
-- [Request Utilities](/references/utilities/request) - File upload utilities
-- [Security Guidelines](/best-practices/security-guidelines) - File upload security
-- [Components Overview](/guides/core-concepts/components) - Component system basics
-- [Controllers](/guides/core-concepts/rest-controllers) - File upload endpoints
+- [`packages/core/src/components/static-asset/component.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/component.ts) - `StaticAssetComponent`
+- [`packages/core/src/components/static-asset/common/types.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/types.ts) - `TStaticAssetsComponentOptions`, `TStaticAssetExtraOptions`, `TMetaLinkConfig`
+- [`packages/core/src/components/static-asset/common/constants.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/common/constants.ts) - `StaticAssetStorageTypes`
+- [`packages/core/src/components/static-asset/controller/factory.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/controller/factory.ts) - `AssetControllerFactory`
+- [`packages/core/src/components/static-asset/models/base.model.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/core/src/components/static-asset/models/base.model.ts) - `BaseMetaLinkModel`
+- [`packages/helpers/src/modules/storage/base.ts`](https://github.com/VENIZIA-AI/ignis/blob/main/packages/helpers/src/modules/storage/base.ts) - `BaseStorageHelper`, `IStorageHelper`