@xylabs/threads 4.8.0-rc.2 → 4.8.0

package/src/observable-promise.ts

@@ -0,0 +1,184 @@
+/* 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 type { ObservableLike, SubscriptionObserver } from 'observable-fns'
+import { Observable } 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 (ex) {
+          const error = ex as 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 override 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,44 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { ObservableLike, SubscriptionObserver } from 'observable-fns'
+import { Observable } 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/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,68 @@
+/* eslint-disable import-x/no-internal-modules */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { SerializedError } from './types/messages.ts'
+
+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(new 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,69 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { $transferable } from './symbols.ts'
+
+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 {
+  console.log('Transfer')
+  if (!transferables) {
+    if (!isTransferable(payload)) throw new Error('Not transferable')
+    transferables = [payload]
+  }
+
+  return {
+    [$transferable]: true,
+    send: payload,
+    transferables,
+  }
+}

package/src/types/master.ts

@@ -0,0 +1,132 @@
+/* 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 type { Observable } from 'observable-fns'
+
+import type { ObservablePromise } from '../observable-promise.ts'
+import type {
+  $errors, $events, $terminate, $worker,
+} from '../symbols.ts'
+import type { TransferDescriptor } from '../transferable.ts'
+
+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
+
+type StripTransfer<Type> = Type extends TransferDescriptor<infer BaseType> ? BaseType : Type
+
+export type ModuleMethods = { [methodName: string]: (...args: any) => any }
+
+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,72 @@
+/* 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[]
+}
+
+////////////////////////////
+// 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'
+}

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

@@ -0,0 +1,5 @@
+export interface WorkerGlobalScope {
+  addEventListener(eventName: string, listener: (event: Event) => void): void
+  postMessage(message: unknown, transferList?: Readonly<Transferable[]>): void
+  removeEventListener(eventName: string, listener: (event: Event) => void): void
+}