@bloomneo/appkit 1.2.9

package/dist/storage/index.js

@@ -0,0 +1,242 @@
+/**
+ * Ultra-simple file storage that just works with automatic Local/S3/R2 strategy
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/index.ts
+ *
+ * @llm-rule WHEN: Building apps that need file storage with zero configuration
+ * @llm-rule AVOID: Complex storage setups - this auto-detects Local/S3/R2 from environment
+ * @llm-rule NOTE: Uses storageClass.get() pattern like auth - get() → storage.put() → distributed
+ * @llm-rule NOTE: Common pattern - storageClass.get() → storage.put() → storage.url() → served
+ */
+import { StorageClass } from './storage.js';
+import { getSmartDefaults } from './defaults.js';
+// Global storage instance for performance (like auth module)
+let globalStorage = null;
+/**
+ * Get storage instance - the only function you need to learn
+ * Strategy auto-detected from environment (S3/R2 env vars → Cloud, nothing → Local)
+ * @llm-rule WHEN: Need file storage in any part of your app - this is your main entry point
+ * @llm-rule AVOID: Creating StorageClass directly - always use this function
+ * @llm-rule NOTE: Typical flow - get() → storage.put() → storage.url() → file served
+ */
+function get(overrides = {}) {
+    // Lazy initialization - parse environment once (like auth)
+    if (!globalStorage) {
+        const defaults = getSmartDefaults();
+        const config = { ...defaults, ...overrides };
+        globalStorage = new StorageClass(config);
+    }
+    return globalStorage;
+}
+/**
+ * Clear storage instance and disconnect - essential for testing
+ * @llm-rule WHEN: Testing storage logic with different configurations or app shutdown
+ * @llm-rule AVOID: Using in production except for graceful shutdown
+ */
+async function clear() {
+    if (globalStorage) {
+        await globalStorage.disconnect();
+        globalStorage = null;
+    }
+}
+/**
+ * Reset storage configuration (useful for testing)
+ * @llm-rule WHEN: Testing storage logic with different environment configurations
+ * @llm-rule AVOID: Using in production - only for tests and development
+ */
+function reset(newConfig = {}) {
+    // Clear existing instance
+    if (globalStorage) {
+        globalStorage.disconnect().catch(console.error);
+        globalStorage = null;
+    }
+    // Create new instance with config
+    const defaults = getSmartDefaults();
+    const config = { ...defaults, ...newConfig };
+    globalStorage = new StorageClass(config);
+    return globalStorage;
+}
+/**
+ * Get active storage strategy for debugging
+ * @llm-rule WHEN: Debugging or health checks to see which strategy is active (Local vs S3 vs R2)
+ * @llm-rule AVOID: Using for application logic - storage should be transparent
+ */
+function getStrategy() {
+    const storage = get();
+    return storage.getStrategy();
+}
+/**
+ * Get storage configuration summary for debugging
+ * @llm-rule WHEN: Health checks or debugging storage configuration
+ * @llm-rule AVOID: Exposing sensitive connection details - this only shows safe info
+ */
+function getConfig() {
+    const storage = get();
+    return storage.getConfig();
+}
+/**
+ * Check if cloud storage is available and configured
+ * @llm-rule WHEN: Conditional logic based on storage capabilities
+ * @llm-rule AVOID: Complex storage detection - just use storage normally, strategy handles it
+ */
+function hasCloudStorage() {
+    const strategy = getStrategy();
+    return strategy === 's3' || strategy === 'r2';
+}
+/**
+ * Check if local storage is being used
+ * @llm-rule WHEN: Development vs production feature detection
+ * @llm-rule AVOID: Using for business logic - storage should be transparent
+ */
+function isLocal() {
+    return getStrategy() === 'local';
+}
+/**
+ * Validate storage configuration at startup
+ * @llm-rule WHEN: App startup to ensure storage is properly configured
+ * @llm-rule AVOID: Skipping validation - missing storage config causes runtime failures
+ */
+function validateConfig() {
+    try {
+        const strategy = getStrategy();
+        if (strategy === 'local' && process.env.NODE_ENV === 'production') {
+            console.warn('[VoilaJSX AppKit] Using local storage in production. ' +
+                'Files will only exist on single server instance. ' +
+                'Set AWS_S3_BUCKET or CLOUDFLARE_R2_BUCKET for distributed storage.');
+        }
+        if (process.env.NODE_ENV === 'production' && !hasCloudStorage()) {
+            console.warn('[VoilaJSX AppKit] No cloud storage configured in production. ' +
+                'Set AWS_S3_BUCKET or CLOUDFLARE_R2_BUCKET for scalable file storage.');
+        }
+    }
+    catch (error) {
+        console.error('[VoilaJSX AppKit] Storage configuration validation failed:', error.message);
+    }
+}
+/**
+ * Get storage statistics for monitoring
+ * @llm-rule WHEN: Monitoring storage system health and usage
+ * @llm-rule AVOID: Using for business logic - this is for monitoring only
+ */
+function getStats() {
+    const config = getConfig();
+    return {
+        strategy: config.strategy,
+        connected: config.connected,
+        maxFileSize: `${Math.round(config.maxFileSize / 1048576)}MB`,
+        environment: process.env.NODE_ENV || 'development',
+    };
+}
+/**
+ * Graceful shutdown for storage system
+ * @llm-rule WHEN: App shutdown or process termination
+ * @llm-rule AVOID: Abrupt process exit - graceful shutdown prevents data corruption
+ */
+async function shutdown() {
+    console.log('🔄 [AppKit] Storage graceful shutdown...');
+    try {
+        await clear();
+        console.log('✅ [AppKit] Storage shutdown complete');
+    }
+    catch (error) {
+        console.error('❌ [AppKit] Storage shutdown error:', error.message);
+    }
+}
+/**
+ * Upload helper with common patterns
+ * @llm-rule WHEN: Quick file uploads with automatic naming and validation
+ * @llm-rule AVOID: Manual key generation - this handles common upload patterns
+ */
+async function upload(file, options) {
+    const storage = get();
+    // Generate key with folder structure
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 8);
+    const folder = options?.folder ? `${options.folder}/` : '';
+    const filename = options?.filename || `file-${timestamp}-${random}`;
+    const key = `${folder}${filename}`;
+    // Upload file
+    const resultKey = await storage.put(key, file, {
+        contentType: options?.contentType,
+    });
+    // Get public URL
+    const url = storage.url(resultKey);
+    return { key: resultKey, url };
+}
+/**
+ * Download helper with error handling
+ * @llm-rule WHEN: Quick file downloads with automatic error handling
+ * @llm-rule AVOID: Manual error handling - this provides consistent download experience
+ */
+async function download(key) {
+    const storage = get();
+    try {
+        const data = await storage.get(key);
+        // Try to determine content type from extension
+        const ext = key.split('.').pop()?.toLowerCase();
+        const contentTypes = {
+            'jpg': 'image/jpeg',
+            'jpeg': 'image/jpeg',
+            'png': 'image/png',
+            'gif': 'image/gif',
+            'pdf': 'application/pdf',
+            'txt': 'text/plain',
+            'json': 'application/json',
+        };
+        return {
+            data,
+            contentType: ext ? contentTypes[ext] : undefined,
+        };
+    }
+    catch (error) {
+        throw new Error(`Failed to download file: ${key}`);
+    }
+}
+/**
+ * Single storage export with minimal API (like auth module)
+ */
+export const storageClass = {
+    // Core method (like auth.get())
+    get,
+    // Utility methods
+    clear,
+    reset,
+    getStrategy,
+    getConfig,
+    hasCloudStorage,
+    isLocal,
+    getStats,
+    validateConfig,
+    shutdown,
+    // Helper methods
+    upload,
+    download,
+};
+export { StorageClass } from './storage.js';
+// Default export
+export default StorageClass;
+// Auto-setup graceful shutdown handlers
+if (typeof process !== 'undefined') {
+    // Handle graceful shutdown
+    const shutdownHandler = () => {
+        shutdown().finally(() => {
+            process.exit(0);
+        });
+    };
+    process.on('SIGTERM', shutdownHandler);
+    process.on('SIGINT', shutdownHandler);
+    // Handle uncaught errors
+    process.on('uncaughtException', (error) => {
+        console.error('[AppKit] Uncaught exception during storage operation:', error);
+        shutdown().finally(() => {
+            process.exit(1);
+        });
+    });
+    process.on('unhandledRejection', (reason) => {
+        console.error('[AppKit] Unhandled rejection during storage operation:', reason);
+        shutdown().finally(() => {
+            process.exit(1);
+        });
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"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"}

package/dist/storage/storage.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Core storage class with automatic strategy selection and ultra-simple API
+ * @module @bloomneo/appkit/storage
+ * @file src/storage/storage.ts
+ *
+ * @llm-rule WHEN: Building apps that need file storage with automatic Local/S3/R2 selection
+ * @llm-rule AVOID: Using directly - always get instance via storageClass.get()
+ * @llm-rule NOTE: Auto-detects Local vs S3 vs R2 based on environment variables
+ */
+import type { StorageConfig } from './defaults.js';
+export interface StorageStrategy {
+    put(key: string, data: Buffer | Uint8Array | string): Promise<string>;
+    get(key: string): Promise<Buffer>;
+    delete(key: string): Promise<boolean>;
+    list(prefix: string): Promise<StorageFile[]>;
+    url(key: string): string;
+    signedUrl?(key: string, expiresIn?: number): Promise<string>;
+    exists(key: string): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+export interface StorageFile {
+    key: string;
+    size: number;
+    lastModified: Date;
+    etag?: string;
+    contentType?: string;
+}
+export interface PutOptions {
+    contentType?: string;
+    metadata?: Record<string, string>;
+    cacheControl?: string;
+    expires?: Date;
+}
+/**
+ * Storage class with automatic strategy selection and ultra-simple API
+ */
+export declare class StorageClass {
+    config: StorageConfig;
+    private strategy;
+    private connected;
+    constructor(config: StorageConfig);
+    /**
+     * Creates appropriate strategy based on configuration
+     * @llm-rule WHEN: Storage initialization - selects Local, S3, or R2 based on environment
+     * @llm-rule AVOID: Manual strategy creation - configuration handles strategy selection
+     */
+    private createStrategy;
+    /**
+     * Connects to storage backend with automatic setup
+     * @llm-rule WHEN: Storage initialization or reconnection after failure
+     * @llm-rule AVOID: Manual connection management - this handles connection state
+     */
+    connect(): Promise<void>;
+    /**
+     * Disconnects from storage backend gracefully
+     * @llm-rule WHEN: App shutdown or storage cleanup
+     * @llm-rule AVOID: Abrupt disconnection - graceful shutdown prevents data loss
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Stores file with automatic validation and type detection
+     * @llm-rule WHEN: Uploading files to storage backend
+     * @llm-rule AVOID: Manual file validation - this handles size, type, and path validation
+     * @llm-rule NOTE: Returns the key/path where file was stored
+     */
+    put(key: string, data: Buffer | Uint8Array | string, options?: PutOptions): Promise<string>;
+    /**
+     * Retrieves file with automatic error handling
+     * @llm-rule WHEN: Downloading files from storage backend
+     * @llm-rule AVOID: Manual error handling - this provides consistent error messages
+     */
+    get(key: string): Promise<Buffer>;
+    /**
+     * Deletes file with confirmation
+     * @llm-rule WHEN: Removing files from storage backend
+     * @llm-rule AVOID: Silent failures - this confirms deletion success
+     */
+    delete(key: string): Promise<boolean>;
+    /**
+     * Lists files with prefix filtering and metadata
+     * @llm-rule WHEN: Browsing files or implementing file managers
+     * @llm-rule AVOID: Loading all files - use prefix filtering for performance
+     */
+    list(prefix?: string, limit?: number): Promise<StorageFile[]>;
+    /**
+     * Gets public URL for file access
+     * @llm-rule WHEN: Generating URLs for file access in web applications
+     * @llm-rule AVOID: Hardcoding URLs - this handles CDN and strategy-specific URLs
+     */
+    url(key: string): string;
+    /**
+     * Generates signed URL for temporary access
+     * @llm-rule WHEN: Creating temporary download links or private file access
+     * @llm-rule AVOID: Permanent URLs for private files - use signed URLs with expiration
+     */
+    signedUrl(key: string, expiresIn?: number): Promise<string>;
+    /**
+     * Checks if file exists without downloading
+     * @llm-rule WHEN: Validating file existence before operations
+     * @llm-rule AVOID: Downloading files just to check existence - this is more efficient
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * Copies file from one location to another
+     * @llm-rule WHEN: Duplicating files or moving between folders
+     * @llm-rule AVOID: Download and upload - this uses efficient copy operations when possible
+     */
+    copy(sourceKey: string, destKey: string): Promise<string>;
+    /**
+     * Gets current storage strategy name for debugging
+     * @llm-rule WHEN: Debugging or health checks to see which strategy is active
+     * @llm-rule AVOID: Using for application logic - storage should be transparent
+     */
+    getStrategy(): string;
+    /**
+     * Gets storage configuration summary for debugging
+     * @llm-rule WHEN: Health checks or debugging storage configuration
+     * @llm-rule AVOID: Exposing sensitive details - this only shows safe info
+     */
+    getConfig(): {
+        strategy: string;
+        connected: boolean;
+        maxFileSize: number;
+        allowedTypes: string[];
+    };
+    /**
+     * Ensures storage system is connected before operations
+     */
+    private ensureConnected;
+    /**
+     * Validates storage key format and security
+     */
+    private validateKey;
+    /**
+     * Normalizes input data to Buffer
+     */
+    private normalizeData;
+    /**
+     * Validates file size against configured limits
+     */
+    private validateFileSize;
+    /**
+     * Detects content type from file extension and buffer
+     */
+    private detectContentType;
+    /**
+     * Validates file type against allowed types
+     */
+    private validateFileType;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/storage/storage.ts"],"names":[],"mappings":"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"}