@evolu/common 8.10.0 → 8.11.0

package/src/Config.ts

@@ -76,139 +76,6 @@ import type {
 export const EnvName = /*#__PURE__*/ maxLength(255)(ConstantCaseIdentifier);
 export type EnvName = typeof EnvName.Output;
 
-/** Fields and one-level namespace groups used to construct an {@link env} Type. */
-export type EnvProps = Readonly<
-  Record<string, ObjectProps[string] | ObjectProps>
->;
-
-// Classify declarations by casing; identifier Types validate the full grammar
-// and name lengths during construction.
-type EnvDeclarationKind<Key> = Key extends string
-  ? Key extends Uppercase<Key>
-    ? "group"
-    : Key extends Uncapitalize<Key>
-      ? "field"
-      : "invalid"
-  : "invalid";
-
-type EnvFlatProps<Props extends EnvProps> =
-  UnionToIntersection<
-    {
-      [Key in keyof Props]: EnvDeclarationKind<Key> extends "group"
-        ? Props[Key]
-        : EnvDeclarationKind<Key> extends "field"
-          ? { readonly [Field in Key]: Props[Key] }
-          : never;
-    }[keyof Props]
-  > extends infer Flat extends ObjectProps
-    ? Flat
-    : {};
-
-type EnvFieldType<Field> = Field extends TypeNode
-  ? Field
-  : Field extends { readonly type: infer T extends TypeNode }
-    ? T
-    : never;
-
-type EnvKeysValidation<Props> =
-  | (string extends keyof Props
-      ? CompileTimeError<
-          "Env",
-          "Environment properties must use fixed string keys."
-        >
-      : never)
-  | (IsUnion<Props> extends true
-      ? CompileTimeError<
-          "Env",
-          "Environment properties must use one concrete schema."
-        >
-      : never)
-  | {
-      [Key in keyof Props]: Key extends string
-        ? ValidateLiteral<Key> extends Key
-          ? never
-          : CompileTimeError<
-              "Env",
-              "Environment properties must use fixed string keys."
-            >
-        : CompileTimeError<
-            "Env",
-            "Environment properties must use fixed string keys."
-          >;
-    }[keyof Props];
-
-type EnvFieldValidation<Field> =
-  IsUnion<Field> extends true
-    ? CompileTimeError<"Env", "Environment fields must use one concrete Type.">
-    : EnvFieldType<Field> extends infer T extends AnyType
-      ? IsUnion<T> extends true
-        ? CompileTimeError<
-            "Env",
-            "Environment fields must use one concrete Type."
-          >
-        : [T["CanonicalInput"]] extends [string]
-          ? Extract<
-              | "ObjectMissingProperty"
-              | "ObjectPropertyAccess"
-              | "ObjectExcessProperty",
-              InferErrors<T>["type"]
-            > extends never
-            ? never
-            : CompileTimeError<
-                "Env",
-                "Environment fields must not use error tags reserved for Object structure."
-              >
-          : CompileTimeError<
-              "Env",
-              "Environment fields must encode to strings."
-            >
-      : CompileTimeError<
-          "Env",
-          "Environment fields must use one concrete Type."
-        >;
-
-type EnvFieldsValidation<Props extends ObjectProps> =
-  | EnvKeysValidation<Props>
-  | {
-      [Key in keyof Props]: EnvDeclarationKind<Key> extends "field"
-        ? EnvFieldValidation<Props[Key]>
-        : CompileTimeError<
-            "Env",
-            "Environment fields must use camelCase names."
-          >;
-    }[keyof Props];
-
-type EnvValidation<Props extends EnvProps> =
-  | EnvKeysValidation<Props>
-  | {
-      [Key in keyof Props]: EnvDeclarationKind<Key> extends "group"
-        ? Props[Key] extends ObjectProps
-          ? EnvFieldsValidation<Props[Key]>
-          : CompileTimeError<
-              "Env",
-              "Environment namespaces must contain a group of fields."
-            >
-        : EnvDeclarationKind<Key> extends "field"
-          ? Props[Key] extends ObjectProps[string]
-            ? EnvFieldValidation<Props[Key]>
-            : CompileTimeError<
-                "Env",
-                "Environment fields must be Types, optional properties, or defaulted properties."
-              >
-          : CompileTimeError<
-              "Env",
-              "Environment declarations must use camelCase field names or CONSTANT_CASE namespace names."
-            >;
-    }[keyof Props];
-
-type EnvKeyType = TransformType<
-  typeof String,
-  typeof CamelCaseIdentifier,
-  "EnvKey",
-  never,
-  string
->;
-
 /** The configuration codec returned by {@link env}. */
 export interface EnvType<Props extends EnvProps> extends TransformType<
   typeof Unknown,
@@ -225,6 +92,11 @@ export interface EnvType<Props extends EnvProps> extends TransformType<
   >
 > {}
 
+/** Fields and one-level namespace groups used to construct an {@link env} Type. */
+export type EnvProps = Readonly<
+  Record<string, ObjectProps[string] | ObjectProps>
+>;
+
 /**
  * Creates a reversible environment-variable codec with a flat decoded output.
  *
@@ -408,3 +280,131 @@ export const env = <const Props extends EnvProps>(
   // cannot be expressed by the runtime loops above.
   return type as unknown as EnvType<Props>;
 };
+
+type EnvFlatProps<Props extends EnvProps> =
+  UnionToIntersection<
+    {
+      [Key in keyof Props]: EnvDeclarationKind<Key> extends "group"
+        ? Props[Key]
+        : EnvDeclarationKind<Key> extends "field"
+          ? { readonly [Field in Key]: Props[Key] }
+          : never;
+    }[keyof Props]
+  > extends infer Flat extends ObjectProps
+    ? Flat
+    : {};
+
+type EnvKeyType = TransformType<
+  typeof String,
+  typeof CamelCaseIdentifier,
+  "EnvKey",
+  never,
+  string
+>;
+
+type EnvValidation<Props extends EnvProps> =
+  | EnvKeysValidation<Props>
+  | {
+      [Key in keyof Props]: EnvDeclarationKind<Key> extends "group"
+        ? Props[Key] extends ObjectProps
+          ? EnvFieldsValidation<Props[Key]>
+          : CompileTimeError<
+              "Env",
+              "Environment namespaces must contain a group of fields."
+            >
+        : EnvDeclarationKind<Key> extends "field"
+          ? Props[Key] extends ObjectProps[string]
+            ? EnvFieldValidation<Props[Key]>
+            : CompileTimeError<
+                "Env",
+                "Environment fields must be Types, optional properties, or defaulted properties."
+              >
+          : CompileTimeError<
+              "Env",
+              "Environment declarations must use camelCase field names or CONSTANT_CASE namespace names."
+            >;
+    }[keyof Props];
+
+type EnvFieldsValidation<Props extends ObjectProps> =
+  | EnvKeysValidation<Props>
+  | {
+      [Key in keyof Props]: EnvDeclarationKind<Key> extends "field"
+        ? EnvFieldValidation<Props[Key]>
+        : CompileTimeError<
+            "Env",
+            "Environment fields must use camelCase names."
+          >;
+    }[keyof Props];
+
+type EnvFieldValidation<Field> =
+  IsUnion<Field> extends true
+    ? CompileTimeError<"Env", "Environment fields must use one concrete Type.">
+    : EnvFieldType<Field> extends infer T extends AnyType
+      ? IsUnion<T> extends true
+        ? CompileTimeError<
+            "Env",
+            "Environment fields must use one concrete Type."
+          >
+        : [T["CanonicalInput"]] extends [string]
+          ? Extract<
+              | "ObjectMissingProperty"
+              | "ObjectPropertyAccess"
+              | "ObjectExcessProperty",
+              InferErrors<T>["type"]
+            > extends never
+            ? never
+            : CompileTimeError<
+                "Env",
+                "Environment fields must not use error tags reserved for Object structure."
+              >
+          : CompileTimeError<
+              "Env",
+              "Environment fields must encode to strings."
+            >
+      : CompileTimeError<
+          "Env",
+          "Environment fields must use one concrete Type."
+        >;
+
+type EnvFieldType<Field> = Field extends TypeNode
+  ? Field
+  : Field extends { readonly type: infer T extends TypeNode }
+    ? T
+    : never;
+
+type EnvKeysValidation<Props> =
+  | (string extends keyof Props
+      ? CompileTimeError<
+          "Env",
+          "Environment properties must use fixed string keys."
+        >
+      : never)
+  | (IsUnion<Props> extends true
+      ? CompileTimeError<
+          "Env",
+          "Environment properties must use one concrete schema."
+        >
+      : never)
+  | {
+      [Key in keyof Props]: Key extends string
+        ? ValidateLiteral<Key> extends Key
+          ? never
+          : CompileTimeError<
+              "Env",
+              "Environment properties must use fixed string keys."
+            >
+        : CompileTimeError<
+            "Env",
+            "Environment properties must use fixed string keys."
+          >;
+    }[keyof Props];
+
+// Classify declarations by casing; identifier Types validate the full grammar
+// and name lengths during construction.
+type EnvDeclarationKind<Key> = Key extends string
+  ? Key extends Uppercase<Key>
+    ? "group"
+    : Key extends Uncapitalize<Key>
+      ? "field"
+      : "invalid"
+  : "invalid";

package/src/Console.ts

@@ -93,6 +93,7 @@ import {
  * For testing, use {@link testCreateConsole} which creates a {@link TestConsole}
  * with array output and snapshot helpers.
  *
+ * @group Core
  * @see {@link createConsole}
  */
 export interface Console {
@@ -176,6 +177,11 @@ export interface Console {
   readonly write: (entry: ConsoleEntry) => void;
 }
 
+/**
+ * Dependency wrapper for {@link Console}.
+ *
+ * @group Core
+ */
 export interface ConsoleDep {
   readonly console: Console;
 }
@@ -193,6 +199,8 @@ export interface ConsoleDep {
  * - `"warn"` — Recoverable issues that may need attention
  * - `"error"` — Failures requiring immediate attention
  * - `"silent"` — Disables all logging
+ *
+ * @group Core
  */
 export type ConsoleLevel =
   "trace" | "debug" | "log" | "info" | "warn" | "error" | "silent";
@@ -202,6 +210,8 @@ export type ConsoleLevel =
  *
  * Contains all information needed for outputs to route the log: method for
  * routing, path for context, and the original arguments.
+ *
+ * @group Core
  */
 export interface ConsoleEntry {
   /** The console method that was called. */
@@ -219,6 +229,8 @@ export interface ConsoleEntry {
  *
  * Used in {@link ConsoleEntry} to identify which console method was invoked.
  * Outputs can route or format differently based on the method.
+ *
+ * @group Core
  */
 export type ConsoleMethod =
   | "trace"
@@ -242,6 +254,8 @@ export type ConsoleMethod =
  * array for testing, etc.).
  *
  * Use {@link createNativeConsoleOutput} for native console output.
+ *
+ * @group Output
  */
 export interface ConsoleOutput {
   /** Write a log entry to this output. */
@@ -253,10 +267,16 @@ export interface ConsoleOutput {
  *
  * Used by {@link ConsoleConfig.formatter} and {@link ConsoleOutput.write}. Create
  * one with {@link createConsoleFormatter}.
+ *
+ * @group Output
  */
 export type ConsoleFormatter = (entry: ConsoleEntry) => ReadonlyArray<unknown>;
 
-/** Configuration for {@link createConsole}. */
+/**
+ * Configuration for {@link createConsole}.
+ *
+ * @group Core
+ */
 export interface ConsoleConfig {
   /** Name of this console. Defaults to empty string. */
   readonly name?: string;
@@ -283,7 +303,11 @@ export interface ConsoleConfig {
   readonly formatter?: ConsoleFormatter;
 }
 
-/** Configuration for {@link createConsoleFormatter}. */
+/**
+ * Configuration for {@link createConsoleFormatter}.
+ *
+ * @group Output
+ */
 export interface ConsoleFormatterConfig {
   /**
    * Timestamp format to prepend to log messages.
@@ -304,7 +328,11 @@ export interface ConsoleFormatterConfig {
   readonly startTime?: Millis;
 }
 
-/** Timestamp format for {@link ConsoleFormatterConfig}. */
+/**
+ * Timestamp format for {@link ConsoleFormatterConfig}.
+ *
+ * @group Output
+ */
 export type ConsoleEntryTimestampFormat =
   "relative" | "absolute" | "iso" | "none";
 
@@ -341,6 +369,8 @@ export type ConsoleEntryTimestampFormat =
  *   args: ["connected"],
  * });
  * ```
+ *
+ * @group Output
  */
 export interface ConsoleStoreOutput extends ConsoleOutput {
   /** Latest entry written to this output. */
@@ -350,6 +380,8 @@ export interface ConsoleStoreOutput extends ConsoleOutput {
 /**
  * Dependency providing the latest {@link ConsoleEntry} from a
  * {@link ConsoleStoreOutput}.
+ *
+ * @group Output
  */
 export interface ConsoleStoreOutputEntryDep {
   readonly consoleStoreOutputEntry: ReadonlyStore<ConsoleEntry | null>;
@@ -359,6 +391,8 @@ export interface ConsoleStoreOutputEntryDep {
  * A test console that captures all output for assertions.
  *
  * Use as a drop-in replacement for {@link Console} in tests.
+ *
+ * @group Testing
  */
 export interface TestConsole extends Console {
   /** Gets all captured entries and clears the internal buffer. */
@@ -368,6 +402,11 @@ export interface TestConsole extends Console {
   readonly clearEntries: () => void;
 }
 
+/**
+ * Dependency wrapper for {@link TestConsole}.
+ *
+ * @group Testing
+ */
 export interface TestConsoleDep {
   readonly console: TestConsole;
 }
@@ -382,7 +421,11 @@ const levelOrder: Record<ConsoleLevel, number> = {
   silent: 6,
 };
 
-/** Creates a {@link Console}. */
+/**
+ * Creates a {@link Console}.
+ *
+ * @group Core
+ */
 export const createConsole = ({
   name = "",
   level = "log",
@@ -458,7 +501,6 @@ export const createConsole = ({
  *
  * ```ts
  * import {
- *   assertEqual,
  *   assertType,
  *   createNativeConsoleOutput,
  *   type ConsoleOutput,
@@ -467,8 +509,9 @@ export const createConsole = ({
  * const output = createNativeConsoleOutput();
  *
  * assertType<typeof output, ConsoleOutput>();
- * assertEqual(typeof output.write, "function");
  * ```
+ *
+ * @group Output
  */
 export const createNativeConsoleOutput = (): ConsoleOutput => ({
   write: (entry, formatter) => {
@@ -530,6 +573,8 @@ export const createNativeConsoleOutput = (): ConsoleOutput => ({
  * assertType(Data, absolute);
  * assertEqual(absolute, ["14:30:15.123 [relay]", "connected"]);
  * ```
+ *
+ * @group Output
  */
 export const createConsoleFormatter =
   ({ time = createTime() }: Partial<TimeDep> = {}) =>
@@ -566,7 +611,11 @@ export const createConsoleFormatter =
     };
   };
 
-/** Creates a {@link ConsoleStoreOutput}. */
+/**
+ * Creates a {@link ConsoleStoreOutput}.
+ *
+ * @group Output
+ */
 export const createConsoleStoreOutput = (): ConsoleStoreOutput => {
   const entry = createStore<ConsoleEntry | null>(null);
   return {
@@ -600,6 +649,8 @@ export const createConsoleStoreOutput = (): ConsoleStoreOutput => {
  *   { method: "info", path: [], args: ["connected"] },
  * ]);
  * ```
+ *
+ * @group Output
  */
 export const createConsoleArrayOutput = (
   entries: Array<ConsoleEntry>,
@@ -644,6 +695,8 @@ export const createConsoleArrayOutput = (
  * assertType(Data, entries[0]);
  * assertEqual(storedEntry, entries[0]);
  * ```
+ *
+ * @group Output
  */
 export const createMultiOutput = (
   outputs: ReadonlyArray<ConsoleOutput>,
@@ -672,6 +725,8 @@ export const createMultiOutput = (
  *   { method: "info", path: ["relay"], args: ["connected"] },
  * ]);
  * ```
+ *
+ * @group Testing
  */
 export const testCreateConsole = ({
   level = "trace",

package/src/Crypto.ts

@@ -24,6 +24,11 @@ import {
   zeroNonNegativeInt,
 } from "./Type.ts";
 
+/**
+ * Cryptographically secure random bytes with length-branded results.
+ *
+ * @group Random bytes
+ */
 export interface RandomBytes {
   /**
    * Creates cryptographically secure random bytes with type-safe length
@@ -77,6 +82,11 @@ export interface RandomBytes {
   create(bytesLength: number): Entropy;
 }
 
+/**
+ * Dependency wrapper for {@link RandomBytes}.
+ *
+ * @group Random bytes
+ */
 export interface RandomBytesDep {
   readonly randomBytes: RandomBytes;
 }
@@ -84,23 +94,53 @@ export interface RandomBytesDep {
 const Entropy = /*#__PURE__*/ brand("Entropy", Uint8Array);
 type Entropy = typeof Entropy.Output;
 
+/**
+ * Cryptographic entropy of exactly 16 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy16 = /*#__PURE__*/ length(16)(Entropy);
 export type Entropy16 = typeof Entropy16.Output;
 
+/**
+ * Cryptographic entropy of exactly 24 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy24 = /*#__PURE__*/ length(24)(Entropy);
 export type Entropy24 = typeof Entropy24.Output;
 
+/**
+ * Cryptographic entropy of exactly 32 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy32 = /*#__PURE__*/ length(32)(Entropy);
 export type Entropy32 = typeof Entropy32.Output;
 
+/**
+ * Cryptographic entropy of exactly 64 bytes.
+ *
+ * @group Random bytes
+ */
 export const Entropy64 = /*#__PURE__*/ length(64)(Entropy);
 export type Entropy64 = typeof Entropy64.Output;
 
+/**
+ * Creates {@link RandomBytes} backed by the platform's secure random number
+ * generator.
+ *
+ * @group Random bytes
+ */
 export const createRandomBytes = (): RandomBytes => ({
   create: randomBytes as RandomBytes["create"],
 });
 
-/** Creates seeded random bytes for deterministic tests. */
+/**
+ * Creates seeded random bytes for deterministic tests.
+ *
+ * @group Testing
+ */
 export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
   ({
     create: (bytesLength: number) =>
@@ -113,6 +153,8 @@ export const testCreateRandomBytes = (deps: RandomLibDep): RandomBytes =>
  * SLIP21.
  *
  * https://github.com/satoshilabs/slips/blob/master/slip-0021.md
+ *
+ * @group Key derivation
  */
 export const createSlip21 = (
   seed: Entropy16 | Entropy32 | Entropy64,
@@ -135,6 +177,7 @@ export const createSlip21 = (
 /**
  * Derives a single node in the SLIP-21 hierarchical key derivation.
  *
+ * @group Key derivation
  * @see {@link createSlip21}
  */
 export const deriveSlip21Node = (
@@ -148,16 +191,25 @@ export const deriveSlip21Node = (
   return hmac(sha512, parentNode.slice(0, 32), message) as Entropy64;
 };
 
-/** The encryption key for symmetric encryption. */
+/**
+ * The encryption key for symmetric encryption.
+ *
+ * @group Encryption
+ */
 export const EncryptionKey = /*#__PURE__*/ brand("EncryptionKey", Entropy32);
 export type EncryptionKey = typeof EncryptionKey.Output;
 
-/** The nonce length for XChaCha20-Poly1305 encryption. */
+/**
+ * The nonce length for XChaCha20-Poly1305 encryption.
+ *
+ * @group Encryption
+ */
 export const xChaCha20Poly1305NonceLength = 24;
 
 /**
  * Branded Uint8Array for XChaCha20-Poly1305 encryption.
  *
+ * @group Encryption
  * @see {@link encryptWithXChaCha20Poly1305}
  */
 export const XChaCha20Poly1305Ciphertext = /*#__PURE__*/ brand(
@@ -196,6 +248,7 @@ export type XChaCha20Poly1305Ciphertext =
  * assertEqual(nonce.length, 24);
  * ```
  *
+ * @group Encryption
  * @see https://github.com/paulmillr/noble-ciphers
  */
 export const encryptWithXChaCha20Poly1305 =
@@ -211,6 +264,11 @@ export const encryptWithXChaCha20Poly1305 =
     return [ciphertext, nonce];
   };
 
+/**
+ * Error returned by {@link decryptWithXChaCha20Poly1305} when decryption fails.
+ *
+ * @group Encryption
+ */
 export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXChaCha20Poly1305Error"> {
   readonly error: unknown;
 }
@@ -254,6 +312,8 @@ export interface DecryptWithXChaCha20Poly1305Error extends Typed<"DecryptWithXCh
  *
  * assertOk(decryptMessage(), "secret message");
  * ```
+ *
+ * @group Encryption
  */
 export const decryptWithXChaCha20Poly1305 = (
   ciphertext: XChaCha20Poly1305Ciphertext,
@@ -275,6 +335,8 @@ export const decryptWithXChaCha20Poly1305 = (
  * wide range of encrypted data sizes.
  *
  * See the PURBs paper for details: https://bford.info/pub/sec/purb.pdf
+ *
+ * @group Padding
  */
 export const createPadmePaddedLength = (
   length: NonNegativeInt,
@@ -287,7 +349,11 @@ export const createPadmePaddedLength = (
   return NonNegativeInt.orThrow((length + mask) & ~mask);
 };
 
-/** Creates a PADMÉ padding array of zeros for the given input length. */
+/**
+ * Creates a PADMÉ padding array of zeros for the given input length.
+ *
+ * @group Padding
+ */
 export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
   const paddedLength = createPadmePaddedLength(length);
   const paddingLength = NonNegativeInt.orThrow(paddedLength - length);
@@ -299,10 +365,16 @@ export const createPadmePadding = (length: NonNegativeInt): Uint8Array => {
  * are equal, false otherwise. Takes constant time regardless of where the
  * arrays differ.
  *
+ * @group Comparison
  * @see https://nodejs.org/api/crypto.html#cryptotimingsafeequala-b
  */
 export type TimingSafeEqual = (a: Uint8Array, b: Uint8Array) => boolean;
 
+/**
+ * Dependency wrapper for {@link TimingSafeEqual}.
+ *
+ * @group Comparison
+ */
 export interface TimingSafeEqualDep {
   readonly timingSafeEqual: TimingSafeEqual;
 }

package/src/Eq.test.ts

@@ -293,13 +293,12 @@ test("eqData", () => {
   }
   const service: Service = { run: () => undefined };
   const broadObject: NonNullable<unknown> = new WeakMap();
-  const compileTimeAssertions = () => {
+  void (() => {
     // @ts-expect-error ⛔ eqData error: Actual and expected values must consist only of Data.
     eqData(service, service);
     // @ts-expect-error ⛔ eqData error: Actual and expected values must consist only of Data.
     eqData(broadObject, broadObject);
-  };
-  assertEqual(typeof compileTimeAssertions, "function");
+  });
 });
 
 test("eqData compares deeply nested Set and Map data", () => {