@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

package/src/Types.ts

@@ -78,82 +78,6 @@ export type NullablePartial<
  */
 export type IntentionalNever = never;
 
-/**
- * A utility interface for creating branded types.
- *
- * Branded types enhance type safety by differentiating otherwise identical base
- * types, such as `number` or `string`, to enforce stricter type checks.
- *
- * Supports multiple brands, allowing types to act like flags.
- *
- * ### Example 1: Single Brand
- *
- * ```ts
- * // A branded type definition
- * type UserId = number & Brand<"UserId">;
- *
- * // A function that creates `UserId` values.
- * // Casting with `as UserId` is unsafe, so `createUserId` must be unit-tested.
- * const createUserId = (): UserId => {
- *   return 123 as UserId; // Unsafe casting
- * };
- *
- * const userId = createUserId();
- *
- * // A function that accepts only `UserId`.
- * const getUser = (id: UserId) => {
- *   // Implementation
- * };
- *
- * getUser(userId); // ✅ Valid
- * getUser(123); // ❌ TypeScript error
- * getUser("123"); // ❌ TypeScript error
- * ```
- *
- * ### Example 2: Multiple Brands
- *
- * ```ts
- * // Define branded types
- * type Min1 = string & Brand<"Min1">;
- * type Max100 = string & Brand<"Max100">;
- * type Min1Max100 = string & Brand<"Min1" | "Max100">;
- *
- * // Functions requiring specific brands
- * const requiresMin1 = (value: Min1): void => {};
- * const requiresMax100 = (value: Max100): void => {};
- *
- * // Values with single brands
- * const min1Value: Min1 = "hello" as Min1;
- * const max100Value: Max100 = "world" as Max100;
- *
- * // Value with multiple brands
- * const min1Max100Value: Min1Max100 = "typescript" as Min1Max100;
- *
- * // Valid cases
- * requiresMin1(min1Value); // ✅ Valid
- * requiresMax100(max100Value); // ✅ Valid
- * requiresMin1(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Min1
- * requiresMax100(min1Max100Value); // ✅ Valid: Min1Max100 satisfies Max100
- * ```
- */
-export interface Brand<B extends string> {
-  readonly [__brand]: Readonly<Record<B, true>>;
-}
-
-declare const __brand: unique symbol;
-
-/**
- * Determines whether a type `T` is a branded type.
- *
- * Works with any base type intersected with a `Brand`.
- *
- * ### Examples
- *
- * - `IsBranded<string>` -> false
- * - `IsBranded<string & Brand<"X">>` -> true
- */
-export type IsBranded<T> = T extends Brand<string> ? true : false;
-
 /**
  * String | number | bigint | boolean | undefined | null
  *

package/src/WebSocket.ts

@@ -6,8 +6,9 @@
 
 import { assertNoErrorInCatch } from "./Assert.js";
 import { constVoid } from "./Function.js";
-import { retry, RetryError, RetryOptions } from "./Promise.js";
 import { err, ok, Result } from "./Result.js";
+import { retry, RetryError, RetryOptions } from "./Task.js";
+import { maxPositiveInt } from "./Type.js";
 
 /** WebSocket with auto-reconnect and offline support. */
 export interface WebSocket extends Disposable {
@@ -20,10 +21,14 @@ export interface WebSocket extends Disposable {
   ) => Result<void, WebSocketSendError>;
 
   readonly getReadyState: () => WebSocketReadyState;
+
+  /** Returns true if the WebSocket is open and ready to send data. */
+  readonly isOpen: () => boolean;
 }
 
 /**
- * An error that occurs when trying to send data but WebSocket is connecting.
+ * An error that occurs when trying to send data but WebSocket is not available
+ * or is in the CONNECTING state.
  *
  * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
  */
@@ -141,8 +146,9 @@ export interface WebSocketConnectionCloseError {
  *
  * TODO:
  */
-export const createWebSocket: CreateWebSocket = (url, options = {}) => {
-  const {
+export const createWebSocket: CreateWebSocket = (
+  url,
+  {
     protocols,
     binaryType,
     onOpen,
@@ -151,14 +157,14 @@ export const createWebSocket: CreateWebSocket = (url, options = {}) => {
     onError,
     retryOptions,
     WebSocketConstructor = globalThis.WebSocket,
-  } = options;
+  } = {},
+) => {
   let isDisposed = false;
 
   const reconnectController = new AbortController();
 
   const defaultRetryOptions: RetryOptions<WebSocketRetryError> = {
-    signal: reconnectController.signal,
-    maxRetries: Infinity,
+    retries: maxPositiveInt, // Practically infinite retries
   };
 
   let socket: globalThis.WebSocket | null = null;
@@ -187,6 +193,10 @@ export const createWebSocket: CreateWebSocket = (url, options = {}) => {
    * - Is resolved when WebSocket is disposed().
    */
   retry(
+    {
+      ...defaultRetryOptions,
+      ...retryOptions,
+    },
     (): Promise<Result<void, WebSocketRetryError>> =>
       new Promise((resolve) => {
         disposePromise = () => {
@@ -227,20 +237,16 @@ export const createWebSocket: CreateWebSocket = (url, options = {}) => {
           onMessage?.(event.data as string | ArrayBuffer | Blob);
         };
       }),
-    {
-      ...defaultRetryOptions,
-      ...retryOptions,
-    },
-  )
+  )(reconnectController)
     .then((result) => {
-      if (result.ok || result.error.type === "RetryAbortError") return;
-      onError?.(result.error);
+      if (result.ok || result.error.type === "AbortError") return;
+      onError?.(result.error as WebSocketError);
     })
     .catch((error: unknown) => {
       assertNoErrorInCatch("WebSocket retry", error);
     });
 
-  const webSocket: WebSocket = {
+  return {
     send: (data) => {
       // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
       if (!socket || socket.readyState === socket.CONNECTING) {
@@ -253,6 +259,8 @@ export const createWebSocket: CreateWebSocket = (url, options = {}) => {
     getReadyState: () =>
       socket ? nativeToStringState[socket.readyState] : "connecting",
 
+    isOpen: () => (socket ? socket.readyState === socket.OPEN : false),
+
     [Symbol.dispose]() {
       if (isDisposed) return;
       isDisposed = true;
@@ -261,8 +269,6 @@ export const createWebSocket: CreateWebSocket = (url, options = {}) => {
       disposePromise?.();
     },
   };
-
-  return webSocket;
 };
 
 const nativeToStringState: Record<number, WebSocketReadyState> = {

package/src/Worker.ts

@@ -20,6 +20,32 @@ export interface WorkerPostMessageDep<Output> {
   readonly postMessage: (message: Output) => void;
 }
 
+/**
+ * Error reporting wrapper that catches synchronous errors in handlers and
+ * converts them to transferable error messages sent to the main thread.
+ */
+export type WithErrorReporting = <A extends Array<any>>(
+  handler: (...args: A) => void,
+) => (...args: A) => void;
+
+type HasInit<Input> =
+  Extract<Input, { type: "init" }> extends never
+    ? ["Input must contain a variant with { type: 'init' }"]
+    : unknown;
+
+type HasWorkerErrorOutput<T> =
+  Extract<T, { type: "onError" }> extends infer E
+    ? [E] extends [never]
+      ? [
+          "Output must contain { type: 'onError'; error: TransferableError | ... }",
+        ]
+      : E extends { error: infer Err }
+        ? TransferableError extends Err
+          ? unknown
+          : ["Output.onError.error must include TransferableError"]
+        : ["Output.onError must have an error property"]
+    : never;
+
 /**
  * Creates a {@link Worker} that supports initialization with dependencies and
  * safe error handling.
@@ -35,9 +61,7 @@ export const createInitializedWorker = <
   readonly init: (
     initMessage: Extract<Input, { type: "init" }>,
     postMessage: (msg: Output) => void,
-    safeHandler: <A extends Array<any>>(
-      handler: (...args: A) => void,
-    ) => (...args: A) => void,
+    withErrorReporting: WithErrorReporting,
   ) => Promise<Deps | null>;
   readonly onMessage: (
     deps: Deps,
@@ -62,7 +86,11 @@ export const createInitializedWorker = <
     } as unknown as Output);
   };
 
-  const safeHandler =
+  /**
+   * Wraps function to catch errors and send them to the main thread instead of
+   * crashing the worker.
+   */
+  const withErrorReporting =
     <A extends Array<any>>(handler: (...args: A) => void) =>
     (...args: A) => {
       try {
@@ -78,7 +106,7 @@ export const createInitializedWorker = <
         if (!deps) {
           pendingMessages.push(message);
         } else {
-          safeHandler(onMessage(deps))(message as NonInitMessage);
+          withErrorReporting(onMessage(deps))(message as NonInitMessage);
         }
         return;
       }
@@ -89,13 +117,13 @@ export const createInitializedWorker = <
       init(
         message as Extract<Input, { type: "init" }>,
         postMessage,
-        safeHandler,
+        withErrorReporting,
       )
         .then((_deps) => {
           if (_deps == null) return;
           deps = _deps;
           for (const message of pendingMessages) {
-            safeHandler(onMessage(deps))(message as NonInitMessage);
+            withErrorReporting(onMessage(deps))(message as NonInitMessage);
           }
           pendingMessages.length = 0;
         })
@@ -110,20 +138,41 @@ export const createInitializedWorker = <
   return worker;
 };
 
-type HasInit<Input> =
-  Extract<Input, { type: "init" }> extends never
-    ? ["Input must contain a variant with { type: 'init' }"]
-    : unknown;
+/** Type helper to extract message types from a union type */
+export type MessageHandlers<Input extends { readonly type: string }, Deps> = {
+  readonly [K in Input["type"]]: (
+    deps: Deps,
+  ) => (message: Extract<Input, { type: K }>) => void;
+};
 
-type HasWorkerErrorOutput<T> =
-  Extract<T, { type: "onError" }> extends infer E
-    ? [E] extends [never]
-      ? [
-          "Output must contain { type: 'onError'; error: TransferableError | ... }",
-        ]
-      : E extends { error: infer Err }
-        ? TransferableError extends Err
-          ? unknown
-          : ["Output.onError.error must include TransferableError"]
-        : ["Output.onError must have an error property"]
-    : never;
+/**
+ * Creates a {@link Worker} with type-safe message handlers for each message
+ * type. This provides better type safety and organization compared to a single
+ * onMessage handler.
+ */
+export const createInitializedWorkerWithHandlers = <
+  Input extends { readonly type: string } & HasInit<Input>,
+  Output extends { readonly type: string } & HasWorkerErrorOutput<Output>,
+  Deps,
+>({
+  init,
+  handlers,
+}: {
+  readonly init: (
+    initMessage: Extract<Input, { type: "init" }>,
+    postMessage: (msg: Output) => void,
+    withErrorReporting: WithErrorReporting,
+  ) => Promise<Deps | null>;
+  readonly handlers: Omit<MessageHandlers<Input, Deps>, "init">;
+}): Worker<Input, Output> =>
+  createInitializedWorker({
+    init,
+    onMessage: (deps) => (message) => {
+      type NonInitMessageType = Exclude<Input["type"], "init">;
+      const messageType = message.type as NonInitMessageType;
+      const handler = handlers[messageType];
+
+      // TypeScript knows handler exists because handlers covers all non-init message types
+      handler(deps)(message as Extract<Input, { type: typeof messageType }>);
+    },
+  });

package/src/index.ts

@@ -1,8 +1,9 @@
 export * from "./Array.js";
 export * from "./Assert.js";
 export * from "./BigInt.js";
+export * from "./Brand.js";
 export * from "./Buffer.js";
-export * from "./Callbacks.js";
+export * from "./CallbackRegistry.js";
 export * from "./Console.js";
 export * from "./Crypto.js";
 export * from "./Eq.js";
@@ -10,17 +11,16 @@ export * from "./Error.js";
 export * from "./Evolu/Public.js";
 export * from "./Function.js";
 export * from "./ManyToManyMap.js";
-export * from "./NanoId.js";
 export * from "./Number.js";
 export * from "./Object.js";
 export * from "./Order.js";
-export * from "./Promise.js";
 export * from "./Random.js";
 export * from "./Ref.js";
 export * from "./Result.js";
 export * from "./Sqlite.js";
 export * from "./Store.js";
 export * from "./String.js";
+export * from "./Task.js";
 export * from "./Time.js";
 export * from "./Type.js";
 export * from "./Types.js";

package/dist/src/Callbacks.d.ts

@@ -1,20 +0,0 @@
-import { NanoIdLibDep } from "./NanoId.js";
-import { Brand } from "./Types.js";
-/**
- * Manages one-time callback functions.
- *
- * Allows registering callbacks with a unique ID and executing them once with an
- * optional argument. Executed callbacks are automatically removed.
- *
- * This is useful for managing event-driven or asynchronous workflows where
- * callbacks need to be invoked only once.
- */
-export interface Callbacks {
-    /** Registers a callback function and returns a unique ID. */
-    readonly register: (callback: (arg?: unknown) => void) => CallbackId;
-    /** Executes and removes a callback associated with the given ID. */
-    readonly execute: (id: CallbackId, arg?: unknown) => void;
-}
-export type CallbackId = string & Brand<"CallbackId">;
-export declare const createCallbacks: (deps: NanoIdLibDep) => Callbacks;
-//# sourceMappingURL=Callbacks.d.ts.map

package/dist/src/Callbacks.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Callbacks.d.ts","sourceRoot":"","sources":["../../src/Callbacks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,KAAK,UAAU,CAAC;IAErE,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;AAEtD,eAAO,MAAM,eAAe,GAAI,MAAM,YAAY,KAAG,SAoBpD,CAAC"}

package/dist/src/Callbacks.js

@@ -1,18 +0,0 @@
-export const createCallbacks = (deps) => {
-    const callbackMap = new Map();
-    const callbacks = {
-        register: (callback) => {
-            const id = deps.nanoIdLib.nanoid();
-            callbackMap.set(id, callback);
-            return id;
-        },
-        execute: (id, arg) => {
-            const callback = callbackMap.get(id);
-            if (callback) {
-                callbackMap.delete(id);
-                callback(arg);
-            }
-        },
-    };
-    return callbacks;
-};

package/dist/src/Evolu/Config.d.ts

@@ -1,69 +0,0 @@
-import { ConsoleConfig } from "../Console.js";
-import { Mnemonic, SimpleName } from "../Type.js";
-import type { DbIndexesBuilder } from "./Kysely.js";
-export interface Config extends ConsoleConfig {
-    /**
-     * The name of Evolu instances. Evolu is multitenant - it can run more
-     * instances concurrently. Every Evolu instance has to have its own unique
-     * name. Database files are separated and invisible to each other.
-     *
-     * The default value is: `Evolu`.
-     *
-     * ### Example
-     *
-     * ```ts
-     * // name: getOrThrow(SimpleName.from("MyApp"))
-     * ```
-     */
-    readonly name: SimpleName;
-    /**
-     * URL for Evolu sync and backup server.
-     *
-     * The default value is `https://free.evoluhq.com`.
-     */
-    readonly syncUrl: string;
-    /**
-     * URL to reload browser tabs after reset or restore.
-     *
-     * The default value is `/`.
-     */
-    readonly reloadUrl: string;
-    /**
-     * Maximum physical clock drift allowed in ms.
-     *
-     * The default value is 5 * 60 * 1000 (5 minutes).
-     */
-    readonly maxDrift: number;
-    /**
-     * Use the `indexes` option to define SQLite indexes.
-     *
-     * Table and column names are not typed because Kysely doesn't support it.
-     *
-     * https://medium.com/@JasonWyatt/squeezing-performance-from-sqlite-indexes-indexes-c4e175f3c346
-     *
-     * ### Example
-     *
-     * ```ts
-     * const evolu = createEvolu(evoluReactDeps)(Schema, {
-     *   indexes: (create) => [
-     *     create("todoCreatedAt").on("todo").column("createdAt"),
-     *     create("todoCategoryCreatedAt")
-     *       .on("todoCategory")
-     *       .column("createdAt"),
-     *   ],
-     * });
-     * ```
-     */
-    readonly indexes?: DbIndexesBuilder;
-    /**
-     * Use this option to create Evolu with the specified mnemonic. If omitted,
-     * the mnemonic will be autogenerated. That should be the default behavior
-     * until special UX requirements are needed (e.g., multitenancy).
-     */
-    readonly mnemonic?: Mnemonic;
-}
-export interface ConfigDep {
-    readonly config: Config;
-}
-export declare const defaultConfig: Config;
-//# sourceMappingURL=Config.d.ts.map

package/dist/src/Evolu/Config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE9C,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,MAAO,SAAQ,aAAa;IAC3C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAE1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;CAC9B;AAED,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,eAAO,MAAM,aAAa,EAAE,MAM3B,CAAC"}

package/dist/src/Evolu/Config.js

@@ -1,9 +0,0 @@
-import { getOrThrow } from "../Result.js";
-import { SimpleName } from "../Type.js";
-export const defaultConfig = {
-    name: getOrThrow(SimpleName.fromParent("Evolu")),
-    syncUrl: "https://free.evoluhq.com",
-    reloadUrl: "/",
-    maxDrift: 5 * 60 * 1000,
-    enableLogging: false,
-};

package/dist/src/Evolu/Kysely.d.ts

@@ -1,6 +0,0 @@
-import { CreateIndexBuilder, Kysely } from "kysely";
-import { DbIndex } from "./Db.js";
-export declare const kysely: Kysely<unknown>;
-export type DbIndexesBuilder = (create: (indexName: string) => CreateIndexBuilder) => ReadonlyArray<CreateIndexBuilder<any>>;
-export declare const createIndexes: (indexes?: DbIndexesBuilder) => ReadonlyArray<DbIndex>;
-//# sourceMappingURL=Kysely.d.ts.map

package/dist/src/Evolu/Kysely.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"Kysely.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Kysely.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAElB,MAAM,EAGP,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC,eAAO,MAAM,MAAM,iBASjB,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,MAAM,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,kBAAkB,KAC9C,aAAa,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAAC;AAI5C,eAAO,MAAM,aAAa,GACxB,UAAU,gBAAgB,KACzB,aAAa,CAAC,OAAO,CAQvB,CAAC"}

package/dist/src/Evolu/Kysely.js

@@ -1,21 +0,0 @@
-import { DummyDriver, Kysely, SqliteAdapter, SqliteQueryCompiler, } from "kysely";
-// https://kysely.dev/docs/recipes/splitting-query-building-and-execution
-export const kysely = new Kysely({
-    dialect: {
-        createAdapter: () => new SqliteAdapter(),
-        createDriver: () => new DummyDriver(),
-        createIntrospector() {
-            throw new Error("Not implemeneted");
-        },
-        createQueryCompiler: () => new SqliteQueryCompiler(),
-    },
-});
-const createIndex = kysely.schema.createIndex.bind(kysely.schema);
-export const createIndexes = (indexes) => {
-    if (!indexes)
-        return [];
-    return indexes(createIndex).map((index) => ({
-        name: index.toOperationNode().name.name,
-        sql: index.compile().sql,
-    }));
-};

package/dist/src/NanoId.d.ts

@@ -1,27 +0,0 @@
-/**
- * Interface representing a NanoId library.
- *
- * It's useful for testing by allowing ID generation to be mocked, ensuring
- * consistent results.
- *
- * @see https://github.com/ai/nanoid
- *
- * ### Example
- *
- * ```ts
- * const foo = createFoo({
- *   ...createNanoIdLib(),
- *   ...createTime(),
- * });
- * ```
- */
-export interface NanoIdLib {
-    readonly urlAlphabet: string;
-    readonly customAlphabet: (alphabet: string, defaultSize?: number) => (size?: number) => string;
-    readonly nanoid: (size?: number) => string;
-}
-export interface NanoIdLibDep {
-    readonly nanoIdLib: NanoIdLib;
-}
-export declare const createNanoIdLib: () => NanoIdLib;
-//# sourceMappingURL=NanoId.d.ts.map

package/dist/src/NanoId.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"NanoId.d.ts","sourceRoot":"","sources":["../../src/NanoId.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,cAAc,EAAE,CACvB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,KACjB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAE/B,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC"}

package/dist/src/NanoId.js

@@ -1,6 +0,0 @@
-import { customAlphabet, nanoid, urlAlphabet } from "nanoid";
-export const createNanoIdLib = () => ({
-    urlAlphabet,
-    customAlphabet,
-    nanoid,
-});