@computekit/core 0.1.0

package/src/types.ts

@@ -0,0 +1,229 @@
+/**
+ * ComputeKit Core Types
+ * Type definitions for the WASM + Worker toolkit
+ */
+
+/** Configuration options for ComputeKit */
+export interface ComputeKitOptions {
+  /** Maximum number of workers in the pool (default: navigator.hardwareConcurrency || 4) */
+  maxWorkers?: number;
+  /** Timeout for compute operations in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+  /** Custom path to worker script */
+  workerPath?: string;
+  /** Whether to use SharedArrayBuffer when available (default: true) */
+  useSharedMemory?: boolean;
+}
+
+/** Options for individual compute operations */
+export interface ComputeOptions {
+  /** Timeout for this specific operation (overrides global) */
+  timeout?: number;
+  /** Transfer these ArrayBuffers to the worker (improves performance) */
+  transfer?: ArrayBuffer[];
+  /** Priority level for scheduling (0-10, higher = more priority) */
+  priority?: number;
+  /** Abort signal to cancel the operation */
+  signal?: AbortSignal;
+  /** Progress callback for long-running operations */
+  onProgress?: (progress: ComputeProgress) => void;
+}
+
+/** Progress information for compute operations */
+export interface ComputeProgress {
+  /** Progress percentage (0-100) */
+  percent: number;
+  /** Current step/phase name */
+  phase?: string;
+  /** Estimated time remaining in milliseconds */
+  estimatedTimeRemaining?: number;
+  /** Any additional data from the compute function */
+  data?: unknown;
+}
+
+/** Result wrapper with metadata */
+export interface ComputeResult<T> {
+  /** The computed result */
+  data: T;
+  /** Time taken in milliseconds */
+  duration: number;
+  /** Whether the result came from cache */
+  cached: boolean;
+  /** Worker ID that processed this */
+  workerId: string;
+}
+
+/** Function definition for registration */
+export interface ComputeFunction<TInput = unknown, TOutput = unknown> {
+  /** The compute function implementation */
+  fn: (input: TInput) => TOutput | Promise<TOutput>;
+  /** Optional WASM module to load */
+  wasmModule?: WebAssembly.Module | ArrayBuffer | string;
+  /** Whether this function supports progress reporting */
+  supportsProgress?: boolean;
+}
+
+/** WASM module configuration */
+export interface WasmModuleConfig {
+  /** Path to the WASM file or base64 encoded WASM */
+  source: string | ArrayBuffer;
+  /** Imports to provide to the WASM module */
+  imports?: WebAssembly.Imports;
+  /** Memory configuration */
+  memory?: {
+    initial: number;
+    maximum?: number;
+    shared?: boolean;
+  };
+}
+
+/** Worker message types */
+export type WorkerMessageType =
+  | 'execute'
+  | 'result'
+  | 'error'
+  | 'progress'
+  | 'init'
+  | 'ready'
+  | 'terminate';
+
+/** Base worker message */
+export interface WorkerMessage<T = unknown> {
+  id: string;
+  type: WorkerMessageType;
+  payload?: T;
+  timestamp: number;
+}
+
+/** Execute message payload */
+export interface ExecutePayload {
+  functionName: string;
+  input: unknown;
+  options?: ComputeOptions;
+}
+
+/** Result message payload */
+export interface ResultPayload<T = unknown> {
+  data: T;
+  duration: number;
+  transfer?: ArrayBuffer[];
+}
+
+/** Error message payload */
+export interface ErrorPayload {
+  message: string;
+  stack?: string;
+  code?: string;
+}
+
+/** Progress message payload */
+export interface ProgressPayload {
+  taskId: string;
+  progress: ComputeProgress;
+}
+
+/** Worker state */
+export type WorkerState = 'idle' | 'busy' | 'error' | 'terminated';
+
+/** Worker info */
+export interface WorkerInfo {
+  id: string;
+  state: WorkerState;
+  currentTask?: string;
+  tasksCompleted: number;
+  errors: number;
+  createdAt: number;
+  lastActiveAt: number;
+}
+
+/** Pool statistics */
+export interface PoolStats {
+  workers: WorkerInfo[];
+  totalWorkers: number;
+  activeWorkers: number;
+  idleWorkers: number;
+  queueLength: number;
+  tasksCompleted: number;
+  tasksFailed: number;
+  averageTaskDuration: number;
+}
+
+/** Event data for worker:created */
+export interface WorkerCreatedEvent {
+  info: WorkerInfo;
+}
+
+/** Event data for worker:terminated */
+export interface WorkerTerminatedEvent {
+  info: WorkerInfo;
+}
+
+/** Event data for worker:error */
+export interface WorkerErrorEvent {
+  error: Error;
+  info: WorkerInfo;
+}
+
+/** Event data for task:start */
+export interface TaskStartEvent {
+  taskId: string;
+  functionName: string;
+}
+
+/** Event data for task:complete */
+export interface TaskCompleteEvent {
+  taskId: string;
+  duration: number;
+}
+
+/** Event data for task:error */
+export interface TaskErrorEvent {
+  taskId: string;
+  error: Error;
+}
+
+/** Event data for task:progress */
+export interface TaskProgressEvent {
+  taskId: string;
+  progress: ComputeProgress;
+}
+
+/** Events emitted by ComputeKit */
+export type ComputeKitEvents = {
+  'worker:created': WorkerCreatedEvent;
+  'worker:terminated': WorkerTerminatedEvent;
+  'worker:error': WorkerErrorEvent;
+  'task:start': TaskStartEvent;
+  'task:complete': TaskCompleteEvent;
+  'task:error': TaskErrorEvent;
+  'task:progress': TaskProgressEvent;
+  [key: string]: unknown;
+};
+
+/** Type helper for compute function signatures */
+export type ComputeFn<TInput, TOutput> = (
+  input: TInput,
+  options?: ComputeOptions
+) => Promise<TOutput>;
+
+/** Registry of compute functions */
+export type ComputeRegistry = Map<string, ComputeFunction>;
+
+/** Transferable types */
+export type Transferable = ArrayBuffer | MessagePort | ImageBitmap | OffscreenCanvas;
+
+/** Serializable types for worker communication */
+export type Serializable =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | Serializable[]
+  | { [key: string]: Serializable }
+  | ArrayBuffer
+  | ArrayBufferView
+  | Map<Serializable, Serializable>
+  | Set<Serializable>;

package/src/utils.ts

@@ -0,0 +1,305 @@
+/**
+ * ComputeKit Utilities
+ * Helper functions for the WASM + Worker toolkit
+ */
+
+/**
+ * Generate a unique ID
+ */
+export function generateId(): string {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Check if running in a Web Worker context
+ */
+export function isWorkerContext(): boolean {
+  return (
+    typeof self !== 'undefined' &&
+    typeof Window === 'undefined' &&
+    typeof self.postMessage === 'function'
+  );
+}
+
+/**
+ * Check if running in a browser context
+ */
+export function isBrowserContext(): boolean {
+  return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+
+/**
+ * Check if SharedArrayBuffer is available
+ */
+export function isSharedArrayBufferAvailable(): boolean {
+  try {
+    return typeof SharedArrayBuffer !== 'undefined';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if WASM is supported
+ */
+export function isWasmSupported(): boolean {
+  try {
+    if (typeof WebAssembly === 'object') {
+      const module = new WebAssembly.Module(
+        Uint8Array.of(0x0, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00)
+      );
+      return module instanceof WebAssembly.Module;
+    }
+  } catch {
+    // WASM not supported
+  }
+  return false;
+}
+
+/**
+ * Get the number of logical processors
+ */
+export function getHardwareConcurrency(): number {
+  if (typeof navigator !== 'undefined' && navigator.hardwareConcurrency) {
+    return navigator.hardwareConcurrency;
+  }
+  return 4; // Reasonable default
+}
+
+/**
+ * Create a deferred promise
+ */
+export interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+}
+
+export function createDeferred<T>(): Deferred<T> {
+  let resolve!: (value: T | PromiseLike<T>) => void;
+  let reject!: (reason?: unknown) => void;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return { promise, resolve, reject };
+}
+
+/**
+ * Create a timeout promise
+ */
+export function createTimeout(ms: number, message?: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(message || `Operation timed out after ${ms}ms`));
+    }, ms);
+  });
+}
+
+/**
+ * Race a promise against a timeout
+ */
+export async function withTimeout<T>(
+  promise: Promise<T>,
+  ms: number,
+  message?: string
+): Promise<T> {
+  return Promise.race([promise, createTimeout(ms, message)]);
+}
+
+/**
+ * Detect transferable objects in data
+ */
+export function findTransferables(data: unknown): Transferable[] {
+  const transferables: Transferable[] = [];
+  const seen = new WeakSet();
+
+  function traverse(obj: unknown): void {
+    if (obj === null || typeof obj !== 'object') return;
+    if (seen.has(obj as object)) return;
+    seen.add(obj as object);
+
+    if (obj instanceof ArrayBuffer) {
+      transferables.push(obj);
+      return;
+    }
+
+    if (ArrayBuffer.isView(obj)) {
+      transferables.push(obj.buffer);
+      return;
+    }
+
+    if (obj instanceof MessagePort) {
+      transferables.push(obj);
+      return;
+    }
+
+    if (typeof ImageBitmap !== 'undefined' && obj instanceof ImageBitmap) {
+      transferables.push(obj);
+      return;
+    }
+
+    if (typeof OffscreenCanvas !== 'undefined' && obj instanceof OffscreenCanvas) {
+      transferables.push(obj);
+      return;
+    }
+
+    if (Array.isArray(obj)) {
+      obj.forEach(traverse);
+      return;
+    }
+
+    if (obj instanceof Map) {
+      obj.forEach((value, key) => {
+        traverse(key);
+        traverse(value);
+      });
+      return;
+    }
+
+    if (obj instanceof Set) {
+      obj.forEach(traverse);
+      return;
+    }
+
+    Object.values(obj).forEach(traverse);
+  }
+
+  traverse(data);
+  return transferables;
+}
+
+/**
+ * Clone data, detaching transferables
+ */
+export function cloneForTransfer<T>(data: T): { data: T; transfer: Transferable[] } {
+  const transfer = findTransferables(data);
+  return { data, transfer };
+}
+
+/**
+ * Create a typed event emitter
+ */
+export type EventHandler<T = unknown> = (data: T) => void;
+
+export class EventEmitter<TEvents extends Record<string, unknown>> {
+  private handlers = new Map<keyof TEvents, Set<EventHandler>>();
+
+  on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler as EventHandler);
+
+    // Return unsubscribe function
+    return () => this.off(event, handler);
+  }
+
+  off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void {
+    this.handlers.get(event)?.delete(handler as EventHandler);
+  }
+
+  emit<K extends keyof TEvents>(event: K, data: TEvents[K]): void {
+    this.handlers.get(event)?.forEach((handler) => {
+      try {
+        handler(data);
+      } catch (err) {
+        console.error(`Error in event handler for ${String(event)}:`, err);
+      }
+    });
+  }
+
+  removeAllListeners(event?: keyof TEvents): void {
+    if (event) {
+      this.handlers.delete(event);
+    } else {
+      this.handlers.clear();
+    }
+  }
+}
+
+/**
+ * Simple LRU cache
+ */
+export class LRUCache<K, V> {
+  private cache = new Map<K, V>();
+  private maxSize: number;
+
+  constructor(maxSize: number = 100) {
+    this.maxSize = maxSize;
+  }
+
+  get(key: K): V | undefined {
+    const value = this.cache.get(key);
+    if (value !== undefined) {
+      // Move to end (most recently used)
+      this.cache.delete(key);
+      this.cache.set(key, value);
+    }
+    return value;
+  }
+
+  set(key: K, value: V): void {
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    } else if (this.cache.size >= this.maxSize) {
+      // Delete oldest (first) entry
+      const firstKey = this.cache.keys().next().value;
+      if (firstKey !== undefined) {
+        this.cache.delete(firstKey);
+      }
+    }
+    this.cache.set(key, value);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+/**
+ * Serialize function to string for worker
+ */
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export function serializeFunction(fn: Function): string {
+  return fn.toString();
+}
+
+/**
+ * Logger utility
+ */
+export interface Logger {
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+
+export function createLogger(prefix: string, enabled: boolean = false): Logger {
+  const noop = () => {};
+  const log = (level: string) =>
+    enabled ? (...args: unknown[]) => console.log(`[${prefix}:${level}]`, ...args) : noop;
+
+  return {
+    debug: log('debug'),
+    info: log('info'),
+    warn: enabled
+      ? (...args: unknown[]) => console.warn(`[${prefix}:warn]`, ...args)
+      : noop,
+    error: (...args: unknown[]) => console.error(`[${prefix}:error]`, ...args),
+  };
+}