@evolu/common 6.0.1-preview.3 → 6.0.1-preview.31

package/src/Brand.ts

@@ -0,0 +1,75 @@
+/**
+ * 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;

package/src/Buffer.ts

@@ -6,7 +6,7 @@ export {
   concatBytes,
   hexToBytes,
   utf8ToBytes,
-} from "@noble/ciphers/utils";
+} from "@noble/ciphers/utils.js";
 
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
@@ -116,10 +116,10 @@ export const createBuffer = (
   let value = arrayLike
     ? new globalThis.Uint8Array(arrayLike)
     : new globalThis.Uint8Array(512);
-  let length = (arrayLike ? arrayLike.length : 0) as NonNegativeInt;
+  let length = NonNegativeInt.orThrow(arrayLike ? arrayLike.length : 0);
 
   const buffer: Buffer = {
-    getCapacity: () => value.length as NonNegativeInt,
+    getCapacity: () => NonNegativeInt.orThrow(value.length),
 
     getLength: () => length,
 
@@ -132,7 +132,7 @@ export const createBuffer = (
         value.set(oldValue);
       }
       value.set(arg, length);
-      length = (length + arg.length) as NonNegativeInt;
+      length = NonNegativeInt.orThrow(length + arg.length);
     },
 
     shift: () => {
@@ -142,7 +142,7 @@ export const createBuffer = (
       const first = value[0];
       value = value.subarray(1);
       length--;
-      return first as NonNegativeInt;
+      return NonNegativeInt.orThrow(first);
     },
 
     shiftN: (n) => {
@@ -151,7 +151,7 @@ export const createBuffer = (
       }
       const subarray = value.subarray(0, n);
       value = value.subarray(n);
-      length = (length - n) as NonNegativeInt;
+      length = NonNegativeInt.orThrow(length - n);
       return subarray;
     },
 
@@ -165,7 +165,7 @@ export const createBuffer = (
     },
 
     reset: () => {
-      length = 0 as NonNegativeInt;
+      length = NonNegativeInt.orThrow(0);
     },
 
     unwrap: () => value.subarray(0, length),

package/src/Cache.ts

@@ -0,0 +1,85 @@
+/**
+ * 🗄️ Generic cache interface and LRU cache implementation.
+ *
+ * @module
+ */
+
+import { PositiveInt } from "./Type.js";
+
+/**
+ * Generic cache interface providing basic key-value storage operations.
+ *
+ * Keys are compared by reference (standard Map semantics).
+ *
+ * Note: Cache does not extend Map because eviction policies (like in LRU)
+ * violate the Liskov Substitution Principle.
+ */
+export interface Cache<K, V> {
+  /** Checks if a key exists in the cache. */
+  has: (key: K) => boolean;
+
+  /** Retrieves the value for a key, or undefined if not present. */
+  get: (key: K) => V | undefined;
+
+  /** Stores a key-value pair in the cache. */
+  set: (key: K, val: V) => void;
+
+  /** Removes a key from the cache. */
+  delete: (key: K) => void;
+
+  /** Returns a readonly view of the internal Map. */
+  readonly map: ReadonlyMap<K, V>;
+}
+
+/**
+ * Creates a Least Recently Used (LRU) cache with a maximum capacity.
+ *
+ * When the cache reaches capacity, the least recently used entry is evicted.
+ * Both `get` and `set` operations update the access order.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const cache = createLruCache<string, number>(2);
+ * cache.set("a", 1);
+ * cache.set("b", 2);
+ * cache.set("c", 3); // Evicts "a"
+ * cache.has("a"); // false
+ * ```
+ */
+export const createLruCache = <K, V>(capacity: PositiveInt): Cache<K, V> => {
+  const internalMap = new Map<K, V>();
+
+  return {
+    has: (key) => internalMap.has(key),
+
+    get: (key) => {
+      const value = internalMap.get(key);
+      if (value === undefined) return undefined;
+
+      // Move to end (most recently used)
+      internalMap.delete(key);
+      internalMap.set(key, value);
+      return value;
+    },
+
+    set: (key, val) => {
+      // If key exists, delete it first to update order
+      if (internalMap.has(key)) {
+        internalMap.delete(key);
+      } else if (internalMap.size === capacity) {
+        // Evict least recently used (first entry)
+        const firstKey = internalMap.keys().next().value as K;
+        internalMap.delete(firstKey);
+      }
+
+      internalMap.set(key, val);
+    },
+
+    delete: (key) => {
+      internalMap.delete(key);
+    },
+
+    map: internalMap,
+  };
+};

package/src/Callbacks.ts

@@ -1,43 +1,83 @@
-import { NanoIdLibDep } from "./NanoId.js";
-import { Brand } from "./Types.js";
+import { Brand } from "./Brand.js";
+import { RandomBytesDep } from "./Crypto.js";
+import { Result } from "./Result.js";
+import { createId, Id } from "./Type.js";
 
 /**
- * Manages one-time callback functions.
+ * Request-response correlation for callbacks across boundaries.
  *
- * Allows registering callbacks with a unique ID and executing them once with an
- * optional argument. Executed callbacks are automatically removed.
+ * Stores callbacks with unique IDs and executes 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.
+ * This is useful for correlating asynchronous request-response operations
+ * across boundaries where callback functions cannot be passed directly (e.g.,
+ * web workers, message queues).
+ *
+ * The `execute` method intentionally does not use try-catch or {@link Result}
+ * because it's the callback's responsibility to handle its own errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // No-argument callbacks
+ * const callbacks = createCallbacks(deps);
+ * const id = callbacks.register(() => console.log("called"));
+ * callbacks.execute(id);
+ *
+ * // With argument callbacks
+ * const stringCallbacks = createCallbacks<string>(deps);
+ * const id = stringCallbacks.register((value) => {
+ *   console.log(value);
+ * });
+ * stringCallbacks.execute(id, "hello");
+ *
+ * // Promise.withResolvers pattern
+ * const promiseCallbacks = createCallbacks<string>(deps);
+ * const { promise, resolve } = Promise.withResolvers<string>();
+ * const id = promiseCallbacks.register(resolve);
+ * promiseCallbacks.execute(id, "resolved value");
+ * await promise; // "resolved value"
+ * ```
+ *
+ * @template T - The type of argument passed to callbacks (defaults to undefined
+ *   for no-argument callbacks)
  */
-export interface Callbacks {
+export interface Callbacks<T = undefined> {
   /** Registers a callback function and returns a unique ID. */
-  readonly register: (callback: (arg?: unknown) => void) => CallbackId;
+  readonly register: (callback: (arg: T) => void) => CallbackId;
 
   /** Executes and removes a callback associated with the given ID. */
-  readonly execute: (id: CallbackId, arg?: unknown) => void;
+  readonly execute: T extends undefined
+    ? (id: CallbackId) => undefined
+    : (id: CallbackId, arg: T) => undefined;
 }
 
-export type CallbackId = string & Brand<"CallbackId">;
+/** Unique identifier for a callback in {@link Callbacks}. */
+export type CallbackId = Id & Brand<"Callback">;
 
-export const createCallbacks = (deps: NanoIdLibDep): Callbacks => {
-  const callbackMap = new Map<CallbackId, (arg?: unknown) => void>();
+/** Creates a new {@link Callbacks}. */
+export const createCallbacks = <T = undefined>(
+  deps: RandomBytesDep,
+): Callbacks<T> => {
+  const callbackMap = new Map<CallbackId, (arg: T) => void>();
 
-  const callbacks: Callbacks = {
+  return {
     register: (callback) => {
-      const id = deps.nanoIdLib.nanoid() as CallbackId;
+      const id = createId<"Callback">(deps);
       callbackMap.set(id, callback);
       return id;
     },
 
-    execute: (id, arg) => {
+    execute: (id: CallbackId, ...args: T extends undefined ? [] : [T]) => {
       const callback = callbackMap.get(id);
-      if (callback) {
-        callbackMap.delete(id);
-        callback(arg);
+      if (!callback) return;
+      callbackMap.delete(id);
+      if (args.length === 0) {
+        // Called without argument (undefined case)
+        (callback as () => void)();
+      } else {
+        callback(args[0]);
       }
     },
-  };
-
-  return callbacks;
+  } as Callbacks<T>;
 };

package/src/Console.ts

@@ -13,14 +13,28 @@
  * ### Example
  *
  * ```ts
- * deps.console.log("[db]", "send data message", protocolMessage);
+ * deps.console.log("[evolu]", "createEvoluInstance", { name });
  * ```
  *
  * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
- * quickly find relevant messages.
+ * quickly find relevant messages. In Node.js, use `grep` to filter output:
  *
- * **Warning**: If you encounter platform-specific issues or missing methods,
- * please contribute a PR with details about the environment and behavior.
+ * ```bash
+ * node app.js | grep "\[relay\]"         # Show only relay logs
+ * node app.js | grep -E "\[db\]|\[sql\]" # Show db and sql logs
+ * node app.js | grep -v "\[debug\]"      # Hide debug logs
+ * ```
+ *
+ * Or add to package.json scripts:
+ *
+ * ```json
+ * {
+ *   "scripts": {
+ *     "dev:relay": "node app.js | grep \"\\[relay\\]\"",
+ *     "dev:db": "node app.js | grep -E \"\\[db\\]|\\[sql\\]\""
+ *   }
+ * }
+ * ```
  *
  * @module
  */
@@ -51,6 +65,9 @@ export interface Console {
   /** Starts a timer with an optional label */
   time: (label?: string) => void;
 
+  /** Logs the elapsed time for a timer without ending it */
+  timeLog: (label?: string, ...data: Array<any>) => void;
+
   /** Ends a timer and logs the elapsed time */
   timeEnd: (label?: string) => void;
 
@@ -69,9 +86,6 @@ export interface Console {
   /** Writes a message if the value is falsy, otherwise does nothing */
   assert: (value: any, message?: string, ...optionalParams: Array<any>) => void;
 
-  /** Logs the elapsed time for a timer without ending it */
-  timeLog: (label?: string, ...data: Array<any>) => void;
-
   /** Prints a stack trace with an optional message */
   trace: (message?: any, ...optionalParams: Array<any>) => void;
 }
@@ -121,6 +135,10 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
       // eslint-disable-next-line no-console
       if (instance.enabled) console.time(label);
     },
+    timeLog: (label, ...data) => {
+      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+      if (instance.enabled) console.timeLog(label, ...data);
+    },
     timeEnd: (label) => {
       // eslint-disable-next-line no-console
       if (instance.enabled) console.timeEnd(label);
@@ -145,10 +163,6 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
       // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
       if (instance.enabled) console.assert(value, message, ...optionalParams);
     },
-    timeLog: (label, ...data) => {
-      // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
-      if (instance.enabled) console.timeLog(label, ...data);
-    },
     trace: (message, ...optionalParams) => {
       // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
       if (instance.enabled) console.trace(message, ...optionalParams);
@@ -157,3 +171,69 @@ export const createConsole = (config: ConsoleConfig = {}): Console => {
 
   return instance;
 };
+
+export interface ConsoleWithTimeConfig extends ConsoleConfig {
+  /**
+   * Type of timestamp to prepend to log messages.
+   *
+   * - 'absolute': Shows actual time (e.g., "14:32:15.234")
+   * - 'relative': Shows time since console creation (e.g., "+1.234s")
+   */
+  readonly timestampType: "absolute" | "relative";
+}
+
+/** Creates a console instance with timestamp prefixes. */
+export const createConsoleWithTime = (
+  config: ConsoleWithTimeConfig = { timestampType: "relative" },
+): Console => {
+  const console = createConsole(config);
+  const startTime = performance.now();
+
+  const getTimestamp = (): string => {
+    if (config.timestampType === "relative") {
+      const elapsed = (performance.now() - startTime) / 1000;
+
+      // Format for better readability at different time scales
+      if (elapsed < 60) {
+        // Under 1 minute: show seconds with millisecond precision
+        return `+${elapsed.toFixed(3)}s`;
+      } else if (elapsed < 3600) {
+        // 1 minute to 1 hour: show minutes and seconds with millisecond precision
+        const minutes = Math.floor(elapsed / 60);
+        const seconds = (elapsed % 60).toFixed(3);
+        return `+${minutes}m${seconds}s`;
+      } else {
+        // Over 1 hour: show hours, minutes, and seconds with millisecond precision
+        const hours = Math.floor(elapsed / 3600);
+        const minutes = Math.floor((elapsed % 3600) / 60);
+        const seconds = ((elapsed % 3600) % 60).toFixed(3);
+        return `+${hours}h${minutes}m${seconds}s`;
+      }
+    } else {
+      // Absolute time - format as HH:MM:SS.mmm
+      const now = new Date();
+      const hours = now.getHours().toString().padStart(2, "0");
+      const minutes = now.getMinutes().toString().padStart(2, "0");
+      const seconds = now.getSeconds().toString().padStart(2, "0");
+      const milliseconds = now.getMilliseconds().toString().padStart(3, "0");
+      return `${hours}:${minutes}:${seconds}.${milliseconds}`;
+    }
+  };
+
+  const withTimestamp =
+    (fn: (...args: Array<any>) => void) =>
+    (...args: Array<any>) => {
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+      fn(`[${getTimestamp()}]`, ...args);
+    };
+
+  // Override methods that should have timestamps
+  console.log = withTimestamp(console.log);
+  console.info = withTimestamp(console.info);
+  console.warn = withTimestamp(console.warn);
+  console.error = withTimestamp(console.error);
+  console.debug = withTimestamp(console.debug);
+  console.trace = withTimestamp(console.trace);
+
+  return console;
+};