@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Function.js

@@ -1,16 +1,18 @@
+/**
+ * Function utilities including exhaustive checks and composition.
+ *
+ * @module
+ */
 /**
  * Helper function to ensure exhaustive matching in a switch statement. Throws
  * an error if an unhandled case is encountered.
  *
- * Remember, it's useful only when we don't return anything from the switch
- * statement. Otherwise, a return type of a function is enough.
- *
  * ### Example
  *
  * ```ts
  * type Color = "red" | "green" | "blue";
  *
- * function handleColor(color: Color): void {
+ * const handleColor = (color: Color): void => {
  *   switch (color) {
  *     case "red":
  *       console.log("Handling red");
@@ -24,14 +26,70 @@
  *     default:
  *       exhaustiveCheck(color); // Ensures all cases are handled
  *   }
- * }
+ * };
+ * ```
+ *
+ * Use this primarily in side-effect switches (`void` branches). For
+ * value-producing switches, TypeScript can enforce exhaustiveness without a
+ * `default` branch.
+ *
+ * ### Example
+ *
+ * Return from each case for value-producing switches.
+ *
+ * ```ts
+ * type Color = "red" | "green" | "blue";
+ *
+ * const colorToHex = (color: Color): string => {
+ *   switch (color) {
+ *     case "red":
+ *       return "#ff0000";
+ *     case "green":
+ *       return "#00ff00";
+ *     case "blue":
+ *       return "#0000ff";
+ *   }
+ * };
+ * ```
+ *
+ * ### Example
+ *
+ * Use assignment + no `default` to get exhaustiveness by definite assignment.
+ *
+ * ```ts
+ * type Input =
+ *   | { readonly type: "Mutate" }
+ *   | { readonly type: "Query" }
+ *   | { readonly type: "Export" };
+ *
+ * const onInput = (input: Input): void => {
+ *   let result: "A" | "B" | "C";
+ *
+ *   switch (input.type) {
+ *     case "Mutate":
+ *       result = "A";
+ *       break;
+ *     case "Query":
+ *       result = "B";
+ *       break;
+ *     case "Export":
+ *       result = "C";
+ *       break;
+ *   }
+ *
+ *   handleKind(result);
+ * };
+ *
+ * const handleKind = (kind: "A" | "B" | "C"): void => {
+ *   console.log(kind);
+ * };
  * ```
  */
 export const exhaustiveCheck = (value) => {
     throw new Error(`exhaustiveCheck unhandled case: ${JSON.stringify(value)}`);
 };
 /**
- * Returns the input value unchanged.
+ * Returns the value unchanged.
  *
  * Useful as a default transformation, placeholder callback, or when a function
  * is required but no transformation is needed.
@@ -47,11 +105,57 @@ export const exhaustiveCheck = (value) => {
  * ```
  */
 export const identity = (a) => a;
-export function readonly(value) {
-    return value;
-}
-export const constVoid = () => undefined;
-export const constUndefined = () => undefined;
-export const constNull = () => null;
-export const constTrue = () => true;
-export const constFalse = () => false;
+/**
+ * Creates a {@link Lazy} from a precomputed value.
+ *
+ * Use when the value is expensive to compute and want to compute it once at
+ * definition time rather than on every call.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Computed once at definition, returned on every call
+ * const getConfig = lazy(parseConfig(rawConfig));
+ *
+ * // vs. computed on every call
+ * const getConfig = () => parseConfig(rawConfig);
+ * ```
+ */
+export const lazy = (value) => () => value;
+/** A {@link Lazy} that returns `true`. */
+export const lazyTrue = /*#__PURE__*/ lazy(true);
+/** A {@link Lazy} that returns `false`. */
+export const lazyFalse = /*#__PURE__*/ lazy(false);
+/** A {@link Lazy} that returns `null`. */
+export const lazyNull = /*#__PURE__*/ lazy(null);
+/** A {@link Lazy} that returns `undefined`. */
+export const lazyUndefined = /*#__PURE__*/ lazy(undefined);
+/** A {@link Lazy} that returns `undefined` for void callbacks. */
+export const lazyVoid = lazyUndefined;
+/**
+ * Development placeholder that always throws.
+ *
+ * Use to sketch function bodies before implementing them. TypeScript infers the
+ * return type from context, so surrounding code still type-checks. Use an
+ * explicit generic when there is no return type annotation.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Type inferred from return type annotation
+ * const fetchUser = (id: UserId): Result<User, FetchError> => todo();
+ *
+ * expectTypeOf(fetchUser).returns.toEqualTypeOf<
+ *   Result<User, FetchError>
+ * >();
+ *
+ * // Explicit generic when no return type
+ * const getConfig = () => todo<Config>();
+ *
+ * expectTypeOf(getConfig).returns.toEqualTypeOf<Config>();
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+export const todo = () => {
+    throw new Error("not yet implemented");
+};

package/dist/src/Identicon.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Visual identicon generation from IDs.
+ *
+ * @module
+ */
 import type { Brand } from "./Brand.js";
 import { Id } from "./Type.js";
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAG5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,QAAO,cAAyB,KAC/B,SA4JF,CAAC"}
+{"version":3,"file":"Identicon.d.ts","sourceRoot":"","sources":["../../src/Identicon.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,EAAE,EAAe,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC;AAEpD,+BAA+B;AAC/B,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,eAAe,GAC1B,IAAI,EAAE,EACN,QAAO,cAAyB,KAC/B,SA4JF,CAAC"}

package/dist/src/Identicon.js

@@ -1,5 +1,10 @@
-import { idToIdBytes } from "./Type.js";
+/**
+ * Visual identicon generation from IDs.
+ *
+ * @module
+ */
 import { md5 } from "@noble/hashes/legacy.js";
+import { Id, idToIdBytes } from "./Type.js";
 /**
  * Creates a deterministic identicon SVG from an {@link Id}.
  *

package/dist/src/Lookup.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Lookup-key collections and helpers.
+ *
+ * @module
+ */
+import type { Brand } from "./Brand.js";
+/**
+ * Derives the native lookup key used by lookup-based collections.
+ *
+ * Native `Map` and `Set` are suitable for primitive keys and keys where
+ * reference identity is the intended key, but they are not useful when
+ * different references should represent the same logical key.
+ *
+ * Lookup-based collections solve that by deriving a stable lookup key from each
+ * input key and using that lookup key for the internal native `Map` lookup.
+ * Keys that derive the same lookup key are treated as the same logical key.
+ *
+ * Use this when callers provide keys in one form but logical identity should be
+ * based on another stable key, such as a natural id or {@link StructuralKey}.
+ *
+ * @see {@link createLookupMap}
+ * @see {@link createLookupSet}
+ */
+export type Lookup<K, L> = (key: K) => L;
+/** Optional {@link Lookup}. */
+export interface LookupOption<K, L = K> {
+    /** Derives the lookup key used for logical equality. */
+    readonly lookup?: Lookup<K, L>;
+}
+/**
+ * `Map`-like collection keyed by a {@link Lookup derived lookup key}.
+ *
+ * `set` preserves the first inserted representative for a logical key. `getKey`
+ * returns that representative for callers that need stable identity.
+ *
+ * @see {@link createLookupMap}
+ */
+export interface LookupMap<K, V> extends Iterable<readonly [K, V]> {
+    readonly size: number;
+    readonly has: (key: K) => boolean;
+    readonly get: (key: K) => V | undefined;
+    readonly getKey: (key: K) => K | undefined;
+    readonly set: (key: K, value: V) => LookupMap<K, V>;
+    readonly delete: (key: K) => boolean;
+    readonly clear: () => void;
+    readonly keys: () => IterableIterator<K>;
+    readonly values: () => IterableIterator<V>;
+    readonly entries: () => IterableIterator<readonly [K, V]>;
+    readonly forEach: (callback: (value: V, key: K, map: LookupMap<K, V>) => void) => void;
+    readonly [Symbol.iterator]: () => IterableIterator<readonly [K, V]>;
+}
+/** Options for {@link createLookupMap}. */
+export interface CreateLookupMapOptions<K, V, L> extends Required<LookupOption<K, L>> {
+    /** Initial entries for the map. */
+    readonly entries?: Iterable<readonly [K, V]>;
+}
+/** Creates {@link LookupMap}. */
+export declare const createLookupMap: <K, V, L>({ lookup, entries, }: CreateLookupMapOptions<K, V, L>) => LookupMap<K, V>;
+/**
+ * `Set`-like collection keyed by a {@link Lookup derived lookup key}.
+ *
+ * `add` preserves the first inserted representative for a logical key. `get`
+ * returns that representative for callers that need stable identity.
+ *
+ * @see {@link createLookupSet}
+ */
+export interface LookupSet<K> extends Iterable<K> {
+    readonly size: number;
+    readonly has: (key: K) => boolean;
+    readonly get: (key: K) => K | undefined;
+    readonly add: (key: K) => LookupSet<K>;
+    readonly delete: (key: K) => boolean;
+    readonly clear: () => void;
+    readonly keys: () => IterableIterator<K>;
+    readonly values: () => IterableIterator<K>;
+    readonly entries: () => IterableIterator<readonly [K, K]>;
+    readonly forEach: (callback: (value: K, key: K, set: LookupSet<K>) => void) => void;
+    readonly [Symbol.iterator]: () => IterableIterator<K>;
+}
+/** Options for {@link createLookupSet}. */
+export interface CreateLookupSetOptions<K, L> extends Required<LookupOption<K, L>> {
+    /** Initial values for the set. */
+    readonly values?: Iterable<K>;
+}
+/** Creates {@link LookupSet}. */
+export declare const createLookupSet: <K, L>({ lookup, values, }: CreateLookupSetOptions<K, L>) => LookupSet<K>;
+/** Scalar branch shared by {@link StructuralKey} and {@link Structural}. */
+export type StructuralScalar = string | number | boolean | null | Uint8Array;
+/** Branded native key produced by {@link structuralLookup}. */
+export type StructuralLookupKey = string & Brand<"StructuralLookupKey">;
+/**
+ * Immutable structural key.
+ *
+ * Structural keys are JSON-like values with `NaN` and positive/negative
+ * infinity also supported, or `Uint8Array`.
+ *
+ * @see {@link Structural}
+ * @see {@link structuralLookup}
+ */
+export type StructuralKey = StructuralScalar | ReadonlyArray<StructuralKey> | {
+    readonly [key: string]: StructuralKey;
+};
+/**
+ * Compile-time structural form of `T` for structural lookup APIs.
+ *
+ * This exists because {@link StructuralKey} is the runtime serialization model,
+ * not a good public generic constraint for interface-shaped objects.
+ * `StructuralKey` models object values with a string index signature, which is
+ * stricter than ordinary interfaces like `{ readonly id: string }` even though
+ * the runtime serializer accepts such plain objects.
+ *
+ * `Structural<T>` checks a concrete type recursively at compile time instead:
+ * scalars pass through, arrays recurse, object properties recurse, and
+ * function-valued properties are rejected. This keeps public structural APIs
+ * ergonomic for interface-based inputs while preserving the same runtime
+ * constraints as structural lookup serialization.
+ *
+ * @see {@link StructuralKey}
+ * @see {@link structuralLookup}
+ */
+export type Structural<T> = T extends StructuralScalar ? T : T extends ReadonlyArray<infer Item> ? ReadonlyArray<Structural<Item>> : T extends StructuralFunction ? never : T extends object ? {
+    readonly [K in keyof T as Extract<T[K], StructuralFunction> extends never ? K : never]: Structural<Exclude<T[K], StructuralFunction>>;
+} & {
+    readonly [K in keyof T as Extract<T[K], StructuralFunction> extends never ? never : K]?: never;
+} : never;
+/** Function branch excluded by {@link Structural}. */
+export type StructuralFunction = (...args: ReadonlyArray<unknown>) => unknown;
+/**
+ * Returns the structural lookup key for `key`.
+ *
+ * Structural lookup keys are derived from JSON-like values plus `Uint8Array`.
+ * Equal structures produce the same lookup key even when they are different
+ * JavaScript instances.
+ *
+ * The derived key is memoized by non-null object identity in a module-scoped
+ * `WeakMap` shared by all callers, so keys must be immutable.
+ *
+ * Use this as a {@link Lookup} when logical equality should be based on
+ * structural value instead of reference identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const byFilter = createLookupMap<
+ *   { readonly table: string; readonly where: readonly [string, string] },
+ *   string,
+ *   StructuralLookupKey
+ * >({
+ *   lookup: structuralLookup,
+ * });
+ *
+ * byFilter.set({ table: "todo", where: ["owner", "ada"] }, "cached");
+ * byFilter.get({ table: "todo", where: ["owner", "ada"] }); // "cached"
+ * ```
+ *
+ * @see {@link StructuralKey}
+ * @see {@link Structural}
+ */
+export declare const structuralLookup: <K>(key: Structural<K>) => StructuralLookupKey;
+//# sourceMappingURL=Lookup.d.ts.map

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

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

package/dist/src/Lookup.js

@@ -0,0 +1,192 @@
+/**
+ * Lookup-key collections and helpers.
+ *
+ * @module
+ */
+import { assert } from "./Assert.js";
+import { isPlainObject } from "./Object.js";
+import { Uint8Array, uint8ArrayToBase64Url } from "./Type.js";
+/** Creates {@link LookupMap}. */
+export const createLookupMap = ({ lookup, entries, }) => {
+    const entriesByLookupKey = new Map();
+    const map = {
+        get size() {
+            return entriesByLookupKey.size;
+        },
+        has: (key) => entriesByLookupKey.has(lookup(key)),
+        get: (key) => entriesByLookupKey.get(lookup(key))?.value,
+        getKey: (key) => entriesByLookupKey.get(lookup(key))?.key,
+        set: (key, value) => {
+            const lookupKey = lookup(key);
+            const existingEntry = entriesByLookupKey.get(lookupKey);
+            entriesByLookupKey.set(lookupKey, {
+                key: existingEntry?.key ?? key,
+                value,
+            });
+            return map;
+        },
+        delete: (key) => entriesByLookupKey.delete(lookup(key)),
+        clear: () => {
+            entriesByLookupKey.clear();
+        },
+        keys: function* () {
+            for (const entry of entriesByLookupKey.values()) {
+                yield entry.key;
+            }
+        },
+        values: function* () {
+            for (const entry of entriesByLookupKey.values()) {
+                yield entry.value;
+            }
+        },
+        entries: function* () {
+            for (const entry of entriesByLookupKey.values()) {
+                yield [entry.key, entry.value];
+            }
+        },
+        forEach: (callback) => {
+            for (const entry of entriesByLookupKey.values()) {
+                callback(entry.value, entry.key, map);
+            }
+        },
+        [Symbol.iterator]: function () {
+            return map.entries();
+        },
+    };
+    if (entries) {
+        for (const [key, value] of entries) {
+            map.set(key, value);
+        }
+    }
+    return map;
+};
+/** Creates {@link LookupSet}. */
+export const createLookupSet = ({ lookup, values, }) => {
+    const map = createLookupMap({ lookup });
+    const set = {
+        get size() {
+            return map.size;
+        },
+        has: (key) => map.has(key),
+        get: (key) => map.getKey(key),
+        add: (key) => {
+            map.set(key, true);
+            return set;
+        },
+        delete: (key) => map.delete(key),
+        clear: () => {
+            map.clear();
+        },
+        keys: () => map.keys(),
+        values: () => map.keys(),
+        entries: function* () {
+            for (const key of map.keys()) {
+                yield [key, key];
+            }
+        },
+        forEach: (callback) => {
+            for (const key of map.keys()) {
+                callback(key, key, set);
+            }
+        },
+        [Symbol.iterator]: function () {
+            return set.keys();
+        },
+    };
+    if (values) {
+        for (const value of values) {
+            set.add(value);
+        }
+    }
+    return set;
+};
+/**
+ * Returns the structural lookup key for `key`.
+ *
+ * Structural lookup keys are derived from JSON-like values plus `Uint8Array`.
+ * Equal structures produce the same lookup key even when they are different
+ * JavaScript instances.
+ *
+ * The derived key is memoized by non-null object identity in a module-scoped
+ * `WeakMap` shared by all callers, so keys must be immutable.
+ *
+ * Use this as a {@link Lookup} when logical equality should be based on
+ * structural value instead of reference identity.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const byFilter = createLookupMap<
+ *   { readonly table: string; readonly where: readonly [string, string] },
+ *   string,
+ *   StructuralLookupKey
+ * >({
+ *   lookup: structuralLookup,
+ * });
+ *
+ * byFilter.set({ table: "todo", where: ["owner", "ada"] }, "cached");
+ * byFilter.get({ table: "todo", where: ["owner", "ada"] }); // "cached"
+ * ```
+ *
+ * @see {@link StructuralKey}
+ * @see {@link Structural}
+ */
+export const structuralLookup = (key) => structuralLookupInternal(key);
+const structuralLookupKeyByValue = new WeakMap();
+const structuralLookupInternal = (value, path = new Set()) => {
+    switch (typeof value) {
+        case "string":
+            return `s:${JSON.stringify(value)}`;
+        case "number":
+            if (Number.isNaN(value))
+                return "n:NaN";
+            if (value === Number.POSITIVE_INFINITY)
+                return "n:Infinity";
+            if (value === Number.NEGATIVE_INFINITY)
+                return "n:-Infinity";
+            return Object.is(value, -0) ? "n:0" : `n:${value}`;
+        case "boolean":
+            return value ? "b:true" : "b:false";
+        case "object": {
+            if (value === null)
+                return "l:null";
+            const cachedLookupKey = structuralLookupKeyByValue.get(value);
+            if (cachedLookupKey)
+                return cachedLookupKey;
+            let lookupKey;
+            if (Array.isArray(value)) {
+                assert(!path.has(value), "Structural lookup keys must not contain cycles.");
+                path.add(value);
+                lookupKey = getStructuralArrayLookupKey(value, path);
+                path.delete(value);
+            }
+            else if (isPlainObject(value)) {
+                assert(!path.has(value), "Structural lookup keys must not contain cycles.");
+                path.add(value);
+                lookupKey = getStructuralObjectLookupKey(value, path);
+                path.delete(value);
+            }
+            else if (Uint8Array.is(value)) {
+                lookupKey = `u:${uint8ArrayToBase64Url(value)}`;
+            }
+            else {
+                assert(false, "Structural lookup keys must be JSON-like values or Uint8Array.");
+            }
+            structuralLookupKeyByValue.set(value, lookupKey);
+            return lookupKey;
+        }
+        default:
+            assert(false, "Structural lookup keys must be JSON-like values or Uint8Array.");
+    }
+};
+const getStructuralArrayLookupKey = (value, path) => `a:[${Array.from(value, (item) => structuralLookupInternal(item, path)).join(",")}]`;
+const getStructuralObjectLookupKey = (value, path) => {
+    const valueRecord = value;
+    const entries = Object.keys(valueRecord)
+        .toSorted()
+        .map((key) => {
+        const item = valueRecord[key];
+        return `${JSON.stringify(key)}:${structuralLookupInternal(item, path)}`;
+    });
+    return `o:{${entries.join(",")}}`;
+};

package/dist/src/Microtask.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Microtask queue utilities.
+ *
+ * @module
+ */
+import { type NonEmptyReadonlyArray } from "./Array.js";
+/**
+ * Batches values and flushes them in a single microtask.
+ *
+ * Calls to {@link MicrotaskBatch.push} within the same tick are coalesced into
+ * one flush.
+ */
+export interface MicrotaskBatch<T> extends Disposable {
+    /** Enqueues one item and schedules a microtask flush if needed. */
+    readonly push: (item: T) => void;
+    /** Flushes queued items immediately. */
+    readonly flushNow: () => void;
+}
+/** Creates {@link MicrotaskBatch}. */
+export declare const createMicrotaskBatch: <T>(onFlush: (items: NonEmptyReadonlyArray<T>) => void) => MicrotaskBatch<T>;
+//# sourceMappingURL=Microtask.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Microtask.d.ts","sourceRoot":"","sources":["../../src/Microtask.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAiB,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,CAAE,SAAQ,UAAU;IACnD,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;IAEjC,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,CAAC;CAC/B;AAED,sCAAsC;AACtC,eAAO,MAAM,oBAAoB,GAAI,CAAC,EACpC,SAAS,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,KAAK,IAAI,KACjD,cAAc,CAAC,CAAC,CAgClB,CAAC"}

package/dist/src/Microtask.js

@@ -0,0 +1,37 @@
+/**
+ * Microtask queue utilities.
+ *
+ * @module
+ */
+import { appendToArray } from "./Array.js";
+/** Creates {@link MicrotaskBatch}. */
+export const createMicrotaskBatch = (onFlush) => {
+    let queue = null;
+    let disposed = false;
+    const flushNow = () => {
+        if (disposed || queue == null)
+            return;
+        const queuedItems = queue;
+        queue = null;
+        onFlush(queuedItems);
+    };
+    return {
+        push: (item) => {
+            if (disposed)
+                return;
+            if (queue == null) {
+                queue = [item];
+                queueMicrotask(flushNow);
+                return;
+            }
+            queue = appendToArray(queue, item);
+        },
+        flushNow,
+        [Symbol.dispose]: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            queue = null;
+        },
+    };
+};

package/dist/src/Number.d.ts

@@ -1,8 +1,13 @@
-import { NonEmptyReadonlyArray } from "./Array.js";
-import { Result } from "./Result.js";
+/**
+ * Number arithmetic, comparison, and branded numeric types.
+ *
+ * @module
+ */
+import type { NonEmptyReadonlyArray } from "./Array.js";
+import type { IsBranded } from "./Brand.js";
+import type { Result } from "./Result.js";
 import { NonNegativeInt, PositiveInt } from "./Type.js";
-import { Predicate, WidenLiteral } from "./Types.js";
-import { IsBranded } from "./Brand.js";
+import type { Predicate, WidenLiteral } from "./Types.js";
 export declare const increment: (n: number) => number;
 export declare const decrement: (n: number) => number;
 /** Clamps a number within a given range. */
@@ -40,4 +45,13 @@ export declare const computeBalancedBuckets: (numberOfItems: NonNegativeInt,
 numberOfBuckets?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">, 
 /** Default: 2 */
 minNumberOfItemsPerBucket?: number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">) => Result<NonEmptyReadonlyArray<PositiveInt>, PositiveInt>;
+/**
+ * Valid index for {@link fibonacciAt}, constrained to 1-78.
+ *
+ * Limited to 78 because F(79) exceeds JavaScript's `MAX_SAFE_INTEGER`.
+ */
+export declare const FibonacciIndex: import("./Type.js").BrandType<import("./Type.js").BrandType<import("./Type.js").Type<"Brand", number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative"> & import("./Brand.js").Brand<"Positive">, number, import("./Type.js").PositiveError, number & import("./Brand.js").Brand<"Int"> & import("./Brand.js").Brand<"NonNegative">, import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError>, "LessThanOrEqualTo78", import("./Type.js").LessThanOrEqualToError<78>, import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError | import("./Type.js").PositiveError>, "FibonacciIndex", import("./Type.js").BrandWithoutRefineError<"FibonacciIndex", import("./Type.js").NumberError | import("./Type.js").NonNegativeError | import("./Type.js").IntError | import("./Type.js").PositiveError | import("./Type.js").LessThanOrEqualToError<78>>, never>;
+export type FibonacciIndex = typeof FibonacciIndex.Type;
+/** Returns the Fibonacci number at the given index (1-indexed: 1,1,2,3,5,8,...). */
+export declare const fibonacciAt: (index: FibonacciIndex) => PositiveInt;
 //# sourceMappingURL=Number.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Number.d.ts","sourceRoot":"","sources":["../../src/Number.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAoB,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,CAAC,CAAC,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC,CAAC,KAClC,SAAS,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,CACa,CAAC;AAE/D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,iJAAyC;AAEzC,iBAAiB;AACjB,2JAAkD,KACjD,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC"}
+{"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,EAIL,cAAc,EACd,WAAW,EACZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE1D,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,eAAO,MAAM,SAAS,GAAI,GAAG,MAAM,KAAG,MAAe,CAAC;AAEtD,4CAA4C;AAC5C,eAAO,MAAM,KAAK,GACf,KAAK,MAAM,EAAE,KAAK,MAAM,MACxB,GAAG,MAAM,KAAG,MACoB,CAAC;AAEpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,SAAS,GACnB,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,SAAS,CAAC,MAAM,CAEd,CAAC;AAEjC,wEAAwE;AACxE,eAAO,MAAM,GAAG,GAAI,CAAC,SAAS,MAAM,EAClC,GAAG,QAAQ,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,EAClC,GAAG,QAAQ,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;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,GACjC,eAAe,cAAc;AAE7B,kBAAkB;AAClB,iJAAyC;AAEzC,iBAAiB;AACjB,2JAAkD,KACjD,MAAM,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,WAAW,CAoBxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,k7BAG1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,WAAW,GAAI,OAAO,cAAc,KAAG,WAMnD,CAAC"}