@evolu/common 5.4.7 → 6.0.0-preview.0

package/dist/src/Console.js

@@ -0,0 +1,103 @@
+/**
+ * 📝 Cross-platform console
+ *
+ * Console abstraction for Chrome 123+, Firefox 125+, Safari 18.1+, Node.js
+ * 22.x+, and React Native 0.75+. Includes methods guaranteed to be available in
+ * these environments and expected to remain compatible in future versions.
+ * Output formatting may vary (e.g., interactive UI in browsers vs. text in
+ * Node.js/React Native), but functionality is consistent across platforms.
+ *
+ * **Convention**: Use a tag (e.g., `[db]`) as the first argument for log
+ * filtering.
+ *
+ * ### Example
+ *
+ * ```ts
+ * deps.console.log("[db]", "send data message", protocolMessage);
+ * ```
+ *
+ * **Tip**: In browser dev tools, you can filter logs by tag (e.g., `[db]`) to
+ * quickly find relevant messages.
+ *
+ * **Warning**: If you encounter platform-specific issues or missing methods,
+ * please contribute a PR with details about the environment and behavior.
+ *
+ * @module
+ */
+/** Creates a console instance using the global console. */
+export const createConsole = (config = {}) => {
+    const instance = {
+        enabled: config.enableLogging ?? false,
+        log: (...args) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.log(...args);
+        },
+        info: (...args) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.info(...args);
+        },
+        warn: (...args) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.warn(...args);
+        },
+        error: (...args) => {
+            // Always log errors, even if disabled
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            console.error(...args);
+        },
+        debug: (...args) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.debug(...args);
+        },
+        time: (label) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.time(label);
+        },
+        timeEnd: (label) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.timeEnd(label);
+        },
+        dir: (object, options) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.dir(object, options);
+        },
+        table: (tabularData, properties) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.table(tabularData, properties);
+        },
+        count: (label) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.count(label);
+        },
+        countReset: (label) => {
+            // eslint-disable-next-line no-console
+            if (instance.enabled)
+                console.countReset(label);
+        },
+        assert: (value, message, ...optionalParams) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.assert(value, message, ...optionalParams);
+        },
+        timeLog: (label, ...data) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.timeLog(label, ...data);
+        },
+        trace: (message, ...optionalParams) => {
+            // eslint-disable-next-line no-console, @typescript-eslint/no-unsafe-argument
+            if (instance.enabled)
+                console.trace(message, ...optionalParams);
+        },
+    };
+    return instance;
+};

package/dist/src/Crypto.d.ts

@@ -1,49 +1,82 @@
-import * as S from "@effect/schema/Schema";
-import * as Brand from "effect/Brand";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
-import { Id } from "./Model.js";
 /**
- * Mnemonic is a password generated by Evolu in BIP39 format.
+ * 🔒
  *
- * A mnemonic, also known as a "seed phrase," is a set of 12 words in a specific
- * order chosen from a predefined list. The purpose of the BIP39 mnemonic is to
- * provide a human-readable way of storing a private key.
+ * @module
  */
-export type Mnemonic = string & Brand.Brand<"Mnemonic">;
+import { Result } from "./Result.js";
+import { Id, Mnemonic, NonNegativeInt } from "./Type.js";
+import { Brand } from "./Types.js";
+/** `Uint8Array` created by {@link createRandomBytes}. */
+export type RandomBytes = Uint8Array & Brand<"RandomBytes">;
+export type CreateRandomBytes = (bytesLength?: number) => RandomBytes;
+export interface CreateRandomBytesDep {
+    readonly createRandomBytes: CreateRandomBytes;
+}
+/** Cryptographically secure PRNG. Uses internal OS-level crypto.getRandomValues. */
+export declare const createRandomBytes: CreateRandomBytes;
+export type CreateMnemonic = () => Mnemonic;
+export interface CreateMnemonicDep {
+    readonly createMnemonic: CreateMnemonic;
+}
+export declare const createEnglishMnemonic: CreateMnemonic;
+export type MnemonicSeed = Uint8Array & Brand<"MnemonicSeed">;
+export declare const mnemonicToMnemonicSeed: (mnemonic: Mnemonic) => MnemonicSeed;
 /**
- * Mnemonic is a password generated by Evolu in BIP39 format.
+ * SLIP21.
  *
- * A mnemonic, also known as a "seed phrase," is a set of 12 words in a specific
- * order chosen from a predefined list. The purpose of the BIP39 mnemonic is to
- * provide a human-readable way of storing a private key.
+ * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
-export declare const createMnemonic: () => Mnemonic;
-/** Parse a string to {@link Mnemonic}. */
-export declare const parseMnemonic: (mnemonic: string) => Effect.Effect<Mnemonic, InvalidMnemonicError>;
-export interface InvalidMnemonicError {
-    readonly _tag: "InvalidMnemonicError";
+export declare const createSlip21: (seed: MnemonicSeed, path: ReadonlyArray<string>) => Uint8Array;
+/**
+ * Creates a 21-character Base64URL ID (also known as nanoid) from a SLIP-21
+ * derived key.
+ *
+ * Reduces the 256-bit SLIP-21 output to 126 bits (21 chars × 6 bits) for a
+ * compact, human-readable, and shareable identifier suitable for UI display or
+ * URL use. While this lowers entropy, 126 bits remains cryptographically secure
+ * for uniqueness and unpredictability in most applications (comparable to
+ * UUIDv4's 122 bits).
+ *
+ * See https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ */
+export declare const createSlip21Id: (seed: MnemonicSeed, path: ReadonlyArray<string>) => Id;
+/** The encryption key for {@link SymmetricCrypto}. */
+export declare const EncryptionKey: import("./Type.js").BrandType<import("./Type.js").BrandType<import("./Type.js").Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, import("./Type.js").Uint8ArrayError, Uint8Array<ArrayBufferLike>, import("./Type.js").Uint8ArrayError>, "Length32", import("./Type.js").LengthError<32>, import("./Type.js").Uint8ArrayError>, "EncryptionKey", import("./Type.js").BrandWithoutRefineError<"EncryptionKey", import("./Type.js").Uint8ArrayError | import("./Type.js").LengthError<32>>, never>;
+export type EncryptionKey = typeof EncryptionKey.Type;
+export declare const createEncryptionKey: (seed: MnemonicSeed) => EncryptionKey;
+/** Symmetric cryptography. */
+export interface SymmetricCrypto {
+    readonly nonceLength: NonNegativeInt;
+    readonly encrypt: (plaintext: Uint8Array, encryptionKey: EncryptionKey) => {
+        readonly nonce: Uint8Array;
+        readonly ciphertext: Uint8Array;
+    };
+    readonly decrypt: (ciphertext: Uint8Array, encryptionKey: EncryptionKey, nonce: Uint8Array) => Result<Uint8Array, SymmetricCryptoDecryptError>;
 }
-export declare const mnemonicToSeed: (mnemonic: Mnemonic) => Uint8Array;
-declare const NanoIdGenerator_base: Context.TagClass<NanoIdGenerator, "NanoIdGenerator", {
-    readonly nanoid: Effect.Effect<NanoId>;
-    readonly nodeId: Effect.Effect<NodeId>;
-    readonly rowId: Effect.Effect<Id>;
-}>;
-export declare class NanoIdGenerator extends NanoIdGenerator_base {
+export interface SymmetricCryptoDep {
+    readonly symmetricCrypto: SymmetricCrypto;
 }
-export declare const createNanoIdGeneratorLive: (customAlphabet: (alphabet: string, defaultSize?: number) => (size?: number) => string, nanoid: (size?: number) => string) => Layer.Layer<NanoIdGenerator, never, never>;
-export type NanoId = string & Brand.Brand<"NanoId">;
-export declare const NodeId: S.brand<S.filter<S.Schema<string, string, never>>, "NodeId">;
-export type NodeId = typeof NodeId.Type;
-export declare const slip21Derive: (seed: Uint8Array, path: ReadonlyArray<string>) => Effect.Effect<Uint8Array>;
-declare const SecretBox_base: Context.TagClass<SecretBox, "SecretBox", {
-    readonly seal: (key: Uint8Array, plaintext: Uint8Array) => Effect.Effect<Uint8Array>;
-    readonly open: (key: Uint8Array, ciphertext: Uint8Array) => Effect.Effect<Uint8Array>;
-}>;
-export declare class SecretBox extends SecretBox_base {
-    static Live: Layer.Layer<SecretBox, never, never>;
+export interface SymmetricCryptoDecryptError {
+    readonly type: "SymmetricCryptoDecryptError";
+    readonly error: unknown;
 }
-export {};
+/**
+ * XChaCha20-Poly1305 encryption
+ *
+ * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
+ */
+export declare const createSymmetricCrypto: (deps: CreateRandomBytesDep) => SymmetricCrypto;
+/**
+ * Returns the PADMÉ padded length for a given input length.
+ *
+ * PADMÉ limits information leakage about the length of the plain-text for a
+ * wide range of encrypted data sizes. See the PURBs paper for details:
+ * https://bford.info/pub/sec/purb.pdf
+ */
+export declare const padmePaddedLength: (length: NonNegativeInt) => NonNegativeInt;
+/**
+ * Returns the PADMÉ padding length for a given input length. Uses
+ * {@link padmePaddedLength}.
+ */
+export declare const padmePaddingLength: (length: NonNegativeInt) => NonNegativeInt;
 //# sourceMappingURL=Crypto.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,uBAAuB,CAAC;AAQ3C,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,KAAK,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,EAAE,EAAE,MAAM,YAAY,CAAC;AAEhC;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAO,QACiB,CAAC;AAEpD,0CAA0C;AAC1C,eAAO,MAAM,aAAa,aACd,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,oBAAoB,CAO9C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;CACvC;AAED,eAAO,MAAM,cAAc,aAAc,QAAQ,KAAG,UAChB,CAAC;;qBAKhB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;qBACrB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;oBACtB,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;;AALrC,qBAAa,eAAgB,SAAQ,oBAOlC;CAAG;AAEN,eAAO,MAAM,yBAAyB,mBACpB,CACd,QAAQ,EAAE,MAAM,EAChB,WAAW,CAAC,EAAE,MAAM,KACjB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,UACtB,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,MAAM,KAChC,KAAK,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,EAAE,KAAK,CAU3C,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;AAEpD,eAAO,MAAM,MAAM,8DAGlB,CAAC;AACF,MAAM,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,IAAI,CAAC;AAIxC,eAAO,MAAM,YAAY,SACjB,UAAU,QACV,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,UAAU,CAWvB,CAAC;;mBAKc,CACb,GAAG,EAAE,UAAU,EACf,SAAS,EAAE,UAAU,KAClB,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;mBAEf,CACb,GAAG,EAAE,UAAU,EACf,UAAU,EAAE,UAAU,KACnB,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC;;AAXlC,qBAAa,SAAU,SAAQ,cAa5B;IACD,MAAM,CAAC,IAAI,uCAgBT;CACH"}
+{"version":3,"file":"Crypto.d.ts","sourceRoot":"","sources":["../../src/Crypto.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,EAAc,MAAM,EAAW,MAAM,aAAa,CAAC;AAC1D,OAAO,EAEL,EAAE,EAEF,QAAQ,EACR,cAAc,EAEf,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,yDAAyD;AACzD,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;AAE5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,WAAW,CAAC,EAAE,MAAM,KAAK,WAAW,CAAC;AAEtE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;CAC/C;AAED,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,EAAE,iBACS,CAAC;AAE1C,MAAM,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;CACzC;AAED,eAAO,MAAM,qBAAqB,EAAE,cACe,CAAC;AAEpD,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,KAAK,CAAC,cAAc,CAAC,CAAC;AAE9D,eAAO,MAAM,sBAAsB,GAAI,UAAU,QAAQ,KAAG,YACR,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,YAAY,EAClB,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,UAUF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACzB,MAAM,YAAY,EAClB,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,EAUF,CAAC;AAEF,sDAAsD;AACtD,eAAO,MAAM,aAAa,8fAAiD,CAAC;AAC5E,MAAM,MAAM,aAAa,GAAG,OAAO,aAAa,CAAC,IAAI,CAAC;AAEtD,eAAO,MAAM,mBAAmB,GAAI,MAAM,YAAY,KAAG,aACS,CAAC;AAEnE,8BAA8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC;IAErC,QAAQ,CAAC,OAAO,EAAE,CAChB,SAAS,EAAE,UAAU,EACrB,aAAa,EAAE,aAAa,KACzB;QACH,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;KACjC,CAAC;IAEF,QAAQ,CAAC,OAAO,EAAE,CAChB,UAAU,EAAE,UAAU,EACtB,aAAa,EAAE,aAAa,EAC5B,KAAK,EAAE,UAAU,KACd,MAAM,CAAC,UAAU,EAAE,2BAA2B,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,MAAM,oBAAoB,KACzB,eAyBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,QAAQ,cAAc,KAAG,cAO1D,CAAC;AAEF;;;GAGG;AAEH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,cAAc,KAAG,cAE3D,CAAC"}

package/dist/src/Crypto.js

@@ -1,67 +1,102 @@
-import * as S from "@effect/schema/Schema";
-import { secretbox } from "@noble/ciphers/salsa";
-import { concatBytes } from "@noble/ciphers/utils";
+/**
+ * 🔒
+ *
+ * @module
+ */
+import { xchacha20poly1305 } from "@noble/ciphers/chacha";
 import { hmac } from "@noble/hashes/hmac";
-import { sha512 } from "@noble/hashes/sha512";
+import { sha512 } from "@noble/hashes/sha2";
 import { randomBytes } from "@noble/hashes/utils";
 import * as bip39 from "@scure/bip39";
 import { wordlist } from "@scure/bip39/wordlists/english";
-import * as Context from "effect/Context";
-import * as Effect from "effect/Effect";
-import * as Layer from "effect/Layer";
+import { urlAlphabet } from "nanoid";
+import { getOrThrow, trySync } from "./Result.js";
+import { brand, length, NonNegativeInt, Uint8Array, } from "./Type.js";
+/** Cryptographically secure PRNG. Uses internal OS-level crypto.getRandomValues. */
+export const createRandomBytes = (bytesLength = 32) => randomBytes(bytesLength);
+export const createEnglishMnemonic = () => bip39.generateMnemonic(wordlist, 128);
+export const mnemonicToMnemonicSeed = (mnemonic) => bip39.mnemonicToSeedSync(mnemonic);
 /**
- * Mnemonic is a password generated by Evolu in BIP39 format.
+ * SLIP21.
  *
- * A mnemonic, also known as a "seed phrase," is a set of 12 words in a specific
- * order chosen from a predefined list. The purpose of the BIP39 mnemonic is to
- * provide a human-readable way of storing a private key.
+ * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
  */
-export const createMnemonic = () => bip39.generateMnemonic(wordlist, 128);
-/** Parse a string to {@link Mnemonic}. */
-export const parseMnemonic = (mnemonic) => {
-    const mnemonicTrimmed = mnemonic.trim();
-    return bip39.validateMnemonic(mnemonicTrimmed, wordlist)
-        ? Effect.succeed(mnemonicTrimmed)
-        : Effect.fail({
-            _tag: "InvalidMnemonicError",
-        });
-};
-export const mnemonicToSeed = (mnemonic) => bip39.mnemonicToSeedSync(mnemonic);
-export class NanoIdGenerator extends Context.Tag("NanoIdGenerator")() {
-}
-export const createNanoIdGeneratorLive = (customAlphabet, nanoid) => {
-    const nanoidForNodeId = customAlphabet("0123456789abcdef", 16);
-    return Layer.succeed(NanoIdGenerator, NanoIdGenerator.of({
-        nanoid: Effect.sync(() => nanoid()),
-        nodeId: Effect.sync(() => nanoidForNodeId()),
-        rowId: Effect.sync(() => nanoid()),
-    }));
-};
-export const NodeId = S.String.pipe(S.pattern(/^[\w-]{16}$/), S.brand("NodeId"));
-// SLIP-21 implementation
-// https://github.com/satoshilabs/slips/blob/master/slip-0021.md
-export const slip21Derive = (seed, path) => Effect.sync(() => {
+export const createSlip21 = (seed, path) => {
     let m = hmac(sha512, "Symmetric key seed", seed);
-    for (let i = 0; i < path.length; i++) {
-        const p = new TextEncoder().encode(path[i]);
-        const e = new Uint8Array(p.byteLength + 1);
+    for (const component of path) {
+        const p = new TextEncoder().encode(component);
+        const e = new globalThis.Uint8Array(p.byteLength + 1);
         e[0] = 0;
         e.set(p, 1);
         m = hmac(sha512, m.slice(0, 32), e);
     }
     return m.slice(32, 64);
-});
-export class SecretBox extends Context.Tag("SecretBox")() {
-}
-SecretBox.Live = Layer.succeed(SecretBox, SecretBox.of({
-    seal: (key, plaintext) => Effect.sync(() => {
-        const nonce = randomBytes(24);
-        const ciphertext = secretbox(key, nonce).seal(plaintext);
-        return concatBytes(nonce, ciphertext);
-    }),
-    open: (key, ciphertext) => Effect.sync(() => {
-        const nonce = ciphertext.subarray(0, 24);
-        const ciphertextWithoutNonce = ciphertext.subarray(24);
-        return secretbox(key, nonce).open(ciphertextWithoutNonce);
-    }),
-}));
+};
+/**
+ * Creates a 21-character Base64URL ID (also known as nanoid) from a SLIP-21
+ * derived key.
+ *
+ * Reduces the 256-bit SLIP-21 output to 126 bits (21 chars × 6 bits) for a
+ * compact, human-readable, and shareable identifier suitable for UI display or
+ * URL use. While this lowers entropy, 126 bits remains cryptographically secure
+ * for uniqueness and unpredictability in most applications (comparable to
+ * UUIDv4's 122 bits).
+ *
+ * See https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ */
+export const createSlip21Id = (seed, path) => {
+    const slip21 = createSlip21(seed, path);
+    let id = "";
+    // Convert the key to the Id/NanoId/Base64Url format.
+    for (let i = 0; i < 21; i++) {
+        id = (id + urlAlphabet[slip21[i] & 63]);
+    }
+    return id;
+};
+/** The encryption key for {@link SymmetricCrypto}. */
+export const EncryptionKey = brand("EncryptionKey", length(32)(Uint8Array));
+export const createEncryptionKey = (seed) => createSlip21(seed, ["Evolu", "Encryption Key"]);
+/**
+ * XChaCha20-Poly1305 encryption
+ *
+ * https://github.com/paulmillr/noble-ciphers?tab=readme-ov-file#which-cipher-should-i-pick
+ */
+export const createSymmetricCrypto = (deps) => {
+    const nonceLength = getOrThrow(NonNegativeInt.from(24));
+    const symmetricCrypto = {
+        nonceLength,
+        encrypt: (plaintext, encryptionKey) => {
+            const nonce = deps.createRandomBytes(nonceLength);
+            const ciphertext = xchacha20poly1305(encryptionKey, nonce).encrypt(plaintext);
+            return { nonce, ciphertext };
+        },
+        decrypt: (ciphertext, encryptionKey, nonce) => trySync(() => xchacha20poly1305(encryptionKey, nonce).decrypt(ciphertext), (error) => ({
+            type: "SymmetricCryptoDecryptError",
+            error,
+        })),
+    };
+    return symmetricCrypto;
+};
+/**
+ * Returns the PADMÉ padded length for a given input length.
+ *
+ * PADMÉ limits information leakage about the length of the plain-text for a
+ * wide range of encrypted data sizes. See the PURBs paper for details:
+ * https://bford.info/pub/sec/purb.pdf
+ */
+export const padmePaddedLength = (length) => {
+    if (length <= 0)
+        return 0;
+    const e = 31 - Math.clz32(length >>> 0);
+    const s = 32 - Math.clz32(e >>> 0);
+    const z = Math.max(0, e - s);
+    const mask = (1 << z) - 1;
+    return ((length + mask) & ~mask);
+};
+/**
+ * Returns the PADMÉ padding length for a given input length. Uses
+ * {@link padmePaddedLength}.
+ */
+export const padmePaddingLength = (length) => {
+    return (padmePaddedLength(length) - length);
+};

package/dist/src/Eq.d.ts

@@ -0,0 +1,97 @@
+import { JsonValue, JsonValueInput } from "./Type.js";
+import { Order } from "./Order.js";
+/**
+ * Compares two values of the same type `A` for equality.
+ *
+ * Equality functions start with an 'eq' prefix, e.g., `eqString`.
+ *
+ * TODO: Explain, examples (composition etc.)
+ */
+export type Eq<in A> = (x: A, y: A) => boolean;
+export declare const eqStrict: <A>(x: A, y: A) => boolean;
+export declare const eqString: Eq<string>;
+export declare const eqNumber: Eq<number>;
+export declare const eqBigInt: Eq<bigint>;
+export declare const eqBoolean: Eq<boolean>;
+export declare const eqUndefined: Eq<undefined>;
+export declare const eqNull: Eq<null>;
+/** Derives an {@link Eq} from an {@link Order}. */
+export declare const eqFromOrder: <A>(order: Order<A>) => Eq<A>;
+/**
+ * Creates an equivalence function for array-like structures based on an
+ * equivalence for their elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqArrayNumber = createEqArrayLike(eqNumber);
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export declare const createEqArrayLike: <A>(item: Eq<A>) => Eq<ArrayLike<A>>;
+/**
+ * Compares two array-like structures of numbers for equality.
+ *
+ * ### Example
+ *
+ * ```ts
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export declare const eqArrayNumber: Eq<ArrayLike<number>>;
+/**
+ * Creates an equivalence function for objects based on an equivalence for their
+ * fields.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqObjectNumber = createEqObject({ a: eqNumber });
+ * eqObjectNumber({ a: 1 }, { a: 1 }); // true
+ * eqObjectNumber({ a: 1 }, { a: 2 }); // false
+ * ```
+ */
+export declare const createEqObject: <A>(eqs: { [K in keyof A]: Eq<A[K]>; }) => Eq<{ readonly [K in keyof A]: A[K]; }>;
+/**
+ * Deeply compares two {@link JsonValue} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export declare const eqJsonValue: (a: JsonValue, b: JsonValue) => boolean;
+/**
+ * Deeply compares two {@link JsonValueInput} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export declare const eqJsonValueInput: (a: JsonValueInput, b: JsonValueInput) => boolean;
+//# sourceMappingURL=Eq.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Eq.d.ts","sourceRoot":"","sources":["../../src/Eq.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,SAAS,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC7E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAE/C,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,CAAC,KAAG,OAAkB,CAAC;AAE5D,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAY,CAAC;AAC7C,eAAO,MAAM,SAAS,EAAE,EAAE,CAAC,OAAO,CAAY,CAAC;AAC/C,eAAO,MAAM,WAAW,EAAE,EAAE,CAAC,SAAS,CAAY,CAAC;AACnD,eAAO,MAAM,MAAM,EAAE,EAAE,CAAC,IAAI,CAAY,CAAC;AAEzC,mDAAmD;AACnD,eAAO,MAAM,WAAW,GACrB,CAAC,EAAE,OAAO,KAAK,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,CAAC,CAEP,CAAC;AAEtB;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAC3B,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAUhC,CAAC;AAEJ;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,uBAA8B,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,GACxB,CAAC,EAAE,KAAK,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAE,KAAG,EAAE,CAAC,EACzC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAC9B,CASA,CAAC;AAEJ;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,WAAW,GAAI,GAAG,SAAS,EAAE,GAAG,SAAS,KAAG,OAsExD,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,GAAG,cAAc,EACjB,GAAG,cAAc,KAChB,OAAsD,CAAC"}

package/dist/src/Eq.js

@@ -0,0 +1,167 @@
+export const eqStrict = (x, y) => x === y;
+export const eqString = eqStrict;
+export const eqNumber = eqStrict;
+export const eqBigInt = eqStrict;
+export const eqBoolean = eqStrict;
+export const eqUndefined = eqStrict;
+export const eqNull = eqStrict;
+/** Derives an {@link Eq} from an {@link Order}. */
+export const eqFromOrder = (order) => (x, y) => order(x, y) === 0;
+/**
+ * Creates an equivalence function for array-like structures based on an
+ * equivalence for their elements.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqArrayNumber = createEqArrayLike(eqNumber);
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export const createEqArrayLike = (item) => (x, y) => {
+    if (x === y)
+        return true;
+    if (x.length !== y.length)
+        return false;
+    for (let i = 0; i < x.length; i++) {
+        if (!item(x[i], y[i]))
+            return false;
+    }
+    return true;
+};
+/**
+ * Compares two array-like structures of numbers for equality.
+ *
+ * ### Example
+ *
+ * ```ts
+ * eqArrayNumber([1, 2, 3], [1, 2, 3]); // true (works with regular arrays)
+ * eqArrayNumber(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3])); // true (works with Uint8Array)
+ * eqArrayNumber([1, 2, 3], [1, 2, 4]); // false
+ * ```
+ */
+export const eqArrayNumber = createEqArrayLike(eqNumber);
+/**
+ * Creates an equivalence function for objects based on an equivalence for their
+ * fields.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const eqObjectNumber = createEqObject({ a: eqNumber });
+ * eqObjectNumber({ a: 1 }, { a: 1 }); // true
+ * eqObjectNumber({ a: 1 }, { a: 2 }); // false
+ * ```
+ */
+export const createEqObject = (eqs) => (x, y) => {
+    if (x === y)
+        return true;
+    for (const key in eqs) {
+        if (!eqs[key](x[key], y[key])) {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Deeply compares two {@link JsonValue} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export const eqJsonValue = (a, b) => {
+    const stack = [[a, b]];
+    const seen = new WeakMap();
+    while (stack.length > 0) {
+        const [x, y] = stack.pop();
+        if (x === y)
+            continue;
+        const typeX = typeof x;
+        const typeY = typeof y;
+        if (typeX !== typeY || x === null || y === null)
+            return false;
+        if (typeX === "number" && isNaN(x) && isNaN(y)) {
+            continue;
+        }
+        if (typeX === "object") {
+            const isArrayX = Array.isArray(x);
+            const isArrayY = Array.isArray(y);
+            if (isArrayX !== isArrayY)
+                return false;
+            const xObj = x;
+            const yObj = y;
+            if (seen.has(xObj)) {
+                const ySet = seen.get(xObj);
+                if (ySet.has(yObj)) {
+                    continue;
+                }
+                ySet.add(yObj);
+            }
+            else {
+                const ySet = new WeakSet();
+                ySet.add(yObj);
+                seen.set(xObj, ySet);
+            }
+            if (isArrayX && isArrayY) {
+                const xArr = x;
+                const yArr = y;
+                if (xArr.length !== yArr.length)
+                    return false;
+                for (let i = 0; i < xArr.length; i++) {
+                    stack.push([xArr[i], yArr[i]]);
+                }
+            }
+            else {
+                const xObjTyped = x;
+                const yObjTyped = y;
+                const xKeys = Object.keys(xObjTyped);
+                const yKeys = Object.keys(yObjTyped);
+                if (xKeys.length !== yKeys.length)
+                    return false;
+                const yKeySet = new Set(yKeys);
+                for (const key of xKeys) {
+                    if (!yKeySet.has(key))
+                        return false;
+                    stack.push([xObjTyped[key], yObjTyped[key]]);
+                }
+            }
+        }
+        else {
+            return false;
+        }
+    }
+    return true;
+};
+/**
+ * Deeply compares two {@link JsonValueInput} values for equality.
+ *
+ * - Uses an iterative approach with a stack to handle large or deeply nested
+ *   objects without risking stack overflow.
+ * - Handles circular references with a WeakMap to prevent infinite loops.
+ * - Unlike JSON.stringify, this function directly compares values, avoiding
+ *   serialization overhead and leveraging short-circuit evaluation for faster
+ *   failure on mismatched structures.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const obj1: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * const obj2: Json = { name: "Alice", hobbies: ["reading", "hiking"] };
+ * console.log(eqJson(obj1, obj2)); // true
+ * ```
+ */
+export const eqJsonValueInput = (a, b) => eqJsonValue(a, b);