@evolu/common 8.10.0 → 8.12.0

package/src/Bytes.ts

@@ -20,7 +20,11 @@
  * @module
  */
 
-import { bytesToUtf8, utf8ToBytes } from "@noble/ciphers/utils.js";
+import {
+  bytesToUtf8,
+  concatBytes as nobleConcatBytes,
+  utf8ToBytes,
+} from "@noble/ciphers/utils.js";
 import { assert } from "./Assert.ts";
 import { err, ok, type Result } from "./Result.ts";
 import { safelyStringifyUnknownValue } from "./String.ts";
@@ -44,9 +48,61 @@ import {
   union,
   type UnionError,
 } from "./Type.ts";
-export { bytesToHex, concatBytes, hexToBytes } from "@noble/ciphers/utils.js";
+export { bytesToHex, hexToBytes } from "@noble/ciphers/utils.js";
 export { bytesToUtf8, utf8ToBytes };
 
+/**
+ * Copies several Uint8Arrays into one.
+ *
+ * Each array is a separate argument, so it is meant for a few arrays. Spreading
+ * many arrays into it overflows the call stack; use {@link concatByteArrays}
+ * when their count is not bounded.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, concatBytes } from "@evolu/common";
+ *
+ * assertEqual(
+ *   concatBytes(new Uint8Array([1]), new Uint8Array([2, 3])),
+ *   new Uint8Array([1, 2, 3]),
+ * );
+ * ```
+ */
+export const concatBytes: typeof nobleConcatBytes = nobleConcatBytes;
+
+/**
+ * Copies an array of Uint8Arrays into one.
+ *
+ * Unlike {@link concatBytes}, it takes the arrays as one array, so it works for
+ * any number of them, such as the timestamps of a batch received from a peer.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { assertEqual, concatByteArrays } from "@evolu/common";
+ *
+ * assertEqual(
+ *   concatByteArrays([new Uint8Array([1]), new Uint8Array([2, 3])]),
+ *   new Uint8Array([1, 2, 3]),
+ * );
+ * ```
+ */
+export const concatByteArrays = (
+  arrays: ReadonlyArray<Uint8Array>,
+): Uint8Array => {
+  let length = 0;
+  for (const array of arrays) length += array.length;
+
+  const result = new Uint8Array(length);
+  let offset = 0;
+  for (const array of arrays) {
+    result.set(array, offset);
+    offset += array.length;
+  }
+  return result;
+};
+
 /**
  * Custom error for {@link Buffer}-related failures like premature end of data.
  * Provides better stack traces for debugging binary protocol issues.

package/src/Config.test.ts

@@ -602,7 +602,7 @@ describe("env", () => {
   });
 
   it("requires concrete field Types that encode to strings", () => {
-    const reject = (
+    void ((
       erased: TypeNode,
       reserved: Type<
         "CustomEnv",
@@ -663,10 +663,6 @@ describe("env", () => {
       env(template);
       // @ts-expect-error Environment properties must use fixed string keys.
       env({ [Symbol("invalidKey")]: String });
-    };
-    assertType<
-      typeof reject extends (...args: Array<never>) => void ? true : false,
-      true
-    >();
+    });
   });
 });

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",