@evolu/common 7.4.0 → 8.0.0-next.0

package/src/Object.ts

@@ -1,28 +1,77 @@
+/**
+ * Object utilities.
+ *
+ * @module
+ */
+
+/**
+ * A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
+ * types (e.g., in {@link mapObject}).
+ */
+export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
+
 /**
  * Checks if a value is a plain object (e.g., created with `{}` or `Object`).
  *
+ * Accepts objects with `Object.prototype` and objects with a `null` prototype
+ * created via `Object.create(null)`. Rejects class instances and other built-in
+ * objects because their prototype chain includes an application-specific or
+ * built-in prototype before `Object.prototype`.
+ *
+ * The prototype-chain check uses structure instead of `prototype ===
+ * Object.prototype` so it also works for plain objects coming from another
+ * JavaScript realm.
+ *
  * ### Example
  *
  * ```ts
  * isPlainObject({}); // true
+ * isPlainObject(Object.create(null)); // true
  * isPlainObject(new Date()); // false
+ * isPlainObject(new (class Example {})()); // false
  * isPlainObject([]); // false
  * isPlainObject(null); // false
  * ```
  */
 export const isPlainObject = (
   value: unknown,
-): value is Record<string, unknown> =>
-  Object.prototype.toString.call(value) === "[object Object]";
+): value is Record<string, unknown> => {
+  if (Object.prototype.toString.call(value) !== "[object Object]") {
+    return false;
+  }
+
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  return prototype === null || Object.getPrototypeOf(prototype) === null;
+};
 
 /**
- * A read-only `Record<K, V>` with `K extends keyof any` to preserve branded key
- * types (e.g., in {@link mapObject}).
+ * Checks if a value is a function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isFunction(() => {}); // true
+ * isFunction(function () {}); // true
+ * isFunction({}); // false
+ * ```
  */
-export type ReadonlyRecord<K extends keyof any, V> = Readonly<Record<K, V>>;
+export const isFunction = (value: unknown): value is globalThis.Function =>
+  typeof value === "function";
 
-// A helper type to remove symbol keys (e.g for branded objects).
-type StringKeyOf<T> = Extract<keyof T, string>;
+/**
+ * Checks if a value is {@link Iterable}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * isIterable([1, 2, 3]); // true
+ * isIterable("abc"); // true
+ * isIterable({}); // false
+ * ```
+ */
+export const isIterable = (value: unknown): value is Iterable<unknown> =>
+  value != null &&
+  typeof (value as Iterable<unknown>)[Symbol.iterator] === "function";
 
 /**
  * Like `Object.entries` but preserves branded keys.
@@ -42,6 +91,51 @@ export const objectToEntries = <T extends Record<string, any>>(
     [StringKeyOf<T>, T[StringKeyOf<T>]]
   > as ReadonlyArray<[StringKeyOf<T>, T[StringKeyOf<T>]]>;
 
+// A helper type to remove symbol keys (e.g for branded objects).
+type StringKeyOf<T> = Extract<keyof T, string>;
+
+/**
+ * Creates an object from key-value pairs, preserving branded key types.
+ *
+ * The inverse of {@link objectToEntries}. Use when you need type-safe
+ * reconstruction of objects with branded keys.
+ *
+ * ### Example
+ *
+ * ```ts
+ * type UserId = string & { readonly __brand: "UserId" };
+ * const entries: ReadonlyArray<[UserId, string]> = [
+ *   ["u1" as UserId, "Alice"],
+ * ];
+ * const users = objectFromEntries(entries); // ReadonlyRecord<UserId, string>
+ * ```
+ */
+export const objectFromEntries = <K extends string, V>(
+  entries: Iterable<readonly [K, V]>,
+): ReadonlyRecord<K, V> => Object.fromEntries(entries) as ReadonlyRecord<K, V>;
+
+/**
+ * Creates an object by mapping keys to values.
+ *
+ * The inverse of `Object.keys` — instead of extracting keys from an object,
+ * builds an object from keys with a mapper function.
+ *
+ * ### Example
+ *
+ * ```ts
+ * objectFrom(["en", "fr", "de"], loadTranslations);
+ * // { en: Translations, fr: Translations, de: Translations }
+ *
+ * objectFrom(["trace", "debug", "log"], (level) => createHandler(level));
+ * // { trace: Handler, debug: Handler, log: Handler }
+ * ```
+ */
+export const objectFrom = <K extends string, V>(
+  keys: ReadonlyArray<K>,
+  getValue: (key: K) => V,
+): ReadonlyRecord<K, V> =>
+  Object.fromEntries(keys.map((k) => [k, getValue(k)])) as ReadonlyRecord<K, V>;
+
 /**
  * Maps a `ReadonlyRecord<K, V>` to a new `ReadonlyRecord<K, U>`, preserving
  * branded key types (e.g., `type Id = 'id' & string`) lost by `Object.entries`.
@@ -50,13 +144,15 @@ export const objectToEntries = <T extends Record<string, any>>(
 export const mapObject = <K extends string, V, U>(
   record: ReadonlyRecord<K, V>,
   fn: (value: V, key: K) => U,
-): ReadonlyRecord<K, U> =>
-  Object.fromEntries(
-    Object.entries(record).map(([key, value]) => [
-      key,
-      fn(value as V, key as K),
-    ]),
-  ) as ReadonlyRecord<K, U>;
+): ReadonlyRecord<K, U> => {
+  const out = Object.create(null) as Record<K, U>;
+
+  for (const key in record) {
+    out[key as K] = fn(record[key as K], key as K);
+  }
+
+  return out as ReadonlyRecord<K, U>;
+};
 
 /** Conditionally excludes a property from an object. */
 export const excludeProp = <T extends object, K extends keyof T>(
@@ -90,6 +186,16 @@ export const createRecord = <K extends string = string, V = unknown>(): Record<
   V
 > => Object.create(null) as Record<K, V>;
 
+/**
+ * An empty readonly record.
+ *
+ * Use as a default or initial value to avoid allocating new empty records.
+ *
+ * @group Constants
+ */
+export const emptyRecord: Readonly<Record<string, never>> =
+  /*#__PURE__*/ createRecord();
+
 /**
  * Safely gets a property from a record, returning `undefined` if the key
  * doesn't exist.
@@ -107,5 +213,38 @@ export const createRecord = <K extends string = string, V = unknown>(): Record<
  */
 export const getProperty = <K extends string, V>(
   record: ReadonlyRecord<K, V>,
-  key: string,
-): V | undefined => (key in record ? record[key as K] : undefined);
+  key: K,
+): V | undefined => (key in record ? record[key] : undefined);
+
+/**
+ * A disposable wrapper around `URL.createObjectURL` that automatically revokes
+ * the URL when disposed. Use with the `using` declaration for automatic
+ * cleanup.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const blob = new Blob(["hello"], { type: "text/plain" });
+ * using objectUrl = createObjectURL(blob);
+ * console.log(objectUrl.url); // blob:...
+ * // URL.revokeObjectURL is automatically called when the scope ends
+ * ```
+ *
+ * This ensures the URL is always revoked when the scope ends, even if an error
+ * occurs, preventing memory leaks from unreleased blob URLs.
+ */
+export interface ObjectURL extends Disposable {
+  /** The object URL string created by `URL.createObjectURL`. */
+  readonly url: string;
+}
+
+/** Creates a disposable {@link ObjectURL} for the given blob. */
+export const createObjectURL = (blob: Blob): ObjectURL => {
+  const url = URL.createObjectURL(blob);
+  return {
+    url,
+    [Symbol.dispose]: () => {
+      URL.revokeObjectURL(url);
+    },
+  };
+};

package/src/Option.ts

@@ -0,0 +1,74 @@
+/**
+ * Optional value container.
+ *
+ * Distinguishes absence from values like `null` or `undefined`.
+ *
+ * Use Option when the value itself can be `null` or `undefined`. For APIs where
+ * `null` means "not found", just use `T | null` directly.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // A cache that can store any value, including null and undefined
+ * const cache = new Map<string, Option<unknown>>();
+ *
+ * const get = (key: string): Option<unknown> => cache.get(key) ?? none;
+ *
+ * cache.set("a", some(null)); // Stored null
+ * cache.set("b", some(undefined)); // Stored undefined
+ *
+ * isSome(get("a")); // true — value is null
+ * isSome(get("b")); // true — value is undefined
+ * isNone(get("c")); // true — key doesn't exist
+ * ```
+ *
+ * @module
+ */
+
+/** Optional value. */
+import type { Typed } from "./Type.js";
+
+/** Optional value. */
+export type Option<T> = Some<T> | None;
+
+/** Present value in an {@link Option}. */
+export interface Some<out T> extends Typed<"Some"> {
+  readonly value: T;
+}
+
+/** Absent value in an {@link Option}. */
+export interface None extends Typed<"None"> {}
+
+/**
+ * Extracts the value type from an {@link Option} or {@link Some}.
+ *
+ * @group Utilities
+ */
+export type InferOption<O extends Option<any>> =
+  O extends Some<infer T> ? T : never;
+
+/** Creates a {@link Some}. */
+export const some = <T>(value: T): Option<T> => ({
+  type: "Some",
+  value,
+});
+
+/** Shared {@link None} instance. */
+export const none: None = { type: "None" };
+
+/** Type guard for {@link Some}. */
+export const isSome = <T>(option: Option<T>): option is Some<T> =>
+  option.type === "Some";
+
+/** Type guard for {@link None}. */
+export const isNone = <T>(option: Option<T>): option is None =>
+  option.type === "None";
+
+/**
+ * Converts a nullable value to an {@link Option}.
+ *
+ * `null` and `undefined` become {@link none}.
+ */
+export const fromNullable = <T>(
+  value: T | null | undefined,
+): Option<NonNullable<T>> => (value == null ? none : some(value));

package/src/Order.ts

@@ -1,3 +1,9 @@
+/**
+ * Ordering and comparison utilities.
+ *
+ * @module
+ */
+
 /**
  * Compares two values of type `A` and returns their ordering.
  *
@@ -61,7 +67,9 @@ export const reverseOrder =
  * ["c", "b", "a"].toSorted(orderString); // ["a", "b", "c"]
  * ```
  */
-export const orderString: Order<string> = createOrder((a, b) => a < b);
+export const orderString: Order<string> = /*#__PURE__*/ createOrder(
+  (a, b) => a < b,
+);
 
 /**
  * An order for numbers in ascending order.
@@ -78,7 +86,7 @@ export const orderString: Order<string> = createOrder((a, b) => a < b);
  * reverseOrder(orderNumber)(1, 1); // 0
  * ```
  */
-export const orderNumber = createOrder<number>((a, b) => a < b);
+export const orderNumber = /*#__PURE__*/ createOrder<number>((a, b) => a < b);
 
 /**
  * An order for bigints in ascending order.
@@ -92,7 +100,7 @@ export const orderNumber = createOrder<number>((a, b) => a < b);
  * [2n, 1n, 3n].toSorted(orderBigInt); // [1n, 2n, 3n]
  * ```
  */
-export const orderBigInt = createOrder<bigint>((a, b) => a < b);
+export const orderBigInt = /*#__PURE__*/ createOrder<bigint>((a, b) => a < b);
 
 /** An {@link Order} for Uint8Array. */
 export const orderUint8Array: Order<Uint8Array> = (a, b) => {

package/src/Platform.ts

@@ -1,9 +1,14 @@
-/** Detects if the code is running in React Native environment. */
-export const isReactNative =
-  typeof navigator !== "undefined" &&
-  "product" in navigator &&
-  // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-  (navigator as any).product === "ReactNative";
+/**
+ * Platform runtime utilities and capability abstractions.
+ *
+ * @module
+ */
+
+/** Returns true if running in React Native with Hermes engine. */
+export const isHermes = "HermesInternal" in globalThis;
+
+/** Returns true if running in a server environment (no DOM). */
+export const isServer = typeof document === "undefined";
 
 /**
  * Detects if Node.js Buffer is available and should be used.
@@ -17,4 +22,35 @@ export const isReactNative =
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
 export const hasNodeBuffer =
-  !isReactNative && typeof globalThis.Buffer !== "undefined";
+  !isHermes && typeof globalThis.Buffer !== "undefined";
+
+/**
+ * FlushSync is for libraries like React to flush updates synchronously inside
+ * the provided callback to ensure the DOM is updated immediately.
+ *
+ * For example, with React, when we want to focus on an element rendered as a
+ * result of a mutation, Evolu ensures all DOM changes are flushed synchronously
+ * if an onComplete callback is used.
+ *
+ * https://react.dev/reference/react-dom/flushSync
+ */
+export type FlushSync = (callback: () => void) => void;
+
+export interface FlushSyncDep {
+  readonly flushSync: FlushSync;
+}
+
+/**
+ * Reload the app in a platform-specific way.
+ *
+ * Use this after purging persistent storage to clear in-memory state and ensure
+ * the app starts fresh. It does not purge storage itself.
+ *
+ * - Web: Redirects to the specified URL (defaults to `/`)
+ * - React Native: Restarts the app (URL ignored)
+ */
+export type ReloadApp = (url?: string) => void;
+
+export interface ReloadAppDep {
+  readonly reloadApp: ReloadApp;
+}