@talex-touch/utils 1.0.40 → 1.0.44

package/transport/event/builder.ts

@@ -0,0 +1,378 @@
+/**
+ * @fileoverview TuffEvent Builder - Type-safe event definition system
+ * @module @talex-touch/utils/transport/event/builder
+ */
+
+import type { EventOptions, TuffEvent } from './types'
+
+// ============================================================================
+// Builder Classes
+// ============================================================================
+
+/**
+ * Namespace builder - Entry point for event definition.
+ *
+ * @typeParam TNamespace - The namespace string type
+ *
+ * @example
+ * ```typescript
+ * const builder = TuffEventBuilder.namespace('core-box')
+ * // or use the shorthand:
+ * const builder = defineEvent('core-box')
+ * ```
+ */
+export class TuffEventBuilder<TNamespace extends string> {
+  private readonly _namespace: TNamespace
+
+  private constructor(namespace: TNamespace) {
+    this._namespace = namespace
+  }
+
+  /**
+   * Creates a new event builder with the specified namespace.
+   *
+   * @param ns - The namespace string (e.g., 'core-box', 'storage')
+   * @returns A new TuffEventBuilder instance
+   * @throws {Error} If namespace is empty or not a string
+   *
+   * @example
+   * ```typescript
+   * const builder = TuffEventBuilder.namespace('my-plugin')
+   * ```
+   */
+  static namespace<T extends string>(ns: T): TuffEventBuilder<T> {
+    if (!ns || typeof ns !== 'string') {
+      throw new Error('[TuffEvent] Namespace must be a non-empty string')
+    }
+    return new TuffEventBuilder(ns)
+  }
+
+  /**
+   * Defines the module for this event.
+   *
+   * @param module - The module string (e.g., 'search', 'ui')
+   * @returns A TuffModuleBuilder instance
+   * @throws {Error} If module is empty or not a string
+   *
+   * @example
+   * ```typescript
+   * defineEvent('core-box').module('search')
+   * ```
+   */
+  module<TModule extends string>(module: TModule): TuffModuleBuilder<TNamespace, TModule> {
+    if (!module || typeof module !== 'string') {
+      throw new Error('[TuffEvent] Module must be a non-empty string')
+    }
+    return new TuffModuleBuilder(this._namespace, module)
+  }
+}
+
+/**
+ * Module builder - Second stage of event definition.
+ *
+ * @typeParam TNamespace - The namespace string type
+ * @typeParam TModule - The module string type
+ */
+export class TuffModuleBuilder<
+  TNamespace extends string,
+  TModule extends string,
+> {
+  /**
+   * @internal
+   */
+  constructor(
+    private readonly _namespace: TNamespace,
+    private readonly _module: TModule,
+  ) {}
+
+  /**
+   * Defines the action for this event.
+   *
+   * @param action - The action string (e.g., 'query', 'hide')
+   * @returns A TuffActionBuilder instance
+   * @throws {Error} If action is empty or not a string
+   *
+   * @example
+   * ```typescript
+   * defineEvent('core-box').module('search').event('query')
+   * ```
+   */
+  event<TAction extends string>(action: TAction): TuffActionBuilder<TNamespace, TModule, TAction> {
+    if (!action || typeof action !== 'string') {
+      throw new Error('[TuffEvent] Action must be a non-empty string')
+    }
+    return new TuffActionBuilder(this._namespace, this._module, action)
+  }
+}
+
+/**
+ * Action builder - Final stage of event definition.
+ *
+ * @typeParam TNamespace - The namespace string type
+ * @typeParam TModule - The module string type
+ * @typeParam TAction - The action string type
+ */
+export class TuffActionBuilder<
+  TNamespace extends string,
+  TModule extends string,
+  TAction extends string,
+> {
+  /**
+   * @internal
+   */
+  constructor(
+    private readonly _namespace: TNamespace,
+    private readonly _module: TModule,
+    private readonly _action: TAction,
+  ) {}
+
+  /**
+   * Finalizes the event definition with request/response types.
+   *
+   * @typeParam TRequest - Type of the request payload (default: void)
+   * @typeParam TResponse - Type of the response payload (default: void)
+   * @param options - Optional batch/stream configuration
+   * @returns An immutable TuffEvent instance
+   *
+   * @example
+   * ```typescript
+   * // Simple event with no payload
+   * const hideEvent = defineEvent('core-box')
+   *   .module('ui')
+   *   .event('hide')
+   *   .define()
+   *
+   * // Event with typed request/response
+   * const queryEvent = defineEvent('core-box')
+   *   .module('search')
+   *   .event('query')
+   *   .define<{ text: string }, SearchResult[]>()
+   *
+   * // Event with batch configuration
+   * const getEvent = defineEvent('storage')
+   *   .module('app')
+   *   .event('get')
+   *   .define<{ key: string }, unknown>({
+   *     batch: { enabled: true, windowMs: 50 }
+   *   })
+   *
+   * // Stream event
+   * const streamEvent = defineEvent('core-box')
+   *   .module('search')
+   *   .event('stream')
+   *   .define<{ text: string }, AsyncIterable<SearchResult>>({
+   *     stream: { enabled: true }
+   *   })
+   * ```
+   */
+  define<TRequest = void, TResponse = void>(
+    options?: EventOptions,
+  ): TuffEvent<TRequest, TResponse, TNamespace, TModule, TAction> {
+    const namespace = this._namespace
+    const module = this._module
+    const action = this._action
+    const eventName = `${namespace}:${module}:${action}`
+
+    // Create immutable event object
+    const event: TuffEvent<TRequest, TResponse, TNamespace, TModule, TAction> = Object.freeze({
+      __brand: 'TuffEvent' as const,
+      namespace,
+      module,
+      action,
+      _batch: options?.batch,
+      _stream: options?.stream,
+      _request: undefined as unknown as TRequest,
+      _response: undefined as unknown as TResponse,
+
+      toString(): string {
+        return eventName
+      },
+
+      toEventName(): string {
+        return eventName
+      },
+    })
+
+    return event
+  }
+}
+
+// ============================================================================
+// Shorthand Functions
+// ============================================================================
+
+/**
+ * Creates a new event definition builder.
+ *
+ * @remarks
+ * This is the primary entry point for defining TuffEvents.
+ * All events MUST be created using this builder to ensure type safety.
+ *
+ * @param namespace - The event namespace (e.g., 'core-box', 'storage', 'plugin')
+ * @returns A TuffEventBuilder instance
+ *
+ * @example
+ * ```typescript
+ * // Define a simple event
+ * const hideEvent = defineEvent('core-box')
+ *   .module('ui')
+ *   .event('hide')
+ *   .define()
+ *
+ * // Define an event with typed payloads
+ * const queryEvent = defineEvent('core-box')
+ *   .module('search')
+ *   .event('query')
+ *   .define<QueryRequest, QueryResponse>()
+ *
+ * // Define a batch-enabled event
+ * const getEvent = defineEvent('storage')
+ *   .module('app')
+ *   .event('get')
+ *   .define<{ key: string }, unknown>({
+ *     batch: { enabled: true, windowMs: 50, maxSize: 20 }
+ *   })
+ * ```
+ */
+export const defineEvent = TuffEventBuilder.namespace
+
+/**
+ * Defines a TuffEvent using a raw event name string.
+ *
+ * @remarks
+ * This is intended for incremental migrations from legacy IPC event names that
+ * don't follow the `namespace:module:action` convention yet.
+ *
+ * Prefer `defineEvent(namespace).module(module).event(action)` for new code.
+ */
+export function defineRawEvent<TRequest = void, TResponse = void>(
+  eventName: string,
+  options?: EventOptions,
+): TuffEvent<TRequest, TResponse, string, string, string> {
+  if (!eventName || typeof eventName !== 'string') {
+    throw new Error('[TuffEvent] Raw event name must be a non-empty string')
+  }
+
+  const parts = eventName.split(':')
+  const namespace = parts[0] || 'raw'
+  const module = parts.length >= 2 ? (parts[1] || 'raw') : 'raw'
+  const action = parts.length >= 3 ? (parts.slice(2).join(':') || 'raw') : 'raw'
+
+  const event: TuffEvent<TRequest, TResponse, string, string, string> = Object.freeze({
+    __brand: 'TuffEvent' as const,
+    namespace,
+    module,
+    action,
+    _batch: options?.batch,
+    _stream: options?.stream,
+    _request: undefined as unknown as TRequest,
+    _response: undefined as unknown as TResponse,
+
+    toString(): string {
+      return eventName
+    },
+
+    toEventName(): string {
+      return eventName
+    },
+  })
+
+  return event
+}
+
+// ============================================================================
+// Type Guards and Assertions
+// ============================================================================
+
+/**
+ * Runtime type guard to check if a value is a valid TuffEvent.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a TuffEvent, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * if (isTuffEvent(maybeEvent)) {
+ *   // TypeScript now knows maybeEvent is a TuffEvent
+ *   console.log(maybeEvent.toString())
+ * }
+ * ```
+ */
+export function isTuffEvent(value: unknown): value is TuffEvent {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && (value as Record<string, unknown>).__brand === 'TuffEvent'
+    && typeof (value as Record<string, unknown>).toString === 'function'
+    && typeof (value as Record<string, unknown>).namespace === 'string'
+    && typeof (value as Record<string, unknown>).module === 'string'
+    && typeof (value as Record<string, unknown>).action === 'string'
+  )
+}
+
+/**
+ * Asserts that a value is a valid TuffEvent, throwing if not.
+ *
+ * @param value - The value to assert
+ * @param context - Optional context string for error messages
+ * @throws {TypeError} If the value is not a TuffEvent
+ *
+ * @example
+ * ```typescript
+ * function sendEvent(event: unknown, payload: unknown) {
+ *   assertTuffEvent(event, 'sendEvent')
+ *   // TypeScript now knows event is a TuffEvent
+ *   console.log(`Sending: ${event.toString()}`)
+ * }
+ * ```
+ */
+export function assertTuffEvent(
+  value: unknown,
+  context?: string,
+): asserts value is TuffEvent {
+  if (!isTuffEvent(value)) {
+    const prefix = context ? `[${context}] ` : ''
+    throw new TypeError(
+      `${prefix}Invalid event. Expected TuffEvent created via defineEvent(), `
+      + `got ${value === null ? 'null' : typeof value}. `
+      + `String event names are not allowed - use the event builder.`,
+    )
+  }
+}
+
+/**
+ * Extracts the event name string from a TuffEvent.
+ *
+ * @param event - The TuffEvent to extract from
+ * @returns The event name string
+ *
+ * @example
+ * ```typescript
+ * const name = getEventName(CoreBoxEvents.ui.hide)
+ * // name = 'core-box:ui:hide'
+ * ```
+ */
+export function getEventName(event: TuffEvent): string {
+  assertTuffEvent(event, 'getEventName')
+  return event.toString()
+}
+
+/**
+ * Checks if an event has batch configuration enabled.
+ *
+ * @param event - The TuffEvent to check
+ * @returns `true` if batch is enabled
+ */
+export function isBatchEnabled(event: TuffEvent): boolean {
+  return event._batch?.enabled === true
+}
+
+/**
+ * Checks if an event has stream configuration enabled.
+ *
+ * @param event - The TuffEvent to check
+ * @returns `true` if stream is enabled
+ */
+export function isStreamEnabled(event: TuffEvent): boolean {
+  return event._stream?.enabled === true
+}

package/transport/event/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @fileoverview Event module exports
+ * @module @talex-touch/utils/transport/event
+ */
+
+export * from './builder'
+export * from './types'

package/transport/event/types.ts

@@ -0,0 +1,292 @@
+/**
+ * @fileoverview Core type definitions for TuffEvent system
+ * @module @talex-touch/utils/transport/event/types
+ */
+
+// ============================================================================
+// Brand Symbol for Type Safety
+// ============================================================================
+
+/**
+ * Unique symbol used for branding TuffEvent instances.
+ * This ensures type-level distinction from plain objects.
+ * @internal
+ */
+declare const _TuffEventBrand: unique symbol
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Merge strategy for batch requests.
+ *
+ * @remarks
+ * - `queue` - All requests are queued in order
+ * - `dedupe` - Duplicate payloads share a single request/response
+ * - `latest` - Only the latest request for a given key is kept
+ */
+export type BatchMergeStrategy = 'queue' | 'dedupe' | 'latest'
+
+/**
+ * Backpressure strategy for stream processing.
+ *
+ * @remarks
+ * - `drop` - Drop new data when buffer is full
+ * - `buffer` - Buffer data (may cause memory growth)
+ * - `error` - Throw error when buffer is full
+ */
+export type StreamBackpressure = 'drop' | 'buffer' | 'error'
+
+/**
+ * Configuration for batch request merging.
+ *
+ * @example
+ * ```typescript
+ * const config: BatchConfig = {
+ *   enabled: true,
+ *   windowMs: 50,
+ *   maxSize: 20,
+ *   mergeStrategy: 'dedupe'
+ * }
+ * ```
+ */
+export interface BatchConfig {
+  /**
+   * Whether batch mode is enabled for this event.
+   * @defaultValue false
+   */
+  enabled: boolean
+
+  /**
+   * Time window in milliseconds to collect requests before flushing.
+   * @defaultValue 50
+   */
+  windowMs?: number
+
+  /**
+   * Maximum number of requests to batch before forcing a flush.
+   * @defaultValue 50
+   */
+  maxSize?: number
+
+  /**
+   * Strategy for merging duplicate requests.
+   * @defaultValue 'queue'
+   */
+  mergeStrategy?: BatchMergeStrategy
+}
+
+/**
+ * Configuration for stream-based communication.
+ *
+ * @example
+ * ```typescript
+ * const config: StreamConfig = {
+ *   enabled: true,
+ *   bufferSize: 100,
+ *   backpressure: 'buffer'
+ * }
+ * ```
+ */
+export interface StreamConfig {
+  /**
+   * Whether stream mode is enabled for this event.
+   * @defaultValue false
+   */
+  enabled: boolean
+
+  /**
+   * Maximum number of items to buffer.
+   * @defaultValue 100
+   */
+  bufferSize?: number
+
+  /**
+   * Strategy for handling backpressure.
+   * @defaultValue 'buffer'
+   */
+  backpressure?: StreamBackpressure
+}
+
+/**
+ * Options for event definition.
+ */
+export interface EventOptions {
+  /**
+   * Batch configuration for this event.
+   */
+  batch?: BatchConfig
+
+  /**
+   * Stream configuration for this event.
+   */
+  stream?: StreamConfig
+}
+
+// ============================================================================
+// TuffEvent Core Interface
+// ============================================================================
+
+/**
+ * Type-safe event definition for TuffTransport.
+ *
+ * @remarks
+ * TuffEvent instances are immutable and created via the event builder.
+ * They encode request/response types at the type level for compile-time safety.
+ *
+ * @typeParam TRequest - Type of the request payload
+ * @typeParam TResponse - Type of the response payload
+ * @typeParam TNamespace - Event namespace (e.g., 'core-box')
+ * @typeParam TModule - Event module (e.g., 'search')
+ * @typeParam TAction - Event action (e.g., 'query')
+ *
+ * @example
+ * ```typescript
+ * const event: TuffEvent<{ text: string }, SearchResult[]> = defineEvent('core-box')
+ *   .module('search')
+ *   .event('query')
+ *   .define()
+ *
+ * // event.toString() returns 'core-box:search:query'
+ * ```
+ */
+export interface TuffEvent<
+  TRequest = void,
+  TResponse = void,
+  TNamespace extends string = string,
+  TModule extends string = string,
+  TAction extends string = string,
+> {
+  /**
+   * Brand identifier for runtime type checking.
+   * @internal
+   */
+  readonly __brand: 'TuffEvent'
+
+  /**
+   * Event namespace (first segment of event name).
+   * @example 'core-box', 'storage', 'plugin'
+   */
+  readonly namespace: TNamespace
+
+  /**
+   * Event module (second segment of event name).
+   * @example 'search', 'ui', 'lifecycle'
+   */
+  readonly module: TModule
+
+  /**
+   * Event action (third segment of event name).
+   * @example 'query', 'hide', 'load'
+   */
+  readonly action: TAction
+
+  /**
+   * Batch configuration for this event.
+   * @internal
+   */
+  readonly _batch?: BatchConfig
+
+  /**
+   * Stream configuration for this event.
+   * @internal
+   */
+  readonly _stream?: StreamConfig
+
+  /**
+   * Type marker for request payload (compile-time only).
+   * @internal
+   */
+  readonly _request: TRequest
+
+  /**
+   * Type marker for response payload (compile-time only).
+   * @internal
+   */
+  readonly _response: TResponse
+
+  /**
+   * Converts event to its string representation.
+   * @returns Event name in format 'namespace:module:action'
+   */
+  toString: () => string
+
+  /**
+   * Gets the full event name.
+   * @returns Event name in format 'namespace:module:action'
+   */
+  toEventName: () => string
+}
+
+// ============================================================================
+// Type Utilities
+// ============================================================================
+
+/**
+ * Extracts the request type from a TuffEvent.
+ *
+ * @typeParam E - The TuffEvent type
+ *
+ * @example
+ * ```typescript
+ * type Req = EventRequest<typeof CoreBoxEvents.search.query>
+ * // Req = { text: string }
+ * ```
+ */
+export type EventRequest<E> = E extends TuffEvent<infer R, any, any, any, any> ? R : never
+
+/**
+ * Extracts the response type from a TuffEvent.
+ *
+ * @typeParam E - The TuffEvent type
+ *
+ * @example
+ * ```typescript
+ * type Res = EventResponse<typeof CoreBoxEvents.search.query>
+ * // Res = TuffSearchResult
+ * ```
+ */
+export type EventResponse<E> = E extends TuffEvent<any, infer R, any, any, any> ? R : never
+
+/**
+ * Checks if an event is a stream event (response is AsyncIterable).
+ *
+ * @typeParam E - The TuffEvent type
+ */
+export type IsStreamEvent<E> = E extends TuffEvent<any, AsyncIterable<any>, any, any, any>
+  ? true
+  : false
+
+/**
+ * Extracts the chunk type from a stream event.
+ *
+ * @typeParam E - The TuffEvent type (must be a stream event)
+ *
+ * @example
+ * ```typescript
+ * type Chunk = StreamChunk<typeof CoreBoxEvents.search.stream>
+ * // Chunk = SearchResult
+ * ```
+ */
+export type StreamChunk<E> = E extends TuffEvent<any, AsyncIterable<infer C>, any, any, any>
+  ? C
+  : never
+
+/**
+ * Extracts the namespace from a TuffEvent.
+ * @internal
+ */
+export type EventNamespace<E> = E extends TuffEvent<any, any, infer N, any, any> ? N : never
+
+/**
+ * Extracts the module from a TuffEvent.
+ * @internal
+ */
+export type EventModule<E> = E extends TuffEvent<any, any, any, infer M, any> ? M : never
+
+/**
+ * Extracts the action from a TuffEvent.
+ * @internal
+ */
+export type EventAction<E> = E extends TuffEvent<any, any, any, any, infer A> ? A : never