@xylabs/threads 4.7.0-rc.1 → 4.7.0

package/eslint.config.mjs

@@ -0,0 +1,35 @@
+import {
+  typescriptConfig,
+  unicornConfig,
+  workspacesConfig,
+  rulesConfig,
+  importConfig,
+} from '@xylabs/eslint-config-flat'
+
+export default [
+  { ignores: ['.yarn', 'dist', '**/dist/**',
+    'build', '**/build/**', 'node_modules/**', 'public', 'storybook-static', 'eslint.config.mjs',
+    'rollup.config.js', 'test-tooling', 'test', 'types', 'worker.*', '*.mjs', '*.d.ts', '*.js'] },
+  unicornConfig,
+  workspacesConfig,
+  rulesConfig,
+  typescriptConfig,
+  importConfig,
+  {
+    rules: {
+      'no-restricted-syntax': ['off'],
+      'no-restricted-imports': [
+        'warn',
+        {
+          paths: [
+            ...rulesConfig.rules['no-restricted-imports'][1].paths,
+            '@xyo-network/*',
+            'lodash',
+            'lodash-es',
+            '@xylabs/lodash',
+          ],
+        },
+      ],
+    },
+  },
+]

package/index.mjs

@@ -0,0 +1,10 @@
+import * as Threads from './dist/index.js'
+
+export const registerSerializer = Threads.registerSerializer
+export const spawn = Threads.spawn
+export const BlobWorker = Threads.BlobWorker
+export const DefaultSerializer = Threads.DefaultSerializer
+export const Pool = Threads.Pool
+export const Thread = Threads.Thread
+export const Transfer = Threads.Transfer
+export const Worker = Threads.Worker

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/threads",
-  "version": "4.7.0-rc.1",
+  "version": "4.7.0",
   "description": "Web workers & worker threads as simple as a function call",
   "keywords": [
     "thread",
@@ -33,67 +33,97 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/neutral/index.mjs"
+      "import": "./dist/neutral/index.mjs",
+      "default": "./dist/neutral/index.mjs"
     },
     "./implementation": {
       "browser": {
         "types": "./dist/types/master/implementation.browser.d.ts",
-        "import": "./dist/browser/master/implementation.browser.mjs"
+        "import": "./dist/browser/master/implementation.browser.mjs",
+        "default": "./dist/browser/master/implementation.browser.mjs"
       },
       "node": {
         "types": "./dist/types/master/implementation.node.d.ts",
-        "import": "./dist/node/master/implementation.node.mjs"
+        "import": "./dist/node/master/implementation.node.mjs",
+        "default": "./dist/node/master/implementation.node.mjs"
       },
       "types": "./dist/types/master/implementation.d.ts",
-      "import": "./dist/neutral/master/implementation.mjs"
+      "import": "./dist/neutral/master/implementation.mjs",
+      "default": "./dist/neutral/master/implementation.mjs"
     },
     "./master": {
       "types": "./dist/types/master/index.d.ts",
-      "import": "./dist/neutral/master/index.mjs"
+      "import": "./dist/neutral/master/index.mjs",
+      "default": "./dist/neutral/master/index.mjs"
     },
     "./spawn": {
       "types": "./dist/types/master/spawn.d.ts",
-      "import": "./dist/neutral/master/spawn.mjs"
+      "import": "./dist/neutral/master/spawn.mjs",
+      "default": "./dist/neutral/master/spawn.mjs"
     },
     "./thread": {
       "types": "./dist/types/master/thread.d.ts",
-      "import": "./dist/neutral/master/thread.mjs"
+      "import": "./dist/neutral/master/thread.mjs",
+      "default": "./dist/neutral/master/thread.mjs"
     },
     "./messenger": {
       "types": "./dist/types/types/messages.d.ts"
     },
     "./observable": {
       "types": "./dist/types/observable.d.ts",
-      "import": "./dist/neutral/observable.mjs"
+      "import": "./dist/neutral/observable.mjs",
+      "default": "./dist/neutral/observable.mjs"
     },
     "./pool": {
       "types": "./dist/types/master/pool.d.ts",
-      "import": "./dist/neutral/master/pool.mjs"
+      "import": "./dist/neutral/master/pool.mjs",
+      "default": "./dist/neutral/master/pool.mjs"
     },
     "./observable-promise": {
       "types": "./dist/types/observable-promise.d.ts",
-      "import": "./dist/neutral/observable-promise.mjs"
+      "import": "./dist/neutral/observable-promise.mjs",
+      "default": "./dist/neutral/observable-promise.mjs"
     },
     "./register": {
       "types": "./dist/types/master/register.d.ts",
-      "import": "./dist/neutral/master/register.mjs"
+      "import": "./dist/neutral/master/register.mjs",
+      "default": "./dist/neutral/master/register.mjs"
     },
     "./worker": {
       "browser": {
         "types": "./dist/types/worker/worker.browser.d.ts",
-        "import": "./dist/browser/worker/worker.browser.mjs"
+        "import": "./dist/browser/worker/worker.browser.mjs",
+        "default": "./dist/browser/worker/worker.browser.mjs"
       },
       "node": {
         "types": "./dist/types/worker/worker.node.d.ts",
-        "import": "./dist/node/worker/worker.node.mjs"
+        "import": "./dist/node/worker/worker.node.mjs",
+        "default": "./dist/node/worker/worker.node.mjs"
       }
     }
   },
+  "main": "dist/neutral/index.mjs",
   "module": "dist/neutral/index.mjs",
   "types": "dist/types/index.d.ts",
   "files": [
-    "dist"
+    "dist/**",
+    "*.js",
+    "*.mjs",
+    "*.ts"
   ],
+  "ava": {
+    "extensions": [
+      "ts"
+    ],
+    "files": [
+      "./test/**/*.test.ts",
+      "./test-tooling/**/*.test.ts"
+    ],
+    "require": [
+      "ts-node/register"
+    ],
+    "serial": true
+  },
   "dependencies": {
     "debug": "^4.4.0",
     "is-observable-2-1-0": "npm:is-observable@2.1.0",
@@ -102,8 +132,8 @@
   "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",
+    "@xylabs/eslint-config-flat": "^6.1.4",
+    "@xylabs/ts-scripts-yarn3": "^6.1.4",
     "typescript": "^5.8.2"
   },
   "optionalDependencies": {
@@ -111,6 +141,5 @@
   },
   "publishConfig": {
     "access": "public"
-  },
-  "stableVersion": "4.6.4"
+  }
 }

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.ts

@@ -0,0 +1,11 @@
+/* eslint-disable import-x/no-internal-modules */
+export { registerSerializer } from './common.ts'
+export * from './master/index.ts'
+export type { QueuedTask } from './master/pool.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/implementation.ts

@@ -0,0 +1,21 @@
+/*
+ * This file is only a stub to make './implementation' resolve to the right module.
+ */
+
+// We alias `src/master/implementation` to `src/master/implementation.browser` for web
+// browsers already in the package.json, so if get here, it's safe to pass-through the
+// node implementation
+
+import * as BrowserImplementation from './implementation.browser.ts'
+import * as NodeImplementation from './implementation.node.ts'
+
+const runningInNode = typeof process !== 'undefined' && (process.arch as string) !== 'browser' && 'pid' in process
+const implementation = runningInNode ? NodeImplementation : BrowserImplementation
+
+/** Default size of pools. Depending on the platform the value might vary from device to device. */
+export const defaultPoolSize = implementation.defaultPoolSize
+
+export const getWorkerImplementation = implementation.getWorkerImplementation
+
+/** Returns `true` if this code is currently running in a worker. */
+export const isWorkerRuntime = implementation.isWorkerRuntime

package/src/master/index.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 { getWorkerImplementation } from './implementation.ts'
+
+export type { FunctionThread, ModuleThread } from '../types/master.ts'
+export { Pool } from './pool.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 = getWorkerImplementation().blob
+
+/** Worker implementation. Either web worker or a node.js Worker class. */
+export const Worker = getWorkerImplementation().default
+
+export { isWorkerRuntime } from './implementation.ts'