Skip to content

Transferable

Marks encoded worker message fields that should move through postMessage as transfer-list entries.

Worker messages still pass through schema encoding and structured clone, but schemas wrapped with schema can also report backing resources such as ArrayBuffer, ImageData.data.buffer, or MessagePort to a Collector. Worker platforms then pass the collected values as the transfer list for the same postMessage call, avoiding copies for large payloads and ports.

10 exports Added in v4.0.0 Source

Accessors

addAll

Added in v4.0.0 Source

Adds transferables to the current Collector when one is present in the context, and does nothing otherwise.

Signature

declare function addAll(tranferables: Iterable<Transferable>): Effect<void>;

Constructors

makeCollector

Added in v4.0.0 Source

Effect that creates a fresh Collector service for accumulating transferables.

Signature

declare const makeCollector: Effect.Effect<Collector["Service"]>;

makeCollectorUnsafe

Added in v4.0.0 Source

Creates a mutable Collector service directly, exposing unsafe synchronous methods for reading, adding, and clearing collected transferables.

Signature

declare function makeCollectorUnsafe(): {
  readonly addAll: (_: Iterable<Transferable>) => Effect<void>;
  readonly addAllUnsafe: (_: Iterable<Transferable>) => void;
  readonly clear: Effect<Array<Transferable>>;
  readonly clearUnsafe: () => Array<Transferable>;
  readonly read: Effect<Array<Transferable>>;
  readonly readUnsafe: () => Array<Transferable>;
};

Getters

getterAddAll

Added in v4.0.0 Source

Creates a schema getter that records transferables derived from a value in the current Collector while passing the value through unchanged.

Signature

declare function getterAddAll<A>(f: (_: A) => Iterable<Transferable>): Getter<A, A>;

Schemas

ImageData

Added in v4.0.0 Source

Schema for transferring ImageData values with their pixel data buffer.

Signature

declare const ImageData: Transferable<Schema.declare<ImageData>>;

MessagePort

Added in v4.0.0 Source

Schema for transferring MessagePort values as transferable objects.

Signature

declare const MessagePort: Transferable<Schema.declare<MessagePort>>;

schema

Added in v4.0.0 Source

Wraps a schema so encoding records transferables selected from the encoded value, enabling worker messages to populate a postMessage transfer list.

Signature

declare const schema: {
  <S extends Top>(f: (_: S["Encoded"]) => Iterable<Transferable>): (self: S) => Transferable<S>;
  <S extends Top>(self: S, f: (_: S["Encoded"]) => Iterable<Transferable>): Transferable<S>;
};

Transferable interface

Added in v4.0.0 Source

Schema wrapper whose encode path can record transferables with a Collector while preserving the wrapped schema's decoded type.

Signature

interface Transferable<S extends Schema.Top> extends decodeTo<
  Schema.toType<S["Rebuild"]>,
  S["Rebuild"]
> {
  constructor(_: never);
}

Uint8Array

Added in v4.0.0 Source

Schema for transferring Uint8Array values with their backing buffer.

Signature

declare const Uint8Array: Transferable<Schema.instanceOf<globalThis.Uint8Array<ArrayBuffer>>>;

Services

Collector

Added in v4.0.0 Source

Service for collecting Transferable objects while encoding worker messages so they can be passed to postMessage transfer lists.

Signature

declare class Collector extends Shape<
  "effect/workers/Transferable/Collector",
  {
    readonly addAll: (_: Iterable<Transferable>) => Effect<void>;
    readonly addAllUnsafe: (_: Iterable<Transferable>) => void;
    readonly clear: Effect<Array<Transferable>>;
    readonly clearUnsafe: () => Array<Transferable>;
    readonly read: Effect<Array<Transferable>>;
    readonly readUnsafe: () => Array<Transferable>;
  },
  this
> {
  constructor(_: never);
}