@xylabs/threads 3.0.4

package/src/types/master.ts

@@ -0,0 +1,130 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/// <reference lib="dom" />
+// tslint:disable max-classes-per-file
+
+// Cannot use `compilerOptions.esModuleInterop` and default import syntax
+// See <https://github.com/microsoft/TypeScript/issues/28009>
+import { Observable } from 'observable-fns'
+
+import { ObservablePromise } from '../observable-promise'
+import { $errors, $events, $terminate, $worker } from '../symbols'
+import { TransferDescriptor } from '../transferable'
+
+interface ObservableLikeSubscription {
+  unsubscribe(): any
+}
+interface ObservableLike<T> {
+  subscribe(onNext: (value: T) => any, onError?: (error: any) => any, onComplete?: () => any): ObservableLikeSubscription
+  subscribe(listeners: { complete?(): any; error?(error: any): any; next?(value: T): any }): ObservableLikeSubscription
+}
+
+export type StripAsync<Type> =
+  Type extends Promise<infer PromiseBaseType> ? PromiseBaseType
+  : Type extends ObservableLike<infer ObservableBaseType> ? ObservableBaseType
+  : Type
+
+export type StripTransfer<Type> = Type extends TransferDescriptor<infer BaseType> ? BaseType : Type
+
+export type ModuleMethods = { [methodName: string]: (...args: any) => any }
+
+export type ProxyableArgs<Args extends any[]> =
+  Args extends [arg0: infer Arg0, ...rest: infer RestArgs] ? [Arg0 extends Transferable ? Arg0 | TransferDescriptor<Arg0> : Arg0, ...RestArgs] : Args
+
+export type ProxyableFunction<Args extends any[], ReturnType> =
+  Args extends [] ? () => ObservablePromise<StripTransfer<StripAsync<ReturnType>>>
+  : (...args: ProxyableArgs<Args>) => ObservablePromise<StripTransfer<StripAsync<ReturnType>>>
+
+export type ModuleProxy<Methods extends ModuleMethods> = {
+  [method in keyof Methods]: ProxyableFunction<Parameters<Methods[method]>, ReturnType<Methods[method]>>
+}
+
+export interface PrivateThreadProps {
+  [$errors]: Observable<Error>
+  [$events]: Observable<WorkerEvent>
+  [$terminate]: () => Promise<void>
+  [$worker]: Worker
+}
+
+export type FunctionThread<Args extends any[] = any[], ReturnType = any> = ProxyableFunction<Args, ReturnType> & PrivateThreadProps
+export type ModuleThread<Methods extends ModuleMethods = any> = ModuleProxy<Methods> & PrivateThreadProps
+
+// We have those extra interfaces to keep the general non-specific `Thread` type
+// as an interface, so it's displayed concisely in any TypeScript compiler output.
+interface AnyFunctionThread extends PrivateThreadProps {
+  (...args: any[]): ObservablePromise<any>
+}
+
+// tslint:disable-next-line no-empty-interface
+interface AnyModuleThread extends PrivateThreadProps {
+  // Not specifying an index signature here as that would make `ModuleThread` incompatible
+}
+
+/** Worker thread. Either a `FunctionThread` or a `ModuleThread`. */
+export type Thread = AnyFunctionThread | AnyModuleThread
+
+export type TransferList = Transferable[]
+
+/** Worker instance. Either a web worker or a node.js Worker provided by `worker_threads` or `tiny-worker`. */
+export interface Worker extends EventTarget {
+  postMessage(value: any, transferList?: TransferList): void
+  /** In nodejs 10+ return type is Promise while with tiny-worker and in browser return type is void */
+  terminate(callback?: (error?: Error, exitCode?: number) => void): void | Promise<number>
+}
+export interface ThreadsWorkerOptions extends WorkerOptions {
+  /** Whether to apply CORS protection workaround. Defaults to true. */
+  CORSWorkaround?: boolean
+  /** Prefix for the path passed to the Worker constructor. Web worker only. */
+  _baseURL?: string
+  /** Resource limits passed on to Node worker_threads */
+  resourceLimits?: {
+    /** The size of a pre-allocated memory range used for generated code. */
+    codeRangeSizeMb?: number
+    /** The maximum size of the main heap in MB. */
+    maxOldGenerationSizeMb?: number
+    /** The maximum size of a heap space for recently created objects. */
+    maxYoungGenerationSizeMb?: number
+  }
+  /** Data passed on to node.js worker_threads. */
+  workerData?: any
+}
+
+/** Worker implementation. Either web worker or a node.js Worker class. */
+export declare class WorkerImplementation extends EventTarget implements Worker {
+  constructor(path: string, options?: ThreadsWorkerOptions)
+  postMessage(value: any, transferList?: TransferList): void
+  terminate(): void | Promise<number>
+}
+
+/** Class to spawn workers from a blob or source string. */
+export declare class BlobWorker extends WorkerImplementation {
+  constructor(blob: Blob, options?: ThreadsWorkerOptions)
+  static fromText(source: string, options?: ThreadsWorkerOptions): WorkerImplementation
+}
+
+export interface ImplementationExport {
+  blob: typeof BlobWorker
+  default: typeof WorkerImplementation
+}
+
+/** Event as emitted by worker thread. Subscribe to using `Thread.events(thread)`. */
+export enum WorkerEventType {
+  internalError = 'internalError',
+  message = 'message',
+  termination = 'termination',
+}
+
+export interface WorkerInternalErrorEvent {
+  error: Error
+  type: WorkerEventType.internalError
+}
+
+export interface WorkerMessageEvent<Data> {
+  data: Data
+  type: WorkerEventType.message
+}
+
+export interface WorkerTerminationEvent {
+  type: WorkerEventType.termination
+}
+
+export type WorkerEvent = WorkerInternalErrorEvent | WorkerMessageEvent<any> | WorkerTerminationEvent

package/src/types/messages.ts

@@ -0,0 +1,81 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/member-ordering */
+export interface SerializedError {
+  __error_marker: '$$error'
+  message: string
+  name: string
+  stack?: string
+}
+
+/////////////////////////////
+// Messages sent by master:
+
+export enum MasterMessageType {
+  cancel = 'cancel',
+  run = 'run',
+}
+
+export type MasterJobCancelMessage = {
+  type: MasterMessageType.cancel
+  uid: number
+}
+
+export type MasterJobRunMessage = {
+  type: MasterMessageType.run
+  uid: number
+  method?: string
+  args: any[]
+}
+
+export type MasterSentMessage = MasterJobCancelMessage | MasterJobRunMessage
+
+////////////////////////////
+// Messages sent by worker:
+
+export enum WorkerMessageType {
+  error = 'error',
+  init = 'init',
+  result = 'result',
+  running = 'running',
+  uncaughtError = 'uncaughtError',
+}
+
+export type WorkerUncaughtErrorMessage = {
+  type: WorkerMessageType.uncaughtError
+  error: {
+    message: string
+    name: string
+    stack?: string
+  }
+}
+
+export type WorkerInitMessage = {
+  type: WorkerMessageType.init
+  exposed: { type: 'function' } | { type: 'module'; methods: string[] }
+}
+
+export type WorkerJobErrorMessage = {
+  type: WorkerMessageType.error
+  uid: number
+  error: SerializedError
+}
+
+export type WorkerJobResultMessage = {
+  type: WorkerMessageType.result
+  uid: number
+  complete?: true
+  payload?: any
+}
+
+export type WorkerJobStartMessage = {
+  type: WorkerMessageType.running
+  uid: number
+  resultType: 'observable' | 'promise'
+}
+
+export type WorkerSentMessage =
+  | WorkerInitMessage
+  | WorkerJobErrorMessage
+  | WorkerJobResultMessage
+  | WorkerJobStartMessage
+  | WorkerUncaughtErrorMessage

package/src/types/worker.ts

@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type UnsubscribeFn = () => void
+
+export interface AbstractedWorkerAPI {
+  isWorkerRuntime(): boolean
+  postMessageToMaster(message: any, transferList?: Transferable[]): void
+  subscribeToMasterMessages(onMessage: (data: any) => void): UnsubscribeFn
+}
+
+export type WorkerFunction = ((...args: any[]) => any) | (() => any)
+
+export type WorkerModule<Keys extends string> = {
+  [key in Keys]: WorkerFunction
+}

package/src/worker/bundle-entry.ts

@@ -0,0 +1,10 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { expose } from './index'
+export * from './index'
+
+if (typeof global !== 'undefined') {
+  ;(global as any).expose = expose
+}
+if (typeof self !== 'undefined') {
+  ;(self as any).expose = expose
+}

package/src/worker/implementation.browser.ts

@@ -0,0 +1,40 @@
+/* eslint-disable import/no-default-export */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/// <reference lib="dom" />
+// tslint:disable no-shadowed-variable
+
+import { AbstractedWorkerAPI } from '../types/worker'
+
+interface WorkerGlobalScope {
+  addEventListener(eventName: string, listener: (event: Event) => void): void
+  postMessage(message: any, transferables?: any[]): void
+  removeEventListener(eventName: string, listener: (event: Event) => void): void
+}
+
+declare const self: WorkerGlobalScope
+
+const isWorkerRuntime: AbstractedWorkerAPI['isWorkerRuntime'] = function isWorkerRuntime() {
+  const isWindowContext = self !== undefined && typeof Window !== 'undefined' && self instanceof Window
+  return self !== undefined && self['postMessage'] && !isWindowContext ? true : false
+}
+
+const postMessageToMaster: AbstractedWorkerAPI['postMessageToMaster'] = function postMessageToMaster(data, transferList?) {
+  self.postMessage(data, transferList)
+}
+
+const subscribeToMasterMessages: AbstractedWorkerAPI['subscribeToMasterMessages'] = function subscribeToMasterMessages(onMessage) {
+  const messageHandler = (messageEvent: MessageEvent) => {
+    onMessage(messageEvent.data)
+  }
+  const unsubscribe = () => {
+    self.removeEventListener('message', messageHandler as EventListener)
+  }
+  self.addEventListener('message', messageHandler as EventListener)
+  return unsubscribe
+}
+
+export default {
+  isWorkerRuntime,
+  postMessageToMaster,
+  subscribeToMasterMessages,
+}

package/src/worker/implementation.tiny-worker.ts

@@ -0,0 +1,52 @@
+/* eslint-disable import/no-default-export */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/// <reference lib="dom" />
+// tslint:disable no-shadowed-variable
+
+import { AbstractedWorkerAPI } from '../types/worker'
+
+interface WorkerGlobalScope {
+  addEventListener(eventName: string, listener: (event: Event) => void): void
+  postMessage(message: any, transferables?: any[]): void
+  removeEventListener(eventName: string, listener: (event: Event) => void): void
+}
+
+declare const self: WorkerGlobalScope
+
+if (self === undefined) {
+  ;(global as any).self = global
+}
+
+const isWorkerRuntime: AbstractedWorkerAPI['isWorkerRuntime'] = function isWorkerRuntime() {
+  return self !== undefined && self['postMessage'] ? true : false
+}
+
+const postMessageToMaster: AbstractedWorkerAPI['postMessageToMaster'] = function postMessageToMaster(data) {
+  // TODO: Warn that Transferables are not supported on first attempt to use feature
+  self.postMessage(data)
+}
+
+let muxingHandlerSetUp = false
+const messageHandlers = new Set<(data: any) => void>()
+
+const subscribeToMasterMessages: AbstractedWorkerAPI['subscribeToMasterMessages'] = function subscribeToMasterMessages(onMessage) {
+  if (!muxingHandlerSetUp) {
+    // We have one multiplexing message handler as tiny-worker's
+    // addEventListener() only allows you to set a single message handler
+    self.addEventListener('message', ((event: MessageEvent) => {
+      for (const handler of messageHandlers) handler(event.data)
+    }) as EventListener)
+    muxingHandlerSetUp = true
+  }
+
+  messageHandlers.add(onMessage)
+
+  const unsubscribe = () => messageHandlers.delete(onMessage)
+  return unsubscribe
+}
+
+export default {
+  isWorkerRuntime,
+  postMessageToMaster,
+  subscribeToMasterMessages,
+}

package/src/worker/implementation.ts

@@ -0,0 +1,23 @@
+/* eslint-disable import/no-default-export */
+// tslint:disable no-var-requires
+/*
+ * This file is only a stub to make './implementation' resolve to the right module.
+ */
+
+import { AbstractedWorkerAPI } from '../types/worker'
+import WebWorkerImplementation from './implementation.browser'
+import TinyWorkerImplementation from './implementation.tiny-worker'
+import WorkerThreadsImplementation from './implementation.worker_threads'
+
+const runningInNode = typeof process !== 'undefined' && (process.arch as string) !== 'browser' && 'pid' in process
+
+function selectNodeImplementation(): AbstractedWorkerAPI {
+  try {
+    WorkerThreadsImplementation.testImplementation()
+    return WorkerThreadsImplementation
+  } catch {
+    return TinyWorkerImplementation
+  }
+}
+
+export default runningInNode ? selectNodeImplementation() : WebWorkerImplementation

package/src/worker/implementation.worker_threads.ts

@@ -0,0 +1,50 @@
+/* eslint-disable import/no-default-export */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// tslint:disable no-shadowed-variable
+import { MessagePort } from 'node:worker_threads'
+
+import { AbstractedWorkerAPI } from '../types/worker'
+import WorkerThreads from '../worker_threads'
+
+function assertMessagePort(port: MessagePort | null | undefined): MessagePort {
+  if (!port) {
+    throw new Error('Invariant violation: MessagePort to parent is not available.')
+  }
+  return port
+}
+
+const isWorkerRuntime: AbstractedWorkerAPI['isWorkerRuntime'] = function isWorkerRuntime() {
+  return !WorkerThreads().isMainThread
+}
+
+const postMessageToMaster: AbstractedWorkerAPI['postMessageToMaster'] = function postMessageToMaster(data, transferList) {
+  assertMessagePort(WorkerThreads().parentPort).postMessage(data, transferList as any)
+}
+
+const subscribeToMasterMessages: AbstractedWorkerAPI['subscribeToMasterMessages'] = function subscribeToMasterMessages(onMessage) {
+  const parentPort = WorkerThreads().parentPort
+
+  if (!parentPort) {
+    throw new Error('Invariant violation: MessagePort to parent is not available.')
+  }
+  const messageHandler = (message: any) => {
+    onMessage(message)
+  }
+  const unsubscribe = () => {
+    assertMessagePort(parentPort).off('message', messageHandler)
+  }
+  assertMessagePort(parentPort).on('message', messageHandler)
+  return unsubscribe
+}
+
+function testImplementation() {
+  // Will throw if `worker_threads` are not available
+  WorkerThreads()
+}
+
+export default {
+  isWorkerRuntime,
+  postMessageToMaster,
+  subscribeToMasterMessages,
+  testImplementation,
+}

package/src/worker/index.ts

@@ -0,0 +1,228 @@
+/* eslint-disable @typescript-eslint/no-floating-promises */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import isSomeObservable from 'is-observable'
+import { Observable, Subscription } from 'observable-fns'
+
+import { deserialize, serialize } from '../common'
+import { isTransferDescriptor, TransferDescriptor } from '../transferable'
+import {
+  MasterJobCancelMessage,
+  MasterJobRunMessage,
+  MasterMessageType,
+  SerializedError,
+  WorkerInitMessage,
+  WorkerJobErrorMessage,
+  WorkerJobResultMessage,
+  WorkerJobStartMessage,
+  WorkerMessageType,
+  WorkerUncaughtErrorMessage,
+} from '../types/messages'
+import { WorkerFunction, WorkerModule } from '../types/worker'
+import Implementation from './implementation'
+
+export { registerSerializer } from '../common'
+export { Transfer } from '../transferable'
+
+/** Returns `true` if this code is currently running in a worker. */
+export const isWorkerRuntime = Implementation.isWorkerRuntime
+
+let exposeCalled = false
+
+const activeSubscriptions = new Map<number, Subscription<any>>()
+
+const isMasterJobCancelMessage = (thing: any): thing is MasterJobCancelMessage => thing && thing.type === MasterMessageType.cancel
+const isMasterJobRunMessage = (thing: any): thing is MasterJobRunMessage => thing && thing.type === MasterMessageType.run
+
+/**
+ * There are issues with `is-observable` not recognizing zen-observable's instances.
+ * We are using `observable-fns`, but it's based on zen-observable, too.
+ */
+const isObservable = (thing: any): thing is Observable<any> => isSomeObservable(thing) || isZenObservable(thing)
+
+function isZenObservable(thing: any): thing is Observable<any> {
+  return thing && typeof thing === 'object' && typeof thing.subscribe === 'function'
+}
+
+function deconstructTransfer(thing: any) {
+  return isTransferDescriptor(thing) ? { payload: thing.send, transferables: thing.transferables } : { payload: thing, transferables: undefined }
+}
+
+function postFunctionInitMessage() {
+  const initMessage: WorkerInitMessage = {
+    exposed: {
+      type: 'function',
+    },
+    type: WorkerMessageType.init,
+  }
+  Implementation.postMessageToMaster(initMessage)
+}
+
+function postModuleInitMessage(methodNames: string[]) {
+  const initMessage: WorkerInitMessage = {
+    exposed: {
+      methods: methodNames,
+      type: 'module',
+    },
+    type: WorkerMessageType.init,
+  }
+  Implementation.postMessageToMaster(initMessage)
+}
+
+function postJobErrorMessage(uid: number, rawError: Error | TransferDescriptor<Error>) {
+  const { payload: error, transferables } = deconstructTransfer(rawError)
+  const errorMessage: WorkerJobErrorMessage = {
+    error: serialize(error) as any as SerializedError,
+    type: WorkerMessageType.error,
+    uid,
+  }
+  Implementation.postMessageToMaster(errorMessage, transferables)
+}
+
+function postJobResultMessage(uid: number, completed: boolean, resultValue?: any) {
+  const { payload, transferables } = deconstructTransfer(resultValue)
+  const resultMessage: WorkerJobResultMessage = {
+    complete: completed ? true : undefined,
+    payload,
+    type: WorkerMessageType.result,
+    uid,
+  }
+  Implementation.postMessageToMaster(resultMessage, transferables)
+}
+
+function postJobStartMessage(uid: number, resultType: WorkerJobStartMessage['resultType']) {
+  const startMessage: WorkerJobStartMessage = {
+    resultType,
+    type: WorkerMessageType.running,
+    uid,
+  }
+  Implementation.postMessageToMaster(startMessage)
+}
+
+function postUncaughtErrorMessage(error: Error) {
+  try {
+    const errorMessage: WorkerUncaughtErrorMessage = {
+      error: serialize(error) as any as SerializedError,
+      type: WorkerMessageType.uncaughtError,
+    }
+    Implementation.postMessageToMaster(errorMessage)
+  } catch (subError) {
+    // tslint:disable-next-line no-console
+    console.error(
+      'Not reporting uncaught error back to master thread as it ' + 'occured while reporting an uncaught error already.' + '\nLatest error:',
+      subError,
+      '\nOriginal error:',
+      error,
+    )
+  }
+}
+
+async function runFunction(jobUID: number, fn: WorkerFunction, args: any[]) {
+  let syncResult: any
+
+  try {
+    syncResult = fn(...args)
+  } catch (error) {
+    return postJobErrorMessage(jobUID, error)
+  }
+
+  const resultType = isObservable(syncResult) ? 'observable' : 'promise'
+  postJobStartMessage(jobUID, resultType)
+
+  if (isObservable(syncResult)) {
+    const subscription = syncResult.subscribe(
+      (value) => postJobResultMessage(jobUID, false, serialize(value)),
+      (error) => {
+        postJobErrorMessage(jobUID, serialize(error) as any)
+        activeSubscriptions.delete(jobUID)
+      },
+      () => {
+        postJobResultMessage(jobUID, true)
+        activeSubscriptions.delete(jobUID)
+      },
+    )
+    activeSubscriptions.set(jobUID, subscription)
+  } else {
+    try {
+      const result = await syncResult
+      postJobResultMessage(jobUID, true, serialize(result))
+    } catch (error) {
+      postJobErrorMessage(jobUID, serialize(error) as any)
+    }
+  }
+}
+
+/**
+ * Expose a function or a module (an object whose values are functions)
+ * to the main thread. Must be called exactly once in every worker thread
+ * to signal its API to the main thread.
+ *
+ * @param exposed Function or object whose values are functions
+ */
+export function expose(exposed: WorkerFunction | WorkerModule<any>) {
+  if (!Implementation.isWorkerRuntime()) {
+    throw new Error('expose() called in the master thread.')
+  }
+  if (exposeCalled) {
+    throw new Error('expose() called more than once. This is not possible. Pass an object to expose() if you want to expose multiple functions.')
+  }
+  exposeCalled = true
+
+  if (typeof exposed === 'function') {
+    Implementation.subscribeToMasterMessages((messageData) => {
+      if (isMasterJobRunMessage(messageData) && !messageData.method) {
+        runFunction(messageData.uid, exposed, messageData.args.map(deserialize))
+      }
+    })
+    postFunctionInitMessage()
+  } else if (typeof exposed === 'object' && exposed) {
+    Implementation.subscribeToMasterMessages((messageData) => {
+      if (isMasterJobRunMessage(messageData) && messageData.method) {
+        runFunction(messageData.uid, exposed[messageData.method], messageData.args.map(deserialize))
+      }
+    })
+
+    const methodNames = Object.keys(exposed).filter((key) => typeof exposed[key] === 'function')
+    postModuleInitMessage(methodNames)
+  } else {
+    throw new Error(`Invalid argument passed to expose(). Expected a function or an object, got: ${exposed}`)
+  }
+
+  Implementation.subscribeToMasterMessages((messageData) => {
+    if (isMasterJobCancelMessage(messageData)) {
+      const jobUID = messageData.uid
+      const subscription = activeSubscriptions.get(jobUID)
+
+      if (subscription) {
+        subscription.unsubscribe()
+        activeSubscriptions.delete(jobUID)
+      }
+    }
+  })
+}
+
+if (typeof self !== 'undefined' && typeof self.addEventListener === 'function' && Implementation.isWorkerRuntime()) {
+  self.addEventListener('error', (event) => {
+    // Post with some delay, so the master had some time to subscribe to messages
+    setTimeout(() => postUncaughtErrorMessage(event.error || event), 250)
+  })
+  self.addEventListener('unhandledrejection', (event) => {
+    const error = (event as any).reason
+    if (error && typeof (error as any).message === 'string') {
+      // Post with some delay, so the master had some time to subscribe to messages
+      setTimeout(() => postUncaughtErrorMessage(error), 250)
+    }
+  })
+}
+
+if (typeof process !== 'undefined' && typeof process.on === 'function' && Implementation.isWorkerRuntime()) {
+  process.on('uncaughtException', (error) => {
+    // Post with some delay, so the master had some time to subscribe to messages
+    setTimeout(() => postUncaughtErrorMessage(error), 250)
+  })
+  process.on('unhandledRejection', (error) => {
+    if (error && typeof (error as any).message === 'string') {
+      // Post with some delay, so the master had some time to subscribe to messages
+      setTimeout(() => postUncaughtErrorMessage(error as any), 250)
+    }
+  })
+}

package/src/worker_threads.ts

@@ -0,0 +1,28 @@
+/* eslint-disable import/no-default-export */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// Webpack hack
+// tslint:disable no-eval
+
+declare function __non_webpack_require__(module: string): any
+
+// FIXME
+type MessagePort = any
+
+interface WorkerThreadsModule {
+  MessagePort: typeof MessagePort
+  isMainThread: boolean
+  parentPort: MessagePort
+}
+
+let implementation: WorkerThreadsModule | undefined
+
+function selectImplementation(): WorkerThreadsModule {
+  return typeof __non_webpack_require__ === 'function' ? __non_webpack_require__('worker_threads') : eval('require')('worker_threads')
+}
+
+export default function getImplementation(): WorkerThreadsModule {
+  if (!implementation) {
+    implementation = selectImplementation()
+  }
+  return implementation
+}