@evolu/common 8.9.0 → 8.11.0

package/src/Number.test.ts

@@ -1,6 +1,7 @@
-import { test } from "node:test";
+import { describe, test } from "node:test";
 import {
   assertEqual,
+  assertErr,
   assertFalse,
   assertOk,
   assertSame,
@@ -26,7 +27,16 @@ import {
   percentageToRatio,
 } from "./Number.ts";
 import { err, ok } from "./Result.ts";
-import { assertType, NonNegativeInt, PositiveInt, Ratio } from "./Type.ts";
+import {
+  localizeTypes,
+  object,
+  typeErrorToIssues,
+  type InferErrors,
+  assertType,
+  NonNegativeInt,
+  PositiveInt,
+  Ratio,
+} from "./Type.ts";
 
 test("bounded integer literal types", () => {
   assertType<1 extends Int1To99 ? true : false, true>();
@@ -53,22 +63,76 @@ test("bounded integer literal types", () => {
   assertType<PositiveInt extends Int1To100OrPositiveInt ? true : false, true>();
 });
 
-test("Percentage accepts canonical literals or Ratio", () => {
-  assertType<"0%" extends PercentageLiteral ? true : false, true>();
-  assertType<"25%" extends PercentageLiteral ? true : false, true>();
-  assertType<"12.5%" extends PercentageLiteral ? true : false, true>();
-  assertType<"100%" extends PercentageLiteral ? true : false, true>();
-  assertType<"01%" extends PercentageLiteral ? true : false, false>();
-  assertType<"10.0%" extends PercentageLiteral ? true : false, false>();
-  assertType<"100.1%" extends PercentageLiteral ? true : false, false>();
-  assertType<Ratio extends Percentage ? true : false, true>();
-  assertTrue(PercentageLiteral.is("0%"));
-  assertTrue(PercentageLiteral.is("25%"));
-  assertTrue(PercentageLiteral.is("12.5%"));
-  assertTrue(PercentageLiteral.is("100%"));
-  assertFalse(PercentageLiteral.is("01%"));
-  assertFalse(PercentageLiteral.is("10.0%"));
-  assertFalse(PercentageLiteral.is("100.1%"));
+describe("PercentageLiteral", () => {
+  test("reports a dedicated error with the original validation failure", () => {
+    for (const value of ["101%", "", 1, null, undefined]) {
+      const result = PercentageLiteral.fromUnknown(value);
+      assertErr(result);
+      assertType<typeof result.error.type, "PercentageLiteral">();
+      assertSame(result.error.value, value);
+      assertEqual(result.error.cause.type, "Union");
+      assertEqual(result.error.cause.errors.length, 1);
+    }
+    const result = PercentageLiteral.fromUnknown("101%", { errors: "all" });
+    assertErr(result);
+    assertEqual(result.error.cause.errors.length, 4);
+    assertEqual(
+      PercentageLiteral.formatError(result.error),
+      'The value "101%" is not a percentage literal. Use a value such as "50%" or "12.5%".',
+    );
+    assertType<
+      InferErrors<typeof PercentageLiteral>["type"],
+      "PercentageLiteral"
+    >();
+    assertOk(PercentageLiteral.from("12.5%"), "12.5%");
+    assertEqual(PercentageLiteral.to("12.5%"), "12.5%");
+    // @ts-expect-error PercentageLiteral Input rejects "101%".
+    const _invalidInput: typeof PercentageLiteral.Input = "101%";
+  });
+
+  test("localizes the named error after composition and preserves its path", async () => {
+    const { first } = localizeTypes(
+      { Value: PercentageLiteral },
+      { first: { PercentageLiteral: () => "First message." } },
+    );
+    const { second } = localizeTypes(
+      { Settings: object({ value: first.Value }) },
+      {
+        second: {
+          Object: () => "Object.",
+          PercentageLiteral: () => "Second message.",
+        },
+      },
+    );
+    const result = second.Settings.fromUnknown({ value: "101%" });
+    assertErr(result);
+    assertEqual(second.Settings.formatError(result.error), "Second message.");
+    assertEqual(typeErrorToIssues(second.Settings, result.error), [
+      { path: ["value"], message: "Second message." },
+    ]);
+    assertEqual(
+      await second.Settings["~standard"].validate({ value: "101%" }),
+      { issues: [{ path: ["value"], message: "Second message." }] },
+    );
+  });
+
+  test("accepts canonical literals or Ratio", () => {
+    assertType<"0%" extends PercentageLiteral ? true : false, true>();
+    assertType<"25%" extends PercentageLiteral ? true : false, true>();
+    assertType<"12.5%" extends PercentageLiteral ? true : false, true>();
+    assertType<"100%" extends PercentageLiteral ? true : false, true>();
+    assertType<"01%" extends PercentageLiteral ? true : false, false>();
+    assertType<"10.0%" extends PercentageLiteral ? true : false, false>();
+    assertType<"100.1%" extends PercentageLiteral ? true : false, false>();
+    assertType<Ratio extends Percentage ? true : false, true>();
+    assertTrue(PercentageLiteral.is("0%"));
+    assertTrue(PercentageLiteral.is("25%"));
+    assertTrue(PercentageLiteral.is("12.5%"));
+    assertTrue(PercentageLiteral.is("100%"));
+    assertFalse(PercentageLiteral.is("01%"));
+    assertFalse(PercentageLiteral.is("10.0%"));
+    assertFalse(PercentageLiteral.is("100.1%"));
+  });
 });
 
 test("percentageToRatio converts percentage literals and preserves Ratio", () => {

package/src/Number.ts

@@ -7,10 +7,15 @@
 import type { NonEmptyReadonlyArray } from "./Array.ts";
 import { assertNonEmptyReadonlyArray } from "./Assert.ts";
 import type { IsBranded } from "./Brand.ts";
+import { safelyStringifyUnknownValue } from "./String.ts";
 import type { Result } from "./Result.ts";
 import { err, ok } from "./Result.ts";
 import {
   brand,
+  createTypeWithError,
+  type Type,
+  type TypeError,
+  type UnionError,
   Digit1To9,
   Digit1To99,
   lessThanOrEqualTo,
@@ -98,13 +103,10 @@ export type Int1To100OrPositiveInt = Int1To100 | PositiveInt;
  */
 export type Percentage = PercentageLiteral | Ratio;
 
-/**
- * Percentage literal from `"0%"` to `"100%"`.
- *
- * Decimal literals support one decimal place. Use {@link Ratio} for computed
- * values or greater precision.
- */
-export const PercentageLiteral = /*#__PURE__*/ union(
+export type PercentageLiteral =
+  "0%" | "100%" | `${Digit1To99}%` | `${"0" | Digit1To99}.${Digit1To9}%`;
+
+const percentageLiteralSyntax = /*#__PURE__*/ union(
   "0%",
   "100%",
   /*#__PURE__*/ templateLiteral(Digit1To99, "%"),
@@ -115,7 +117,73 @@ export const PercentageLiteral = /*#__PURE__*/ union(
     "%",
   ),
 );
-export type PercentageLiteral = typeof PercentageLiteral.Output;
+
+/**
+ * Percentage literal Type with compile-time and runtime validation.
+ *
+ * Supported formats:
+ *
+ * - Integers: `0%`, `50%`, `100%` (0-100)
+ * - One decimal place: `0.1%`, `12.5%`, `99.9%` (0.1-99.9)
+ *
+ * The decimal digit is never zero, so `12.0%` must be written as `"12%"`, and
+ * `100%` has no decimal form. For computed values or more precision, use
+ * {@link Ratio} directly.
+ *
+ * See {@link Percentage} for a type that also accepts {@link Ratio}. Use
+ * {@link percentageToRatio} to convert.
+ *
+ * Invalid values produce a {@link PercentageLiteralError}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   PercentageLiteral,
+ * } from "@evolu/common";
+ *
+ * // The TypeScript type accepts valid spellings and rejects the rest.
+ * const literal: PercentageLiteral = "12.5%";
+ * assertType<
+ *   Extract<PercentageLiteral, "101%" | "12.0%" | "12.55%">,
+ *   never
+ * >();
+ *
+ * // The runtime Type validates the same grammar.
+ * assertOk(PercentageLiteral.fromUnknown(literal), "12.5%");
+ * assertFalse(PercentageLiteral.is("101%"));
+ * ```
+ */
+export const PercentageLiteral: Type<
+  "PercentageLiteral",
+  PercentageLiteral,
+  PercentageLiteral,
+  PercentageLiteralError
+> = /*#__PURE__*/ createTypeWithError(
+  "PercentageLiteral",
+  percentageLiteralSyntax,
+  (cause, value): PercentageLiteralError => ({
+    type: "PercentageLiteral",
+    value,
+    cause,
+  }),
+  (error) =>
+    `The value ${safelyStringifyUnknownValue(error.value)} is not a percentage literal. Use a value such as "50%" or "12.5%".`,
+);
+
+/** Error returned when {@link PercentageLiteral} rejects a value. */
+export interface PercentageLiteralError extends TypeError<"PercentageLiteral"> {
+  readonly value: unknown;
+  /**
+   * The underlying union failure, retained for diagnostics.
+   *
+   * With `{ errors: "all" }`, includes every failed alternative.
+   */
+  readonly cause: UnionError;
+}
 
 /** Converts a {@link Percentage} to its numeric {@link Ratio}. */
 export const percentageToRatio = (percentage: Percentage): Ratio =>

package/src/Object.test.ts

@@ -1,5 +1,12 @@
-import { test } from "node:test";
-import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
+import nodeAssert from "node:assert/strict";
+import { describe, it, test } from "node:test";
+import {
+  assertEqual,
+  assertFalse,
+  assertNonNullable,
+  assertSame,
+  assertTrue,
+} from "./Assert.ts";
 
 import type { Brand } from "./Brand.ts";
 import type { ReadonlyRecord } from "./Object.ts";
@@ -8,6 +15,7 @@ import {
   createMutableRecord,
   emptyRecord,
   excludeProp,
+  filterObjectKeys,
   getObjectKind,
   getOwnProp,
   isFunction,
@@ -103,6 +111,22 @@ test("isPlainObject", () => {
   assertFalse(isPlainObject(Object.create(partialObjectPrototype)));
 });
 
+test("isPlainObject checks the root markers of Object.prototype", () => {
+  for (const key of ["hasOwnProperty", "isPrototypeOf"]) {
+    const descriptor = Object.getOwnPropertyDescriptor(Object.prototype, key);
+    assertNonNullable(descriptor);
+    Reflect.deleteProperty(Object.prototype, key);
+    try {
+      assertFalse(isPlainObject({}));
+      assertTrue(isPlainObject(Object.create(null)));
+    } finally {
+      // oxlint-disable-next-line eslint/no-extend-native -- Restores the built-in property this test deleted.
+      Object.defineProperty(Object.prototype, key, descriptor);
+    }
+  }
+  assertTrue(isPlainObject({}));
+});
+
 test("isFunction", () => {
   assertTrue(isFunction(() => {}));
   assertTrue(isFunction(function () {}));
@@ -205,6 +229,117 @@ test("mapObject", () => {
   assertEqual(mapped, { u1: "u1:10", u2: "u2:20" });
 });
 
+describe("filterObjectKeys", () => {
+  it("preserves field types and makes selected fields optional", () => {
+    const symbol = Symbol("ignored");
+    const source = {
+      APP_PORT: "4000",
+      other: 1,
+      42: true,
+      [symbol]: "ignored",
+    };
+    const selected = filterObjectKeys(source, (key) => {
+      assertType<typeof key, string>();
+      return key.startsWith("APP_") || key === "42";
+    });
+    assertType<
+      typeof selected,
+      {
+        readonly APP_PORT?: string;
+        readonly other?: number;
+        readonly 42?: boolean;
+      }
+    >();
+    assertEqual(selected, { APP_PORT: "4000", 42: true });
+    assertFalse(selected === source);
+    assertEqual(
+      filterObjectKeys(source, () => false),
+      {},
+    );
+
+    type UserId = string & Brand<"UserId">;
+    const users: ReadonlyRecord<UserId, number> = { ["u1" as UserId]: 1 };
+    const selectedUsers = filterObjectKeys(users, () => true);
+    assertType<
+      typeof selectedUsers,
+      Readonly<Partial<Record<UserId, number>>>
+    >();
+    assertEqual(selectedUsers, { u1: 1 });
+
+    void (() => {
+      // @ts-expect-error filterObjectKeys requires an object source.
+      filterObjectKeys("text", () => true);
+      // @ts-expect-error Selected properties are readonly.
+      selected.APP_PORT = "5000";
+    });
+  });
+
+  it("preserves descriptors without reading getters", () => {
+    let reads = 0;
+    const getter = () => {
+      reads++;
+      return "value";
+    };
+    const source = Object.defineProperties(Object.create({ inherited: 1 }), {
+      visible: { value: { nested: true }, enumerable: true, writable: true },
+      hidden: { value: undefined },
+      accessor: { get: getter, enumerable: true, configurable: true },
+      excluded: { get: getter },
+      [Symbol("ignored")]: { get: getter },
+    });
+    const visited: Array<string> = [];
+    const selected = filterObjectKeys(source, (key) => {
+      visited.push(key);
+      return key !== "excluded";
+    });
+    assertEqual(visited, ["visible", "hidden", "accessor", "excluded"]);
+    assertEqual(Object.getOwnPropertyNames(selected), [
+      "visible",
+      "hidden",
+      "accessor",
+    ]);
+    for (const key of Object.getOwnPropertyNames(selected)) {
+      nodeAssert.deepEqual(
+        Object.getOwnPropertyDescriptor(selected, key),
+        Object.getOwnPropertyDescriptor(source, key),
+      );
+    }
+    assertEqual(reads, 0);
+    assertFalse(Object.hasOwn(selected, "inherited"));
+    assertEqual(Object.getOwnPropertySymbols(selected), []);
+    assertSame(Object.getPrototypeOf(selected), Object.prototype);
+    assertSame(
+      Reflect.get(selected, "visible"),
+      Reflect.get(source, "visible"),
+    );
+    assertSame(Reflect.get(selected, "accessor"), "value");
+    assertEqual(reads, 1);
+  });
+
+  it("safely copies special keys and handles arrays as objects", () => {
+    const source = createMutableRecord();
+    source.__proto__ = "value";
+    Object.defineProperty(source, "constructor", {
+      value: "constructor",
+      enumerable: true,
+    });
+    const selected = filterObjectKeys(source, () => true);
+    assertTrue(Object.hasOwn(selected, "__proto__"));
+    assertSame(Object.getPrototypeOf(selected), Object.prototype);
+    assertEqual(selected, {
+      ["__proto__"]: "value",
+      constructor: "constructor",
+    });
+
+    const values: ReadonlyArray<number> = [10, 20];
+    const array = filterObjectKeys(values, (key) => key === "0");
+    assertFalse(Array.isArray(array));
+    assertEqual(array, { 0: 10 });
+    assertType<(typeof array)[0], number | undefined>();
+    assertType<typeof array.map, ReadonlyArray<number>["map"] | undefined>();
+  });
+});
+
 test("excludeProp", () => {
   const obj = { a: 1, b: 2, c: 3 };
 
@@ -246,16 +381,10 @@ test("createMutableRecord", () => {
   assertEqual(source, { name: "Ada" });
   assertSame(Object.getPrototypeOf(copy), null);
 
-  const compileTimeAssertions = () => {
+  void (() => {
     // @ts-expect-error createMutableRecord source must be an object.
     createMutableRecord("Ada");
-  };
-  assertType<
-    typeof compileTimeAssertions extends (...args: Array<never>) => unknown
-      ? true
-      : false,
-    true
-  >();
+  });
 });
 
 test("emptyRecord", () => {

package/src/Object.ts

@@ -87,6 +87,11 @@ export const isPlainObject = (
 
   const prototype = Object.getPrototypeOf(value) as object | null;
   if (prototype === null) return true;
+  // This realm's Object.prototype has an immutable null prototype, so `in`
+  // checks the same own properties as the structural test below, faster.
+  if (prototype === Object.prototype) {
+    return "hasOwnProperty" in prototype && "isPrototypeOf" in prototype;
+  }
   return (
     Object.getPrototypeOf(prototype) === null &&
     Object.hasOwn(prototype, "hasOwnProperty") &&
@@ -243,6 +248,50 @@ export const mapObject = <K extends string, V, U>(
   return out;
 };
 
+/**
+ * Selects own string-keyed properties while preserving their descriptors.
+ *
+ * Visits enumerable and non-enumerable properties, ignoring inherited and
+ * symbol properties. The predicate receives only the key; property values and
+ * getters are never read. The result is a new ordinary object with matching
+ * descriptors, including accessor functions and property flags. Declared
+ * properties are optional because the predicate may exclude any of them.
+ * Numeric property names are visited as strings.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   filterObjectKeys,
+ * } from "@evolu/common";
+ *
+ * const source = { APP_PORT: "4000", HOME: "/home/evolu" };
+ * const selected = filterObjectKeys(source, (key) =>
+ *   key.startsWith("APP_"),
+ * );
+ *
+ * assertEqual(selected, { APP_PORT: "4000" });
+ * assertType<
+ *   typeof selected,
+ *   { readonly APP_PORT?: string; readonly HOME?: string }
+ * >();
+ * ```
+ */
+export const filterObjectKeys = <T extends object>(
+  source: T,
+  predicate: (key: string) => boolean,
+): Readonly<Partial<Pick<T, Exclude<keyof T, symbol>>>> => {
+  const selected: Partial<Pick<T, Exclude<keyof T, symbol>>> = {};
+  for (const key of Object.getOwnPropertyNames(source)) {
+    if (!predicate(key)) continue;
+    const descriptor = Object.getOwnPropertyDescriptor(source, key)!;
+    Object.defineProperty(selected, key, descriptor);
+  }
+  return selected;
+};
+
 /** Conditionally excludes a property from an object. */
 export const excludeProp = <T extends object, K extends keyof T>(
   obj: T,

package/src/Platform.ts

@@ -4,10 +4,18 @@
  * @module
  */
 
-/** Returns true if running in React Native with Hermes engine. */
+/**
+ * Returns true if running in React Native with Hermes engine.
+ *
+ * @group Detection
+ */
 export const isHermes = "HermesInternal" in globalThis;
 
-/** Returns true if running in a server environment (no DOM). */
+/**
+ * Returns true if running in a server environment (no DOM).
+ *
+ * @group Detection
+ */
 export const isServer = typeof document === "undefined";
 
 /**
@@ -20,6 +28,8 @@ export const isServer = typeof document === "undefined";
  * where no bundler ran, such as un-bundled browser ESM, where it fails closed
  * to production behavior. Node.js reads it natively; React Native polyfills it.
  * A missing `NODE_ENV` counts as development, matching React semantics.
+ *
+ * @group Detection
  */
 export const isDev =
   typeof process === "undefined"
@@ -35,6 +45,7 @@ export const isDev =
  * Returns false in React Native even if Buffer is polyfilled, as we prefer
  * native methods in that environment.
  *
+ * @group Detection
  * @see https://github.com/craftzdog/react-native-quick-base64#installation
  */
 export const hasNodeBuffer =
@@ -49,9 +60,16 @@ export const hasNodeBuffer =
  * if an onComplete callback is used.
  *
  * https://react.dev/reference/react-dom/flushSync
+ *
+ * @group Integration
  */
 export type FlushSync = (callback: () => void) => void;
 
+/**
+ * Dependency wrapper for {@link FlushSync}.
+ *
+ * @group Integration
+ */
 export interface FlushSyncDep {
   readonly flushSync: FlushSync;
 }
@@ -59,18 +77,32 @@ export interface FlushSyncDep {
 /**
  * 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.
+ * On the web, Evolu reloads tabs of a build when another build of the app waits
+ * for the local databases, so they load the build the server now serves. It can
+ * also clear in-memory state after persistent storage was purged; it does not
+ * purge storage itself.
  *
- * - Web: Redirects to the specified URL (defaults to `/`)
+ * - Web: Reloads the page, or loads the specified URL instead
  * - React Native: Restarts the app (URL ignored)
+ *
+ * @group Integration
  */
 export type ReloadApp = (url?: string) => void;
 
+/**
+ * Dependency wrapper for {@link ReloadApp}.
+ *
+ * @group Integration
+ */
 export interface ReloadAppDep {
   readonly reloadApp: ReloadApp;
 }
 
+/**
+ * Records platform global errors until disposed.
+ *
+ * @group Testing
+ */
 export interface TestGlobalErrors extends Disposable {
   readonly errors: ReadonlyArray<unknown>;
   readonly next: () => Promise<unknown>;
@@ -88,15 +120,25 @@ export interface TestGlobalErrors extends Disposable {
   readonly settle: () => Promise<ReadonlyArray<unknown>>;
 }
 
-/** Records platform global uncaught-error reporting until disposed. */
+/**
+ * Records platform global uncaught-error reporting until disposed.
+ *
+ * @group Testing
+ */
 export const testGlobalUncaughtErrors = (): TestGlobalErrors =>
   createTestGlobalErrors("uncaughtErrors");
 
-/** Records platform global unhandled-rejection reporting until disposed. */
+/**
+ * Records platform global unhandled-rejection reporting until disposed.
+ *
+ * @group Testing
+ */
 export const testGlobalUnhandledRejections = (): TestGlobalErrors =>
   createTestGlobalErrors("unhandledRejection");
 
-const settleSentinel = new Error("TestGlobalErrors.settle sentinel");
+const settleSentinel = /*#__PURE__*/ new Error(
+  "TestGlobalErrors.settle sentinel",
+);
 
 const createTestGlobalErrors = (
   kind: "uncaughtErrors" | "unhandledRejection",

package/src/Random.ts

@@ -11,6 +11,8 @@ import type { Brand } from "./Brand.ts";
  * A random floating point number in [0, 1).
  *
  * Branded to distinguish random values from arbitrary numbers.
+ *
+ * @group Core
  */
 export type RandomNumber = number & Brand<"RandomNumber">;
 
@@ -43,17 +45,28 @@ export type RandomNumber = number & Brand<"RandomNumber">;
  * const secondTestRandom = testCreateRandom("test");
  * assertEqual(firstTestRandom.next(), secondTestRandom.next());
  * ```
+ *
+ * @group Core
  */
 export interface Random {
   /** Returns a floating point number in [0, 1). Just like Math.random(). */
   readonly next: () => RandomNumber;
 }
 
+/**
+ * Dependency wrapper for {@link Random}.
+ *
+ * @group Core
+ */
 export interface RandomDep {
   readonly random: Random;
 }
 
-/** Creates a {@link Random} using Math.random(). */
+/**
+ * Creates a {@link Random} using Math.random().
+ *
+ * @group Core
+ */
 export const createRandom = (): Random => ({
   next: () => Math.random() as RandomNumber,
 });
@@ -62,6 +75,8 @@ export const createRandom = (): Random => ({
  * Creates a seeded {@link Random} for deterministic tests.
  *
  * Default seed "evolu".
+ *
+ * @group Testing
  */
 export const testCreateRandom = (seed = "evolu"): Random => {
   const random = new RandomLib(seed);
@@ -75,12 +90,18 @@ export const testCreateRandom = (seed = "evolu"): Random => {
  * provided by the NPM `random` package.
  *
  * https://github.com/transitive-bullshit/random
+ *
+ * @group Core
  */
 export interface RandomLibDep {
   readonly randomLib: RandomLib;
 }
 
-/** Creates a random number generator from the NPM `random` package. */
+/**
+ * Creates a random number generator from the NPM `random` package.
+ *
+ * @group Core
+ */
 export const createRandomLib = (): RandomLib => new RandomLib();
 
 /**
@@ -88,6 +109,8 @@ export const createRandomLib = (): RandomLib => new RandomLib();
  * deterministic tests.
  *
  * Default seed "evolu".
+ *
+ * @group Testing
  */
 export const testCreateRandomLib = (seed = "evolu"): RandomLib =>
   new RandomLib(seed);