@evolu/common 6.0.1-preview.8 → 7.0.0

package/src/Type.ts

@@ -1,84 +1,219 @@
 /**
- * 🧩 Validation, Parsing, and Transformation
+ * 🧩 Type-safe runtime types
  *
- * ## Intro
+ * Evolu {@link Type} is like a type guard that returns typed errors (via
+ * {@link Result}) instead of throwing. We either get a safely typed value or a
+ * composable typed error telling us exactly why validation failed.
  *
- * You probably know [Zod](https://zod.dev). Evolu has {@link Type}.
+ * Why another validation library?
  *
- * Evolu Type exists because no existing validation/parsing/transformation
- * library fully met our needs:
+ * - **Result-based error handling** – no exceptions for normal control flow.
+ * - **Typed errors with decoupled formatters** – validation logic ≠ user
+ *   messages.
+ * - **Consistent constraints via {@link Brand}** – every constraint becomes part
+ *   of the type.
+ * - **Skippable validation** – parent validations can be skipped when already
+ *   proved by types.
+ * - **Simple, top-down implementation** – readable source code from top to
+ *   bottom.
+ * - **No user-land chaining DSL** – prepared for TC39 Hack pipes.
  *
- * - **Result-based error handling**: Leveraging {@link Result} instead of throwing
- *   exceptions.
- * - **Consistent constraints**: Enforcing {@link Brand} for all constraints.
- * - **Typed errors with decoupled formatters**: Avoiding coupling error messages
- *   with validators.
- * - **No user-land chaining**: Designed with ES pipe operator in mind.
- * - **Selective validation/transformation**: Skipping parent Type validations and
- *   transformations when TypeScript's type system can be relied upon.
- * - **Bidirectional transformations**: Supporting transformations in both
- *   directions.
- * - **Minimal and transparent code**: No runtime dependencies or hidden magic.
+ * A distinctive feature of Evolu Type compared to other validation libraries is
+ * that it returns typed errors rather than string messages. This allows
+ * TypeScript to enforce that all validation errors are handled by type
+ * checking, significantly improving the developer experience.
  *
- * **Note**: A proper quickstart guide is on the way. In the meantime, each type
- * includes its own usage example, and you can (and should) check the tests for
- * practical demonstrations of the API. Or dang, just read the code. It's
- * simple.
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
  *
- * - Evolu `Type` is:
+ * ### Base Types Quick Start
  *
- * - A TypeScript type with a {@link Brand} whenever it's possible.
- * - A function to create a value of that type, which may fail.
- * - A function to transform value back to its original representation, which
- *   cannot fail.
+ * ```ts
+ * // Validate unknown values
+ * const value: unknown = "hello";
+ * const stringResult = String.fromUnknown(value);
+ * if (!stringResult.ok) {
+ *   // console.error(formatStringError(stringResult.error));
+ *   return stringResult; // inside a function returning Result<string, _>
+ * }
+ * // Safe branch: value is now string
+ * const upper = stringResult.value.toUpperCase();
+ *
+ * // Type guard style
+ * if (String.is(value)) {
+ *   // narrowed to string
+ * }
+ *
+ * // Composing: arrays & objects
+ * const Numbers = array(Number); // ReadonlyArray<number>
+ * const Point = object({ x: Number, y: Number });
+ *
+ * Numbers.from([1, 2, 3]); // ok
+ * Point.from({ x: 1, y: 2 }); // ok
+ * Point.from({ x: 1, y: "2" }); // err -> nested Number error
+ * ```
+ *
+ * ### Branding Basics
+ *
+ * Branding adds semantic meaning & constraints while preserving the runtime
+ * shape:
+ *
+ * ```ts
+ * const CurrencyCode = brand("CurrencyCode", String, (value) =>
+ *   /^[A-Z]{3}$/.test(value)
+ *     ? ok(value)
+ *     : err<CurrencyCodeError>({ type: "CurrencyCode", value }),
+ * );
+ * type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
+ *
+ * interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
+ *
+ * const formatCurrencyCodeError =
+ *   createTypeErrorFormatter<CurrencyCodeError>(
+ *     (error) => `Invalid currency code: ${error.value}`,
+ *   );
+ *
+ * const r = CurrencyCode.from("USD"); // ok("USD")
+ * const e = CurrencyCode.from("usd"); // err(...)
+ * ```
+ *
+ * See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
+ * `positive`, `between`, etc.
+ *
+ * ### Objects & Optional Fields
+ *
+ * ```ts
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ * type User = typeof User.Type;
+ *
+ * User.from({ name: "Alice" }); // ok
+ * User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
+ * ```
+ *
+ * ### Deriving JSON String Types
+ *
+ * ```ts
+ * const Person = object({
+ *   name: NonEmptyString50,
+ *   // Did you know that JSON.stringify converts NaN (a number) into null?
+ *   // To prevent this, use FiniteNumber.
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
+ *
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * const person = Person.orThrow({
+ *   name: "Alice",
+ *   age: 30,
+ * });
+ *
+ * const personJson = personToPersonJson(person);
+ * expect(personJsonToPerson(personJson)).toEqual(person);
+ * ```
+ *
+ * ### Error Formatting
+ *
+ * Evolu separates validation logic from human-readable messages. There are two
+ * layers:
+ *
+ * 1. Per-type formatters (e.g. `formatStringError`) – simple, focused, already
+ *    used earlier in the quick start example.
+ * 2. A unified formatter via `createFormatTypeError` – composes all built-in and
+ *    custom errors (including nested composite types) and lets us override
+ *    selected messages.
+ *
+ * #### 1. Per-Type Formatter (recap)
  *
- * Types are chainable. The chain starts with a Base Type that refines an
- * unknown value into something and can continue with further refinements or
- * transformations. For example, `NonEmptyTrimmedString100` chain looks like
- * this:
+ * ```ts
+ * const r = String.fromUnknown(42);
+ * if (!r.ok) console.error(formatStringError(r.error));
+ * ```
  *
- * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ * #### 2. Unified Formatter with Overrides
  *
- * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
- * `TrimmedString`, the parent Type is `String`.
+ * ```ts
+ * // Override only what we care about; fall back to built-ins for the rest.
+ * const formatTypeError = createFormatTypeError((error) => {
+ *   if (error.type === "MinLength") return `Min length is ${error.min}`;
+ * });
  *
- * The parent of the `String` Type is the `String` Type itself. All Base Types
- * `fromParent` functions are just a typed alias to `fromUnknown` to ensure that
- * `fromParent` and `toParent` can be called on any Type.
+ * const User = object({ name: NonEmptyTrimmedString100 });
+ * const resultUser = User.from({ name: "" });
+ * if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
  *
- * Speaking of `fromParent` and `toParent`, those functions exist to bypass
- * parent Types when we can rely on TypeScript types.
+ * const badPoint = object({ x: Number, y: Number }).from({
+ *   x: 1,
+ *   y: "foo",
+ * });
+ * if (!badPoint.ok) console.error(formatTypeError(badPoint.error));
+ * ```
  *
- * `Type` transformations should be reversible. If you need an irreversible
- * transformation, such as `TrimString` (trimming is not reversible as `untrim`
- * can't know what has been trimmed), you can do that, but note in JSDoc that
- * `to` will not restore the original representation. You can also use
- * {@link assert}: `assert(false, "Untrim is not possible")`.
+ * The unified formatter walks nested structures (object / array / record /
+ * tuple / union) and applies overrides only where specified, greatly reducing
+ * boilerplate when formatting complex validation errors.
  *
  * ### Tip
  *
  * If necessary, write `globalThis.String` instead of `String` to avoid naming
- * clashes with Base Types.
+ * clashes with native types.
+ *
+ * ### Design Decision: No Bidirectional Transformations
  *
- * ### Design Decision:
+ * Evolu Type intentionally does not support bidirectional transformations. It
+ * previously did, but supporting that while keeping typed error fidelity added
+ * complexity that hurt readability & reliability. Most persistence pipelines
+ * (e.g. SQLite) already require explicit mapping of query results, so implicit
+ * reverse transforms would not buy much. We may revisit this if we can design a
+ * minimal, 100% safe API that preserves simplicity.
  *
- * While the `from` function can fail, the `to` function cannot. This simplifies
- * the model by ensuring that every valid input has a corresponding valid
- * output, eliminating the risk of edge cases caused by irreversible
- * operations.
+ * ### Prepared for TC39 Hack Pipes
+ *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper) and read well, but with
+ * TC39 Hack pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
+ * Note `minLength` and `maxLength` are curried because they are factories.
  *
  * @module
  */
 
+import { utf8ToBytes } from "@noble/ciphers/utils.js";
+import { sha256 } from "@noble/hashes/sha2.js";
 import * as bip39 from "@scure/bip39";
-import { wordlist } from "@scure/bip39/wordlists/english";
-import { assert } from "./Assert.js";
-import { identity } from "./Function.js";
-import { NanoIdLibDep } from "./NanoId.js";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { pack } from "msgpackr";
+import type { Brand } from "./Brand.js";
+import { type RandomBytesDep } from "./Crypto.js";
 import { isPlainObject } from "./Object.js";
-import { Err, err, Ok, ok, Result, trySync } from "./Result.js";
+import { hasNodeBuffer } from "./Platform.js";
+import { err, getOrNull, getOrThrow, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
-import type { Brand, Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { TimeDep } from "./Time.js";
+import type { Literal, Simplify, WidenLiteral } from "./Types.js";
 import { IntentionalNever } from "./Types.js";
 
 export interface Type<
@@ -93,7 +228,7 @@ export interface Type<
   Parent = T,
   /** The parent's error. */
   ParentError extends TypeError = Error,
-> {
+> extends StandardSchemaV1<Input, T> {
   readonly name: Name;
 
   /**
@@ -106,41 +241,98 @@ export interface Type<
   readonly from: (value: Input) => Result<T, ParentError | Error>;
 
   /**
-   * Creates `T` from an unknown value.
+   * Creates `T` from an `Input` value, throwing an error if validation fails.
    *
-   * This is useful when a value is unknown.
-   */
-  readonly fromUnknown: (value: unknown) => Result<T, ParentError | Error>;
-
-  /**
-   * The opposite of `from` and `fromUnknown`.
+   * Throws an Error with the Type validation error in its `cause` property,
+   * making it debuggable while avoiding the need for custom error messages.
+   *
+   * This is a convenience method that combines `from` with `getOrThrow`.
+   *
+   * **When to use:**
    *
-   * This is useful to transform `T` back to its `Input` representation.
+   * - Configuration values that are guaranteed to be valid (e.g., hardcoded
+   *   constants)
+   * - Application startup where failure should crash the program
+   * - As an alternative to assertions when the Type error in the thrown Error's
+   *   `cause` provides sufficient debugging information
+   * - Test code with known valid inputs (when error message clarity is not
+   *   critical; for better test error messages, use Vitest `schemaMatching` +
+   *   `assert` with `.is()`)
    *
-   * For `refine`, it only removes the brand. For `transform`, it changes value.
+   * ### Example
+   *
+   * ```ts
+   * // ✅ Good: Known valid constant
+   * const maxRetries = PositiveInt.orThrow(3);
+   *
+   * // ✅ Good: App configuration that should crash on invalid values
+   * const appName = SimpleName.orThrow("MyApp");
+   *
+   * // ✅ Good: Instead of assert when Type error is clear enough
+   * // Context makes it obvious: count increments from non-negative value
+   * const currentCount = counts.get(id) ?? 0;
+   * const newCount = PositiveInt.orThrow(currentCount + 1);
+   *
+   * // ✅ Good: Test setup with known valid values
+   * const testUser = User.orThrow({ name: "Alice", age: 30 });
+   *
+   * // ❌ Avoid: User input (use `from` instead)
+   * const userAge = PositiveInt.orThrow(userInput); // Could crash!
+   *
+   * // ✅ Better: Handle user input gracefully
+   * const ageResult = PositiveInt.from(userInput);
+   * if (!ageResult.ok) {
+   *   // Handle validation error
+   * }
+   * ```
    */
-  readonly to: (value: T) => Input;
+  readonly orThrow: (value: Input) => T;
 
   /**
-   * Creates `T` from `Parent` type.
+   * Creates `T` from an `Input` value, returning `null` if validation fails.
    *
-   * This function skips parent Types validations/transformations when we have
-   * already partially validated/transformed value.
+   * This is a convenience method that combines `from` with `getOrNull`.
    *
-   * For example, `TrimString.from` checks whether a value is a string and trims
-   * it. If we only want to trim a string, we can use `fromParent`.
+   * **When to use:**
+   *
+   * - When you need to convert a validation result to a nullable value
+   * - When the error is not important and you just want the value or nothing
    *
    * ### Example
    *
    * ```ts
-   * // string & Brand<"Trimmed">
-   * const value = TrimString.fromParent("a ").value; // as efficient as foo.trim()
+   * // ✅ Good: Optional user input
+   * const age = PositiveInt.orNull(userInput);
+   * if (age != null) {
+   *   console.log("Valid age:", age);
+   * }
+   *
+   * // ✅ Good: Default fallback
+   * const maxRetries = PositiveInt.orNull(config.retries) ?? 3;
+   *
+   * // ❌ Avoid: When you need to know why validation failed (use `from` instead)
+   * const result = PositiveInt.from(userInput);
+   * if (!result.ok) {
+   *   console.error(formatPositiveError(result.error));
+   * }
    * ```
    */
-  readonly fromParent: (value: Parent) => Result<T, Error>;
+  readonly orNull: (value: Input) => T | null;
 
-  /** The opposite of `fromParent`. */
-  readonly toParent: (value: T) => Parent;
+  /**
+   * Creates `T` from an unknown value.
+   *
+   * This is useful when a value is unknown.
+   */
+  readonly fromUnknown: (value: unknown) => Result<T, ParentError | Error>;
+
+  /**
+   * Creates `T` from `Parent` type.
+   *
+   * This function skips parent Types validations when we have already partially
+   * validated value.
+   */
+  readonly fromParent: (value: Parent) => Result<T, Error>;
 
   /**
    * A **type guard** that checks whether an unknown value satisfies the
@@ -221,8 +413,6 @@ export interface Type<
   readonly ParentError: ParentError;
 
   /**
-   * Error | ParentError
-   *
    * ### Example
    *
    * ```ts
@@ -261,26 +451,61 @@ export interface TypeErrorWithReason<
 
 export type AnyType = Type<any, any, any, any, any, any>;
 
+/**
+ * Extracts the name from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferName<A extends AnyType> =
   A extends Type<infer Name, any, any, any, any, any> ? Name : never;
 
+/**
+ * Extracts the type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferType<A extends AnyType> =
   A extends Type<any, infer T, any, any, any, any> ? T : never;
 
+/**
+ * Extracts the input type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferInput<A extends AnyType> =
   A extends Type<any, any, infer Input, any, any, any> ? Input : never;
 
+/**
+ * Extracts the specific error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferError<A extends AnyType> =
   A extends Type<any, any, any, infer Error, any, any> ? Error : never;
 
+/**
+ * Extracts the parent type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParent<A extends AnyType> =
   A extends Type<any, any, any, any, infer Parent, any> ? Parent : never;
 
+/**
+ * Extracts the parent error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParentError<A extends AnyType> =
   A extends Type<any, any, any, any, any, infer ParentError>
     ? ParentError
     : never;
 
+/**
+ * Extracts all error types from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferErrors<T extends AnyType> =
   T extends Type<any, any, any, infer Error, any, infer ParentError>
     ? Error | ParentError
@@ -310,6 +535,8 @@ const createType = <
     | "name"
     | "is"
     | "from"
+    | "orThrow"
+    | "orNull"
     | typeof EvoluTypeSymbol
     | "Type"
     | "Input"
@@ -317,12 +544,15 @@ const createType = <
     | "Parent"
     | "ParentError"
     | "Errors"
+    | "~standard"
   >,
 ): Type<Name, T, Input, Error, Parent, ParentError> => ({
   ...definition,
   name,
   is: (value: unknown): value is T => definition.fromUnknown(value).ok,
   from: definition.fromUnknown,
+  orThrow: (value) => getOrThrow(definition.fromUnknown(value)),
+  orNull: (value) => getOrNull(definition.fromUnknown(value)),
   [EvoluTypeSymbol]: true,
   Type: undefined as unknown as T,
   Input: undefined as unknown as Input,
@@ -330,6 +560,27 @@ const createType = <
   Parent: undefined as unknown as Parent,
   ParentError: undefined as unknown as ParentError,
   Errors: undefined as unknown as Error | ParentError,
+  "~standard": {
+    version: 1,
+    vendor: "evolu",
+    validate: (value: unknown): StandardSchemaV1.Result<T> => {
+      const result = definition.fromUnknown(value);
+      if (result.ok) {
+        return { value: result.value };
+      }
+      cachedStandardSchemaFormatTypeError ??= createFormatTypeError();
+      return {
+        issues: typeErrorToStandardSchemaIssues(
+          result.error as TypeErrors<Error>,
+          cachedStandardSchemaFormatTypeError,
+        ),
+      };
+    },
+    types: {
+      input: undefined as unknown as Input,
+      output: undefined as unknown as T,
+    },
+  },
 });
 
 /**
@@ -365,12 +616,6 @@ export type TypeErrorFormatter<Error extends TypeError> = (
  * Base {@link Type}.
  *
  * A Base Type validates that a value conforms to a specific TypeScript type.
- * Unlike refinements or transformations, Base Types establish the fundamental
- * shape of a value before any branding or transformation occurs.
- *
- * - To **refine** a Base Type further, use the {@link brand} Type Factory.
- * - To **transform** a Base Type into a different representation, use the
- *   {@link transform} Type Factory.
  *
  * ### Example
  *
@@ -396,9 +641,7 @@ export const base = <Name extends TypeName, T, Error extends TypeError>(
 ): Type<Name, T, T, Error> =>
   createType(name, {
     fromUnknown,
-    to: identity,
     fromParent: ok<T>, // `fromParent` relies on types, so it can't fail for the Base Type
-    toParent: identity,
   });
 
 /**
@@ -564,7 +807,7 @@ export interface InstanceOfType<T extends abstract new (...args: any) => any>
 }
 
 export const formatInstanceOfError = createTypeErrorFormatter<InstanceOfError>(
-  (error) => `Value ${error.value} is not an instance of ${error.ctor}`,
+  (error) => `The value ${error.value} is not an instance of ${error.ctor}.`,
 );
 
 /**
@@ -607,7 +850,7 @@ export const formatIsTypeError = createTypeErrorFormatter<EvoluTypeError>(
  * The `brand` Type Factory takes the name of a new {@link Brand}, a parent Type
  * to be branded, and the optional `refine` function for additional constraint.
  *
- * If the `refine` function is omited, TODO:
+ * The `refine` function can be omitted if we only want to add a brand.
  *
  * ### Examples
  *
@@ -686,7 +929,7 @@ export const formatIsTypeError = createTypeErrorFormatter<EvoluTypeError>(
  *   confirmPassword: SimplePassword,
  * });
  *
- * const ValidForm = brand("Valid", Form, (value) => {
+ * const ValidForm = brand("ValidForm", Form, (value) => {
  *   if (value.password !== value.confirmPassword)
  *     return err<ValidFormError>({
  *       type: "ValidForm",
@@ -780,9 +1023,7 @@ export function brand<
   return {
     ...createType("Brand", {
       fromUnknown,
-      to: identity,
       fromParent: (refine ?? ok) as IntentionalNever,
-      toParent: identity,
     }),
     brand: name,
     parentType: parent,
@@ -830,7 +1071,7 @@ export interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
 
 export const formatCurrencyCodeError =
   createTypeErrorFormatter<CurrencyCodeError>(
-    (error) => `Invalid currency code: ${error.value}`,
+    (error) => `Invalid currency code: ${error.value}.`,
   );
 
 /**
@@ -848,30 +1089,41 @@ export const formatCurrencyCodeError =
  * ### Example
  *
  * ```ts
- * const result = DateIsoString.from("2023-01-01T12:00:00.000Z"); // ok
- * const error = DateIsoString.from("10000-01-01T00:00:00.000Z"); // err
+ * const result = DateIso.from("2023-01-01T12:00:00.000Z"); // ok
+ * const error = DateIso.from("10000-01-01T00:00:00.000Z"); // err
  * ```
  *
  * @category String
  */
-export const DateIsoString = brand("DateIso", String, (value) => {
+export const DateIso = brand("DateIso", String, (value) => {
   if (value.length !== 24) {
-    return err<DateIsoStringError>({ type: "DateIsoString", value });
+    return err<DateIsoError>({ type: "DateIso", value });
+  }
+  const parsed = globalThis.Date.parse(value);
+  if (isNaN(parsed)) {
+    return err<DateIsoError>({ type: "DateIso", value });
   }
-  if (isNaN(globalThis.Date.parse(value))) {
-    return err<DateIsoStringError>({ type: "DateIsoString", value });
+  // Round-trip test: ensure the string is actually a proper ISO format
+  const roundTrip = new globalThis.Date(parsed).toISOString();
+  if (roundTrip !== value) {
+    return err<DateIsoError>({ type: "DateIso", value });
   }
   return ok(value);
 });
 
-export type DateIsoString = typeof DateIsoString.Type;
+export type DateIso = typeof DateIso.Type;
 
-export interface DateIsoStringError extends TypeError<"DateIsoString"> {}
+export interface DateIsoError extends TypeError<"DateIso"> {}
 
-export const formatDateIsoStringError =
-  createTypeErrorFormatter<DateIsoStringError>(
-    (error) => `The value ${error.value} is not a valid ISO 8601 date string.`,
-  );
+export const formatDateIsoError = createTypeErrorFormatter<DateIsoError>(
+  (error) => `The value ${error.value} is not a valid ISO 8601 date string.`,
+);
+
+export const dateToDateIso = (value: Date): Result<DateIso, DateIsoError> =>
+  DateIso.fromParent(value.toISOString());
+
+export const dateIsoToDate = (value: DateIso): Date =>
+  new globalThis.Date(value);
 
 /**
  * Helper type for Type Factory that creates a branded Type.
@@ -914,18 +1166,12 @@ export type BrandFactory<
 /**
  * Trimmed string.
  *
- * This Type Factory does not transform; it only validates whether a string has
- * no leading or trailing whitespaces. To trim a string, use {@link trim} Type
- * Factory.
+ * This Type Factory validates whether a string has no leading or trailing
+ * whitespaces.
  *
- * ### Examples
+ * ### Example
  *
  * ```ts
- * // this Type already exists
- * const TrimmedString = trimmed(String);
- * type TrimmedString = typeof TrimmedString.Type;
- *
- * // we can make any branded Type trimmed:
  * const TrimmedNonEmptyString = trimmed(minLength(1)(String));
  * // string & Brand<"MinLength1"> & Brand<"Trimmed">
  * type TrimmedNonEmptyString = typeof TrimmedNonEmptyString.Type;
@@ -945,67 +1191,9 @@ export const trimmed: BrandFactory<"Trimmed", string, TrimmedError> = (
 export interface TrimmedError extends TypeError<"Trimmed"> {}
 
 export const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
-  (error) => `A value ${error.value} is not trimmed`,
+  (error) => `The value ${error.value} must be trimmed.`,
 );
 
-export type TransformBrandFactory<
-  Name extends TypeName,
-  Input,
-  TransformError extends TypeError = never,
-> = <
-  PName extends TypeName,
-  P extends Input,
-  PInput,
-  PParent,
-  PError extends TypeError = never,
-  PParentError extends TypeError = never,
->(
-  parent: Type<PName, P, PInput, PError, PParent, PParentError>,
-) => TransformType<
-  Type<PName, P, PInput, PError, PParent, PParentError>,
-  BrandType<
-    Type<PName, P, PInput, PError, PParent, PParentError>,
-    Name,
-    never,
-    PError | PParentError
-  >,
-  TransformError
->;
-
-/**
- * Trims leading and trailing whitespace from a string.
- *
- * This Type Factory **transforms** the input string by removing whitespace from
- * both ends. For validation only, use {@link trimmed} Type Factory.
- *
- * ### Example
- *
- * ```ts
- * const TrimString = trim(String);
- * expect(TrimString.from("a ")).toEqual(ok("a"));
- * expect(TrimString.fromParent("a ").value).toEqual("a");
- *
- * const TrimNonEmptyString = trim(NonEmptyString);
- * expect(TrimNonEmptyString.from("a " as NonEmptyString)).toEqual(ok("a"));
- * expect(
- *   TrimNonEmptyString.fromParent("a " as NonEmptyString).value,
- * ).toEqual("a");
- * ```
- *
- * **Note:** This transformation is irreversible. Calling `toParent` will not
- * restore the original representation.
- *
- * @category String
- */
-
-export const trim: TransformBrandFactory<"Trimmed", string> = (parent) =>
-  transform(
-    parent,
-    trimmed(parent) as BrandType<typeof parent, "Trimmed">,
-    (value) => ok(value.trim() as InferType<typeof parent> & Brand<"Trimmed">),
-    (value) => value,
-  );
-
 /**
  * Trimmed string
  *
@@ -1017,6 +1205,9 @@ export const trim: TransformBrandFactory<"Trimmed", string> = (parent) =>
 export const TrimmedString = trimmed(String);
 export type TrimmedString = typeof TrimmedString.Type;
 
+export const trim = (value: string): TrimmedString =>
+  value.trim() as TrimmedString;
+
 /**
  * Minimum length.
  *
@@ -1045,7 +1236,7 @@ export interface MinLengthError<Min extends number = number>
 
 export const formatMinLengthError = createTypeErrorFormatter<MinLengthError>(
   (error) =>
-    `Value ${error.value} does not meet the minimum length of ${error.min}.`,
+    `The value ${error.value} does not meet the minimum length of ${error.min}.`,
 );
 
 /**
@@ -1075,7 +1266,8 @@ export interface MaxLengthError<Max extends number = number>
 }
 
 export const formatMaxLengthError = createTypeErrorFormatter<MaxLengthError>(
-  (error) => `Value ${error.value} exceeds the maximum length of ${error.max}.`,
+  (error) =>
+    `The value ${error.value} exceeds the maximum length of ${error.max}.`,
 );
 
 /**
@@ -1108,7 +1300,7 @@ export interface LengthError<Exact extends number = number>
 
 export const formatLengthError = createTypeErrorFormatter<LengthError>(
   (error) =>
-    `Value ${error.value} does not have the required length of ${error.exact}.`,
+    `The value ${error.value} does not have the required length of ${error.exact}.`,
 );
 
 /** @category String */
@@ -1170,7 +1362,7 @@ export type Mnemonic = typeof Mnemonic.Type;
 export interface MnemonicError extends TypeError<"Mnemonic"> {}
 
 export const formatMnemonicError = createTypeErrorFormatter<MnemonicError>(
-  (error) => `Invalid BIP39 mnemonic: ${error.value}`,
+  (error) => `Invalid BIP39 mnemonic: ${error.value}.`,
 );
 
 /**
@@ -1209,13 +1401,13 @@ export interface RegexError<Name extends TypeName = TypeName>
 
 export const formatRegexError = createTypeErrorFormatter<RegexError>(
   (error) =>
-    `Value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}`,
+    `The value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}.`,
 );
 
 /**
- * URL-safe Base64 string.
+ * URL-safe string.
  *
- * A `Base64Url` string uses a limited alphabet that is URL-safe:
+ * A `UrlSafeString` uses a limited alphabet that is safe for URLs:
  *
  * - Uppercase letters (`A-Z`)
  * - Lowercase letters (`a-z`)
@@ -1223,37 +1415,117 @@ export const formatRegexError = createTypeErrorFormatter<RegexError>(
  * - Dash (`-`)
  * - Underscore (`_`)
  *
+ * This is the same character set used by Base64Url encoding, but this type does
+ * not validate that the string is actually Base64Url-encoded data.
+ *
  * ### Example
  *
  * ```ts
- * const result = Base64Url.from("abc123_-");
+ * const result = UrlSafeString.from("abc123_-");
  * if (result.ok) {
- *   console.log("Valid Base64Url string:", result.value);
+ *   console.log("Valid URL-safe string:", result.value);
  * } else {
- *   console.error("Invalid Base64Url string:", result.error);
+ *   console.error("Invalid URL-safe string:", result.error);
  * }
  * ```
  *
  * @category String
  */
-export const Base64Url = regex(
+export const UrlSafeString = regex("UrlSafeString", /^[A-Za-z0-9_-]+$/)(String);
+export type UrlSafeString = typeof UrlSafeString.Type;
+export type UrlSafeStringError = typeof UrlSafeString.Error;
+
+/**
+ * Base64Url without padding.
+ *
+ * Encode with {@link uint8ArrayToBase64Url}, decode with
+ * {@link base64UrlToUint8Array}.
+ *
+ * @category String
+ */
+export const Base64Url = brand(
   "Base64Url",
-  /^[A-Za-z0-9_-]+$/, // URL-safe Base64 alphabet
-)(String);
+  String,
+  (value: string): Result<string, Base64UrlError> => {
+    // Round-trip validation ensures consistency across different base64url
+    // implementations (Node.js Buffer, native browser API, manual fallback).
+    // Only strings that decode and encode identically are accepted.
+    let roundTrip;
+    try {
+      roundTrip = uint8ArrayToBase64Url(
+        base64UrlToUint8Array(value as Base64Url),
+      );
+    } catch {
+      //
+    }
+    return roundTrip === value
+      ? ok(value)
+      : err<Base64UrlError>({ type: "Base64Url", value });
+  },
+);
 export type Base64Url = typeof Base64Url.Type;
-export type Base64UrlError = typeof Base64Url.Error;
+export interface Base64UrlError extends TypeError<"Base64Url"> {}
+
+export const formatBase64UrlError = createTypeErrorFormatter<Base64UrlError>(
+  (error) => `The value ${error.value} is not a valid Base64Url string.`,
+);
+
+const base64UrlOptions = { alphabet: "base64url", omitPadding: true };
+
+/** Encodes a Uint8Array to a {@link Base64Url} string. */
+export const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url =
+  hasNodeBuffer
+    ? (bytes: Uint8Array) =>
+        globalThis.Buffer.from(bytes).toString("base64url") as Base64Url
+    : // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      typeof (globalThis.Uint8Array.prototype as any)?.toBase64 !== "undefined"
+      ? (bytes: Uint8Array) =>
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+          (bytes as any).toBase64(base64UrlOptions) as Base64Url
+      : (bytes: Uint8Array) => {
+          const binaryString = Array.from(bytes, (byte) =>
+            globalThis.String.fromCodePoint(byte),
+          ).join("");
+          const base64 = globalThis.btoa(binaryString);
+          return base64
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+            .replace(/=/g, "") as Base64Url;
+        };
+
+/** Decodes a {@link Base64Url} string to a Uint8Array. */
+export const base64UrlToUint8Array: (str: Base64Url) => Uint8Array =
+  hasNodeBuffer
+    ? (str: Base64Url) => {
+        const nodeBuffer = globalThis.Buffer.from(str, "base64url");
+        return new globalThis.Uint8Array(nodeBuffer);
+      }
+    : // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+      typeof (globalThis.Uint8Array as any)?.fromBase64 !== "undefined"
+      ? (str: Base64Url) =>
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+          (globalThis.Uint8Array as any).fromBase64(
+            str,
+            base64UrlOptions,
+          ) as Uint8Array
+      : (str: Base64Url) => {
+          let base64 = str.replace(/-/g, "+").replace(/_/g, "/");
+          while (base64.length % 4 !== 0) {
+            base64 += "=";
+          }
+          const binaryString = globalThis.atob(base64);
+          return globalThis.Uint8Array.from(binaryString, (c) =>
+            c.charCodeAt(0),
+          );
+        };
 
 /**
- * Simple alphanumeric string for naming.
+ * Simple alphanumeric string for naming in file systems, URLs, and identifiers.
  *
- * A `SimpleName` string uses a limited, safe alphabet for naming purposes:
+ * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
+ * `_`). See `UrlSafeString` for details.
  *
- * - Uppercase letters (`A-Z`)
- * - Lowercase letters (`a-z`)
- * - Digits (`0-9`)
- * - Dash (`-`)
- *
- * The string must be between 1 and 42 characters.
+ * The string must be between 1 and 64 characters.
  *
  * ### Example
  *
@@ -1268,22 +1540,36 @@ export type Base64UrlError = typeof Base64Url.Error;
  *
  * @category String
  */
-export const SimpleName = regex("SimpleName", /^[a-z0-9-]{1,42}$/i)(String);
+export const SimpleName = brand("SimpleName", UrlSafeString, (value) =>
+  value.length >= 1 && value.length <= 64
+    ? ok(value)
+    : err<SimpleNameError>({ type: "SimpleName", value }),
+);
 export type SimpleName = typeof SimpleName.Type;
-export type SimpleNameError = typeof SimpleName.Error;
-
-/**
- * Default NanoId.
- *
- * @category String
- */
-export const NanoId = regex("NanoId", /^[A-Za-z0-9_-]{21}$/)(String);
-export type NanoId = typeof NanoId.Type;
-export type NanoIdError = typeof NanoId.Error;
+export interface SimpleNameError extends TypeError<"SimpleName"> {}
 
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper), but with TC39 Hack
+ * pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
  * @category String
  */
 export const SimplePassword = brand(
@@ -1304,33 +1590,146 @@ export const formatSimplePasswordError = (
   );
 
 /**
- * `Id` {@link Type}.
+ * Evolu Id: 16 bytes encoded as a 22‑character Base64Url string.
  *
- * Represents a unique identifier with exactly 21 characters, using NanoID's
- * standard format (`A-Za-z0-9_-`).
+ * There are three ways to create an Evolu Id:
+ *
+ * - {@link createId} – default cryptographically secure random bytes
+ *   (privacy‑preserving)
+ * - {@link createIdFromString} – deterministic: first 16 bytes of SHA‑256 of a
+ *   string
+ * - {@link createIdAsUuidv7} – optional: embeds timestamp bits (UUID v7 layout)
+ *
+ * Privacy: the default random Id does not leak creation time and is safe to
+ * share or log. The UUID v7 variant leaks creation time anywhere the Id is
+ * copied (logs, URLs, exports); only use it when you explicitly want insertion
+ * locality for very large write‑heavy tables and accept timestamp exposure.
+ *
+ * ### Future
+ *
+ * A possible hybrid masked‑time approach (`timestamp ^ H(cluster_id, timestamp
+ *
+ * > > N)`) could provide locality without exposing raw creation time. See
+ * > > https://brooker.co.za/blog/2025/10/22/uuidv7.html
  *
  * @category String
  */
-export const Id = regex("Id", /^[A-Za-z0-9_-]{21}$/)(String);
+export const Id = brand("Id", String, (value) =>
+  value.length === 22 && Base64Url.fromParent(value).ok
+    ? ok(value)
+    : err<IdError>({ type: "Id", value }),
+);
 export type Id = typeof Id.Type;
 
-export const idTypeValueLength = 21;
+export interface IdError extends TypeError<"Id"> {}
+
+export const formatIdError = createTypeErrorFormatter<IdError>(
+  (error) => `The value ${error.value} is not a valid Id.`,
+);
 
 /**
- * Creates an {@link Id}.
+ * Creates a random {@link Id}. This is the recommended default.
+ *
+ * Use {@link createIdFromString} for deterministic mapping of external IDs or
+ * {@link createIdAsUuidv7} when you accept timestamp leakage for index
+ * locality.
  *
  * ### Example
  *
  * ```ts
- * // string & Brand<"Id">
  * const id = createId(deps);
+ * const todoId = createId<"Todo">(deps);
+ * ```
+ */
+export const createId = <B extends string = never>(
+  deps: RandomBytesDep,
+): [B] extends [never] ? Id : Id & Brand<B> => {
+  const id = uint8ArrayToBase64Url(deps.randomBytes.create(16));
+  return id as unknown as [B] extends [never] ? Id : Id & Brand<B>;
+};
+
+/**
+ * Creates an {@link Id} from a string using SHA-256.
+ *
+ * When integrating with external systems that use different ID formats, use
+ * this function to convert external IDs into valid Evolu IDs.
+ *
+ * In Evolu's CRDT, the ID serves as the unique identifier for conflict
+ * resolution across distributed clients. When multiple clients create records
+ * with the same external identifier, they must resolve to the same Evolu ID to
+ * ensure data consistency.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Both clients will generate the same ID
+ * const id1 = createIdFromString("user-api-123");
+ * const id2 = createIdFromString("user-api-123");
+ * console.log(id1 === id2); // true
+ *
+ * upsert("todo", {
+ *   id: createIdFromString("external-todo-456"),
+ *   title: "Synced from external system",
+ * });
  * ```
+ *
+ * **Important**: This transformation uses the first 16 bytes of SHA-256 hash of
+ * the string bytes, therefore it's not possible to recover the original
+ * external string from the generated {@link Id}. If you need to preserve the
+ * original external ID, store it in a separate column.
+ *
+ * @category String
  */
-export const createId = (deps: NanoIdLibDep): Id =>
-  deps.nanoIdLib.nanoid() as Id;
+export const createIdFromString = <B extends string = never>(
+  value: string,
+): [B] extends [never] ? Id : Id & Brand<B> => {
+  const hash = sha256(utf8ToBytes(value));
+  // Take first 16 bytes of hash and convert to Id
+  const id = idBytesToId(hash.slice(0, 16) as IdBytes);
+
+  return id as [B] extends [never] ? Id : Id & Brand<B>;
+};
+
+/**
+ * Creates an {@link Id} embedding timestamp bits (UUID v7 layout) before
+ * Base64Url encoding.
+ *
+ * Tradeoff: better insertion locality / index performance for huge datasets vs
+ * leaking creation time everywhere the Id appears. Evolu uses {@link createId}
+ * by default to avoid activity leakage; choose this only if you explicitly
+ * accept timestamp exposure.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const id = createIdAsUuidv7({ randomBytes, time });
+ * const todoId = createIdAsUuidv7<"Todo">({ randomBytes, time });
+ * ```
+ */
+export const createIdAsUuidv7 = <B extends string = never>(
+  deps: RandomBytesDep & TimeDep,
+): [B] extends [never] ? Id : Id & Brand<B> => {
+  const id = deps.randomBytes.create(16);
+
+  const timestamp = globalThis.BigInt(deps.time.now());
+
+  id[0] = globalThis.Number((timestamp >> 40n) & 0xffn);
+  id[1] = globalThis.Number((timestamp >> 32n) & 0xffn);
+  id[2] = globalThis.Number((timestamp >> 24n) & 0xffn);
+  id[3] = globalThis.Number((timestamp >> 16n) & 0xffn);
+  id[4] = globalThis.Number((timestamp >> 8n) & 0xffn);
+  id[5] = globalThis.Number(timestamp & 0xffn);
+
+  id[6] = (id[6] & 0x0f) | 0x70;
+  id[8] = (id[8] & 0x3f) | 0x80;
+
+  return id as unknown as [B] extends [never] ? Id : Id & Brand<B>;
+};
 
 /**
- * Type Factory to create branded {@link Id} Type for a specific table.
+ * Creates a branded {@link Id} Type for a table's primary key.
+ *
+ * The table name becomes an additional brand for type safety.
  *
  * ### Example
  *
@@ -1342,55 +1741,64 @@ export const createId = (deps: NanoIdLibDep): Id =>
  *
  * @category String
  */
-export const id = <Table extends TypeName>(table: Table): IdType<Table> => {
+export const id = <Table extends TypeName>(table: Table): TableId<Table> => {
+  const fromUnknown = (value: unknown) => {
+    const parentResult = String.fromUnknown(value);
+    if (!parentResult.ok) return parentResult;
+    return fromParent(parentResult.value);
+  };
+
   const fromParent = (value: string) => {
     const idResult = Id.fromParent(value);
     if (!idResult.ok) {
-      return err<IdError<Table>>({ type: "Id", value, table });
+      return err<TableIdError<Table>>({ type: "TableId", value, table });
     }
     return ok(idResult.value as Id & Brand<Table>);
   };
 
-  const fromUnknown = (value: unknown) => {
-    const parentResult = String.fromUnknown(value);
-    if (!parentResult.ok) return parentResult;
-    return fromParent(parentResult.value);
-  };
-
   return {
-    ...createType("Id", {
-      fromUnknown,
-      to: (value: Id & Brand<Table>) => value as string,
-      fromParent,
-      toParent: (value: Id & Brand<Table>) => value as string,
-    }),
+    ...createType("Id", { fromUnknown, fromParent }),
     table,
   };
 };
 
-export interface IdType<Table extends TypeName>
+export interface TableId<Table extends TypeName>
   extends Type<
     "Id",
     string & Brand<"Id"> & Brand<Table>,
     string,
-    IdError<Table>,
+    TableIdError<Table>,
     string,
     StringError
   > {
   table: Table;
 }
 
-export interface IdError<Table extends TypeName = TypeName>
-  extends TypeError<"Id"> {
+export interface TableIdError<Table extends TypeName = TypeName>
+  extends TypeError<"TableId"> {
   readonly table: Table;
 }
 
-export const formatIdError = createTypeErrorFormatter<IdError>(
-  (error) => `Invalid ${error.type} table Id: ${error.value}`,
+export const formatTableIdError = createTypeErrorFormatter<TableIdError>(
+  (error) => `Invalid Id for table ${error.table}: ${error.value}.`,
 );
 
+/** Binary representation of an {@link Id}. */
+export const IdBytes = brand("IdBytes", length(16)(Uint8Array));
+export type IdBytes = typeof IdBytes.Type;
+
+export const idBytesTypeValueLength = 16 as NonNegativeInt;
+
+export const idToIdBytes = (id: Id): IdBytes =>
+  // Id is Base64Url (validated by Id.from), cast is safe
+  base64UrlToUint8Array(id as unknown as Base64Url) as IdBytes;
+
+export const idBytesToId = (idBytes: IdBytes): Id =>
+  // Base64Url encoding of 16 bytes always produces valid Id (22 chars)
+  uint8ArrayToBase64Url(idBytes) as unknown as Id;
+
 /**
- * Positive number.
+ * Positive number (> 0).
  *
  * ### Example
  *
@@ -1413,11 +1821,11 @@ export const positive: BrandFactory<"Positive", number, PositiveError> = (
 export interface PositiveError extends TypeError<"Positive"> {}
 
 export const formatPositiveError = createTypeErrorFormatter<PositiveError>(
-  (error) => `The value ${error.value} is not positive.`,
+  (error) => `The value ${error.value} must be positive (> 0).`,
 );
 
 /**
- * Negative number.
+ * Negative number (< 0).
  *
  * ### Example
  *
@@ -1437,11 +1845,11 @@ export const negative: BrandFactory<"Negative", number, NegativeError> = (
 export interface NegativeError extends TypeError<"Negative"> {}
 
 export const formatNegativeError = createTypeErrorFormatter<NegativeError>(
-  (error) => `The value ${error.value} is not negative.`,
+  (error) => `The value ${error.value} must be negative (< 0).`,
 );
 
 /**
- * Non-positive number.
+ * Non-positive number (≤ 0).
  *
  * ### Example
  *
@@ -1466,11 +1874,11 @@ export interface NonPositiveError extends TypeError<"NonPositive"> {}
 
 export const formatNonPositiveError =
   createTypeErrorFormatter<NonPositiveError>(
-    (error) => `The value ${error.value} is not non-positive.`,
+    (error) => `The value ${error.value} must be non-positive (≤ 0).`,
   );
 
 /**
- * Non-negative number.
+ * Non-negative number (≥ 0).
  *
  * ### Example
  *
@@ -1495,22 +1903,38 @@ export interface NonNegativeError extends TypeError<"NonNegative"> {}
 
 export const formatNonNegativeError =
   createTypeErrorFormatter<NonNegativeError>(
-    (error) => `The value ${error.value} is not non-negative.`,
+    (error) => `The value ${error.value} must be non-negative (≥ 0).`,
   );
 
-/** @category Number */
+/**
+ * Non-negative number (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeNumber = nonNegative(Number);
 export type NonNegativeNumber = typeof NonNegativeNumber.Type;
 
-/** @category Number */
+/**
+ * Positive number (> 0).
+ *
+ * @category Number
+ */
 export const PositiveNumber = positive(NonNegativeNumber);
 export type PositiveNumber = typeof PositiveNumber.Type;
 
-/** @category Number */
+/**
+ * Non-positive number (≤ 0).
+ *
+ * @category Number
+ */
 export const NonPositiveNumber = nonPositive(Number);
 export type NonPositiveNumber = typeof NonPositiveNumber.Type;
 
-/** @category Number */
+/**
+ * Negative number (< 0).
+ *
+ * @category Number
+ */
 export const NegativeNumber = negative(NonPositiveNumber);
 export type NegativeNumber = typeof NegativeNumber.Type;
 
@@ -1535,7 +1959,7 @@ export const int: BrandFactory<"Int", number, IntError> = (parent) =>
 export interface IntError extends TypeError<"Int"> {}
 
 export const formatIntError = createTypeErrorFormatter<IntError>(
-  (error) => `The value ${error.value} is not an integer.`,
+  (error) => `The value ${error.value} must be an integer.`,
 );
 
 /**
@@ -1546,19 +1970,40 @@ export const formatIntError = createTypeErrorFormatter<IntError>(
 export const Int = int(Number);
 export type Int = typeof Int.Type;
 
-/** @category Number */
+/**
+ * Non-negative integer (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeInt = nonNegative(Int);
 export type NonNegativeInt = typeof NonNegativeInt.Type;
 
-/** @category Number */
+/**
+ * Positive integer (> 0).
+ *
+ * @category Number
+ */
 export const PositiveInt = positive(NonNegativeInt);
 export type PositiveInt = typeof PositiveInt.Type;
 
-/** @category Number */
+/** Maximum safe positive integer value for practically infinite operations. */
+export const maxPositiveInt = PositiveInt.orThrow(
+  globalThis.Number.MAX_SAFE_INTEGER,
+);
+
+/**
+ * Non-positive integer (≤ 0).
+ *
+ * @category Number
+ */
 export const NonPositiveInt = nonPositive(Int);
 export type NonPositiveInt = typeof NonPositiveInt.Type;
 
-/** @category Number */
+/**
+ * Negative integer (< 0).
+ *
+ * @category Number
+ */
 export const NegativeInt = negative(NonPositiveInt);
 export type NegativeInt = typeof NegativeInt.Type;
 
@@ -1676,7 +2121,7 @@ export const nonNaN: BrandFactory<"NonNaN", number, NonNaNError> = (parent) =>
 export interface NonNaNError extends TypeError<"NonNaN"> {}
 
 export const formatNonNaNError = createTypeErrorFormatter<NonNaNError>(
-  (error) => `The value ${error.value} is NaN (not a number).`,
+  () => `The value must not be NaN.`,
 );
 
 /** @category Number */
@@ -1698,7 +2143,7 @@ export const finite: BrandFactory<"Finite", number, FiniteError> = (parent) =>
 export interface FiniteError extends TypeError<"Finite"> {}
 
 export const formatFiniteError = createTypeErrorFormatter<FiniteError>(
-  (error) => `The value ${error.value} is not finite.`,
+  (error) => `The value ${error.value} must be finite.`,
 );
 
 /**
@@ -1778,195 +2223,54 @@ export const formatBetweenError = createTypeErrorFormatter<BetweenError>(
     `The value ${error.value} is not between ${error.min} and ${error.max}, inclusive.`,
 );
 
-/** @category Number */
-export const Between1And10 = between(1, 10)(Number);
-export type Between1And10 = typeof Between1And10.Type;
-
 /**
  * Literal {@link Type}.
  *
- * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
- *
- * ### Example
- *
- * ```ts
- * const LiteralHello = literal("Hello");
- * const result = LiteralHello.from("Hello"); // ok("Hello")
- * const errorResult = LiteralHello.from("World"); // err
- * ```
- *
- * TODO: Add JsonValue
- *
- * @category Base Factories
- */
-export const literal = <T extends Literal>(expected: T): LiteralType<T> => {
-  const fromUnknown = (value: unknown): Result<T, LiteralError<T>> =>
-    value === expected
-      ? ok(expected)
-      : err<LiteralError<T>>({ type: "Literal", value, expected });
-
-  return {
-    ...createType("Literal", {
-      fromUnknown,
-      to: identity as (value: T) => WidenLiteral<T>,
-      fromParent: ok,
-      toParent: identity,
-    }),
-    expected,
-  };
-};
-
-export interface LiteralType<T extends Literal>
-  extends Type<"Literal", T, WidenLiteral<T>, LiteralError<T>> {
-  expected: T;
-}
-
-export interface LiteralError<T extends Literal = Literal>
-  extends TypeError<"Literal"> {
-  readonly expected: T;
-}
-
-export const formatLiteralError = createTypeErrorFormatter<LiteralError>(
-  (error) =>
-    `The value ${error.value} is not strictly equal to the expected literal: ${globalThis.String(
-      error.expected,
-    )}.`,
-);
-
-/**
- * {@link Type} that transforms values between `FromType` and `ToType`.
- *
- * - `fromParent`: Converts `FromType` to `ToType`, may fail.
- * - `toParent`: Converts `ToType` back to `FromType`, must not fail.
- *
- * ### Example
- *
- * // TODO: Examples
- *
- * @category Base Factories
- */
-export const transform = <
-  FromType extends AnyType,
-  ToType extends AnyType,
-  TransformError extends TypeError = never,
->(
-  fromType: FromType,
-  toType: ToType,
-  fromParent: (
-    parentValue: InferType<FromType>,
-  ) => Result<InferType<ToType>, TransformError>,
-  toParent: (value: InferType<ToType>) => InferType<FromType>,
-): TransformType<FromType, ToType, TransformError> => {
-  const fromUnknown = (
-    value: unknown,
-  ): Result<InferType<ToType>, InferErrors<FromType> | TransformError> => {
-    const parentResult = fromType.fromUnknown(value);
-    if (!parentResult.ok) return parentResult;
-    return fromParent(parentResult.value as IntentionalNever);
-  };
-
-  const to = (value: InferType<ToType>): InferInput<FromType> =>
-    fromType.to(toParent(value)) as IntentionalNever;
-
-  return {
-    ...createType("Transform", {
-      fromUnknown,
-      to,
-      fromParent,
-      toParent,
-    }),
-    is: toType.is,
-    fromType,
-    toType,
-  } as TransformType<FromType, ToType, TransformError>;
-};
-
-/**
- * TransformType extends {@link Type} with additional `fromType` and `toType`
- * properties for reflection.
- */
-export interface TransformType<
-  FromType extends AnyType,
-  ToType extends AnyType,
-  TransformError extends TypeError = never,
-> extends Type<
-    "Transform",
-    InferType<ToType>,
-    InferInput<FromType>,
-    TransformError,
-    InferType<FromType>,
-    InferErrors<FromType>
-  > {
-  readonly fromType: FromType;
-  readonly toType: ToType;
-
-  readonly fromParent: (
-    value: InferType<FromType>,
-  ) => [TransformError] extends [never]
-    ? Ok<InferType<ToType>>
-    : Result<InferType<ToType>, TransformError>;
-}
-
-/**
- * Trims leading and trailing whitespace from a string.
- *
- * ### Example
- *
- * ```ts
- * expect(TrimString.from("a ")).toEqual(ok("a"));
- * expect(TrimString.fromParent("a ").value).toEqual("a");
- * ```
- *
- * @category String
- */
-export const TrimString = trim(String);
-
-/**
- * Transforms a {@link Date} into a {@link DateIsoString} string and vice versa.
- *
- * ### Example
- *
- * TODO:
- *
- * @category String
- */
-export const DateIso = transform(
-  Date,
-  DateIsoString,
-  (value) => DateIsoString.fromParent(value.toISOString()),
-  (value) => new globalThis.Date(value),
-);
-
-/**
- * Transforms a {@link NonEmptyTrimmedString} into a {@link FiniteNumber}.
- *
+ * https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types
+ *
  * ### Example
  *
  * ```ts
- * NumberFromString.from("42"); // ok(42)
- * NumberFromString.from("abc"); // err({ type: "NumberFromString", value: "abc" })
+ * const LiteralHello = literal("Hello");
+ * const result = LiteralHello.from("Hello"); // ok("Hello")
+ * const errorResult = LiteralHello.from("World"); // err
  * ```
  *
- * @category Number
+ * TODO: Add JsonValue
+ *
+ * @category Base Factories
  */
-export const NumberFromString = transform(
-  NonEmptyTrimmedString,
-  FiniteNumber,
-  (value) => {
-    const result = FiniteNumber.fromParent(globalThis.Number(value));
-    if (!result.ok)
-      return err<NumberFromStringError>({ type: "NumberFromString", value });
-    return result;
-  },
-  (num) => num.toString() as NonEmptyTrimmedString,
-);
+export const literal = <T extends Literal>(expected: T): LiteralType<T> => {
+  const fromUnknown = (value: unknown): Result<T, LiteralError<T>> =>
+    value === expected
+      ? ok(expected)
+      : err<LiteralError<T>>({ type: "Literal", value, expected });
 
-export interface NumberFromStringError extends TypeError<"NumberFromString"> {}
+  return {
+    ...createType("Literal", {
+      fromUnknown,
+      fromParent: ok,
+    }),
+    expected,
+  } as LiteralType<T>;
+};
 
-export const formatNumberFromStringError =
-  createTypeErrorFormatter<NumberFromStringError>((error) => {
-    return `The value ${error.value} could not be converted to a finite number.`;
-  });
+export interface LiteralType<T extends Literal>
+  extends Type<"Literal", T, WidenLiteral<T>, LiteralError<T>> {
+  expected: T;
+}
+
+export interface LiteralError<T extends Literal = Literal>
+  extends TypeError<"Literal"> {
+  readonly expected: T;
+}
+
+export const formatLiteralError = createTypeErrorFormatter<LiteralError>(
+  (error) =>
+    `The value ${error.value} is not strictly equal to the expected literal: ${globalThis.String(
+      error.expected,
+    )}.`,
+);
 
 /**
  * Array of a specific {@link Type}.
@@ -2020,9 +2324,6 @@ export const array = <ElementType extends AnyType>(
     return ok(result);
   };
 
-  const to = (value: ReadonlyArray<InferType<ElementType>>) =>
-    value.map(element.to) as ReadonlyArray<InferInput<ElementType>>;
-
   const fromParent = (
     value: ReadonlyArray<InferParent<ElementType>>,
   ): Result<
@@ -2048,18 +2349,10 @@ export const array = <ElementType extends AnyType>(
     return ok(result);
   };
 
-  const toParent = (values: ReadonlyArray<InferType<ElementType>>) =>
-    values.map(element.toParent) as ReadonlyArray<InferParent<ElementType>>;
-
   return {
-    ...createType("Array", {
-      fromUnknown,
-      to,
-      fromParent,
-      toParent,
-    }),
+    ...createType("Array", { fromUnknown, fromParent }),
     element,
-  } as ArrayType<ElementType>;
+  };
 };
 
 /** ArrayType extends Type with an additional `element` property for reflection. */
@@ -2192,16 +2485,6 @@ export const record = <
     return ok(result);
   };
 
-  const to = (
-    value: Readonly<Record<KeyT, InferType<Value>>>,
-  ): Readonly<Record<KeyInput, InferInput<Value>>> =>
-    Object.fromEntries(
-      Object.entries(value).map(([key, val]) => [
-        keyType.to(key as KeyT),
-        valueType.to(val),
-      ]),
-    ) as Readonly<Record<KeyInput, InferInput<Value>>>;
-
   const fromParent = (
     value: Readonly<Record<KeyParent, InferParent<Value>>>,
   ): Result<
@@ -2246,22 +2529,10 @@ export const record = <
     return ok(result);
   };
 
-  const toParent = (
-    value: Readonly<Record<KeyT, InferType<Value>>>,
-  ): Readonly<Record<KeyParent, InferParent<Value>>> =>
-    Object.fromEntries(
-      Object.entries(value).map(([key, val]) => [
-        keyType.toParent(key as KeyT),
-        valueType.toParent(val),
-      ]),
-    ) as Readonly<Record<KeyParent, InferParent<Value>>>;
-
   return {
     ...createType("Record", {
       fromUnknown,
-      to,
       fromParent,
-      toParent,
     }),
     key: keyType,
     value: valueType,
@@ -2561,25 +2832,6 @@ export function object(
     return ok(result);
   };
 
-  const to = (value: any) => {
-    const entries: [string, any][] = [];
-    for (const key of propKeys) {
-      if (!(key in value) && isOptionalType(props[key])) {
-        continue;
-      }
-      entries.push([key, props[key].to(value[key])]);
-    }
-    if (record) {
-      const recordEntries = Object.entries(value).filter(
-        ([key]) => !propKeys.includes(key),
-      );
-      for (const [key, val] of recordEntries) {
-        entries.push([record.key.to(key), record.value.to(val)]);
-      }
-    }
-    return Object.fromEntries(entries);
-  };
-
   const fromParent = (value: any): Result<any, any> => {
     const errors: Record<string, any> = {};
     const result: Record<string, any> = {};
@@ -2631,31 +2883,10 @@ export function object(
     return ok(result);
   };
 
-  const toParent = (value: any) => {
-    const entries: [string, any][] = [];
-    for (const key of propKeys) {
-      if (!(key in value) && isOptionalType(props[key])) {
-        continue;
-      }
-      entries.push([key, props[key].toParent(value[key])]);
-    }
-    if (record) {
-      const recordEntries = Object.entries(value).filter(
-        ([key]) => !propKeys.includes(key),
-      );
-      for (const [key, val] of recordEntries) {
-        entries.push([record.key.toParent(key), record.value.toParent(val)]);
-      }
-    }
-    return Object.fromEntries(entries);
-  };
-
   return {
     ...createType(record ? "ObjectWithRecord" : "Object", {
       fromUnknown,
-      to,
       fromParent,
-      toParent,
     }),
     props,
     ...(record ? { record } : {}),
@@ -2897,7 +3128,6 @@ export function union(...args: ReadonlyArray<any>): any {
    *         cases.
    */
 
-  /* eslint-disable */
   const members = args.map((arg) => (isType(arg) ? arg : literal(arg)));
 
   const fromUnknown = (value: unknown) => {
@@ -2915,23 +3145,13 @@ export function union(...args: ReadonlyArray<any>): any {
     });
   };
 
-  const to = (value: any) => {
-    for (const member of members) {
-      if (member.is(value)) return member.to(value);
-    }
-    assert(false, "No matching member found in Union Type `to` function");
-  };
-
   return {
     ...createType("Union", {
       fromUnknown,
-      to,
       fromParent: fromUnknown,
-      toParent: to,
     }),
     members,
   };
-  /* eslint-enable */
 }
 
 /**
@@ -3025,20 +3245,10 @@ export const recursive = <ParentType extends AnyType>(
       type ??= create();
       return type.fromUnknown(value);
     },
-    to: (value: T) => {
-      type ??= create();
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-      return type.to(value);
-    },
     fromParent: (value: Parent) => {
       type ??= create();
       return type.fromParent(value);
     },
-    toParent: (value: T) => {
-      type ??= create();
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-      return type.toParent(value);
-    },
     is: (value: unknown): value is T => {
       type ??= create();
       return type.is(value);
@@ -3176,9 +3386,6 @@ export const tuple = <Elements extends [AnyType, ...ReadonlyArray<AnyType>]>(
     return ok(result);
   };
 
-  const to = (value: { [K in keyof Elements]: InferType<Elements[K]> }) =>
-    value.map((val, index) => elements[index].to(val) as IntentionalNever);
-
   const fromParent = (value: {
     [K in keyof Elements]: InferParent<Elements[K]>;
   }) => {
@@ -3210,21 +3417,10 @@ export const tuple = <Elements extends [AnyType, ...ReadonlyArray<AnyType>]>(
     return ok(result as { [K in keyof Elements]: InferType<Elements[K]> });
   };
 
-  const toParent = (value: { [K in keyof Elements]: InferType<Elements[K]> }): {
-    [K in keyof Elements]: InferParent<Elements[K]>;
-  } =>
-    value.map(
-      (val, index) => elements[index].toParent(val) as IntentionalNever,
-    ) as {
-      [K in keyof Elements]: InferParent<Elements[K]>;
-    };
-
   return {
     ...createType("Tuple", {
       fromUnknown,
-      to,
       fromParent,
-      toParent,
     }),
     elements,
   } as IntentionalNever;
@@ -3300,37 +3496,21 @@ export const formatInt64Error = createTypeErrorFormatter<Int64Error>(
     `The value ${error.value} is not a valid 64-bit signed integer (Int64).`,
 );
 
-export const BigIntFromString = transform(
-  String,
-  BigInt,
-  (value) =>
-    trySync(
-      () => globalThis.BigInt(value),
-      (): BigIntFromStringError => ({ type: "BigIntFromString", value }),
-    ),
-  (value) => value.toString(),
-);
-
-export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {}
-
-export const formatBigIntFromStringError =
-  createTypeErrorFormatter<BigIntFromStringError>(
-    (error) => `The value ${error.value} could not be converted to a BigInt.`,
-  );
-
 /**
  * Stringified {@link Int64}.
  *
- * @category Number
+ * @category String
  */
-export const Int64String = brand("Int64", String, (value) => {
-  const bigint = BigIntFromString.fromParent(value);
-  if (bigint.ok) {
-    const int64 = Int64.fromParent(globalThis.BigInt(value));
-    if (int64.ok) return ok(value);
-  }
-  return err<Int64StringError>({ type: "Int64String", value });
-});
+export const Int64String = brand("Int64", NonEmptyTrimmedString, (value) =>
+  trySync(
+    () => {
+      const maybeInt = globalThis.BigInt(value);
+      Int64.orThrow(maybeInt);
+      return value;
+    },
+    (): Int64StringError => ({ type: "Int64String", value }),
+  ),
+);
 
 export type Int64String = typeof Int64String.Type;
 
@@ -3435,42 +3615,14 @@ export const JsonArray = array(JsonValue);
  */
 export const JsonObject = record(String, JsonValue);
 
-/**
- * Transform Type that parses a JSON into a {@link JsonValue} and serializes a
- * JsonValue back into a JSON string.
- *
- * ### Example
- *
- * ```ts
- * JsonValueFromString.from(`{"key":"value"}`); // -> ok({ key: "value" })
- * JsonValueFromString.to({ key: "value" }); // -> '{"key":"value"}'
- * ```
- *
- * @category String
- */
-export const JsonValueFromString = transform(
-  String,
-  JsonValue,
-  (value) =>
-    trySync(
-      () => JSON.parse(value) as JsonValue,
-      (error): JsonValueFromStringError => ({
-        type: `JsonValueFromString`,
-        value,
-        message: globalThis.String(error),
-      }),
-    ),
-  (value) => JSON.stringify(value),
-);
-
-export interface JsonValueFromStringError
-  extends TypeError<"JsonValueFromString"> {
-  readonly message: string;
-}
-
-export const formatJsonValueFromStringError =
-  createTypeErrorFormatter<JsonValueFromStringError>(
-    (error) => `Invalid JSONValue: ${error.value}. Error: ${error.message}`,
+export const parseJson = (value: string): Result<JsonValue, JsonError> =>
+  trySync(
+    () => JSON.parse(value) as JsonValue,
+    (error): JsonError => ({
+      type: `Json`,
+      value,
+      message: globalThis.String(error),
+    }),
   );
 
 /**
@@ -3479,20 +3631,15 @@ export const formatJsonValueFromStringError =
  * ### Example
  *
  * ```ts
- * const result = Json.from('{"key":"value"}'); // -> ok('{"key":"value"}')
- * const error = Json.from("invalid json"); // -> err({ type: "Json", value: "invalid json", message: "Unexpected token i in JSON at position 0" })
+ * const result = Json.from('{"key":"value"}'); // ok
+ * const error = Json.from("invalid json"); // err
  * ```
  *
  * @category String
  */
 export const Json = brand("Json", String, (value) => {
-  const result = JsonValueFromString.fromParent(value);
-  if (!result.ok)
-    return err<JsonError>({
-      type: "Json",
-      value,
-      message: result.error.message,
-    });
+  const result = parseJson(value);
+  if (!result.ok) return result;
   return ok(value);
 });
 
@@ -3506,6 +3653,80 @@ export const formatJsonError = createTypeErrorFormatter<JsonError>(
   (error) => `Invalid JSON: ${error.value}. Error: ${error.message}`,
 );
 
+export const jsonValueToJson = (value: JsonValue): Json =>
+  JSON.stringify(value) as Json;
+
+export const jsonToJsonValue = (value: Json): JsonValue =>
+  JSON.parse(value) as JsonValue;
+
+/**
+ * Creates a branded JSON string {@link Type} and type-safe conversion functions
+ * for a given Type.
+ *
+ * This factory creates:
+ *
+ * 1. A branded string Type that validates JSON parsing and structural conformity
+ * 2. A serialization function (Type → branded JSON string)
+ * 3. A parsing function (branded JSON string → Type, skipping validation)
+ *
+ * Optimized for Evolu's SQLite workflow where we store typed JSON strings and
+ * need type-safe conversions without double parsing.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const Person = object({
+ *   name: NonEmptyString100,
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
+ *
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * // Usage:
+ * const person: Person = { name: "Alice", age: 30 };
+ * const jsonString = personToPersonJson(person); // PersonJson
+ * const backToPerson = personJsonToPerson(jsonString); // Person
+ * ```
+ */
+export const json = <T extends AnyType, Name extends TypeName>(
+  type: T,
+  name: Name,
+): [
+  BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>,
+  (
+    value: InferType<T>,
+  ) => InferType<
+    BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>
+  >,
+  (
+    value: InferType<
+      BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>
+    >,
+  ) => InferType<T>,
+] => {
+  const BrandedJsonType = brand(name, String, (value) => {
+    const parseResult = parseJson(value);
+    if (!parseResult.ok) return parseResult;
+
+    const validationResult = type.fromUnknown(parseResult.value);
+    if (!validationResult.ok) return validationResult;
+
+    return ok(value);
+  }) as BrandType<typeof String, Name, JsonError | InferErrors<T>, StringError>;
+
+  return [
+    BrandedJsonType,
+    jsonValueToJson as IntentionalNever,
+    jsonToJsonValue as IntentionalNever,
+  ];
+};
+
 /**
  * Optional {@link Type}.
  *
@@ -3530,9 +3751,7 @@ export const formatJsonError = createTypeErrorFormatter<JsonError>(
 export const optional = <T extends AnyType>(type: T): OptionalType<T> => ({
   ...createType("Optional", {
     fromUnknown: type.fromUnknown,
-    to: type.to,
     fromParent: type.fromParent,
-    toParent: type.toParent,
   }),
   parent: type,
 });
@@ -3556,7 +3775,7 @@ export const isOptionalType = (x: unknown): x is OptionalType<any> =>
 /**
  * Creates a partial object type where all properties are optional.
  *
- * This is useful when you want to validate an object in which none of the keys
+ * This is useful when we want to validate an object in which none of the keys
  * are required, but if they are present they must conform to their
  * corresponding Types.
  *
@@ -3661,68 +3880,39 @@ export function omit<T extends ObjectType<any>, Keys extends keyof T["props"]>(
   return object(newProps);
 }
 
+export const maxMutationSize = 655360;
+
 /**
- * Creates a transform Type that serializes a given `Type` into a branded JSON
- * string. The transformation is reversible, ensuring that we can safely parse
- * it back.
- *
- * ### Example
- *
- * ```ts
- * const Person = object({
- *   name: NonEmptyString50,
- *   age: FiniteNumber,
- * });
- * type Person = typeof Person.Type;
- *
- * const PersonJson = json(Person, "PersonJson");
- * // string & Brand<"PersonJson">
- * type PersonJson = typeof PersonJson.Type;
- *
- * // Person -> string & Brand<"PersonJson">
- * const personJson = PersonJson.from({ name: "Alice", age: 30 });
- * expect(personJson).toEqual(ok('{"name":"Alice","age":30}'));
- *
- * // string & Brand<"PersonJson"> -> Person
- * const person = PersonJson.to(personJson);
- *
- * // serialize/parse any JSON value
- * const AnyJson = json(JsonValue, "AnyJson");
- * ```
+ * Evolu has to limit the maximum mutation size. Otherwise, sync couldn't use
+ * the `maxProtocolMessageRangesSize`. The max size is 640KB in bytes, measured
+ * via MessagePack. Evolu Protocol DbChange will be smaller thanks to various
+ * optimizations.
  */
-export const json = <T extends AnyType, Name extends TypeName>(
+export const validMutationSize = <T extends AnyType>(
   type: T,
-  name: Name,
-): TransformType<
-  T,
-  BrandType<
-    typeof String,
-    Name,
-    JsonValueFromStringError | T["Errors"],
-    StringError
-  >
-> => {
-  type E = JsonValueFromStringError | T["Errors"];
-
-  const BrandedJsonString: BrandType<typeof String, Name, E, StringError> =
-    brand(name, String, (value) => {
-      const jsonValue = JsonValueFromString.fromParent(value);
-      if (!jsonValue.ok) return jsonValue as Err<E>;
-
-      const parsed = type.fromUnknown(jsonValue.value);
-      if (!parsed.ok) return parsed as Err<E>;
+): BrandType<T, "ValidMutationSize", ValidMutationSizeError, InferErrors<T>> =>
+  brand("ValidMutationSize", type, (value) =>
+    pack(value).byteLength <= maxMutationSize
+      ? ok(value)
+      : err<ValidMutationSizeError>({ type: "ValidMutationSize", value }),
+  );
 
-      return ok(value as InferType<typeof BrandedJsonString>);
-    });
+export interface ValidMutationSizeError
+  extends TypeError<"ValidMutationSize"> {}
 
-  return transform(
-    type,
-    BrandedJsonString,
-    (value) => ok(JSON.stringify(value) as InferType<typeof BrandedJsonString>),
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    (value) => JSON.parse(value) as InferType<T>,
+export const formatValidMutationSizeError =
+  createTypeErrorFormatter<ValidMutationSizeError>(
+    (error) =>
+      `The mutation size exceeds the maximum limit of ${maxMutationSize} bytes. The provided mutation has a size of ${pack(error.value).byteLength} bytes.`,
   );
-};
+
+export type ValidMutationSize<Props extends Record<string, AnyType>> =
+  BrandType<
+    ObjectType<Props>,
+    "ValidMutationSize",
+    ValidMutationSizeError,
+    InferErrors<ObjectType<Props>>
+  >;
 
 /**
  * Union of all `TypeError`s defined in the `Type.ts` file, including base type
@@ -3749,16 +3939,16 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | InstanceOfError
   | EvoluTypeError
   | CurrencyCodeError
-  | DateIsoStringError
+  | DateIsoError
   | TrimmedError
   | MinLengthError
   | MaxLengthError
   | LengthError
   | MnemonicError
   | RegexError
-  | NanoIdError
   | SimplePasswordError
   | IdError
+  | TableIdError
   | PositiveError
   | NegativeError
   | NonPositiveError
@@ -3774,10 +3964,9 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | BetweenError
   | LiteralError
   | Int64Error
-  | BigIntFromStringError
   | Int64StringError
-  | JsonValueFromStringError
   | JsonError
+  | ValidMutationSizeError
   | ExtraErrors
   // Composite errors
   | ArrayError<TypeErrors<ExtraErrors>>
@@ -3792,70 +3981,74 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | TupleError<TypeErrors<ExtraErrors>>;
 
 /**
- * Creates a unified error formatter that handles both Evolu Type's built-in
- * {@link TypeErrors} and custom errors. It also lets us override the default
- * formatting for specific errors.
+ * Formats Evolu Type errors into user-friendly messages.
  *
- * If you prefer not to reuse any built-in error formatters, you can write your
- * own `formatTypeError` function from scratch.
+ * Evolu Type typed errors ensure every error type must have a formatter.
+ * TypeScript enforces this at compile-time, preventing unhandled validation
+ * errors from reaching users.
  *
- * ### Examples
+ * The `createFormatTypeError` function handles both built-in {@link TypeErrors}
+ * and custom errors, and lets us override default formatting for specific
+ * errors.
+ *
+ * ### Example
  *
  * ```ts
- * const formatError = createFormatTypeError();
- * console.log(formatError({ type: "String", value: 42 }));
- * // "A value 42 is not a string."
+ * const formatTypeError = createFormatTypeError<
+ *   MinLengthError | MaxLengthError
+ * >((error): string => {
+ *   switch (error.type) {
+ *     case "MinLength":
+ *       return `Text must be at least ${error.min} character${error.min === 1 ? "" : "s"} long`;
+ *     case "MaxLength":
+ *       return `Text is too long (maximum ${error.max} characters)`;
+ *   }
+ * });
  * ```
  *
- * A custom `formatTypeError` function:
+ * Alternatively, write a custom formatter from scratch without using
+ * `createFormatTypeError`. This gives us full control over error formatting:
  *
  * ```ts
- * type AppErrors =
- *   | ValidMutationSizeError
+ * const Person = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ *
+ * // Define only the errors actually used by Person Type
+ * type PersonErrors =
  *   | StringError
- *   | MinLengthError
  *   | MaxLengthError
- *   | NullError
- *   | IdError
+ *   | MinLengthError
  *   | TrimmedError
- *   | MnemonicError
- *   | LiteralError
- *   // Composite errors
- *   | ObjectError<Record<string, AppErrors>>
- *   | UnionError<AppErrors>;
- *
- * const formatTypeError: TypeErrorFormatter<AppErrors> = (error) => {
- *   // In the real code, we would use the createTypeErrorFormatter helper
- *   // that safely stringifies error value.
+ *   | PositiveError
+ *   | NonNegativeError
+ *   | IntError
+ *   | NumberError
+ *   | ObjectError<Record<string, PersonErrors>>;
+ *
+ * const formatTypeError: TypeErrorFormatter<PersonErrors> = (error) => {
  *   switch (error.type) {
- *     case "Id":
- *       return `Invalid Id on table: ${error.table}.`;
- *     case "MaxLength":
- *       return `Max length is ${error.max}.`;
- *     case "MinLength":
- *       return `Min length is ${error.min}.`;
- *     case "Mnemonic":
- *       return `Invalid mnemonic: ${String(error.value)}`;
- *     case "Null":
- *       return `Not null`;
  *     case "String":
- *       // We can reuse existing formatter.
  *       return formatStringError(error);
+ *     case "Number":
+ *       return "Must be a number";
+ *     case "MinLength":
+ *       return `Must be at least ${error.min} characters`;
+ *     case "MaxLength":
+ *       return `Cannot exceed ${error.max} characters`;
  *     case "Trimmed":
- *       return "Value is not trimmed.";
- *     case "ValidMutationSize":
- *       return "A developer made an error, this should not happen.";
- *     case "Literal":
- *       return formatLiteralError(error);
- *     // Composite Types
- *     case "Union":
- *       return `Union errors: ${error.errors.map(formatTypeError).join(", ")}`;
+ *       return "Cannot have leading or trailing spaces";
+ *     case "Positive":
+ *       return "Must be a positive number";
+ *     case "NonNegative":
+ *       return "Must be zero or positive";
+ *     case "Int":
+ *       return "Must be an integer";
  *     case "Object": {
- *       if (
- *         error.reason.kind === "ExtraKeys" ||
- *         error.reason.kind === "NotObject"
- *       )
- *         return "A developer made an error, this should not happen.";
+ *       if (error.reason.kind === "NotObject") return "Must be an object";
+ *       if (error.reason.kind === "ExtraKeys")
+ *         return "Contains unexpected fields";
  *       const firstError = Object.values(error.reason.errors).find(
  *         (e) => e !== undefined,
  *       )!;
@@ -3902,8 +4095,8 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatIsTypeError(error);
       case "CurrencyCode":
         return formatCurrencyCodeError(error);
-      case "DateIsoString":
-        return formatDateIsoStringError(error);
+      case "DateIso":
+        return formatDateIsoError(error);
       case "Trimmed":
         return formatTrimmedError(error);
       case "MinLength":
@@ -3918,6 +4111,8 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatRegexError(error);
       case "Id":
         return formatIdError(error);
+      case "TableId":
+        return formatTableIdError(error);
       case "Positive":
         return formatPositiveError(error);
       case "Negative":
@@ -3948,14 +4143,12 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatLiteralError(error);
       case "Int64":
         return formatInt64Error(error);
-      case "BigIntFromString":
-        return formatBigIntFromStringError(error);
       case "Int64String":
         return formatInt64StringError(error);
-      case "JsonValueFromString":
-        return formatJsonValueFromStringError(error);
       case "Json":
         return formatJsonError(error);
+      case "ValidMutationSize":
+        return formatValidMutationSizeError(error);
       // Composite Types
       case "SimplePassword":
         return formatSimplePasswordError(formatTypeError)(error);
@@ -3971,8 +4164,220 @@ export const createFormatTypeError = <ExtraErrors extends TypeError = never>(
         return formatUnionError(formatTypeError)(error);
       case "Tuple":
         return formatTupleError(formatTypeError)(error);
+      default: {
+        // Fallback for unknown error types
+        const unknownError = error as TypeError;
+        return `A value ${safelyStringifyUnknownValue(unknownError.value)} is not valid for type ${unknownError.type}.`;
+      }
     }
   };
 
   return formatTypeError;
 };
+
+/**
+ * Converts an Evolu {@link TypeError} to Standard Schema V1 issues format.
+ *
+ * This function recursively converts Evolu's typed errors into the Standard
+ * Schema issue format with proper path tracking for nested structures.
+ *
+ * @category Utilities
+ */
+export const typeErrorToStandardSchemaIssues = <
+  ExtraErrors extends TypeError = never,
+>(
+  error: TypeErrors<ExtraErrors>,
+  formatTypeError: TypeErrorFormatter<TypeErrors<ExtraErrors>>,
+  path: ReadonlyArray<PropertyKey> = [],
+): ReadonlyArray<StandardSchemaV1.Issue> => {
+  if (error.type === "Array") {
+    const arrayError = error as ArrayError;
+    if (arrayError.reason.kind === "NotArray") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      arrayError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, arrayError.reason.index],
+    );
+  }
+
+  if (error.type === "Object") {
+    const objectError = error as ObjectError;
+    if (
+      objectError.reason.kind === "NotObject" ||
+      objectError.reason.kind === "ExtraKeys"
+    ) {
+      return [{ message: formatTypeError(error), path }];
+    }
+    const issues: Array<StandardSchemaV1.Issue> = [];
+    for (const [key, propError] of Object.entries(objectError.reason.errors)) {
+      issues.push(
+        ...typeErrorToStandardSchemaIssues(
+          propError as TypeErrors<ExtraErrors>,
+          formatTypeError,
+          [...path, key],
+        ),
+      );
+    }
+    return issues;
+  }
+
+  if (error.type === "ObjectWithRecord") {
+    const objectWithRecordError = error as ObjectWithRecordError;
+    if (objectWithRecordError.reason.kind === "NotObject") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    if (
+      objectWithRecordError.reason.kind === "IndexKey" ||
+      objectWithRecordError.reason.kind === "IndexValue"
+    ) {
+      return typeErrorToStandardSchemaIssues(
+        objectWithRecordError.reason.error as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        [...path, objectWithRecordError.reason.key as PropertyKey],
+      );
+    }
+    const issues: Array<StandardSchemaV1.Issue> = [];
+    for (const [key, propError] of Object.entries(
+      objectWithRecordError.reason.errors,
+    )) {
+      issues.push(
+        ...typeErrorToStandardSchemaIssues(
+          propError as TypeErrors<ExtraErrors>,
+          formatTypeError,
+          [...path, key],
+        ),
+      );
+    }
+    return issues;
+  }
+
+  if (error.type === "Record") {
+    const recordError = error as RecordError;
+    if (recordError.reason.kind === "NotRecord") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      recordError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, recordError.reason.key as PropertyKey],
+    );
+  }
+
+  if (error.type === "Tuple") {
+    const tupleError = error as TupleError;
+    if (tupleError.reason.kind === "InvalidLength") {
+      return [{ message: formatTypeError(error), path }];
+    }
+    return typeErrorToStandardSchemaIssues(
+      tupleError.reason.error as TypeErrors<ExtraErrors>,
+      formatTypeError,
+      [...path, tupleError.reason.index],
+    );
+  }
+
+  if (error.type === "Union") {
+    const unionError = error as UnionError;
+    return unionError.errors.flatMap((err) =>
+      typeErrorToStandardSchemaIssues(
+        err as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        path,
+      ),
+    );
+  }
+
+  if (error.type === "Brand") {
+    const brandError = error as BrandWithoutRefineError<TypeName, TypeError>;
+    if ("parentError" in brandError) {
+      return typeErrorToStandardSchemaIssues(
+        brandError.parentError as TypeErrors<ExtraErrors>,
+        formatTypeError,
+        path,
+      );
+    }
+    return [{ message: formatTypeError(error), path }];
+  }
+
+  return [{ message: formatTypeError(error), path }];
+};
+
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  export interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (
+      value: unknown,
+    ) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+
+  /** The result interface of the validate function. */
+  export type Result<Output> = SuccessResult<Output> | FailureResult;
+
+  /** The result interface if validation succeeds. */
+  export interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+
+  /** The result interface if validation fails. */
+  export interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: ReadonlyArray<Issue>;
+  }
+
+  /** The issue interface of the failure output. */
+  export interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+
+  /** The path segment interface of the issue. */
+  export interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+
+  /** The Standard Schema types interface. */
+  export interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+
+  /** Infers the input type of a Standard Schema. */
+  export type InferInput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["input"];
+
+  /** Infers the output type of a Standard Schema. */
+  export type InferOutput<Schema extends StandardSchemaV1> = NonNullable<
+    Schema["~standard"]["types"]
+  >["output"];
+}
+
+/**
+ * Shared formatter cache for Standard Schema integration - avoids circular
+ * dependency by lazily creating the formatter on first use rather than during
+ * module initialization.
+ */
+let cachedStandardSchemaFormatTypeError: TypeErrorFormatter<any> | undefined;