create-fluxstack 1.10.1 → 1.12.0

package/core/types/plugin.ts

@@ -1,108 +1,108 @@
-/**
- * Plugin system types
- * Comprehensive type definitions for the plugin system
- */
-
-// Import namespace for type alias
-import type { FluxStack } from "../plugins/types"
-
-// Re-export plugin types
-export type {
-  FluxStack,
-  PluginContext,
-  PluginUtils,
-  RequestContext,
-  ResponseContext,
-  ErrorContext,
-  BuildContext,
-  ConfigLoadContext,
-  RouteContext,
-  ValidationContext,
-  TransformContext,
-  BuildAssetContext,
-  BuildErrorContext,
-  PluginEventContext
-} from "../plugins/types"
-
-// Export Plugin as a standalone type for convenience
-export type Plugin = FluxStack.Plugin
-
-// Additional plugin-related types
-export interface PluginManifest {
-  name: string
-  version: string
-  description: string
-  author: string
-  license: string
-  homepage?: string
-  repository?: string
-  keywords: string[]
-  dependencies: Record<string, string>
-  peerDependencies?: Record<string, string>
-  fluxstack: {
-    version: string
-    hooks: string[]
-    config?: any
-  }
-}
-
-export interface PluginLoadResult {
-  success: boolean
-  plugin?: Plugin
-  error?: string
-  warnings?: string[]
-}
-
-export interface PluginRegistryState {
-  plugins: Map<string, Plugin>
-  loadOrder: string[]
-  dependencies: Map<string, string[]>
-  conflicts: string[]
-}
-
-export interface PluginHookResult {
-  success: boolean
-  error?: Error
-  duration: number
-  plugin: string
-  hook: string
-}
-
-export interface PluginMetrics {
-  loadTime: number
-  setupTime: number
-  hookExecutions: Map<string, number>
-  errors: number
-  warnings: number
-}
-
-export type PluginHook = 
-  | 'setup'
-  | 'onServerStart'
-  | 'onServerStop'
-  | 'onRequest'
-  | 'onResponse'
-  | 'onError'
-
-export type PluginPriority = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number
-
-export interface PluginConfigSchema {
-  type: 'object'
-  properties: Record<string, any>
-  required?: string[]
-  additionalProperties?: boolean
-}
-
-export interface PluginDiscoveryOptions {
-  directories?: string[]
-  patterns?: string[]
-  includeBuiltIn?: boolean
-  includeExternal?: boolean
-}
-
-export interface PluginInstallOptions {
-  version?: string
-  registry?: string
-  force?: boolean
-  dev?: boolean
+/**
+ * Plugin system types
+ * Comprehensive type definitions for the plugin system
+ */
+
+// Import namespace for type alias
+import type { FluxStack } from "../plugins/types"
+
+// Re-export plugin types
+export type {
+  FluxStack,
+  PluginContext,
+  PluginUtils,
+  RequestContext,
+  ResponseContext,
+  ErrorContext,
+  BuildContext,
+  ConfigLoadContext,
+  RouteContext,
+  ValidationContext,
+  TransformContext,
+  BuildAssetContext,
+  BuildErrorContext,
+  PluginEventContext
+} from "../plugins/types"
+
+// Export Plugin as a standalone type for convenience
+export type Plugin = FluxStack.Plugin
+
+// Additional plugin-related types
+export interface PluginManifest {
+  name: string
+  version: string
+  description: string
+  author: string
+  license: string
+  homepage?: string
+  repository?: string
+  keywords: string[]
+  dependencies: Record<string, string>
+  peerDependencies?: Record<string, string>
+  fluxstack: {
+    version: string
+    hooks: string[]
+    config?: any
+  }
+}
+
+export interface PluginLoadResult {
+  success: boolean
+  plugin?: Plugin
+  error?: string
+  warnings?: string[]
+}
+
+export interface PluginRegistryState {
+  plugins: Map<string, Plugin>
+  loadOrder: string[]
+  dependencies: Map<string, string[]>
+  conflicts: string[]
+}
+
+export interface PluginHookResult {
+  success: boolean
+  error?: Error
+  duration: number
+  plugin: string
+  hook: string
+}
+
+export interface PluginMetrics {
+  loadTime: number
+  setupTime: number
+  hookExecutions: Map<string, number>
+  errors: number
+  warnings: number
+}
+
+export type PluginHook = 
+  | 'setup'
+  | 'onServerStart'
+  | 'onServerStop'
+  | 'onRequest'
+  | 'onResponse'
+  | 'onError'
+
+export type PluginPriority = 'highest' | 'high' | 'normal' | 'low' | 'lowest' | number
+
+export interface PluginConfigSchema {
+  type: 'object'
+  properties: Record<string, any>
+  required?: string[]
+  additionalProperties?: boolean
+}
+
+export interface PluginDiscoveryOptions {
+  directories?: string[]
+  patterns?: string[]
+  includeBuiltIn?: boolean
+  includeExternal?: boolean
+}
+
+export interface PluginInstallOptions {
+  version?: string
+  registry?: string
+  force?: boolean
+  dev?: boolean
 }

package/core/types/types.ts

@@ -1,11 +1,56 @@
 // 🔥 FluxStack Live Components - Shared Types
 
+import { roomEvents } from '@core/server/live/RoomEventBus'
+import { liveRoomManager } from '@core/server/live/LiveRoomManager'
+import type { ServerWebSocket } from 'bun'
+
+// ============================================
+// 🔌 WebSocket Types for Server-Side
+// ============================================
+
+/**
+ * WebSocket data stored on each connection
+ * This is attached to ws.data by the WebSocket plugin
+ */
+export interface FluxStackWSData {
+  connectionId: string
+  components: Map<string, LiveComponent>
+  subscriptions: Set<string>
+  connectedAt: Date
+  userId?: string
+}
+
+/**
+ * Type-safe WebSocket interface for FluxStack Live Components
+ * Compatible with both Elysia's ElysiaWS and Bun's ServerWebSocket
+ */
+export interface FluxStackWebSocket {
+  /** Send data to the client */
+  send(data: string | BufferSource, compress?: boolean): number
+  /** Close the connection */
+  close(code?: number, reason?: string): void
+  /** Connection data storage */
+  data: FluxStackWSData
+  /** Remote address of the client */
+  readonly remoteAddress: string
+  /** Current ready state */
+  readonly readyState: 0 | 1 | 2 | 3
+}
+
+/**
+ * Raw ServerWebSocket from Bun with FluxStack data
+ * Use this when you need access to all Bun WebSocket methods
+ */
+export type FluxStackServerWebSocket = ServerWebSocket<FluxStackWSData>
+
 export interface LiveMessage {
   type: 'COMPONENT_MOUNT' | 'COMPONENT_UNMOUNT' |
   'COMPONENT_REHYDRATE' | 'COMPONENT_ACTION' | 'CALL_ACTION' |
   'ACTION_RESPONSE' | 'PROPERTY_UPDATE' | 'STATE_UPDATE' | 'STATE_REHYDRATED' |
   'ERROR' | 'BROADCAST' | 'FILE_UPLOAD_START' | 'FILE_UPLOAD_CHUNK' | 'FILE_UPLOAD_COMPLETE' |
-  'COMPONENT_PING' | 'COMPONENT_PONG'
+  'COMPONENT_PING' | 'COMPONENT_PONG' |
+  // Room system messages
+  'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_STATE_SET' | 'ROOM_STATE_GET'
   componentId: string
   action?: string
   property?: string
@@ -34,6 +79,9 @@ export interface LiveComponentInstance<TState = ComponentState, TActions = Recor
   room?: string
 }
 
+/**
+ * @deprecated Use FluxStackWSData instead
+ */
 export interface WebSocketData {
   components: Map<string, any>
   userId?: string
@@ -43,7 +91,7 @@ export interface WebSocketData {
 export interface ComponentDefinition<TState = ComponentState> {
   name: string
   initialState: TState
-  component: new (initialState: TState, ws: any) => LiveComponent<TState>
+  component: new (initialState: TState, ws: FluxStackWebSocket, options?: { room?: string; userId?: string }) => LiveComponent<TState>
 }
 
 export interface BroadcastMessage {
@@ -69,7 +117,9 @@ export interface WebSocketMessage {
 }
 
 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' | 'COMPONENT_PONG'
+  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' | 'COMPONENT_PONG' |
+  // Room system responses
+  'ROOM_EVENT' | 'ROOM_STATE' | 'ROOM_SYSTEM' | 'ROOM_JOINED' | 'ROOM_LEFT'
   originalType?: string
   componentId?: string
   success?: boolean
@@ -135,27 +185,214 @@ export interface HybridComponentOptions {
   onStateChange?: (newState: any, oldState: any) => void
 }
 
+// Interface para handle de sala no servidor
+export interface ServerRoomHandle<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+  readonly id: string
+  readonly state: TState
+  join: (initialState?: TState) => void
+  leave: () => void
+  emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => number
+  on: <K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void) => () => void
+  setState: (updates: Partial<TState>) => void
+}
+
+// Proxy para $room no servidor
+export interface ServerRoomProxy<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+  (roomId: string): ServerRoomHandle<TState, TEvents>
+  readonly id: string | undefined
+  readonly state: TState
+  join: (initialState?: TState) => void
+  leave: () => void
+  emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => number
+  on: <K extends keyof TEvents>(event: K, handler: (data: TEvents[K]) => void) => () => void
+  setState: (updates: Partial<TState>) => void
+}
+
 export abstract class LiveComponent<TState = ComponentState> {
+  /** Component name for registry lookup - must be defined in subclasses */
+  static componentName: string
+  /** Default state - must be defined in subclasses */
+  static defaultState: any
+
   public readonly id: string
-  public state: TState
-  protected ws: any
+  private _state: TState
+  public state: TState // Proxy wrapper
+  protected ws: FluxStackWebSocket
   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 }) {
+  // Room event subscriptions (cleaned up on destroy)
+  private roomEventUnsubscribers: (() => void)[] = []
+  private joinedRooms: Set<string> = new Set()
+
+  // Room type for typed events (override in subclass)
+  protected roomType: string = 'default'
+
+  // Cached room handles
+  private roomHandles: Map<string, ServerRoomHandle> = new Map()
+
+  constructor(initialState: Partial<TState>, ws: FluxStackWebSocket, options?: { room?: string; userId?: string }) {
     this.id = this.generateId()
-    this.state = initialState
+    // Merge defaultState with initialState - subclass defaultState takes precedence for missing fields
+    const ctor = this.constructor as typeof LiveComponent
+    this._state = { ...ctor.defaultState, ...initialState } as TState
+
+    // Create reactive proxy that auto-syncs on mutation
+    this.state = this.createStateProxy(this._state)
+
     this.ws = ws
     this.room = options?.room
     this.userId = options?.userId
+
+    // Auto-join default room if specified
+    if (this.room) {
+      this.joinedRooms.add(this.room)
+      liveRoomManager.joinRoom(this.id, this.room, this.ws)
+    }
+  }
+
+  // Create a Proxy that auto-emits STATE_UPDATE on any mutation
+  private createStateProxy(state: TState): TState {
+    const self = this
+    return new Proxy(state as object, {
+      set(target, prop, value) {
+        const oldValue = (target as any)[prop]
+        if (oldValue !== value) {
+          (target as any)[prop] = value
+          // Auto-sync to frontend
+          self.emit('STATE_UPDATE', { state: self._state })
+        }
+        return true
+      },
+      get(target, prop) {
+        return (target as any)[prop]
+      }
+    }) as TState
+  }
+
+  // ========================================
+  // 🔥 $room - Sistema de Salas Unificado
+  // ========================================
+
+  /**
+   * Acessa uma sala específica ou a sala padrão
+   * @example
+   * // Sala padrão
+   * this.$room.emit('typing', { user: 'João' })
+   * this.$room.on('message:new', handler)
+   *
+   * // Outra sala
+   * this.$room('sala-vip').join()
+   * this.$room('sala-vip').emit('typing', { user: 'João' })
+   */
+  public get $room(): ServerRoomProxy {
+    const self = this
+
+    const createHandle = (roomId: string): ServerRoomHandle => {
+      // Retornar handle cacheado
+      if (this.roomHandles.has(roomId)) {
+        return this.roomHandles.get(roomId)!
+      }
+
+      const handle: ServerRoomHandle = {
+        get id() { return roomId },
+        get state() { return liveRoomManager.getRoomState(roomId) },
+
+        join: (initialState?: any) => {
+          if (self.joinedRooms.has(roomId)) return
+          self.joinedRooms.add(roomId)
+          liveRoomManager.joinRoom(self.id, roomId, self.ws, initialState)
+        },
+
+        leave: () => {
+          if (!self.joinedRooms.has(roomId)) return
+          self.joinedRooms.delete(roomId)
+          liveRoomManager.leaveRoom(self.id, roomId)
+        },
+
+        emit: (event: string, data: any): number => {
+          return liveRoomManager.emitToRoom(roomId, event, data, self.id)
+        },
+
+        on: (event: string, handler: (data: any) => void): (() => void) => {
+          // Usar 'room' como tipo genérico e roomId como identificador
+          // Isso permite que emitToRoom encontre os handlers corretamente
+          const unsubscribe = roomEvents.on(
+            'room', // Tipo genérico para todas as salas
+            roomId,
+            event,
+            self.id,
+            handler
+          )
+          self.roomEventUnsubscribers.push(unsubscribe)
+          return unsubscribe
+        },
+
+        setState: (updates: any) => {
+          liveRoomManager.setRoomState(roomId, updates, self.id)
+        }
+      }
+
+      this.roomHandles.set(roomId, handle)
+      return handle
+    }
+
+    // Criar proxy que funciona como função e objeto
+    const proxyFn = ((roomId: string) => createHandle(roomId)) as ServerRoomProxy
+
+    const defaultHandle = this.room ? createHandle(this.room) : null
+
+    Object.defineProperties(proxyFn, {
+      id: { get: () => self.room },
+      state: { get: () => defaultHandle?.state ?? {} },
+      join: {
+        value: (initialState?: any) => {
+          if (!defaultHandle) throw new Error('No default room set')
+          defaultHandle.join(initialState)
+        }
+      },
+      leave: {
+        value: () => {
+          if (!defaultHandle) throw new Error('No default room set')
+          defaultHandle.leave()
+        }
+      },
+      emit: {
+        value: (event: string, data: any) => {
+          if (!defaultHandle) throw new Error('No default room set')
+          return defaultHandle.emit(event, data)
+        }
+      },
+      on: {
+        value: (event: string, handler: (data: any) => void) => {
+          if (!defaultHandle) throw new Error('No default room set')
+          return defaultHandle.on(event, handler)
+        }
+      },
+      setState: {
+        value: (updates: any) => {
+          if (!defaultHandle) throw new Error('No default room set')
+          defaultHandle.setState(updates)
+        }
+      }
+    })
+
+    return proxyFn
+  }
+
+  /**
+   * Lista de IDs das salas que este componente está participando
+   */
+  public get $rooms(): string[] {
+    return Array.from(this.joinedRooms)
   }
 
-  // State management
+  // State management (batch update - single emit)
   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 })
+    const newUpdates = typeof updates === 'function' ? updates(this._state) : updates
+    Object.assign(this._state as object, newUpdates)
+    this.emit('STATE_UPDATE', { state: this._state })
   }
 
   // Generic setValue action - set any state key with type safety
@@ -204,8 +441,13 @@ export abstract class LiveComponent<TState = ComponentState> {
     }
   }
 
-  // Broadcast to all clients in room
+  // Broadcast to all clients in room (via WebSocket)
   protected broadcast(type: string, payload: any, excludeCurrentUser = false) {
+    if (!this.room) {
+      console.warn(`⚠️ [${this.id}] Cannot broadcast '${type}' - no room set`)
+      return
+    }
+
     const message: BroadcastMessage = {
       type,
       payload,
@@ -213,10 +455,84 @@ export abstract class LiveComponent<TState = ComponentState> {
       excludeUser: excludeCurrentUser ? this.userId : undefined
     }
 
+    console.log(`📤 [${this.id}] Broadcasting '${type}' to room '${this.room}'`)
+
     // This will be handled by the registry
     this.broadcastToRoom(message)
   }
 
+  // ========================================
+  // 🔥 Room Events - Internal Server Events
+  // ========================================
+
+  /**
+   * Emite um evento para todos os componentes da sala (server-side)
+   * Cada componente inscrito pode reagir e atualizar seu próprio cliente
+   *
+   * @param event - Nome do evento
+   * @param data - Dados do evento
+   * @param notifySelf - Se true, este componente também recebe (default: false)
+   */
+  protected emitRoomEvent(event: string, data: any, notifySelf = false): number {
+    if (!this.room) {
+      console.warn(`⚠️ [${this.id}] Cannot emit room event '${event}' - no room set`)
+      return 0
+    }
+
+    const excludeId = notifySelf ? undefined : this.id
+    const notified = roomEvents.emit(this.roomType, this.room, event, data, excludeId)
+
+    console.log(`📡 [${this.id}] Room event '${event}' → ${notified} components`)
+    return notified
+  }
+
+  /**
+   * Inscreve este componente em um evento da sala
+   * Handler é chamado quando outro componente emite o evento
+   *
+   * @param event - Nome do evento para escutar
+   * @param handler - Função chamada quando evento é recebido
+   */
+  protected onRoomEvent<T = any>(event: string, handler: (data: T) => void): void {
+    if (!this.room) {
+      console.warn(`⚠️ [${this.id}] Cannot subscribe to room event '${event}' - no room set`)
+      return
+    }
+
+    const unsubscribe = roomEvents.on(
+      this.roomType,
+      this.room,
+      event,
+      this.id,
+      handler
+    )
+
+    // Guardar para cleanup no destroy
+    this.roomEventUnsubscribers.push(unsubscribe)
+
+    console.log(`👂 [${this.id}] Subscribed to room event '${event}'`)
+  }
+
+  /**
+   * Helper: Emite evento E atualiza estado local + envia pro cliente
+   * Útil para o componente que origina a ação
+   *
+   * @param event - Nome do evento
+   * @param data - Dados do evento
+   * @param stateUpdates - Atualizações de estado para aplicar localmente
+   */
+  protected emitRoomEventWithState(
+    event: string,
+    data: any,
+    stateUpdates: Partial<TState>
+  ): number {
+    // 1. Atualiza estado local (envia pro cliente deste componente)
+    this.setState(stateUpdates)
+
+    // 2. Emite evento para outros componentes da sala
+    return this.emitRoomEvent(event, data, false)
+  }
+
   // Subscribe to room for multi-user features
   protected async subscribeToRoom(roomId: string) {
     this.room = roomId
@@ -236,6 +552,19 @@ export abstract class LiveComponent<TState = ComponentState> {
 
   // Cleanup when component is destroyed
   public destroy() {
+    // Limpa todas as inscrições de room events
+    for (const unsubscribe of this.roomEventUnsubscribers) {
+      unsubscribe()
+    }
+    this.roomEventUnsubscribers = []
+
+    // Sai de todas as salas
+    for (const roomId of this.joinedRooms) {
+      liveRoomManager.leaveRoom(this.id, roomId)
+    }
+    this.joinedRooms.clear()
+    this.roomHandles.clear()
+
     this.unsubscribeFromRoom()
     // Override in subclasses for custom cleanup
   }
@@ -407,11 +736,21 @@ export interface FileUploadChunkMessage {
   uploadId: string
   chunkIndex: number
   totalChunks: number
-  data: string // Base64 encoded chunk
+  data: string | Buffer // Base64 string (JSON) or Buffer (binary protocol)
   hash?: string
   requestId?: string
 }
 
+// Binary protocol header for chunk uploads
+export interface BinaryChunkHeader {
+  type: 'FILE_UPLOAD_CHUNK'
+  componentId: string
+  uploadId: string
+  chunkIndex: number
+  totalChunks: number
+  requestId?: string
+}
+
 export interface FileUploadCompleteMessage {
   type: 'FILE_UPLOAD_COMPLETE'
   componentId: string
@@ -452,7 +791,7 @@ export interface ActiveUpload {
   fileType: string
   fileSize: number
   totalChunks: number
-  receivedChunks: Map<number, string>
+  receivedChunks: Map<number, string | Buffer> // Base64 string or raw Buffer (binary protocol)
   bytesReceived: number // Track actual bytes received for adaptive chunking
   startTime: number
   lastChunkTime: number