coincident

If you cannot use special headers or a ServiceWorker, coincident defaults to a SharedArrayBuffer polyfill that only supports asynchronous notifications.

This mode is ideal when:

• No special headers or ServiceWorkers are allowed.
• You only need to await asynchronous utilities from a Worker.
• You never need to reach or execute code on the main thread from a Worker.
• Your Worker never receives a main thread reference as an argument.

Coincident uses an Atomics-based Proxy to synchronize tasks between the main thread and Workers.

1. On the Main Thread: You use coincident/main to create a Worker instance. This instance provides a proxy where you can assign callbacks (e.g., proxy.location = () => location.href) that the Worker can then invoke.
2. On the Worker Thread: You use coincident/worker to access the proxy. This proxy allows you to call functions exposed by the main thread. If native is true (meaning SharedArrayBuffer is supported), these calls can be synchronous.
3. Data Transfer: Use the transfer utility at the end of proxied function calls to move ArrayBuffers directly via postMessage for better performance.

Deadlocks can occur when a Worker invokes a synchronous utility on the Main thread using Atomics.wait, and that Main utility subsequently tries to invoke a synchronous utility on that same Worker.

Best Practice: Do not invoke utilities from the other world while one of your own exported utilities is currently executing. If you must, execute the foreign utility on the next tick, micro-task, timeout, or idle state.

To enable synchronous Atomics and full SharedArrayBuffer capabilities, you must ensure your server provides the necessary security headers.

Ways to enable SAB:

1. Server Headers: Configure your server to provide the required COI headers (e.g., using npx mini-coi ./ for local testing).
2. ServiceWorker Bootstrap: Include <script src="./mini-coi.js"></script> at the top of your <head> to use a ServiceWorker that forces these headers for all requests.
3. Coincident ServiceWorker: Pass a ServiceWorker file to the coincident constructor via the serviceWorker option (e.g., npx coincident ./public/sw.js) to polyfill the synchronous case.

Every property access via the window reference involves a Worker ↔ Main thread roundtrip. To avoid performance degradation, especially when using a SharedArrayBuffer polyfill, manually cache references that you know will not change.

Performance Note:

• With SharedArrayBuffer polyfill: ~1,000 roundtrips/sec.
• With native SharedArrayBuffer: ~50,000 roundtrips/sec.

const { window } = await coincident();

// Instead of accessing window.document.body repeatedly:
const { document } = window;
const { head, body } = document;

// Use the cached reference
body.textContent = 'Hello World 👋';

If header issues prevent SharedArrayBuffer from working (e.g., in iframes), you can use a ServiceWorker-based fallback that intercepts synchronous xhr calls.

Setup:

1. Generate the fallback file: npx coincident ./sw.js.
2. Initialize coincident with the generated file: { serviceWorker: './sw.js' }.

Note: This method is slower and may face rate-limiting or kill-switch issues on iOS devices.

// Initialization with XHR fallback
const { Worker } = await coincident({ serviceWorker: './sw.js' });

When your Worker code requires references to both the main window and the server, use coincident/server/main on the main thread. Unlike the standard window variant, you must provide the WebSocket ws URL during initialization.

import coincident from 'coincident/server/main';

const { Worker, polyfill, transfer } = coincident({
  ws: 'ws://localhost:8080/'
});

On the Worker side, importing coincident/server/worker provides a namespace that includes utilities to interact with the server. After bootstrap, the returned object contains a server proxy (a synchronous, Atomics.wait based proxy to the server's globalThis) and an isServerProxy helper.

It also provides an ffi (Foreign Function Interface) namespace for calling methods on both window and server.

import coincident from 'coincident/server/worker';

const {
  proxy, native, transfer,
  window, isWindowProxy,
  server,
  isServerProxy,
  ffi: {
    assign, gather, query, evaluate,
    window: { ... },
    server: { ... },
  }
} = await coincident();

// Direct synchronous access to the server
server.console.log('Hello World 👋');

// Example of module import on the server
const os = await server.import('os');
console.log(os.platform());

Use coincident/server to instrument connected WebSockets in Node.js, Bun, or other environments. This allows a Worker to drive both the main thread and the running server.

Warning: This feature enables a Worker to potentially take over the server; it is intended primarily for Kiosk or IoT projects and should not be exposed to untrusted public code.

// Bun example
import coincident from 'coincident/server';

serve({
  port,
  fetch,
  websocket: coincident({ bun: true })
});

// NodeJS with `ws` module
import { WebSocketServer } from 'ws';
import coincident from 'coincident/server';

const server = ...;
coincident({
  wss: new WebSocketServer({ server })
});

To use Coincident within a Worker, import coincident from coincident/worker. This provides a proxy to invoke main-thread utilities (sync or async) and a direct method to transfer values as-is. You can configure minByteLength and maxByteLength for SharedArrayBuffer usage.

import coincident from 'coincident/worker';

const {
  // proxy to invoke main thread utilities
  proxy: Proxy,
  // true if SharedArrayBuffer and sync operations are usable
  native: boolean,
  // utility to transfer buffers directly via `postMessage`
  transfer: (...buffers: ArrayBuffer[]) => buffers,
  // a way to directly transfer a value as it is
  direct: value => value,
} = await coincident({
  transform: value => any,
  decoder: reflectedFFIDirectDecoder,
  transfer: boolean,
  minByteLength: 0x7FFF,
  maxByteLength: 0x1000000,
});

If a Worker needs to operate directly on the main thread's DOM or window object, use coincident/window/worker. This provides a window proxy that allows synchronous access to the main thread's globalThis using Atomics.wait.

import coincident from 'coincident/window/worker';

const {
  proxy,
  native,
  transfer,
  // synchronous, Atomic.wait based Proxy to the main thread's globalThis
  window,
  // returns true if the reference points to the main thread
  isWindowProxy,
} = await coincident();

// Direct synchronous access
console.log(window.location.href);
window.document.body.textContent = 'Hello World 👋';