@evolu/common 6.0.1-preview.3 → 6.0.1-preview.30

package/dist/src/Type.js

@@ -1,80 +1,186 @@
 /**
- * 🧩 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}.
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
  *
- * Evolu Type exists because no existing validation/parsing/transformation
- * library fully met our needs:
+ * Why another validation library?
  *
- * - **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.
+ * - **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.
  *
- * **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.
+ * ### Base Types Quick Start
  *
- * - Evolu `Type` is:
+ * ```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;
  *
- * - 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.
+ * 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,
+ * });
  *
- * 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:
+ * const personJson = personToPersonJson(person);
+ * expect(personJsonToPerson(personJson)).toEqual(person);
+ * ```
  *
- * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ * ### Error Formatting
  *
- * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
- * `TrimmedString`, the parent Type is `String`.
+ * Evolu separates validation logic from human-readable messages. There are two
+ * layers:
  *
- * 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.
+ * 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.
  *
- * Speaking of `fromParent` and `toParent`, those functions exist to bypass
- * parent Types when we can rely on TypeScript types.
+ * #### 1. Per-Type Formatter (recap)
  *
- * `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")`.
+ * ```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));
+ * ```
+ *
+ * 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 { wordlist } from "@scure/bip39/wordlists/english.js";
+import { pack } from "msgpackr";
 import { isPlainObject } from "./Object.js";
-import { err, ok, trySync } from "./Result.js";
+import { hasNodeBuffer } from "./Platform.js";
+import { err, getOrNull, getOrThrow, ok, trySync } from "./Result.js";
 import { safelyStringifyUnknownValue } from "./String.js";
 const EvoluTypeSymbol = Symbol("evolu.Type");
 /**
@@ -88,6 +194,8 @@ const createType = (name, definition) => ({
     name,
     is: (value) => definition.fromUnknown(value).ok,
     from: definition.fromUnknown,
+    orThrow: (value) => getOrThrow(definition.fromUnknown(value)),
+    orNull: (value) => getOrNull(definition.fromUnknown(value)),
     [EvoluTypeSymbol]: true,
     Type: undefined,
     Input: undefined,
@@ -95,6 +203,24 @@ const createType = (name, definition) => ({
     Parent: undefined,
     ParentError: undefined,
     Errors: undefined,
+    "~standard": {
+        version: 1,
+        vendor: "evolu",
+        validate: (value) => {
+            const result = definition.fromUnknown(value);
+            if (result.ok) {
+                return { value: result.value };
+            }
+            cachedStandardSchemaFormatTypeError ??= createFormatTypeError();
+            return {
+                issues: typeErrorToStandardSchemaIssues(result.error, cachedStandardSchemaFormatTypeError),
+            };
+        },
+        types: {
+            input: undefined,
+            output: undefined,
+        },
+    },
 });
 /**
  * Creates a formatter function for {@link TypeError}.
@@ -117,12 +243,6 @@ export const createTypeErrorFormatter = (format) => (error) => format({ ...error
  * 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
  *
@@ -144,9 +264,7 @@ export const createTypeErrorFormatter = (format) => (error) => format({ ...error
  */
 export const base = (name, fromUnknown) => createType(name, {
     fromUnknown,
-    to: identity,
     fromParent: (ok), // `fromParent` relies on types, so it can't fail for the Base Type
-    toParent: identity,
 });
 /**
  * Creates a formatter function for a base {@link TypeError}.
@@ -233,7 +351,7 @@ export const instanceOf = (ctor) => ({
         : err({ type: "InstanceOf", value, ctor: ctor.name })),
     ctor,
 });
-export const formatInstanceOfError = createTypeErrorFormatter((error) => `Value ${error.value} is not an instance of ${error.ctor}`);
+export const formatInstanceOfError = createTypeErrorFormatter((error) => `The value ${error.value} is not an instance of ${error.ctor}.`);
 /**
  * JavaScript Date.
  *
@@ -280,9 +398,7 @@ export function brand(name, parent, refine) {
     return {
         ...createType("Brand", {
             fromUnknown,
-            to: identity,
             fromParent: (refine ?? ok),
-            toParent: identity,
         }),
         brand: name,
         parentType: parent,
@@ -296,7 +412,7 @@ export function brand(name, parent, refine) {
 export const CurrencyCode = brand("CurrencyCode", String, (value) => /^[A-Z]{3}$/.test(value)
     ? ok(value)
     : err({ type: "CurrencyCode", value }));
-export const formatCurrencyCodeError = createTypeErrorFormatter((error) => `Invalid currency code: ${error.value}`);
+export const formatCurrencyCodeError = createTypeErrorFormatter((error) => `Invalid currency code: ${error.value}.`);
 /**
  * ISO 8601 date-time string.
  *
@@ -312,37 +428,39 @@ export const formatCurrencyCodeError = createTypeErrorFormatter((error) => `Inva
  * ### 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({ type: "DateIsoString", value });
+        return err({ type: "DateIso", value });
     }
-    if (isNaN(globalThis.Date.parse(value))) {
-        return err({ type: "DateIsoString", value });
+    const parsed = globalThis.Date.parse(value);
+    if (isNaN(parsed)) {
+        return err({ type: "DateIso", 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({ type: "DateIso", value });
     }
     return ok(value);
 });
-export const formatDateIsoStringError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid ISO 8601 date string.`);
+export const formatDateIsoError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid ISO 8601 date string.`);
+export const dateToDateIso = (value) => DateIso.fromParent(value.toISOString());
+export const dateIsoToDate = (value) => new globalThis.Date(value);
 /**
  * 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;
@@ -353,33 +471,7 @@ export const formatDateIsoStringError = createTypeErrorFormatter((error) => `The
 export const trimmed = (parent) => brand("Trimmed", parent, (value) => value.trim().length === value.length
     ? ok(value)
     : err({ type: "Trimmed", value }));
-export const formatTrimmedError = createTypeErrorFormatter((error) => `A value ${error.value} is not trimmed`);
-/**
- * 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 = (parent) => transform(parent, trimmed(parent), (value) => ok(value.trim()), (value) => value);
+export const formatTrimmedError = createTypeErrorFormatter((error) => `The value ${error.value} must be trimmed.`);
 /**
  * Trimmed string
  *
@@ -389,6 +481,7 @@ export const trim = (parent) => transform(parent, trimmed(parent), (value) => ok
  * @category String
  */
 export const TrimmedString = trimmed(String);
+export const trim = (value) => value.trim();
 /**
  * Minimum length.
  *
@@ -403,7 +496,7 @@ export const TrimmedString = trimmed(String);
  * @category Array
  */
 export const minLength = (min) => (parent) => brand(`MinLength${min}`, parent, (value) => value.length >= min ? ok(value) : err({ type: "MinLength", value, min }));
-export const formatMinLengthError = createTypeErrorFormatter((error) => `Value ${error.value} does not meet the minimum length of ${error.min}.`);
+export const formatMinLengthError = createTypeErrorFormatter((error) => `The value ${error.value} does not meet the minimum length of ${error.min}.`);
 /**
  * Maximum length.
  *
@@ -418,7 +511,7 @@ export const formatMinLengthError = createTypeErrorFormatter((error) => `Value $
  * @category Array
  */
 export const maxLength = (max) => (parent) => brand(`MaxLength${max}`, parent, (value) => value.length <= max ? ok(value) : err({ type: "MaxLength", value, max }));
-export const formatMaxLengthError = createTypeErrorFormatter((error) => `Value ${error.value} exceeds the maximum length of ${error.max}.`);
+export const formatMaxLengthError = createTypeErrorFormatter((error) => `The value ${error.value} exceeds the maximum length of ${error.max}.`);
 /**
  * Exact length.
  *
@@ -435,7 +528,7 @@ export const formatMaxLengthError = createTypeErrorFormatter((error) => `Value $
 export const length = (exact) => (parent) => brand(`Length${exact}`, parent, (value) => value.length === exact
     ? ok(value)
     : err({ type: "Length", value, exact }));
-export const formatLengthError = createTypeErrorFormatter((error) => `Value ${error.value} does not have the required length of ${error.exact}.`);
+export const formatLengthError = createTypeErrorFormatter((error) => `The value ${error.value} does not have the required length of ${error.exact}.`);
 /** @category String */
 export const NonEmptyString = minLength(1)(String);
 /** @category String */
@@ -468,7 +561,7 @@ export const NonEmptyTrimmedString1000 = minLength(1)(TrimmedString1000);
 export const Mnemonic = brand("Mnemonic", NonEmptyTrimmedString, (value) => bip39.validateMnemonic(value, wordlist)
     ? ok(value)
     : err({ type: "Mnemonic", value }));
-export const formatMnemonicError = createTypeErrorFormatter((error) => `Invalid BIP39 mnemonic: ${error.value}`);
+export const formatMnemonicError = createTypeErrorFormatter((error) => `Invalid BIP39 mnemonic: ${error.value}.`);
 /**
  * String matching a regular expression.
  *
@@ -492,11 +585,11 @@ export const regex = (name, pattern) => {
             : err({ type: "Regex", name, value, pattern });
     });
 };
-export const formatRegexError = createTypeErrorFormatter((error) => `Value ${error.value} does not match the pattern for ${error.name}: ${error.pattern}`);
+export const formatRegexError = createTypeErrorFormatter((error) => `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`)
@@ -504,29 +597,88 @@ export const formatRegexError = createTypeErrorFormatter((error) => `Value ${err
  * - 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("Base64Url", /^[A-Za-z0-9_-]+$/)(String);
+export const UrlSafeString = regex("UrlSafeString", /^[A-Za-z0-9_-]+$/)(String);
 /**
- * Simple alphanumeric string for naming.
+ * Base64Url without padding.
  *
- * A `SimpleName` string uses a limited, safe alphabet for naming purposes:
+ * Encode with {@link uint8ArrayToBase64Url}, decode with
+ * {@link base64UrlToUint8Array}.
  *
- * - Uppercase letters (`A-Z`)
- * - Lowercase letters (`a-z`)
- * - Digits (`0-9`)
- * - Dash (`-`)
+ * @category String
+ */
+export const Base64Url = brand("Base64Url", String, (value) => {
+    // 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));
+    }
+    catch {
+        //
+    }
+    return roundTrip === value
+        ? ok(value)
+        : err({ type: "Base64Url", value });
+});
+export const formatBase64UrlError = createTypeErrorFormatter((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 = hasNodeBuffer
+    ? (bytes) => globalThis.Buffer.from(bytes).toString("base64url")
+    : // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        typeof globalThis.Uint8Array.prototype?.toBase64 !== "undefined"
+            ? (bytes) => 
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            bytes.toBase64(base64UrlOptions)
+            : (bytes) => {
+                const binaryString = Array.from(bytes, (byte) => globalThis.String.fromCodePoint(byte)).join("");
+                const base64 = globalThis.btoa(binaryString);
+                return base64
+                    .replace(/\+/g, "-")
+                    .replace(/\//g, "_")
+                    .replace(/=/g, "");
+            };
+/** Decodes a {@link Base64Url} string to a Uint8Array. */
+export const base64UrlToUint8Array = hasNodeBuffer
+    ? (str) => {
+        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?.fromBase64 !== "undefined"
+            ? (str) => 
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
+            globalThis.Uint8Array.fromBase64(str, base64UrlOptions)
+            : (str) => {
+                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 in file systems, URLs, and identifiers.
+ *
+ * Uses the same safe alphabet as {@link UrlSafeString} (letters, digits, `-`,
+ * `_`). See `UrlSafeString` for details.
  *
  * The string must be between 1 and 42 characters.
  *
@@ -543,13 +695,9 @@ export const Base64Url = regex("Base64Url", /^[A-Za-z0-9_-]+$/)(String);
  *
  * @category String
  */
-export const SimpleName = regex("SimpleName", /^[a-z0-9-]{1,42}$/i)(String);
-/**
- * Default NanoId.
- *
- * @category String
- */
-export const NanoId = regex("NanoId", /^[A-Za-z0-9_-]{21}$/)(String);
+export const SimpleName = brand("SimpleName", UrlSafeString, (value) => value.length >= 1 && value.length <= 42
+    ? ok(value)
+    : err({ type: "SimpleName", value }));
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
@@ -558,15 +706,48 @@ export const NanoId = regex("NanoId", /^[A-Za-z0-9_-]{21}$/)(String);
 export const SimplePassword = brand("SimplePassword", minLength(8)(maxLength(64)(TrimmedString)));
 export const formatSimplePasswordError = (formatTypeError) => createTypeErrorFormatter((error) => `Invalid password: ${formatTypeError(error.parentError)}`);
 /**
- * `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 idTypeValueLength = 21;
+export const Id = brand("Id", String, (value) => value.length === 22 && Base64Url.fromParent(value).ok
+    ? ok(value)
+    : err({ type: "Id", value }));
+export const formatIdError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid Id.`);
 /**
  * Creates an {@link Id}.
  *
@@ -575,11 +756,53 @@ 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) => deps.nanoIdLib.nanoid();
+export const createId = (deps) => uint8ArrayToBase64Url(deps.randomBytes.create(16));
 /**
- * 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 = (value) => {
+    const hash = sha256(utf8ToBytes(value));
+    // Take first 16 bytes of hash and convert to Id
+    const id = idBytesToId(hash.slice(0, 16));
+    return id;
+};
+/**
+ * Creates a branded {@link Id} Type for a table's primary key.
+ *
+ * The table name becomes an additional brand for type safety.
  *
  * ### Example
  *
@@ -592,32 +815,36 @@ export const createId = (deps) => deps.nanoIdLib.nanoid();
  * @category String
  */
 export const id = (table) => {
-    const fromParent = (value) => {
-        const idResult = Id.fromParent(value);
-        if (!idResult.ok) {
-            return err({ type: "Id", value, table });
-        }
-        return ok(idResult.value);
-    };
     const fromUnknown = (value) => {
         const parentResult = String.fromUnknown(value);
         if (!parentResult.ok)
             return parentResult;
         return fromParent(parentResult.value);
     };
+    const fromParent = (value) => {
+        const idResult = Id.fromParent(value);
+        if (!idResult.ok) {
+            return err({ type: "TableId", value, table });
+        }
+        return ok(idResult.value);
+    };
     return {
-        ...createType("Id", {
-            fromUnknown,
-            to: (value) => value,
-            fromParent,
-            toParent: (value) => value,
-        }),
+        ...createType("Id", { fromUnknown, fromParent }),
         table,
     };
 };
-export const formatIdError = createTypeErrorFormatter((error) => `Invalid ${error.type} table Id: ${error.value}`);
-/**
- * Positive number.
+export const formatTableIdError = createTypeErrorFormatter((error) => `Invalid Id for table ${error.table}: ${error.value}.`);
+/** Binary representation of an {@link Id}. */
+export const IdBytes = brand("IdBytes", length(16)(Uint8Array));
+export const idBytesTypeValueLength = 16;
+export const idToIdBytes = (id) => 
+// Id is Base64Url (validated by Id.from), cast is safe
+base64UrlToUint8Array(id);
+export const idBytesToId = (idBytes) => 
+// Base64Url encoding of 16 bytes always produces valid Id (22 chars)
+uint8ArrayToBase64Url(idBytes);
+/**
+ * Positive number (> 0).
  *
  * ### Example
  *
@@ -631,9 +858,9 @@ export const formatIdError = createTypeErrorFormatter((error) => `Invalid ${erro
  * @category Number
  */
 export const positive = (parent) => brand("Positive", parent, (value) => value > 0 ? ok(value) : err({ type: "Positive", value }));
-export const formatPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} is not positive.`);
+export const formatPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} must be positive (> 0).`);
 /**
- * Negative number.
+ * Negative number (< 0).
  *
  * ### Example
  *
@@ -644,9 +871,9 @@ export const formatPositiveError = createTypeErrorFormatter((error) => `The valu
  * @category Number
  */
 export const negative = (parent) => brand("Negative", parent, (value) => value < 0 ? ok(value) : err({ type: "Negative", value }));
-export const formatNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} is not negative.`);
+export const formatNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} must be negative (< 0).`);
 /**
- * Non-positive number.
+ * Non-positive number (≤ 0).
  *
  * ### Example
  *
@@ -659,9 +886,9 @@ export const formatNegativeError = createTypeErrorFormatter((error) => `The valu
 export const nonPositive = (parent) => brand("NonPositive", parent, (value) => value <= 0
     ? ok(value)
     : err({ type: "NonPositive", value }));
-export const formatNonPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} is not non-positive.`);
+export const formatNonPositiveError = createTypeErrorFormatter((error) => `The value ${error.value} must be non-positive (≤ 0).`);
 /**
- * Non-negative number.
+ * Non-negative number (≥ 0).
  *
  * ### Example
  *
@@ -674,14 +901,30 @@ export const formatNonPositiveError = createTypeErrorFormatter((error) => `The v
 export const nonNegative = (parent) => brand("NonNegative", parent, (value) => value >= 0
     ? ok(value)
     : err({ type: "NonNegative", value }));
-export const formatNonNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} is not non-negative.`);
-/** @category Number */
+export const formatNonNegativeError = createTypeErrorFormatter((error) => `The value ${error.value} must be non-negative (≥ 0).`);
+/**
+ * Non-negative number (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeNumber = nonNegative(Number);
-/** @category Number */
+/**
+ * Positive number (> 0).
+ *
+ * @category Number
+ */
 export const PositiveNumber = positive(NonNegativeNumber);
-/** @category Number */
+/**
+ * Non-positive number (≤ 0).
+ *
+ * @category Number
+ */
 export const NonPositiveNumber = nonPositive(Number);
-/** @category Number */
+/**
+ * Negative number (< 0).
+ *
+ * @category Number
+ */
 export const NegativeNumber = negative(NonPositiveNumber);
 /**
  * Integer within the safe range of JavaScript numbers.
@@ -697,20 +940,38 @@ export const NegativeNumber = negative(NonPositiveNumber);
 export const int = (parent) => brand("Int", parent, (value) => globalThis.Number.isSafeInteger(value)
     ? ok(value)
     : err({ type: "Int", value }));
-export const formatIntError = createTypeErrorFormatter((error) => `The value ${error.value} is not an integer.`);
+export const formatIntError = createTypeErrorFormatter((error) => `The value ${error.value} must be an integer.`);
 /**
  * Integer within the safe range of JavaScript numbers.
  *
  * @category Number
  */
 export const Int = int(Number);
-/** @category Number */
+/**
+ * Non-negative integer (≥ 0).
+ *
+ * @category Number
+ */
 export const NonNegativeInt = nonNegative(Int);
-/** @category Number */
+/**
+ * Positive integer (> 0).
+ *
+ * @category Number
+ */
 export const PositiveInt = positive(NonNegativeInt);
-/** @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);
-/** @category Number */
+/**
+ * Negative integer (< 0).
+ *
+ * @category Number
+ */
 export const NegativeInt = negative(NonPositiveInt);
 /**
  * Number greater than a specified value.
@@ -750,7 +1011,7 @@ export const formatLessThanOrEqualToError = createTypeErrorFormatter((error) =>
 export const nonNaN = (parent) => brand("NonNaN", parent, (value) => !globalThis.Number.isNaN(value)
     ? ok(value)
     : err({ type: "NonNaN", value }));
-export const formatNonNaNError = createTypeErrorFormatter((error) => `The value ${error.value} is NaN (not a number).`);
+export const formatNonNaNError = createTypeErrorFormatter(() => `The value must not be NaN.`);
 /** @category Number */
 export const NonNaNNumber = nonNaN(Number);
 /**
@@ -761,7 +1022,7 @@ export const NonNaNNumber = nonNaN(Number);
 export const finite = (parent) => brand("Finite", parent, (value) => globalThis.Number.isFinite(value)
     ? ok(value)
     : err({ type: "Finite", value }));
-export const formatFiniteError = createTypeErrorFormatter((error) => `The value ${error.value} is not finite.`);
+export const formatFiniteError = createTypeErrorFormatter((error) => `The value ${error.value} must be finite.`);
 /**
  * Finite number.
  *
@@ -802,8 +1063,6 @@ export const between = (min, max) => (parent) => brand(`Between${min}-${max}`, p
     ? ok(value)
     : err({ type: "Between", value, min, max }));
 export const formatBetweenError = createTypeErrorFormatter((error) => `The value ${error.value} is not between ${error.min} and ${error.max}, inclusive.`);
-/** @category Number */
-export const Between1And10 = between(1, 10)(Number);
 /**
  * Literal {@link Type}.
  *
@@ -828,90 +1087,12 @@ export const literal = (expected) => {
     return {
         ...createType("Literal", {
             fromUnknown,
-            to: identity,
             fromParent: ok,
-            toParent: identity,
         }),
         expected,
     };
 };
 export const formatLiteralError = createTypeErrorFormatter((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, toType, fromParent, toParent) => {
-    const fromUnknown = (value) => {
-        const parentResult = fromType.fromUnknown(value);
-        if (!parentResult.ok)
-            return parentResult;
-        return fromParent(parentResult.value);
-    };
-    const to = (value) => fromType.to(toParent(value));
-    return {
-        ...createType("Transform", {
-            fromUnknown,
-            to,
-            fromParent,
-            toParent,
-        }),
-        is: toType.is,
-        fromType,
-        toType,
-    };
-};
-/**
- * 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({ type: "NumberFromString", value });
-    return result;
-}, (num) => num.toString());
-export const formatNumberFromStringError = createTypeErrorFormatter((error) => {
-    return `The value ${error.value} could not be converted to a finite number.`;
-});
 /**
  * Array of a specific {@link Type}.
  *
@@ -954,7 +1135,6 @@ export const array = (element) => {
         }
         return ok(result);
     };
-    const to = (value) => value.map(element.to);
     const fromParent = (value) => {
         const result = [];
         for (let i = 0; i < value.length; i++) {
@@ -974,14 +1154,8 @@ export const array = (element) => {
         }
         return ok(result);
     };
-    const toParent = (values) => values.map(element.toParent);
     return {
-        ...createType("Array", {
-            fromUnknown,
-            to,
-            fromParent,
-            toParent,
-        }),
+        ...createType("Array", { fromUnknown, fromParent }),
         element,
     };
 };
@@ -1055,10 +1229,6 @@ export const record = (keyType, valueType) => {
         }
         return ok(result);
     };
-    const to = (value) => Object.fromEntries(Object.entries(value).map(([key, val]) => [
-        keyType.to(key),
-        valueType.to(val),
-    ]));
     const fromParent = (value) => {
         const result = {};
         for (const [rawKey, rawValue] of Object.entries(value)) {
@@ -1090,16 +1260,10 @@ export const record = (keyType, valueType) => {
         }
         return ok(result);
     };
-    const toParent = (value) => Object.fromEntries(Object.entries(value).map(([key, val]) => [
-        keyType.toParent(key),
-        valueType.toParent(val),
-    ]));
     return {
         ...createType("Record", {
             fromUnknown,
-            to,
             fromParent,
-            toParent,
         }),
         key: keyType,
         value: valueType,
@@ -1186,22 +1350,6 @@ export function object(props, record) {
         }
         return ok(result);
     };
-    const to = (value) => {
-        const entries = [];
-        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) => {
         const errors = {};
         const result = {};
@@ -1249,28 +1397,10 @@ export function object(props, record) {
         }
         return ok(result);
     };
-    const toParent = (value) => {
-        const entries = [];
-        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 } : {}),
@@ -1323,7 +1453,6 @@ export function union(...args) {
      *    - Generate a specialized function to improve validation performance for such
      *         cases.
      */
-    /* eslint-disable */
     const members = args.map((arg) => (isType(arg) ? arg : literal(arg)));
     const fromUnknown = (value) => {
         const errors = [];
@@ -1339,23 +1468,13 @@ export function union(...args) {
             errors,
         });
     };
-    const to = (value) => {
-        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 */
 }
 export const formatUnionError = (formatTypeError) => createTypeErrorFormatter((error) => {
     const formattedErrors = error.errors
@@ -1411,20 +1530,10 @@ export const recursive = (create) => {
             type ??= create();
             return type.fromUnknown(value);
         },
-        to: (value) => {
-            type ??= create();
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-            return type.to(value);
-        },
         fromParent: (value) => {
             type ??= create();
             return type.fromParent(value);
         },
-        toParent: (value) => {
-            type ??= create();
-            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-            return type.toParent(value);
-        },
         is: (value) => {
             type ??= create();
             return type.is(value);
@@ -1528,7 +1637,6 @@ export const tuple = (...elements) => {
         }
         return ok(result);
     };
-    const to = (value) => value.map((val, index) => elements[index].to(val));
     const fromParent = (value) => {
         if (!Array.isArray(value) || value.length !== elements.length) {
             return err({
@@ -1555,13 +1663,10 @@ export const tuple = (...elements) => {
         }
         return ok(result);
     };
-    const toParent = (value) => value.map((val, index) => elements[index].toParent(val));
     return {
         ...createType("Tuple", {
             fromUnknown,
-            to,
             fromParent,
-            toParent,
         }),
         elements,
     };
@@ -1595,22 +1700,32 @@ export const Int64 = brand("Int64", BigInt, (value) => value >= -922337203685477
     ? ok(value)
     : err({ type: "Int64", value }));
 export const formatInt64Error = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid 64-bit signed integer (Int64).`);
-export const BigIntFromString = transform(String, BigInt, (value) => trySync(() => globalThis.BigInt(value), () => ({ type: "BigIntFromString", value })), (value) => value.toString());
-export const formatBigIntFromStringError = createTypeErrorFormatter((error) => `The value ${error.value} could not be converted to a BigInt.`);
+// // co s timhle? je to string, ze ktereho lze udelat bigint
+// 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({ type: "Int64String", value });
-});
+export const Int64String = brand("Int64", NonEmptyTrimmedString, (value) => trySync(() => {
+    const maybeInt = globalThis.BigInt(value);
+    Int64.orThrow(maybeInt);
+    return value;
+}, () => ({ type: "Int64String", value })));
 export const formatInt64StringError = createTypeErrorFormatter((error) => `The value ${error.value} is not a valid Int64 string.`);
 /**
  * JSON-compatible value: string, {@link FiniteNumber}, boolean, null,
@@ -1631,48 +1746,83 @@ export const JsonArray = array(JsonValue);
  * @category Object
  */
 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), (error) => ({
-    type: `JsonValueFromString`,
+export const parseJson = (value) => trySync(() => JSON.parse(value), (error) => ({
+    type: `Json`,
     value,
     message: globalThis.String(error),
-})), (value) => JSON.stringify(value));
-export const formatJsonValueFromStringError = createTypeErrorFormatter((error) => `Invalid JSONValue: ${error.value}. Error: ${error.message}`);
+}));
 /**
  * JSON-string {@link Type}.
  *
  * ### 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);
+    const result = parseJson(value);
     if (!result.ok)
-        return err({
-            type: "Json",
-            value,
-            message: result.error.message,
-        });
+        return result;
     return ok(value);
 });
 export const formatJsonError = createTypeErrorFormatter((error) => `Invalid JSON: ${error.value}. Error: ${error.message}`);
+export const jsonValueToJson = (value) => JSON.stringify(value);
+export const jsonToJsonValue = (value) => JSON.parse(value);
+/**
+ * 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 = (type, name) => {
+    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);
+    });
+    return [
+        BrandedJsonType,
+        jsonValueToJson,
+        jsonToJsonValue,
+    ];
+};
 /**
  * Optional {@link Type}.
  *
@@ -1697,9 +1847,7 @@ export const formatJsonError = createTypeErrorFormatter((error) => `Invalid JSON
 export const optional = (type) => ({
     ...createType("Optional", {
         fromUnknown: type.fromUnknown,
-        to: type.to,
         fromParent: type.fromParent,
-        toParent: type.toParent,
     }),
     parent: type,
 });
@@ -1708,7 +1856,7 @@ export const isOptionalType = (x) => typeof x === "object" && x != null && "name
 /**
  * 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.
  *
@@ -1779,114 +1927,86 @@ export function omit(objectType, ...keys) {
     }
     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 = (type, name) => {
-    const BrandedJsonString = brand(name, String, (value) => {
-        const jsonValue = JsonValueFromString.fromParent(value);
-        if (!jsonValue.ok)
-            return jsonValue;
-        const parsed = type.fromUnknown(jsonValue.value);
-        if (!parsed.ok)
-            return parsed;
-        return ok(value);
-    });
-    return transform(type, BrandedJsonString, (value) => ok(JSON.stringify(value)), 
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    (value) => JSON.parse(value));
-};
+export const validMutationSize = (type) => brand("ValidMutationSize", type, (value) => pack(value).byteLength <= maxMutationSize
+    ? ok(value)
+    : err({ type: "ValidMutationSize", value }));
+export const formatValidMutationSizeError = createTypeErrorFormatter((error) => `The mutation size exceeds the maximum limit of ${maxMutationSize} bytes. The provided mutation has a size of ${pack(error.value).byteLength} bytes.`);
 /**
- * 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.
+ *
+ * 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.
  *
- * If you prefer not to reuse any built-in error formatters, you can write your
- * own `formatTypeError` function from scratch.
+ * The `createFormatTypeError` function handles both built-in {@link TypeErrors}
+ * and custom errors, and lets us override default formatting for specific
+ * errors.
  *
- * ### Examples
+ * ### 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,
  *       )!;
@@ -1927,8 +2047,8 @@ export const createFormatTypeError = (extraFormatter) => {
                 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":
@@ -1943,6 +2063,8 @@ export const createFormatTypeError = (extraFormatter) => {
                 return formatRegexError(error);
             case "Id":
                 return formatIdError(error);
+            case "TableId":
+                return formatTableIdError(error);
             case "Positive":
                 return formatPositiveError(error);
             case "Negative":
@@ -1973,14 +2095,12 @@ export const createFormatTypeError = (extraFormatter) => {
                 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);
@@ -1996,7 +2116,88 @@ export const createFormatTypeError = (extraFormatter) => {
                 return formatUnionError(formatTypeError)(error);
             case "Tuple":
                 return formatTupleError(formatTypeError)(error);
+            default: {
+                // Fallback for unknown error types
+                const unknownError = error;
+                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 = (error, formatTypeError, path = []) => {
+    if (error.type === "Array") {
+        const arrayError = error;
+        if (arrayError.reason.kind === "NotArray") {
+            return [{ message: formatTypeError(error), path }];
+        }
+        return typeErrorToStandardSchemaIssues(arrayError.reason.error, formatTypeError, [...path, arrayError.reason.index]);
+    }
+    if (error.type === "Object") {
+        const objectError = error;
+        if (objectError.reason.kind === "NotObject" ||
+            objectError.reason.kind === "ExtraKeys") {
+            return [{ message: formatTypeError(error), path }];
+        }
+        const issues = [];
+        for (const [key, propError] of Object.entries(objectError.reason.errors)) {
+            issues.push(...typeErrorToStandardSchemaIssues(propError, formatTypeError, [...path, key]));
+        }
+        return issues;
+    }
+    if (error.type === "ObjectWithRecord") {
+        const objectWithRecordError = error;
+        if (objectWithRecordError.reason.kind === "NotObject") {
+            return [{ message: formatTypeError(error), path }];
+        }
+        if (objectWithRecordError.reason.kind === "IndexKey" ||
+            objectWithRecordError.reason.kind === "IndexValue") {
+            return typeErrorToStandardSchemaIssues(objectWithRecordError.reason.error, formatTypeError, [...path, objectWithRecordError.reason.key]);
+        }
+        const issues = [];
+        for (const [key, propError] of Object.entries(objectWithRecordError.reason.errors)) {
+            issues.push(...typeErrorToStandardSchemaIssues(propError, formatTypeError, [...path, key]));
+        }
+        return issues;
+    }
+    if (error.type === "Record") {
+        const recordError = error;
+        if (recordError.reason.kind === "NotRecord") {
+            return [{ message: formatTypeError(error), path }];
+        }
+        return typeErrorToStandardSchemaIssues(recordError.reason.error, formatTypeError, [...path, recordError.reason.key]);
+    }
+    if (error.type === "Tuple") {
+        const tupleError = error;
+        if (tupleError.reason.kind === "InvalidLength") {
+            return [{ message: formatTypeError(error), path }];
+        }
+        return typeErrorToStandardSchemaIssues(tupleError.reason.error, formatTypeError, [...path, tupleError.reason.index]);
+    }
+    if (error.type === "Union") {
+        const unionError = error;
+        return unionError.errors.flatMap((err) => typeErrorToStandardSchemaIssues(err, formatTypeError, path));
+    }
+    if (error.type === "Brand") {
+        const brandError = error;
+        if ("parentError" in brandError) {
+            return typeErrorToStandardSchemaIssues(brandError.parentError, formatTypeError, path);
+        }
+        return [{ message: formatTypeError(error), path }];
+    }
+    return [{ message: formatTypeError(error), path }];
+};
+/**
+ * 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;