@shelchin/threadx 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# @shelchin/threadx
+
+Seamless Worker communication - call Workers like async functions.
+
+## Features
+
+- **Transparent RPC** - Call Worker methods like regular async functions
+- **Streaming Support** - Use generators for streaming results with `for await`
+- **Zero-Copy Transfer** - Transfer ArrayBuffers without copying
+- **Type Safe** - Full TypeScript support with automatic type inference
+- **Cancellation** - Break out of streams to cancel Worker operations
+- **Cross-Platform** - Works in Browser, Bun, and Deno
+
+## Installation
+
+```bash
+bun add @shelchin/threadx
+# or
+npm install @shelchin/threadx
+```
+
+## Quick Start
+
+### Worker Side
+
+```typescript
+// calc.worker.ts
+import { expose } from '@shelchin/threadx/worker'
+
+expose({
+  add(a: number, b: number) {
+    return a + b
+  },
+
+  async fetchData(url: string) {
+    const res = await fetch(url)
+    return res.json()
+  },
+
+  *progress(total: number) {
+    for (let i = 0; i <= total; i++) {
+      yield Math.round((i / total) * 100)
+    }
+  }
+})
+```
+
+### Main Thread
+
+```typescript
+// main.ts
+import { wrap, t, kill } from '@shelchin/threadx'
+import type * as CalcMethods from './calc.worker'
+
+const calc = wrap<typeof CalcMethods>(new Worker('./calc.worker.js'))
+
+// RPC call - just like a regular function
+const sum = await calc.add(1, 2)  // 3
+
+// Streaming with for-await
+for await (const percent of calc.progress(100)) {
+  console.log(`${percent}%`)
+}
+
+// Zero-copy transfer
+const buffer = new ArrayBuffer(1024 * 1024)
+await calc.processBuffer(t(buffer))
+// buffer.byteLength is now 0 (transferred)
+
+// Terminate worker
+kill(calc)
+```
+
+## API
+
+### Main Thread
+
+#### `wrap<T>(worker, options?)`
+
+Wrap a Worker for seamless RPC.
+
+```typescript
+const api = wrap<typeof WorkerMethods>(new Worker('./worker.js'), {
+  timeout: 30000,  // Default timeout in ms
+  name: 'calc'     // Debug name
+})
+```
+
+#### `t(value, transferables?)`
+
+Mark value for zero-copy transfer.
+
+```typescript
+// Single transferable
+await api.process(t(buffer))
+
+// Object with specified transferables
+await api.process(t({ image: buffer, meta: info }, [buffer]))
+```
+
+#### `kill(proxy)`
+
+Terminate the Worker.
+
+```typescript
+kill(api)
+```
+
+#### State Hooks
+
+```typescript
+api.$state    // 'init' | 'ready' | 'dead'
+api.$pending  // Number of pending calls
+api.$worker   // Original Worker instance
+```
+
+### Worker Side
+
+#### `expose(methods)`
+
+Expose methods to main thread.
+
+```typescript
+import { expose } from '@shelchin/threadx/worker'
+
+expose({
+  // Sync function → Promise
+  add: (a, b) => a + b,
+
+  // Async function → Promise
+  async fetch(url) {
+    return await fetch(url).then(r => r.json())
+  },
+
+  // Generator → AsyncIterable
+  *range(start, end) {
+    for (let i = start; i <= end; i++) yield i
+  },
+
+  // Async Generator → AsyncIterable
+  async *stream(urls) {
+    for (const url of urls) {
+      yield await fetch(url).then(r => r.json())
+    }
+  }
+})
+```
+
+### Error Types
+
+```typescript
+import { WorkerError, TimeoutError, InitError } from '@shelchin/threadx'
+
+try {
+  await api.riskyMethod()
+} catch (e) {
+  if (e instanceof WorkerError) {
+    console.log(e.message)      // Error message
+    console.log(e.workerStack)  // Stack from Worker
+  }
+  if (e instanceof TimeoutError) {
+    console.log('Call timed out')
+  }
+  if (e instanceof InitError) {
+    console.log('Worker failed to initialize')
+  }
+}
+```
+
+## Streaming & Cancellation
+
+Generators automatically stream values. Use `break` to cancel:
+
+```typescript
+for await (const chunk of api.longProcess()) {
+  console.log(chunk)
+  if (shouldStop) break  // Sends CANCEL to Worker
+}
+```
+
+## Type Safety
+
+Full type inference from Worker methods:
+
+```typescript
+// worker.ts
+export function add(a: number, b: number): number { ... }
+export function* count(n: number): Generator<number> { ... }
+
+// main.ts
+import type * as Methods from './worker'
+
+const api = wrap<typeof Methods>(worker)
+
+await api.add(1, 2)     // Promise<number>
+api.count(10)           // AsyncIterable<number>
+```
+
+## Platform Support
+
+| Platform | Support |
+|----------|---------|
+| Browser | Native Worker |
+| Bun | Native Worker |
+| Deno | Native Worker |
+| Node.js | Not supported |
+| Cloudflare Workers | Not supported |
+
+## License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import type { SerializedError } from './protocol.js';
+/**
+ * Error thrown when Worker execution fails
+ */
+export declare class WorkerError extends Error {
+    /** Stack trace from the Worker side */
+    workerStack?: string;
+    constructor(serialized: SerializedError, callSite?: Error);
+}
+/**
+ * Error thrown when a call times out
+ */
+export declare class TimeoutError extends Error {
+    constructor(method: string, timeout: number);
+}
+/**
+ * Error thrown when Worker initialization fails
+ */
+export declare class InitError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown on unsupported runtime
+ */
+export declare class UnsupportedRuntimeError extends Error {
+    constructor(runtime: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD;;GAEG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,uCAAuC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;gBAET,UAAU,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,KAAK;CAY1D;AAED;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5C;AAED;;GAEG;AACH,qBAAa,SAAU,SAAQ,KAAK;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,EAAE,MAAM;CAI5B"}

package/dist/errors.js

@@ -0,0 +1,45 @@
+// src/errors.ts
+class WorkerError extends Error {
+  workerStack;
+  constructor(serialized, callSite) {
+    super(serialized.message);
+    this.name = serialized.name || "WorkerError";
+    this.workerStack = serialized.stack;
+    if (callSite?.stack) {
+      this.stack = `${this.name}: ${this.message}
+` + `    at Worker
+` + callSite.stack.split(`
+`).slice(1).join(`
+`);
+    }
+  }
+}
+
+class TimeoutError extends Error {
+  constructor(method, timeout) {
+    super(`Call to '${method}' timed out after ${timeout}ms`);
+    this.name = "TimeoutError";
+  }
+}
+
+class InitError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InitError";
+  }
+}
+
+class UnsupportedRuntimeError extends Error {
+  constructor(runtime) {
+    super(`ThreadX is not supported on ${runtime}. Supported runtimes: Browser, Bun, Deno`);
+    this.name = "UnsupportedRuntimeError";
+  }
+}
+export {
+  WorkerError,
+  UnsupportedRuntimeError,
+  TimeoutError,
+  InitError
+};
+
+//# debugId=254D6696BA51CA2D64756E2164756E21

package/dist/errors.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/errors.ts"],
+  "sourcesContent": [
+    "import type { SerializedError } from './protocol.js';\n\n/**\n * Error thrown when Worker execution fails\n */\nexport class WorkerError extends Error {\n  /** Stack trace from the Worker side */\n  workerStack?: string;\n\n  constructor(serialized: SerializedError, callSite?: Error) {\n    super(serialized.message);\n    this.name = serialized.name || 'WorkerError';\n    this.workerStack = serialized.stack;\n\n    // Combine stacks: Worker error + call site\n    if (callSite?.stack) {\n      this.stack = `${this.name}: ${this.message}\\n` +\n        `    at Worker\\n` +\n        callSite.stack.split('\\n').slice(1).join('\\n');\n    }\n  }\n}\n\n/**\n * Error thrown when a call times out\n */\nexport class TimeoutError extends Error {\n  constructor(method: string, timeout: number) {\n    super(`Call to '${method}' timed out after ${timeout}ms`);\n    this.name = 'TimeoutError';\n  }\n}\n\n/**\n * Error thrown when Worker initialization fails\n */\nexport class InitError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'InitError';\n  }\n}\n\n/**\n * Error thrown on unsupported runtime\n */\nexport class UnsupportedRuntimeError extends Error {\n  constructor(runtime: string) {\n    super(`ThreadX is not supported on ${runtime}. Supported runtimes: Browser, Bun, Deno`);\n    this.name = 'UnsupportedRuntimeError';\n  }\n}\n"
+  ],
+  "mappings": ";AAKO,MAAM,oBAAoB,MAAM;AAAA,EAErC;AAAA,EAEA,WAAW,CAAC,YAA6B,UAAkB;AAAA,IACzD,MAAM,WAAW,OAAO;AAAA,IACxB,KAAK,OAAO,WAAW,QAAQ;AAAA,IAC/B,KAAK,cAAc,WAAW;AAAA,IAG9B,IAAI,UAAU,OAAO;AAAA,MACnB,KAAK,QAAQ,GAAG,KAAK,SAAS,KAAK;AAAA,IACjC;AAAA,IACA,SAAS,MAAM,MAAM;AAAA,CAAI,EAAE,MAAM,CAAC,EAAE,KAAK;AAAA,CAAI;AAAA,IACjD;AAAA;AAEJ;AAAA;AAKO,MAAM,qBAAqB,MAAM;AAAA,EACtC,WAAW,CAAC,QAAgB,SAAiB;AAAA,IAC3C,MAAM,YAAY,2BAA2B,WAAW;AAAA,IACxD,KAAK,OAAO;AAAA;AAEhB;AAAA;AAKO,MAAM,kBAAkB,MAAM;AAAA,EACnC,WAAW,CAAC,SAAiB;AAAA,IAC3B,MAAM,OAAO;AAAA,IACb,KAAK,OAAO;AAAA;AAEhB;AAAA;AAKO,MAAM,gCAAgC,MAAM;AAAA,EACjD,WAAW,CAAC,SAAiB;AAAA,IAC3B,MAAM,+BAA+B,iDAAiD;AAAA,IACtF,KAAK,OAAO;AAAA;AAEhB;",
+  "debugId": "254D6696BA51CA2D64756E2164756E21",
+  "names": []
+}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ThreadX - Seamless Worker Communication
+ *
+ * @example
+ * // Main thread
+ * import { wrap, t, kill } from '@shelchin/threadx'
+ * import type * as CalcMethods from './calc.worker'
+ *
+ * const calc = wrap<typeof CalcMethods>(new Worker('./calc.worker.js'))
+ *
+ * // RPC call
+ * const sum = await calc.add(1, 2)
+ *
+ * // Streaming call
+ * for await (const progress of calc.process(data)) {
+ *   console.log(progress)
+ * }
+ *
+ * // Zero-copy transfer
+ * await calc.processBuffer(t(arrayBuffer))
+ *
+ * // Terminate
+ * kill(calc)
+ *
+ * @example
+ * // Worker side (calc.worker.ts)
+ * import { expose } from '@shelchin/threadx/worker'
+ *
+ * expose({
+ *   add: (a, b) => a + b,
+ *   *process(data) {
+ *     for (let i = 0; i <= 100; i++) {
+ *       yield i
+ *     }
+ *   }
+ * })
+ */
+export { wrap, kill } from './wrap.js';
+export { t } from './transfer.js';
+export { WorkerError, TimeoutError, InitError, UnsupportedRuntimeError } from './errors.js';
+export type { WrapOptions, WrappedWorker, WorkerState } from './types.js';
+export type { TransferDescriptor } from './transfer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAGlC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAG5F,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC"}