@veloxts/storage 0.6.91 → 0.6.92

package/dist/drivers/local.js

@@ -7,6 +7,7 @@
 import { createReadStream, createWriteStream } from 'node:fs';
 import { mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative } from 'node:path';
+import { StorageObjectNotFoundError } from '../errors.js';
 import { detectMimeType, isReadableStream, normalizePath, toBuffer, validatePath, } from '../utils.js';
 /**
  * Default configuration for local storage.
@@ -93,6 +94,10 @@ export function createLocalStore(config) {
         }
     }
     const store = {
+        async init() {
+            // Create root directory if it doesn't exist
+            await mkdir(root, { recursive: true });
+        },
         async put(path, content, putOptions = {}) {
             const fullPath = getFullPath(path);
             await ensureDir(fullPath);
@@ -101,9 +106,20 @@ export function createLocalStore(config) {
                 // Stream content to file
                 await new Promise((resolve, reject) => {
                     const writeStream = createWriteStream(fullPath);
-                    content.pipe(writeStream);
+                    const readStream = content;
+                    // Handle errors on both streams to prevent resource leaks
+                    readStream.on('error', (err) => {
+                        writeStream.destroy();
+                        reject(err);
+                    });
+                    writeStream.on('error', (err) => {
+                        if (typeof readStream.destroy === 'function') {
+                            readStream.destroy();
+                        }
+                        reject(err);
+                    });
                     writeStream.on('finish', resolve);
-                    writeStream.on('error', reject);
+                    readStream.pipe(writeStream);
                 });
             }
             else {
@@ -236,6 +252,13 @@ export function createLocalStore(config) {
                 return null;
             }
         },
+        async head(path) {
+            const result = await store.metadata(path);
+            if (result === null) {
+                throw new StorageObjectNotFoundError(path);
+            }
+            return result;
+        },
         async list(prefix = '', listOptions = {}) {
             const { recursive = false, limit = 1000 } = listOptions;
             const files = [];
@@ -286,6 +309,12 @@ export function createLocalStore(config) {
             // In production, you'd implement a token-based verification endpoint
             return store.url(path);
         },
+        async signedUploadUrl(options) {
+            // Local storage doesn't support true presigned upload URLs
+            // Return the URL where the file would be served from
+            // In production, you'd implement a token-based upload endpoint
+            return store.url(options.key);
+        },
         async setVisibility(path, visibility) {
             const storedMeta = (await readStoredMetadata(path)) ?? {
                 visibility,

package/dist/drivers/s3.js

@@ -4,6 +4,7 @@
  * S3-compatible file storage implementation.
  * Works with AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces, and other S3-compatible services.
  */
+import { StorageObjectNotFoundError } from '../errors.js';
 import { detectMimeType, isReadableStream, joinPath, normalizePath, streamToBuffer, // Still needed for get()
 toBuffer, validatePath, } from '../utils.js';
 /**
@@ -50,7 +51,7 @@ const DEFAULT_CONFIG = {
  */
 export async function createS3Store(config) {
     const options = { ...DEFAULT_CONFIG, ...config };
-    const { bucket, region, endpoint, accessKeyId, secretAccessKey, forcePathStyle, defaultVisibility, prefix, } = options;
+    const { bucket, region, endpoint, accessKeyId, secretAccessKey, forcePathStyle, defaultVisibility, prefix, publicUrl, } = options;
     // Dynamic import of AWS SDK (peer dependency)
     const { S3Client, CopyObjectCommand, DeleteObjectCommand, DeleteObjectsCommand, GetObjectCommand, HeadObjectCommand, ListObjectsV2Command, PutObjectCommand, } = await import('@aws-sdk/client-s3');
     const { getSignedUrl } = await import('@aws-sdk/s3-request-presigner');
@@ -108,6 +109,19 @@ export async function createS3Store(config) {
     // Import Upload for streaming multipart uploads (prevents memory exhaustion for large files)
     const { Upload } = await import('@aws-sdk/lib-storage');
     const store = {
+        async init() {
+            // Verify connectivity by listing a single object
+            try {
+                await client.send(new ListObjectsV2Command({
+                    Bucket: bucket,
+                    MaxKeys: 1,
+                }));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : 'Unknown error';
+                throw new Error(`S3 storage init failed for bucket "${bucket}": ${message}`);
+            }
+        },
         async put(path, content, putOptions = {}) {
             const key = getKey(path);
             const visibility = putOptions.visibility ?? defaultVisibility ?? 'private';
@@ -229,28 +243,33 @@ export async function createS3Store(config) {
             if (paths.length === 0) {
                 return 0;
             }
-            // S3 supports batch delete of up to 1000 objects
-            const keys = paths.map((path) => ({ Key: getKey(path) }));
-            try {
-                const response = await client.send(new DeleteObjectsCommand({
-                    Bucket: bucket,
-                    Delete: {
-                        Objects: keys,
-                        Quiet: false,
-                    },
-                }));
-                return response.Deleted?.length ?? 0;
-            }
-            catch {
-                // Fall back to individual deletes if batch fails
-                let count = 0;
-                const results = await Promise.all(paths.map((path) => store.delete(path)));
-                for (const deleted of results) {
-                    if (deleted)
-                        count++;
+            // S3 supports batch delete of up to 1000 objects per request
+            const BATCH_SIZE = 1000;
+            let totalDeleted = 0;
+            // Process in batches to respect S3 API limit
+            for (let i = 0; i < paths.length; i += BATCH_SIZE) {
+                const batch = paths.slice(i, i + BATCH_SIZE);
+                const keys = batch.map((path) => ({ Key: getKey(path) }));
+                try {
+                    const response = await client.send(new DeleteObjectsCommand({
+                        Bucket: bucket,
+                        Delete: {
+                            Objects: keys,
+                            Quiet: false,
+                        },
+                    }));
+                    totalDeleted += response.Deleted?.length ?? 0;
+                }
+                catch {
+                    // Fall back to individual deletes if batch fails
+                    const results = await Promise.all(batch.map((path) => store.delete(path)));
+                    for (const deleted of results) {
+                        if (deleted)
+                            totalDeleted++;
+                    }
                 }
-                return count;
             }
+            return totalDeleted;
         },
         async copy(source, destination, copyOptions = {}) {
             const sourceKey = getKey(source);
@@ -260,8 +279,11 @@ export async function createS3Store(config) {
             const visibility = copyOptions.visibility ?? sourceMeta?.visibility ?? defaultVisibility ?? 'private';
             await client.send(new CopyObjectCommand({
                 Bucket: bucket,
-                // CopySource must be URL-encoded for special characters in paths
-                CopySource: encodeURIComponent(`${bucket}/${sourceKey}`),
+                // CopySource format: bucket/key - encode key segments but not the bucket/key separator
+                CopySource: `${bucket}/${sourceKey
+                    .split('/')
+                    .map((s) => encodeURIComponent(s))
+                    .join('/')}`,
                 Key: destKey,
                 ACL: visibilityToAcl(visibility),
             }));
@@ -294,6 +316,13 @@ export async function createS3Store(config) {
                 throw error;
             }
         },
+        async head(path) {
+            const result = await store.metadata(path);
+            if (result === null) {
+                throw new StorageObjectNotFoundError(path);
+            }
+            return result;
+        },
         async list(listPrefix = '', listOptions = {}) {
             const { recursive = false, limit = 1000, cursor } = listOptions;
             const fullPrefix = prefix ? joinPath(prefix, listPrefix) : listPrefix;
@@ -322,7 +351,18 @@ export async function createS3Store(config) {
         },
         async url(path) {
             const key = getKey(path);
-            return `${getBaseUrl()}/${key}`;
+            // URL-encode each path segment separately to preserve `/` delimiters
+            // but properly encode special characters like spaces, ?, #, etc.
+            const encodedKey = key
+                .split('/')
+                .map((segment) => encodeURIComponent(segment))
+                .join('/');
+            // Use custom publicUrl (e.g., CDN) if provided, otherwise use S3 URL
+            if (publicUrl) {
+                const base = publicUrl.endsWith('/') ? publicUrl.slice(0, -1) : publicUrl;
+                return `${base}/${encodedKey}`;
+            }
+            return `${getBaseUrl()}/${encodedKey}`;
         },
         async signedUrl(path, signedOptions = {}) {
             const key = getKey(path);
@@ -335,13 +375,26 @@ export async function createS3Store(config) {
             });
             return await getSignedUrl(client, command, { expiresIn });
         },
+        async signedUploadUrl(options) {
+            const { key, expiresIn = 3600, contentType } = options;
+            const fullKey = getKey(key);
+            const command = new PutObjectCommand({
+                Bucket: bucket,
+                Key: fullKey,
+                ContentType: contentType,
+            });
+            return await getSignedUrl(client, command, { expiresIn });
+        },
         async setVisibility(path, visibility) {
             const key = getKey(path);
             // S3 requires copying the object to itself to change ACL
             await client.send(new CopyObjectCommand({
                 Bucket: bucket,
-                // CopySource must be URL-encoded for special characters in paths
-                CopySource: encodeURIComponent(`${bucket}/${key}`),
+                // CopySource format: bucket/key - encode key segments but not the bucket/key separator
+                CopySource: `${bucket}/${key
+                    .split('/')
+                    .map((s) => encodeURIComponent(s))
+                    .join('/')}`,
                 Key: key,
                 ACL: visibilityToAcl(visibility),
                 MetadataDirective: 'COPY',

package/dist/errors.d.ts

@@ -70,6 +70,15 @@ export declare class S3Error extends StorageError {
     readonly statusCode?: number;
     constructor(operation: string, message: string, statusCode?: number);
 }
+/**
+ * Error thrown when a storage object is not found.
+ * Used by head() and similar methods that require the object to exist.
+ */
+export declare class StorageObjectNotFoundError extends StorageError {
+    readonly code = "STORAGE_OBJECT_NOT_FOUND";
+    readonly key: string;
+    constructor(key: string);
+}
 /**
  * Type guard to check if an error is a StorageError.
  */
@@ -82,3 +91,7 @@ export declare function isFileNotFoundError(error: unknown): error is FileNotFou
  * Type guard to check if an error is a PermissionDeniedError.
  */
 export declare function isPermissionDeniedError(error: unknown): error is PermissionDeniedError;
+/**
+ * Type guard to check if an error is a StorageObjectNotFoundError.
+ */
+export declare function isStorageObjectNotFoundError(error: unknown): error is StorageObjectNotFoundError;

package/dist/errors.js

@@ -99,6 +99,18 @@ export class S3Error extends StorageError {
         this.statusCode = statusCode;
     }
 }
+/**
+ * Error thrown when a storage object is not found.
+ * Used by head() and similar methods that require the object to exist.
+ */
+export class StorageObjectNotFoundError extends StorageError {
+    code = 'STORAGE_OBJECT_NOT_FOUND';
+    key;
+    constructor(key) {
+        super(`Storage object not found: ${key}`);
+        this.key = key;
+    }
+}
 /**
  * Type guard to check if an error is a StorageError.
  */
@@ -117,3 +129,9 @@ export function isFileNotFoundError(error) {
 export function isPermissionDeniedError(error) {
     return error instanceof PermissionDeniedError;
 }
+/**
+ * Type guard to check if an error is a StorageObjectNotFoundError.
+ */
+export function isStorageObjectNotFoundError(error) {
+    return error instanceof StorageObjectNotFoundError;
+}

package/dist/index.d.ts

@@ -39,10 +39,10 @@
  */
 export { createLocalStore, DRIVER_NAME as LOCAL_DRIVER } from './drivers/local.js';
 export { createS3Store, DRIVER_NAME as S3_DRIVER } from './drivers/s3.js';
-export { FileExistsError, FileNotFoundError, InvalidPathError, isFileNotFoundError, isPermissionDeniedError, isStorageError, PermissionDeniedError, QuotaExceededError, S3Error, StorageConfigError, StorageError, } from './errors.js';
+export { FileExistsError, FileNotFoundError, InvalidPathError, isFileNotFoundError, isPermissionDeniedError, isStorageError, isStorageObjectNotFoundError, PermissionDeniedError, QuotaExceededError, S3Error, StorageConfigError, StorageError, StorageObjectNotFoundError, } from './errors.js';
 export { createStorageManager, type StorageManager, storage } from './manager.js';
 export { _resetStandaloneStorage, closeStorage, 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 type { CopyOptions, FileMetadata, FileVisibility, GetOptions, ListOptions, ListResult, LocalStorageConfig, PutOptions, S3StorageConfig, SignedUploadOptions, SignedUrlOptions, StorageBaseOptions, StorageConfig, StorageDefaultOptions, StorageDriver, StorageLocalOptions, StorageManagerOptions, StoragePluginOptions, StorageProvider, StorageS3Options, StorageStore, } from './types.js';
 /**
  * Utility functions for storage operations.
  *

package/dist/index.js

@@ -41,7 +41,7 @@
 export { createLocalStore, DRIVER_NAME as LOCAL_DRIVER } from './drivers/local.js';
 export { createS3Store, DRIVER_NAME as S3_DRIVER } from './drivers/s3.js';
 // Errors
-export { FileExistsError, FileNotFoundError, InvalidPathError, isFileNotFoundError, isPermissionDeniedError, isStorageError, PermissionDeniedError, QuotaExceededError, S3Error, StorageConfigError, StorageError, } from './errors.js';
+export { FileExistsError, FileNotFoundError, InvalidPathError, isFileNotFoundError, isPermissionDeniedError, isStorageError, isStorageObjectNotFoundError, PermissionDeniedError, QuotaExceededError, S3Error, StorageConfigError, StorageError, StorageObjectNotFoundError, } from './errors.js';
 // Manager
 export { createStorageManager, storage } from './manager.js';
 // Plugin

package/dist/manager.d.ts

@@ -4,11 +4,17 @@
  * High-level file storage API with unified interface across all drivers.
  */
 import type { Readable } from 'node:stream';
-import type { CopyOptions, FileMetadata, FileVisibility, GetOptions, ListOptions, ListResult, PutOptions, SignedUrlOptions, StorageManagerOptions } from './types.js';
+import type { CopyOptions, FileMetadata, FileVisibility, GetOptions, ListOptions, ListResult, PutOptions, SignedUploadOptions, SignedUrlOptions, StorageManagerOptions } from './types.js';
 /**
  * Storage manager interface providing a unified file storage API.
  */
 export interface StorageManager {
+    /**
+     * Initialize the storage manager.
+     * Called automatically by the plugin during registration.
+     * Can be called manually when using standalone storage.
+     */
+    init(): Promise<void>;
     /**
      * Upload a file.
      *
@@ -151,6 +157,28 @@ export interface StorageManager {
      * ```
      */
     metadata(path: string): Promise<FileMetadata | null>;
+    /**
+     * Get file metadata, throwing if not found.
+     * Unlike metadata() which returns null for missing files,
+     * head() throws StorageObjectNotFoundError.
+     *
+     * @param path - File path/key
+     * @returns File metadata
+     * @throws StorageObjectNotFoundError if file does not exist
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const meta = await storage.head('uploads/image.jpg');
+     *   console.log(`Size: ${meta.size}`);
+     * } catch (error) {
+     *   if (isStorageObjectNotFoundError(error)) {
+     *     console.log('File does not exist');
+     *   }
+     * }
+     * ```
+     */
+    head(path: string): Promise<FileMetadata>;
     /**
      * List files in a directory/prefix.
      *
@@ -205,6 +233,30 @@ export interface StorageManager {
      * ```
      */
     signedUrl(path: string, options?: SignedUrlOptions): Promise<string>;
+    /**
+     * Get a signed/temporary URL for uploading a file directly to storage.
+     * Enables direct browser-to-storage uploads without proxying through the server.
+     *
+     * @param options - Signed upload URL options
+     * @returns Signed URL string for PUT upload
+     *
+     * @example
+     * ```typescript
+     * const uploadUrl = await storage.signedUploadUrl({
+     *   key: 'uploads/user-123/avatar.jpg',
+     *   contentType: 'image/jpeg',
+     *   expiresIn: 300, // 5 minutes
+     * });
+     *
+     * // Client can now PUT directly to this URL
+     * await fetch(uploadUrl, {
+     *   method: 'PUT',
+     *   body: file,
+     *   headers: { 'Content-Type': 'image/jpeg' },
+     * });
+     * ```
+     */
+    signedUploadUrl(options: SignedUploadOptions): Promise<string>;
     /**
      * Set file visibility.
      *

package/dist/manager.js

@@ -85,6 +85,7 @@ export async function createStorageManager(options = {}) {
     }
     // Create manager that delegates to the store
     const manager = {
+        init: () => store.init?.() ?? Promise.resolve(),
         put: (path, content, putOptions) => store.put(path, content, putOptions),
         get: (path, getOptions) => store.get(path, getOptions),
         stream: (path, streamOptions) => store.stream(path, streamOptions),
@@ -94,9 +95,11 @@ export async function createStorageManager(options = {}) {
         copy: (source, destination, copyOptions) => store.copy(source, destination, copyOptions),
         move: (source, destination, moveOptions) => store.move(source, destination, moveOptions),
         metadata: (path) => store.metadata(path),
+        head: (path) => store.head(path),
         list: (prefix, listOptions) => store.list(prefix, listOptions),
         url: (path) => store.url(path),
         signedUrl: (path, signedOptions) => store.signedUrl(path, signedOptions),
+        signedUploadUrl: (options) => store.signedUploadUrl(options),
         setVisibility: (path, visibility) => store.setVisibility(path, visibility),
         getVisibility: (path) => store.getVisibility(path),
         makePublic: (path) => store.setVisibility(path, 'public'),

package/dist/plugin.js

@@ -52,6 +52,8 @@ export function storagePlugin(options = {}) {
     return fp(async (fastify) => {
         // Create storage manager
         const storage = await createStorageManager(options);
+        // Initialize the storage (create directories, verify connectivity, etc.)
+        await storage.init();
         // Store on fastify instance
         fastify[STORAGE_KEY] = storage;
         // Decorate request with storage accessor

package/dist/providers/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Storage Providers
+ *
+ * Re-exports all storage provider factory functions.
+ *
+ * @example
+ * ```typescript
+ * import { r2, minio } from '@veloxts/storage/providers';
+ *
+ * // Cloudflare R2
+ * const r2Storage = await r2({
+ *   bucket: 'my-bucket',
+ *   accountId: 'xxx',
+ *   accessKeyId: 'xxx',
+ *   secretAccessKey: 'xxx',
+ * });
+ *
+ * // MinIO
+ * const minioStorage = await minio({
+ *   bucket: 'my-bucket',
+ *   endpoint: 'http://localhost:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ * ```
+ */
+export { createLocalStore, DRIVER_NAME as LOCAL_DRIVER } from '../drivers/local.js';
+export { createS3Store, DRIVER_NAME as S3_DRIVER } from '../drivers/s3.js';
+export { type MinIOConfig, minio, PROVIDER_NAME as MINIO_PROVIDER } from './minio.js';
+export { PROVIDER_NAME as R2_PROVIDER, type R2Config, r2 } from './r2.js';

package/dist/providers/index.js

@@ -0,0 +1,32 @@
+/**
+ * Storage Providers
+ *
+ * Re-exports all storage provider factory functions.
+ *
+ * @example
+ * ```typescript
+ * import { r2, minio } from '@veloxts/storage/providers';
+ *
+ * // Cloudflare R2
+ * const r2Storage = await r2({
+ *   bucket: 'my-bucket',
+ *   accountId: 'xxx',
+ *   accessKeyId: 'xxx',
+ *   secretAccessKey: 'xxx',
+ * });
+ *
+ * // MinIO
+ * const minioStorage = await minio({
+ *   bucket: 'my-bucket',
+ *   endpoint: 'http://localhost:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ * ```
+ */
+// Re-export the base drivers for convenience
+export { createLocalStore, DRIVER_NAME as LOCAL_DRIVER } from '../drivers/local.js';
+export { createS3Store, DRIVER_NAME as S3_DRIVER } from '../drivers/s3.js';
+// Provider factories
+export { minio, PROVIDER_NAME as MINIO_PROVIDER } from './minio.js';
+export { PROVIDER_NAME as R2_PROVIDER, r2 } from './r2.js';

package/dist/providers/minio.d.ts

@@ -0,0 +1,74 @@
+/**
+ * MinIO Storage Provider
+ *
+ * Factory function that creates an S3-compatible storage store configured
+ * for MinIO.
+ */
+import { z } from 'zod';
+import type { StorageStore } from '../types.js';
+/**
+ * MinIO configuration schema.
+ */
+declare const MinIOConfigSchema: z.ZodObject<{
+    /** MinIO bucket name */
+    bucket: z.ZodString;
+    /** MinIO endpoint (e.g., 'http://localhost:9000') */
+    endpoint: z.ZodString;
+    /** MinIO access key ID */
+    accessKeyId: z.ZodString;
+    /** MinIO secret access key */
+    secretAccessKey: z.ZodString;
+    /** AWS region (default: 'us-east-1') */
+    region: z.ZodDefault<z.ZodString>;
+    /** Custom public URL for accessing files */
+    publicUrl: z.ZodOptional<z.ZodString>;
+    /** Key prefix for all operations */
+    prefix: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    bucket: string;
+    region: string;
+    endpoint: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    prefix?: string | undefined;
+    publicUrl?: string | undefined;
+}, {
+    bucket: string;
+    endpoint: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    region?: string | undefined;
+    prefix?: string | undefined;
+    publicUrl?: string | undefined;
+}>;
+/**
+ * MinIO configuration options.
+ */
+export type MinIOConfig = z.input<typeof MinIOConfigSchema>;
+/**
+ * Create a MinIO storage store.
+ *
+ * @param config - MinIO configuration
+ * @returns Storage store implementation
+ *
+ * @example
+ * ```typescript
+ * import { minio } from '@veloxts/storage/providers/minio';
+ *
+ * const storage = await minio({
+ *   bucket: 'my-bucket',
+ *   endpoint: 'http://localhost:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ *
+ * await storage.init();
+ * await storage.put('uploads/file.txt', 'Hello World');
+ * ```
+ */
+export declare function minio(config: MinIOConfig): Promise<StorageStore>;
+/**
+ * MinIO provider name identifier.
+ */
+export declare const PROVIDER_NAME: "minio";
+export {};

package/dist/providers/minio.js

@@ -0,0 +1,68 @@
+/**
+ * MinIO Storage Provider
+ *
+ * Factory function that creates an S3-compatible storage store configured
+ * for MinIO.
+ */
+import { z } from 'zod';
+import { createS3Store } from '../drivers/s3.js';
+/**
+ * MinIO configuration schema.
+ */
+const MinIOConfigSchema = z.object({
+    /** MinIO bucket name */
+    bucket: z.string().min(1, 'Bucket name is required'),
+    /** MinIO endpoint (e.g., 'http://localhost:9000') */
+    endpoint: z.string().url('Endpoint must be a valid URL'),
+    /** MinIO access key ID */
+    accessKeyId: z.string().min(1, 'Access key ID is required'),
+    /** MinIO secret access key */
+    secretAccessKey: z.string().min(1, 'Secret access key is required'),
+    /** AWS region (default: 'us-east-1') */
+    region: z.string().default('us-east-1'),
+    /** Custom public URL for accessing files */
+    publicUrl: z.string().url().optional(),
+    /** Key prefix for all operations */
+    prefix: z.string().optional(),
+});
+/**
+ * Create a MinIO storage store.
+ *
+ * @param config - MinIO configuration
+ * @returns Storage store implementation
+ *
+ * @example
+ * ```typescript
+ * import { minio } from '@veloxts/storage/providers/minio';
+ *
+ * const storage = await minio({
+ *   bucket: 'my-bucket',
+ *   endpoint: 'http://localhost:9000',
+ *   accessKeyId: 'minioadmin',
+ *   secretAccessKey: 'minioadmin',
+ * });
+ *
+ * await storage.init();
+ * await storage.put('uploads/file.txt', 'Hello World');
+ * ```
+ */
+export async function minio(config) {
+    // Validate configuration with Zod
+    const validated = MinIOConfigSchema.parse(config);
+    // Create S3-compatible store with MinIO-specific configuration
+    return createS3Store({
+        driver: 's3',
+        bucket: validated.bucket,
+        region: validated.region,
+        endpoint: validated.endpoint,
+        accessKeyId: validated.accessKeyId,
+        secretAccessKey: validated.secretAccessKey,
+        forcePathStyle: true, // MinIO requires path-style URLs
+        prefix: validated.prefix,
+        publicUrl: validated.publicUrl,
+    });
+}
+/**
+ * MinIO provider name identifier.
+ */
+export const PROVIDER_NAME = 'minio';