@evolu/common 8.0.0-next.2 → 8.0.0-next.4

package/src/Worker.ts

@@ -1,16 +1,16 @@
 /**
- * Platform-agnostic Worker abstractions.
+ * Typed, disposable worker and messaging primitives.
  *
  * @module
  */
 
-import { assert } from "./Assert.js";
+import { assert, assertNotDisposed } from "./Assert.js";
 import type { Brand } from "./Brand.js";
 import type { ConsoleDep, ConsoleStoreOutputEntryDep } from "./Console.js";
 import { testWaitForMacrotask } from "./Test.js";
 
 /**
- * Platform-agnostic Worker.
+ * Typed, disposable Worker.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Worker
  */
@@ -20,7 +20,7 @@ export interface Worker<Input, Output = never> extends MessagePort<
 > {}
 
 /**
- * Platform-agnostic SharedWorker.
+ * Typed, disposable SharedWorker.
  *
  * A shared worker is shared across multiple clients (tabs, windows, iframes)
  * and provides a port for bidirectional communication with each client.
@@ -33,7 +33,7 @@ export interface SharedWorker<Input, Output = never> extends Disposable {
 }
 
 /**
- * Platform-agnostic MessagePort.
+ * Typed, disposable MessagePort.
  *
  * Note: There is no reliable way to detect when a port is closed or
  * disconnected. Calling `postMessage` on a disposed port does not throw — it
@@ -114,7 +114,7 @@ export type WorkerDeps = ConsoleDep &
   CreateMessagePortDep;
 
 /**
- * Platform-agnostic MessageChannel.
+ * Typed, disposable MessageChannel.
  *
  * Creates two entangled ports: keep one and transfer the other (e.g., to a
  * SharedWorker via `postMessage` with `transfer`). Messages sent to one port
@@ -178,6 +178,31 @@ export interface CreateMessageChannelDep {
   readonly createMessageChannel: CreateMessageChannel;
 }
 
+/**
+ * Typed, disposable BroadcastChannel.
+ *
+ * Broadcast channels deliver messages to other channels opened with the same
+ * name. The sending channel does not receive its own messages.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
+ */
+export interface BroadcastChannel<Input, Output = Input> extends Disposable {
+  /** Posts a message to other channels with the same name. */
+  readonly postMessage: (message: Input) => void;
+
+  /** Handler for incoming broadcast messages. */
+  onMessage: ((message: Output) => void) | null;
+}
+
+/** Factory function to create a {@link BroadcastChannel}. */
+export type CreateBroadcastChannel = <Input, Output = Input>(
+  name: string,
+) => BroadcastChannel<Input, Output>;
+
+export interface CreateBroadcastChannelDep {
+  readonly createBroadcastChannel: CreateBroadcastChannel;
+}
+
 /**
  * Typed `self` for code running inside a dedicated worker.
  *
@@ -250,29 +275,46 @@ export const createMessageChannel: CreateMessageChannel = <
     handler: null,
     queue: [],
     flushScheduled: false,
+    flushTimeoutId: null,
+    ownerCount: 0,
+    pendingTransferCount: 0,
   };
   const state2: PortState<Input> = {
     handler: null,
     queue: [],
     flushScheduled: false,
+    flushTimeoutId: null,
+    ownerCount: 0,
+    pendingTransferCount: 0,
   };
 
   const native1 = createNativeMessagePortToken<Input, Output>();
   const native2 = createNativeMessagePortToken<Output, Input>();
 
-  const port1 = createTestPort<Input, Output>(state1, state2, native1);
-  const port2 = createTestPort<Output, Input>(state2, state1, native2);
+  const port1Registration: PortRegistration<Input, Output> = {
+    receive: state1,
+    peerReceive: state2,
+    native: native1,
+  };
+  const port2Registration: PortRegistration<Output, Input> = {
+    receive: state2,
+    peerReceive: state1,
+    native: native2,
+  };
+
+  using disposer = new DisposableStack();
 
-  nativePortRegistry.set(native1, port1);
-  nativePortRegistry.set(native2, port2);
+  const port1 = disposer.use(createTestPort(port1Registration));
+  const port2 = disposer.use(createTestPort(port2Registration));
+  const disposables = disposer.move();
+
+  nativePortRegistry.set(native1, port1Registration);
+  nativePortRegistry.set(native2, port2Registration);
 
   return {
     port1,
     port2,
-    [Symbol.dispose]: () => {
-      port1[Symbol.dispose]();
-      port2[Symbol.dispose]();
-    },
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
@@ -285,11 +327,80 @@ export const createMessageChannel: CreateMessageChannel = <
 export const createMessagePort: CreateMessagePort = <Input, Output = never>(
   nativePort: NativeMessagePort<Input, Output>,
 ): MessagePort<Input, Output> => {
-  const pair = nativePortRegistry.get(nativePort);
-  assert(pair, "Unknown native port — did you transfer it?");
-  return pair as MessagePort<Input, Output>;
+  const registration = nativePortRegistry.get(nativePort);
+  assert(registration, "Unknown native port — did you transfer it?");
+  return createTestPort(registration as PortRegistration<Input, Output>);
+};
+
+/**
+ * Creates an in-memory {@link BroadcastChannel}.
+ *
+ * This is a memory-only fallback for platforms without native BroadcastChannel
+ * support. Message delivery is asynchronous in-process.
+ */
+export const createBroadcastChannel: CreateBroadcastChannel = <
+  Input,
+  Output = Input,
+>(
+  name: string,
+): BroadcastChannel<Input, Output> => {
+  let onMessageHandler: ((message: Output) => void) | null = null;
+  const dispatch: BroadcastChannelDispatch<Output> = (message) => {
+    onMessageHandler?.(message);
+  };
+
+  let dispatches = broadcastChannelDispatchesByName.get(name);
+  if (!dispatches) {
+    dispatches = new Set();
+    broadcastChannelDispatchesByName.set(name, dispatches);
+  }
+  dispatches.add(dispatch as BroadcastChannelDispatch<any>);
+
+  using disposer = new DisposableStack();
+
+  disposer.defer(() => {
+    onMessageHandler = null;
+
+    dispatches.delete(dispatch as BroadcastChannelDispatch<any>);
+    if (dispatches.size === 0) broadcastChannelDispatchesByName.delete(name);
+  });
+
+  const disposables = disposer.move();
+
+  return {
+    postMessage: (message) => {
+      assertNotDisposed(disposables);
+
+      const dispatches = broadcastChannelDispatchesByName.get(name);
+      assert(dispatches, "Expected broadcast channel dispatches");
+
+      for (const otherDispatch of [...dispatches]) {
+        if (otherDispatch === dispatch) continue;
+
+        globalThis.setTimeout(() => {
+          if (!dispatches.has(otherDispatch)) return;
+          otherDispatch(message);
+        }, 0);
+      }
+    },
+    get onMessage() {
+      return disposables.disposed ? null : onMessageHandler;
+    },
+    set onMessage(fn) {
+      if (disposables.disposed) return;
+      onMessageHandler = fn;
+    },
+    [Symbol.dispose]: () => disposables.dispose(),
+  };
 };
 
+type BroadcastChannelDispatch<T> = (message: T) => void;
+
+const broadcastChannelDispatchesByName = new Map<
+  string,
+  Set<BroadcastChannelDispatch<any>>
+>();
+
 /**
  * Test {@link Worker} with access to its paired worker-side `self`.
  *
@@ -325,6 +436,14 @@ export interface TestMessageChannel<
   readonly isDisposed: () => boolean;
 }
 
+/** {@link BroadcastChannel} with disposal tracking for testing. */
+export interface TestBroadcastChannel<
+  Input,
+  Output = Input,
+> extends BroadcastChannel<Input, Output> {
+  readonly isDisposed: () => boolean;
+}
+
 /**
  * Creates a connected {@link TestWorker} for testing.
  *
@@ -341,7 +460,7 @@ export const testCreateWorker = <Input, Output = never>(): TestWorker<
     self = nextSelf;
   });
 
-  return Object.assign(worker, { self }) as TestWorker<Input, Output>;
+  return Object.assign(worker, { self });
 };
 
 /**
@@ -361,7 +480,7 @@ export const testCreateSharedWorker = <
   return Object.assign(worker, {
     self,
     connect,
-  }) as TestSharedWorker<Input, Output>;
+  });
 };
 
 /**
@@ -377,18 +496,16 @@ export const testCreateMessageChannel = <
   Input,
   Output = never,
 >(): TestMessageChannel<Input, Output> => {
-  const channel = createMessageChannel<Input, Output>();
+  using disposer = new DisposableStack();
 
-  let disposed = false;
+  const channel = disposer.use(createMessageChannel<Input, Output>());
+  const disposables = disposer.move();
 
   return {
     port1: channel.port1,
     port2: channel.port2,
-    isDisposed: () => disposed,
-    [Symbol.dispose]: () => {
-      disposed = true;
-      channel[Symbol.dispose]();
-    },
+    isDisposed: () => disposables.disposed,
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
@@ -397,11 +514,35 @@ export const testCreateMessagePort: CreateMessagePort = <Input, Output = never>(
   nativePort: NativeMessagePort<Input, Output>,
 ): MessagePort<Input, Output> => createMessagePort(nativePort);
 
+/** Creates an in-memory {@link BroadcastChannel} for testing. */
+export const testCreateBroadcastChannel = <Input, Output = Input>(
+  name: string,
+): TestBroadcastChannel<Input, Output> => {
+  using disposer = new DisposableStack();
+
+  const channel = disposer.use(createBroadcastChannel<Input, Output>(name));
+  const disposables = disposer.move();
+
+  return {
+    postMessage: channel.postMessage,
+    get onMessage() {
+      return channel.onMessage;
+    },
+    set onMessage(value) {
+      channel.onMessage = value;
+    },
+    isDisposed: () => disposables.disposed,
+    [Symbol.dispose]: () => disposables.dispose(),
+  };
+};
+
 /**
- * Waits long enough for multi-hop in-memory worker message delivery in tests.
+ * Waits the minimal time necessary for in-memory worker message delivery in
+ * tests.
  *
- * Some flows require several queued macrotasks across worker/message-port
- * boundaries; this helper advances that pipeline deterministically.
+ * This is better than `vi.waitFor` when a test only needs to flush the known
+ * in-memory worker/message-port pipeline. It encodes that transport boundary
+ * once, avoids polling, and keeps worker-focused tests fast and explicit.
  */
 export const testWaitForWorkerMessage = async (): Promise<void> => {
   await testWaitForMacrotask();
@@ -481,55 +622,105 @@ interface PortState<T> {
   handler: ((message: T) => void) | null;
   readonly queue: Array<T>;
   flushScheduled: boolean;
+  flushTimeoutId: ReturnType<typeof globalThis.setTimeout> | null;
+  ownerCount: number;
+  pendingTransferCount: number;
 }
 
-const createPort = <Input, Output>(
-  receive: PortState<Output>,
-  peerReceive: PortState<Input>,
-  native: NativeMessagePort<Input, Output>,
-): MessagePort<Input, Output> => {
+interface PortRegistration<Input, Output> {
+  readonly receive: PortState<Output>;
+  readonly peerReceive: PortState<Input>;
+  readonly native: NativeMessagePort<Input, Output>;
+}
+
+const createPort = <Input, Output>({
+  receive,
+  peerReceive,
+  native,
+}: PortRegistration<Input, Output>): MessagePort<Input, Output> => {
+  using disposer = new DisposableStack();
+
+  if (receive.pendingTransferCount > 0) receive.pendingTransferCount -= 1;
+  else receive.ownerCount += 1;
+
+  disposer.defer(() => {
+    receive.ownerCount -= 1;
+    if (receive.ownerCount > 0) return;
+
+    nativePortRegistry.delete(native);
+
+    if (receive.flushTimeoutId != null) {
+      globalThis.clearTimeout(receive.flushTimeoutId);
+      receive.flushTimeoutId = null;
+    }
+
+    receive.handler = null;
+    receive.flushScheduled = false;
+    receive.queue.length = 0;
+  });
+
+  const disposables = disposer.move();
+
   const scheduleFlush = (state: PortState<any>): void => {
-    if (state.flushScheduled) return;
+    if (state.flushScheduled || state.ownerCount === 0) return;
     state.flushScheduled = true;
 
     // Native worker messages are task-queued; use macrotask timing.
-    setTimeout(() => {
+    state.flushTimeoutId = globalThis.setTimeout(() => {
+      state.flushTimeoutId = null;
       state.flushScheduled = false;
+      if (state.ownerCount === 0) return;
 
-      const handler = state.handler;
-      if (!handler) return;
+      const firstHandler = state.handler;
+      if (!firstHandler) return;
 
       for (const message of state.queue.splice(0)) {
+        const handler = state.handler;
+        if (!handler) return;
+
         handler(message);
       }
     }, 0);
   };
 
   return {
-    postMessage: (message) => {
+    postMessage: (message, transfer) => {
+      if (
+        disposables.disposed ||
+        receive.ownerCount === 0 ||
+        peerReceive.ownerCount === 0
+      )
+        return;
+
+      for (const transferable of transfer ?? []) {
+        if (transferable instanceof globalThis.ArrayBuffer) continue;
+
+        const registration = nativePortRegistry.get(transferable);
+        if (!registration) continue;
+
+        registration.receive.ownerCount += 1;
+        registration.receive.pendingTransferCount += 1;
+      }
+
       peerReceive.queue.push(message);
       scheduleFlush(peerReceive);
     },
     get onMessage() {
-      return receive.handler;
+      return disposables.disposed ? null : receive.handler;
     },
     set onMessage(fn) {
+      if (disposables.disposed || receive.ownerCount === 0) return;
       receive.handler = fn;
       if (fn) scheduleFlush(receive);
     },
     native,
-    [Symbol.dispose]: () => {
-      receive.handler = null;
-      receive.flushScheduled = false;
-    },
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
 const createTestPort = <Input, Output>(
-  receive: PortState<Output>,
-  peerReceive: PortState<Input>,
-  native: NativeMessagePort<Input, Output>,
-): MessagePort<Input, Output> => createPort(receive, peerReceive, native);
+  registration: PortRegistration<Input, Output>,
+): MessagePort<Input, Output> => createPort(registration);
 
 const createNativeMessagePortToken = <Input, Output>(): NativeMessagePort<
   Input,
@@ -548,5 +739,5 @@ const createNativeMessagePortToken = <Input, Output>(): NativeMessagePort<
  */
 const nativePortRegistry = new WeakMap<
   NativeMessagePort<any, any>,
-  MessagePort<any, any>
+  PortRegistration<any, any>
 >();

package/src/index.ts

@@ -17,6 +17,7 @@ export * from "./Eq.js";
 export * from "./Error.js";
 export * from "./Function.js";
 export * from "./Identicon.js";
+export * from "./LockManager.js";
 export * from "./Lookup.js";
 export * from "./Microtask.js";
 export * from "./Number.js";

package/src/local-first/Db.ts

@@ -18,6 +18,8 @@ import {
   type RandomBytesDep,
 } from "../Crypto.js";
 import { exhaustiveCheck, lazyFalse, lazyVoid } from "../Function.js";
+import type { LockManagerDep } from "../LockManager.js";
+import { acquireLeaderLock } from "../LockManager.js";
 import { createRecord, getProperty, objectToEntries } from "../Object.js";
 import { ok, type Result } from "../Result.js";
 import type {
@@ -35,7 +37,7 @@ import {
   sqliteQueryStringToSqliteQuery,
   SqliteValue,
 } from "../Sqlite.js";
-import { callback, type LeaderLockDep, type Task } from "../Task.js";
+import { callback, type Task } from "../Task.js";
 import { Millis, millisToDateIso, type TimeDep } from "../Time.js";
 import type { Name } from "../Type.js";
 import {
@@ -47,6 +49,7 @@ import {
 } from "../Type.js";
 import type { ExtractType } from "../Types.js";
 import type {
+  CreateBroadcastChannelDep,
   NativeMessagePort,
   Worker,
   WorkerDeps,
@@ -72,7 +75,14 @@ import {
   getEvoluSqliteSchema,
   systemColumns,
 } from "./Schema.js";
-import type { DbWorkerInput, DbWorkerOutput } from "./Shared.js";
+import type {
+  ConsoleEntryOrError,
+  DbWorkerInput,
+  DbWorkerOutput,
+  DbWorkerQueuedResponse,
+  DbWorkerRequest,
+} from "./Shared.js";
+import { consoleEntryOrErrorBroadcastChannelName } from "./Shared.js";
 import {
   createBaseSqliteStorage,
   createBaseSqliteStorageTables,
@@ -105,7 +115,7 @@ import {
 export type DbWorker = Worker<DbWorkerInit>;
 
 export interface DbWorkerInit {
-  readonly type: "Init";
+  readonly type: "DbWorkerInit";
   readonly name: Name;
   readonly consoleLevel: ConsoleLevel;
   readonly sqliteSchema: SqliteSchema;
@@ -120,18 +130,22 @@ export interface CreateDbWorkerDep {
   readonly createDbWorker: CreateDbWorker;
 }
 
-export type DbWorkerDeps = WorkerDeps & LeaderLockDep & CreateSqliteDriverDep;
+export type DbWorkerDeps = WorkerDeps &
+  CreateBroadcastChannelDep &
+  LockManagerDep &
+  CreateSqliteDriverDep;
 
 export const startDbWorker =
   (self: WorkerSelf<DbWorkerInit>): Task<void, never, DbWorkerDeps> =>
-  async (_run) => {
-    await using stack = new AsyncDisposableStack();
-    const run = stack.use(_run.create());
-    const { deps } = run;
+  async (run) => {
+    await using disposer = new AsyncDisposableStack();
+    disposer.use(self);
+    const dbWorkerRun = disposer.use(run.create());
+    const { deps } = dbWorkerRun;
 
     let initialized = false;
 
-    const initMessage = await run.orThrow(
+    const initMessage = await dbWorkerRun.orThrow(
       callback<DbWorkerInit>(({ ok }) => {
         self.onMessage = (message) => {
           assert(!initialized, "DbWorker must be initialized only once");
@@ -143,26 +157,36 @@ export const startDbWorker =
 
     const console = deps.console.child(initMessage.name).child("DbWorker");
     console.setLevel(initMessage.consoleLevel);
-    console.info("start DbWorker");
 
-    const port = stack.use(
+    const port = disposer.use(
       deps.createMessagePort<DbWorkerOutput, DbWorkerInput>(initMessage.port),
     );
+    const consoleEntryOrErrorBroadcastChannel = disposer.use(
+      deps.createBroadcastChannel<ConsoleEntryOrError>(
+        consoleEntryOrErrorBroadcastChannelName,
+      ),
+    );
 
-    stack.defer(
+    disposer.defer(
       deps.consoleStoreOutputEntry.subscribe(() => {
         const entry = deps.consoleStoreOutputEntry.get();
-        if (entry) port.postMessage({ type: "OnConsoleEntry", entry });
+        if (entry)
+          consoleEntryOrErrorBroadcastChannel.postMessage({
+            type: "ConsoleEntry",
+            entry,
+          });
       }),
     );
+    console.debug("createDbWorker");
 
-    stack.use(await run.orThrow(deps.leaderLock.lock(initMessage.name)));
-    if (stack.disposed) return ok();
+    disposer.use(
+      await dbWorkerRun.orThrow(acquireLeaderLock(initMessage.name)),
+    );
 
     port.postMessage({ type: "LeaderAcquired", name: initMessage.name });
 
-    const sqlite = stack.use(
-      await run.orThrow(
+    const sqlite = disposer.use(
+      await dbWorkerRun.orThrow(
         createSqlite(
           initMessage.name,
           initMessage.memoryOnly
@@ -173,10 +197,13 @@ export const startDbWorker =
     );
     console.debug("SQLite created");
 
-    const baseSqliteStorage = createBaseSqliteStorage({ sqlite, ...run.deps });
+    const baseSqliteStorage = createBaseSqliteStorage({
+      sqlite,
+      ...dbWorkerRun.deps,
+    });
 
     const dbDeps = {
-      ...run.deps,
+      ...dbWorkerRun.deps,
       sqlite,
       sqliteSchema: initMessage.sqliteSchema,
       baseSqliteStorage,
@@ -195,33 +222,26 @@ export const startDbWorker =
 
     const storage = createClientStorage({ ...dbDeps, clock })({
       onError: (error) => {
-        port.postMessage({ type: "OnError", error });
+        consoleEntryOrErrorBroadcastChannel.postMessage({
+          type: "Error",
+          error,
+        });
       },
     });
 
-    // TODO: Call on dispose message.
-    const _moved = stack.move();
-    const runWithStorage = run.addDeps({ storage });
+    const disposables = disposer.move();
+    const dbWorkerRunWithStorage = dbWorkerRun.addDeps({ storage });
 
-    /**
-     * SharedWorker retries until some leader replies, so this worker must
-     * ignore callback IDs it already completed.
-     *
-     * The Set intentionally lives for one leader's lifetime. If that leader tab
-     * closes, retries go to a new leader with a fresh Set. Revisit this only if
-     * memory pressure shows up; even millions of short callback IDs are
-     * acceptable here, and naive eviction could let a still-retried request run
-     * again.
-     */
-    const processedRequestIds = new Set<Id>();
+    port.onMessage = (input) => {
+      if (input.type === "Dispose") {
+        if (!disposables.disposed) console.debug("disposeDbWorker");
+        void disposables.disposeAsync();
+        return;
+      }
 
-    port.onMessage = ({ callbackId, request }) => {
-      if (processedRequestIds.has(callbackId)) return;
-      processedRequestIds.add(callbackId);
+      const { callbackId, request } = input;
 
-      const postQueuedResponse = (
-        response: ExtractType<DbWorkerOutput, "OnQueuedResponse">["response"],
-      ): void => {
+      const postQueuedResponse = (response: DbWorkerQueuedResponse): void => {
         port.postMessage(
           { type: "OnQueuedResponse", callbackId, response },
           response.type === "ForEvolu" && response.message.type === "Export"
@@ -238,11 +258,14 @@ export const startDbWorker =
                 request.message,
               );
               if (!result.ok) {
-                port.postMessage({ type: "OnError", error: result.error });
+                consoleEntryOrErrorBroadcastChannel.postMessage({
+                  type: "Error",
+                  error: result.error,
+                });
               } else {
                 postQueuedResponse({
                   type: "ForEvolu",
-                  evoluPortId: request.evoluPortId,
+                  id: request.id,
                   message: result.value,
                 });
               }
@@ -252,7 +275,7 @@ export const startDbWorker =
             case "Query":
               postQueuedResponse({
                 type: "ForEvolu",
-                evoluPortId: request.evoluPortId,
+                id: request.id,
                 message: {
                   type: "Query",
                   rowsByQuery: loadQueries(dbDeps)(request.message.queries),
@@ -263,7 +286,7 @@ export const startDbWorker =
             case "Export":
               postQueuedResponse({
                 type: "ForEvolu",
-                evoluPortId: request.evoluPortId,
+                id: request.id,
                 message: {
                   type: "Export",
                   file: dbDeps.sqlite.export(),
@@ -307,7 +330,7 @@ export const startDbWorker =
             case "ApplySyncMessage": {
               const { owner, inputMessage } = request.message;
 
-              runWithStorage<void, never>(async (run) => {
+              dbWorkerRunWithStorage<void, never>(async (run) => {
                 storage.setRequestContext(owner.encryptionKey);
 
                 const result = await run(
@@ -777,7 +800,7 @@ const handleMutation =
   ) =>
   (
     message: ExtractType<
-      ExtractType<DbWorkerInput["request"], "ForEvolu">["message"],
+      ExtractType<DbWorkerRequest, "ForEvolu">["message"],
       "Mutate"
     >,
   ): Result<