@talex-touch/utils 1.0.42 → 1.0.45

package/transport/errors.ts

@@ -0,0 +1,310 @@
+/**
+ * @fileoverview Error types for TuffTransport
+ * @module @talex-touch/utils/transport/errors
+ */
+
+// ============================================================================
+// Error Codes
+// ============================================================================
+
+/**
+ * Error codes for TuffTransport operations.
+ */
+export enum TuffTransportErrorCode {
+  /**
+   * Event is not a valid TuffEvent instance.
+   */
+  INVALID_EVENT = 'INVALID_EVENT',
+
+  /**
+   * No handler registered for the event.
+   */
+  UNKNOWN_EVENT = 'UNKNOWN_EVENT',
+
+  /**
+   * Request timed out waiting for response.
+   */
+  TIMEOUT = 'TIMEOUT',
+
+  /**
+   * Stream was cancelled by the client.
+   */
+  STREAM_CANCELLED = 'STREAM_CANCELLED',
+
+  /**
+   * Batch request failed.
+   */
+  BATCH_FAILED = 'BATCH_FAILED',
+
+  /**
+   * Failed to serialize request payload.
+   */
+  SERIALIZE_FAILED = 'SERIALIZE_FAILED',
+
+  /**
+   * Failed to deserialize response payload.
+   */
+  DESERIALIZE_FAILED = 'DESERIALIZE_FAILED',
+
+  /**
+   * Target window/WebContents not found or destroyed.
+   */
+  TARGET_NOT_FOUND = 'TARGET_NOT_FOUND',
+
+  /**
+   * Plugin security key is invalid or expired.
+   */
+  INVALID_PLUGIN_KEY = 'INVALID_PLUGIN_KEY',
+
+  /**
+   * Plugin attempted unauthorized operation.
+   */
+  PLUGIN_UNAUTHORIZED = 'PLUGIN_UNAUTHORIZED',
+
+  /**
+   * IPC channel error (e.g., EPIPE).
+   */
+  IPC_ERROR = 'IPC_ERROR',
+
+  /**
+   * Transport instance has been destroyed.
+   */
+  TRANSPORT_DESTROYED = 'TRANSPORT_DESTROYED',
+
+  /**
+   * Generic internal error.
+   */
+  INTERNAL_ERROR = 'INTERNAL_ERROR',
+}
+
+// ============================================================================
+// Error Class
+// ============================================================================
+
+/**
+ * Custom error class for TuffTransport operations.
+ *
+ * @remarks
+ * Provides structured error information including error codes,
+ * event context, and optional cause for error chaining.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await transport.send(event, payload)
+ * } catch (err) {
+ *   if (err instanceof TuffTransportError) {
+ *     switch (err.code) {
+ *       case TuffTransportErrorCode.TIMEOUT:
+ *         // Handle timeout
+ *         break
+ *       case TuffTransportErrorCode.INVALID_PLUGIN_KEY:
+ *         // Handle auth error
+ *         break
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export class TuffTransportError extends Error {
+  /**
+   * Error code for programmatic handling.
+   */
+  readonly code: TuffTransportErrorCode
+
+  /**
+   * Event name associated with this error (if applicable).
+   */
+  readonly eventName?: string
+
+  /**
+   * Plugin name associated with this error (if applicable).
+   */
+  readonly pluginName?: string
+
+  /**
+   * Original error that caused this error (if applicable).
+   */
+  override readonly cause?: Error
+
+  /**
+   * Timestamp when this error occurred.
+   */
+  readonly timestamp: number
+
+  /**
+   * Creates a new TuffTransportError.
+   *
+   * @param code - Error code
+   * @param message - Human-readable error message
+   * @param options - Additional error context
+   */
+  constructor(
+    code: TuffTransportErrorCode,
+    message: string,
+    options?: {
+      eventName?: string
+      pluginName?: string
+      cause?: Error
+    },
+  ) {
+    super(message)
+    this.name = 'TuffTransportError'
+    this.code = code
+    this.eventName = options?.eventName
+    this.pluginName = options?.pluginName
+    this.cause = options?.cause
+    this.timestamp = Date.now()
+
+    // Maintain proper stack trace in V8 environments
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TuffTransportError)
+    }
+  }
+
+  /**
+   * Creates a serializable representation of this error.
+   *
+   * @returns Plain object representation
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      eventName: this.eventName,
+      pluginName: this.pluginName,
+      timestamp: this.timestamp,
+      stack: this.stack,
+    }
+  }
+
+  /**
+   * Creates a TuffTransportError from a plain object.
+   *
+   * @param obj - Plain object (e.g., from IPC)
+   * @returns TuffTransportError instance
+   */
+  static fromJSON(obj: Record<string, unknown>): TuffTransportError {
+    const error = new TuffTransportError(
+      (obj.code as TuffTransportErrorCode) || TuffTransportErrorCode.INTERNAL_ERROR,
+      (obj.message as string) || 'Unknown error',
+      {
+        eventName: obj.eventName as string | undefined,
+        pluginName: obj.pluginName as string | undefined,
+      },
+    )
+    if (obj.stack && typeof obj.stack === 'string') {
+      error.stack = obj.stack
+    }
+    return error
+  }
+}
+
+// ============================================================================
+// Error Factory Functions
+// ============================================================================
+
+/**
+ * Creates an INVALID_EVENT error.
+ *
+ * @param context - Context where the error occurred
+ * @returns TuffTransportError
+ */
+export function createInvalidEventError(context: string): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.INVALID_EVENT,
+    `[${context}] Invalid event. Expected TuffEvent created via defineEvent(), `
+    + `received a string or invalid object. String event names are not allowed.`,
+  )
+}
+
+/**
+ * Creates a TIMEOUT error.
+ *
+ * @param eventName - Event that timed out
+ * @param timeoutMs - Timeout duration in milliseconds
+ * @returns TuffTransportError
+ */
+export function createTimeoutError(eventName: string, timeoutMs: number): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.TIMEOUT,
+    `Request "${eventName}" timed out after ${timeoutMs}ms`,
+    { eventName },
+  )
+}
+
+/**
+ * Creates an UNKNOWN_EVENT error.
+ *
+ * @param eventName - Event name that was not found
+ * @returns TuffTransportError
+ */
+export function createUnknownEventError(eventName: string): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.UNKNOWN_EVENT,
+    `No handler registered for event "${eventName}"`,
+    { eventName },
+  )
+}
+
+/**
+ * Creates an INVALID_PLUGIN_KEY error.
+ *
+ * @param pluginName - Plugin name (if known)
+ * @returns TuffTransportError
+ */
+export function createInvalidPluginKeyError(pluginName?: string): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.INVALID_PLUGIN_KEY,
+    pluginName
+      ? `Invalid or expired security key for plugin "${pluginName}"`
+      : 'Invalid or expired plugin security key',
+    { pluginName },
+  )
+}
+
+/**
+ * Creates a TARGET_NOT_FOUND error.
+ *
+ * @param target - Description of the target
+ * @param eventName - Event name (if applicable)
+ * @returns TuffTransportError
+ */
+export function createTargetNotFoundError(target: string, eventName?: string): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.TARGET_NOT_FOUND,
+    `Target "${target}" not found or has been destroyed`,
+    { eventName },
+  )
+}
+
+/**
+ * Creates a SERIALIZE_FAILED error.
+ *
+ * @param eventName - Event name
+ * @param cause - Original error
+ * @returns TuffTransportError
+ */
+export function createSerializeError(eventName: string, cause: Error): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.SERIALIZE_FAILED,
+    `Failed to serialize payload for "${eventName}": ${cause.message}`,
+    { eventName, cause },
+  )
+}
+
+/**
+ * Creates a STREAM_CANCELLED error.
+ *
+ * @param eventName - Event name
+ * @param streamId - Stream identifier
+ * @returns TuffTransportError
+ */
+export function createStreamCancelledError(eventName: string, streamId: string): TuffTransportError {
+  return new TuffTransportError(
+    TuffTransportErrorCode.STREAM_CANCELLED,
+    `Stream "${streamId}" for event "${eventName}" was cancelled`,
+    { eventName },
+  )
+}

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'