@evolu/common 6.0.1-preview.9 → 7.0.0

package/dist/src/Type.d.ts

@@ -1,77 +1,210 @@
 /**
- * 🧩 Validation, Parsing, and Transformation
+ * 🧩 Type-safe runtime types
  *
- * ## Intro
+ * Evolu {@link Type} is like a type guard that returns typed errors (via
+ * {@link Result}) instead of throwing. We either get a safely typed value or a
+ * composable typed error telling us exactly why validation failed.
  *
- * You probably know [Zod](https://zod.dev). Evolu has {@link Type}.
+ * Why another validation library?
  *
- * Evolu Type exists because no existing validation/parsing/transformation
- * library fully met our needs:
+ * - **Result-based error handling** – no exceptions for normal control flow.
+ * - **Typed errors with decoupled formatters** – validation logic ≠ user
+ *   messages.
+ * - **Consistent constraints via {@link Brand}** – every constraint becomes part
+ *   of the type.
+ * - **Skippable validation** – parent validations can be skipped when already
+ *   proved by types.
+ * - **Simple, top-down implementation** – readable source code from top to
+ *   bottom.
+ * - **No user-land chaining DSL** – prepared for TC39 Hack pipes.
  *
- * - **Result-based error handling**: Leveraging {@link Result} instead of throwing
- *   exceptions.
- * - **Consistent constraints**: Enforcing {@link Brand} for all constraints.
- * - **Typed errors with decoupled formatters**: Avoiding coupling error messages
- *   with validators.
- * - **No user-land chaining**: Designed with ES pipe operator in mind.
- * - **Selective validation/transformation**: Skipping parent Type validations and
- *   transformations when TypeScript's type system can be relied upon.
- * - **Bidirectional transformations**: Supporting transformations in both
- *   directions.
- * - **Minimal and transparent code**: No runtime dependencies or hidden magic.
+ * A distinctive feature of Evolu Type compared to other validation libraries is
+ * that it returns typed errors rather than string messages. This allows
+ * TypeScript to enforce that all validation errors are handled by type
+ * checking, significantly improving the developer experience.
  *
- * **Note**: A proper quickstart guide is on the way. In the meantime, each type
- * includes its own usage example, and you can (and should) check the tests for
- * practical demonstrations of the API. Or dang, just read the code. It's
- * simple.
+ * Evolu Type supports [Standard Schema](https://standardschema.dev/) for
+ * interoperability with 40+ validation-compatible tools and frameworks.
  *
- * - Evolu `Type` is:
+ * ### Base Types Quick Start
  *
- * - A TypeScript type with a {@link Brand} whenever it's possible.
- * - A function to create a value of that type, which may fail.
- * - A function to transform value back to its original representation, which
- *   cannot fail.
+ * ```ts
+ * // Validate unknown values
+ * const value: unknown = "hello";
+ * const stringResult = String.fromUnknown(value);
+ * if (!stringResult.ok) {
+ *   // console.error(formatStringError(stringResult.error));
+ *   return stringResult; // inside a function returning Result<string, _>
+ * }
+ * // Safe branch: value is now string
+ * const upper = stringResult.value.toUpperCase();
+ *
+ * // Type guard style
+ * if (String.is(value)) {
+ *   // narrowed to string
+ * }
+ *
+ * // Composing: arrays & objects
+ * const Numbers = array(Number); // ReadonlyArray<number>
+ * const Point = object({ x: Number, y: Number });
+ *
+ * Numbers.from([1, 2, 3]); // ok
+ * Point.from({ x: 1, y: 2 }); // ok
+ * Point.from({ x: 1, y: "2" }); // err -> nested Number error
+ * ```
+ *
+ * ### Branding Basics
+ *
+ * Branding adds semantic meaning & constraints while preserving the runtime
+ * shape:
+ *
+ * ```ts
+ * const CurrencyCode = brand("CurrencyCode", String, (value) =>
+ *   /^[A-Z]{3}$/.test(value)
+ *     ? ok(value)
+ *     : err<CurrencyCodeError>({ type: "CurrencyCode", value }),
+ * );
+ * type CurrencyCode = typeof CurrencyCode.Type; // string & Brand<"CurrencyCode">
+ *
+ * interface CurrencyCodeError extends TypeError<"CurrencyCode"> {}
+ *
+ * const formatCurrencyCodeError =
+ *   createTypeErrorFormatter<CurrencyCodeError>(
+ *     (error) => `Invalid currency code: ${error.value}`,
+ *   );
+ *
+ * const r = CurrencyCode.from("USD"); // ok("USD")
+ * const e = CurrencyCode.from("usd"); // err(...)
+ * ```
+ *
+ * See also reusable brand factories like `minLength`, `maxLength`, `trimmed`,
+ * `positive`, `between`, etc.
+ *
+ * ### Objects & Optional Fields
+ *
+ * ```ts
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: optional(PositiveInt),
+ * });
+ * type User = typeof User.Type;
+ *
+ * User.from({ name: "Alice" }); // ok
+ * User.from({ name: "Alice", age: -1 }); // err(PositiveInt)
+ * ```
+ *
+ * ### Deriving JSON String Types
+ *
+ * ```ts
+ * const Person = object({
+ *   name: NonEmptyString50,
+ *   // Did you know that JSON.stringify converts NaN (a number) into null?
+ *   // To prevent this, use FiniteNumber.
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
+ *
+ * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
+ *   Person,
+ *   "PersonJson",
+ * );
+ * // string & Brand<"PersonJson">
+ * type PersonJson = typeof PersonJson.Type;
+ *
+ * const person = Person.orThrow({
+ *   name: "Alice",
+ *   age: 30,
+ * });
+ *
+ * const personJson = personToPersonJson(person);
+ * expect(personJsonToPerson(personJson)).toEqual(person);
+ * ```
+ *
+ * ### Error Formatting
  *
- * 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:
+ * Evolu separates validation logic from human-readable messages. There are two
+ * layers:
  *
- * `Unknown` -> `String` -> `TrimmedString` -> `NonEmptyTrimmedString100`
+ * 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.
  *
- * For `NonEmptyTrimmedString100`, the parent Type is `TrimmedString`. For
- * `TrimmedString`, the parent Type is `String`.
+ * #### 1. Per-Type Formatter (recap)
  *
- * 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.
+ * ```ts
+ * const r = String.fromUnknown(42);
+ * if (!r.ok) console.error(formatStringError(r.error));
+ * ```
+ *
+ * #### 2. Unified Formatter with Overrides
  *
- * Speaking of `fromParent` and `toParent`, those functions exist to bypass
- * parent Types when we can rely on TypeScript types.
+ * ```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}`;
+ * });
  *
- * `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")`.
+ * 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: No Bidirectional Transformations
+ *
+ * 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.
+ *
+ * ### Prepared for TC39 Hack Pipes
  *
- * ### Design Decision:
+ * Take a look how `SimplePassword` is defined:
  *
- * 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.
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper) and read well, but with
+ * TC39 Hack pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
+ * Note `minLength` and `maxLength` are curried because they are factories.
  *
  * @module
  */
-import { NanoIdLibDep } from "./NanoId.js";
-import { Ok, Result } from "./Result.js";
-import type { Brand, Literal, Simplify, WidenLiteral } from "./Types.js";
+import type { Brand } from "./Brand.js";
+import { type RandomBytesDep } from "./Crypto.js";
+import { Result } from "./Result.js";
+import type { TimeDep } from "./Time.js";
+import type { Literal, Simplify, WidenLiteral } from "./Types.js";
 export interface Type<Name extends TypeName, 
 /** The type this Type resolves to. */
 T, 
@@ -82,7 +215,7 @@ Error extends TypeError = never,
 /** The parent type. */
 Parent = T, 
 /** The parent's error. */
-ParentError extends TypeError = Error> {
+ParentError extends TypeError = Error> extends StandardSchemaV1<Input, T> {
     readonly name: Name;
     /**
      * Creates `T` from an `Input` value.
@@ -93,38 +226,95 @@ ParentError extends TypeError = Error> {
      */
     readonly from: (value: Input) => Result<T, ParentError | Error>;
     /**
-     * Creates `T` from an unknown value.
+     * Creates `T` from an `Input` value, throwing an error if validation fails.
      *
-     * This is useful when a value is unknown.
-     */
-    readonly fromUnknown: (value: unknown) => Result<T, ParentError | Error>;
-    /**
-     * The opposite of `from` and `fromUnknown`.
+     * Throws an Error with the Type validation error in its `cause` property,
+     * making it debuggable while avoiding the need for custom error messages.
+     *
+     * This is a convenience method that combines `from` with `getOrThrow`.
      *
-     * 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.
+     * - Configuration values that are guaranteed to be valid (e.g., hardcoded
+     *   constants)
+     * - Application startup where failure should crash the program
+     * - As an alternative to assertions when the Type error in the thrown Error's
+     *   `cause` provides sufficient debugging information
+     * - Test code with known valid inputs (when error message clarity is not
+     *   critical; for better test error messages, use Vitest `schemaMatching` +
+     *   `assert` with `.is()`)
+     *
+     * ### Example
+     *
+     * ```ts
+     * // ✅ Good: Known valid constant
+     * const maxRetries = PositiveInt.orThrow(3);
+     *
+     * // ✅ Good: App configuration that should crash on invalid values
+     * const appName = SimpleName.orThrow("MyApp");
+     *
+     * // ✅ Good: Instead of assert when Type error is clear enough
+     * // Context makes it obvious: count increments from non-negative value
+     * const currentCount = counts.get(id) ?? 0;
+     * const newCount = PositiveInt.orThrow(currentCount + 1);
+     *
+     * // ✅ Good: Test setup with known valid values
+     * const testUser = User.orThrow({ name: "Alice", age: 30 });
+     *
+     * // ❌ Avoid: User input (use `from` instead)
+     * const userAge = PositiveInt.orThrow(userInput); // Could crash!
+     *
+     * // ✅ Better: Handle user input gracefully
+     * const ageResult = PositiveInt.from(userInput);
+     * if (!ageResult.ok) {
+     *   // Handle validation error
+     * }
+     * ```
      */
-    readonly to: (value: T) => Input;
+    readonly orThrow: (value: Input) => T;
     /**
-     * Creates `T` from `Parent` type.
+     * Creates `T` from an `Input` value, returning `null` if validation fails.
+     *
+     * This is a convenience method that combines `from` with `getOrNull`.
      *
-     * This function skips parent Types validations/transformations when we have
-     * already partially validated/transformed value.
+     * **When 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`.
+     * - When you need to convert a validation result to a nullable value
+     * - When the error is not important and you just want the value or nothing
      *
      * ### Example
      *
      * ```ts
-     * // string & Brand<"Trimmed">
-     * const value = TrimString.fromParent("a ").value; // as efficient as foo.trim()
+     * // ✅ Good: Optional user input
+     * const age = PositiveInt.orNull(userInput);
+     * if (age != null) {
+     *   console.log("Valid age:", age);
+     * }
+     *
+     * // ✅ Good: Default fallback
+     * const maxRetries = PositiveInt.orNull(config.retries) ?? 3;
+     *
+     * // ❌ Avoid: When you need to know why validation failed (use `from` instead)
+     * const result = PositiveInt.from(userInput);
+     * if (!result.ok) {
+     *   console.error(formatPositiveError(result.error));
+     * }
      * ```
      */
+    readonly orNull: (value: Input) => T | null;
+    /**
+     * 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>;
-    /** The opposite of `fromParent`. */
-    readonly toParent: (value: T) => Parent;
     /**
      * A **type guard** that checks whether an unknown value satisfies the
      * {@link Type}.
@@ -197,8 +387,6 @@ ParentError extends TypeError = Error> {
      */
     readonly ParentError: ParentError;
     /**
-     * Error | ParentError
-     *
      * ### Example
      *
      * ```ts
@@ -230,12 +418,47 @@ export interface TypeErrorWithReason<Name extends TypeName = TypeName, Reason ex
     readonly reason: Reason;
 }
 export type AnyType = Type<any, any, any, any, any, any>;
+/**
+ * Extracts the name from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferName<A extends AnyType> = A extends Type<infer Name, any, any, any, any, any> ? Name : never;
+/**
+ * Extracts the type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferType<A extends AnyType> = A extends Type<any, infer T, any, any, any, any> ? T : never;
+/**
+ * Extracts the input type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferInput<A extends AnyType> = A extends Type<any, any, infer Input, any, any, any> ? Input : never;
+/**
+ * Extracts the specific error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferError<A extends AnyType> = A extends Type<any, any, any, infer Error, any, any> ? Error : never;
+/**
+ * Extracts the parent type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParent<A extends AnyType> = A extends Type<any, any, any, any, infer Parent, any> ? Parent : never;
+/**
+ * Extracts the parent error type from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferParentError<A extends AnyType> = A extends Type<any, any, any, any, any, infer ParentError> ? ParentError : never;
+/**
+ * Extracts all error types from a {@link Type}.
+ *
+ * @category Utilities
+ */
 export type InferErrors<T extends AnyType> = T extends Type<any, any, any, infer Error, any, infer ParentError> ? Error | ParentError : never;
 declare const EvoluTypeSymbol: unique symbol;
 /**
@@ -268,12 +491,6 @@ export type TypeErrorFormatter<Error extends TypeError> = (error: Error) => stri
  * 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
  *
@@ -410,7 +627,7 @@ export declare const formatIsTypeError: TypeErrorFormatter<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
  *
@@ -489,7 +706,7 @@ export declare const formatIsTypeError: TypeErrorFormatter<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",
@@ -567,17 +784,19 @@ export declare const formatCurrencyCodeError: TypeErrorFormatter<CurrencyCodeErr
  * ### 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 declare const DateIsoString: BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoStringError, StringError>;
-export type DateIsoString = typeof DateIsoString.Type;
-export interface DateIsoStringError extends TypeError<"DateIsoString"> {
+export declare const DateIso: BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoError, StringError>;
+export type DateIso = typeof DateIso.Type;
+export interface DateIsoError extends TypeError<"DateIso"> {
 }
-export declare const formatDateIsoStringError: TypeErrorFormatter<DateIsoStringError>;
+export declare const formatDateIsoError: TypeErrorFormatter<DateIsoError>;
+export declare const dateToDateIso: (value: Date) => Result<DateIso, DateIsoError>;
+export declare const dateIsoToDate: (value: DateIso) => Date;
 /**
  * Helper type for Type Factory that creates a branded Type.
  *
@@ -600,18 +819,12 @@ export type BrandFactory<Name extends TypeName, Input, RefineError extends TypeE
 /**
  * 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;
@@ -623,33 +836,6 @@ export declare const trimmed: BrandFactory<"Trimmed", string, TrimmedError>;
 export interface TrimmedError extends TypeError<"Trimmed"> {
 }
 export declare const formatTrimmedError: TypeErrorFormatter<TrimmedError>;
-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 declare const trim: TransformBrandFactory<"Trimmed", string>;
 /**
  * Trimmed string
  *
@@ -660,6 +846,7 @@ export declare const trim: TransformBrandFactory<"Trimmed", string>;
  */
 export declare const TrimmedString: BrandType<Type<"String", string, string, StringError, string, StringError>, "Trimmed", TrimmedError, StringError>;
 export type TrimmedString = typeof TrimmedString.Type;
+export declare const trim: (value: string) => TrimmedString;
 /**
  * Minimum length.
  *
@@ -782,9 +969,9 @@ export interface RegexError<Name extends TypeName = TypeName> extends TypeError<
 }
 export declare const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<string>>>;
 /**
- * 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`)
@@ -792,33 +979,49 @@ export declare const formatRegexError: TypeErrorFormatter<RegexError<Capitalize<
  * - 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 declare const Base64Url: BrandType<Type<"String", string, string, StringError, string, StringError>, "Base64Url", RegexError<"Base64Url">, StringError>;
-export type Base64Url = typeof Base64Url.Type;
-export type Base64UrlError = typeof Base64Url.Error;
+export declare const UrlSafeString: BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>;
+export type UrlSafeString = typeof UrlSafeString.Type;
+export type UrlSafeStringError = typeof UrlSafeString.Error;
 /**
- * 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 declare const Base64Url: BrandType<Type<"String", string, string, StringError, string, StringError>, "Base64Url", Base64UrlError, StringError>;
+export type Base64Url = typeof Base64Url.Type;
+export interface Base64UrlError extends TypeError<"Base64Url"> {
+}
+export declare const formatBase64UrlError: TypeErrorFormatter<Base64UrlError>;
+/** Encodes a Uint8Array to a {@link Base64Url} string. */
+export declare const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url;
+/** Decodes a {@link Base64Url} string to a Uint8Array. */
+export declare const base64UrlToUint8Array: (str: Base64Url) => Uint8Array;
+/**
+ * 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.
+ * The string must be between 1 and 64 characters.
  *
  * ### Example
  *
@@ -833,20 +1036,32 @@ export type Base64UrlError = typeof Base64Url.Error;
  *
  * @category String
  */
-export declare const SimpleName: BrandType<Type<"String", string, string, StringError, string, StringError>, "SimpleName", RegexError<"SimpleName">, StringError>;
+export declare const SimpleName: BrandType<BrandType<Type<"String", string, string, StringError, string, StringError>, "UrlSafeString", RegexError<"UrlSafeString">, StringError>, "SimpleName", SimpleNameError, StringError | RegexError<"UrlSafeString">>;
 export type SimpleName = typeof SimpleName.Type;
-export type SimpleNameError = typeof SimpleName.Error;
-/**
- * Default NanoId.
- *
- * @category String
- */
-export declare const NanoId: BrandType<Type<"String", string, string, StringError, string, StringError>, "NanoId", RegexError<"NanoId">, StringError>;
-export type NanoId = typeof NanoId.Type;
-export type NanoIdError = typeof NanoId.Error;
+export interface SimpleNameError extends TypeError<"SimpleName"> {
+}
 /**
  * Trimmed string between 8 and 64 characters, branded as `SimplePassword`.
  *
+ * Take a look how `SimplePassword` is defined:
+ *
+ * ```ts
+ * export const SimplePassword = brand(
+ *   "SimplePassword",
+ *   minLength(8)(maxLength(64)(TrimmedString)),
+ * );
+ * ```
+ *
+ * Nested functions are often OK (if not, make a helper), but with TC39 Hack
+ * pipes it would be clearer:
+ *
+ * ```ts
+ * // TrimmedString
+ * //   |> minLength(8)(%)
+ * //   |> maxLength(64)(%)
+ * //   |> brand("SimplePassword", %)
+ * ```
+ *
  * @category String
  */
 export declare const SimplePassword: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed"> & Brand<"MaxLength64">, string, MaxLengthError<64>, string & Brand<"Trimmed">, StringError | TrimmedError>, "MinLength8", MinLengthError<8>, StringError | TrimmedError | MaxLengthError<64>>, "SimplePassword", BrandWithoutRefineError<"SimplePassword", StringError | TrimmedError | MinLengthError<8> | MaxLengthError<64>>, never>;
@@ -854,29 +1069,104 @@ export type SimplePassword = typeof SimplePassword.Type;
 export type SimplePasswordError = typeof SimplePassword.Error;
 export declare const formatSimplePasswordError: (formatTypeError: TypeErrorFormatter<StringError | MinLengthError<8> | MaxLengthError<64> | TrimmedError>) => TypeErrorFormatter<SimplePasswordError>;
 /**
- * `Id` {@link Type}.
+ * Evolu Id: 16 bytes encoded as a 22‑character Base64Url string.
+ *
+ * There are three ways to create an Evolu Id:
+ *
+ * - {@link createId} – default cryptographically secure random bytes
+ *   (privacy‑preserving)
+ * - {@link createIdFromString} – deterministic: first 16 bytes of SHA‑256 of a
+ *   string
+ * - {@link createIdAsUuidv7} – optional: embeds timestamp bits (UUID v7 layout)
+ *
+ * Privacy: the default random Id does not leak creation time and is safe to
+ * share or log. The UUID v7 variant leaks creation time anywhere the Id is
+ * copied (logs, URLs, exports); only use it when you explicitly want insertion
+ * locality for very large write‑heavy tables and accept timestamp exposure.
+ *
+ * ### Future
  *
- * Represents a unique identifier with exactly 21 characters, using NanoID's
- * standard format (`A-Za-z0-9_-`).
+ * A possible hybrid masked‑time approach (`timestamp ^ H(cluster_id, timestamp
+ *
+ * > > N)`) could provide locality without exposing raw creation time. See
+ * > > https://brooker.co.za/blog/2025/10/22/uuidv7.html
  *
  * @category String
  */
-export declare const Id: BrandType<Type<"String", string, string, StringError, string, StringError>, "Id", RegexError<"Id">, StringError>;
+export declare const Id: BrandType<Type<"String", string, string, StringError, string, StringError>, "Id", IdError, StringError>;
 export type Id = typeof Id.Type;
-export declare const idTypeValueLength = 21;
+export interface IdError extends TypeError<"Id"> {
+}
+export declare const formatIdError: TypeErrorFormatter<IdError>;
 /**
- * Creates an {@link Id}.
+ * Creates a random {@link Id}. This is the recommended default.
+ *
+ * Use {@link createIdFromString} for deterministic mapping of external IDs or
+ * {@link createIdAsUuidv7} when you accept timestamp leakage for index
+ * locality.
  *
  * ### Example
  *
  * ```ts
- * // string & Brand<"Id">
  * const id = createId(deps);
+ * const todoId = createId<"Todo">(deps);
  * ```
  */
-export declare const createId: (deps: NanoIdLibDep) => Id;
+export declare const createId: <B extends string = never>(deps: RandomBytesDep) => [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 uses the first 16 bytes of SHA-256 hash of
+ * the string bytes, therefore it's not possible to recover the original
+ * external string from the generated {@link Id}. If you need to preserve the
+ * original external ID, store it in a separate column.
+ *
+ * @category String
+ */
+export declare const createIdFromString: <B extends string = never>(value: string) => [B] extends [never] ? Id : Id & Brand<B>;
+/**
+ * Creates an {@link Id} embedding timestamp bits (UUID v7 layout) before
+ * Base64Url encoding.
+ *
+ * Tradeoff: better insertion locality / index performance for huge datasets vs
+ * leaking creation time everywhere the Id appears. Evolu uses {@link createId}
+ * by default to avoid activity leakage; choose this only if you explicitly
+ * accept timestamp exposure.
+ *
+ * ### Example
+ *
+ * ```ts
+ * const id = createIdAsUuidv7({ randomBytes, time });
+ * const todoId = createIdAsUuidv7<"Todo">({ randomBytes, time });
+ * ```
+ */
+export declare const createIdAsUuidv7: <B extends string = never>(deps: RandomBytesDep & TimeDep) => [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
  *
@@ -888,16 +1178,22 @@ export declare const createId: (deps: NanoIdLibDep) => Id;
  *
  * @category String
  */
-export declare const id: <Table extends TypeName>(table: Table) => IdType<Table>;
-export interface IdType<Table extends TypeName> extends Type<"Id", string & Brand<"Id"> & Brand<Table>, string, IdError<Table>, string, StringError> {
+export declare const id: <Table extends TypeName>(table: Table) => TableId<Table>;
+export interface TableId<Table extends TypeName> extends Type<"Id", string & Brand<"Id"> & Brand<Table>, string, 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 declare const formatIdError: TypeErrorFormatter<IdError<Capitalize<string>>>;
+export declare const formatTableIdError: TypeErrorFormatter<TableIdError<Capitalize<string>>>;
+/** Binary representation of an {@link Id}. */
+export declare const IdBytes: BrandType<BrandType<Type<"Uint8Array", Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>, Uint8ArrayError, Uint8Array<ArrayBufferLike>, Uint8ArrayError>, "Length16", LengthError<16>, Uint8ArrayError>, "IdBytes", BrandWithoutRefineError<"IdBytes", LengthError<16> | Uint8ArrayError>, never>;
+export type IdBytes = typeof IdBytes.Type;
+export declare const idBytesTypeValueLength: NonNegativeInt;
+export declare const idToIdBytes: (id: Id) => IdBytes;
+export declare const idBytesToId: (idBytes: IdBytes) => Id;
 /**
- * Positive number.
+ * Positive number (> 0).
  *
  * ### Example
  *
@@ -915,7 +1211,7 @@ export interface PositiveError extends TypeError<"Positive"> {
 }
 export declare const formatPositiveError: TypeErrorFormatter<PositiveError>;
 /**
- * Negative number.
+ * Negative number (< 0).
  *
  * ### Example
  *
@@ -930,7 +1226,7 @@ export interface NegativeError extends TypeError<"Negative"> {
 }
 export declare const formatNegativeError: TypeErrorFormatter<NegativeError>;
 /**
- * Non-positive number.
+ * Non-positive number (≤ 0).
  *
  * ### Example
  *
@@ -945,7 +1241,7 @@ export interface NonPositiveError extends TypeError<"NonPositive"> {
 }
 export declare const formatNonPositiveError: TypeErrorFormatter<NonPositiveError>;
 /**
- * Non-negative number.
+ * Non-negative number (≥ 0).
  *
  * ### Example
  *
@@ -959,16 +1255,32 @@ export declare const nonNegative: BrandFactory<"NonNegative", number, NonNegativ
 export interface NonNegativeError extends TypeError<"NonNegative"> {
 }
 export declare const formatNonNegativeError: TypeErrorFormatter<NonNegativeError>;
-/** @category Number */
+/**
+ * Non-negative number (≥ 0).
+ *
+ * @category Number
+ */
 export declare const NonNegativeNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonNegative", NonNegativeError, NumberError>;
 export type NonNegativeNumber = typeof NonNegativeNumber.Type;
-/** @category Number */
-export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NumberError | NonNegativeError>;
+/**
+ * Positive number (> 0).
+ *
+ * @category Number
+ */
+export declare const PositiveNumber: BrandType<Type<"Brand", number & Brand<"NonNegative">, number, NonNegativeError, number, NumberError>, "Positive", PositiveError, NonNegativeError | NumberError>;
 export type PositiveNumber = typeof PositiveNumber.Type;
-/** @category Number */
+/**
+ * Non-positive number (≤ 0).
+ *
+ * @category Number
+ */
 export declare const NonPositiveNumber: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "NonPositive", NonPositiveError, NumberError>;
 export type NonPositiveNumber = typeof NonPositiveNumber.Type;
-/** @category Number */
+/**
+ * Negative number (< 0).
+ *
+ * @category Number
+ */
 export declare const NegativeNumber: BrandType<Type<"Brand", number & Brand<"NonPositive">, number, NonPositiveError, number, NumberError>, "Negative", NegativeError, NumberError | NonPositiveError>;
 export type NegativeNumber = typeof NegativeNumber.Type;
 /**
@@ -993,17 +1305,35 @@ export declare const formatIntError: TypeErrorFormatter<IntError>;
  */
 export declare const Int: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Int", IntError, NumberError>;
 export type Int = typeof Int.Type;
-/** @category Number */
-export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, NumberError | IntError>;
+/**
+ * Non-negative integer (≥ 0).
+ *
+ * @category Number
+ */
+export declare const NonNegativeInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonNegative", NonNegativeError, IntError | NumberError>;
 export type NonNegativeInt = typeof NonNegativeInt.Type;
-/** @category Number */
-export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, NumberError | IntError>, "Positive", PositiveError, NumberError | NonNegativeError | IntError>;
+/**
+ * Positive integer (> 0).
+ *
+ * @category Number
+ */
+export declare const PositiveInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonNegative">, number, NonNegativeError, number & Brand<"Int">, IntError | NumberError>, "Positive", PositiveError, NonNegativeError | IntError | NumberError>;
 export type PositiveInt = typeof PositiveInt.Type;
-/** @category Number */
-export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, NumberError | IntError>;
+/** Maximum safe positive integer value for practically infinite operations. */
+export declare const maxPositiveInt: number & Brand<"Int"> & Brand<"NonNegative"> & Brand<"Positive">;
+/**
+ * Non-positive integer (≤ 0).
+ *
+ * @category Number
+ */
+export declare const NonPositiveInt: BrandType<Type<"Brand", number & Brand<"Int">, number, IntError, number, NumberError>, "NonPositive", NonPositiveError, IntError | NumberError>;
 export type NonPositiveInt = typeof NonPositiveInt.Type;
-/** @category Number */
-export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, NumberError | IntError>, "Negative", NegativeError, NumberError | NonPositiveError | IntError>;
+/**
+ * Negative integer (< 0).
+ *
+ * @category Number
+ */
+export declare const NegativeInt: BrandType<Type<"Brand", number & Brand<"Int"> & Brand<"NonPositive">, number, NonPositiveError, number & Brand<"Int">, IntError | NumberError>, "Negative", NegativeError, IntError | NumberError | NonPositiveError>;
 export type NegativeInt = typeof NegativeInt.Type;
 /**
  * Number greater than a specified value.
@@ -1110,9 +1440,6 @@ export interface BetweenError<Min extends number = number, Max extends number =
     readonly max: Max;
 }
 export declare const formatBetweenError: TypeErrorFormatter<BetweenError<number, number>>;
-/** @category Number */
-export declare const Between1And10: BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Between1-10", BetweenError<1, 10>, NumberError>;
-export type Between1And10 = typeof Between1And10.Type;
 /**
  * Literal {@link Type}.
  *
@@ -1138,67 +1465,6 @@ export interface LiteralError<T extends Literal = Literal> extends TypeError<"Li
     readonly expected: T;
 }
 export declare const formatLiteralError: TypeErrorFormatter<LiteralError<Literal>>;
-/**
- * {@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 declare 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>;
-/**
- * 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 declare const TrimString: TransformType<Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"String", string, string, StringError, string, StringError>, "Trimmed", never, StringError>, never>;
-/**
- * Transforms a {@link Date} into a {@link DateIsoString} string and vice versa.
- *
- * ### Example
- *
- * TODO:
- *
- * @category String
- */
-export declare const DateIso: TransformType<InstanceOfType<DateConstructor>, BrandType<Type<"String", string, string, StringError, string, StringError>, "DateIso", DateIsoStringError, StringError>, DateIsoStringError>;
-/**
- * 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 declare const NumberFromString: TransformType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, NumberFromStringError>;
-export interface NumberFromStringError extends TypeError<"NumberFromString"> {
-}
-export declare const formatNumberFromStringError: TypeErrorFormatter<NumberFromStringError>;
 /**
  * Array of a specific {@link Type}.
  *
@@ -1656,16 +1922,12 @@ export type Int64 = typeof Int64.Type;
 export interface Int64Error extends TypeError<"Int64"> {
 }
 export declare const formatInt64Error: TypeErrorFormatter<Int64Error>;
-export declare const BigIntFromString: TransformType<Type<"String", string, string, StringError, string, StringError>, Type<"BigInt", bigint, bigint, BigIntError, bigint, BigIntError>, BigIntFromStringError>;
-export interface BigIntFromStringError extends TypeError<"BigIntFromString"> {
-}
-export declare const formatBigIntFromStringError: TypeErrorFormatter<BigIntFromStringError>;
 /**
  * Stringified {@link Int64}.
  *
- * @category Number
+ * @category String
  */
-export declare const Int64String: BrandType<Type<"String", string, string, StringError, string, StringError>, "Int64", Int64StringError, StringError>;
+export declare const Int64String: BrandType<BrandType<Type<"Brand", string & Brand<"Trimmed">, string, TrimmedError, string, StringError>, "MinLength1", MinLengthError<1>, StringError | TrimmedError>, "Int64", Int64StringError, StringError | TrimmedError | MinLengthError<1>>;
 export type Int64String = typeof Int64String.Type;
 export interface Int64StringError extends TypeError<"Int64String"> {
 }
@@ -1700,42 +1962,63 @@ export declare const JsonArray: ArrayType<RecursiveType<UnionType<[Type<"String"
  * @category Object
  */
 export declare const JsonObject: RecordType<"String", string, string, StringError, string, StringError, RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>>;
+export declare const parseJson: (value: string) => Result<JsonValue, JsonError>;
 /**
- * Transform Type that parses a JSON into a {@link JsonValue} and serializes a
- * JsonValue back into a JSON string.
+ * JSON-string {@link Type}.
  *
  * ### Example
  *
  * ```ts
- * JsonValueFromString.from(`{"key":"value"}`); // -> ok({ key: "value" })
- * JsonValueFromString.to({ key: "value" }); // -> '{"key":"value"}'
+ * const result = Json.from('{"key":"value"}'); // ok
+ * const error = Json.from("invalid json"); // err
  * ```
  *
  * @category String
  */
-export declare const JsonValueFromString: TransformType<Type<"String", string, string, StringError, string, StringError>, RecursiveType<UnionType<[Type<"String", string, string, StringError, string, StringError>, BrandType<Type<"Number", number, number, NumberError, number, NumberError>, "Finite", FiniteError, NumberError>, Type<"Boolean", boolean, boolean, BooleanError, boolean, BooleanError>, Type<"Null", null, null, NullError, null, NullError>, ArrayType<Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>, RecordType<"String", string, string, StringError, string, StringError, Type<"Recursive", JsonValue, JsonValueInput, JsonValueError, JsonValueInput, JsonValueError>>]>>, JsonValueFromStringError>;
-export interface JsonValueFromStringError extends TypeError<"JsonValueFromString"> {
+export declare const Json: BrandType<Type<"String", string, string, StringError, string, StringError>, "Json", JsonError, StringError>;
+export type Json = typeof Json.Type;
+export interface JsonError extends TypeError<"Json"> {
     readonly message: string;
 }
-export declare const formatJsonValueFromStringError: TypeErrorFormatter<JsonValueFromStringError>;
+export declare const formatJsonError: TypeErrorFormatter<JsonError>;
+export declare const jsonValueToJson: (value: JsonValue) => Json;
+export declare const jsonToJsonValue: (value: Json) => JsonValue;
 /**
- * JSON-string {@link Type}.
+ * 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 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 Person = object({
+ *   name: NonEmptyString100,
+ *   age: FiniteNumber,
+ * });
+ * type Person = typeof Person.Type;
  *
- * @category String
+ * 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 declare const Json: BrandType<Type<"String", string, string, StringError, string, StringError>, "Json", JsonError, StringError>;
-export type Json = typeof Json.Type;
-export interface JsonError extends TypeError<"Json"> {
-    readonly message: string;
-}
-export declare const formatJsonError: TypeErrorFormatter<JsonError>;
+export declare 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>];
 /**
  * Optional {@link Type}.
  *
@@ -1766,7 +2049,7 @@ export declare 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.
  *
@@ -1812,36 +2095,18 @@ export type NullTypeInMembers<Members extends [AnyType, ...Array<AnyType>]> = Me
  * @category Object
  */
 export declare function omit<T extends ObjectType<any>, Keys extends keyof T["props"]>(objectType: T, ...keys: ReadonlyArray<Keys>): ObjectType<Omit<T["props"], Keys>>;
+export declare 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 declare const json: <T extends AnyType, Name extends TypeName>(type: T, name: Name) => TransformType<T, BrandType<typeof String, Name, JsonValueFromStringError | T["Errors"], StringError>>;
+export declare const validMutationSize: <T extends AnyType>(type: T) => BrandType<T, "ValidMutationSize", ValidMutationSizeError, InferErrors<T>>;
+export interface ValidMutationSizeError extends TypeError<"ValidMutationSize"> {
+}
+export declare const formatValidMutationSizeError: TypeErrorFormatter<ValidMutationSizeError>;
+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
  * errors (e.g., `StringError`, `NumberError`), composite type errors
@@ -1855,72 +2120,76 @@ export declare const json: <T extends AnyType, Name extends TypeName>(type: T, n
  *
  * @category Utilities
  */
-export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoStringError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | NanoIdError | SimplePasswordError | IdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | BigIntFromStringError | Int64StringError | JsonValueFromStringError | JsonError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | TupleError<TypeErrors<ExtraErrors>>;
+export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | NumberError | BigIntError | BooleanError | UndefinedError | NullError | FunctionError | Uint8ArrayError | InstanceOfError | EvoluTypeError | CurrencyCodeError | DateIsoError | TrimmedError | MinLengthError | MaxLengthError | LengthError | MnemonicError | RegexError | SimplePasswordError | IdError | TableIdError | PositiveError | NegativeError | NonPositiveError | NonNegativeError | IntError | GreaterThanError | LessThanError | GreaterThanOrEqualToError | LessThanOrEqualToError | NonNaNError | FiniteError | MultipleOfError | BetweenError | LiteralError | Int64Error | Int64StringError | JsonError | ValidMutationSizeError | ExtraErrors | ArrayError<TypeErrors<ExtraErrors>> | RecordError<TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | ObjectError<Record<string, TypeErrors<ExtraErrors>>> | ObjectWithRecordError<Record<string, TypeErrors<ExtraErrors>>, TypeErrors<ExtraErrors>, TypeErrors<ExtraErrors>> | UnionError<TypeErrors<ExtraErrors>> | 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,
  *       )!;
@@ -1933,5 +2202,69 @@ export type TypeErrors<ExtraErrors extends TypeError = never> = StringError | Nu
  * @category Utilities
  */
 export declare const createFormatTypeError: <ExtraErrors extends TypeError = never>(extraFormatter?: TypeErrorFormatter<ExtraErrors>) => TypeErrorFormatter<TypeErrors<ExtraErrors>>;
+/**
+ * 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 declare const typeErrorToStandardSchemaIssues: <ExtraErrors extends TypeError = never>(error: TypeErrors<ExtraErrors>, formatTypeError: TypeErrorFormatter<TypeErrors<ExtraErrors>>, path?: ReadonlyArray<PropertyKey>) => ReadonlyArray<StandardSchemaV1.Issue>;
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** The non-existent issues. */
+        readonly issues?: undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard Schema types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Schema. */
+    type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Schema. */
+    type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
 export {};
 //# sourceMappingURL=Type.d.ts.map