@xylabs/threads 3.0.4

package/src/master/spawn.ts

@@ -0,0 +1,172 @@
+/* eslint-disable @typescript-eslint/no-floating-promises */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import DebugLogger from 'debug'
+import { Observable } from 'observable-fns'
+
+import { deserialize } from '../common'
+import { createPromiseWithResolver } from '../promise'
+import { $errors, $events, $terminate, $worker } from '../symbols'
+import {
+  FunctionThread,
+  ModuleThread,
+  PrivateThreadProps,
+  StripAsync,
+  Worker as WorkerType,
+  WorkerEvent,
+  WorkerEventType,
+  WorkerInternalErrorEvent,
+  WorkerMessageEvent,
+  WorkerTerminationEvent,
+} from '../types/master'
+import { WorkerInitMessage, WorkerUncaughtErrorMessage } from '../types/messages'
+import { WorkerFunction, WorkerModule } from '../types/worker'
+import { createProxyFunction, createProxyModule } from './invocation-proxy'
+
+type ArbitraryWorkerInterface = WorkerFunction & WorkerModule<string> & { somekeythatisneverusedinproductioncode123: 'magicmarker123' }
+type ArbitraryThreadType = FunctionThread<any, any> & ModuleThread<any>
+
+export type ExposedToThreadType<Exposed extends WorkerFunction | WorkerModule<any>> =
+  Exposed extends ArbitraryWorkerInterface ? ArbitraryThreadType
+  : Exposed extends WorkerFunction ? FunctionThread<Parameters<Exposed>, StripAsync<ReturnType<Exposed>>>
+  : Exposed extends WorkerModule<any> ? ModuleThread<Exposed>
+  : never
+
+const debugMessages = DebugLogger('threads:master:messages')
+const debugSpawn = DebugLogger('threads:master:spawn')
+const debugThreadUtils = DebugLogger('threads:master:thread-utils')
+
+const isInitMessage = (data: any): data is WorkerInitMessage => data && data.type === ('init' as const)
+const isUncaughtErrorMessage = (data: any): data is WorkerUncaughtErrorMessage => data && data.type === ('uncaughtError' as const)
+
+const initMessageTimeout =
+  typeof process !== 'undefined' && process.env !== undefined && process.env.THREADS_WORKER_INIT_TIMEOUT ?
+    Number.parseInt(process.env.THREADS_WORKER_INIT_TIMEOUT, 10)
+  : 10_000
+
+async function withTimeout<T>(promise: Promise<T>, timeoutInMs: number, errorMessage: string): Promise<T> {
+  let timeoutHandle: any
+
+  const timeout = new Promise<never>((resolve, reject) => {
+    timeoutHandle = setTimeout(() => reject(Error(errorMessage)), timeoutInMs)
+  })
+  const result = await Promise.race([promise, timeout])
+
+  clearTimeout(timeoutHandle)
+  return result
+}
+
+function receiveInitMessage(worker: WorkerType): Promise<WorkerInitMessage> {
+  return new Promise((resolve, reject) => {
+    const messageHandler = ((event: MessageEvent) => {
+      debugMessages('Message from worker before finishing initialization:', event.data)
+      if (isInitMessage(event.data)) {
+        worker.removeEventListener('message', messageHandler)
+        resolve(event.data)
+      } else if (isUncaughtErrorMessage(event.data)) {
+        worker.removeEventListener('message', messageHandler)
+        reject(deserialize(event.data.error))
+      }
+    }) as EventListener
+    worker.addEventListener('message', messageHandler)
+  })
+}
+
+function createEventObservable(worker: WorkerType, workerTermination: Promise<any>): Observable<WorkerEvent> {
+  return new Observable<WorkerEvent>((observer) => {
+    const messageHandler = ((messageEvent: MessageEvent) => {
+      const workerEvent: WorkerMessageEvent<any> = {
+        data: messageEvent.data,
+        type: WorkerEventType.message,
+      }
+      observer.next(workerEvent)
+    }) as EventListener
+    const rejectionHandler = ((errorEvent: PromiseRejectionEvent) => {
+      debugThreadUtils('Unhandled promise rejection event in thread:', errorEvent)
+      const workerEvent: WorkerInternalErrorEvent = {
+        error: Error(errorEvent.reason),
+        type: WorkerEventType.internalError,
+      }
+      observer.next(workerEvent)
+    }) as EventListener
+    worker.addEventListener('message', messageHandler)
+    worker.addEventListener('unhandledrejection', rejectionHandler)
+
+    workerTermination.then(() => {
+      const terminationEvent: WorkerTerminationEvent = {
+        type: WorkerEventType.termination,
+      }
+      worker.removeEventListener('message', messageHandler)
+      worker.removeEventListener('unhandledrejection', rejectionHandler)
+      observer.next(terminationEvent)
+      observer.complete()
+    })
+  })
+}
+
+function createTerminator(worker: WorkerType): { terminate: () => Promise<void>; termination: Promise<void> } {
+  const [termination, resolver] = createPromiseWithResolver<void>()
+  const terminate = async () => {
+    debugThreadUtils('Terminating worker')
+    // Newer versions of worker_threads workers return a promise
+    await worker.terminate()
+    resolver()
+  }
+  return { terminate, termination }
+}
+
+function setPrivateThreadProps<T>(
+  raw: T,
+  worker: WorkerType,
+  workerEvents: Observable<WorkerEvent>,
+  terminate: () => Promise<void>,
+): T & PrivateThreadProps {
+  const workerErrors = workerEvents
+    .filter((event) => event.type === WorkerEventType.internalError)
+    .map((errorEvent) => (errorEvent as WorkerInternalErrorEvent).error)
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return Object.assign(raw as any, {
+    [$errors]: workerErrors,
+    [$events]: workerEvents,
+    [$terminate]: terminate,
+    [$worker]: worker,
+  })
+}
+
+/**
+ * Spawn a new thread. Takes a fresh worker instance, wraps it in a thin
+ * abstraction layer to provide the transparent API and verifies that
+ * the worker has initialized successfully.
+ *
+ * @param worker Instance of `Worker`. Either a web worker, `worker_threads` worker or `tiny-worker` worker.
+ * @param [options]
+ * @param [options.timeout] Init message timeout. Default: 10000 or set by environment variable.
+ */
+export async function spawn<Exposed extends WorkerFunction | WorkerModule<any> = ArbitraryWorkerInterface>(
+  worker: WorkerType,
+  options?: { timeout?: number },
+): Promise<ExposedToThreadType<Exposed>> {
+  debugSpawn('Initializing new thread')
+
+  const timeout = options && options.timeout ? options.timeout : initMessageTimeout
+  const initMessage = await withTimeout(
+    receiveInitMessage(worker),
+    timeout,
+    `Timeout: Did not receive an init message from worker after ${timeout}ms. Make sure the worker calls expose().`,
+  )
+  const exposed = initMessage.exposed
+
+  const { termination, terminate } = createTerminator(worker)
+  const events = createEventObservable(worker, termination)
+
+  if (exposed.type === 'function') {
+    const proxy = createProxyFunction(worker)
+    return setPrivateThreadProps(proxy, worker, events, terminate) as ExposedToThreadType<Exposed>
+  } else if (exposed.type === 'module') {
+    const proxy = createProxyModule(worker, exposed.methods)
+    return setPrivateThreadProps(proxy, worker, events, terminate) as ExposedToThreadType<Exposed>
+  } else {
+    const type = (exposed as WorkerInitMessage['exposed']).type
+    throw new Error(`Worker init message states unexpected type of expose(): ${type}`)
+  }
+}

package/src/master/thread.ts

@@ -0,0 +1,26 @@
+import { Observable } from 'observable-fns'
+
+import { $errors, $events, $terminate } from '../symbols'
+import { Thread as ThreadType, WorkerEvent } from '../types/master'
+
+function fail(message: string): never {
+  throw new Error(message)
+}
+
+export type Thread = ThreadType
+
+/** Thread utility functions. Use them to manage or inspect a `spawn()`-ed thread. */
+export const Thread = {
+  /** Return an observable that can be used to subscribe to all errors happening in the thread. */
+  errors<ThreadT extends ThreadType>(thread: ThreadT): Observable<Error> {
+    return thread[$errors] || fail('Error observable not found. Make sure to pass a thread instance as returned by the spawn() promise.')
+  },
+  /** Return an observable that can be used to subscribe to internal events happening in the thread. Useful for debugging. */
+  events<ThreadT extends ThreadType>(thread: ThreadT): Observable<WorkerEvent> {
+    return thread[$events] || fail('Events observable not found. Make sure to pass a thread instance as returned by the spawn() promise.')
+  },
+  /** Terminate a thread. Remember to terminate every thread when you are done using it. */
+  terminate<ThreadT extends ThreadType>(thread: ThreadT) {
+    return thread[$terminate]()
+  },
+}

package/src/observable-promise.ts

@@ -0,0 +1,181 @@
+/* eslint-disable unicorn/no-thenable */
+/* eslint-disable @typescript-eslint/member-ordering */
+/* eslint-disable @typescript-eslint/no-floating-promises */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-this-alias */
+/* eslint-disable unicorn/no-this-assignment */
+import { Observable, ObservableLike, SubscriptionObserver } from 'observable-fns'
+
+type OnFulfilled<T, Result = void> = (value: T) => Result
+type OnRejected<Result = void> = (error: Error) => Result
+
+type Initializer<T> = (observer: SubscriptionObserver<T>) => UnsubscribeFn | void
+
+type Thenable<T> = { then: (onFulfilled?: (value: T) => any, onRejected?: (error: any) => any) => any }
+
+type UnsubscribeFn = () => void
+
+const doNothing = () => {}
+const returnInput = <T>(input: T): T => input
+const runDeferred = (fn: () => void) => Promise.resolve().then(fn)
+
+function fail(error: Error): never {
+  throw error
+}
+
+function isThenable(thing: any): thing is Thenable<any> {
+  return thing && typeof thing.then === 'function'
+}
+
+/**
+ * Creates a hybrid, combining the APIs of an Observable and a Promise.
+ *
+ * It is used to proxy async process states when we are initially not sure
+ * if that async process will yield values once (-> Promise) or multiple
+ * times (-> Observable).
+ *
+ * Note that the observable promise inherits some of the observable's characteristics:
+ * The `init` function will be called *once for every time anyone subscribes to it*.
+ *
+ * If this is undesired, derive a hot observable from it using `makeHot()` and
+ * subscribe to that.
+ */
+export class ObservablePromise<T> extends Observable<T> implements Promise<T> {
+  readonly [Symbol.toStringTag] = '[object ObservablePromise]'
+  private initHasRun = false
+  private fulfillmentCallbacks: Array<OnFulfilled<T>> = []
+  private rejectionCallbacks: OnRejected[] = []
+
+  private firstValue: T | undefined
+  private firstValueSet = false
+  private rejection: Error | undefined
+  private state: 'fulfilled' | 'pending' | 'rejected' = 'pending'
+
+  constructor(init: Initializer<T>) {
+    super((originalObserver: SubscriptionObserver<T>) => {
+      // tslint:disable-next-line no-this-assignment
+      const self = this
+      const observer: SubscriptionObserver<T> = {
+        ...originalObserver,
+        complete() {
+          originalObserver.complete()
+          self.onCompletion()
+        },
+        error(error: Error) {
+          originalObserver.error(error)
+          self.onError(error)
+        },
+        next(value: T) {
+          originalObserver.next(value)
+          self.onNext(value)
+        },
+      }
+
+      try {
+        this.initHasRun = true
+        return init(observer)
+      } catch (error) {
+        observer.error(error)
+      }
+    })
+  }
+
+  private onNext(value: T) {
+    if (!this.firstValueSet) {
+      this.firstValue = value
+      this.firstValueSet = true
+    }
+  }
+
+  private onError(error: Error) {
+    this.state = 'rejected'
+    this.rejection = error
+
+    for (const onRejected of this.rejectionCallbacks) {
+      // Promisifying the call to turn errors into unhandled promise rejections
+      // instead of them failing sync and cancelling the iteration
+      runDeferred(() => onRejected(error))
+    }
+  }
+
+  private onCompletion() {
+    this.state = 'fulfilled'
+
+    for (const onFulfilled of this.fulfillmentCallbacks) {
+      // Promisifying the call to turn errors into unhandled promise rejections
+      // instead of them failing sync and cancelling the iteration
+      runDeferred(() => onFulfilled(this.firstValue as T))
+    }
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onFulfilledRaw?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+    onRejectedRaw?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+  ): Promise<TResult1 | TResult2> {
+    const onFulfilled: OnFulfilled<T, TResult1> = onFulfilledRaw || (returnInput as any)
+    const onRejected = onRejectedRaw || fail
+    let onRejectedCalled = false
+
+    return new Promise<TResult1 | TResult2>((resolve, reject) => {
+      const rejectionCallback = (error: Error) => {
+        if (onRejectedCalled) return
+        onRejectedCalled = true
+
+        try {
+          resolve(onRejected(error))
+        } catch (anotherError) {
+          reject(anotherError)
+        }
+      }
+      const fulfillmentCallback = (value: T) => {
+        try {
+          resolve(onFulfilled(value))
+        } catch (error) {
+          rejectionCallback(error)
+        }
+      }
+      if (!this.initHasRun) {
+        this.subscribe({ error: rejectionCallback })
+      }
+      if (this.state === 'fulfilled') {
+        return resolve(onFulfilled(this.firstValue as T))
+      }
+      if (this.state === 'rejected') {
+        onRejectedCalled = true
+        return resolve(onRejected(this.rejection as Error))
+      }
+      this.fulfillmentCallbacks.push(fulfillmentCallback)
+      this.rejectionCallbacks.push(rejectionCallback)
+    })
+  }
+
+  catch<Result = never>(onRejected: ((error: Error) => Promise<Result> | Result) | null | undefined) {
+    return this.then(undefined, onRejected) as Promise<Result>
+  }
+
+  finally(onCompleted?: (() => void) | null | undefined) {
+    const handler = onCompleted || doNothing
+    return this.then(
+      (value: T) => {
+        handler()
+        return value
+      },
+      () => handler(),
+    ) as Promise<T>
+  }
+
+  static from<T>(thing: Observable<T> | ObservableLike<T> | ArrayLike<T> | Thenable<T>): ObservablePromise<T> {
+    return isThenable(thing) ?
+        new ObservablePromise((observer) => {
+          const onFulfilled = (value: T) => {
+            observer.next(value)
+            observer.complete()
+          }
+          const onRejected = (error: any) => {
+            observer.error(error)
+          }
+          thing.then(onFulfilled, onRejected)
+        })
+      : (super.from(thing) as ObservablePromise<T>)
+  }
+}

package/src/observable.ts

@@ -0,0 +1,43 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { Observable, ObservableLike, SubscriptionObserver } from 'observable-fns'
+
+const $observers = Symbol('observers')
+
+/**
+ * Observable subject. Implements the Observable interface, but also exposes
+ * the `next()`, `error()`, `complete()` methods to initiate observable
+ * updates "from the outside".
+ *
+ * Use `Observable.from(subject)` to derive an observable that proxies all
+ * values, errors and the completion raised on this subject, but does not
+ * expose the `next()`, `error()`, `complete()` methods.
+ */
+export class Subject<T> extends Observable<T> implements ObservableLike<T> {
+  private [$observers]: Array<SubscriptionObserver<T>>
+
+  constructor() {
+    super((observer) => {
+      this[$observers] = [...(this[$observers] || []), observer]
+      const unsubscribe = () => {
+        this[$observers] = this[$observers].filter((someObserver) => someObserver !== observer)
+      }
+      return unsubscribe
+    })
+
+    this[$observers] = []
+  }
+
+  complete() {
+    for (const observer of this[$observers]) observer.complete()
+  }
+
+  error(error: any) {
+    for (const observer of this[$observers]) observer.error(error)
+  }
+
+  next(value: T) {
+    for (const observer of this[$observers]) observer.next(value)
+  }
+}
+
+export { Observable } from 'observable-fns'

package/src/ponyfills.ts

@@ -0,0 +1,31 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type SettlementResult<T> =
+  | {
+      status: 'fulfilled'
+      value: T
+    }
+  | {
+      reason: any
+      status: 'rejected'
+    }
+
+// Based on <https://github.com/es-shims/Promise.allSettled/blob/master/implementation.js>
+export function allSettled<T>(values: T[]): Promise<Array<SettlementResult<T>>> {
+  return Promise.all(
+    values.map((item) => {
+      const onFulfill = (value: T) => {
+        return { status: 'fulfilled', value } as const
+      }
+      const onReject = (reason: any) => {
+        return { reason, status: 'rejected' } as const
+      }
+
+      const itemPromise = Promise.resolve(item)
+      try {
+        return itemPromise.then(onFulfill, onReject)
+      } catch (error) {
+        return Promise.reject(error)
+      }
+    }),
+  )
+}

package/src/promise.ts

@@ -0,0 +1,26 @@
+// eslint-disable-next-line unicorn/no-useless-undefined
+const doNothing = () => undefined
+
+/**
+ * Creates a new promise and exposes its resolver function.
+ * Use with care!
+ */
+export function createPromiseWithResolver<T>(): [Promise<T>, (result: T) => void] {
+  let alreadyResolved = false
+  let resolvedTo: T
+  let resolver: (value: T | PromiseLike<T>) => void = doNothing
+
+  const promise = new Promise<T>((resolve) => {
+    if (alreadyResolved) {
+      resolve(resolvedTo)
+    } else {
+      resolver = resolve
+    }
+  })
+  const exposedResolver = (value: T) => {
+    alreadyResolved = true
+    resolvedTo = value
+    resolver(resolvedTo)
+  }
+  return [promise, exposedResolver]
+}

package/src/serializers.ts

@@ -0,0 +1,67 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { SerializedError } from './types/messages'
+
+export interface Serializer<Msg = JsonSerializable, Input = any> {
+  deserialize(message: Msg): Input
+  serialize(input: Input): Msg
+}
+
+export interface SerializerImplementation<Msg = JsonSerializable, Input = any> {
+  deserialize(message: Msg, defaultDeserialize: (msg: Msg) => Input): Input
+  serialize(input: Input, defaultSerialize: (inp: Input) => Msg): Msg
+}
+
+export function extendSerializer<MessageType, InputType = any>(
+  extend: Serializer<MessageType, InputType>,
+  implementation: SerializerImplementation<MessageType, InputType>,
+): Serializer<MessageType, InputType> {
+  const fallbackDeserializer = extend.deserialize.bind(extend)
+  const fallbackSerializer = extend.serialize.bind(extend)
+
+  return {
+    deserialize(message: MessageType): InputType {
+      return implementation.deserialize(message, fallbackDeserializer)
+    },
+
+    serialize(input: InputType): MessageType {
+      return implementation.serialize(input, fallbackSerializer)
+    },
+  }
+}
+
+type JsonSerializablePrimitive = string | number | boolean | null
+
+type JsonSerializableObject = {
+  [key: string]: JsonSerializablePrimitive | JsonSerializablePrimitive[] | JsonSerializableObject | JsonSerializableObject[] | undefined
+}
+
+export type JsonSerializable = JsonSerializablePrimitive | JsonSerializablePrimitive[] | JsonSerializableObject | JsonSerializableObject[]
+
+const DefaultErrorSerializer: Serializer<SerializedError, Error> = {
+  deserialize(message: SerializedError): Error {
+    return Object.assign(Error(message.message), {
+      name: message.name,
+      stack: message.stack,
+    })
+  },
+  serialize(error: Error): SerializedError {
+    return {
+      __error_marker: '$$error',
+      message: error.message,
+      name: error.name,
+      stack: error.stack,
+    }
+  },
+}
+
+const isSerializedError = (thing: any): thing is SerializedError =>
+  thing && typeof thing === 'object' && '__error_marker' in thing && thing.__error_marker === '$$error'
+
+export const DefaultSerializer: Serializer<JsonSerializable> = {
+  deserialize(message: JsonSerializable): any {
+    return isSerializedError(message) ? DefaultErrorSerializer.deserialize(message) : message
+  },
+  serialize(input: any): JsonSerializable {
+    return input instanceof Error ? (DefaultErrorSerializer.serialize(input) as any as JsonSerializable) : input
+  },
+}

package/src/symbols.ts

@@ -0,0 +1,5 @@
+export const $errors = Symbol('thread.errors')
+export const $events = Symbol('thread.events')
+export const $terminate = Symbol('thread.terminate')
+export const $transferable = Symbol('thread.transferable')
+export const $worker = Symbol('thread.worker')

package/src/transferable.ts

@@ -0,0 +1,68 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { $transferable } from './symbols'
+
+export interface TransferDescriptor<T = any> {
+  [$transferable]: true
+  send: T
+  transferables: Transferable[]
+}
+
+function isTransferable(thing: any): thing is Transferable {
+  if (!thing || typeof thing !== 'object') return false
+  // Don't check too thoroughly, since the list of transferable things in JS might grow over time
+  return true
+}
+
+export function isTransferDescriptor(thing: any): thing is TransferDescriptor {
+  return thing && typeof thing === 'object' && thing[$transferable]
+}
+
+/**
+ * Mark a transferable object as such, so it will no be serialized and
+ * deserialized on messaging with the main thread, but to transfer
+ * ownership of it to the receiving thread.
+ *
+ * Only works with array buffers, message ports and few more special
+ * types of objects, but it's much faster than serializing and
+ * deserializing them.
+ *
+ * Note:
+ * The transferable object cannot be accessed by this thread again
+ * unless the receiving thread transfers it back again!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+export function Transfer(transferable: Transferable): TransferDescriptor
+
+/**
+ * Mark transferable objects within an arbitrary object or array as
+ * being a transferable object. They will then not be serialized
+ * and deserialized on messaging with the main thread, but ownership
+ * of them will be tranferred to the receiving thread.
+ *
+ * Only array buffers, message ports and few more special types of
+ * objects can be transferred, but it's much faster than serializing and
+ * deserializing them.
+ *
+ * Note:
+ * The transferable object cannot be accessed by this thread again
+ * unless the receiving thread transfers it back again!
+ *
+ * @param transferable Array buffer, message port or similar.
+ * @see <https://developers.google.com/web/updates/2011/12/Transferable-Objects-Lightning-Fast>
+ */
+export function Transfer<T>(payload: T, transferables: Transferable[]): TransferDescriptor
+
+export function Transfer<T>(payload: T, transferables?: Transferable[]): TransferDescriptor {
+  if (!transferables) {
+    if (!isTransferable(payload)) throw new Error('Not transferable')
+    transferables = [payload]
+  }
+
+  return {
+    [$transferable]: true,
+    send: payload,
+    transferables,
+  }
+}