bunsane 0.1.0 → 0.1.1

package/tsconfig.json

@@ -1,34 +1,35 @@
-{
-  "compilerOptions": {
-    // Environment setup & latest features
-    "lib": ["ESNext"],
-    "target": "ESNext",
-    "module": "Preserve",
-    "moduleDetection": "force",
-    "jsx": "react-jsx",
-    "allowJs": true,
-
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
-
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false,
-
-    "baseUrl": ".",
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true,
-    "typeRoots": ["./types", "./node_modules/@types"]
-  }
-}
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Path mappings for internal modules
+    "baseUrl": ".",
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "typeRoots": ["./types", "./node_modules/@types"]
+  }
+}

package/types/graphql.types.ts

@@ -0,0 +1,87 @@
+// GraphQL Type Definitions for Bunsane Framework
+// This file provides basic type safety for GraphQL resolvers and context
+
+import { Entity } from "../core/Entity";
+
+/**
+ * Basic GraphQL Context interface
+ * Provides common properties used in resolvers
+ * Applications can extend this interface to add their own context properties
+ */
+export interface GraphQLContext {
+    /** The incoming HTTP request */
+    request?: Request;
+    /** Additional context properties can be added by applications */
+    [key: string]: any;
+}
+
+/**
+ * Simplified GraphQL Info type
+ * Represents the GraphQLResolveInfo with minimal properties for type safety
+ */
+export interface GraphQLInfo {
+    /** The field name being resolved */
+    fieldName: string;
+    /** The field nodes in the selection set */
+    fieldNodes: any[];
+    /** The return type of the field */
+    returnType: any;
+    /** The parent type */
+    parentType: any;
+    /** The schema */
+    schema: any;
+    /** Fragments defined in the query */
+    fragments: any;
+    /** Root value */
+    rootValue: any;
+    /** Operation */
+    operation: any;
+    /** Variable values */
+    variableValues: any;
+    /** Path to the current field */
+    path: any;
+}
+
+/**
+ * Utility type for resolver functions
+ * Simplifies resolver signatures by hiding complex generics
+ */
+export type SimpleResolver<TArgs = any, TReturn = any> = (
+    args: TArgs,
+    context: GraphQLContext,
+    info: GraphQLInfo
+) => TReturn | Promise<TReturn>;
+
+/**
+ * Utility type for field resolvers
+ * Provides type safety for parent entity and common parameters
+ */
+export type FieldResolver<TParent = Entity, TArgs = any, TReturn = any> = (
+    parent: TParent,
+    args: TArgs,
+    context: GraphQLContext,
+    info: GraphQLInfo
+) => TReturn | Promise<TReturn>;
+
+/**
+ * Branded type for better error messages
+ */
+export type BrandedString<T extends string> = string & { __brand: T };
+
+/**
+ * Schema-aware GraphQL operation type
+ */
+export type SchemaOperation<TInput, TOutput> = {
+    type: "Query" | "Mutation";
+    input: TInput;
+    output: TOutput;
+};
+
+/**
+ * Type-safe resolver with schema awareness
+ */
+export type SchemaResolver<TInput, TOutput> = (
+    args: TInput,
+    context: GraphQLContext,
+    info: GraphQLInfo
+) => TOutput | Promise<TOutput>;

package/types/hooks.types.ts

@@ -0,0 +1,141 @@
+/**
+ * Type definitions for the Entity Lifecycle Hooks system
+ */
+
+import type { Entity } from "../core/Entity";
+import type { BaseComponent } from "../core/Components";
+import type {
+    EntityEvent,
+    ComponentEvent,
+    LifecycleEvent,
+    EntityCreatedEvent,
+    EntityUpdatedEvent,
+    EntityDeletedEvent,
+    ComponentAddedEvent,
+    ComponentUpdatedEvent,
+    ComponentRemovedEvent
+} from "../core/events/EntityLifecycleEvents";
+
+/**
+ * Hook callback function signature for entity events
+ */
+export type EntityHookCallback<T extends EntityEvent = EntityEvent> = (event: T) => void;
+
+/**
+ * Hook callback function signature for component events
+ */
+export type ComponentHookCallback<T extends ComponentEvent = ComponentEvent> = (event: T) => void;
+
+/**
+ * Hook callback function signature for any lifecycle event
+ */
+export type LifecycleHookCallback = (event: LifecycleEvent) => void;
+
+/**
+ * Hook registration options
+ */
+export interface HookOptions {
+    /** Priority for hook execution order (higher numbers execute first) */
+    priority?: number;
+    /** Optional name for the hook for debugging */
+    name?: string;
+    /** Whether the hook should be executed asynchronously */
+    async?: boolean;
+}
+
+/**
+ * Hook execution context
+ */
+export interface HookContext {
+    /** The entity associated with the event */
+    entity: Entity;
+    /** The event that triggered the hook */
+    event: LifecycleEvent;
+    /** Timestamp when the hook execution started */
+    executionStart: Date;
+}
+
+/**
+ * Hook execution result
+ */
+export interface HookResult {
+    /** Whether the hook executed successfully */
+    success: boolean;
+    /** Execution time in milliseconds */
+    executionTime: number;
+    /** Error if execution failed */
+    error?: Error;
+}
+
+/**
+ * Batch hook execution result
+ */
+export interface BatchHookResult {
+    /** Total number of hooks executed */
+    totalHooks: number;
+    /** Number of successful executions */
+    successful: number;
+    /** Number of failed executions */
+    failed: number;
+    /** Total execution time */
+    totalExecutionTime: number;
+    /** Individual hook results */
+    results: HookResult[];
+}
+
+/**
+ * Hook filter function for conditional execution
+ */
+export type HookFilter<T extends LifecycleEvent = LifecycleEvent> = (event: T) => boolean;
+
+/**
+ * Filtered hook registration options
+ */
+export interface FilteredHookOptions extends HookOptions {
+    /** Filter function to determine if hook should execute */
+    filter?: HookFilter;
+}
+
+/**
+ * Hook metadata for introspection
+ */
+export interface HookMetadata {
+    /** Unique hook identifier */
+    id: string;
+    /** Event type the hook is registered for */
+    eventType: string;
+    /** Hook name for debugging */
+    name?: string;
+    /** Hook priority */
+    priority: number;
+    /** Whether hook executes asynchronously */
+    async: boolean;
+    /** Registration timestamp */
+    registeredAt: Date;
+}
+
+/**
+ * Hook manager statistics
+ */
+export interface HookStats {
+    /** Total number of registered hooks */
+    totalHooks: number;
+    /** Number of hooks by event type */
+    hooksByEventType: Record<string, number>;
+    /** Average execution time per event type */
+    averageExecutionTime: Record<string, number>;
+    /** Error rate per event type */
+    errorRate: Record<string, number>;
+}
+
+/**
+ * Hook execution options for advanced scenarios
+ */
+export interface HookExecutionOptions {
+    /** Timeout for hook execution in milliseconds */
+    timeout?: number;
+    /** Whether to continue executing other hooks if one fails */
+    continueOnError?: boolean;
+    /** Maximum number of hooks to execute in parallel */
+    maxConcurrency?: number;
+}

package/types/scheduler.types.ts

@@ -0,0 +1,165 @@
+/**
+ * System Scheduler Type Definitions
+ * Comprehensive TypeScript types for the BunSane scheduler system
+ */
+
+import type { QueryFilter } from "../core/Query";
+import type { ComponentTargetConfig } from "../core/EntityHookManager";
+
+export enum ScheduleInterval {
+    MINUTE = "minute",
+    HOUR = "hour",
+    DAILY = "daily",
+    WEEKLY = "weekly",
+    MONTHLY = "monthly",
+    CRON = "cron"
+}
+
+export interface ScheduledTaskOptions {
+    /** Unique identifier for the task */
+    id?: string;
+    /** Human-readable name for the task */
+    name?: string;
+    /** Whether the task should run immediately on startup */
+    runOnStart?: boolean;
+    /** Maximum execution time in milliseconds */
+    timeout?: number;
+    /** Whether to enable logging for this task */
+    enableLogging?: boolean;
+    /** Priority for execution ordering (higher numbers execute first) */
+    priority?: number;
+    /** Maximum retry attempts for failed tasks */
+    maxRetries?: number;
+    /** Delay between retry attempts in milliseconds */
+    retryDelay?: number;
+    /** Whether to continue retrying on failure */
+    continueOnError?: boolean;
+    /** Query filters to apply when querying components */
+    componentFilters?: QueryFilter[];
+    /** Maximum number of entities to process per execution */
+    maxEntitiesPerExecution?: number;
+    /** Whether to enable task metrics collection */
+    enableMetrics?: boolean;
+    /** Component targeting configuration for fine-grained entity selection */
+    componentTarget?: ComponentTargetConfig;
+}
+
+export interface ScheduledTaskInfo {
+    /** Unique task identifier */
+    id: string;
+    /** Task name */
+    name: string;
+    /** Target component class (legacy - use options.componentTarget instead) */
+    componentTarget?: new (...args: any[]) => any;
+    /** Schedule interval */
+    interval: ScheduleInterval;
+    /** Cron expression (when interval is CRON) */
+    cronExpression?: string;
+    /** Task options */
+    options: ScheduledTaskOptions;
+    /** Service instance */
+    service: any;
+    /** Method name to execute */
+    methodName: string;
+    /** Next execution timestamp */
+    nextExecution: Date;
+    /** Last execution timestamp */
+    lastExecution?: Date;
+    /** Execution count */
+    executionCount: number;
+    /** Whether task is currently running */
+    isRunning: boolean;
+    /** Whether task is enabled */
+    enabled: boolean;
+    /** Priority for execution ordering (higher numbers execute first) */
+    priority?: number;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Current retry count */
+    retryCount?: number;
+    /** Last error message */
+    lastError?: string;
+}
+
+export interface SchedulerMetrics {
+    /** Total number of registered tasks */
+    totalTasks: number;
+    /** Number of currently running tasks */
+    runningTasks: number;
+    /** Number of completed executions */
+    completedExecutions: number;
+    /** Number of failed executions */
+    failedExecutions: number;
+    /** Average execution time in milliseconds */
+    averageExecutionTime: number;
+    /** Total execution time in milliseconds */
+    totalExecutionTime: number;
+    /** Number of timed out tasks */
+    timedOutTasks: number;
+    /** Number of retried tasks */
+    retriedTasks: number;
+    /** Task-specific metrics */
+    taskMetrics: Record<string, TaskMetrics>;
+}
+
+export interface TaskMetrics {
+    /** Task ID */
+    taskId: string;
+    /** Task name */
+    taskName: string;
+    /** Total executions */
+    totalExecutions: number;
+    /** Successful executions */
+    successfulExecutions: number;
+    /** Failed executions */
+    failedExecutions: number;
+    /** Average execution time */
+    averageExecutionTime: number;
+    /** Last execution time */
+    lastExecutionTime?: Date;
+    /** Total entities processed */
+    totalEntitiesProcessed: number;
+    /** Retry count */
+    retryCount: number;
+    /** Timeout count */
+    timeoutCount: number;
+}
+
+export interface TaskExecutionResult {
+    /** Whether execution was successful */
+    success: boolean;
+    /** Execution duration in milliseconds */
+    duration: number;
+    /** Number of entities processed */
+    entitiesProcessed: number;
+    /** Error message if execution failed */
+    error?: string;
+    /** Timestamp of execution */
+    executedAt: Date;
+}
+
+export interface SchedulerEvent {
+    /** Event type */
+    type: 'task.registered' | 'task.executed' | 'task.failed' | 'task.timeout' | 'task.retry' | 'scheduler.started' | 'scheduler.stopped';
+    /** Task ID if applicable */
+    taskId?: string;
+    /** Event timestamp */
+    timestamp: Date;
+    /** Additional event data */
+    data?: any;
+}
+
+export type SchedulerEventCallback = (event: SchedulerEvent) => void;
+
+export interface SchedulerConfig {
+    /** Whether scheduler is enabled */
+    enabled: boolean;
+    /** Maximum concurrent tasks */
+    maxConcurrentTasks: number;
+    /** Default task timeout in milliseconds */
+    defaultTimeout: number;
+    /** Whether to enable detailed logging */
+    enableLogging: boolean;
+    /** Whether to run tasks on startup */
+    runOnStart: boolean;
+}

package/types/upload.types.ts

@@ -0,0 +1,184 @@
+/**
+ * Upload System Type Definitions
+ * Comprehensive TypeScript types for the Bunsane upload system
+ */
+
+export interface UploadConfiguration {
+    /** Maximum file size in bytes */
+    maxFileSize: number;
+    
+    /** Allowed MIME types */
+    allowedMimeTypes: string[];
+    
+    /** Allowed file extensions */
+    allowedExtensions: string[];
+    
+    /** Validate file signature (magic numbers) */
+    validateFileSignature: boolean;
+    
+    /** Sanitize file names to prevent path traversal */
+    sanitizeFileName: boolean;
+    
+    /** Preserve original file name */
+    preserveOriginalName: boolean;
+    
+    /** Generate thumbnails for images */
+    generateThumbnails: boolean;
+    
+    /** Upload path relative to storage root */
+    uploadPath: string;
+    
+    /** File naming strategy */
+    namingStrategy: "uuid" | "timestamp" | "original";
+    
+    /** Storage provider to use */
+    storageProvider?: string;
+    
+    /** Image processing options */
+    imageProcessing?: ImageProcessingOptions;
+    
+    /** Validation options */
+    validation?: ValidationOptions;
+}
+
+export interface ImageProcessingOptions {
+    /** Generate thumbnails */
+    generateThumbnails: boolean;
+    
+    /** Thumbnail sizes */
+    thumbnailSizes: Array<{ width: number; height: number; suffix: string }>;
+    
+    /** Compress images */
+    compress: boolean;
+    
+    /** Compression quality (0-100) */
+    quality: number;
+    
+    /** Convert to specific format */
+    convertTo?: "jpeg" | "png" | "webp";
+    
+    /** Maximum dimensions */
+    maxDimensions?: { width: number; height: number };
+}
+
+export interface ValidationOptions {
+    /** Check for malicious files */
+    scanForMalware: boolean;
+    
+    /** Custom validation functions */
+    customValidators?: Array<(file: File) => Promise<ValidationResult>>;
+    
+    /** Strict MIME type checking */
+    strictMimeType: boolean;
+}
+
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings?: string[];
+}
+
+export interface UploadResult {
+    success: boolean;
+    uploadId?: string;
+    fileName?: string;
+    originalFileName?: string;
+    mimeType?: string;
+    size?: number;
+    path?: string;
+    url?: string;
+    metadata?: Record<string, any>;
+    thumbnails?: Array<{ size: string; url: string; path: string }>;
+    error?: UploadError;
+}
+
+export interface UploadError {
+    uploadId: string;
+    code: UploadErrorCode;
+    message: string;
+    details?: Record<string, any>;
+}
+
+export type UploadErrorCode = 
+    | "VALIDATION_FAILED"
+    | "FILE_TOO_LARGE"
+    | "INVALID_FILE_TYPE"
+    | "MALICIOUS_FILE"
+    | "UPLOAD_FAILED"
+    | "STORAGE_ERROR"
+    | "PROCESSING_ERROR"
+    | "NETWORK_ERROR"
+    | "PERMISSION_DENIED"
+    | "QUOTA_EXCEEDED";
+
+export interface FileMetadata {
+    uploadId: string;
+    fileName: string;
+    originalFileName: string;
+    mimeType: string;
+    size: number;
+    extension: string;
+    uploadedAt: string;
+    dimensions?: { width: number; height: number };
+    hash?: string;
+    userMetadata?: Record<string, any>;
+}
+
+export interface StorageResult {
+    path: string;
+    url: string;
+    metadata?: Record<string, any>;
+}
+
+export interface UploadProgress {
+    uploadId: string;
+    fileName: string;
+    totalBytes: number;
+    uploadedBytes: number;
+    percentage: number;
+    speed?: number;
+    remainingTime?: number;
+    status: "pending" | "uploading" | "processing" | "completed" | "failed";
+}
+
+export interface BatchUploadResult {
+    totalFiles: number;
+    successfulUploads: number;
+    failedUploads: number;
+    results: UploadResult[];
+    errors: UploadError[];
+}
+
+export interface UploadComponentData {
+    uploadId: string;
+    fileName: string;
+    originalFileName: string;
+    mimeType: string;
+    size: number;
+    path: string;
+    url: string;
+    metadata: Record<string, any>;
+    uploadedAt: string;
+}
+
+/**
+ * Configuration for upload decorators
+ */
+export interface UploadDecoratorConfig extends Partial<UploadConfiguration> {
+    /** Field name to apply upload to */
+    field?: string;
+    
+    /** Enable batch uploads */
+    batch?: boolean;
+    
+    /** Required upload */
+    required?: boolean;
+    
+    /** Custom validation message */
+    validationMessage?: string;
+}
+
+/**
+ * Upload field types for GraphQL
+ */
+export type UploadGraphQLType = "Upload" | "[Upload]" | "Upload!" | "[Upload]!";