@xylabs/threads 4.8.0-rc.2 → 4.8.0

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@xylabs/threads",
-  "version": "4.8.0-rc.2",
-  "stableVersion": "4.7.1",
+  "version": "4.8.0",
   "description": "Web workers & worker threads as simple as a function call",
   "keywords": [
     "thread",
@@ -24,17 +23,18 @@
   "funding": "https://github.com/andywer/threads.js?sponsor=1",
   "license": "MIT",
   "author": "Andy Wermke (https://github.com/andywer)",
-  "sideEffects": [
-    "./dist*/master/register.js",
-    "./dist*/worker/index.js",
-    "./register.*js",
-    "./worker.*js"
-  ],
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/types/index.d.ts",
-      "import": "./dist/neutral/index.mjs"
+      "browser": {
+        "types": "./dist/types/index-browser.d.ts",
+        "import": "./dist/browser/index-browser.mjs"
+      },
+      "node": {
+        "types": "./dist/types/index-node.d.ts",
+        "import": "./dist/node/index-node.mjs"
+      }
     },
     "./implementation": {
       "browser": {
@@ -44,13 +44,17 @@
       "node": {
         "types": "./dist/types/master/implementation.node.d.ts",
         "import": "./dist/node/master/implementation.node.mjs"
-      },
-      "types": "./dist/types/master/implementation.d.ts",
-      "import": "./dist/neutral/master/implementation.mjs"
+      }
     },
     "./master": {
-      "types": "./dist/types/master/index.d.ts",
-      "import": "./dist/neutral/master/index.mjs"
+      "browser": {
+        "types": "./dist/types/master/index-browser.d.ts",
+        "import": "./dist/browser/master/index-browser.mjs"
+      },
+      "node": {
+        "types": "./dist/types/master/index-node.d.ts",
+        "import": "./dist/node/master/index-node.mjs"
+      }
     },
     "./spawn": {
       "types": "./dist/types/master/spawn.d.ts",
@@ -68,8 +72,14 @@
       "import": "./dist/neutral/observable.mjs"
     },
     "./pool": {
-      "types": "./dist/types/master/pool.d.ts",
-      "import": "./dist/neutral/master/pool.mjs"
+      "browser": {
+        "types": "./dist/types/master/pool-browser.d.ts",
+        "import": "./dist/browser/master/pool-browser.mjs"
+      },
+      "node": {
+        "types": "./dist/types/master/pool-node.d.ts",
+        "import": "./dist/node/master/pool-node.mjs"
+      }
     },
     "./observable-promise": {
       "types": "./dist/types/observable-promise.d.ts",
@@ -90,10 +100,13 @@
       }
     }
   },
-  "module": "dist/neutral/index.mjs",
-  "types": "dist/types/index.d.ts",
+  "module": "dist/browser/index-browser.mjs",
+  "types": "dist/types/index-browser.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
   ],
   "dependencies": {
     "debug": "^4.4.0",
@@ -102,13 +115,10 @@
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",
-    "@types/node": "^22.13.10",
-    "@xylabs/eslint-config-flat": "^6.1.3",
-    "@xylabs/ts-scripts-yarn3": "^6.1.3",
-    "typescript": "^5.8.2"
-  },
-  "optionalDependencies": {
-    "tiny-worker": "^2.3.0"
+    "@types/node": "^22.14.0",
+    "@xylabs/eslint-config-flat": "^6.2.1",
+    "@xylabs/ts-scripts-yarn3": "^6.2.1",
+    "typescript": "^5.8.3"
   },
   "publishConfig": {
     "access": "public"

package/src/common.ts

@@ -0,0 +1,23 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type {
+  JsonSerializable, Serializer, SerializerImplementation,
+} from './serializers.ts'
+import { DefaultSerializer, extendSerializer } from './serializers.ts'
+
+declare global {
+  var registeredSerializer: Serializer<JsonSerializable>
+}
+
+globalThis.registeredSerializer = globalThis.registeredSerializer ?? DefaultSerializer
+
+export function registerSerializer(serializer: SerializerImplementation<JsonSerializable>) {
+  globalThis.registeredSerializer = extendSerializer(globalThis.registeredSerializer, serializer)
+}
+
+export function deserialize(message: JsonSerializable): any {
+  return globalThis.registeredSerializer.deserialize(message)
+}
+
+export function serialize(input: any): JsonSerializable {
+  return globalThis.registeredSerializer.serialize(input)
+}

package/src/index-browser.ts

@@ -0,0 +1,11 @@
+/* eslint-disable import-x/no-internal-modules */
+export { registerSerializer } from './common.ts'
+export * from './master/index-browser.ts'
+export type { QueuedTask } from './master/pool-node.ts'
+export type { ExposedToThreadType as ExposedAs } from './master/spawn.ts'
+export type {
+  JsonSerializable, Serializer, SerializerImplementation,
+} from './serializers.ts'
+export { DefaultSerializer } from './serializers.ts'
+export type { TransferDescriptor } from './transferable.ts'
+export { Transfer } from './transferable.ts'

package/src/index-node.ts

@@ -0,0 +1,11 @@
+/* eslint-disable import-x/no-internal-modules */
+export { registerSerializer } from './common.ts'
+export * from './master/index-node.ts'
+export type { QueuedTask } from './master/pool-node.ts'
+export type { ExposedToThreadType as ExposedAs } from './master/spawn.ts'
+export type {
+  JsonSerializable, Serializer, SerializerImplementation,
+} from './serializers.ts'
+export { DefaultSerializer } from './serializers.ts'
+export type { TransferDescriptor } from './transferable.ts'
+export { Transfer } from './transferable.ts'

package/src/master/get-bundle-url.browser.ts

@@ -0,0 +1,32 @@
+// Source: <https://github.com/parcel-bundler/parcel/blob/master/packages/core/parcel-bundler/src/builtins/bundle-url.js>
+
+let bundleURL: string | undefined
+
+function getBundleURLCached(): string {
+  if (!bundleURL) {
+    bundleURL = getBundleURL()
+  }
+
+  return bundleURL
+}
+
+function getBundleURL(): string {
+  // Attempt to find the URL of the current script and use that as the base URL
+  try {
+    throw new Error('getBundleURL failed')
+  } catch (ex) {
+    const err = ex as Error
+    const matches = ('' + err.stack).match(/(https?|file|ftp|chrome-extension|moz-extension):\/\/[^\n)]+/g)
+    if (matches) {
+      return getBaseURL(matches[0])
+    }
+  }
+
+  return '/'
+}
+
+function getBaseURL(url: string): string {
+  return ('' + url).replace(/^((?:https?|file|ftp|chrome-extension|moz-extension):\/\/.+)?\/[^/]+(?:\?.*)?$/, '$1') + '/'
+}
+
+export { getBundleURLCached as getBundleURL }

package/src/master/implementation.browser.ts

@@ -0,0 +1,82 @@
+/* eslint-disable @stylistic/max-len */
+/* eslint-disable import-x/no-internal-modules */
+// tslint:disable max-classes-per-file
+
+import type { ImplementationExport, ThreadsWorkerOptions } from '../types/master.ts'
+import { getBundleURL } from './get-bundle-url.browser.ts'
+
+export const defaultPoolSize = typeof navigator !== 'undefined' && navigator.hardwareConcurrency ? navigator.hardwareConcurrency : 4
+
+const isAbsoluteURL = (value: string) => /^[A-Za-z][\d+.A-Za-z\-]*:/.test(value)
+
+function createSourceBlobURL(code: string): string {
+  const blob = new Blob([code], { type: 'application/javascript' })
+  return URL.createObjectURL(blob)
+}
+
+function selectWorkerImplementation(): ImplementationExport {
+  if (typeof Worker === 'undefined') {
+    // Might happen on Safari, for instance
+    // The idea is to only fail if the constructor is actually used
+    return class NoWebWorker {
+      constructor() {
+        throw new Error(
+          "No web worker implementation available. You might have tried to spawn a worker within a worker in a browser that doesn't support workers in workers.",
+        )
+      }
+    } as unknown as ImplementationExport
+  }
+
+  class WebWorker extends Worker {
+    constructor(url: string | URL, options?: ThreadsWorkerOptions) {
+      if (typeof url === 'string' && options && options._baseURL) {
+        url = new URL(url, options._baseURL)
+      } else if (typeof url === 'string' && !isAbsoluteURL(url) && /^file:\/\//i.test(getBundleURL())) {
+        url = new URL(url, getBundleURL().replace(/\/[^/]+$/, '/'))
+        if (options?.CORSWorkaround ?? true) {
+          url = createSourceBlobURL(`importScripts(${JSON.stringify(url)});`)
+        }
+      }
+      if (
+        typeof url === 'string'
+        && isAbsoluteURL(url) // Create source code blob loading JS file via `importScripts()`
+        // to circumvent worker CORS restrictions
+        && (options?.CORSWorkaround ?? true)
+      ) {
+        url = createSourceBlobURL(`importScripts(${JSON.stringify(url)});`)
+      }
+      super(url, options)
+    }
+  }
+
+  class BlobWorker extends WebWorker {
+    constructor(blob: Blob, options?: ThreadsWorkerOptions) {
+      const url = globalThis.URL.createObjectURL(blob)
+      super(url, options)
+    }
+
+    static fromText(source: string, options?: ThreadsWorkerOptions): WebWorker {
+      const blob = new globalThis.Blob([source], { type: 'text/javascript' })
+      return new BlobWorker(blob, options)
+    }
+  }
+
+  return {
+    blob: BlobWorker,
+    default: WebWorker,
+  }
+}
+
+let implementation: ImplementationExport
+
+export function getWorkerImplementation(): ImplementationExport {
+  if (!implementation) {
+    implementation = selectWorkerImplementation()
+  }
+  return implementation
+}
+
+export function isWorkerRuntime() {
+  const isWindowContext = typeof globalThis !== 'undefined' && typeof Window !== 'undefined' && globalThis instanceof Window
+  return typeof globalThis !== 'undefined' && self['postMessage'] && !isWindowContext ? true : false
+}

package/src/master/implementation.node.ts

@@ -0,0 +1,208 @@
+/* eslint-disable @typescript-eslint/no-require-imports */
+
+/* eslint-disable unicorn/prefer-add-event-listener */
+/* eslint-disable unicorn/prefer-event-target */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable unicorn/text-encoding-identifier-case */
+
+import { EventEmitter } from 'node:events'
+import { cpus } from 'node:os'
+import path from 'node:path'
+import { cwd } from 'node:process'
+import { Worker as NativeWorker } from 'node:worker_threads'
+
+import type {
+  ImplementationExport, ThreadsWorkerOptions, WorkerImplementation,
+// eslint-disable-next-line import-x/no-internal-modules
+} from '../types/master.ts'
+
+declare const __non_webpack_require__: typeof require
+
+type WorkerEventName = 'error' | 'message'
+
+export const defaultPoolSize = cpus().length
+
+function resolveScriptPath(scriptPath: string, baseURL?: string | undefined) {
+  const makeAbsolute = (filePath: string) => {
+    return path.isAbsolute(filePath) ? filePath : path.join(baseURL ?? cwd(), filePath)
+  }
+
+  const absolutePath = makeAbsolute(scriptPath)
+  return absolutePath
+}
+
+function initWorkerThreadsWorker(): ImplementationExport {
+  let allWorkers: Array<NativeWorker> = []
+
+  class Worker extends NativeWorker {
+    private mappedEventListeners: WeakMap<EventListener, EventListener>
+
+    constructor(scriptPath: string, options?: ThreadsWorkerOptions & { fromSource: boolean }) {
+      const resolvedScriptPath = options && options.fromSource ? null : resolveScriptPath(scriptPath, (options ?? {})._baseURL)
+      if (resolvedScriptPath) {
+        super(resolvedScriptPath, options)
+      } else {
+        // `options.fromSource` is true
+        const sourceCode = scriptPath
+        super(sourceCode, { ...options, eval: true })
+      }
+
+      this.mappedEventListeners = new WeakMap()
+      allWorkers.push(this)
+    }
+
+    addEventListener(eventName: string, rawListener: EventListener) {
+      const listener = (message: any) => {
+        rawListener({ data: message } as any)
+      }
+      this.mappedEventListeners.set(rawListener, listener)
+      this.on(eventName, listener)
+    }
+
+    removeEventListener(eventName: string, rawListener: EventListener) {
+      const listener = this.mappedEventListeners.get(rawListener) || rawListener
+      this.off(eventName, listener)
+    }
+  }
+
+  const terminateWorkersAndMaster = () => {
+    // we should terminate all workers and then gracefully shutdown self process
+    Promise.all(allWorkers.map(worker => worker.terminate())).then(
+      () => process.exit(0),
+      () => process.exit(1),
+    )
+    allWorkers = []
+  }
+
+  // Take care to not leave orphaned processes behind. See #147.
+  process.on('SIGINT', () => terminateWorkersAndMaster())
+  process.on('SIGTERM', () => terminateWorkersAndMaster())
+
+  class BlobWorker extends Worker {
+    constructor(blob: Uint8Array, options?: ThreadsWorkerOptions) {
+      super(Buffer.from(blob).toString('utf-8'), { ...options, fromSource: true })
+    }
+
+    static fromText(source: string, options?: ThreadsWorkerOptions): WorkerImplementation {
+      return new Worker(source, { ...options, fromSource: true }) as any
+    }
+  }
+
+  return {
+    blob: BlobWorker as any,
+    default: Worker as any,
+  }
+}
+
+function initTinyWorker(): ImplementationExport {
+  const TinyWorker = require('tiny-worker')
+
+  let allWorkers: Array<typeof TinyWorker> = []
+
+  class Worker extends TinyWorker {
+    private emitter: EventEmitter
+
+    constructor(scriptPath: string, options?: ThreadsWorkerOptions & { fromSource?: boolean }) {
+      // Need to apply a work-around for Windows or it will choke upon the absolute path
+      // (`Error [ERR_INVALID_PROTOCOL]: Protocol 'c:' not supported`)
+      const resolvedScriptPath
+        = options && options.fromSource
+          ? null
+          : process.platform === 'win32'
+            ? `file:///${resolveScriptPath(scriptPath).replaceAll('\\', '/')}`
+            : resolveScriptPath(scriptPath)
+
+      if (resolvedScriptPath) {
+        super(resolvedScriptPath, [], { esm: true })
+      } else {
+        // `options.fromSource` is true
+        const sourceCode = scriptPath
+        super(new Function(sourceCode), [], { esm: true })
+      }
+
+      allWorkers.push(this)
+
+      this.emitter = new EventEmitter()
+      this.onerror = (error: Error) => this.emitter.emit('error', error)
+      this.onmessage = (message: MessageEvent) => this.emitter.emit('message', message)
+    }
+
+    addEventListener(eventName: WorkerEventName, listener: EventListener) {
+      this.emitter.addListener(eventName, listener)
+    }
+
+    removeEventListener(eventName: WorkerEventName, listener: EventListener) {
+      this.emitter.removeListener(eventName, listener)
+    }
+
+    terminate() {
+      allWorkers = allWorkers.filter(worker => worker !== this)
+      return super.terminate()
+    }
+  }
+
+  const terminateWorkersAndMaster = () => {
+    // we should terminate all workers and then gracefully shutdown self process
+    Promise.all(allWorkers.map(worker => worker.terminate())).then(
+      () => process.exit(0),
+      () => process.exit(1),
+    )
+    allWorkers = []
+  }
+
+  // Take care to not leave orphaned processes behind
+  // See <https://github.com/avoidwork/tiny-worker#faq>
+  process.on('SIGINT', () => terminateWorkersAndMaster())
+  process.on('SIGTERM', () => terminateWorkersAndMaster())
+
+  class BlobWorker extends Worker {
+    constructor(blob: Uint8Array, options?: ThreadsWorkerOptions) {
+      super(Buffer.from(blob).toString('utf-8'), { ...options, fromSource: true })
+    }
+
+    static fromText(source: string, options?: ThreadsWorkerOptions): WorkerImplementation {
+      return new Worker(source, { ...options, fromSource: true }) as any
+    }
+  }
+
+  return {
+    blob: BlobWorker as any,
+    default: Worker as any,
+  }
+}
+
+let implementation: ImplementationExport
+let isTinyWorker: boolean
+
+function selectWorkerImplementation(): ImplementationExport {
+  try {
+    isTinyWorker = false
+    return initWorkerThreadsWorker()
+  } catch (ex) {
+    console.error(ex)
+    // tslint:disable-next-line no-console
+    console.debug('Node worker_threads not available. Trying to fall back to tiny-worker polyfill...')
+    isTinyWorker = true
+    return initTinyWorker()
+  }
+}
+
+export function getWorkerImplementation(): ImplementationExport {
+  if (!implementation) {
+    implementation = selectWorkerImplementation()
+  }
+  return implementation
+}
+
+export function isWorkerRuntime() {
+  if (isTinyWorker) {
+    return globalThis !== undefined && self['postMessage'] ? true : false
+  } else {
+    // Webpack hack
+    const isMainThread
+      = typeof __non_webpack_require__ === 'function'
+        ? __non_webpack_require__('worker_threads').isMainThread
+        : eval('require')('worker_threads').isMainThread
+    return !isMainThread
+  }
+}

package/src/master/index-browser.ts

@@ -0,0 +1,19 @@
+/* eslint-disable import-x/no-internal-modules */
+import type { BlobWorker as BlobWorkerClass, Worker as WorkerType } from '../types/master.ts'
+import * as BrowserImplementation from './implementation.browser.ts'
+
+export type { FunctionThread, ModuleThread } from '../types/master.ts'
+export { Pool } from './pool-browser.ts'
+export { spawn } from './spawn.ts'
+export { Thread } from './thread.ts'
+
+export type BlobWorker = typeof BlobWorkerClass
+export type Worker = WorkerType
+
+/** Separate class to spawn workers from source code blobs or strings. */
+export const BlobWorker = BrowserImplementation.getWorkerImplementation().blob
+
+/** Worker implementation. Either web worker or a node.js Worker class. */
+export const Worker = BrowserImplementation.getWorkerImplementation().default
+
+export { isWorkerRuntime } from './implementation.browser.ts'

package/src/master/index-node.ts

@@ -0,0 +1,19 @@
+/* eslint-disable import-x/no-internal-modules */
+import type { BlobWorker as BlobWorkerClass, Worker as WorkerType } from '../types/master.ts'
+import * as NodeImplementation from './implementation.node.ts'
+
+export type { FunctionThread, ModuleThread } from '../types/master.ts'
+export { Pool } from './pool-browser.ts'
+export { spawn } from './spawn.ts'
+export { Thread } from './thread.ts'
+
+export type BlobWorker = typeof BlobWorkerClass
+export type Worker = WorkerType
+
+/** Separate class to spawn workers from source code blobs or strings. */
+export const BlobWorker = NodeImplementation.getWorkerImplementation().blob
+
+/** Worker implementation. Either web worker or a node.js Worker class. */
+export const Worker = NodeImplementation.getWorkerImplementation().default
+
+export { isWorkerRuntime } from './implementation.node.ts'

package/src/master/invocation-proxy.ts

@@ -0,0 +1,151 @@
+/* eslint-disable import-x/no-internal-modules */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/*
+ * This source file contains the code for proxying calls in the master thread to calls in the workers
+ * by `.postMessage()`-ing.
+ *
+ * Keep in mind that this code can make or break the program's performance! Need to optimize more…
+ */
+
+import DebugLogger from 'debug'
+import { multicast, Observable } from 'observable-fns'
+
+import { deserialize, serialize } from '../common.ts'
+import { ObservablePromise } from '../observable-promise.ts'
+import { isTransferDescriptor } from '../transferable.ts'
+import type {
+  ModuleMethods, ModuleProxy, ProxyableFunction, Worker as WorkerType,
+} from '../types/master.ts'
+import type {
+  MasterJobCancelMessage,
+  MasterJobRunMessage,
+  WorkerJobErrorMessage,
+  WorkerJobResultMessage,
+  WorkerJobStartMessage,
+} from '../types/messages.ts'
+import {
+  MasterMessageType,
+  WorkerMessageType,
+} from '../types/messages.ts'
+
+const debugMessages = DebugLogger('threads:master:messages')
+
+let nextJobUID = 1
+
+const dedupe = <T>(array: T[]): T[] => [...new Set(array)]
+
+const isJobErrorMessage = (data: any): data is WorkerJobErrorMessage => data && data.type === WorkerMessageType.error
+const isJobResultMessage = (data: any): data is WorkerJobResultMessage => data && data.type === WorkerMessageType.result
+const isJobStartMessage = (data: any): data is WorkerJobStartMessage => data && data.type === WorkerMessageType.running
+
+function createObservableForJob<ResultType>(worker: WorkerType, jobUID: number): Observable<ResultType> {
+  return new Observable((observer) => {
+    let asyncType: 'observable' | 'promise' | undefined
+
+    const messageHandler = ((event: MessageEvent) => {
+      debugMessages('Message from worker:', event.data)
+      if (!event.data || event.data.uid !== jobUID) return
+
+      if (isJobStartMessage(event.data)) {
+        asyncType = event.data.resultType
+      } else if (isJobResultMessage(event.data)) {
+        if (asyncType === 'promise') {
+          if (event.data.payload !== undefined) {
+            observer.next(deserialize(event.data.payload))
+          }
+          observer.complete()
+          worker.removeEventListener('message', messageHandler)
+        } else {
+          if (event.data.payload) {
+            observer.next(deserialize(event.data.payload))
+          }
+          if (event.data.complete) {
+            observer.complete()
+            worker.removeEventListener('message', messageHandler)
+          }
+        }
+      } else if (isJobErrorMessage(event.data)) {
+        const error = deserialize(event.data.error as any)
+        if (asyncType === 'promise' || !asyncType) {
+          observer.error(error)
+        } else {
+          observer.error(error)
+        }
+        worker.removeEventListener('message', messageHandler)
+      }
+    }) as EventListener
+
+    worker.addEventListener('message', messageHandler)
+
+    return () => {
+      if (asyncType === 'observable' || !asyncType) {
+        const cancelMessage: MasterJobCancelMessage = {
+          type: MasterMessageType.cancel,
+          uid: jobUID,
+        }
+        worker.postMessage(cancelMessage)
+      }
+      worker.removeEventListener('message', messageHandler)
+    }
+  })
+}
+
+function prepareArguments(rawArgs: any[]): { args: any[]; transferables: Transferable[] } {
+  if (rawArgs.length === 0) {
+    // Exit early if possible
+    return {
+      args: [],
+      transferables: [],
+    }
+  }
+
+  const args: any[] = []
+  const transferables: Transferable[] = []
+
+  for (const arg of rawArgs) {
+    if (isTransferDescriptor(arg)) {
+      args.push(serialize(arg.send))
+      transferables.push(...arg.transferables)
+    } else {
+      args.push(serialize(arg))
+    }
+  }
+
+  return {
+    args,
+    transferables: transferables.length === 0 ? transferables : dedupe(transferables),
+  }
+}
+
+export function createProxyFunction<Args extends any[], ReturnType>(worker: WorkerType, method?: string) {
+  return ((...rawArgs: Args) => {
+    const uid = nextJobUID++
+    const { args, transferables } = prepareArguments(rawArgs)
+    const runMessage: MasterJobRunMessage = {
+      args,
+      method,
+      type: MasterMessageType.run,
+      uid,
+    }
+
+    debugMessages('Sending command to run function to worker:', runMessage)
+
+    try {
+      worker.postMessage(runMessage, transferables)
+    } catch (error) {
+      return ObservablePromise.from(Promise.reject(error))
+    }
+
+    return ObservablePromise.from(multicast(createObservableForJob<ReturnType>(worker, uid)))
+  }) as any as ProxyableFunction<Args, ReturnType>
+}
+
+export function createProxyModule<Methods extends ModuleMethods>(worker: WorkerType, methodNames: string[]): ModuleProxy<Methods> {
+  const proxy: any = {}
+
+  for (const methodName of methodNames) {
+    proxy[methodName] = createProxyFunction(worker, methodName)
+  }
+
+  return proxy
+}