@evolu/common 8.0.0-next.4 → 8.0.0

package/src/WebSocket.ts

@@ -4,16 +4,16 @@
  * @module
  */
 
-import { assert } from "./Assert.js";
-import { lazyTrue } from "./Function.js";
-import type { Result } from "./Result.js";
-import { err, ok } from "./Result.js";
-import type { Schedule } from "./Schedule.js";
-import { exponential, jitter, maxDelay } from "./Schedule.js";
-import type { RetryError, Task } from "./Task.js";
-import { callback, retry } from "./Task.js";
-import type { Millis } from "./Time.js";
-import { ArrayBuffer, String, Uint8Array, type Typed } from "./Type.js";
+import { assert } from "./Assert.ts";
+import { constTrue } from "./Function.ts";
+import type { Result } from "./Result.ts";
+import { err, ok } from "./Result.ts";
+import type { Schedule } from "./Schedule.ts";
+import { exponential, jitter, maxDelay } from "./Schedule.ts";
+import type { RetryError, Task } from "./Task.ts";
+import { callback, retry } from "./Task.ts";
+import type { Millis } from "./Time.ts";
+import { ArrayBuffer, String, Uint8Array, type Typed } from "./Type.ts";
 
 /**
  * WebSocket with auto-reconnect.
@@ -49,20 +49,42 @@ import { ArrayBuffer, String, Uint8Array, type Typed } from "./Type.js";
  *   - A Blob (default: "blob")
  *   - An ArrayBuffer ("arraybuffer")
  *
- * ### Example
+ * ### Connecting and sending
  *
  * ```ts
- * const ws = await run(
- *   createWebSocket("wss://example.com", {
- *     onMessage: (data) => console.log("Received:", data),
- *     onOpen: () => console.log("Connected"),
- *     onClose: () => console.log("Disconnected"),
- *   }),
- * );
- * if (ws.ok) {
- *   ws.value.send("Hello");
- *   // Later: await ws.value[Symbol.asyncDispose]();
- * }
+ * import {
+ *   createRun,
+ *   createWebSocket,
+ *   testCreateWebSocket,
+ *   type CreateWebSocket,
+ *   type Task,
+ *   type WebSocketSendError,
+ * } from "@evolu/common";
+ *
+ * const connectAndSend =
+ *   (
+ *     createSocket: CreateWebSocket = createWebSocket,
+ *   ): Task<void, WebSocketSendError> =>
+ *   async (run) => {
+ *     await using socket = await run.ok(
+ *       createSocket("wss://example.com", {
+ *         protocols: ["evolu"],
+ *         binaryType: "arraybuffer",
+ *         onOpen: () => console.log("Connected"),
+ *         onMessage: (data) => console.log("Received:", data),
+ *         onClose: () => console.log("Disconnected"),
+ *       }),
+ *     );
+ *     return socket.send("Hello");
+ *   };
+ *
+ * const socketFactory = testCreateWebSocket();
+ * await using run = createRun();
+ *
+ * expectOk(await run(connectAndSend(socketFactory)), undefined);
+ * expect(socketFactory.sentMessages).toEqual([
+ *   { url: "wss://example.com", data: "Hello" },
+ * ]);
  * ```
  */
 export interface WebSocket extends AsyncDisposable {
@@ -129,12 +151,8 @@ export interface WebSocketOptions {
   readonly onMessage?: (data: string | ArrayBuffer | Blob) => void;
 
   /**
-   * Retry schedule for reconnection. Defaults to:
-   *
-   * ```ts
-   * // A jittered, capped, unlimited exponential backoff.
-   * jitter(1)(maxDelay("30s")(exponential("100ms")));
-   * ```
+   * Retry schedule for reconnection. Defaults to
+   * {@link webSocketReconnectSchedule}.
    */
   readonly schedule?: Schedule<Millis, WebSocketRetryError>;
 
@@ -175,14 +193,24 @@ export interface WebSocketConnectionError extends Typed<"WebSocketConnectionErro
 }
 
 export type WebSocketRetryError =
-  | WebSocketConnectError
-  | WebSocketConnectionCloseError;
+  WebSocketConnectError | WebSocketConnectionCloseError;
 
 /** An error that occurs when the connection is closed by the server. */
 export interface WebSocketConnectionCloseError extends Typed<"WebSocketConnectionCloseError"> {
   readonly event: CloseEvent;
 }
 
+/**
+ * Default WebSocket reconnect schedule.
+ *
+ * Uses unlimited exponential backoff with a 100ms base, 30s cap, and full
+ * jitter.
+ */
+export const webSocketReconnectSchedule: Schedule<Millis, WebSocketRetryError> =
+  /*#__PURE__*/ jitter("100%")(
+    /*#__PURE__*/ maxDelay("30s")(/*#__PURE__*/ exponential("100ms")),
+  );
+
 /** Create a new {@link WebSocket}. */
 export const createWebSocket: CreateWebSocket =
   (
@@ -192,10 +220,10 @@ export const createWebSocket: CreateWebSocket =
       binaryType,
       onOpen,
       onClose,
-      shouldRetryOnClose = lazyTrue,
+      shouldRetryOnClose = constTrue,
       onMessage,
       onError,
-      schedule = jitter(1)(maxDelay("30s")(exponential("100ms"))),
+      schedule = webSocketReconnectSchedule,
       WebSocketConstructor = globalThis.WebSocket,
     } = {},
   ) =>
@@ -226,7 +254,7 @@ export const createWebSocket: CreateWebSocket =
      * A task that connects and stays connected until the connection closes or
      * errors. Returns error to trigger retry.
      */
-    const connect: Task<void, WebSocketRetryError> = callback(({ err, ok }) => {
+    const connect: Task<void, WebSocketRetryError> = callback(({ resolve }) => {
       closeSocket();
 
       socket = new WebSocketConstructor(
@@ -246,9 +274,9 @@ export const createWebSocket: CreateWebSocket =
       socket.onclose = (event) => {
         onClose?.(event);
         if (shouldRetryOnClose(event)) {
-          err({ type: "WebSocketConnectionCloseError", event });
+          resolve(err({ type: "WebSocketConnectionCloseError", event }));
         } else {
-          ok();
+          resolve(ok());
         }
       };
 
@@ -262,7 +290,7 @@ export const createWebSocket: CreateWebSocket =
           : { type: "WebSocketConnectError", event };
         onError?.(error);
 
-        if (error.type === "WebSocketConnectError") err(error);
+        if (error.type === "WebSocketConnectError") resolve(err(error));
       };
 
       return closeSocket;

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";