@veloxts/storage 0.6.87 → 0.6.89

package/GUIDE.md

@@ -1,43 +1,61 @@
 # @veloxts/storage Guide
 
-## Drivers
+File storage abstraction for VeloxTS applications with support for local filesystem and S3-compatible storage (AWS S3, Cloudflare R2, MinIO).
 
-### Local Driver (default)
+## Installation
 
-Store files on the local filesystem.
+```bash
+pnpm add @veloxts/storage
+
+# For S3/R2 (production)
+pnpm add @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
+```
+
+## Quick Start
+
+### Development (Local)
 
 ```typescript
+import { veloxApp } from '@veloxts/core';
 import { storagePlugin } from '@veloxts/storage';
 
-app.use(storagePlugin({
+const app = veloxApp();
+
+app.register(storagePlugin({
   driver: 'local',
   config: {
     root: './storage',
     baseUrl: 'http://localhost:3030/files',
   },
 }));
+
+await app.start();
 ```
 
-### S3 Driver
+### Production (AWS S3)
 
-S3-compatible storage (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces).
+```typescript
+import { veloxApp } from '@veloxts/core';
+import { storagePlugin } from '@veloxts/storage';
 
-```bash
-npm install @aws-sdk/client-s3 @aws-sdk/lib-storage @aws-sdk/s3-request-presigner
-```
+const app = veloxApp();
 
-```typescript
-// AWS S3
-app.use(storagePlugin({
+app.register(storagePlugin({
   driver: 's3',
   config: {
     bucket: process.env.S3_BUCKET,
-    region: 'us-east-1',
+    region: process.env.S3_REGION,
+    // Uses AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY from env
   },
 }));
 
-// Cloudflare R2
-app.use(storagePlugin({
+await app.start();
+```
+
+### Production (Cloudflare R2)
+
+```typescript
+app.register(storagePlugin({
   driver: 's3',
   config: {
     bucket: process.env.R2_BUCKET,
@@ -47,19 +65,22 @@ app.use(storagePlugin({
     secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
   },
 }));
+```
 
-// MinIO (local S3)
-app.use(storagePlugin({
-  driver: 's3',
-  config: {
-    bucket: 'my-bucket',
-    region: 'us-east-1',
-    endpoint: 'http://localhost:9000',
-    forcePathStyle: true,
-    accessKeyId: 'minioadmin',
-    secretAccessKey: 'minioadmin',
-  },
-}));
+**Environment Variables:**
+
+```bash
+# .env (AWS S3)
+S3_BUCKET=my-bucket
+S3_REGION=us-east-1
+AWS_ACCESS_KEY_ID=AKIA...
+AWS_SECRET_ACCESS_KEY=...
+
+# .env (Cloudflare R2)
+R2_BUCKET=my-bucket
+R2_ACCOUNT_ID=your-account-id
+R2_ACCESS_KEY_ID=...
+R2_SECRET_ACCESS_KEY=...
 ```
 
 ## Basic Operations
@@ -77,7 +98,7 @@ await ctx.storage.put('videos/large.mp4', readableStream);
 // Download a file
 const content = await ctx.storage.get('documents/report.pdf');
 
-// Stream a file (memory-efficient for large files)
+// Stream a file (memory-efficient)
 const stream = await ctx.storage.stream('videos/large.mp4');
 
 // Check if file exists
@@ -98,7 +119,7 @@ const url = await ctx.storage.url('avatars/user-123.jpg');
 
 // Signed URL (temporary access to private files)
 const signedUrl = await ctx.storage.signedUrl('documents/private.pdf', {
-  expiresIn: 3600, // 1 hour
+  expiresIn: 3600, // 1 hour in seconds
 });
 ```
 
@@ -143,3 +164,79 @@ do {
 // Set visibility
 await ctx.storage.setVisibility('file.jpg', 'public');  // or 'private'
 ```
+
+## Production Deployment
+
+### Choosing a Provider
+
+| Provider | Best For |
+|----------|----------|
+| [Cloudflare R2](https://developers.cloudflare.com/r2/) | Zero egress fees, global edge |
+| [AWS S3](https://aws.amazon.com/s3/) | Mature ecosystem, extensive features |
+| [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces) | Simple pricing, S3-compatible |
+| [MinIO](https://min.io/) | Self-hosted, S3-compatible |
+
+### Production Checklist
+
+1. **Use S3-compatible storage** - Local filesystem doesn't scale
+2. **Configure bucket policies** - Least privilege access
+3. **Set proper CORS** - For direct browser uploads
+4. **Use signed URLs for private files** - Time-limited access
+5. **Enable versioning** - For critical files (optional)
+
+### Complete S3 Configuration
+
+```typescript
+app.register(storagePlugin({
+  driver: 's3',
+  config: {
+    bucket: process.env.S3_BUCKET,
+    region: process.env.S3_REGION,
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+
+    // Optional settings
+    endpoint: process.env.S3_ENDPOINT,      // For R2, MinIO, etc.
+    forcePathStyle: false,                   // true for MinIO
+    defaultVisibility: 'private',
+  },
+}));
+```
+
+### Serving Files in Production
+
+For public files, use a CDN in front of your storage:
+
+```typescript
+app.register(storagePlugin({
+  driver: 's3',
+  config: {
+    bucket: process.env.S3_BUCKET,
+    region: process.env.S3_REGION,
+    publicUrl: 'https://cdn.example.com',  // CDN URL
+  },
+}));
+```
+
+## Standalone Usage
+
+Use storage outside of Fastify request context (CLI commands, background jobs):
+
+```typescript
+import { getStorage, closeStorage } from '@veloxts/storage';
+
+// Get standalone storage instance
+const storage = await getStorage({
+  driver: 's3',
+  config: {
+    bucket: process.env.S3_BUCKET,
+    region: process.env.S3_REGION,
+  },
+});
+
+await storage.put('file.txt', Buffer.from('Hello'));
+const content = await storage.get('file.txt');
+
+// Clean up when done
+await closeStorage();
+```

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export { createLocalStore, DRIVER_NAME as LOCAL_DRIVER } from './drivers/local.j
 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 { createStorageManager, type StorageManager, storage } from './manager.js';
-export { _resetStandaloneStorage, getStorage, getStorageFromInstance, storagePlugin, } from './plugin.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';
 /**
  * Utility functions for storage operations.

package/dist/index.js

@@ -45,7 +45,7 @@ export { FileExistsError, FileNotFoundError, InvalidPathError, isFileNotFoundErr
 // Manager
 export { createStorageManager, storage } from './manager.js';
 // Plugin
-export { _resetStandaloneStorage, getStorage, getStorageFromInstance, storagePlugin, } from './plugin.js';
+export { _resetStandaloneStorage, closeStorage, getStorage, getStorageFromInstance, storagePlugin, } from './plugin.js';
 /**
  * Utility functions for storage operations.
  *

package/dist/plugin.d.ts

@@ -100,8 +100,24 @@ export declare function getStorageFromInstance(fastify: FastifyInstance): Storag
  * ```
  */
 export declare function getStorage(options?: StoragePluginOptions): Promise<StorageManager>;
+/**
+ * Close the standalone storage instance.
+ *
+ * Call this when shutting down your application to release resources.
+ *
+ * @example
+ * ```typescript
+ * import { closeStorage } from '@veloxts/storage';
+ *
+ * // On shutdown
+ * await closeStorage();
+ * ```
+ */
+export declare function closeStorage(): Promise<void>;
 /**
  * Reset the standalone storage instance.
  * Primarily used for testing.
+ *
+ * @deprecated Use `closeStorage()` instead. Will be removed in v2.0.
  */
 export declare function _resetStandaloneStorage(): Promise<void>;

package/dist/plugin.js

@@ -121,12 +121,30 @@ export async function getStorage(options) {
     return standaloneStorage;
 }
 /**
- * Reset the standalone storage instance.
- * Primarily used for testing.
+ * Close the standalone storage instance.
+ *
+ * Call this when shutting down your application to release resources.
+ *
+ * @example
+ * ```typescript
+ * import { closeStorage } from '@veloxts/storage';
+ *
+ * // On shutdown
+ * await closeStorage();
+ * ```
  */
-export async function _resetStandaloneStorage() {
+export async function closeStorage() {
     if (standaloneStorage) {
         await standaloneStorage.close();
         standaloneStorage = null;
     }
 }
+/**
+ * Reset the standalone storage instance.
+ * Primarily used for testing.
+ *
+ * @deprecated Use `closeStorage()` instead. Will be removed in v2.0.
+ */
+export async function _resetStandaloneStorage() {
+    await closeStorage();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/storage",
-  "version": "0.6.87",
+  "version": "0.6.89",
   "description": "Multi-driver file storage abstraction for VeloxTS framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -32,7 +32,7 @@
   "dependencies": {
     "fastify-plugin": "5.1.0",
     "mime-types": "2.1.35",
-    "@veloxts/core": "0.6.87"
+    "@veloxts/core": "0.6.89"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": ">=3.0.0",
@@ -56,12 +56,12 @@
     "@aws-sdk/lib-storage": "3.821.0",
     "@aws-sdk/s3-request-presigner": "3.821.0",
     "@types/mime-types": "2.1.4",
-    "@types/node": "22.15.29",
+    "@types/node": "25.0.3",
     "@vitest/coverage-v8": "4.0.16",
     "fastify": "5.6.2",
-    "typescript": "5.8.3",
+    "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.87"
+    "@veloxts/testing": "0.6.89"
   },
   "publishConfig": {
     "access": "public"