@evolu/common 8.0.0-next.3 → 8.0.0-next.5

package/src/Test.ts

@@ -17,7 +17,7 @@ import {
   type Random,
   type RandomLibDep,
 } from "./Random.js";
-import { createRun, type Run, type RunDeps } from "./Task.js";
+import { createRun, type Run, type RunDefaultDeps } from "./Task.js";
 import {
   minMillis,
   setTimeout,
@@ -35,14 +35,14 @@ export type TestCreateId = <B extends string = never>() => [B] extends [never]
 /**
  * Cheap deterministic baseline deps for tests.
  *
- * `TestDeps` includes test-friendly replacements for {@link RunDeps}, such as
- * {@link TestConsole} and {@link TestTime}, plus extra helpers commonly useful in
- * tests and fixtures, such as `randomLib` (only that for now).
+ * `TestDeps` includes test-friendly replacements for {@link RunDefaultDeps},
+ * such as {@link TestConsole} and {@link TestTime}, plus extra helpers commonly
+ * useful in tests and fixtures, such as `randomLib` (only that for now).
  *
  * Use it directly for synchronous test setup, fixtures, and helpers. It is also
  * intentionally the base deps used by {@link testCreateRun}.
  */
-export type TestDeps = Omit<RunDeps, "console" | "time"> &
+export type TestDeps = Omit<RunDefaultDeps, "console" | "time"> &
   TestConsoleDep &
   TestTimeDep &
   RandomLibDep;
@@ -103,7 +103,7 @@ export const testCreateDeps = (options?: {
  * ### Example
  *
  * ```ts
- * // Built-in TestTime
+ * // Default TestTime
  * await using run = testCreateRun();
  * const fiber = run(sleep("1s"));
  * run.deps.time.advance("1s");
@@ -112,24 +112,23 @@ export const testCreateDeps = (options?: {
  * // For a single test, create the dependency using the Run.
  * await using run = testCreateRun();
  * await using foo = await run.orThrow(createFoo());
- * const runWithFoo = run.addDeps({ foo });
- *
- * expect(runWithFoo.deps.foo).toBe(foo);
+ * await run.orThrow(taskThatNeedsFoo, { foo });
  *
  * // If multiple tests need the same setup, create a disposable helper.
  * // Then `await using setup` disposes everything the helper owns.
  * const setupFoo = async () => {
- *   await using stack = new AsyncDisposableStack();
- *   const run = stack.use(testCreateRun());
- *   const foo = stack.use(await run.orThrow(createFoo()));
- *   const moved = stack.move();
+ *   await using disposer = new AsyncDisposableStack();
+ *   const run = disposer.use(testCreateRun());
+ *   const foo = disposer.use(await run.orThrow(createFoo()));
+ *   const runWithFoo = disposer.use(run.create({ ...run.deps, foo }));
+ *   const disposables = disposer.move();
  *
  *   // Return whatever the tests need: a Run with the dependency,
  *   // the dependency itself, or both.
  *   return {
- *     run: run.addDeps({ foo }),
+ *     run: runWithFoo,
  *     foo,
- *     [Symbol.asyncDispose]: () => moved.disposeAsync(),
+ *     [Symbol.asyncDispose]: () => disposables.disposeAsync(),
  *   };
  * };
  *

package/src/Time.ts

@@ -177,6 +177,13 @@ export const minMillis = 0 as Millis;
 /** Maximum {@link Millis} value. */
 export const maxMillis = (maxMillisWithInfinity - 1) as Millis;
 
+/**
+ * Converts a number to {@link Millis}, rounding to the nearest millisecond and
+ * saturating overflow at {@link maxMillis}.
+ */
+export const saturateMillis = (value: number): Millis =>
+  Millis.orNull(Math.max(0, Math.round(value))) ?? maxMillis;
+
 /**
  * Converts {@link Millis} to {@link DateIso}.
  *

package/src/Type.ts

@@ -2334,6 +2334,14 @@ export const formatFiniteError =
 export const FiniteNumber = /*#__PURE__*/ finite(Number);
 export type FiniteNumber = typeof FiniteNumber.Type;
 
+/**
+ * Non-negative finite number.
+ *
+ * @group Number
+ */
+export const NonNegativeFiniteNumber = /*#__PURE__*/ nonNegative(FiniteNumber);
+export type NonNegativeFiniteNumber = typeof NonNegativeFiniteNumber.Type;
+
 /**
  * Number that is a multiple of a divisor.
  *
@@ -4651,6 +4659,7 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
 
     if (extraMessage != null) return extraMessage;
 
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
     error = error as TypeErrors;
 
     switch (error.type) {

package/src/Types.ts

@@ -359,12 +359,3 @@ export type ExtractType<
   TUnion extends { readonly type: TypeName },
   TType extends TUnion["type"],
 > = Extract<TUnion, { readonly type: TType }>;
-
-/**
- * Constrains `T` to only contain keys not present in `Existing`.
- *
- * Use as a generic constraint to prevent overriding existing properties.
- */
-export type NewKeys<T, Existing> = {
-  [K in keyof T]: K extends keyof Existing ? never : T[K];
-};

package/src/WebSocket.ts

@@ -200,7 +200,7 @@ export const createWebSocket: CreateWebSocket =
     } = {},
   ) =>
   async (run) => {
-    await using stack = new AsyncDisposableStack();
+    await using disposer = new AsyncDisposableStack();
 
     let socket: globalThis.WebSocket | null = null;
 
@@ -268,7 +268,7 @@ export const createWebSocket: CreateWebSocket =
       return closeSocket;
     });
 
-    const retryFiber = stack.use(run.daemon(retry(connect, schedule)));
+    const retryFiber = disposer.use(run.daemon(retry(connect, schedule)));
 
     // Report RetryError (schedule exhausted) via onError callback
     void retryFiber.then((result) => {
@@ -277,7 +277,7 @@ export const createWebSocket: CreateWebSocket =
       }
     });
 
-    const moved = stack.move();
+    const disposables = disposer.move();
 
     return ok<WebSocket>({
       send: (data) => {
@@ -290,14 +290,15 @@ export const createWebSocket: CreateWebSocket =
       },
 
       getReadyState: () => {
-        if (moved.disposed) return "closed";
+        if (disposables.disposed) return "closed";
         return socket ? nativeToStringState[socket.readyState] : "connecting";
       },
 
       isOpen: () =>
-        !moved.disposed && socket?.readyState === globalThis.WebSocket.OPEN,
+        !disposables.disposed &&
+        socket?.readyState === globalThis.WebSocket.OPEN,
 
-      [Symbol.asyncDispose]: () => moved.disposeAsync(),
+      [Symbol.asyncDispose]: () => disposables.disposeAsync(),
     });
   };
 

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,17 +275,17 @@ export const createMessageChannel: CreateMessageChannel = <
     handler: null,
     queue: [],
     flushScheduled: false,
-    refCount: 0,
+    flushTimeoutId: null,
+    ownerCount: 0,
     pendingTransferCount: 0,
-    closed: false,
   };
   const state2: PortState<Input> = {
     handler: null,
     queue: [],
     flushScheduled: false,
-    refCount: 0,
+    flushTimeoutId: null,
+    ownerCount: 0,
     pendingTransferCount: 0,
-    closed: false,
   };
 
   const native1 = createNativeMessagePortToken<Input, Output>();
@@ -277,8 +302,11 @@ export const createMessageChannel: CreateMessageChannel = <
     native: native2,
   };
 
-  const port1 = createTestPort(port1Registration);
-  const port2 = createTestPort(port2Registration);
+  using disposer = new DisposableStack();
+
+  const port1 = disposer.use(createTestPort(port1Registration));
+  const port2 = disposer.use(createTestPort(port2Registration));
+  const disposables = disposer.move();
 
   nativePortRegistry.set(native1, port1Registration);
   nativePortRegistry.set(native2, port2Registration);
@@ -286,10 +314,7 @@ export const createMessageChannel: CreateMessageChannel = <
   return {
     port1,
     port2,
-    [Symbol.dispose]: () => {
-      port1[Symbol.dispose]();
-      port2[Symbol.dispose]();
-    },
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 
@@ -307,6 +332,75 @@ export const createMessagePort: CreateMessagePort = <Input, Output = never>(
   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`.
  *
@@ -342,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.
  *
@@ -358,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 });
 };
 
 /**
@@ -378,7 +480,7 @@ export const testCreateSharedWorker = <
   return Object.assign(worker, {
     self,
     connect,
-  }) as TestSharedWorker<Input, Output>;
+  });
 };
 
 /**
@@ -394,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(),
   };
 };
 
@@ -414,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();
@@ -498,9 +622,9 @@ interface PortState<T> {
   handler: ((message: T) => void) | null;
   readonly queue: Array<T>;
   flushScheduled: boolean;
-  refCount: number;
+  flushTimeoutId: ReturnType<typeof globalThis.setTimeout> | null;
+  ownerCount: number;
   pendingTransferCount: number;
-  closed: boolean;
 }
 
 interface PortRegistration<Input, Output> {
@@ -514,23 +638,46 @@ const createPort = <Input, Output>({
   peerReceive,
   native,
 }: PortRegistration<Input, Output>): MessagePort<Input, Output> => {
+  using disposer = new DisposableStack();
+
   if (receive.pendingTransferCount > 0) receive.pendingTransferCount -= 1;
-  receive.refCount += 1;
-  let isDisposed = false;
+  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 || state.closed) 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.closed) return;
+      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);
@@ -538,41 +685,36 @@ const createPort = <Input, Output>({
 
   return {
     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;
-        registration.receive.closed = false;
       }
 
-      if (peerReceive.closed) return;
       peerReceive.queue.push(message);
       scheduleFlush(peerReceive);
     },
     get onMessage() {
-      return isDisposed ? null : receive.handler;
+      return disposables.disposed ? null : receive.handler;
     },
     set onMessage(fn) {
-      if (isDisposed || receive.closed) return;
+      if (disposables.disposed || receive.ownerCount === 0) return;
       receive.handler = fn;
       if (fn) scheduleFlush(receive);
     },
     native,
-    [Symbol.dispose]: () => {
-      if (isDisposed) return;
-      isDisposed = true;
-
-      receive.refCount -= 1;
-      if (receive.refCount > 0 || receive.pendingTransferCount > 0) return;
-
-      receive.closed = true;
-      receive.handler = null;
-      receive.flushScheduled = false;
-      receive.queue.length = 0;
-    },
+    [Symbol.dispose]: () => disposables.dispose(),
   };
 };
 

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