@evolu/common 6.0.1-preview.2 → 6.0.1-preview.21

package/src/Type.ts

@@ -1,84 +1,187 @@
 /**
- * 🧩 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
+ * precise, composable error value 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.
+ * - **No user-land chaining DSL** – designed with the upcoming ES pipe operator
+ *   in mind.
+ * - **Selective validation** – parent validations are skipped when already proved
+ *   by typing.
+ * - **Simple, top-down implementation** – readable source code from top to bottom
+ *   with no hidden magic; just plain functions and composition.
  *
- * - **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.
+ * ### Base Types Quick Start
  *
- * **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.
+ * ```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;
  *
- * - Evolu `Type` is:
+ * User.from({ name: "Alice" }); // ok
+ * User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
+ * ```
  *
- * - 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.
+ * ### Deriving JSON String Types
  *
- * 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 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;
  *
- * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
  *
- * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
- * `TrimmedString`, the parent Type is `String`.
+ * const person = Person.orThrow({
+ *   name: "Alice",
+ *   age: 30,
+ * });
  *
- * 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 personJson = personToPersonJson(person);
+ * expect(personJsonToPerson(personJson)).toEqual(person);
+ * ```
  *
- * Speaking of `fromParent` and `toParent`, those functions exist to bypass
- * parent Types when we can rely on TypeScript types.
+ * ### 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)
+ *
+ * ```ts
+ * const r = String.fromUnknown(42);
+ * if (!r.ok) console.error(formatStringError(r.error));
+ * ```
+ *
+ * #### 2. Unified Formatter with Overrides
+ *
+ * ```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}`;
+ * });
+ *
+ * const User = object({ name: NonEmptyTrimmedString100 });
+ * const resultUser = User.from({ name: "" });
+ * if (!resultUser.ok) console.error(formatTypeError(resultUser.error));
+ *
+ * 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:
+ * ### Design Decision: No Bidirectional Transformations
  *
- * 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.
+ * 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.
  *
  * @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 { err, getOrThrow, ok, Result, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
-import type { Brand, Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Literal, Simplify, WidenLiteral } from "./Types.js";
 import { IntentionalNever } from "./Types.js";
 
 export interface Type<
@@ -106,41 +209,60 @@ 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`.
+   * This is a convenience method that combines `from` with `getOrThrow`.
    *
-   * This is useful to transform `T` back to its `Input` representation.
+   * **When to use:**
    *
-   * For `refine`, it only removes the brand. For `transform`, it changes value.
-   */
-  readonly to: (value: T) => Input;
-
-  /**
-   * Creates `T` from `Parent` type.
+   * - Configuration values that are guaranteed to be valid (e.g., hardcoded
+   *   constants)
+   * - Application startup where failure should crash the program
+   * - Test code with known valid inputs
+   * - Converting from trusted sources where validation failure indicates a
+   *   programming error
    *
-   * This function skips parent Types validations/transformations when we have
-   * already partially validated/transformed value.
+   * **When NOT to use:**
    *
-   * 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`.
+   * - User input validation - use `from` and handle errors gracefully
+   * - Data from external APIs or files - use `from` for proper error handling
+   * - Library code that should return Results rather than throw
    *
    * ### Example
    *
    * ```ts
-   * // string & Brand<"Trimmed">
-   * const value = TrimString.fromParent("a ").value; // as efficient as foo.trim()
+   * // ✅ Good: Known valid constant
+   * const maxRetries = PositiveInt.orThrow(3);
+   *
+   * // ✅ Good: App configuration that should crash on invalid values
+   * const appName = SimpleName.orThrow("MyApp");
+   *
+   * // ❌ 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 fromParent: (value: Parent) => Result<T, Error>;
+  readonly orThrow: (value: Input) => T;
 
-  /** 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
@@ -261,26 +383,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 (Error | ParentError) 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 +467,7 @@ const createType = <
     | "name"
     | "is"
     | "from"
+    | "orThrow"
     | typeof EvoluTypeSymbol
     | "Type"
     | "Input"
@@ -323,6 +481,7 @@ const createType = <
   name,
   is: (value: unknown): value is T => definition.fromUnknown(value).ok,
   from: definition.fromUnknown,
+  orThrow: (value: Input): T => getOrThrow(definition.fromUnknown(value)),
   [EvoluTypeSymbol]: true,
   Type: undefined as unknown as T,
   Input: undefined as unknown as Input,
@@ -365,12 +524,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 +549,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,
   });
 
 /**
@@ -607,7 +758,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 +837,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 +931,7 @@ export function brand<
   return {
     ...createType("Brand", {
       fromUnknown,
-      to: identity,
       fromParent: (refine ?? ok) as IntentionalNever,
-      toParent: identity,
     }),
     brand: name,
     parentType: parent,
@@ -848,30 +997,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 +1074,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;
@@ -948,64 +1102,6 @@ export const formatTrimmedError = createTypeErrorFormatter<TrimmedError>(
   (error) => `A value ${error.value} is not 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 +1113,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.
  *
@@ -1213,9 +1312,9 @@ export const formatRegexError = createTypeErrorFormatter<RegexError>(
 );
 
 /**
- * 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,35 +1322,116 @@ 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) => `Value ${error.value} is not a valid Base64Url string.`,
+);
+
+const hasNodeBuffer = typeof globalThis.Buffer !== "undefined";
+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.
- *
- * A `SimpleName` string uses a limited, safe alphabet for naming purposes:
+ * Simple alphanumeric string for naming in file systems, URLs, and identifiers.
  *
- * - Uppercase letters (`A-Z`)
- * - Lowercase letters (`a-z`)
- * - Digits (`0-9`)
- * - Dash (`-`)
+ * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
+ * `_`). See `UrlSafeString` for details.
  *
  * The string must be between 1 and 42 characters.
  *
@@ -1268,18 +1448,13 @@ 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 <= 42
+    ? 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`.
@@ -1304,17 +1479,56 @@ export const formatSimplePasswordError = (
   );
 
 /**
- * `Id` {@link Type}.
+ * Globally unique identifier.
  *
- * Represents a unique identifier with exactly 21 characters, using NanoID's
- * standard format (`A-Za-z0-9_-`).
+ * **Evolu Id** is 16 random bytes from a cryptographically secure random
+ * generator, encoded as 22-character Base64Url string. This provides strong
+ * collision resistance for distributed ID generation.
+ *
+ * ### Design Rationale
+ *
+ * Why Evolu Id over alternatives:
+ *
+ * - **NanoID**: No standard binary serialization format, and uses only ~126 bits
+ *   of entropy (21 characters from 64-symbol alphabet) compared to Evolu Id's
+ *   128 bits.
+ * - **UUID (v4)**: String format is 36 characters (with hyphens) compared to
+ *   Evolu Id's 22 characters. While UUIDs can be stored as 16 bytes, their
+ *   standard string representation is verbose.
+ * - **UUID v7**: Includes timestamp in the ID, which leaks information about when
+ *   data was created. This is a privacy concern for local-first applications
+ *   where creation time must remain private.
+ *
+ * Evolu Id provides 128 bits of entropy, compact string representation (22
+ * characters), standard and native string serialization (Base64Url), and no
+ * privacy leaks.
+ *
+ * ### Future Consideration
+ *
+ * For database-heavy workloads where insert performance is critical, a hybrid
+ * approach could be considered: `timestamp ^ H(cluster_id, timestamp >> N)`
+ * where H is a keyed hash function and N is a configurable parameter. This
+ * would maintain spatial locality for database caches (improving insert
+ * performance by an order of magnitude) while adding entropy to prevent
+ * timestamp leakage and correlation across systems. The parameter N would allow
+ * trading off cache locality (larger N = better locality) versus entropy
+ * distribution. See https://brooker.co.za/blog/2025/10/22/uuidv7.html for
+ * details on this approach.
  *
  * @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) => `Value ${error.value} is not a valid Id.`,
+);
 
 /**
  * Creates an {@link Id}.
@@ -1324,13 +1538,65 @@ export const idTypeValueLength = 21;
  * ```ts
  * // string & Brand<"Id">
  * const id = createId(deps);
+ *
+ * // string & Brand<"Id"> & Brand<"Todo">
+ * const todoId = createId<"Todo">(deps);
  * ```
  */
-export const createId = (deps: NanoIdLibDep): Id =>
-  deps.nanoIdLib.nanoid() as Id;
+export const createId = <B extends string = never>(
+  deps: RandomBytesDep,
+): [B] extends [never] ? Id : Id & Brand<B> =>
+  uint8ArrayToBase64Url(deps.randomBytes.create(16)) as unknown as [B] extends [
+    never,
+  ]
+    ? Id
+    : Id & Brand<B>;
 
 /**
- * Type Factory to create branded {@link Id} Type for a specific table.
+ * 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 is one-way. We cannot recover the original
+ * external string from the generated {@link Id}. If we need to preserve the
+ * original external ID, store it in a separate column.
+ *
+ * @category String
+ */
+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 a branded {@link Id} Type for a table's primary key.
+ *
+ * The table name becomes an additional brand for type safety.
  *
  * ### Example
  *
@@ -1342,53 +1608,62 @@ 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>(
+export const formatTableIdError = createTypeErrorFormatter<TableIdError>(
   (error) => `Invalid ${error.type} table Id: ${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.
  *
@@ -1554,6 +1829,11 @@ export type NonNegativeInt = typeof NonNegativeInt.Type;
 export const PositiveInt = positive(NonNegativeInt);
 export type PositiveInt = typeof PositiveInt.Type;
 
+/** Maximum safe positive integer value for practically infinite operations. */
+export const maxPositiveInt = PositiveInt.orThrow(
+  globalThis.Number.MAX_SAFE_INTEGER,
+);
+
 /** @category Number */
 export const NonPositiveInt = nonPositive(Int);
 export type NonPositiveInt = typeof NonPositiveInt.Type;
@@ -1778,10 +2058,6 @@ 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}.
  *
@@ -1808,12 +2084,10 @@ export const literal = <T extends Literal>(expected: T): LiteralType<T> => {
   return {
     ...createType("Literal", {
       fromUnknown,
-      to: identity as (value: T) => WidenLiteral<T>,
       fromParent: ok,
-      toParent: identity,
     }),
     expected,
-  };
+  } as LiteralType<T>;
 };
 
 export interface LiteralType<T extends Literal>
@@ -1833,141 +2107,6 @@ export const formatLiteralError = createTypeErrorFormatter<LiteralError>(
     )}.`,
 );
 
-/**
- * {@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}.
- *
- * ### Example
- *
- * ```ts
- * NumberFromString.from("42"); // ok(42)
- * NumberFromString.from("abc"); // err({ type: "NumberFromString", value: "abc" })
- * ```
- *
- * @category Number
- */
-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 interface NumberFromStringError extends TypeError<"NumberFromString"> {}
-
-export const formatNumberFromStringError =
-  createTypeErrorFormatter<NumberFromStringError>((error) => {
-    return `The value ${error.value} could not be converted to a finite number.`;
-  });
-
 /**
  * Array of a specific {@link Type}.
  *
@@ -2020,9 +2159,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 +2184,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 +2320,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 +2364,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 +2667,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 +2718,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 +2963,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 +2980,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 +3080,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 +3221,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 +3252,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 +3331,41 @@ 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(),
-);
+// // co s timhle? je to string, ze ktereho lze udelat bigint
 
-export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {}
+// export const BigIntFromString = transform(
+//   String,
+//   BigInt,
+//   (value) =>
+//     trySync(
+//       () => globalThis.BigInt(value),
+//       (): BigIntFromStringError => ({ type: "BigIntFromString", value }),
+//     ),
+//   (value) => value.toString(),
+// );
 
-export const formatBigIntFromStringError =
-  createTypeErrorFormatter<BigIntFromStringError>(
-    (error) => `The value ${error.value} could not be converted to a BigInt.`,
-  );
+// 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 +3470,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 +3486,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 +3508,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 +3606,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 +3630,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 +3735,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 +3794,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 +3819,9 @@ export type TypeErrors<ExtraErrors extends TypeError = never> =
   | BetweenError
   | LiteralError
   | Int64Error
-  | BigIntFromStringError
   | Int64StringError
-  | JsonValueFromStringError
   | JsonError
+  | ValidMutationSizeError
   | ExtraErrors
   // Composite errors
   | ArrayError<TypeErrors<ExtraErrors>>
@@ -3792,70 +3836,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 +3950,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 +3966,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 +3998,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);