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

package/dist/src/Promise.d.ts

@@ -1,180 +0,0 @@
-import { Result } from "./Result.js";
-import { Predicate } from "./Types.js";
-/**
- * Helper function to delay execution for a specified number of milliseconds.
- *
- * ### Example
- *
- * ```ts
- * await wait(10);
- * ```
- */
-export declare const wait: (ms: number) => Promise<Result<void, never>>;
-/** Options for configuring retry behavior. */
-export interface RetryOptions<E> {
-    /**
-     * Maximum number of retry attempts after the initial attempt (default: 3).
-     * For example, with maxRetries = 3, the function will be called up to 4 times
-     * (1 initial attempt + 3 retries).
-     */
-    maxRetries?: number;
-    /**
-     * Initial delay between retry attempts in milliseconds (default: 100). This
-     * is the delay after the first failed attempt. Subsequent delays increase
-     * exponentially according to the factor option.
-     */
-    initialDelay?: number;
-    /**
-     * Maximum delay between retry attempts in milliseconds (default: 10000). This
-     * caps the exponential backoff to prevent extremely long delays after many
-     * retries.
-     */
-    maxDelay?: number;
-    /**
-     * Multiplier that determines how quickly the delay increases (default: 2).
-     * With the default value, each successive delay is twice as long as the
-     * previous one (e.g., 100ms, 200ms, 400ms, 800ms, etc).
-     */
-    factor?: number;
-    /**
-     * Random jitter factor between 0 and 1 (default: 0.1). Adds randomness to
-     * delay times to prevent retry storms in distributed systems.
-     */
-    jitter?: number;
-    /**
-     * Optional AbortSignal to cancel retries. If the signal is aborted, the retry
-     * operation stops and returns a RetryAbortError.
-     */
-    signal?: AbortSignal;
-    /**
-     * Optional predicate to determine if an error should be retried. Returns true
-     * if the error is retryable, false otherwise. This allows selectively
-     * retrying only certain types of errors. By default, all errors are
-     * considered retryable.
-     */
-    retryable?: Predicate<E>;
-    /**
-     * Optional callback called before each retry attempt. Receives the error that
-     * caused the retry, the current attempt number (starting at 1), and the delay
-     * in milliseconds before the next attempt.
-     */
-    onRetry?: (error: E, attempt: number, delay: number) => void;
-}
-/** Error representing a retry operation that failed after multiple attempts. */
-export interface RetryError<E> {
-    readonly type: "RetryError";
-    /** The original error that caused the retry to fail */
-    readonly cause: E;
-    /** Number of retry attempts made */
-    readonly attempts: number;
-}
-/** Error representing a retry operation that was aborted. */
-export interface RetryAbortError {
-    readonly type: "RetryAbortError";
-    readonly abortedBeforeExecution: boolean;
-}
-/**
- * Executes a function with retry logic using exponential backoff and jitter.
- *
- * ### Example with Result-based API
- *
- * ```ts
- * interface ApiError {
- *   type: "ApiError";
- *   statusCode: number;
- * }
- *
- * const fetchData = async (
- *   url: string,
- * ): Promise<Result<Data, ApiError>> => {
- *   // Implementation that returns Result
- * };
- *
- * const result = await retry(
- *   async () => fetchData("https://api.example.com/data"),
- *   {
- *     maxRetries: 5,
- *     initialDelay: 200,
- *     // Only retry on specific status codes
- *     retryable: (error) =>
- *       error.type === "ApiError" && [429, 503].includes(error.statusCode),
- *   },
- * );
- *
- * if (!result.ok) {
- *   if (result.error.type === "RetryAbortError") {
- *     console.log("Operation was aborted");
- *   } else {
- *     console.log(`Failed after ${result.error.attempts} attempts`);
- *   }
- *   return;
- * }
- *
- * // Use result.value
- * ```
- *
- * ### Example with tryAsync for exception-based API
- *
- * ```ts
- * interface FetchError {
- *   type: "FetchError";
- *   message: string;
- * }
- *
- * const controller = new AbortController();
- *
- * const result = await retry(
- *   async () =>
- *     tryAsync(
- *       async () => {
- *         const response = await fetch("https://api.example.com/data", {
- *           signal: controller.signal,
- *         });
- *
- *         if (!response.ok) {
- *           throw new Error(`HTTP error ${response.status}`);
- *         }
- *
- *         return await response.json();
- *       },
- *       (error): FetchError => ({
- *         type: "FetchError",
- *         message: String(error),
- *       }),
- *     ),
- *   {
- *     maxRetries: 3,
- *     signal: controller.signal,
- *   },
- * );
- * ```
- *
- * ## HTTP Request Recommendations
- *
- * For HTTP requests, configure the `retryable` option to only retry on
- * appropriate errors:
- *
- * - **DO retry**: 429 (Too Many Requests), 503 (Service Unavailable), network
- *   errors
- * - **DON'T retry**: 4xx client errors (except 429), most 5xx server errors
- */
-export declare const retry: <T, E>(fn: () => Promise<Result<T, E>>, options?: RetryOptions<E>) => Promise<Result<T, RetryError<E> | RetryAbortError>>;
-export interface TimeoutError {
-    readonly type: "TimeoutError";
-    readonly timeoutMs: number;
-}
-/**
- * Wraps an async function with a timeout, returning {@link Result} that fails
- * with {@link TimeoutError} if the timeout is exceeded. The provided function
- * must accept an AbortSignal and return a Result.
- *
- * ### Example
- *
- * ```ts
- * const fetchWithTimeout = () =>
- *   withTimeout((signal) => fetch("url", signal), 5000);
- * const result = await retry(fetchWithTimeout, { maxRetries: 3 });
- * ```
- */
-export declare const withTimeout: <T, E>(fn: (signal: AbortSignal) => Promise<Result<T, E>>, timeoutMs: number) => Promise<Result<T, E | TimeoutError>>;
-//# sourceMappingURL=Promise.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"Promise.d.ts","sourceRoot":"","sources":["../../src/Promise.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAW,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;GAQG;AACH,eAAO,MAAM,IAAI,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAK1D,CAAC;AAEJ,8CAA8C;AAC9C,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IAErB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IAEzB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9D;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,oCAAoC;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,6DAA6D;AAC7D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,sBAAsB,EAAE,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,eAAO,MAAM,KAAK,GAAU,CAAC,EAAE,CAAC,EAC9B,IAAI,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAC/B,UAAS,YAAY,CAAC,CAAC,CAAM,KAC5B,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CA2EpD,CAAC;AAEF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EAAE,CAAC,EACpC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAClD,WAAW,MAAM,KAChB,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAerC,CAAC"}

package/dist/src/Promise.js

@@ -1,176 +0,0 @@
-import { constTrue } from "./Function.js";
-import { err, ok } from "./Result.js";
-/**
- * Helper function to delay execution for a specified number of milliseconds.
- *
- * ### Example
- *
- * ```ts
- * await wait(10);
- * ```
- */
-export const wait = (ms) => new Promise((resolve) => setTimeout(() => {
-    resolve(ok());
-}, ms));
-/**
- * Executes a function with retry logic using exponential backoff and jitter.
- *
- * ### Example with Result-based API
- *
- * ```ts
- * interface ApiError {
- *   type: "ApiError";
- *   statusCode: number;
- * }
- *
- * const fetchData = async (
- *   url: string,
- * ): Promise<Result<Data, ApiError>> => {
- *   // Implementation that returns Result
- * };
- *
- * const result = await retry(
- *   async () => fetchData("https://api.example.com/data"),
- *   {
- *     maxRetries: 5,
- *     initialDelay: 200,
- *     // Only retry on specific status codes
- *     retryable: (error) =>
- *       error.type === "ApiError" && [429, 503].includes(error.statusCode),
- *   },
- * );
- *
- * if (!result.ok) {
- *   if (result.error.type === "RetryAbortError") {
- *     console.log("Operation was aborted");
- *   } else {
- *     console.log(`Failed after ${result.error.attempts} attempts`);
- *   }
- *   return;
- * }
- *
- * // Use result.value
- * ```
- *
- * ### Example with tryAsync for exception-based API
- *
- * ```ts
- * interface FetchError {
- *   type: "FetchError";
- *   message: string;
- * }
- *
- * const controller = new AbortController();
- *
- * const result = await retry(
- *   async () =>
- *     tryAsync(
- *       async () => {
- *         const response = await fetch("https://api.example.com/data", {
- *           signal: controller.signal,
- *         });
- *
- *         if (!response.ok) {
- *           throw new Error(`HTTP error ${response.status}`);
- *         }
- *
- *         return await response.json();
- *       },
- *       (error): FetchError => ({
- *         type: "FetchError",
- *         message: String(error),
- *       }),
- *     ),
- *   {
- *     maxRetries: 3,
- *     signal: controller.signal,
- *   },
- * );
- * ```
- *
- * ## HTTP Request Recommendations
- *
- * For HTTP requests, configure the `retryable` option to only retry on
- * appropriate errors:
- *
- * - **DO retry**: 429 (Too Many Requests), 503 (Service Unavailable), network
- *   errors
- * - **DON'T retry**: 4xx client errors (except 429), most 5xx server errors
- */
-export const retry = async (fn, options = {}) => {
-    const { maxRetries = 3, initialDelay = 100, maxDelay = 10000, factor = 2, jitter = 0.1, signal, retryable = constTrue, onRetry, } = options;
-    let attempt = 0;
-    if (signal?.aborted) {
-        return err({ type: "RetryAbortError", abortedBeforeExecution: true });
-    }
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const result = await fn();
-        if (result.ok) {
-            return result;
-        }
-        attempt += 1;
-        if (attempt > maxRetries || !retryable(result.error)) {
-            return err({
-                type: "RetryError",
-                cause: result.error,
-                attempts: attempt,
-            });
-        }
-        // Calculate delay with exponential backoff
-        const exponentialDelay = initialDelay * Math.pow(factor, attempt);
-        const cappedDelay = Math.min(exponentialDelay, maxDelay);
-        // Apply jitter to prevent thundering herd problem
-        const randomFactor = 1 - jitter + Math.random() * jitter * 2;
-        const delay = Math.floor(cappedDelay * randomFactor);
-        if (onRetry) {
-            onRetry(result.error, attempt, delay);
-        }
-        if (signal?.aborted) {
-            return err({ type: "RetryAbortError", abortedBeforeExecution: false });
-        }
-        // Wait with abort support
-        if (signal) {
-            const abortPromise = new Promise((resolve) => {
-                const onAbort = () => {
-                    resolve(err({ type: "RetryAbortError", abortedBeforeExecution: false }));
-                };
-                signal.addEventListener("abort", onAbort, { once: true });
-            });
-            const delayPromise = wait(delay);
-            const raceResult = await Promise.race([abortPromise, delayPromise]);
-            if (!raceResult.ok) {
-                return raceResult;
-            }
-        }
-        else {
-            await wait(delay);
-        }
-    }
-};
-/**
- * Wraps an async function with a timeout, returning {@link Result} that fails
- * with {@link TimeoutError} if the timeout is exceeded. The provided function
- * must accept an AbortSignal and return a Result.
- *
- * ### Example
- *
- * ```ts
- * const fetchWithTimeout = () =>
- *   withTimeout((signal) => fetch("url", signal), 5000);
- * const result = await retry(fetchWithTimeout, { maxRetries: 3 });
- * ```
- */
-export const withTimeout = async (fn, timeoutMs) => {
-    const controller = new AbortController();
-    const signal = controller.signal;
-    const timeoutId = setTimeout(() => {
-        controller.abort();
-    }, timeoutMs);
-    const result = await fn(signal);
-    clearTimeout(timeoutId);
-    if (signal.aborted) {
-        return err({ type: "TimeoutError", timeoutMs });
-    }
-    return result;
-};

package/src/Callbacks.ts

@@ -1,43 +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 const createCallbacks = (deps: NanoIdLibDep): Callbacks => {
-  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
-
-  const callbacks: Callbacks = {
-    register: (callback) => {
-      const id = deps.nanoIdLib.nanoid() as CallbackId;
-      callbackMap.set(id, callback);
-      return id;
-    },
-
-    execute: (id, arg) => {
-      const callback = callbackMap.get(id);
-      if (callback) {
-        callbackMap.delete(id);
-        callback(arg);
-      }
-    },
-  };
-
-  return callbacks;
-};

package/src/Evolu/Config.ts

@@ -1,83 +0,0 @@
-import { ConsoleConfig } from "../Console.js";
-import { getOrThrow } from "../Result.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 const defaultConfig: Config = {
-  name: getOrThrow(SimpleName.fromParent("Evolu")),
-  syncUrl: "https://free.evoluhq.com",
-  reloadUrl: "/",
-  maxDrift: 5 * 60 * 1000,
-  enableLogging: false,
-};

package/src/Evolu/Kysely.ts

@@ -1,38 +0,0 @@
-import {
-  CreateIndexBuilder,
-  DummyDriver,
-  Kysely,
-  SqliteAdapter,
-  SqliteQueryCompiler,
-} from "kysely";
-import { DbIndex } from "./Db.js";
-
-// 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(),
-  },
-});
-
-export type DbIndexesBuilder = (
-  create: (indexName: string) => CreateIndexBuilder,
-) => ReadonlyArray<CreateIndexBuilder<any>>;
-
-const createIndex = kysely.schema.createIndex.bind(kysely.schema);
-
-export const createIndexes = (
-  indexes?: DbIndexesBuilder,
-): ReadonlyArray<DbIndex> => {
-  if (!indexes) return [];
-  return indexes(createIndex).map(
-    (index): DbIndex => ({
-      name: index.toOperationNode().name.name,
-      sql: index.compile().sql,
-    }),
-  );
-};

package/src/NanoId.ts

@@ -1,39 +0,0 @@
-import { customAlphabet, nanoid, urlAlphabet } from "nanoid";
-
-/**
- * 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 const createNanoIdLib = (): NanoIdLib => ({
-  urlAlphabet,
-  customAlphabet,
-  nanoid,
-});