@evolu/common 8.14.0 → 8.15.0

package/dist/src/Crypto.d.ts

@@ -258,7 +258,8 @@ export declare const createPadmePadding: (length: NonNegativeInt) => Uint8Array;
 /**
  * Performs a timing-safe comparison of two Uint8Arrays. Returns true if they
  * are equal, false otherwise. Takes constant time regardless of where the
- * arrays differ.
+ * arrays differ. Arrays of different lengths are unequal, and the comparison
+ * does not hide their lengths.
  *
  * @group Comparison
  * @see https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b

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

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

package/dist/src/Redacted.d.ts

@@ -4,7 +4,6 @@
  * @module
  */
 import type { Brand } from "./Brand.ts";
-import type { Eq } from "./Eq.ts";
 /**
  * A wrapper type that prevents sensitive values from being accidentally exposed
  * through logging, serialization, or inspection.
@@ -15,13 +14,17 @@ import type { Eq } from "./Eq.ts";
  *
  * For type-level distinction between different secrets, use branded types.
  *
- * The actual value lives in a `WeakMap`, so it never appears as a property and
- * is automatically garbage collected when the wrapper is dropped. This is
- * better than a class with a private field because private fields are still
- * visible in devtools. Symbols can't be used because they don't support custom
- * `toString`.
+ * Redacted guards against accidental exposure, such as logs, error reports, and
+ * serialized payloads. It does not hide the value from a debugger: DevTools and
+ * heap snapshots can still reach it.
  *
- * Implements `Disposable` for automatic cleanup via the `using` syntax.
+ * A structured clone, such as a `postMessage` to a worker, does not copy the
+ * hidden value and arrives as an empty object. Reveal the value before posting
+ * it, and wrap it again on arrival if the receiver passes it to app code.
+ *
+ * Implements `Disposable`, so the `using` syntax detaches the value when the
+ * scope ends. Disposal does not overwrite the value or release other references
+ * to it.
  *
  * ### Example
  *
@@ -45,7 +48,6 @@ import type { Eq } from "./Eq.ts";
  * using redactedKey: RedactedApiKey = createRedacted(apiKey);
  * const fetchUser = (key: RedactedApiKey): ApiKey => revealRedacted(key);
  *
- * // oxlint-disable-next-line typescript/no-base-to-string -- Redacted intentionally implements a safe custom toString.
  * assertEqual(redactedKey.toString(), "<redacted>");
  * assertEqual(
  *   JSON.stringify({ apiKey: redactedKey }),
@@ -61,13 +63,18 @@ import type { Eq } from "./Eq.ts";
  *   using key = createRedacted(apiKey);
  *   return key;
  * })();
- * // Leaving the `using` scope removes the value from memory.
+ * // Leaving the `using` scope detaches the value, so revealing it throws.
  * assertErr(trySync(() => revealRedacted(disposedKey)));
  * ```
  */
 export interface Redacted<A> extends Brand<"Redacted">, Disposable {
-    /** The inner type. Useful for inference via `typeof redacted.Type`. */
+    /**
+     * The inner type. This is a type-only phantom property. Use it through
+     * `typeof redacted.Type`; it does not exist at runtime.
+     */
     readonly Type: A;
+    readonly toString: () => "<redacted>";
+    readonly toJSON: () => "<redacted>";
 }
 /** Creates a {@link Redacted} wrapper for a sensitive value. */
 export declare const createRedacted: <A>(value: A) => Redacted<A>;
@@ -77,37 +84,10 @@ export declare const createRedacted: <A>(value: A) => Redacted<A>;
  * This is a separate function rather than a method on {@link Redacted} to make
  * access visually explicit and easy to grep in code reviews. Accessing
  * sensitive values should feel intentional, not convenient.
+ *
+ * Throws when the wrapper was disposed or is a structured clone.
  */
 export declare const revealRedacted: <A>(redacted: Redacted<A>) => A;
 /** Checks if a value is a {@link Redacted} wrapper. */
 export declare const isRedacted: (value: unknown) => value is Redacted<unknown>;
-/**
- * Creates an {@link Eq} for {@link Redacted} values based on an equality function
- * for the underlying type.
- *
- * ### Example
- *
- * ```ts
- * import {
- *   assertFalse,
- *   assertTrue,
- *   createEqRedacted,
- *   createRedacted,
- *   eqString,
- *   type Brand,
- * } from "@evolu/common";
- *
- * type ApiKey = string & Brand<"ApiKey">;
- * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
- *
- * // Apply brands only after validation or at another trusted boundary.
- * using a = createRedacted("x" as ApiKey);
- * using b = createRedacted("x" as ApiKey);
- * using c = createRedacted("y" as ApiKey);
- *
- * assertTrue(eqRedactedApiKey(a, b));
- * assertFalse(eqRedactedApiKey(a, c));
- * ```
- */
-export declare const createEqRedacted: <A>(eq: Eq<A>) => Eq<Redacted<A>>;
 //# sourceMappingURL=Redacted.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../../src/Redacted.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,UAAU,CAAC,EAAE,UAAU;IAChE,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,CAAC,KAAG,QAAQ,CAAC,CAAC,CAItD,CAAC;AAaF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAG,CAGzD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAG7B,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,gBAAgB,GAC1B,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,KAAG,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAEY,CAAC"}
+{"version":3,"file":"Redacted.d.ts","sourceRoot":"","sources":["../../src/Redacted.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,UAAU,CAAC,EAAE,UAAU;IAChE;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,QAAQ,EAAE,MAAM,YAAY,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,YAAY,CAAC;CACrC;AAED,gEAAgE;AAChE,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,CAAC,KAAG,QAAQ,CAAC,CAAC,CAatD,CAAC;AAiBF;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,YAAY,QAAQ,CAAC,CAAC,CAAC,KAAG,CAGzD,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,UAAU,UAAW,OAAO,KAAG,KAAK,IAAI,QAAQ,CAAC,OAAO,CAG7B,CAAC"}

package/dist/src/Redacted.js

@@ -6,7 +6,16 @@
 import { assert } from "./Assert.js";
 /** Creates a {@link Redacted} wrapper for a sensitive value. */
 export const createRedacted = (value) => {
-    const redacted = Object.create(proto);
+    // Symbol.dispose is read here rather than in proto because installPolyfills
+    // runs after imported modules are evaluated. An arrow function also keeps a
+    // detached dispose method working.
+    const redacted = Object.create(proto, {
+        [Symbol.dispose]: {
+            value: () => {
+                registry.delete(redacted);
+            },
+        },
+    });
     registry.set(redacted, value);
     return redacted;
 };
@@ -14,11 +23,14 @@ const proto = {
     toString: () => redactedString,
     toJSON: () => redactedString,
     [Symbol.for("nodejs.util.inspect.custom")]: () => redactedString,
-    [Symbol.dispose]() {
-        registry.delete(this);
-    },
 };
 const redactedString = "<redacted>";
+// The value lives in a WeakMap, so it is never a property: previews,
+// enumeration, and serialization cannot show it, and it is garbage collected
+// with the wrapper. A private field would show when DevTools expands the
+// object. The wrapper is an object, not a symbol, because a symbol cannot
+// customize toString or toJSON. DevTools can still reach the registry through
+// the scopes of the wrapper's functions.
 const registry = new WeakMap();
 /**
  * Reveals the original value from a {@link Redacted} wrapper.
@@ -26,6 +38,8 @@ const registry = new WeakMap();
  * This is a separate function rather than a method on {@link Redacted} to make
  * access visually explicit and easy to grep in code reviews. Accessing
  * sensitive values should feel intentional, not convenient.
+ *
+ * Throws when the wrapper was disposed or is a structured clone.
  */
 export const revealRedacted = (redacted) => {
     assert(registry.has(redacted), "Redacted value was not in registry");
@@ -35,32 +49,3 @@ export const revealRedacted = (redacted) => {
 export const isRedacted = (value) => typeof value === "object" &&
     value !== null &&
     Object.getPrototypeOf(value) === proto;
-/**
- * Creates an {@link Eq} for {@link Redacted} values based on an equality function
- * for the underlying type.
- *
- * ### Example
- *
- * ```ts
- * import {
- *   assertFalse,
- *   assertTrue,
- *   createEqRedacted,
- *   createRedacted,
- *   eqString,
- *   type Brand,
- * } from "@evolu/common";
- *
- * type ApiKey = string & Brand<"ApiKey">;
- * const eqRedactedApiKey = createEqRedacted<ApiKey>(eqString);
- *
- * // Apply brands only after validation or at another trusted boundary.
- * using a = createRedacted("x" as ApiKey);
- * using b = createRedacted("x" as ApiKey);
- * using c = createRedacted("y" as ApiKey);
- *
- * assertTrue(eqRedactedApiKey(a, b));
- * assertFalse(eqRedactedApiKey(a, c));
- * ```
- */
-export const createEqRedacted = (eq) => (x, y) => eq(revealRedacted(x), revealRedacted(y));

package/dist/src/Type.d.ts

@@ -3585,6 +3585,61 @@ export interface NameError extends TypeError<"Name"> {
  */
 export declare const Name: BrandType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "UrlSafeString", RegexError<"UrlSafeString">>, "Name", NameError>;
 export type Name = typeof Name.Output;
+/**
+ * Error returned when a string is not a valid {@link Email}.
+ *
+ * @group String
+ */
+export interface EmailError extends TypeError<"Email"> {
+    readonly value: string;
+}
+/**
+ * Email address as defined by the WHATWG HTML Standard.
+ *
+ * Email accepts a [valid email
+ * address](https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address),
+ * the syntax browsers enforce for `<input type="email">`. The HTML Standard
+ * deliberately departs from RFC 5322: it rejects quoted local parts, comments,
+ * IP address literals, and whitespace, and it accepts only ASCII. Use the ASCII
+ * (`xn--`) form of internationalized domains.
+ *
+ * Email does not normalize. The local part is case-sensitive, so different
+ * Email strings can still reach the same mailbox, and only a delivered message
+ * proves that an address exists.
+ *
+ * The HTML Standard limits each domain label to 63 characters but sets no total
+ * length. SMTP limits an address to 254 characters; compose
+ * `maxLength(254)(Email)` when that limit matters.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertErr,
+ *   assertOk,
+ *   Email,
+ *   maxLength,
+ * } from "@evolu/common";
+ *
+ * assertOk(Email.fromUnknown("ada@example.com"), "ada@example.com");
+ * assertOk(Email.fromUnknown("Ada@Example.com"), "Ada@Example.com");
+ *
+ * const invalid = Email.fromUnknown("Ada <ada@example.com>");
+ * assertErr(invalid);
+ * assertEqual(invalid.error, {
+ *   type: "Email",
+ *   value: "Ada <ada@example.com>",
+ * });
+ *
+ * const SmtpEmail = maxLength(254)(Email);
+ * assertErr(SmtpEmail.fromUnknown(`${"a".repeat(251)}@b.c`));
+ * ```
+ *
+ * @group String
+ */
+export declare const Email: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Email", EmailError>;
+export type Email = typeof Email.Output;
 /**
  * Stable valid {@link Name} for tests and internal fixtures.
  *
@@ -3829,6 +3884,112 @@ export declare const idToIdBytes: (value: Id) => IdBytes;
  * @group String
  */
 export declare const idBytesToId: (value: IdBytes) => Id;
+/**
+ * Error returned when a string is not a canonical {@link Uuid}.
+ *
+ * @group String
+ */
+export interface UuidError extends TypeError<"Uuid"> {
+    readonly value: string;
+}
+/**
+ * UUID in its canonical lowercase text form, as defined by [RFC
+ * 9562](https://www.rfc-editor.org/rfc/rfc9562).
+ *
+ * Uuid accepts 32 lowercase hexadecimal digits in the 8-4-4-4-12 layout, as
+ * produced by `crypto.randomUUID()`. It accepts every version and variant,
+ * including the Nil and Max UUIDs, so every 128-bit value has exactly one
+ * Uuid.
+ *
+ * RFC 9562 reads UUIDs in any case. Uuid requires lowercase so that equal UUIDs
+ * are equal strings; lowercase text from other sources before validating it.
+ *
+ * Convert a Uuid to an {@link Id} with {@link uuidToId} and back with
+ * {@link idToUuid}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, assertErr, assertOk, Uuid } from "@evolu/common";
+ *
+ * const value = "0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d";
+ * assertOk(Uuid.fromUnknown(value), value);
+ *
+ * const uppercase = value.toUpperCase();
+ * const invalid = Uuid.fromUnknown(uppercase);
+ * assertErr(invalid);
+ * assertEqual(invalid.error, { type: "Uuid", value: uppercase });
+ * assertOk(Uuid.fromUnknown(uppercase.toLowerCase()), value);
+ * ```
+ *
+ * @group String
+ */
+export declare const Uuid: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Uuid", UuidError>;
+export type Uuid = typeof Uuid.Output;
+/**
+ * Converts a {@link Uuid} to the {@link Id} with the same 16 bytes.
+ *
+ * Use this to store records whose external keys are UUIDs. Unlike
+ * {@link createIdFromString}, the mapping is reversible with {@link idToUuid}, so
+ * the original UUID does not need its own column. A time-based UUID, such as
+ * version 1, 6, or 7, keeps its creation time in the Id.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertType,
+ *   idToUuid,
+ *   Uuid,
+ *   uuidToId,
+ *   type Brand,
+ *   type Id,
+ * } from "@evolu/common";
+ *
+ * const uuid = Uuid.orThrow("0190a6f4-8c3e-7b2a-9d41-5e6f7a8b9c0d");
+ * const todoId = uuidToId<"Todo">(uuid);
+ *
+ * assertEqual(todoId, "AZCm9Iw-eyqdQV5veoucDQ");
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
+ * assertEqual(idToUuid(todoId), uuid);
+ * ```
+ *
+ * @group String
+ */
+export declare const uuidToId: <B extends string = never>(value: Uuid, ..._validation: IdBrandValidation<B>) => CreatedId<B>;
+/**
+ * Converts an {@link Id} to the {@link Uuid} with the same 16 bytes.
+ *
+ * The result is a Uuid of any version or variant, because Ids created by
+ * {@link createId} are random 128-bit values. Ids created by
+ * {@link createIdAsUuidv7} convert to version 7 UUIDs.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   createIdAsUuidv7,
+ *   createRandomBytes,
+ *   createTime,
+ *   idToUuid,
+ *   uuidToId,
+ * } from "@evolu/common";
+ *
+ * const id = createIdAsUuidv7({
+ *   randomBytes: createRandomBytes(),
+ *   time: createTime(),
+ * });
+ * const uuid = idToUuid(id);
+ *
+ * assertEqual(uuid[14], "7");
+ * assertEqual(uuidToId(uuid), id);
+ * ```
+ *
+ * @group String
+ */
+export declare const idToUuid: (value: Id) => Uuid;
 /**
  * Error returned when a string is not a canonical {@link Int64String}.
  *