@evolu/common 5.4.7 → 6.0.0

package/dist/src/Evolu/Sync.d.ts

@@ -0,0 +1,59 @@
+import { ConsoleConfig, ConsoleDep } from "../Console.js";
+import { ProtocolMessage } from "./Protocol.js";
+import { Millis } from "./Timestamp.js";
+export interface Sync {
+    readonly send: (message: ProtocolMessage) => void;
+}
+export interface SyncDep {
+    readonly sync: Sync;
+}
+export type CreateSync = (deps: ConsoleDep) => (config: SyncConfig) => Sync;
+export interface CreateSyncDep {
+    readonly createSync: CreateSync;
+}
+export interface SyncConfig extends ConsoleConfig {
+    readonly syncUrl: string;
+    readonly onOpen: (send: Sync["send"]) => void;
+    readonly onMessage: (message: Uint8Array, send: Sync["send"]) => void;
+}
+export declare const createWebSocketSync: CreateSync;
+/**
+ * The possible states of a synchronization process. The `SyncState` can be one
+ * of the following:
+ *
+ * - {@link SyncStateInitial}
+ * - {@link SyncStateIsSyncing}
+ * - {@link SyncStateIsSynced}
+ * - {@link SyncStateIsNotSynced}
+ */
+export type SyncState = SyncStateInitial | SyncStateIsSyncing | SyncStateIsSynced | SyncStateIsNotSynced;
+/**
+ * The initial synchronization state when the app starts. In this state, the app
+ * needs to determine whether the data is synced.
+ */
+export interface SyncStateInitial {
+    readonly type: "SyncStateInitial";
+}
+export interface SyncStateIsSyncing {
+    readonly type: "SyncStateIsSyncing";
+}
+export interface SyncStateIsSynced {
+    readonly type: "SyncStateIsSynced";
+    readonly time: Millis;
+}
+export interface SyncStateIsNotSynced {
+    readonly type: "SyncStateIsNotSynced";
+    readonly error: NetworkError | ServerError | PaymentRequiredError;
+}
+export interface NetworkError {
+    readonly type: "NetworkError";
+}
+export interface ServerError {
+    readonly type: "ServerError";
+    readonly status: number;
+}
+export interface PaymentRequiredError {
+    readonly type: "PaymentRequiredError";
+}
+export declare const initialSyncState: SyncStateInitial;
+//# sourceMappingURL=Sync.d.ts.map

package/dist/src/Evolu/Sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sync.d.ts","sourceRoot":"","sources":["../../../src/Evolu/Sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAExC,MAAM,WAAW,IAAI;IACnB,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD;AAED,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;CACrB;AAED,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;AAE5E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;CACjC;AAED,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;CACvE;AAED,eAAO,MAAM,mBAAmB,EAAE,UA2BjC,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,iBAAiB,GACjB,oBAAoB,CAAC;AAEzB;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;CACnC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,WAAW,GAAG,oBAAoB,CAAC;CACnE;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;CAC/B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,eAAO,MAAM,gBAAgB,EAAE,gBAA+C,CAAC"}

package/dist/src/Evolu/Sync.js

@@ -0,0 +1,29 @@
+import { createWebSocket } from "../WebSocket.js";
+export const createWebSocketSync = (_deps) => (config) => {
+    const sync = {
+        send: (message) => {
+            /**
+             * We don't need an in-memory queue; apps can be offline for a long time,
+             * and mutations are stored in SQLite. Dropped CRDT messages are synced
+             * when the web socket connection is open.
+             */
+            if (socket.getReadyState() !== "open")
+                return;
+            socket.send(message);
+        },
+    };
+    const socket = createWebSocket(config.syncUrl, {
+        binaryType: "arraybuffer",
+        onOpen: () => {
+            config.onOpen(sync.send);
+        },
+        onMessage: (data) => {
+            if (data instanceof ArrayBuffer) {
+                const messages = new Uint8Array(data);
+                config.onMessage(messages, sync.send);
+            }
+        },
+    });
+    return sync;
+};
+export const initialSyncState = { type: "SyncStateInitial" };

package/dist/src/Evolu/Timestamp.d.ts

@@ -0,0 +1,106 @@
+import { NanoIdLibDep } from "../NanoId.js";
+import { Order } from "../Order.js";
+import { Result } from "../Result.js";
+import { TimeDep } from "../Time.js";
+import { Brand } from "../Types.js";
+export interface TimestampConfig {
+    /**
+     * Maximum physical clock drift allowed in ms.
+     *
+     * The default value is 5 * 60 * 1000 (5 minutes).
+     */
+    readonly maxDrift: number;
+}
+export interface TimestampConfigDep {
+    readonly timestampConfig: TimestampConfig;
+}
+export type TimestampError = TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError;
+export interface TimestampDriftError {
+    readonly type: "TimestampDriftError";
+    readonly next: Millis;
+    readonly now: Millis;
+}
+export interface TimestampCounterOverflowError {
+    readonly type: "TimestampCounterOverflowError";
+}
+export interface TimestampDuplicateNodeError {
+    readonly type: "TimestampDuplicateNodeError";
+    readonly nodeId: NodeId;
+}
+export interface TimestampTimeOutOfRangeError {
+    readonly type: "TimestampTimeOutOfRangeError";
+}
+/**
+ * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
+ * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
+ * for infinity). This enables more efficient binary serialization, saving 2
+ * bytes compared to the typical 8-byte (64-bit) timestamp representation.
+ *
+ * This limit is enforced to prevent data corruption. If a device's clock
+ * exceeds this range, Evolu will stop saving data until the clock is
+ * corrected.
+ *
+ * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
+ */
+export declare const Millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+export type Millis = typeof Millis.Type;
+export declare const minMillis: Millis;
+export declare const maxMillis: Millis;
+export declare const Counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+export type Counter = typeof Counter.Type;
+export declare const minCounter: Counter;
+export declare const maxCounter: Counter;
+/**
+ * A NodeId uniquely identifies an owner's device. Generated once per device
+ * using cryptographic randomness.
+ *
+ * Collision probability (birthday paradox):
+ *
+ * - 1,000 devices: ~0.00000000000271% (negligible).
+ * - 1M devices: ~0.00000271% (1 in 37M chance).
+ * - 135M devices: ~1% chance.
+ * - 4.29B devices: ~50% chance.
+ *
+ * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
+ *
+ * What will happen if a different device generates the same NodeId?
+ *
+ * If the device belongs to a different owner, nothing will happen because
+ * different owner have different owner IDs. Timestamps are partitioned by
+ * OwnerId.
+ *
+ * If the device belongs to the same owner, the other device will return
+ * {@link TimestampDuplicateNodeError}.
+ */
+export declare const NodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
+export type NodeId = typeof NodeId.Type;
+export declare const minNodeId: NodeId;
+export declare const maxNodeId: NodeId;
+/**
+ * Hybrid Logical Clock timestamp.
+ *
+ * - https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
+ * - https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
+ * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
+ */
+export declare const Timestamp: import("../Type.js").ObjectType<{
+    millis: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, `LessThanOrEqualTo${number}`, import("../Type.js").LessThanOrEqualToError<number>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Millis", import("../Type.js").BrandWithoutRefineError<"Millis", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<number>>, never>;
+    counter: import("../Type.js").BrandType<import("../Type.js").BrandType<import("../Type.js").Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, import("../Type.js").NonNegativeError, number & Brand<"Int">, import("../Type.js").NumberError | import("../Type.js").IntError>, "LessThanOrEqualTo65535", import("../Type.js").LessThanOrEqualToError<65535>, import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError>, "Counter", import("../Type.js").BrandWithoutRefineError<"Counter", import("../Type.js").NumberError | import("../Type.js").NonNegativeError | import("../Type.js").IntError | import("../Type.js").LessThanOrEqualToError<65535>>, never>;
+    nodeId: import("../Type.js").BrandType<import("../Type.js").Type<"String", string, string, import("../Type.js").StringError, string, import("../Type.js").StringError>, "NodeId", import("../Type.js").RegexError<"NodeId">, import("../Type.js").StringError>;
+}>;
+export type Timestamp = typeof Timestamp.Type;
+export declare const createTimestamp: ({ millis, counter, nodeId, }?: Partial<Timestamp>) => Timestamp;
+export declare const createInitialTimestamp: (deps: NanoIdLibDep) => Timestamp;
+/** TimestampString is a sortable string version of {@link Timestamp}. */
+export type TimestampString = string & Brand<"TimestampString">;
+export declare const timestampToTimestampString: (t: Timestamp) => TimestampString;
+export declare const timestampStringToTimestamp: (timestampString: TimestampString) => Timestamp;
+export declare const sendTimestamp: (deps: TimeDep & TimestampConfigDep) => (timestamp: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampTimeOutOfRangeError>;
+export declare const receiveTimestamp: (deps: TimeDep & TimestampConfigDep) => (local: Timestamp, remote: Timestamp) => Result<Timestamp, TimestampDriftError | TimestampCounterOverflowError | TimestampDuplicateNodeError | TimestampTimeOutOfRangeError>;
+/** BinaryTimestamp is a binary and sortable version of {@link Timestamp} for DB. */
+export type BinaryTimestamp = Uint8Array & Brand<"BinaryTimestamp">;
+export declare const binaryTimestampLength: number & Brand<"Int"> & Brand<"NonNegative">;
+export declare const timestampToBinaryTimestamp: (timestamp: Timestamp) => BinaryTimestamp;
+export declare const binaryTimestampToTimestamp: (timestamp: BinaryTimestamp) => Timestamp;
+export declare const orderBinaryTimestamp: Order<BinaryTimestamp>;
+//# sourceMappingURL=Timestamp.d.ts.map

package/dist/src/Evolu/Timestamp.d.ts.map

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

package/dist/src/Evolu/Timestamp.js

@@ -0,0 +1,179 @@
+import { assert } from "../Assert.js";
+import { increment } from "../Number.js";
+import { orderUint8Array } from "../Order.js";
+import { err, getOrThrow, ok } from "../Result.js";
+import { brand, lessThanOrEqualTo, NonNegativeInt, object, regex, String, } from "../Type.js";
+/**
+ * Millis is a timestamp in milliseconds, like `Date.now()`, but limited to the
+ * maximum value representable in 6 bytes (281474976710655) minus 1 (reserved
+ * for infinity). This enables more efficient binary serialization, saving 2
+ * bytes compared to the typical 8-byte (64-bit) timestamp representation.
+ *
+ * This limit is enforced to prevent data corruption. If a device's clock
+ * exceeds this range, Evolu will stop saving data until the clock is
+ * corrected.
+ *
+ * `new Date(281474976710654).toString()` = Tue Aug 02 10889 07:31:49
+ */
+export const Millis = brand("Millis", lessThanOrEqualTo(281474976710655 - 1)(NonNegativeInt));
+export const minMillis = 0;
+export const maxMillis = (281474976710655 - 1);
+export const Counter = brand("Counter", lessThanOrEqualTo(65535)(NonNegativeInt));
+export const minCounter = 0;
+export const maxCounter = 65535;
+/**
+ * A NodeId uniquely identifies an owner's device. Generated once per device
+ * using cryptographic randomness.
+ *
+ * Collision probability (birthday paradox):
+ *
+ * - 1,000 devices: ~0.00000000000271% (negligible).
+ * - 1M devices: ~0.00000271% (1 in 37M chance).
+ * - 135M devices: ~1% chance.
+ * - 4.29B devices: ~50% chance.
+ *
+ * https://lemire.me/blog/2019/12/12/are-64-bit-random-identifiers-free-from-collision
+ *
+ * What will happen if a different device generates the same NodeId?
+ *
+ * If the device belongs to a different owner, nothing will happen because
+ * different owner have different owner IDs. Timestamps are partitioned by
+ * OwnerId.
+ *
+ * If the device belongs to the same owner, the other device will return
+ * {@link TimestampDuplicateNodeError}.
+ */
+export const NodeId = regex("NodeId", /^[a-f0-9]{16}$/)(String);
+export const minNodeId = "0000000000000000";
+export const maxNodeId = "ffffffffffffffff";
+/**
+ * Hybrid Logical Clock timestamp.
+ *
+ * - https://muratbuffalo.blogspot.com/2014/07/hybrid-logical-clocks.html
+ * - https://sergeiturukin.com/2017/06/26/hybrid-logical-clocks.html
+ * - https://jaredforsyth.com/posts/hybrid-logical-clocks/
+ */
+export const Timestamp = object({
+    millis: Millis,
+    counter: Counter,
+    nodeId: NodeId,
+});
+export const createTimestamp = ({ millis = minMillis, counter = minCounter, nodeId = minNodeId, } = {}) => ({ millis, counter, nodeId });
+const hexAlphabet = "0123456789abcdef";
+export const createInitialTimestamp = (deps) => {
+    const nodeId = deps.nanoIdLib.customAlphabet(hexAlphabet, 16)();
+    return createTimestamp({ nodeId });
+};
+export const timestampToTimestampString = (t) => [
+    new Date(t.millis).toISOString(),
+    t.counter.toString(16).toUpperCase().padStart(4, "0"),
+    t.nodeId,
+].join("-");
+export const timestampStringToTimestamp = (timestampString) => {
+    const array = timestampString.split("-");
+    const timestamp = {
+        millis: Date.parse(array.slice(0, 3).join("-")).valueOf(),
+        counter: parseInt(array[3], 16),
+        nodeId: array[4],
+    };
+    assert(Timestamp.is(timestamp), "timestampString is malformed");
+    return timestamp;
+};
+const getNextMillis = (deps) => (millis) => {
+    const now = Millis.from(deps.time.now());
+    if (!now.ok) {
+        return err({ type: "TimestampTimeOutOfRangeError" });
+    }
+    const next = Math.max(now.value, ...millis);
+    return next - now.value > deps.timestampConfig.maxDrift
+        ? err({
+            type: "TimestampDriftError",
+            now: now.value,
+            next,
+        })
+        : ok(next);
+};
+const incrementCounter = (counter) => {
+    const next = Counter.from(increment(counter));
+    if (!next.ok)
+        return err({ type: "TimestampCounterOverflowError" });
+    return ok(next.value);
+};
+export const sendTimestamp = (deps) => (timestamp) => {
+    const millis = getNextMillis(deps)([timestamp.millis]);
+    if (!millis.ok)
+        return millis;
+    const counter = millis.value === timestamp.millis
+        ? incrementCounter(timestamp.counter)
+        : ok(minCounter);
+    if (!counter.ok)
+        return counter;
+    return ok({
+        millis: millis.value,
+        counter: counter.value,
+        nodeId: timestamp.nodeId,
+    });
+};
+export const receiveTimestamp = (deps) => (local, remote) => {
+    if (local.nodeId === remote.nodeId) {
+        return err({ type: "TimestampDuplicateNodeError", nodeId: local.nodeId });
+    }
+    const millis = getNextMillis(deps)([local.millis, remote.millis]);
+    if (!millis.ok)
+        return millis;
+    const counter = millis.value === local.millis && millis.value === remote.millis
+        ? incrementCounter(Math.max(local.counter, remote.counter))
+        : millis.value === local.millis
+            ? incrementCounter(local.counter)
+            : millis.value === remote.millis
+                ? incrementCounter(remote.counter)
+                : ok(minCounter);
+    if (!counter.ok)
+        return counter;
+    return ok({
+        millis: millis.value,
+        counter: counter.value,
+        nodeId: local.nodeId,
+    });
+};
+export const binaryTimestampLength = getOrThrow(NonNegativeInt.from(16));
+export const timestampToBinaryTimestamp = (timestamp) => {
+    const { millis, counter, nodeId } = timestamp;
+    // 6 bytes for millis, 2 bytes for counter, 8 bytes for nodeId.
+    const value = new Uint8Array(16);
+    // Encode `millis` into the first 6 bytes.
+    const millisBigInt = BigInt(millis);
+    value[0] = Number((millisBigInt >> 40n) & 0xffn);
+    value[1] = Number((millisBigInt >> 32n) & 0xffn);
+    value[2] = Number((millisBigInt >> 24n) & 0xffn);
+    value[3] = Number((millisBigInt >> 16n) & 0xffn);
+    value[4] = Number((millisBigInt >> 8n) & 0xffn);
+    value[5] = Number(millisBigInt & 0xffn);
+    // Encode `counter` into the next 2 bytes.
+    value[6] = (counter >> 8) & 0xff;
+    value[7] = counter & 0xff;
+    // Encode `nodeId` (16-character hex string) into the next 8 bytes.
+    for (let i = 0; i < 8; i++) {
+        const byte = parseInt(nodeId.slice(i * 2, i * 2 + 2), 16);
+        value[8 + i] = byte;
+    }
+    return value;
+};
+export const binaryTimestampToTimestamp = (timestamp) => {
+    // Decode `millis` from the first 6 bytes.
+    const millis = (BigInt(timestamp[0]) << 40n) |
+        (BigInt(timestamp[1]) << 32n) |
+        (BigInt(timestamp[2]) << 24n) |
+        (BigInt(timestamp[3]) << 16n) |
+        (BigInt(timestamp[4]) << 8n) |
+        BigInt(timestamp[5]);
+    // Decode `counter` from the next 2 bytes.
+    const counter = (timestamp[6] << 8) | timestamp[7];
+    // Decode `nodeId` from the last 8 bytes.
+    let nodeId = "";
+    for (let i = 8; i < 16; i++) {
+        nodeId += timestamp[i].toString(16).padStart(2, "0");
+    }
+    return { millis: Number(millis), counter, nodeId };
+};
+export const orderBinaryTimestamp = orderUint8Array;

package/dist/src/Function.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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 {
+ *   switch (color) {
+ *     case "red":
+ *       console.log("Handling red");
+ *       break;
+ *     case "green":
+ *       console.log("Handling green");
+ *       break;
+ *     case "blue":
+ *       console.log("Handling blue");
+ *       break;
+ *     default:
+ *       exhaustiveCheck(color); // Ensures all cases are handled
+ *   }
+ * }
+ * ```
+ */
+export declare const exhaustiveCheck: (value: never) => never;
+export declare const identity: <A>(a: A) => A;
+/**
+ * A function that delays computation and returns a value of type T.
+ *
+ * Useful for:
+ *
+ * - Lazy evaluation
+ * - Returning constant values
+ * - Providing default or placeholder behaviors
+ *
+ * ### Example
+ *
+ * ```ts
+ * const getRandomNumber: LazyValue<number> = () => Math.random();
+ * const randomValue = getRandomNumber();
+ * ```
+ */
+export type LazyValue<T> = () => T;
+export declare const constVoid: LazyValue<void>;
+export declare const constUndefined: LazyValue<undefined>;
+export declare const constNull: LazyValue<null>;
+export declare const constTrue: LazyValue<true>;
+export declare const constFalse: LazyValue<false>;
+//# sourceMappingURL=Function.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Function.d.ts","sourceRoot":"","sources":["../../src/Function.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,KAAG,KAE9C,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,KAAG,CAAM,CAAC;AAE1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC;AAEnC,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAmB,CAAC;AAC1D,eAAO,MAAM,cAAc,EAAE,SAAS,CAAC,SAAS,CAAmB,CAAC;AACpE,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAc,CAAC;AACrD,eAAO,MAAM,SAAS,EAAE,SAAS,CAAC,IAAI,CAAc,CAAC;AACrD,eAAO,MAAM,UAAU,EAAE,SAAS,CAAC,KAAK,CAAe,CAAC"}

package/dist/src/Function.js

@@ -0,0 +1,38 @@
+/**
+ * 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 {
+ *   switch (color) {
+ *     case "red":
+ *       console.log("Handling red");
+ *       break;
+ *     case "green":
+ *       console.log("Handling green");
+ *       break;
+ *     case "blue":
+ *       console.log("Handling blue");
+ *       break;
+ *     default:
+ *       exhaustiveCheck(color); // Ensures all cases are handled
+ *   }
+ * }
+ * ```
+ */
+export const exhaustiveCheck = (value) => {
+    throw new Error(`exhaustiveCheck unhandled case: ${JSON.stringify(value)}`);
+};
+export const identity = (a) => a;
+export const constVoid = () => undefined;
+export const constUndefined = () => undefined;
+export const constNull = () => null;
+export const constTrue = () => true;
+export const constFalse = () => false;

package/dist/src/ManyToManyMap.d.ts

@@ -0,0 +1,26 @@
+/** Represents a many-to-many mapping between keys and values. */
+export interface ManyToManyMap<K, V> {
+    /** Adds a key-value association to the map. */
+    add: (key: K, value: V) => ManyToManyMap<K, V>;
+    /** Removes a specific key-value association. */
+    remove: (key: K, value: V) => boolean;
+    /** Gets all values associated with a key. */
+    getValues: (key: K) => Set<V> | undefined;
+    /** Gets all keys associated with a value. */
+    getKeys: (value: V) => Set<K> | undefined;
+    /** Checks if a specific key-value pair exists. */
+    hasPair: (key: K, value: V) => boolean;
+    /** Checks if a key exists in the map. */
+    hasKey(key: K): boolean;
+    /** Checks if a value exists in the map. */
+    hasValue: (value: V) => boolean;
+    /** Deletes all associations for a key. */
+    deleteKey: (key: K) => boolean;
+    /** Deletes all associations for a value. */
+    deleteValue: (value: V) => boolean;
+    /** Clears all associations in the map. */
+    clear(): void;
+}
+/** Creates a {@link ManyToManyMap}. */
+export declare const createManyToManyMap: <K, V>() => ManyToManyMap<K, V>;
+//# sourceMappingURL=ManyToManyMap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ManyToManyMap.d.ts","sourceRoot":"","sources":["../../src/ManyToManyMap.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,WAAW,aAAa,CAAC,CAAC,EAAE,CAAC;IACjC,+CAA+C;IAC/C,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAE/C,gDAAgD;IAChD,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEtC,6CAA6C;IAC7C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAE1C,6CAA6C;IAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAE1C,kDAAkD;IAClD,OAAO,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEvC,yCAAyC;IACzC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC;IAExB,2CAA2C;IAC3C,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEhC,0CAA0C;IAC1C,SAAS,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC;IAE/B,4CAA4C;IAC5C,WAAW,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAEnC,0CAA0C;IAC1C,KAAK,IAAI,IAAI,CAAC;CACf;AAED,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,GAAI,CAAC,EAAE,CAAC,OAAK,aAAa,CAAC,CAAC,EAAE,CAAC,CAyG9D,CAAC"}

package/dist/src/ManyToManyMap.js

@@ -0,0 +1,92 @@
+/** Creates a {@link ManyToManyMap}. */
+export const createManyToManyMap = () => {
+    const forwardMap = new Map();
+    const reverseMap = new Map();
+    const map = {
+        add(key, value) {
+            let values = forwardMap.get(key);
+            if (!values) {
+                values = new Set();
+                forwardMap.set(key, values);
+            }
+            values.add(value);
+            let keys = reverseMap.get(value);
+            if (!keys) {
+                keys = new Set();
+                reverseMap.set(value, keys);
+            }
+            keys.add(key);
+            return map;
+        },
+        remove(key, value) {
+            const values = forwardMap.get(key);
+            if (!values?.has(value))
+                return false;
+            values.delete(value);
+            if (values.size === 0) {
+                forwardMap.delete(key);
+            }
+            const keys = reverseMap.get(value);
+            if (keys?.size) {
+                keys.delete(key);
+                if (keys.size === 0) {
+                    reverseMap.delete(value);
+                }
+            }
+            return true;
+        },
+        getValues(key) {
+            return forwardMap.get(key);
+        },
+        getKeys(value) {
+            return reverseMap.get(value);
+        },
+        hasPair(key, value) {
+            const values = forwardMap.get(key);
+            return values?.has(value) ?? false;
+        },
+        hasKey(key) {
+            return forwardMap.has(key);
+        },
+        hasValue(value) {
+            return reverseMap.has(value);
+        },
+        deleteKey(key) {
+            const values = forwardMap.get(key);
+            if (!values)
+                return false;
+            for (const value of values) {
+                const keys = reverseMap.get(value);
+                if (keys) {
+                    keys.delete(key);
+                    if (keys.size === 0) {
+                        reverseMap.delete(value);
+                    }
+                }
+            }
+            forwardMap.delete(key);
+            return true;
+        },
+        deleteValue(value) {
+            const keys = reverseMap.get(value);
+            if (!keys)
+                return false;
+            for (const key of keys) {
+                const values = forwardMap.get(key);
+                if (values) {
+                    values.delete(value);
+                    if (values.size === 0) {
+                        forwardMap.delete(key);
+                    }
+                }
+            }
+            reverseMap.delete(value);
+            return true;
+        },
+        clear() {
+            forwardMap.clear();
+            reverseMap.clear();
+        },
+    };
+    return map;
+};

package/dist/src/NanoId.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Interface representing a NanoId library.
+ *
+ * It's useful for testing by allowing ID generation to be mocked, ensuring
+ * consistent results.
+ *
+ * @see https://github.com/ai/nanoid
+ *
+ * ### Example
+ *
+ * ```ts
+ * const foo = createFoo({
+ *   ...createNanoIdLib(),
+ *   ...createTime(),
+ * });
+ * ```
+ */
+export interface NanoIdLib {
+    readonly urlAlphabet: string;
+    readonly customAlphabet: (alphabet: string, defaultSize?: number) => (size?: number) => string;
+    readonly nanoid: (size?: number) => string;
+}
+export interface NanoIdLibDep {
+    readonly nanoIdLib: NanoIdLib;
+}
+export declare const createNanoIdLib: () => NanoIdLib;
+//# sourceMappingURL=NanoId.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NanoId.d.ts","sourceRoot":"","sources":["../../src/NanoId.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,QAAQ,CAAC,cAAc,EAAE,CACvB,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,KACjB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;IAE/B,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CAC5C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;CAC/B;AAED,eAAO,MAAM,eAAe,QAAO,SAIjC,CAAC"}

package/dist/src/NanoId.js

@@ -0,0 +1,6 @@
+import { customAlphabet, nanoid, urlAlphabet } from "nanoid";
+export const createNanoIdLib = () => ({
+    urlAlphabet,
+    customAlphabet,
+    nanoid,
+});