worker.postMessage({ type: 'DO_WORK', payload });

worker.onmessage = event => {
  console.log(event.data);
};

caller stack -> callee stack -> return value / throw

sender context
  -> serialize / clone / transfer data
  -> enqueue task to receiver event loop
  -> sender continues immediately

receiver context
  -> later, when event loop picks the task
  -> dispatch MessageEvent
  -> handler runs

postMessage gives you delivery attempt, not distributed correctness.

Every message is a delayed fact. Treat it as possibly stale on arrival.

worker.postMessage({ action: 'calculate', data });

type MessageKind = 'command' | 'event' | 'query' | 'response' | 'error';

type ProtocolEnvelope<TType extends string, TPayload> = {
  protocol: 'browser-orchestration/v1';
  id: string;
  type: TType;
  kind: MessageKind;

  source: {
    contextId: string;
    contextType: 'window' | 'dedicated-worker' | 'shared-worker' | 'service-worker' | 'iframe';
    instanceId: string;
    buildId: string;
  };

  target?: {
    contextId?: string;
    contextType?: string;
    role?: 'leader' | 'owner' | 'any';
  };

  causationId?: string;
  correlationId?: string;
  sequence?: number;
  issuedAt: number;
  expiresAt?: number;

  payload: TPayload;
};

Command has an owner.
Event has observers.
Query has a response.
Response has a correlationId.

{ type: 'REFRESH_TOKEN' }

{
  protocol: 'browser-orchestration/v1',
  id: crypto.randomUUID(),
  type: 'auth.tokenRefresh.request',
  kind: 'command',
  source: currentSource,
  target: { role: 'leader' },
  issuedAt: Date.now(),
  expiresAt: Date.now() + 10_000,
  payload: {
    reason: 'api-401',
    audience: 'main-api'
  }
}

iframe.contentWindow?.postMessage(message, '*');

iframe.contentWindow?.postMessage(message, 'https://trusted.example.com');

const allowedOrigins = new Set([
  'https://trusted.example.com',
  'https://checkout.example-payments.com'
]);

window.addEventListener('message', (event: MessageEvent) => {
  if (!allowedOrigins.has(event.origin)) {
    return;
  }

  const message = parseEnvelope(event.data);
  if (!message.ok) return;

  dispatch(message.value);
});

const trustedSource = iframe.contentWindow;

window.addEventListener('message', event => {
  if (event.origin !== 'https://trusted.example.com') return;
  if (event.source !== trustedSource) return;

  // safe enough to continue with schema validation
});

{
  type: 'payment.intent.authorized',
  payload: {
    paymentIntentId: 'pi_...',
    status: 'authorized'
  }
}

{
  type: 'payment.user.context',
  payload: {
    user,
    token,
    permissions,
    fullCart,
    fraudScore
  }
}

type WorkerCommand =
  | { type: 'job.start'; jobId: string; inputRef: string }
  | { type: 'job.cancel'; jobId: string }
  | { type: 'job.status.get'; jobId: string };

worker.postMessage(
  {
    type: 'image.process.request',
    jobId,
    buffer,
    options
  },
  [buffer]
);

Do not mix high-frequency control messages with unbounded data payloads without backpressure.

type RequestMap = {
  'math.sum': {
    request: { values: number[] };
    response: { total: number };
  };
  'text.tokenize': {
    request: { text: string };
    response: { tokens: string[] };
  };
};

type PendingRequest = {
  resolve: (value: unknown) => void;
  reject: (reason: unknown) => void;
  timeoutId: ReturnType<typeof setTimeout>;
};

class WorkerRpc<T extends Record<string, { request: unknown; response: unknown }>> {
  private pending = new Map<string, PendingRequest>();

  constructor(private readonly worker: Worker) {
    worker.addEventListener('message', event => this.onMessage(event.data));
    worker.addEventListener('error', event => {
      this.rejectAll(new Error(`Worker error: ${event.message}`));
    });
    worker.addEventListener('messageerror', () => {
      this.rejectAll(new Error('Worker message deserialization failed'));
    });
  }

  request<K extends keyof T & string>(
    type: K,
    payload: T[K]['request'],
    options: { timeoutMs?: number } = {}
  ): Promise<T[K]['response']> {
    const id = crypto.randomUUID();
    const timeoutMs = options.timeoutMs ?? 10_000;

    return new Promise((resolve, reject) => {
      const timeoutId = setTimeout(() => {
        this.pending.delete(id);
        reject(new Error(`Worker request timed out: ${type} ${id}`));
      }, timeoutMs);

      this.pending.set(id, { resolve, reject, timeoutId });

      this.worker.postMessage({
        protocol: 'worker-rpc/v1',
        id,
        type,
        kind: 'query',
        issuedAt: Date.now(),
        expiresAt: Date.now() + timeoutMs,
        payload
      });
    });
  }

  private onMessage(message: unknown): void {
    if (!isRpcResponse(message)) return;

    const pending = this.pending.get(message.correlationId);
    if (!pending) return;

    this.pending.delete(message.correlationId);
    clearTimeout(pending.timeoutId);

    if (message.kind === 'error') {
      pending.reject(new Error(message.payload.message));
    } else {
      pending.resolve(message.payload);
    }
  }

  private rejectAll(reason: unknown): void {
    for (const [id, pending] of this.pending) {
      clearTimeout(pending.timeoutId);
      pending.reject(reason);
      this.pending.delete(id);
    }
  }
}

function isRpcResponse(value: unknown): value is {
  protocol: 'worker-rpc/v1';
  kind: 'response' | 'error';
  correlationId: string;
  payload: any;
} {
  return typeof value === 'object'
    && value !== null
    && (value as any).protocol === 'worker-rpc/v1'
    && typeof (value as any).correlationId === 'string';
}

type Handler = (payload: any, message: any) => Promise<any> | any;

const handlers = new Map<string, Handler>();

handlers.set('math.sum', ({ values }) => {
  return { total: values.reduce((a: number, b: number) => a + b, 0) };
});

self.addEventListener('message', async event => {
  const message = event.data;

  if (!isRpcRequest(message)) return;
  if (message.expiresAt && Date.now() > message.expiresAt) {
    return;
  }

  const handler = handlers.get(message.type);

  if (!handler) {
    self.postMessage({
      protocol: 'worker-rpc/v1',
      id: crypto.randomUUID(),
      kind: 'error',
      type: `${message.type}.error`,
      correlationId: message.id,
      issuedAt: Date.now(),
      payload: { message: `No handler for ${message.type}` }
    });
    return;
  }

  try {
    const result = await handler(message.payload, message);

    self.postMessage({
      protocol: 'worker-rpc/v1',
      id: crypto.randomUUID(),
      kind: 'response',
      type: `${message.type}.response`,
      correlationId: message.id,
      issuedAt: Date.now(),
      payload: result
    });
  } catch (error) {
    self.postMessage({
      protocol: 'worker-rpc/v1',
      id: crypto.randomUUID(),
      kind: 'error',
      type: `${message.type}.error`,
      correlationId: message.id,
      issuedAt: Date.now(),
      payload: normalizeError(error)
    });
  }
});

function isRpcRequest(value: unknown): value is any {
  return typeof value === 'object'
    && value !== null
    && (value as any).protocol === 'worker-rpc/v1'
    && ((value as any).kind === 'query' || (value as any).kind === 'command')
    && typeof (value as any).id === 'string'
    && typeof (value as any).type === 'string';
}

function normalizeError(error: unknown): { name: string; message: string; stack?: string } {
  if (error instanceof Error) {
    return {
      name: error.name,
      message: error.message,
      stack: error.stack
    };
  }

  return {
    name: 'UnknownError',
    message: String(error)
  };
}

worker.addEventListener('message', event => {
  const message = event.data;
  runHandler(message.type, message.payload);
});

type ParseResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: string };

function parseEnvelope(value: unknown): ParseResult<ProtocolEnvelope<string, unknown>> {
  if (typeof value !== 'object' || value === null) {
    return { ok: false, reason: 'message-not-object' };
  }

  const raw = value as Record<string, unknown>;

  if (raw.protocol !== 'browser-orchestration/v1') {
    return { ok: false, reason: 'unsupported-protocol' };
  }

  if (typeof raw.id !== 'string') {
    return { ok: false, reason: 'missing-id' };
  }

  if (typeof raw.type !== 'string') {
    return { ok: false, reason: 'missing-type' };
  }

  if (typeof raw.issuedAt !== 'number') {
    return { ok: false, reason: 'missing-issued-at' };
  }

  if (typeof raw.expiresAt === 'number' && Date.now() > raw.expiresAt) {
    return { ok: false, reason: 'message-expired' };
  }

  return { ok: true, value: raw as ProtocolEnvelope<string, unknown> };
}

type StreamMessage<T> = ProtocolEnvelope<string, T> & {
  stream: {
    name: string;
    producerId: string;
    sequence: number;
  };
};

const lastSeen = new Map<string, number>();

function shouldAccept(message: StreamMessage<unknown>): boolean {
  const key = `${message.stream.name}:${message.stream.producerId}`;
  const previous = lastSeen.get(key) ?? 0;

  if (message.stream.sequence <= previous) {
    return false;
  }

  lastSeen.set(key, message.stream.sequence);
  return true;
}

Durable fact: IndexedDB event log
Fast signal: postMessage / BroadcastChannel

q = "a"     -> worker search request #1
q = "ab"    -> worker search request #2
q = "abc"   -> worker search request #3

let searchVersion = 0;

async function search(query: string) {
  const version = ++searchVersion;

  const result = await workerRpc.request('search.query', {
    query,
    version
  });

  if (version !== searchVersion) {
    return; // stale result
  }

  renderSearchResult(result);
}

{
  type: 'search.query',
  id,
  payload: {
    query,
    viewVersion
  }
}

Tab A sends command C1
Receiver processes C1
Response delayed
Tab A times out
Tab A retries C1
Receiver processes C1 again

Every command that can be retried must have idempotency key.

{
  id: 'message-123',
  type: 'offlineQueue.flush.request',
  kind: 'command',
  payload: {
    idempotencyKey: 'flush-cart-456-v3',
    queueName: 'cart-write-queue'
  }
}

const processed = new Set<string>();

async function handleCommand(message: any) {
  const key = message.payload.idempotencyKey ?? message.id;

  if (processed.has(key)) {
    return { status: 'duplicate-ignored' };
  }

  processed.add(key);
  return executeCommand(message.payload);
}

Worker failed

Worker request timed out waiting for response

worker.postMessage({
  protocol: 'worker-rpc/v1',
  id: crypto.randomUUID(),
  type: 'job.cancel',
  kind: 'command',
  correlationId: jobId,
  issuedAt: Date.now(),
  payload: { jobId }
});

const cancellations = new Set<string>();

handlers.set('job.cancel', ({ jobId }) => {
  cancellations.add(jobId);
  return { cancelled: true };
});

async function longRunningJob(jobId: string, chunks: Chunk[]) {
  for (const chunk of chunks) {
    if (cancellations.has(jobId)) {
      throw new Error(`Job cancelled: ${jobId}`);
    }

    processChunk(chunk);
    await yieldToEventLoop();
  }
}

function yieldToEventLoop() {
  return new Promise(resolve => setTimeout(resolve, 0));
}

for (const item of oneMillionItems) {
  worker.postMessage({ type: 'process.item', payload: item });
}

class BoundedWorkerClient {
  private inFlight = 0;
  private readonly queue: Array<() => void> = [];

  constructor(private readonly maxInFlight: number) {}

  async schedule<T>(task: () => Promise<T>): Promise<T> {
    if (this.inFlight >= this.maxInFlight) {
      await new Promise<void>(resolve => this.queue.push(resolve));
    }

    this.inFlight++;

    try {
      return await task();
    } finally {
      this.inFlight--;
      this.queue.shift()?.();
    }
  }
}

worker.postMessage({
  type: 'process.batch',
  payload: {
    batchId,
    items: items.slice(offset, offset + batchSize)
  }
});

type Unsubscribe = () => void;

type MessageTransport = {
  name: string;
  publish(message: ProtocolEnvelope<string, unknown>, transfer?: Transferable[]): void;
  subscribe(handler: (message: ProtocolEnvelope<string, unknown>) => void): Unsubscribe;
  close(): void;
};

function createWorkerTransport(worker: Worker): MessageTransport {
  const handlers = new Set<(message: ProtocolEnvelope<string, unknown>) => void>();

  const listener = (event: MessageEvent) => {
    const parsed = parseEnvelope(event.data);
    if (!parsed.ok) return;

    for (const handler of handlers) {
      handler(parsed.value);
    }
  };

  worker.addEventListener('message', listener);

  return {
    name: 'worker',

    publish(message, transfer = []) {
      worker.postMessage(message, transfer);
    },

    subscribe(handler) {
      handlers.add(handler);
      return () => handlers.delete(handler);
    },

    close() {
      worker.removeEventListener('message', listener);
      worker.terminate();
      handlers.clear();
    }
  };
}

function createWindowTransport(options: {
  targetWindow: Window;
  targetOrigin: string;
  allowedOrigin: string;
}): MessageTransport {
  const handlers = new Set<(message: ProtocolEnvelope<string, unknown>) => void>();

  const listener = (event: MessageEvent) => {
    if (event.origin !== options.allowedOrigin) return;

    const parsed = parseEnvelope(event.data);
    if (!parsed.ok) return;

    for (const handler of handlers) {
      handler(parsed.value);
    }
  };

  window.addEventListener('message', listener);

  return {
    name: 'window-postmessage',

    publish(message, transfer = []) {
      options.targetWindow.postMessage(message, options.targetOrigin, transfer);
    },

    subscribe(handler) {
      handlers.add(handler);
      return () => handlers.delete(handler);
    },

    close() {
      window.removeEventListener('message', listener);
      handlers.clear();
    }
  };
}

type MessageTrace = {
  ts: number;
  direction: 'in' | 'out';
  transport: string;
  id: string;
  type: string;
  kind: string;
  correlationId?: string;
  sourceContextId?: string;
  targetContextId?: string;
  payloadBytesEstimate?: number;
};

function withTracing(transport: MessageTransport, trace: (entry: MessageTrace) => void): MessageTransport {
  return {
    ...transport,

    publish(message, transfer) {
      trace({
        ts: performance.now(),
        direction: 'out',
        transport: transport.name,
        id: message.id,
        type: message.type,
        kind: message.kind,
        correlationId: message.correlationId,
        sourceContextId: message.source?.contextId,
        targetContextId: message.target?.contextId
      });

      transport.publish(message, transfer);
    },

    subscribe(handler) {
      return transport.subscribe(message => {
        trace({
          ts: performance.now(),
          direction: 'in',
          transport: transport.name,
          id: message.id,
          type: message.type,
          kind: message.kind,
          correlationId: message.correlationId,
          sourceContextId: message.source?.contextId,
          targetContextId: message.target?.contextId
        });

        handler(message);
      });
    }
  };
}

worker.postMessage(data);

otherWindow.postMessage(secret, '*');

{ type: 'message', payload: { action: '...' } }

worker.postMessage(new DomainAggregate(...));

postMessage = async transport
protocol envelope = semantic contract
correlation id = causality
idempotency key = retry safety
timeout = waiting policy
schema validation = boundary defense
durable store = source of truth
observability = ability to debug reality