@evolu/common 5.4.7 → 6.0.0

package/src/Types.ts

@@ -0,0 +1,209 @@
+/**
+ * TypeScript utility types
+ *
+ * @module
+ */
+
+import * as Kysely from "kysely";
+
+/**
+ * Checks a condition on a value and returns a boolean.
+ *
+ * A predicate starts with an 'is' prefix, e.g., `isEven`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const isEven: Predicate<number> = (n) => n % 2 === 0;
+ *
+ * const numbers = [1, 2, 3, 4];
+ * const evenNumbers = numbers.filter(isEven); // [2, 4]
+ * ```
+ */
+export type Predicate<T> = (value: T) => boolean;
+
+/**
+ * A type guard function that refines type `A` to a narrower type `B`.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Animal = { name: string };
+ * type Dog = Animal & { breed: string };
+ *
+ * const isDog: Refinement<Animal, Dog> = (animal): animal is Dog =>
+ *   "breed" in animal;
+ *
+ * const animal: Animal = { name: "Dog", breed: "Beagle" };
+ * if (isDog(animal)) {
+ *   console.log(animal.breed); // Safe access to `breed`
+ * }
+ * ```
+ */
+export type Refinement<in A, out B extends A> = (a: A) => a is B;
+
+/**
+ * Makes properties optional if they accept `null` as a value.
+ *
+ * For each property in `T`, if `null` is a valid value for that property, the
+ * property will be made optional in the resulting type.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type Example = {
+ *   required: string;
+ *   optionalWithNull: string | null;
+ * };
+ *
+ * type Result = NullablePartial<Example>;
+ * // Result is:
+ * // {
+ * //   required: string;
+ * //   optionalWithNull?: string | null;
+ * // }
+ * ```
+ */
+export type NullablePartial<
+  T,
+  NK extends keyof T = {
+    [K in keyof T]: null extends T[K] ? K : never;
+  }[keyof T],
+  NP = Pick<T, Exclude<keyof T, NK>> & Partial<Pick<T, NK>>,
+> = { [K in keyof NP]: NP[K] };
+
+/**
+ * A type alias for `never` that is used intentionally when casting is not
+ * needed and unit tests exist to ensure correctness.
+ */
+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
+ *
+ * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
+ */
+export type Literal = string | number | bigint | boolean | undefined | null;
+
+/**
+ * Infers a broader type from a specific literal value type.
+ *
+ * Examples:
+ *
+ * - "foo" -> string
+ * - 42 -> number
+ * - 42n -> bigint
+ * - True -> boolean
+ */
+export type WidenLiteral<T extends Literal> = T extends string
+  ? string
+  : T extends number
+    ? number
+    : T extends boolean
+      ? boolean
+      : T extends bigint
+        ? bigint
+        : T;
+
+/**
+ * Simplify an intersection type into a single mapped type.
+ *
+ * This utility forces TypeScript to "flatten" an intersection type into a
+ * single object type so that tooltips and error messages are easier to read.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type A = { a: string } & { b: number };
+ * // Without Simplify, TypeScript may display A as:
+ * // { a: string } & { b: number }
+ *
+ * type B = Simplify<A>;
+ * // B is equivalent to:
+ * // { a: string; b: number }
+ * ```
+ */
+export type Simplify<T> = Kysely.Simplify<T>;
+
+/**
+ * Makes a specific property of an object optional while keeping others
+ * unchanged.
+ */
+export type PartialProp<T, K extends keyof T> = Omit<T, K> &
+  Partial<Pick<T, K>>;

package/src/WebSocket.ts

@@ -0,0 +1,273 @@
+/**
+ * Websocket with auto-reconnect and offline support
+ *
+ * @module
+ */
+
+import { assertNoErrorInCatch } from "./Assert.js";
+import { constVoid } from "./Function.js";
+import { retry, RetryError, RetryOptions } from "./Promise.js";
+import { err, ok, Result } from "./Result.js";
+
+/** WebSocket with auto-reconnect and offline support. */
+export interface WebSocket extends Disposable {
+  /**
+   * Send data through the WebSocket connection. Returns {@link Result} with an
+   * error if the data couldn't be sent.
+   */
+  send: (
+    data: string | ArrayBufferLike | Blob | ArrayBufferView,
+  ) => Result<void, WebSocketSendError>;
+
+  readonly getReadyState: () => WebSocketReadyState;
+}
+
+/**
+ * An error that occurs when trying to send data but WebSocket is connecting.
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+ */
+export interface WebSocketSendError {
+  readonly type: "WebSocketSendError";
+}
+
+/** WebSocket connection states. */
+export type WebSocketReadyState = "connecting" | "open" | "closing" | "closed";
+
+export type CreateWebSocket = (
+  url: string,
+  options?: WebSocketOptions,
+) => WebSocket;
+
+export interface CreateWebSocketDep {
+  readonly createWebSocket: CreateWebSocket;
+}
+
+/** Options for creating {@link WebSocket} */
+export interface WebSocketOptions {
+  /** Protocol(s) to use with the WebSocket connection. */
+  protocols?: string | Array<string>;
+
+  /** Sets the binary type for the data being received. */
+  binaryType?: "blob" | "arraybuffer";
+
+  /** Callback when the connection is established. */
+  onOpen?: () => void;
+
+  /** Callback when an error occurs. */
+  onError?: (error: WebSocketError) => void;
+
+  /** Callback when the connection is closed. */
+  onClose?: (event: CloseEvent) => void;
+
+  /** Callback when message data is received. */
+  onMessage?: (data: string | ArrayBuffer | Blob) => void;
+
+  /** Options for retry behavior. */
+  retryOptions?: Omit<RetryOptions<WebSocketRetryError>, "signal">;
+
+  /**
+   * For custom WebSocket implementations.
+   *
+   * This suppors blob:
+   *
+   * https://github.com/callstackincubator/react-native-fast-io
+   */
+  WebSocketConstructor?: typeof globalThis.WebSocket;
+}
+
+export type WebSocketError =
+  | WebSocketConnectError
+  | WebSocketConnectionError
+  | RetryError<WebSocketRetryError>;
+
+/**
+ * An error that occurs when a connection cannot be established due to a network
+ * error.
+ */
+export interface WebSocketConnectError {
+  readonly type: "WebSocketConnectError";
+  readonly event: Event;
+}
+
+/**
+ * An error that occurs when a connection is closed due to an issue (e.g.,
+ * failure to send some data).
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/error_event
+ */
+export interface WebSocketConnectionError {
+  readonly type: "WebSocketConnectionError";
+  readonly event: Event;
+}
+
+export type WebSocketRetryError =
+  | WebSocketConnectError
+  | WebSocketConnectionCloseError;
+
+export interface WebSocketConnectionCloseError {
+  readonly type: "WebSocketConnectionCloseError";
+  readonly event: CloseEvent;
+}
+
+/**
+ * Create a new {@link WebSocket}.
+ *
+ * The default behavior is that WebSocket tries to reconnect repeatedly in case
+ * the application is offline, because online events (both web and native) are
+ * not reliable. Once it connects and the connection is closed, it tries to
+ * reconnect again. Retrying the connection can be controlled using the
+ * retryOptions retryable predicate.
+ *
+ * ### How Binary Messages Work in WebSockets
+ *
+ * The Server Chooses the Message Type:
+ *
+ * - Text (0x1) → Sent as UTF-8 encoded text (always received as a string in the
+ *   browser).
+ * - Binary (0x2) → Sent as raw binary data (received as a Blob or ArrayBuffer,
+ *   depending on binaryType).
+ *
+ * The Client's binaryType Controls How Binary Data is Processed:
+ *
+ * - If the server sends a text frame (0x1), the browser always delivers
+ *   event.data as a string, regardless of binaryType.
+ * - If the server sends a binary frame (0x2), the browser delivers event.data as:
+ *
+ *   - A Blob (default: "blob")
+ *   - An ArrayBuffer ("arraybuffer")
+ *
+ * ### Example
+ *
+ * TODO:
+ */
+export const createWebSocket: CreateWebSocket = (url, options = {}) => {
+  const {
+    protocols,
+    binaryType,
+    onOpen,
+    onClose,
+    onMessage,
+    onError,
+    retryOptions,
+    WebSocketConstructor = globalThis.WebSocket,
+  } = options;
+  let isDisposed = false;
+
+  const reconnectController = new AbortController();
+
+  const defaultRetryOptions: RetryOptions<WebSocketRetryError> = {
+    signal: reconnectController.signal,
+    maxRetries: Infinity,
+  };
+
+  let socket: globalThis.WebSocket | null = null;
+
+  const disposeSocket = () => {
+    if (!socket) return;
+
+    // Remove all listeners before closing
+    socket.onopen = null;
+    socket.onclose = null;
+    socket.onmessage = null;
+    socket.onerror = null;
+
+    socket.close();
+    socket = null;
+  };
+
+  // To prevent a memory leak from pending connection promise.
+  let disposePromise: null | typeof constVoid = null;
+
+  /**
+   * This promise represents continuous connection which:
+   *
+   * - Is rejected when a connection cannot be established.
+   * - Is rejected when a connection is closed.
+   * - Is resolved when WebSocket is disposed().
+   */
+  retry(
+    (): Promise<Result<void, WebSocketRetryError>> =>
+      new Promise((resolve) => {
+        disposePromise = () => {
+          resolve(ok());
+        };
+
+        if (isDisposed) disposePromise();
+
+        disposeSocket();
+
+        socket = new WebSocketConstructor(url, protocols);
+        if (binaryType) socket.binaryType = binaryType;
+
+        let isOpen = false;
+
+        socket.onopen = () => {
+          isOpen = true;
+          onOpen?.();
+        };
+
+        socket.onerror = (event) => {
+          const error: WebSocketConnectionError | WebSocketConnectError = isOpen
+            ? { type: "WebSocketConnectionError", event }
+            : { type: "WebSocketConnectError", event };
+          onError?.(error);
+          // Trigger reconnect only on WebSocketConnectError.
+          if (error.type === "WebSocketConnectError") {
+            resolve(err(error));
+          }
+        };
+
+        socket.onclose = (event) => {
+          onClose?.(event);
+          resolve(err({ type: "WebSocketConnectionCloseError", event }));
+        };
+
+        socket.onmessage = (event) => {
+          onMessage?.(event.data as string | ArrayBuffer | Blob);
+        };
+      }),
+    {
+      ...defaultRetryOptions,
+      ...retryOptions,
+    },
+  )
+    .then((result) => {
+      if (result.ok || result.error.type === "RetryAbortError") return;
+      onError?.(result.error);
+    })
+    .catch((error: unknown) => {
+      assertNoErrorInCatch("WebSocket retry", error);
+    });
+
+  const webSocket: WebSocket = {
+    send: (data) => {
+      // https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/send
+      if (!socket || socket.readyState === socket.CONNECTING) {
+        return err({ type: "WebSocketSendError" });
+      }
+      socket.send(data);
+      return ok();
+    },
+
+    getReadyState: () =>
+      socket ? nativeToStringState[socket.readyState] : "connecting",
+
+    [Symbol.dispose]() {
+      if (isDisposed) return;
+      isDisposed = true;
+      reconnectController.abort();
+      disposeSocket();
+      disposePromise?.();
+    },
+  };
+
+  return webSocket;
+};
+
+const nativeToStringState: Record<number, WebSocketReadyState> = {
+  [WebSocket.CONNECTING]: "connecting",
+  [WebSocket.OPEN]: "open",
+  [WebSocket.CLOSING]: "closing",
+  [WebSocket.CLOSED]: "closed",
+};

package/src/Worker.ts

@@ -0,0 +1,129 @@
+/**
+ * Cross-platform worker abstraction
+ *
+ * @module
+ */
+
+import { assert } from "./Assert.js";
+import { createTransferableError, TransferableError } from "./Error.js";
+
+/** Cross-platform worker abstraction. */
+export interface Worker<Input, Output> {
+  /** Sends a message to the worker. */
+  readonly postMessage: (message: Input) => void;
+
+  /** Sets a callback for messages from the worker. */
+  readonly onMessage: (callback: (message: Output) => void) => void;
+}
+
+export interface WorkerPostMessageDep<Output> {
+  readonly postMessage: (message: Output) => void;
+}
+
+/**
+ * Creates a {@link Worker} that supports initialization with dependencies and
+ * safe error handling.
+ */
+export const createInitializedWorker = <
+  Input extends { readonly type: string } & HasInit<Input>,
+  Output extends { readonly type: string } & HasWorkerErrorOutput<Output>,
+  Deps,
+>({
+  init,
+  onMessage,
+}: {
+  readonly init: (
+    initMessage: Extract<Input, { type: "init" }>,
+    postMessage: (msg: Output) => void,
+    safeHandler: <A extends Array<any>>(
+      handler: (...args: A) => void,
+    ) => (...args: A) => void,
+  ) => Promise<Deps | null>;
+  readonly onMessage: (
+    deps: Deps,
+  ) => (message: Exclude<Input, { type: "init" }>) => void;
+}): Worker<Input, Output> => {
+  type NonInitMessage = Exclude<Input, { type: "init" }>;
+
+  let onMessageCallback: ((msg: Output) => void) | null = null;
+  let deps: Deps | null = null;
+  const pendingMessages: Array<Input> = [];
+  let initializing = false;
+
+  const postMessage = (msg: Output) => {
+    assert(onMessageCallback != null, "The onMessage wasn't set");
+    onMessageCallback(msg);
+  };
+
+  const postMessageTransferableError = (error: unknown) => {
+    postMessage({
+      type: "onError",
+      error: createTransferableError(error),
+    } as unknown as Output);
+  };
+
+  const safeHandler =
+    <A extends Array<any>>(handler: (...args: A) => void) =>
+    (...args: A) => {
+      try {
+        handler(...args);
+      } catch (error) {
+        postMessageTransferableError(error);
+      }
+    };
+
+  const worker: Worker<Input, Output> = {
+    postMessage: (message) => {
+      if (message.type !== "init") {
+        if (!deps) {
+          pendingMessages.push(message);
+        } else {
+          safeHandler(onMessage(deps))(message as NonInitMessage);
+        }
+        return;
+      }
+
+      if (initializing) return;
+      initializing = true;
+
+      init(
+        message as Extract<Input, { type: "init" }>,
+        postMessage,
+        safeHandler,
+      )
+        .then((_deps) => {
+          if (_deps == null) return;
+          deps = _deps;
+          for (const message of pendingMessages) {
+            safeHandler(onMessage(deps))(message as NonInitMessage);
+          }
+          pendingMessages.length = 0;
+        })
+        .catch(postMessageTransferableError);
+    },
+
+    onMessage: (callback) => {
+      onMessageCallback = callback;
+    },
+  };
+
+  return worker;
+};
+
+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;

package/src/index.ts

@@ -1,15 +1,28 @@
-export * from "./Config.js";
-export * from "./Crdt.js";
+export * from "./Array.js";
+export * from "./Assert.js";
+export * from "./BigInt.js";
+export * from "./Buffer.js";
+export * from "./Callbacks.js";
+export * from "./Console.js";
 export * from "./Crypto.js";
-export * from "./Db.js";
-export * from "./Diff.js";
+export * from "./Eq.js";
 export * from "./Error.js";
-export * from "./Evolu.js";
-export * from "./Model.js";
-export * from "./Murmurhash.js";
-export * from "./Owner.js";
-export * from "./Platform.js";
-export * from "./Protobuf.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 "./Sync.js";
+export * from "./String.js";
+export * from "./Time.js";
+export * from "./Type.js";
+export * from "./Types.js";
+export * from "./WebSocket.js";
+export * from "./Worker.js";

package/dist/src/Config.d.ts

@@ -1,56 +0,0 @@
-import * as Context from "effect/Context";
-import * as ManagedRuntime from "effect/ManagedRuntime";
-export interface Config {
-    /**
-     * URL to reload browser tabs after {@link Owner} reset or restore.
-     *
-     * The default value is `/`.
-     */
-    reloadUrl: string;
-    /**
-     * URL for Evolu sync and backup server.
-     *
-     * The default value is `https://evolu.world`.
-     */
-    syncUrl: string;
-    /**
-     * 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`.
-     */
-    name: string;
-    /**
-     * Maximum physical clock drift allowed in ms.
-     *
-     * The default value is 5 * 60 * 1000 (5 minutes).
-     */
-    maxDrift: number;
-    /**
-     * Setting the minimum log level. The default value is `none`.
-     *
-     * For development, use `trace` to log all events and `debug` to log only
-     * events with values. For production, use `warning`.
-     */
-    minimumLogLevel: "none" | "trace" | "debug" | "warning";
-    /**
-     * Enables websocket connection
-     *
-     * If set to true runs a websocket connection on the sync url
-     */
-    enableWebsocketConnection?: true;
-    /**
-     * Allows to reuse websocket connections for multiple database setup
-     *
-     * Works INSTEAD of enableWebsocket and if set overrides enableWebsocket this
-     * attaches the database to a connection produced by a call back from another
-     * database that has enableWebsocketConnection
-     */
-    externalWebsocketConnection?: WebSocket;
-}
-export declare const Config: Context.Tag<Config, Config>;
-export declare const defaultConfig: Config;
-/** https://effect.website/docs/guides/runtime */
-export declare const createRuntime: (partialConfig?: Partial<Config>) => ManagedRuntime.ManagedRuntime<Config, never>;
-//# sourceMappingURL=Config.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Config.d.ts","sourceRoot":"","sources":["../../src/Config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAI1C,OAAO,KAAK,cAAc,MAAM,uBAAuB,CAAC;AAGxD,MAAM,WAAW,MAAM;IACrB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,CAAC;IAExD;;;;OAIG;IACH,yBAAyB,CAAC,EAAE,IAAI,CAAC;IAEjC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,SAAS,CAAC;CACzC;AAED,eAAO,MAAM,MAAM,6BAAuC,CAAC;AAE3D,eAAO,MAAM,aAAa,EAAE,MAM3B,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,aAAa,mBACR,OAAO,CAAC,MAAM,CAAC,KAC9B,cAAc,CAAC,cAAc,CAAC,MAAM,EAAE,KAAK,CAsB7C,CAAC"}