@evolu/common 8.0.0-next.5 → 8.0.0

package/src/Worker.ts

@@ -4,10 +4,10 @@
  * @module
  */
 
-import { assert, assertNotDisposed } from "./Assert.js";
-import type { Brand } from "./Brand.js";
-import type { ConsoleDep, ConsoleStoreOutputEntryDep } from "./Console.js";
-import { testWaitForMacrotask } from "./Test.js";
+import { assert } from "./Assert.ts";
+import type { Brand } from "./Brand.ts";
+import type { ConsoleDep, ConsoleStoreOutputEntryDep } from "./Console.ts";
+import { disposable } from "./Function.ts";
 
 /**
  * Typed, disposable Worker.
@@ -60,13 +60,28 @@ export interface MessagePort<Input, Output = never> extends Disposable {
   /**
    * The native underlying port for transferring via `postMessage`.
    *
-   * ### Example
+   * Prepare a port for transfer:
    *
    * ```ts
-   * sharedWorker.port.postMessage(
-   *   { type: "InitConsole", port: consoleChannel.port1.native },
-   *   [consoleChannel.port1.native],
-   * );
+   * import {
+   *   createMessageChannel,
+   *   type NativeMessagePort,
+   * } from "@evolu/common";
+   *
+   * interface ConsoleMessage {
+   *   readonly type: "ConsoleEntry";
+   *   readonly text: string;
+   * }
+   *
+   * using consoleChannel = createMessageChannel<ConsoleMessage>();
+   * const init = {
+   *   type: "InitConsole",
+   *   port: consoleChannel.port1.native,
+   * };
+   *
+   * expectTypeOf(init.port).toEqualTypeOf<
+   *   NativeMessagePort<ConsoleMessage>
+   * >();
    * ```
    */
   readonly native: NativeMessagePort<Input, Output>;
@@ -126,36 +141,80 @@ export type WorkerDeps = ConsoleDep &
  *
  * For one-way communication, omit `Output` (defaults to `never`).
  *
- * ### Example
- *
- * Transfer a channel port to a SharedWorker for async initialization:
+ * Transfer a channel port to a SharedWorker and use the retained port
+ * immediately:
  *
  * ```ts
- * // Main thread: create channel, transfer port1, use port2 immediately.
- * const channel = createMessageChannel<EvoluRequest, EvoluResponse>();
- *
- * sharedWorker.port.postMessage(
- *   { type: "CreateEvolu", port: channel.port1.native },
- *   [channel.port1.native],
- * );
- *
- * // Safe to send immediately — messages queue until worker is ready.
- * channel.port2.postMessage({ type: "Query", query });
- * channel.port2.onMessage = (response) => {
- *   handleResponse(response);
- * };
+ * import {
+ *   createMessageChannel,
+ *   createMessagePort,
+ *   createSharedWorker,
+ *   type NativeMessagePort,
+ * } from "@evolu/common";
+ *
+ * interface Query {
+ *   readonly text: string;
+ * }
+ * interface QueryResult {
+ *   readonly rows: ReadonlyArray<string>;
+ * }
+ * interface ConnectToEvolu {
+ *   readonly port: NativeMessagePort<QueryResult, Query>;
+ * }
+ *
+ * const response = Promise.withResolvers<QueryResult>();
+ * using sharedWorker = createSharedWorker<ConnectToEvolu>((self) => {
+ *   self.onConnect = (controlPort) => {
+ *     controlPort.onMessage = ({ port }) => {
+ *       const workerQueries = createMessagePort<QueryResult, Query>(port);
+ *       workerQueries.onMessage = (query) => {
+ *         workerQueries.postMessage({ rows: [query.text] });
+ *         workerQueries[Symbol.dispose]();
+ *       };
+ *     };
+ *   };
+ * });
+ * using queryChannel = createMessageChannel<Query, QueryResult>();
+ * queryChannel.port1.onMessage = response.resolve;
+ *
+ * // The main thread retains port1 and transfers the worker-facing port2.
+ * sharedWorker.port.postMessage({ port: queryChannel.port2.native }, [
+ *   queryChannel.port2.native,
+ * ]);
+ * queryChannel.port1.postMessage({ text: "all todos" });
+ *
+ * expect(await response.promise).toEqual({ rows: ["all todos"] });
  * ```
  *
+ * On the worker side, attach the handler after asynchronous initialization;
+ * messages sent earlier remain queued:
+ *
  * ```ts
- * // Worker: receive the port, do async init, then start listening.
- * const evoluPort = createMessagePort<EvoluResponse, EvoluRequest>(
- *   message.port,
- * );
- * await openDatabase(name);
- * evoluPort.onMessage = (request) => {
- *   handleRequest(request);
+ * import { createMessageChannel, createMessagePort } from "@evolu/common";
+ *
+ * interface Query {
+ *   readonly text: string;
+ * }
+ *
+ * using channel = createMessageChannel<Query>();
+ * using workerPort = createMessagePort<never, Query>(channel.port2.native);
+ * const received: Array<Query> = [];
+ * const allReceived = Promise.withResolvers<void>();
+ * // The main thread can send several messages while the worker initializes.
+ * channel.port1.postMessage({ text: "all todos" });
+ * channel.port1.postMessage({ text: "completed todos" });
+ *
+ * await Promise.resolve();
+ * workerPort.onMessage = (query) => {
+ *   received.push(query);
+ *   if (received.length === 2) allReceived.resolve();
  * };
- * // Queued messages are now delivered in order.
+ * await allReceived.promise;
+ *
+ * expect(received).toEqual([
+ *   { text: "all todos" },
+ *   { text: "completed todos" },
+ * ]);
  * ```
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/MessageChannel
@@ -357,41 +416,41 @@ export const createBroadcastChannel: CreateBroadcastChannel = <
   dispatches.add(dispatch as BroadcastChannelDispatch<any>);
 
   using disposer = new DisposableStack();
+  let disposed = false;
 
   disposer.defer(() => {
+    disposed = true;
     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;
+  return disposable<BroadcastChannel<Input, Output>>(
+    {
+      postMessage: (message) => {
+        const dispatches = broadcastChannelDispatchesByName.get(name);
+        assert(dispatches, "Expected broadcast channel dispatches");
+
+        for (const otherDispatch of [...dispatches]) {
+          if (otherDispatch === dispatch) continue;
+
+          scheduleWorkerTask(() => {
+            if (!dispatches.has(otherDispatch)) return;
+            otherDispatch(message);
+          });
+        }
+      },
+      get onMessage() {
+        return disposed ? null : onMessageHandler;
+      },
+      set onMessage(fn) {
+        if (disposed) return;
+        onMessageHandler = fn;
+      },
     },
-    set onMessage(fn) {
-      if (disposables.disposed) return;
-      onMessageHandler = fn;
-    },
-    [Symbol.dispose]: () => disposables.dispose(),
-  };
+    disposer,
+  );
 };
 
 type BroadcastChannelDispatch<T> = (message: T) => void;
@@ -537,17 +596,17 @@ export const testCreateBroadcastChannel = <Input, Output = Input>(
 };
 
 /**
- * Waits the minimal time necessary for in-memory worker message delivery in
- * tests.
+ * Waits until scheduled in-memory worker message delivery becomes idle.
  *
- * 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.
+ * This observes actual transport tasks instead of waiting for an arbitrary
+ * duration. It also waits through message handlers that schedule more worker
+ * tasks before the current microtask checkpoint completes.
  */
-export const testWaitForWorkerMessage = async (): Promise<void> => {
-  await testWaitForMacrotask();
-  await testWaitForMacrotask();
-};
+export const testWaitForWorkerMessage = (): Promise<void> =>
+  new Promise((resolve) => {
+    workerTaskIdleWaiters.add(resolve);
+    notifyWorkerTaskIdle();
+  });
 
 const createMemoryWorkerPair = <Input, Output = never>(): {
   readonly worker: Worker<Input, Output>;
@@ -650,7 +709,7 @@ const createPort = <Input, Output>({
     nativePortRegistry.delete(native);
 
     if (receive.flushTimeoutId != null) {
-      globalThis.clearTimeout(receive.flushTimeoutId);
+      cancelWorkerTask(receive.flushTimeoutId);
       receive.flushTimeoutId = null;
     }
 
@@ -665,8 +724,7 @@ const createPort = <Input, Output>({
     if (state.flushScheduled || state.ownerCount === 0) return;
     state.flushScheduled = true;
 
-    // Native worker messages are task-queued; use macrotask timing.
-    state.flushTimeoutId = globalThis.setTimeout(() => {
+    state.flushTimeoutId = scheduleWorkerTask(() => {
       state.flushTimeoutId = null;
       state.flushScheduled = false;
       if (state.ownerCount === 0) return;
@@ -680,7 +738,7 @@ const createPort = <Input, Output>({
 
         handler(message);
       }
-    }, 0);
+    });
   };
 
   return {
@@ -718,6 +776,56 @@ const createPort = <Input, Output>({
   };
 };
 
+const pendingWorkerTaskIds = new Set<
+  ReturnType<typeof globalThis.setTimeout>
+>();
+const workerTaskIdleWaiters = new Set<() => void>();
+let workerTaskIdleCheckTimeoutId:
+  ReturnType<typeof globalThis.setTimeout> | undefined;
+
+const scheduleWorkerTask = (
+  callback: () => void,
+): ReturnType<typeof globalThis.setTimeout> => {
+  if (workerTaskIdleCheckTimeoutId != null) {
+    globalThis.clearTimeout(workerTaskIdleCheckTimeoutId);
+    workerTaskIdleCheckTimeoutId = undefined;
+  }
+
+  const timeoutId = globalThis.setTimeout(() => {
+    pendingWorkerTaskIds.delete(timeoutId);
+    try {
+      callback();
+    } finally {
+      queueMicrotask(notifyWorkerTaskIdle);
+    }
+  }, 0);
+  pendingWorkerTaskIds.add(timeoutId);
+  return timeoutId;
+};
+
+const cancelWorkerTask = (
+  timeoutId: ReturnType<typeof globalThis.setTimeout>,
+): void => {
+  globalThis.clearTimeout(timeoutId);
+  pendingWorkerTaskIds.delete(timeoutId);
+  queueMicrotask(notifyWorkerTaskIdle);
+};
+
+const notifyWorkerTaskIdle = (): void => {
+  if (
+    pendingWorkerTaskIds.size > 0 ||
+    workerTaskIdleWaiters.size === 0 ||
+    workerTaskIdleCheckTimeoutId != null
+  )
+    return;
+
+  workerTaskIdleCheckTimeoutId = globalThis.setTimeout(() => {
+    workerTaskIdleCheckTimeoutId = undefined;
+    for (const resolve of workerTaskIdleWaiters) resolve();
+    workerTaskIdleWaiters.clear();
+  }, 0);
+};
+
 const createTestPort = <Input, Output>(
   registration: PortRegistration<Input, Output>,
 ): MessagePort<Input, Output> => createPort(registration);

package/src/index.ts

@@ -4,60 +4,63 @@
  * @module
  */
 
-export * from "./Array.js";
-export * from "./Assert.js";
-export * from "./BigInt.js";
-export * from "./Brand.js";
-export * from "./Buffer.js";
-export * from "./Cache.js";
-export * from "./Callbacks.js";
-export * from "./Console.js";
-export * from "./Crypto.js";
-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";
-export * from "./Object.js";
-export * from "./Option.js";
-export * from "./Order.js";
-export * from "./Platform.js";
-export * from "./Random.js";
-export * from "./Redacted.js";
-export * from "./Ref.js";
-export * from "./RefCount.js";
-export * from "./Relation.js";
-export * from "./Resource.js";
-export * from "./Result.js";
-export * from "./Set.js";
-export * from "./Sqlite.js";
-export * from "./Store.js";
-export * from "./String.js";
-export * from "./Task.js";
-export * from "./Test.js";
-export * from "./Time.js";
-export * from "./Tracer.js";
-export * from "./Type.js";
-export * from "./Types.js";
-export * from "./WebSocket.js";
-export * from "./Worker.js";
+export * from "./Array.ts";
+export * from "./Assert.ts";
+export * from "./BigInt.ts";
+export * from "./Brand.ts";
+export * from "./Buffer.ts";
+export * from "./Cache.ts";
+export * from "./Callbacks.ts";
+export * from "./Console.ts";
+export * from "./Crypto.ts";
+export * from "./Eq.ts";
+export * from "./Error.ts";
+export * from "./Function.ts";
+export * from "./Http.ts";
+export * from "./Identicon.ts";
+export * from "./LeakDetector.ts";
+export * from "./LockManager.ts";
+export * from "./Lookup.ts";
+export * from "./Microtask.ts";
+export * from "./Number.ts";
+export * from "./Object.ts";
+export * from "./Option.ts";
+export * from "./Order.ts";
+export * from "./Platform.ts";
+export * from "./Random.ts";
+export * from "./Redacted.ts";
+export * from "./Ref.ts";
+export * from "./RefCount.ts";
+export * from "./Relation.ts";
+export * from "./Resource.ts";
+export * from "./Result.ts";
+export * from "./Schedule.ts";
+export * from "./Set.ts";
+export * from "./Sqlite.ts";
+export type { StandardSchemaV1 } from "@standard-schema/spec";
+export * from "./Store.ts";
+export * from "./String.ts";
+export * from "./Task.ts";
+export * from "./Test.ts";
+export * from "./Time.ts";
+export * from "./Type.ts";
+export * from "./Types.ts";
+export * from "./WebSocket.ts";
+export * from "./Worker.ts";
 
 // Local-first essentials.
-export type { EvoluError } from "./local-first/Error.js";
-export { AppName, createEvolu } from "./local-first/Evolu.js";
+export type { EvoluError } from "./local-first/Error.ts";
+export { AppName, createEvolu } from "./local-first/Evolu.ts";
 export type {
   AppNameError,
   Evolu,
   EvoluConfig,
   EvoluDeps,
   UnuseOwner,
-} from "./local-first/Evolu.js";
-export * from "./local-first/LocalAuth.js";
-export * from "./local-first/Owner.js";
-export type { SyncOwner } from "./local-first/Owner.js";
+} from "./local-first/Evolu.ts";
+export * from "./local-first/LocalAuth.ts";
+export * from "./local-first/Owner.ts";
+export type { SyncOwner } from "./local-first/Owner.ts";
 export {
   evoluJsonArrayFrom,
   evoluJsonBuildObject,
@@ -69,8 +72,8 @@ export {
   type Query,
   type QueryRows,
   type Row,
-} from "./local-first/Query.js";
-export { createQueryBuilder } from "./local-first/Schema.js";
+} from "./local-first/Query.ts";
+export { createQueryBuilder } from "./local-first/Schema.ts";
 export type {
   AnyStandardSchemaV1,
   EvoluSchema,
@@ -85,22 +88,22 @@ export type {
   TableSchema,
   UpdateValues,
   UpsertValues,
-} from "./local-first/Schema.js";
+} from "./local-first/Schema.ts";
 export type {
   // NetworkError,
   // PaymentRequiredError,
   // ServerError,
   SyncState,
-} from "./local-first/Shared.js";
+} from "./local-first/Shared.ts";
 export {
   Timestamp,
   timestampBytesToTimestamp,
   timestampToTimestampBytes,
-} from "./local-first/Timestamp.js";
+} from "./local-first/Timestamp.ts";
 export type {
   TimestampBytes,
   TimestampCounterOverflowError,
   TimestampDriftError,
   TimestampError,
   TimestampTimeOutOfRangeError,
-} from "./local-first/Timestamp.js";
+} from "./local-first/Timestamp.ts";