@evolu/common 8.9.0 → 8.11.0

package/dist/src/Fs.js

@@ -0,0 +1,113 @@
+/**
+ * File system operations for {@link Task}s.
+ *
+ * {@link Fs} reads, writes, copies, and renames files; lists and manages
+ * directories; and provides metadata and existence checks. Each operation
+ * returns a Task.
+ *
+ * Tasks can sequence file operations without synchronous I/O. Node.js's
+ * synchronous methods are intentionally omitted to avoid accidentally blocking
+ * the event loop.
+ *
+ * Inject {@link @evolu/nodejs!createNodeFs | createNodeFs} through
+ * {@link @evolu/nodejs!runMain | runMain} or {@link createRun}. Tasks declare
+ * {@link FsDep} and access the file system through `run.deps.fs`.
+ *
+ * {@link FsError} includes the path, a diagnostic message, and a
+ * {@link FsErrorReason} such as `NotFound` or `PermissionDenied`.
+ * {@link Fs.exists} returns `false` for `NotFound` and preserves other errors.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   ok,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ * import { createNodeFs, runMain } from "@evolu/nodejs";
+ * import { join } from "node:path";
+ *
+ * const main: Task<void, FsError, FsDep> = async (run) => {
+ *   const { fs } = run.deps;
+ *   const temp = await run(
+ *     fs.createTempDirectory({ prefix: "evolu-fs-" }),
+ *   );
+ *   if (!temp.ok) return temp;
+ *
+ *   await using directory = temp.value;
+ *   const path = join(directory.path, "message.txt");
+ *
+ *   const result = await run(fs.writeFile(path, "hello"));
+ *   if (!result.ok) return result;
+ *
+ *   const text = await run(fs.readFile(path, "utf8"));
+ *   if (!text.ok) return text;
+ *   assertEqual(text.value, "hello");
+ *
+ *   return ok();
+ * };
+ *
+ * await runMain({ fs: createNodeFs() }, { mode: "command" })(main);
+ * ```
+ *
+ * @module
+ */
+/**
+ * Creates a test {@link Fs} with the supplied operation overrides.
+ *
+ * Unconfigured operations throw a defect naming the method when their Task
+ * runs. Constructing a Task does not execute it. This helper performs no file
+ * system I/O; overrides provide the behavior needed by each test.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   ok,
+ *   testCreateFs,
+ *   testCreateRun,
+ *   type FsDep,
+ *   type FsError,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const saveMessage: Task<void, FsError, FsDep> = (run) =>
+ *   run(run.deps.fs.writeFile("message.txt", "hello"));
+ *
+ * await using run = testCreateRun({
+ *   fs: testCreateFs({
+ *     writeFile: (path, data) => () => {
+ *       assertEqual(path, "message.txt");
+ *       assertEqual(data, "hello");
+ *       return ok();
+ *     },
+ *   }),
+ * });
+ *
+ * assertOk(await run(saveMessage));
+ * ```
+ *
+ * @group Testing
+ */
+export const testCreateFs = (overrides = {}) => ({
+    readFile: createUnexpectedFsOperation("readFile"),
+    writeFile: createUnexpectedFsOperation("writeFile"),
+    readDirectory: createUnexpectedFsOperation("readDirectory"),
+    createDirectory: createUnexpectedFsOperation("createDirectory"),
+    copy: createUnexpectedFsOperation("copy"),
+    copyFile: createUnexpectedFsOperation("copyFile"),
+    rename: createUnexpectedFsOperation("rename"),
+    remove: createUnexpectedFsOperation("remove"),
+    getMetadata: createUnexpectedFsOperation("getMetadata"),
+    exists: createUnexpectedFsOperation("exists"),
+    createTempDirectory: createUnexpectedFsOperation("createTempDirectory"),
+    ...overrides,
+});
+const createUnexpectedFsOperation = (method) => () => () => {
+    throw new Error(`Unexpected Fs.${method} call`);
+};

package/dist/src/Identicon.d.ts

@@ -32,6 +32,7 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  *   assertTrue,
  *   createIdFromString,
  *   createIdenticon,
+ *   testTodoId,
  * } from "@evolu/common";
  *
  * const id = createIdFromString("identicon-example");
@@ -42,8 +43,7 @@ export type IdenticonStyle = "github" | "quadrant" | "gradient" | "sutnar";
  * );
  *
  * // Branded IDs work too.
- * const todoId = createIdFromString<"Todo">("todo-1");
- * const todoSvg = createIdenticon(todoId);
+ * const todoSvg = createIdenticon(testTodoId);
  *
  * assertTrue(svg.startsWith("<svg"));
  * assertEqual(new Set([svg, ...alternativeSvgs]).size, 4);

package/dist/src/Identicon.js

@@ -25,6 +25,7 @@ import { Id, idToIdBytes } from "./Type.js";
  *   assertTrue,
  *   createIdFromString,
  *   createIdenticon,
+ *   testTodoId,
  * } from "@evolu/common";
  *
  * const id = createIdFromString("identicon-example");
@@ -35,8 +36,7 @@ import { Id, idToIdBytes } from "./Type.js";
  * );
  *
  * // Branded IDs work too.
- * const todoId = createIdFromString<"Todo">("todo-1");
- * const todoSvg = createIdenticon(todoId);
+ * const todoSvg = createIdenticon(testTodoId);
  *
  * assertTrue(svg.startsWith("<svg"));
  * assertEqual(new Set([svg, ...alternativeSvgs]).size, 4);

package/dist/src/LeakDetector.d.ts

@@ -19,6 +19,8 @@ import { type ConsoleDep } from "./Console.ts";
  * a warning may come late or, in short-lived processes, never. It is a
  * development canary, not a guarantee. Production uses
  * {@link noopLeakDetector}.
+ *
+ * @group Core
  */
 export interface LeakDetector {
     /**
@@ -33,7 +35,11 @@ export interface LeakDetector {
     /** Stops tracking the target registered with `unregisterToken`. */
     readonly untrack: (unregisterToken: object) => void;
 }
-/** Describes a tracked handle for {@link LeakDetector.track}. */
+/**
+ * Describes a tracked handle for {@link LeakDetector.track}.
+ *
+ * @group Core
+ */
 export interface Leak {
     /** Handle name used in the warning, for example `"Lease"`. */
     readonly name: string;
@@ -43,6 +49,7 @@ export interface Leak {
 /**
  * Dependency wrapper for {@link LeakDetector}.
  *
+ * @group Core
  * @see {@link LeakDetector}
  */
 export interface LeakDetectorDep {
@@ -53,13 +60,20 @@ export interface LeakDetectorDep {
  *
  * Capturing a stack per track call is too expensive for production; use
  * {@link noopLeakDetector} there.
+ *
+ * @group Core
  */
 export declare const createLeakDetector: (deps: ConsoleDep) => LeakDetector;
-/** No-op {@link LeakDetector} for production. */
+/**
+ * No-op {@link LeakDetector} for production.
+ *
+ * @group Core
+ */
 export declare const noopLeakDetector: LeakDetector;
 /**
  * Test {@link LeakDetector} with deterministic collection.
  *
+ * @group Testing
  * @see {@link testCreateLeakDetector}
  */
 export interface TestLeakDetector extends LeakDetector {
@@ -78,11 +92,16 @@ export interface TestLeakDetector extends LeakDetector {
 /**
  * Dependency wrapper for {@link TestLeakDetector}.
  *
+ * @group Testing
  * @see {@link TestLeakDetector}
  */
 export interface TestLeakDetectorDep extends LeakDetectorDep {
     readonly leakDetector: TestLeakDetector;
 }
-/** Creates {@link TestLeakDetector}. */
+/**
+ * Creates {@link TestLeakDetector}.
+ *
+ * @group Testing
+ */
 export declare const testCreateLeakDetector: (deps: ConsoleDep) => TestLeakDetector;
 //# sourceMappingURL=LeakDetector.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"LeakDetector.d.ts","sourceRoot":"","sources":["../../src/LeakDetector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9E,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED,iEAAiE;AACjE,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,SAAU,UAAU,KAAG,YAsBrD,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,gBAAgB,EAAE,YAG9B,CAAC;AAyBF;;;;GAIG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAE/B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACnE;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,wCAAwC;AACxC,eAAO,MAAM,sBAAsB,SAAU,UAAU,KAAG,gBAsCzD,CAAC"}
+{"version":3,"file":"LeakDetector.d.ts","sourceRoot":"","sources":["../../src/LeakDetector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;IAE9E,mEAAmE;IACnE,QAAQ,CAAC,OAAO,EAAE,CAAC,eAAe,EAAE,MAAM,KAAK,IAAI,CAAC;CACrD;AAED;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,SAAU,UAAU,KAAG,YAsBrD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,YAG9B,CAAC;AAyBF;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,MAAM,CAAC;IAE/B,uDAAuD;IACvD,QAAQ,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC;CACnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IAC1D,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,SAAU,UAAU,KAAG,gBAsCzD,CAAC"}

package/dist/src/LeakDetector.js

@@ -10,6 +10,8 @@ import { constVoid } from "./Function.js";
  *
  * Capturing a stack per track call is too expensive for production; use
  * {@link noopLeakDetector} there.
+ *
+ * @group Core
  */
 export const createLeakDetector = (deps) => {
     if (typeof globalThis.FinalizationRegistry !== "function")
@@ -28,7 +30,11 @@ export const createLeakDetector = (deps) => {
         },
     };
 };
-/** No-op {@link LeakDetector} for production. */
+/**
+ * No-op {@link LeakDetector} for production.
+ *
+ * @group Core
+ */
 export const noopLeakDetector = {
     track: constVoid,
     untrack: constVoid,
@@ -47,7 +53,11 @@ const reportLeak = (deps) => (leak) => {
     deps.console.warn(`${leak.name} was garbage-collected without cleanup. Tracked at:`, leak.stack);
     return true;
 };
-/** Creates {@link TestLeakDetector}. */
+/**
+ * Creates {@link TestLeakDetector}.
+ *
+ * @group Testing
+ */
 export const testCreateLeakDetector = (deps) => {
     const trackedLeaksByToken = new Map();
     const report = reportLeak(deps);

package/dist/src/LockManager.d.ts

@@ -41,6 +41,8 @@ import type { Callback } from "./Types.ts";
  * );
  * assertEqual(result, "example");
  * ```
+ *
+ * @group Core
  */
 export interface LockManagerDep {
     readonly lockManager: LockManager;
@@ -57,6 +59,8 @@ export interface LockManagerDep {
  * via internal namespacing, so tests can reuse the same lock names without
  * contending through the global Web Locks. Query results are filtered to that
  * private namespace and returned with the original visible names.
+ *
+ * @group Testing
  */
 export declare const testCreateLockManager: (nativeLockManager?: LockManager) => LockManager;
 /**
@@ -68,6 +72,8 @@ export declare const testCreateLockManager: (nativeLockManager?: LockManager) =>
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
+ *
+ * @group Leader election
  */
 export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable, never, LockManagerDep>;
 /**
@@ -80,6 +86,8 @@ export declare const acquireLeaderLock: (name: string) => Task<AsyncDisposable,
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable by disposing the returned handle.
+ *
+ * @group Leader election
  */
 export declare const acquireLeaderLockCallback: (deps: LockManagerDep) => (name: string, callback: Callback<void>) => Disposable;
 //# sourceMappingURL=LockManager.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,uBACb,WAAW,KAC7B,WAwCF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,SACrB,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,CAuB1D,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,SAC7B,cAAc,YACd,MAAM,YAAY,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}
+{"version":3,"file":"LockManager.d.ts","sourceRoot":"","sources":["../../src/LockManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;CACnC;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,uBACb,WAAW,KAC7B,WAwCF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,SACrB,MAAM,KAAG,IAAI,CAAC,eAAe,EAAE,KAAK,EAAE,cAAc,CAuB1D,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,SAC7B,cAAc,YACd,MAAM,YAAY,QAAQ,CAAC,IAAI,CAAC,KAAG,UAsBzC,CAAC"}

package/dist/src/LockManager.js

@@ -19,6 +19,8 @@ import { createId } from "./Type.js";
  * via internal namespacing, so tests can reuse the same lock names without
  * contending through the global Web Locks. Query results are filtered to that
  * private namespace and returned with the original visible names.
+ *
+ * @group Testing
  */
 export const testCreateLockManager = (nativeLockManager = navigator.locks) => {
     const namespace = createId({ randomBytes: createRandomBytes() });
@@ -54,6 +56,8 @@ export const testCreateLockManager = (nativeLockManager = navigator.locks) => {
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable via the calling {@link Task}'s signal.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLock = (name) => async (run) => {
     const acquisition = Promise.withResolvers();
@@ -81,6 +85,8 @@ export const acquireLeaderLock = (name) => async (run) => {
  * Leadership is held until the returned handle is disposed. Once released,
  * another waiting caller may become the next leader. Waiting for leadership is
  * abortable by disposing the returned handle.
+ *
+ * @group Leader election
  */
 export const acquireLeaderLockCallback = (deps) => (name, callback) => {
     const abortController = new AbortController();

package/dist/src/Number.d.ts

@@ -6,7 +6,7 @@
 import type { NonEmptyReadonlyArray } from "./Array.ts";
 import type { IsBranded } from "./Brand.ts";
 import type { Result } from "./Result.ts";
-import { Digit1To99, NonNegativeInt, PositiveInt, Ratio } from "./Type.ts";
+import { type Type, type TypeError, type UnionError, Digit1To9, Digit1To99, NonNegativeInt, PositiveInt, Ratio } from "./Type.ts";
 import type { Predicate, WidenLiteral } from "./Types.ts";
 /** Integer literal from `1` to `99`. */
 export type Int1To99 = Digit1To99 extends `${infer Value extends number}` ? Value : never;
@@ -76,14 +76,57 @@ export type Int1To100OrPositiveInt = Int1To100 | PositiveInt;
  * ```
  */
 export type Percentage = PercentageLiteral | Ratio;
+export type PercentageLiteral = "0%" | "100%" | `${Digit1To99}%` | `${"0" | Digit1To99}.${Digit1To9}%`;
 /**
- * Percentage literal from `"0%"` to `"100%"`.
+ * Percentage literal Type with compile-time and runtime validation.
  *
- * Decimal literals support one decimal place. Use {@link Ratio} for computed
- * values or greater precision.
+ * 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 declare const PercentageLiteral: import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"0%">, import("./Type.ts").LiteralType<"100%">, import("./Type.ts").TemplateLiteralType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>, import("./Type.ts").TemplateLiteralType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>, import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"0">, import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>]>]>, "%"]>, import("./Type.ts").TemplateLiteralType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"0">, import("./Type.ts").UnionType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>, import("./Type.ts").TemplateLiteralType<readonly [import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>, import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"0">, import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>]>]>]>, ".", import("./Type.ts").UnionType<readonly [import("./Type.ts").LiteralType<"1">, import("./Type.ts").LiteralType<"2">, import("./Type.ts").LiteralType<"3">, import("./Type.ts").LiteralType<"4">, import("./Type.ts").LiteralType<"5">, import("./Type.ts").LiteralType<"6">, import("./Type.ts").LiteralType<"7">, import("./Type.ts").LiteralType<"8">, import("./Type.ts").LiteralType<"9">]>, "%"]>]>;
-export type PercentageLiteral = typeof PercentageLiteral.Output;
+export declare const PercentageLiteral: Type<"PercentageLiteral", PercentageLiteral, PercentageLiteral, PercentageLiteralError>;
+/** 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 declare const percentageToRatio: (percentage: Percentage) => Ratio;
 export declare const increment: (n: number) => number;
@@ -150,7 +193,7 @@ minNumberOfItemsPerBucket?: number & import("./Brand.ts").Brand<"NonNaN"> & impo
  *
  * Limited to 78 because F(79) exceeds JavaScript's `MAX_SAFE_INTEGER`.
  */
-export declare const FibonacciIndex: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").Type<"Number", number, number, import("./Type.ts").TypeOfError<"Number">, null, import("./Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("./Type.ts").NonNaNError>, "Finite", import("./Type.ts").FiniteError>, "Int", import("./Type.ts").IntError>, "NonNegative", import("./Type.ts").NonNegativeError>, "Positive", import("./Type.ts").PositiveError>, "LessThanOrEqualTo78", import("./Type.ts").LessThanOrEqualToError<78>>, "FibonacciIndex", never>;
+export declare const FibonacciIndex: import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<import("./Type.ts").BrandType<Type<"Number", number, number, import("./Type.ts").TypeOfError<"Number">, null, import("./Type.ts").TypeOfError<"Number">, never, number, true>, "NonNaN", import("./Type.ts").NonNaNError>, "Finite", import("./Type.ts").FiniteError>, "Int", import("./Type.ts").IntError>, "NonNegative", import("./Type.ts").NonNegativeError>, "Positive", import("./Type.ts").PositiveError>, "LessThanOrEqualTo78", import("./Type.ts").LessThanOrEqualToError<78>>, "FibonacciIndex", never>;
 export type FibonacciIndex = typeof FibonacciIndex.Output;
 /** Returns the Fibonacci number at the given index (1-indexed: 1,1,2,3,5,8,...). */
 export declare const fibonacciAt: (index: FibonacciIndex) => PositiveInt;

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

@@ -1 +1 @@
-{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAGL,UAAU,EAGV,cAAc,EACd,WAAW,EACX,KAAK,EAGN,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,wCAAwC;AACxC,MAAM,MAAM,QAAQ,GAAG,UAAU,SAAS,GAAG,MAAM,KAAK,SAAS,MAAM,EAAE,GACrE,KAAK,GACL,KAAK,CAAC;AAEV,yCAAyC;AACzC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,GAAG,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,GAAG,SAAS,GAAG,cAAc,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,sBAAsB,GAAG,SAAS,GAAG,WAAW,CAAC;AAE7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,UAAU,GAAG,iBAAiB,GAAG,KAAK,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,ysGAU7B,CAAC;AACF,MAAM,MAAM,iBAAiB,GAAG,OAAO,iBAAiB,CAAC,MAAM,CAAC;AAEhE,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,eAAgB,UAAU,KAAG,KAGH,CAAC;AAEzD,eAAO,MAAM,SAAS,MAAO,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,MAAO,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,QACV,MAAM,OAAO,MAAM,SACrB,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS,QACd,MAAM,OAAO,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,aACvB,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,aACvB,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACE,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,sBAAsB,kBAClB,cAAc;AAE7B,kBAAkB;;AAGlB,iBAAiB;8OAEhB,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,6rBAG1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,MAAM,CAAC;AAE1D,oFAAoF;AACpF,eAAO,MAAM,WAAW,UAAW,cAAc,KAAG,WAMnD,CAAC"}
+{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"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"}

package/dist/src/Number.js

@@ -4,18 +4,57 @@
  * @module
  */
 import { assertNonEmptyReadonlyArray } from "./Assert.js";
+import { safelyStringifyUnknownValue } from "./String.js";
 import { err, ok } from "./Result.js";
-import { brand, Digit1To9, Digit1To99, lessThanOrEqualTo, onePositiveInt, NonNegativeInt, PositiveInt, Ratio, templateLiteral, union, } from "./Type.js";
-/**
- * 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("0%", "100%", 
+import { brand, createTypeWithError, Digit1To9, Digit1To99, lessThanOrEqualTo, onePositiveInt, NonNegativeInt, PositiveInt, Ratio, templateLiteral, union, } from "./Type.js";
+const percentageLiteralSyntax = /*#__PURE__*/ union("0%", "100%", 
 /*#__PURE__*/ templateLiteral(Digit1To99, "%"), 
 /*#__PURE__*/ templateLiteral(
 /*#__PURE__*/ union("0", Digit1To99), ".", Digit1To9, "%"));
+/**
+ * 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 = /*#__PURE__*/ createTypeWithError("PercentageLiteral", percentageLiteralSyntax, (cause, value) => ({
+    type: "PercentageLiteral",
+    value,
+    cause,
+}), (error) => `The value ${safelyStringifyUnknownValue(error.value)} is not a percentage literal. Use a value such as "50%" or "12.5%".`);
 /** Converts a {@link Percentage} to its numeric {@link Ratio}. */
 export const percentageToRatio = (percentage) => typeof percentage === "number"
     ? percentage

package/dist/src/Object.d.ts

@@ -175,6 +175,38 @@ export declare const objectFrom: <K extends string, V>(keys: ReadonlyArray<K>, g
  * Uses `K extends string` for precision.
  */
 export declare const mapObject: <K extends string, V, U>(record: ReadonlyRecord<K, V>, fn: (value: V, key: K) => U) => ReadonlyRecord<K, U>;
+/**
+ * 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 declare const filterObjectKeys: <T extends object>(source: T, predicate: (key: string) => boolean) => Readonly<Partial<Pick<T, Exclude<keyof T, symbol>>>>;
 /** Conditionally excludes a property from an object. */
 export declare const excludeProp: <T extends object, K extends keyof T>(obj: T, prop: K, condition?: boolean) => typeof condition extends true ? T : Omit<T, K>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Object.d.ts","sourceRoot":"","sources":["../../src/Object.ts"],"names":[],"mappings":"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"}

package/dist/src/Object.js

@@ -74,6 +74,11 @@ export const isPlainObject = (value) => {
     const prototype = Object.getPrototypeOf(value);
     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") &&
         Object.hasOwn(prototype, "isPrototypeOf"));
@@ -202,6 +207,47 @@ export const mapObject = (record, fn) => {
     }
     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 = (source, predicate) => {
+    const selected = {};
+    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 = (obj, prop, condition) => {
     if (condition) {