bunsane 0.1.0 → 0.1.1

package/core/UploadManager.ts

@@ -0,0 +1,261 @@
+import { logger as MainLogger } from "./Logger";
+import { uuidv7 } from "../utils/uuid";
+import type { StorageProvider } from "./storage/StorageProvider";
+import { LocalStorageProvider } from "./storage/LocalStorageProvider";
+import type { UploadConfiguration, UploadResult, UploadError, FileMetadata } from "../types/upload.types";
+import { FileValidator } from "./FileValidator";
+
+const logger = MainLogger.child({ scope: "UploadManager" });
+
+/**
+ * UploadManager - Singleton class for managing file uploads
+ * Provides centralized upload handling with pluggable storage backends
+ */
+export class UploadManager {
+    private static instance: UploadManager;
+    private storageProviders: Map<string, StorageProvider> = new Map();
+    private defaultStorageProvider: string = "local";
+    private fileValidator: FileValidator;
+    private globalConfig: UploadConfiguration;
+
+    private constructor() {
+        this.fileValidator = new FileValidator();
+        this.globalConfig = this.getDefaultConfiguration();
+        this.initializeDefaultProviders();
+    }
+
+    public static getInstance(): UploadManager {
+        if (!UploadManager.instance) {
+            UploadManager.instance = new UploadManager();
+        }
+        return UploadManager.instance;
+    }
+
+    /**
+     * Register a storage provider
+     */
+    public registerStorageProvider(name: string, provider: StorageProvider): void {
+        logger.info(`Registering storage provider: ${name}`);
+        this.storageProviders.set(name, provider);
+    }
+
+    /**
+     * Set the default storage provider
+     */
+    public setDefaultStorageProvider(name: string): void {
+        if (!this.storageProviders.has(name)) {
+            throw new Error(`Storage provider '${name}' not found`);
+        }
+        this.defaultStorageProvider = name;
+        logger.info(`Default storage provider set to: ${name}`);
+    }
+
+    /**
+     * Get storage provider by name
+     */
+    public getStorageProvider(name?: string): StorageProvider {
+        const providerName = name || this.defaultStorageProvider;
+        const provider = this.storageProviders.get(providerName);
+        if (!provider) {
+            throw new Error(`Storage provider '${providerName}' not found`);
+        }
+        return provider;
+    }
+
+    /**
+     * Process file upload
+     */
+    public async uploadFile(
+        file: File,
+        config?: Partial<UploadConfiguration>,
+        storageProvider?: string
+    ): Promise<UploadResult> {
+        const uploadId = uuidv7();
+        const mergedConfig = { ...this.globalConfig, ...config };
+        
+        logger.info(`Processing upload ${uploadId} for file: ${file.name}`);
+
+        try {
+            // Validate file
+            const validation = await this.fileValidator.validate(file, mergedConfig);
+            if (!validation.valid) {
+                const error: UploadError = {
+                    uploadId,
+                    code: "VALIDATION_FAILED",
+                    message: validation.errors.join(", "),
+                    details: { validationErrors: validation.errors }
+                };
+                logger.warn(`Upload ${uploadId} validation failed: ${validation.errors.join(', ')}`);
+                return { success: false, error };
+            }
+
+            // Get storage provider
+            const provider = this.getStorageProvider(storageProvider);
+
+            // Generate file metadata
+            const metadata = await this.generateFileMetadata(file, uploadId, mergedConfig);
+
+            // Store file
+            const storeResult = await provider.store(file, metadata, mergedConfig);
+
+            const result: UploadResult = {
+                success: true,
+                uploadId,
+                fileName: metadata.fileName,
+                originalFileName: file.name,
+                mimeType: file.type,
+                size: file.size,
+                path: storeResult.path,
+                url: storeResult.url,
+                metadata: storeResult.metadata || {}
+            };
+
+            logger.info(`Upload ${uploadId} completed successfully`);
+            return result;
+
+        } catch (error) {
+            const uploadError: UploadError = {
+                uploadId,
+                code: "UPLOAD_FAILED",
+                message: error instanceof Error ? error.message : "Unknown error occurred",
+                details: { originalError: error }
+            };
+            logger.error(`Upload ${uploadId} failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return { success: false, error: uploadError };
+        }
+    }
+
+    /**
+     * Process multiple file uploads
+     */
+    public async uploadFiles(
+        files: File[],
+        config?: Partial<UploadConfiguration>,
+        storageProvider?: string
+    ): Promise<UploadResult[]> {
+        logger.info(`Processing batch upload of ${files.length} files`);
+        
+        const uploadPromises = files.map(file => 
+            this.uploadFile(file, config, storageProvider)
+        );
+
+        return await Promise.all(uploadPromises);
+    }
+
+    /**
+     * Delete uploaded file
+     */
+    public async deleteFile(path: string, storageProvider?: string): Promise<boolean> {
+        try {
+            const provider = this.getStorageProvider(storageProvider);
+            const success = await provider.delete(path);
+            logger.info(`File deleted: ${path}`);
+            return success;
+        } catch (error) {
+            logger.error(`Failed to delete file ${path}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return false;
+        }
+    }
+
+    /**
+     * Get file URL
+     */
+    public async getFileUrl(path: string, storageProvider?: string): Promise<string | null> {
+        try {
+            const provider = this.getStorageProvider(storageProvider);
+            return await provider.getUrl(path);
+        } catch (error) {
+            logger.error(`Failed to get URL for file ${path}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            return null;
+        }
+    }
+
+    /**
+     * Update global configuration
+     */
+    public updateConfiguration(config: Partial<UploadConfiguration>): void {
+        this.globalConfig = { ...this.globalConfig, ...config };
+        logger.info("Upload configuration updated");
+    }
+
+    /**
+     * Get current configuration
+     */
+    public getConfiguration(): UploadConfiguration {
+        return { ...this.globalConfig };
+    }
+
+    private async initializeDefaultProviders(): Promise<void> {
+        // Register default local storage provider
+        const localProvider = new LocalStorageProvider();
+        await localProvider.initialize();
+        this.registerStorageProvider("local", localProvider);
+    }
+
+    private getDefaultConfiguration(): UploadConfiguration {
+        return {
+            maxFileSize: 10 * 1024 * 1024, // 10MB
+            allowedMimeTypes: [
+                "image/jpeg",
+                "image/png",
+                "image/gif",
+                "image/webp"
+            ],
+            allowedExtensions: [".jpg", ".jpeg", ".png", ".gif", ".webp"],
+            validateFileSignature: true,
+            sanitizeFileName: true,
+            preserveOriginalName: false,
+            generateThumbnails: false,
+            uploadPath: "uploads",
+            namingStrategy: "uuid"
+        };
+    }
+
+    private async generateFileMetadata(
+        file: File,
+        uploadId: string,
+        config: UploadConfiguration
+    ): Promise<FileMetadata> {
+        const extension = this.getFileExtension(file.name);
+        
+        let fileName: string;
+        switch (config.namingStrategy) {
+            case "uuid":
+                fileName = `${uploadId}${extension}`;
+                break;
+            case "timestamp":
+                fileName = `${Date.now()}_${this.sanitizeFileName(file.name)}`;
+                break;
+            case "original":
+                fileName = config.sanitizeFileName ? 
+                    this.sanitizeFileName(file.name) : file.name;
+                break;
+            default:
+                fileName = `${uploadId}${extension}`;
+        }
+
+        return {
+            uploadId,
+            fileName,
+            originalFileName: file.name,
+            mimeType: file.type,
+            size: file.size,
+            extension,
+            uploadedAt: new Date().toISOString()
+        };
+    }
+
+    private getFileExtension(fileName: string): string {
+        const lastDot = fileName.lastIndexOf('.');
+        return lastDot > 0 ? fileName.slice(lastDot) : '';
+    }
+
+    private sanitizeFileName(fileName: string): string {
+        // Remove dangerous characters and normalize
+        return fileName
+            .replace(/[^a-zA-Z0-9.-]/g, '_')
+            .replace(/_{2,}/g, '_')
+            .replace(/^_+|_+$/g, '')
+            .toLowerCase();
+    }
+}

package/core/components/UploadComponent.ts

@@ -0,0 +1,206 @@
+import { BaseComponent, Component, CompData } from "../Components";
+import type { UploadComponentData } from "../../types/upload.types";
+
+/**
+ * UploadComponent - Stores file upload metadata in entities
+ * This component contains all essential information about uploaded files
+ */
+@Component
+export class UploadComponent extends BaseComponent {
+    @CompData()
+    uploadId: string = "";
+
+    @CompData()
+    fileName: string = "";
+
+    @CompData()
+    originalFileName: string = "";
+
+    @CompData()
+    mimeType: string = "";
+
+    @CompData()
+    size: number = 0;
+
+    @CompData()
+    path: string = "";
+
+    @CompData()
+    url: string = "";
+
+    @CompData()
+    uploadedAt: string = "";
+
+    @CompData()
+    metadata: string = "{}"; // JSON string for additional metadata
+
+    /**
+     * Set upload data from UploadResult
+     */
+    public setUploadData(data: UploadComponentData): void {
+        this.uploadId = data.uploadId;
+        this.fileName = data.fileName;
+        this.originalFileName = data.originalFileName;
+        this.mimeType = data.mimeType;
+        this.size = data.size;
+        this.path = data.path;
+        this.url = data.url;
+        this.uploadedAt = data.uploadedAt;
+        this.metadata = JSON.stringify(data.metadata || {});
+    }
+
+    /**
+     * Get parsed metadata
+     */
+    public getMetadata(): Record<string, any> {
+        try {
+            return JSON.parse(this.metadata);
+        } catch {
+            return {};
+        }
+    }
+
+    /**
+     * Update metadata
+     */
+    public updateMetadata(newMetadata: Record<string, any>): void {
+        const current = this.getMetadata();
+        this.metadata = JSON.stringify({ ...current, ...newMetadata });
+    }
+
+    /**
+     * Check if this is an image file
+     */
+    public isImage(): boolean {
+        return this.mimeType.startsWith("image/");
+    }
+
+    /**
+     * Check if this is a document file
+     */
+    public isDocument(): boolean {
+        const documentMimeTypes = [
+            "application/pdf",
+            "text/plain",
+            "application/msword",
+            "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+        ];
+        return documentMimeTypes.includes(this.mimeType);
+    }
+
+    /**
+     * Get file extension
+     */
+    public getExtension(): string {
+        const lastDot = this.fileName.lastIndexOf('.');
+        return lastDot > 0 ? this.fileName.slice(lastDot) : '';
+    }
+
+    /**
+     * Get human-readable file size
+     */
+    public getHumanReadableSize(): string {
+        const bytes = this.size;
+        const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+        if (bytes === 0) return '0 Bytes';
+        const i = Math.floor(Math.log(bytes) / Math.log(1024));
+        return Math.round(bytes / Math.pow(1024, i) * 100) / 100 + ' ' + sizes[i];
+    }
+
+    /**
+     * Get upload age in days
+     */
+    public getUploadAge(): number {
+        const uploadDate = new Date(this.uploadedAt);
+        const now = new Date();
+        const diffTime = Math.abs(now.getTime() - uploadDate.getTime());
+        return Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+    }
+}
+
+/**
+ * ImageMetadataComponent - Extended metadata for image files
+ */
+@Component
+export class ImageMetadataComponent extends BaseComponent {
+    @CompData()
+    width: number = 0;
+
+    @CompData()
+    height: number = 0;
+
+    @CompData()
+    colorDepth: number = 0;
+
+    @CompData()
+    hasAlpha: boolean = false;
+
+    @CompData()
+    isAnimated: boolean = false;
+
+    @CompData()
+    thumbnails: string = "[]"; // JSON array of thumbnail paths
+
+    /**
+     * Set image dimensions
+     */
+    public setDimensions(width: number, height: number): void {
+        this.width = width;
+        this.height = height;
+    }
+
+    /**
+     * Get aspect ratio
+     */
+    public getAspectRatio(): number {
+        return this.height > 0 ? this.width / this.height : 0;
+    }
+
+    /**
+     * Get thumbnail paths
+     */
+    public getThumbnails(): Array<{ size: string; url: string; path: string }> {
+        try {
+            return JSON.parse(this.thumbnails);
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * Add thumbnail
+     */
+    public addThumbnail(thumbnail: { size: string; url: string; path: string }): void {
+        const thumbnails = this.getThumbnails();
+        thumbnails.push(thumbnail);
+        this.thumbnails = JSON.stringify(thumbnails);
+    }
+
+    /**
+     * Check if image is landscape
+     */
+    public isLandscape(): boolean {
+        return this.width > this.height;
+    }
+
+    /**
+     * Check if image is portrait
+     */
+    public isPortrait(): boolean {
+        return this.height > this.width;
+    }
+
+    /**
+     * Check if image is square
+     */
+    public isSquare(): boolean {
+        return this.width === this.height;
+    }
+
+    /**
+     * Get megapixels
+     */
+    public getMegapixels(): number {
+        return Math.round((this.width * this.height) / 1000000 * 100) / 100;
+    }
+}

package/core/decorators/EntityHooks.ts

@@ -0,0 +1,190 @@
+import EntityHookManager from "../EntityHookManager";
+import type { EntityEvent, ComponentEvent } from "../events/EntityLifecycleEvents";
+import type { HookOptions, ComponentTargetConfig } from "../EntityHookManager";
+
+/**
+ * Decorator for registering entity lifecycle hooks
+ * @param eventType The entity event type to hook into
+ * @param options Hook registration options
+ */
+export function EntityHook(eventType: EntityEvent['eventType'], options: HookOptions = {}) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+
+        // Store hook info for later registration
+        if (!target.constructor.__entityHooks) {
+            target.constructor.__entityHooks = [];
+        }
+
+        target.constructor.__entityHooks.push({
+            eventType,
+            methodName: propertyKey,
+            options
+        });
+
+        // Replace method to ensure it can be called normally
+        descriptor.value = function (...args: any[]) {
+            return originalMethod.apply(this, args);
+        };
+    };
+}
+
+/**
+ * Decorator for registering component lifecycle hooks
+ * @param eventType The component event type to hook into
+ * @param options Hook registration options
+ */
+export function ComponentHook(eventType: ComponentEvent['eventType'], options: HookOptions = {}) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+
+        // Store hook info for later registration
+        if (!target.constructor.__componentHooks) {
+            target.constructor.__componentHooks = [];
+        }
+
+        target.constructor.__componentHooks.push({
+            eventType,
+            methodName: propertyKey,
+            options
+        });
+
+        // Replace method to ensure it can be called normally
+        descriptor.value = function (...args: any[]) {
+            return originalMethod.apply(this, args);
+        };
+    };
+}
+
+/**
+ * Decorator for registering hooks for all lifecycle events
+ * @param options Hook registration options
+ */
+export function LifecycleHook(options: HookOptions = {}) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+
+        // Store hook info for later registration
+        if (!target.constructor.__lifecycleHooks) {
+            target.constructor.__lifecycleHooks = [];
+        }
+
+        target.constructor.__lifecycleHooks.push({
+            methodName: propertyKey,
+            options
+        });
+
+        // Replace method to ensure it can be called normally
+        descriptor.value = function (...args: any[]) {
+            return originalMethod.apply(this, args);
+        };
+    };
+}
+
+/**
+ * Decorator for registering component-targeted entity lifecycle hooks
+ * @param eventType The entity event type to hook into
+ * @param componentTarget Component targeting configuration
+ * @param options Additional hook registration options
+ */
+export function ComponentTargetHook(
+    eventType: EntityEvent['eventType'],
+    componentTarget: ComponentTargetConfig,
+    options: Omit<HookOptions, 'componentTarget'> = {}
+) {
+    return function (target: any, propertyKey: string, descriptor: PropertyDescriptor) {
+        const originalMethod = descriptor.value;
+
+        // Store hook info for later registration
+        if (!target.constructor.__componentTargetHooks) {
+            target.constructor.__componentTargetHooks = [];
+        }
+
+        target.constructor.__componentTargetHooks.push({
+            eventType,
+            methodName: propertyKey,
+            componentTarget,
+            options
+        });
+
+        // Replace method to ensure it can be called normally
+        descriptor.value = function (...args: any[]) {
+            return originalMethod.apply(this, args);
+        };
+    };
+}
+
+/**
+ * Register all decorated hooks for a service class
+ * Call this method after instantiating a service to register its decorated hooks
+ * @param serviceInstance The service instance to register hooks for
+ */
+export function registerDecoratedHooks(serviceInstance: any): void {
+    const constructor = serviceInstance.constructor;
+
+    // Register entity hooks
+    if (constructor.__entityHooks) {
+        for (const hookInfo of constructor.__entityHooks) {
+            const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
+
+            EntityHookManager.registerEntityHook(
+                hookInfo.eventType,
+                hookMethod,
+                hookInfo.options
+            );
+        }
+    }
+
+    // Register component hooks
+    if (constructor.__componentHooks) {
+        for (const hookInfo of constructor.__componentHooks) {
+            const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
+
+            EntityHookManager.registerComponentHook(
+                hookInfo.eventType,
+                hookMethod,
+                hookInfo.options
+            );
+        }
+    }
+
+    // Register component target hooks
+    if (constructor.__componentTargetHooks) {
+        for (const hookInfo of constructor.__componentTargetHooks) {
+            const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
+
+            EntityHookManager.registerEntityHook(
+                hookInfo.eventType,
+                hookMethod,
+                {
+                    ...hookInfo.options,
+                    componentTarget: hookInfo.componentTarget
+                }
+            );
+        }
+    }
+
+    // Register lifecycle hooks
+    if (constructor.__lifecycleHooks) {
+        for (const hookInfo of constructor.__lifecycleHooks) {
+            const hookMethod = serviceInstance[hookInfo.methodName].bind(serviceInstance);
+
+            EntityHookManager.registerLifecycleHook(
+                hookMethod,
+                hookInfo.options
+            );
+        }
+    }
+}
+
+/**
+ * Unregister all decorated hooks for a service class
+ * Call this method before destroying a service to clean up its hooks
+ * @param serviceInstance The service instance to unregister hooks for
+ */
+export function unregisterDecoratedHooks(serviceInstance: any): void {
+    // Note: This is a simplified implementation
+    // In a production system, you'd want to track hook IDs during registration
+    // and use them for targeted removal here
+    console.warn('unregisterDecoratedHooks is not fully implemented. Use EntityHookManager.removeHook() for individual hook removal.');
+}