create-fluxstack 1.0.13 → 1.0.15

package/core/types/types.ts

@@ -0,0 +1,319 @@
+// 🔥 FluxStack Live Components - Shared Types
+
+export interface LiveMessage {
+  type: 'COMPONENT_MOUNT' | 'COMPONENT_UNMOUNT' | 'COMPONENT_REHYDRATE' | 'COMPONENT_ACTION' | 'CALL_ACTION' | 'ACTION_RESPONSE' | 'PROPERTY_UPDATE' | 'STATE_UPDATE' | 'STATE_REHYDRATED' | 'ERROR' | 'BROADCAST'
+  componentId: string
+  action?: string
+  property?: string
+  payload?: any
+  timestamp?: number
+  userId?: string
+  room?: string
+  // Request-Response system
+  requestId?: string
+  responseId?: string
+  expectResponse?: boolean
+}
+
+export interface ComponentState {
+  [key: string]: any
+}
+
+export interface LiveComponentInstance<TState = ComponentState, TActions = Record<string, Function>> {
+  id: string
+  state: TState
+  call: <T extends keyof TActions>(action: T, ...args: any[]) => Promise<any>
+  set: <K extends keyof TState>(property: K, value: TState[K]) => void
+  loading: boolean
+  errors: Record<string, string>
+  connected: boolean
+  room?: string
+}
+
+export interface WebSocketData {
+  components: Map<string, any>
+  userId?: string
+  subscriptions: Set<string>
+}
+
+export interface ComponentDefinition<TState = ComponentState> {
+  name: string
+  initialState: TState
+  component: new (initialState: TState, ws: any) => LiveComponent<TState>
+}
+
+export interface BroadcastMessage {
+  type: string
+  payload: any
+  room?: string
+  excludeUser?: string
+}
+
+// WebSocket Types for Client
+export interface WebSocketMessage {
+  type: string
+  componentId?: string
+  action?: string
+  payload?: any
+  timestamp?: number
+  userId?: string
+  room?: string
+  // Request-Response system
+  requestId?: string
+  responseId?: string
+  expectResponse?: boolean
+}
+
+export interface WebSocketResponse {
+  type: 'MESSAGE_RESPONSE' | 'CONNECTION_ESTABLISHED' | 'ERROR' | 'BROADCAST' | 'ACTION_RESPONSE' | 'COMPONENT_MOUNTED' | 'COMPONENT_REHYDRATED' | 'STATE_UPDATE' | 'STATE_REHYDRATED' | 'FILE_UPLOAD_PROGRESS' | 'FILE_UPLOAD_COMPLETE' | 'FILE_UPLOAD_ERROR' | 'FILE_UPLOAD_START_RESPONSE'
+  originalType?: string
+  componentId?: string
+  success?: boolean
+  result?: any
+  // Request-Response system
+  requestId?: string
+  responseId?: string
+  error?: string
+  timestamp?: number
+  connectionId?: string
+  payload?: any
+  // File upload specific fields
+  uploadId?: string
+  chunkIndex?: number
+  totalChunks?: number
+  bytesUploaded?: number
+  totalBytes?: number
+  progress?: number
+  filename?: string
+  fileUrl?: string
+  // Re-hydration specific fields
+  signedState?: any
+  oldComponentId?: string
+  newComponentId?: string
+}
+
+// Hybrid Live Component Types
+export interface HybridState<T> {
+  data: T
+  validation: StateValidation
+  conflicts: StateConflict[]
+  status: 'synced' | 'conflict' | 'disconnected'
+}
+
+export interface StateValidation {
+  checksum: string
+  version: number
+  source: 'client' | 'server' | 'mount'
+  timestamp: number
+}
+
+export interface StateConflict {
+  property: string
+  clientValue: any
+  serverValue: any
+  timestamp: number
+  resolved: boolean
+}
+
+export interface HybridComponentOptions {
+  fallbackToLocal?: boolean
+  room?: string
+  userId?: string
+  autoMount?: boolean
+  debug?: boolean
+}
+
+export abstract class LiveComponent<TState = ComponentState> {
+  public readonly id: string
+  public state: TState
+  protected ws: any
+  public room?: string
+  public userId?: string
+  public broadcastToRoom: (message: BroadcastMessage) => void = () => {} // Will be injected by registry
+
+  constructor(initialState: TState, ws: any, options?: { room?: string; userId?: string }) {
+    this.id = this.generateId()
+    this.state = initialState
+    this.ws = ws
+    this.room = options?.room
+    this.userId = options?.userId
+  }
+
+  // State management
+  public setState(updates: Partial<TState> | ((prev: TState) => Partial<TState>)) {
+    const newUpdates = typeof updates === 'function' ? updates(this.state) : updates
+    this.state = { ...this.state, ...newUpdates }
+    this.emit('STATE_UPDATE', { state: this.state })
+  }
+
+  // Execute action safely
+  public async executeAction(action: string, payload: any): Promise<any> {
+    try {
+      // Check if method exists
+      const method = (this as any)[action]
+      if (typeof method !== 'function') {
+        throw new Error(`Action '${action}' not found on component`)
+      }
+
+      // Execute method
+      const result = await method.call(this, payload)
+      return result
+    } catch (error: any) {
+      this.emit('ERROR', { 
+        action, 
+        error: error.message,
+        stack: error.stack 
+      })
+      throw error
+    }
+  }
+
+  // Send message to client
+  protected emit(type: string, payload: any) {
+    const message: LiveMessage = {
+      type: type as any,
+      componentId: this.id,
+      payload,
+      timestamp: Date.now(),
+      userId: this.userId,
+      room: this.room
+    }
+
+    if (this.ws && this.ws.send) {
+      this.ws.send(JSON.stringify(message))
+    }
+  }
+
+  // Broadcast to all clients in room
+  protected broadcast(type: string, payload: any, excludeCurrentUser = false) {
+    const message: BroadcastMessage = {
+      type,
+      payload,
+      room: this.room,
+      excludeUser: excludeCurrentUser ? this.userId : undefined
+    }
+
+    // This will be handled by the registry
+    this.broadcastToRoom(message)
+  }
+
+  // Subscribe to room for multi-user features
+  protected async subscribeToRoom(roomId: string) {
+    this.room = roomId
+    // Registry will handle the actual subscription
+  }
+
+  // Unsubscribe from room
+  protected async unsubscribeFromRoom() {
+    this.room = undefined
+    // Registry will handle the actual unsubscription
+  }
+
+  // Generate unique ID
+  private generateId(): string {
+    return `live-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
+  }
+
+  // Cleanup when component is destroyed
+  public destroy() {
+    this.unsubscribeFromRoom()
+    // Override in subclasses for custom cleanup
+  }
+
+  // Get serializable state for client
+  public getSerializableState(): TState {
+    return this.state
+  }
+}
+
+// Utility types for better TypeScript experience
+export type ComponentActions<T> = {
+  [K in keyof T]: T[K] extends (...args: any[]) => any ? T[K] : never
+}
+
+export type ComponentProps<T extends LiveComponent> = T extends LiveComponent<infer TState> ? TState : never
+
+export type ActionParameters<T, K extends keyof T> = T[K] extends (...args: infer P) => any ? P : never
+
+export type ActionReturnType<T, K extends keyof T> = T[K] extends (...args: any[]) => infer R ? R : never
+
+// File Upload Types for Chunked WebSocket Upload
+export interface FileChunkData {
+  uploadId: string
+  filename: string
+  fileType: string
+  fileSize: number
+  chunkIndex: number
+  totalChunks: number
+  chunkSize: number
+  data: string // Base64 encoded chunk data
+  hash?: string // Optional chunk hash for verification
+}
+
+export interface FileUploadStartMessage {
+  type: 'FILE_UPLOAD_START'
+  componentId: string
+  uploadId: string
+  filename: string
+  fileType: string
+  fileSize: number
+  chunkSize?: number // Optional, defaults to 64KB
+  requestId?: string
+}
+
+export interface FileUploadChunkMessage {
+  type: 'FILE_UPLOAD_CHUNK'
+  componentId: string
+  uploadId: string
+  chunkIndex: number
+  totalChunks: number
+  data: string // Base64 encoded chunk
+  hash?: string
+  requestId?: string
+}
+
+export interface FileUploadCompleteMessage {
+  type: 'FILE_UPLOAD_COMPLETE'
+  componentId: string
+  uploadId: string
+  requestId?: string
+}
+
+export interface FileUploadProgressResponse {
+  type: 'FILE_UPLOAD_PROGRESS'
+  componentId: string
+  uploadId: string
+  chunkIndex: number
+  totalChunks: number
+  bytesUploaded: number
+  totalBytes: number
+  progress: number // 0-100
+  requestId?: string
+  timestamp: number
+}
+
+export interface FileUploadCompleteResponse {
+  type: 'FILE_UPLOAD_COMPLETE'
+  componentId: string
+  uploadId: string
+  success: boolean
+  filename?: string
+  fileUrl?: string
+  error?: string
+  requestId?: string
+  timestamp: number
+}
+
+// File Upload Manager for handling uploads
+export interface ActiveUpload {
+  uploadId: string
+  componentId: string
+  filename: string
+  fileType: string
+  fileSize: number
+  totalChunks: number
+  receivedChunks: Map<number, string>
+  startTime: number
+  lastChunkTime: number
+  tempFilePath?: string
+}

package/core/utils/env-runtime.ts

@@ -216,6 +216,13 @@ export const validate = {
     if (value && !validValues.includes(value)) {
       throw new Error(`${key} must be one of: ${validValues.join(', ')}, got: ${value}`)
     }
+  },
+
+  validate(key: string, validator: (value: string) => boolean, errorMessage: string): void {
+    const value = smartEnv.get(key, '')
+    if (value && !validator(value)) {
+      throw new Error(`${key}: ${errorMessage}`)
+    }
   }
 }
 

package/core/utils/errors/handlers.ts

@@ -1,63 +1,288 @@
-import { FluxStackError } from "./index"
+import { FluxStackError, wrapError, type ErrorMetadata, type ErrorSerializedResponse } from "./index"
 import type { Logger } from "../logger/index"
+import { v4 as uuidv4 } from 'uuid'
 
 export interface ErrorHandlerContext {
   logger: Logger
   isDevelopment: boolean
   request?: Request
   path?: string
+  method?: string
+  correlationId?: string
+  userId?: string
+  userAgent?: string
+  ip?: string
+  metricsCollector?: ErrorMetricsCollector
 }
 
-export const errorHandler = (error: Error, context: ErrorHandlerContext) => {
-  const { logger, isDevelopment, request, path } = context
-  
-  if (error instanceof FluxStackError) {
-    // Log FluxStack errors with appropriate level
-    const logLevel = error.statusCode >= 500 ? 'error' : 'warn'
-    logger[logLevel](error.message, {
+export interface ErrorMetricsCollector {
+  recordError(error: FluxStackError, context: ErrorHandlerContext): void
+}
+
+export interface ErrorRecoveryStrategy {
+  canRecover(error: FluxStackError): boolean
+  recover(error: FluxStackError, context: ErrorHandlerContext): Promise<any> | any
+}
+
+export interface ErrorHandlerOptions {
+  enableStackTrace?: boolean
+  enableErrorMetrics?: boolean
+  enableCorrelationId?: boolean
+  sanitizeErrors?: boolean
+  recoveryStrategies?: ErrorRecoveryStrategy[]
+  customErrorMessages?: Record<string, string>
+}
+
+export class EnhancedErrorHandler {
+  private options: Required<ErrorHandlerOptions>
+  private recoveryStrategies: ErrorRecoveryStrategy[]
+
+  constructor(options: ErrorHandlerOptions = {}) {
+    this.options = {
+      enableStackTrace: options.enableStackTrace ?? true,
+      enableErrorMetrics: options.enableErrorMetrics ?? true,
+      enableCorrelationId: options.enableCorrelationId ?? true,
+      sanitizeErrors: options.sanitizeErrors ?? true,
+      recoveryStrategies: options.recoveryStrategies ?? [],
+      customErrorMessages: options.customErrorMessages ?? {}
+    }
+    this.recoveryStrategies = this.options.recoveryStrategies
+  }
+
+  async handle(error: Error, context: ErrorHandlerContext): Promise<ErrorSerializedResponse> {
+    const { logger, isDevelopment, request, path, method, correlationId, userId, userAgent, ip, metricsCollector } = context
+    
+    // Generate correlation ID if not provided and enabled
+    const finalCorrelationId = this.options.enableCorrelationId 
+      ? (correlationId || uuidv4())
+      : correlationId
+
+    // Create metadata from context
+    const metadata: ErrorMetadata = {
+      correlationId: finalCorrelationId,
+      userId,
+      userAgent,
+      ip,
+      path,
+      method,
+      timestamp: new Date().toISOString()
+    }
+
+    // Convert to FluxStackError if needed
+    let fluxError: FluxStackError
+    if (error instanceof FluxStackError) {
+      fluxError = error.withMetadata(metadata)
+    } else {
+      fluxError = wrapError(error, metadata)
+    }
+
+    // Try recovery strategies for operational errors
+    if (fluxError.isOperational && this.recoveryStrategies.length > 0) {
+      for (const strategy of this.recoveryStrategies) {
+        if (strategy.canRecover(fluxError)) {
+          try {
+            const recoveryResult = await strategy.recover(fluxError, context)
+            logger.info('Error recovery successful', {
+              errorCode: fluxError.code,
+              correlationId: finalCorrelationId,
+              strategy: strategy.constructor.name
+            })
+            return recoveryResult
+          } catch (recoveryError) {
+            logger.warn('Error recovery failed', {
+              errorCode: fluxError.code,
+              correlationId: finalCorrelationId,
+              strategy: strategy.constructor.name,
+              recoveryError: recoveryError instanceof Error ? recoveryError.message : recoveryError
+            })
+          }
+        }
+      }
+    }
+
+    // Log the error with appropriate level and context
+    this.logError(fluxError, logger, isDevelopment)
+
+    // Record metrics if enabled
+    if (this.options.enableErrorMetrics && metricsCollector) {
+      try {
+        metricsCollector.recordError(fluxError, context)
+      } catch (metricsError) {
+        logger.warn('Failed to record error metrics', { 
+          error: metricsError instanceof Error ? metricsError.message : metricsError 
+        })
+      }
+    }
+
+    // Generate user-friendly response
+    return this.generateErrorResponse(fluxError, isDevelopment)
+  }
+
+  private logError(error: FluxStackError, logger: Logger, isDevelopment: boolean): void {
+    const logLevel = this.getLogLevel(error)
+    const logData = {
       code: error.code,
       statusCode: error.statusCode,
       context: error.context,
-      path,
-      method: request?.method,
-      stack: isDevelopment ? error.stack : undefined
-    })
+      metadata: error.metadata,
+      isOperational: error.isOperational,
+      ...(isDevelopment && { stack: error.stack })
+    }
+
+    // Skip logging for certain errors to reduce noise
+    if (this.shouldSkipLogging(error)) {
+      return
+    }
+
+    logger[logLevel](error.message, logData)
+  }
+
+  private getLogLevel(error: FluxStackError): 'error' | 'warn' | 'info' {
+    if (!error.isOperational) {
+      return 'error'
+    }
     
-    return {
-      error: {
-        message: error.message,
-        code: error.code,
-        statusCode: error.statusCode,
-        ...(error.context && { details: error.context }),
-        ...(isDevelopment && { stack: error.stack })
+    if (error.statusCode >= 500) {
+      return 'error'
+    } else if (error.statusCode >= 400) {
+      return 'warn'
+    } else {
+      return 'info'
+    }
+  }
+
+  private shouldSkipLogging(error: FluxStackError): boolean {
+    // Skip logging for 404 errors unless explicitly enabled
+    if (error.code === 'NOT_FOUND' && !process.env.ENABLE_NOT_FOUND_LOGS) {
+      return true
+    }
+
+    // Skip logging for rate limit errors to prevent log spam
+    if (error.code === 'RATE_LIMIT_EXCEEDED' && !process.env.ENABLE_RATE_LIMIT_LOGS) {
+      return true
+    }
+
+    return false
+  }
+
+  private generateErrorResponse(error: FluxStackError, isDevelopment: boolean): ErrorSerializedResponse {
+    const response = error.toResponse(isDevelopment)
+    
+    // Apply custom error messages if configured
+    if (this.options.customErrorMessages[error.code]) {
+      response.error.message = this.options.customErrorMessages[error.code]
+    }
+
+    // Sanitize sensitive information in production
+    if (!isDevelopment && this.options.sanitizeErrors) {
+      response.error = this.sanitizeErrorResponse(response.error)
+    }
+
+    return response
+  }
+
+  private sanitizeErrorResponse(errorResponse: any): any {
+    const sanitized = { ...errorResponse }
+    
+    // Remove potentially sensitive fields in production
+    if (sanitized.details) {
+      // Remove sensitive fields from details
+      const sensitiveFields = ['password', 'token', 'secret', 'key', 'credential']
+      for (const field of sensitiveFields) {
+        if (sanitized.details[field]) {
+          sanitized.details[field] = '[REDACTED]'
+        }
       }
     }
+
+    return sanitized
   }
-  
-  // Handle unknown errors - skip logging for NOT_FOUND unless explicitly enabled
-  if (error.message === 'NOT_FOUND' && !process.env.ENABLE_NOT_FOUND_LOGS) {
-    // Skip logging NOT_FOUND errors to reduce noise
-  } else {
-    logger.error('Unhandled error', { 
-      error: error.message, 
-      stack: error.stack,
-      path,
-      method: request?.method
-    })
+
+  addRecoveryStrategy(strategy: ErrorRecoveryStrategy): void {
+    this.recoveryStrategies.push(strategy)
   }
+
+  removeRecoveryStrategy(strategyClass: new (...args: any[]) => ErrorRecoveryStrategy): void {
+    this.recoveryStrategies = this.recoveryStrategies.filter(
+      strategy => !(strategy instanceof strategyClass)
+    )
+  }
+}
+
+// Legacy error handler for backward compatibility
+export const errorHandler = (error: Error, context: ErrorHandlerContext) => {
+  const handler = new EnhancedErrorHandler()
+  return handler.handle(error, context)
+}
+
+export const createErrorHandler = (
+  baseContext: Omit<ErrorHandlerContext, 'request' | 'path' | 'method'>,
+  options?: ErrorHandlerOptions
+) => {
+  const handler = new EnhancedErrorHandler(options)
   
-  return {
-    error: {
-      message: isDevelopment ? error.message : 'Internal server error',
-      code: 'INTERNAL_ERROR',
-      statusCode: 500,
-      ...(isDevelopment && { stack: error.stack })
+  return async (error: Error, request?: Request, path?: string, method?: string) => {
+    const context: ErrorHandlerContext = {
+      ...baseContext,
+      request,
+      path,
+      method: method || request?.method
     }
+    
+    return handler.handle(error, context)
+  }
+}
+
+// Built-in recovery strategies
+export class RetryRecoveryStrategy implements ErrorRecoveryStrategy {
+  constructor(
+    private maxRetries: number = 3,
+    private retryDelay: number = 1000,
+    private retryableCodes: string[] = ['EXTERNAL_SERVICE_ERROR', 'DATABASE_ERROR']
+  ) {}
+
+  canRecover(error: FluxStackError): boolean {
+    return this.retryableCodes.includes(error.code) && 
+           (!error.context?.retryCount || error.context.retryCount < this.maxRetries)
+  }
+
+  async recover(error: FluxStackError, context: ErrorHandlerContext): Promise<any> {
+    const retryCount = (error.context?.retryCount || 0) + 1
+    
+    context.logger.info('Attempting error recovery', {
+      errorCode: error.code,
+      retryCount,
+      maxRetries: this.maxRetries
+    })
+
+    // Wait before retry
+    await new Promise(resolve => setTimeout(resolve, this.retryDelay * retryCount))
+    
+    // This would typically re-execute the original operation
+    // For now, we'll just return a recovery response
+    throw error.withMetadata({ ...error.metadata, retryCount })
   }
 }
 
-export const createErrorHandler = (context: Omit<ErrorHandlerContext, 'request' | 'path'>) => {
-  return (error: Error, request?: Request, path?: string) => {
-    return errorHandler(error, { ...context, request, path })
+export class FallbackRecoveryStrategy implements ErrorRecoveryStrategy {
+  constructor(
+    private fallbackResponse: any,
+    private applicableCodes: string[] = ['EXTERNAL_SERVICE_ERROR']
+  ) {}
+
+  canRecover(error: FluxStackError): boolean {
+    return this.applicableCodes.includes(error.code)
+  }
+
+  recover(error: FluxStackError, context: ErrorHandlerContext): any {
+    context.logger.info('Using fallback recovery', {
+      errorCode: error.code,
+      correlationId: error.metadata.correlationId
+    })
+
+    return {
+      data: this.fallbackResponse,
+      warning: 'Fallback data provided due to service unavailability'
+    }
   }
 }