@veloxts/storage 0.6.56 → 0.6.57

package/dist/index.d.ts

@@ -44,3 +44,25 @@ export { createStorageManager, type StorageManager, storage } from './manager.js
 export { _resetStandaloneStorage, getStorage, getStorageFromInstance, storagePlugin, } from './plugin.js';
 export type { CopyOptions, FileMetadata, FileVisibility, GetOptions, ListOptions, ListResult, LocalStorageConfig, PutOptions, S3StorageConfig, SignedUrlOptions, StorageBaseOptions, StorageConfig, StorageDefaultOptions, StorageDriver, StorageLocalOptions, StorageManagerOptions, StoragePluginOptions, StorageS3Options, StorageStore, } from './types.js';
 export { basename, detectMimeType, dirname, extname, formatBytes, joinPath, normalizePath, uniqueFileName, validatePath, } from './utils.js';
+/**
+ * DI tokens and providers for @veloxts/storage
+ *
+ * Use these to integrate storage services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads' },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+export { registerStorageProviders } from './providers.js';
+export { STORAGE_CONFIG, STORAGE_MANAGER, STORAGE_STORE } from './tokens.js';

package/dist/index.js

@@ -48,3 +48,30 @@ export { createStorageManager, storage } from './manager.js';
 export { _resetStandaloneStorage, getStorage, getStorageFromInstance, storagePlugin, } from './plugin.js';
 // Utilities
 export { basename, detectMimeType, dirname, extname, formatBytes, joinPath, normalizePath, uniqueFileName, validatePath, } from './utils.js';
+// ============================================================================
+// Dependency Injection
+// ============================================================================
+/**
+ * DI tokens and providers for @veloxts/storage
+ *
+ * Use these to integrate storage services with the @veloxts/core DI container.
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads' },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+// Provider exports - factory functions for registering services
+export { registerStorageProviders } from './providers.js';
+// Token exports - unique identifiers for DI resolution
+export { STORAGE_CONFIG, STORAGE_MANAGER, STORAGE_STORE } from './tokens.js';

package/dist/providers.d.ts

@@ -0,0 +1,65 @@
+/**
+ * DI Providers for @veloxts/storage
+ *
+ * Factory provider functions for registering storage services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module storage/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads' },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+import type { Container } from '@veloxts/core';
+import type { StoragePluginOptions } from './types.js';
+/**
+ * Registers storage providers with a container
+ *
+ * This handles async initialization of the storage manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Storage plugin options (driver, config, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ *
+ * // Local filesystem driver
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads', baseUrl: '/files' },
+ * });
+ *
+ * // S3-compatible driver (AWS S3, Cloudflare R2, MinIO)
+ * await registerStorageProviders(container, {
+ *   driver: 's3',
+ *   config: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-east-1',
+ *     credentials: {
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *     },
+ *   },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('avatars/user-123.jpg', imageBuffer);
+ * ```
+ */
+export declare function registerStorageProviders(container: Container, config?: StoragePluginOptions): Promise<void>;

package/dist/providers.js

@@ -0,0 +1,82 @@
+/**
+ * DI Providers for @veloxts/storage
+ *
+ * Factory provider functions for registering storage services with the DI container.
+ * These providers allow services to be managed by the container for testability and flexibility.
+ *
+ * @module storage/providers
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads' },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+import { createStorageManager } from './manager.js';
+import { STORAGE_CONFIG, STORAGE_MANAGER } from './tokens.js';
+// ============================================================================
+// Bulk Registration Helpers
+// ============================================================================
+/**
+ * Registers storage providers with a container
+ *
+ * This handles async initialization of the storage manager and registers
+ * the resolved instance directly for synchronous resolution.
+ *
+ * @param container - The DI container to register providers with
+ * @param config - Storage plugin options (driver, config, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { registerStorageProviders, STORAGE_MANAGER } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ *
+ * // Local filesystem driver
+ * await registerStorageProviders(container, {
+ *   driver: 'local',
+ *   config: { root: './uploads', baseUrl: '/files' },
+ * });
+ *
+ * // S3-compatible driver (AWS S3, Cloudflare R2, MinIO)
+ * await registerStorageProviders(container, {
+ *   driver: 's3',
+ *   config: {
+ *     bucket: 'my-bucket',
+ *     region: 'us-east-1',
+ *     credentials: {
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+ *     },
+ *   },
+ * });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('avatars/user-123.jpg', imageBuffer);
+ * ```
+ */
+export async function registerStorageProviders(container, config = {}) {
+    // Register config
+    container.register({
+        provide: STORAGE_CONFIG,
+        useValue: config,
+    });
+    // Create storage manager (async operation)
+    const storageManager = await createStorageManager(config);
+    // Register the resolved storage manager instance directly
+    // This allows synchronous resolution from the container
+    container.register({
+        provide: STORAGE_MANAGER,
+        useValue: storageManager,
+    });
+}

package/dist/tokens.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DI Tokens for @veloxts/storage
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow storage services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module storage/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { STORAGE_MANAGER, registerStorageProviders } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, { driver: 'local', config: { root: './uploads' } });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+import type { StorageManager } from './manager.js';
+import type { StoragePluginOptions, StorageStore } from './types.js';
+/**
+ * Storage manager token
+ *
+ * The main storage manager instance for file operations.
+ *
+ * @example
+ * ```typescript
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('avatars/user-123.jpg', imageBuffer);
+ * const url = await storage.url('avatars/user-123.jpg');
+ * ```
+ */
+export declare const STORAGE_MANAGER: import("@veloxts/core").SymbolToken<StorageManager>;
+/**
+ * Storage store token
+ *
+ * The underlying storage driver (local filesystem or S3-compatible).
+ * Use STORAGE_MANAGER for high-level operations; use this for direct driver access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(STORAGE_STORE);
+ * await store.put('file.txt', Buffer.from('content'), { visibility: 'public' });
+ * ```
+ */
+export declare const STORAGE_STORE: import("@veloxts/core").SymbolToken<StorageStore>;
+/**
+ * Storage configuration token
+ *
+ * Contains storage plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(STORAGE_CONFIG);
+ * console.log(config.driver); // 'local' or 's3'
+ * ```
+ */
+export declare const STORAGE_CONFIG: import("@veloxts/core").SymbolToken<StoragePluginOptions>;

package/dist/tokens.js

@@ -0,0 +1,65 @@
+/**
+ * DI Tokens for @veloxts/storage
+ *
+ * Symbol-based tokens for type-safe dependency injection.
+ * These tokens allow storage services to be registered, resolved, and mocked via the DI container.
+ *
+ * @module storage/tokens
+ *
+ * @example
+ * ```typescript
+ * import { Container } from '@veloxts/core';
+ * import { STORAGE_MANAGER, registerStorageProviders } from '@veloxts/storage';
+ *
+ * const container = new Container();
+ * await registerStorageProviders(container, { driver: 'local', config: { root: './uploads' } });
+ *
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('file.txt', Buffer.from('Hello'));
+ * ```
+ */
+import { token } from '@veloxts/core';
+// ============================================================================
+// Core Storage Tokens
+// ============================================================================
+/**
+ * Storage manager token
+ *
+ * The main storage manager instance for file operations.
+ *
+ * @example
+ * ```typescript
+ * const storage = container.resolve(STORAGE_MANAGER);
+ * await storage.put('avatars/user-123.jpg', imageBuffer);
+ * const url = await storage.url('avatars/user-123.jpg');
+ * ```
+ */
+export const STORAGE_MANAGER = token.symbol('STORAGE_MANAGER');
+/**
+ * Storage store token
+ *
+ * The underlying storage driver (local filesystem or S3-compatible).
+ * Use STORAGE_MANAGER for high-level operations; use this for direct driver access.
+ *
+ * @example
+ * ```typescript
+ * const store = container.resolve(STORAGE_STORE);
+ * await store.put('file.txt', Buffer.from('content'), { visibility: 'public' });
+ * ```
+ */
+export const STORAGE_STORE = token.symbol('STORAGE_STORE');
+// ============================================================================
+// Configuration Tokens
+// ============================================================================
+/**
+ * Storage configuration token
+ *
+ * Contains storage plugin options including driver and driver-specific config.
+ *
+ * @example
+ * ```typescript
+ * const config = container.resolve(STORAGE_CONFIG);
+ * console.log(config.driver); // 'local' or 's3'
+ * ```
+ */
+export const STORAGE_CONFIG = token.symbol('STORAGE_CONFIG');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/storage",
-  "version": "0.6.56",
+  "version": "0.6.57",
   "description": "Multi-driver file storage abstraction for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
   "dependencies": {
     "fastify-plugin": "5.1.0",
     "mime-types": "2.1.35",
-    "@veloxts/core": "0.6.56"
+    "@veloxts/core": "0.6.57"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.0.0",
@@ -57,7 +57,7 @@
     "fastify": "5.6.2",
     "typescript": "5.8.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.56"
+    "@veloxts/testing": "0.6.57"
   },
   "publishConfig": {
     "access": "public"