@evolu/common 8.8.0 → 8.10.0

package/src/Object.test.ts

@@ -1,4 +1,5 @@
-import { test } from "node:test";
+import nodeAssert from "node:assert/strict";
+import { describe, it, test } from "node:test";
 import { assertEqual, assertFalse, assertSame, assertTrue } from "./Assert.ts";
 
 import type { Brand } from "./Brand.ts";
@@ -8,6 +9,7 @@ import {
   createMutableRecord,
   emptyRecord,
   excludeProp,
+  filterObjectKeys,
   getObjectKind,
   getOwnProp,
   isFunction,
@@ -205,6 +207,118 @@ 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 });
+
+    const reject = () => {
+      // @ts-expect-error filterObjectKeys requires an object source.
+      filterObjectKeys("text", () => true);
+      // @ts-expect-error Selected properties are readonly.
+      selected.APP_PORT = "5000";
+    };
+    assertType<typeof reject, () => void>();
+  });
+
+  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 };
 

package/src/Object.ts

@@ -243,6 +243,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/Polyfills.ts

@@ -16,6 +16,12 @@
  *   `Map.prototype.getOrInsertComputed`, `WeakMap.prototype.getOrInsert`, and
  *   `WeakMap.prototype.getOrInsertComputed`) for Node 24 and React Native
  *
+ * The polyfills are implemented directly in the Evolu Library instead of being
+ * third-party runtime dependencies. We audit their behavior against
+ * specifications, conformance tests, and native implementations, and fix issues
+ * when necessary. This lets Evolu understand and control every line of this
+ * runtime code.
+ *
  * `@evolu/react-native` has its own `Polyfills` module and its
  * `installPolyfills` calls this function first, then installs React Native
  * specific polyfills.

package/src/Sqlite.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Brand } from "./Brand.ts";
-import { bytesToHex, hexToBytes } from "./Binary.ts";
+import { bytesToHex, hexToBytes } from "./Bytes.ts";
 import type { EncryptionKey } from "./Crypto.ts";
 import type { Eq } from "./Eq.ts";
 import { createEqObject, eqString, eqUint8Array } from "./Eq.ts";

package/src/Time.test.ts

@@ -1,6 +1,8 @@
 import { afterEach, describe, it, mock } from "node:test";
 import {
   assertEqual,
+  assertErr,
+  assertOk,
   assertFalse,
   assertLength,
   assertSame,
@@ -37,19 +39,21 @@ import {
   saturateMillis,
   testCreateTime,
 } from "./Time.ts";
-import { assertType, type DateIso, NonNaNNumber } from "./Type.ts";
+import {
+  localizeTypes,
+  object,
+  typeErrorToIssues,
+  type InferErrors,
+  assertType,
+  type DateIso,
+  NonNaNNumber,
+} from "./Type.ts";
 
 const negativeMillisCause = {
   type: "NonNegative",
   value: -1,
 };
 
-const assertThrowsWithCause = (run: () => unknown, cause: unknown): void => {
-  const error = assertThrowsInstanceOf(run, Error);
-  assertEqual(error.message, "getOrThrow");
-  assertEqual(error.cause, cause);
-};
-
 describe("Time", () => {
   afterEach(() => {
     mock.restoreAll();
@@ -218,14 +222,17 @@ describe("Time", () => {
         );
         mock.method(Date, "now", () => -1);
 
-        assertThrowsWithCause(
+        const error = assertThrowsInstanceOf(
           () =>
             createTime().setTimeout(
               () => undefined,
               PositiveMillis.orThrow(2 ** 31),
             ),
-          negativeMillisCause,
+          Error,
         );
+
+        assertEqual(error.message, "The value -1 must be non-negative (>= 0).");
+        assertEqual(error.cause, negativeMillisCause);
         assertEqual(setTimeout.mock.callCount(), 0);
       });
 
@@ -247,7 +254,10 @@ describe("Time", () => {
         );
         now = -1;
 
-        assertThrowsWithCause(() => callbacks[0](), negativeMillisCause);
+        const error = assertThrowsInstanceOf(() => callbacks[0](), Error);
+
+        assertEqual(error.message, "The value -1 must be non-negative (>= 0).");
+        assertEqual(error.cause, negativeMillisCause);
         assertLength(callbacks, 1);
       });
 
@@ -445,7 +455,16 @@ describe("Time", () => {
     it("setTimeout rejects a deadline after maxMillis", () => {
       const time = testCreateTime({ startAt: maxMillis });
 
-      assertThrowsWithCause(() => time.setTimeout(() => undefined, "1ms"), {
+      const error = assertThrowsInstanceOf(
+        () => time.setTimeout(() => undefined, "1ms"),
+        Error,
+      );
+
+      assertEqual(
+        error.message,
+        "The value 281474976710655 must be less than 281474976710655.",
+      );
+      assertEqual(error.cause, {
         type: "LessThan281474976710655",
         value: maxMillis + 1,
         max: maxMillis + 1,
@@ -727,6 +746,58 @@ describe("Time", () => {
   });
 
   describe("DurationLiteral", () => {
+    it("reports a dedicated error with the original validation failure", () => {
+      for (const value of ["60s", "", 1, null, undefined]) {
+        const result = DurationLiteral.fromUnknown(value);
+        assertErr(result);
+        assertType<typeof result.error.type, "DurationLiteral">();
+        assertSame(result.error.value, value);
+        assertEqual(result.error.cause.type, "Union");
+        assertEqual(result.error.cause.errors.length, 1);
+      }
+      const result = DurationLiteral.fromUnknown("60s", { errors: "all" });
+      assertErr(result);
+      assertEqual(result.error.cause.errors.length, 7);
+      assertEqual(
+        DurationLiteral.formatError(result.error),
+        'The value "60s" is not a duration literal. Use a value such as "500ms" or "1.5s".',
+      );
+      assertType<
+        InferErrors<typeof DurationLiteral>["type"],
+        "DurationLiteral"
+      >();
+      assertOk(DurationLiteral.from("1.5s"), "1.5s");
+      assertEqual(DurationLiteral.to("1.5s"), "1.5s");
+      // @ts-expect-error DurationLiteral Input rejects "60s".
+      const _invalidInput: typeof DurationLiteral.Input = "60s";
+    });
+
+    it("localizes the named error after composition and preserves its path", async () => {
+      const { first } = localizeTypes(
+        { Value: DurationLiteral },
+        { first: { DurationLiteral: () => "First message." } },
+      );
+      const { second } = localizeTypes(
+        { Settings: object({ value: first.Value }) },
+        {
+          second: {
+            Object: () => "Object.",
+            DurationLiteral: () => "Second message.",
+          },
+        },
+      );
+      const result = second.Settings.fromUnknown({ value: "60s" });
+      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: "60s" }),
+        { issues: [{ path: ["value"], message: "Second message." }] },
+      );
+    });
+
     it("valid durations", () => {
       // Milliseconds
       assertType<"1ms" extends DurationLiteral ? true : false, true>();

package/src/Time.ts

@@ -1,15 +1,31 @@
 /**
  * Time representations, durations, and scheduling utilities.
  *
+ * Durations follow a pattern that other quantities in Evolu repeat, such as
+ * sizes in Bytes.ts:
+ *
+ * - {@link Millis} is the canonical unit, a validated number of milliseconds.
+ * - {@link DurationLiteral} is the human-readable form, such as `"1.5s"`,
+ *   validated at compile time and runtime.
+ * - {@link Duration} is what APIs accept: `DurationLiteral | Millis`.
+ * - {@link durationToMillis} normalizes a `Duration` to `Millis`.
+ *
  * @module
  */
 
+import { safelyStringifyUnknownValue } from "./String.ts";
 import { assert } from "./Assert.ts";
 import type { Brand } from "./Brand.ts";
 import { exhaustiveCheck } from "./Function.ts";
 import type { yieldNow } from "./Task.ts";
 import {
   brand,
+  createTypeWithError,
+  type Type,
+  type TypeError,
+  type UnionError,
+  type UnionType,
+  type TemplateLiteralType,
   type DateIso,
   Digit,
   Digit1To23,
@@ -418,8 +434,18 @@ export type Duration = DurationLiteral | Millis;
  */
 export type PositiveDuration = DurationLiteral | PositiveMillis;
 
+// Keep these annotations concrete. Generic unit wrappers add thousands of
+// compiler instantiations to pnpm bench:type.
 /** Milliseconds duration: `"1ms"` to `"999ms"`. See {@link DurationLiteral}. */
-export const DurationLiteralMilliseconds = /*#__PURE__*/ union(
+export const DurationLiteralMilliseconds: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To9, "ms"]>,
+    TemplateLiteralType<readonly [typeof Digit1To9, typeof Digit, "ms"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To9, typeof Digit, typeof Digit, "ms"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To9, "ms"),
   /*#__PURE__*/ templateLiteral(Digit1To9, Digit, "ms"),
   /*#__PURE__*/ templateLiteral(Digit1To9, Digit, Digit, "ms"),
@@ -431,7 +457,14 @@ export type DurationLiteralMilliseconds =
  * Seconds duration: `"1s"` to `"59s"` or `"1.1s"` to `"59.9s"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralSeconds = /*#__PURE__*/ union(
+export const DurationLiteralSeconds: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To59, "s"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To59, ".", typeof Digit1To9, "s"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To59, "s"),
   /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "s"),
 );
@@ -441,7 +474,14 @@ export type DurationLiteralSeconds = typeof DurationLiteralSeconds.Output;
  * Minutes duration: `"1m"` to `"59m"` or `"1.1m"` to `"59.9m"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralMinutes = /*#__PURE__*/ union(
+export const DurationLiteralMinutes: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To59, "m"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To59, ".", typeof Digit1To9, "m"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To59, "m"),
   /*#__PURE__*/ templateLiteral(Digit1To59, ".", Digit1To9, "m"),
 );
@@ -451,7 +491,14 @@ export type DurationLiteralMinutes = typeof DurationLiteralMinutes.Output;
  * Hours duration: `"1h"` to `"23h"` or `"1.1h"` to `"23.9h"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralHours = /*#__PURE__*/ union(
+export const DurationLiteralHours: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To23, "h"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To23, ".", typeof Digit1To9, "h"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To23, "h"),
   /*#__PURE__*/ templateLiteral(Digit1To23, ".", Digit1To9, "h"),
 );
@@ -461,7 +508,14 @@ export type DurationLiteralHours = typeof DurationLiteralHours.Output;
  * Days duration: `"1d"` to `"6d"` or `"1.1d"` to `"6.9d"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralDays = /*#__PURE__*/ union(
+export const DurationLiteralDays: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To6, "d"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To6, ".", typeof Digit1To9, "d"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To6, "d"),
   /*#__PURE__*/ templateLiteral(Digit1To6, ".", Digit1To9, "d"),
 );
@@ -471,7 +525,14 @@ export type DurationLiteralDays = typeof DurationLiteralDays.Output;
  * Weeks duration: `"1w"` to `"51w"` or `"1.1w"` to `"51.9w"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralWeeks = /*#__PURE__*/ union(
+export const DurationLiteralWeeks: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To51, "w"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To51, ".", typeof Digit1To9, "w"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To51, "w"),
   /*#__PURE__*/ templateLiteral(Digit1To51, ".", Digit1To9, "w"),
 );
@@ -481,12 +542,38 @@ export type DurationLiteralWeeks = typeof DurationLiteralWeeks.Output;
  * Years duration: `"1y"` to `"99y"` or `"1.1y"` to `"99.9y"`. See
  * {@link DurationLiteral}.
  */
-export const DurationLiteralYears = /*#__PURE__*/ union(
+export const DurationLiteralYears: UnionType<
+  readonly [
+    TemplateLiteralType<readonly [typeof Digit1To99, "y"]>,
+    TemplateLiteralType<
+      readonly [typeof Digit1To99, ".", typeof Digit1To9, "y"]
+    >,
+  ]
+> = /*#__PURE__*/ union(
   /*#__PURE__*/ templateLiteral(Digit1To99, "y"),
   /*#__PURE__*/ templateLiteral(Digit1To99, ".", Digit1To9, "y"),
 );
 export type DurationLiteralYears = typeof DurationLiteralYears.Output;
 
+export type DurationLiteral =
+  | DurationLiteralMilliseconds
+  | DurationLiteralSeconds
+  | DurationLiteralMinutes
+  | DurationLiteralHours
+  | DurationLiteralDays
+  | DurationLiteralWeeks
+  | DurationLiteralYears;
+
+const durationLiteralSyntax = /*#__PURE__*/ union(
+  DurationLiteralMilliseconds,
+  DurationLiteralSeconds,
+  DurationLiteralMinutes,
+  DurationLiteralHours,
+  DurationLiteralDays,
+  DurationLiteralWeeks,
+  DurationLiteralYears,
+);
+
 /**
  * Duration literal Type with compile-time and runtime validation.
  *
@@ -514,17 +601,55 @@ export type DurationLiteralYears = typeof DurationLiteralYears.Output;
  *
  * See {@link Duration} for a type that also accepts {@link Millis}. Use
  * {@link durationToMillis} to convert to milliseconds.
+ *
+ * Invalid values produce a {@link DurationLiteralError}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   DurationLiteral,
+ * } from "@evolu/common";
+ *
+ * // The TypeScript type accepts valid spellings and rejects the rest.
+ * const literal: DurationLiteral = "1.5s";
+ * assertType<Extract<DurationLiteral, "1000ms" | "60s" | "0s">, never>();
+ *
+ * // The runtime Type validates the same grammar.
+ * assertOk(DurationLiteral.fromUnknown(literal), "1.5s");
+ * assertFalse(DurationLiteral.is("1000ms"));
+ * ```
  */
-export const DurationLiteral = /*#__PURE__*/ union(
-  DurationLiteralMilliseconds,
-  DurationLiteralSeconds,
-  DurationLiteralMinutes,
-  DurationLiteralHours,
-  DurationLiteralDays,
-  DurationLiteralWeeks,
-  DurationLiteralYears,
+export const DurationLiteral: Type<
+  "DurationLiteral",
+  DurationLiteral,
+  DurationLiteral,
+  DurationLiteralError
+> = /*#__PURE__*/ createTypeWithError(
+  "DurationLiteral",
+  durationLiteralSyntax,
+  (cause, value): DurationLiteralError => ({
+    type: "DurationLiteral",
+    value,
+    cause,
+  }),
+  (error) =>
+    `The value ${safelyStringifyUnknownValue(error.value)} is not a duration literal. Use a value such as "500ms" or "1.5s".`,
 );
-export type DurationLiteral = typeof DurationLiteral.Output;
+
+/** Error returned when {@link DurationLiteral} rejects a value. */
+export interface DurationLiteralError extends TypeError<"DurationLiteral"> {
+  readonly value: unknown;
+  /**
+   * The underlying union failure, retained for diagnostics.
+   *
+   * With `{ errors: "all" }`, includes every failed alternative.
+   */
+  readonly cause: UnionError;
+}
 
 /**
  * Converts a duration to milliseconds.