@evolu/common 8.7.0 → 8.8.0

package/dist/src/Type.d.ts

@@ -143,7 +143,7 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * const values: ReadonlyArray<unknown> = [42n, "42", null];
      * const integers = values.filter(Int64FromInt64String.is);
      *
-     * assertType<Array<Int64>, typeof integers>();
+     * assertType<typeof integers, Array<Int64>>();
      * assertTrue(Int64FromInt64String.is(42n));
      * assertFalse(Int64FromInt64String.is("42"));
      * ```
@@ -157,10 +157,10 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * Type toward the root. The deepest suffix accepts the root Output.
      *
      * Every entry point asserts its selected boundary before running the
-     * remaining pipeline. Assertion failures throw because they indicate a
-     * developer error. The Error message identifies the expected boundary Type,
-     * and its cause preserves the structured validation error. Only failures
-     * introduced after that boundary are returned through `Result`.
+     * remaining pipeline. Assertion failures throw because they indicate a bug
+     * that must be fixed. The Error message identifies the expected boundary
+     * Type, and its cause preserves the structured validation error. Only
+     * failures introduced after that boundary are returned through `Result`.
      *
      * ### Example
      *
@@ -205,8 +205,8 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * const result = saveTodo(title, note);
      *
      * assertType<
-     *   Result<typeof Todo.Output, MaxLengthError<100> | MinLengthError<1>>,
-     *   typeof result
+     *   typeof result,
+     *   Result<typeof Todo.Output, MaxLengthError<100> | MinLengthError<1>>
      * >();
      * assertOk(result, { title, note });
      * ```
@@ -240,7 +240,7 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * `from` operation, which accepts this Type's `Input`.
      *
      * The typed `Input` boundary is asserted before the remaining pipeline runs.
-     * A boundary violation throws a developer error directly; `getOrThrow` maps
+     * A boundary violation is a bug, so it throws directly; `getOrThrow` maps
      * only a validation error returned after that boundary.
      *
      * `Type.orThrow.parent(value)` does not exist. To throw after starting from a
@@ -278,8 +278,8 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
      * `from` operation, which accepts this Type's `Input`.
      *
      * The typed `Input` boundary is asserted before the remaining pipeline runs.
-     * A boundary violation throws a developer error directly; `getOrNull` maps
-     * only a validation error returned after that boundary to `null`.
+     * A boundary violation is a bug, so it throws directly; `getOrNull` maps only
+     * a validation error returned after that boundary to `null`.
      *
      * `Type.orNull.parent(value)` does not exist. To return `null` after starting
      * from a typed boundary, call `getOrNull` with the corresponding `from`
@@ -380,18 +380,18 @@ export interface TypeNode {
     readonly is: (value: unknown) => boolean;
 }
 /**
- * Asserts exact compile-time type equality or that a value belongs to a
- * {@link Type} Output domain.
+ * Asserts type equality or validates a value with a {@link Type}.
  *
- * - `assertType<Expected, Actual>()` requires compiler-identical types without
- *   evaluating a value.
+ * - `assertType<Actual, Expected>()` requires compiler-identical types without
+ *   evaluating a value. It is Evolu's platform-agnostic equivalent of Vitest's
+ *   `expectTypeOf(...).toEqualTypeOf<...>()` and does not require a test
+ *   runner.
  * - `assertType(type, value)` validates and narrows a runtime value to the Type's
  *   Output.
  *
- * Use the runtime form for internal invariants, not external input. Validate
- * external input with `Type.fromUnknown` so validation failures remain typed
- * values. A failed runtime assertion uses the Type name for its message and
- * preserves the exact Output validation error as the thrown Error's cause.
+ * Use the runtime form for code-correctness invariants, not expected validation
+ * failures. Validate external input with `Type.fromUnknown` so validation
+ * failures remain typed values.
  *
  * ### Example
  *
@@ -405,18 +405,15 @@ export interface TypeNode {
  * const value: unknown = "Evolu";
  * assertType(NonEmptyTrimmedString100, value);
  * assertType<
- *   string &
- *     Brand<"Trimmed"> &
- *     Brand<"MinLength1"> &
- *     Brand<"MaxLength100">,
- *   typeof value
+ *   typeof value,
+ *   string & Brand<"Trimmed"> & Brand<"MinLength1"> & Brand<"MaxLength100">
  * >();
  * ```
  *
  * @group Core
  */
-export declare function assertType<Expected, Actual>(...error: IsSameType<Expected, Actual> extends true ? [] : [
-    error: CompileTimeError<"assertType", "Expected and actual types must be identical">
+export declare function assertType<Actual, Expected>(...error: IsSameType<Actual, Expected> extends true ? [] : [
+    error: CompileTimeError<"assertType", "Actual and expected types must be identical">
 ]): void;
 export declare function assertType<T extends TypeNode>(type: T, value: unknown): asserts value is T["Output"];
 /**
@@ -474,7 +471,7 @@ export declare function assertType<T extends TypeNode>(type: T, value: unknown):
  *   },
  * );
  *
- * assertType<typeof Label, typeof typesByLocale.cs.Label>();
+ * assertType<typeof typesByLocale.cs.Label, typeof Label>();
  *
  * const result = typesByLocale.cs.Label.fromUnknown("");
  * assertErr(result);
@@ -625,7 +622,7 @@ declare const identityEncodingSymbol: unique symbol;
  *
  * const user = User.orThrow({ name: "Ada", age: 37 });
  *
- * assertType<typeof User.Output, typeof user>();
+ * assertType<typeof user, typeof User.Output>();
  * assertEqual(user.name, "Ada");
  * ```
  *
@@ -808,11 +805,10 @@ export declare function createType<Name extends TypeName, ParentType extends Con
  * not lose distinctions present in the Output domain.
  *
  * Transformation callbacks are Type construction code. Their successful results
- * are asserted against the declared boundary so a broken callback fails as a
- * developer error rather than becoming a validation error. Like all
- * Type-construction callbacks, they are trusted to follow their declared
- * TypeScript types. A `Result<_, never>` callback is therefore trusted never to
- * return an `Err`.
+ * are asserted against the declared boundary, so a broken callback throws
+ * instead of becoming a validation error. Like all Type-construction callbacks,
+ * they are trusted to follow their declared TypeScript types. A `Result<_,
+ * never>` callback is therefore trusted never to return an `Err`.
  *
  * Errors from the parent and the forward callback remain unchanged. A forward
  * callback error must use the transformation name as its type. Errors from the
@@ -1012,7 +1008,7 @@ export interface TypeOfError<Name extends keyof TypeOfOutputByName> extends Type
  * const WireValue100 = maxLength(100)(String);
  * type WireValue100 = typeof WireValue100.Output;
  *
- * assertType<string & Brand<"MaxLength100">, WireValue100>();
+ * assertType<WireValue100, string & Brand<"MaxLength100">>();
  * assertOk(WireValue100.fromUnknown(""), "");
  * assertOk(WireValue100.fromUnknown(" value "), " value ");
  * ```
@@ -1055,34 +1051,34 @@ export declare const String: Type<"String", string, string, TypeOfError<"String"
  * } from "@evolu/common";
  *
  * // Note how every additional constraint accumulates its Brand.
- * assertType<number, typeof Number.Output>();
- * assertType<number & Brand<"NonNaN">, typeof NonNaNNumber.Output>();
+ * assertType<typeof Number.Output, number>();
+ * assertType<typeof NonNaNNumber.Output, number & Brand<"NonNaN">>();
  * assertType<
- *   number & Brand<"NonNaN"> & Brand<"Finite">,
- *   typeof FiniteNumber.Output
+ *   typeof FiniteNumber.Output,
+ *   number & Brand<"NonNaN"> & Brand<"Finite">
  * >();
  * assertType<
- *   number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int">,
- *   typeof Int.Output
+ *   typeof Int.Output,
+ *   number & Brand<"NonNaN"> & Brand<"Finite"> & Brand<"Int">
  * >();
  * assertType<
+ *   typeof NonNegativeInt.Output,
  *   number &
  *     Brand<"NonNaN"> &
  *     Brand<"Finite"> &
  *     Brand<"Int"> &
- *     Brand<"NonNegative">,
- *   typeof NonNegativeInt.Output
+ *     Brand<"NonNegative">
  * >();
  *
  * assertType<
+ *   typeof Age.Output,
  *   number &
  *     Brand<"NonNaN"> &
  *     Brand<"Finite"> &
  *     Brand<"Int"> &
  *     Brand<"NonNegative"> &
  *     Brand<"LessThan200"> &
- *     Brand<"Age">,
- *   typeof Age.Output
+ *     Brand<"Age">
  * >();
  *
  * assertOk(Age.fromUnknown(122), 122);
@@ -1246,8 +1242,8 @@ export declare function objectTag<Name extends keyof ObjectTagOutputByName>(name
  * assertOk(result);
  * assertSame(result.value, value);
  * assertType<
- *   true,
- *   typeof result.value extends TaggedValue ? true : false
+ *   typeof result.value extends TaggedValue ? true : false,
+ *   true
  * >();
  * assertEqual(TaggedValueType.expected, "TaggedValue");
  * ```
@@ -1368,7 +1364,7 @@ type InstanceConstructorCompileTimeError = CompileTimeError<"Type", "Constructor
  *
  * const Ready = literal("ready");
  *
- * assertType<"ready", typeof Ready.Output>();
+ * assertType<typeof Ready.Output, "ready">();
  * assertOk(Ready.fromUnknown("ready"), "ready");
  * const invalid = Ready.fromUnknown("pending");
  * assertErr(invalid);
@@ -1673,20 +1669,20 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  *
  * // Output is the decoded language and region.
  * type SupportedLocale = typeof SupportedLocale.Output;
- * assertType<readonly ["en" | "cs", "US" | "CZ"], SupportedLocale>();
+ * assertType<SupportedLocale, readonly ["en" | "cs", "US" | "CZ"]>();
  *
  * // The parent Output is the canonical locale string.
  * type SupportedLocaleLiteral = typeof SupportedLocale.parent.Output;
  * assertType<
- *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ",
- *   SupportedLocaleLiteral
+ *   SupportedLocaleLiteral,
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
  * >();
  *
  * // Parse an unknown string into structured data.
  * const result = SupportedLocale.fromUnknown("cs-CZ");
  * assertOk(result, ["cs", "CZ"]);
  * const locale = result.value;
- * assertType<SupportedLocale, typeof locale>();
+ * assertType<typeof locale, SupportedLocale>();
  * const invalid = SupportedLocale.fromUnknown("cs/CZ");
  * assertErr(invalid);
  * assertType(Data, invalid.error);
@@ -1698,13 +1694,13 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  *
  * // Encode structured data into its canonical string.
  * const localeLiteral = SupportedLocale.to(locale);
- * assertType<SupportedLocaleLiteral, typeof localeLiteral>();
+ * assertType<typeof localeLiteral, SupportedLocaleLiteral>();
  * assertEqual(localeLiteral, "cs-CZ");
  *
  * // Validate a string configuration value.
  * const configValue: unknown = "cs-CZ";
  * assertType(SupportedLocale.parent, configValue);
- * assertType<SupportedLocaleLiteral, typeof configValue>();
+ * assertType<typeof configValue, SupportedLocaleLiteral>();
  * assertFalse(SupportedLocale.parent.is("fr-CZ"));
  * ```
  *
@@ -1756,11 +1752,11 @@ interface UnionErrorValue<Error extends TypeError, MemberError extends UnionMemb
  * const result = ItemId.fromUnknown("item-42");
  * assertOk(result, [42n]);
  * const itemId = result.value;
- * assertType<ItemId, typeof itemId>();
+ * assertType<typeof itemId, ItemId>();
  *
  * // Encode the structured data into its canonical string.
  * const itemIdLiteral = ItemId.to(itemId);
- * assertType<ItemIdLiteral, typeof itemIdLiteral>();
+ * assertType<typeof itemIdLiteral, ItemIdLiteral>();
  * assertEqual(itemIdLiteral, "item-42");
  *
  * // TypeScript cannot prove from the literal alone that "42" is a valid Int64 encoding.
@@ -1858,8 +1854,8 @@ export interface TemplateLiteralType<Parts extends TemplateLiteralParts> extends
  * const Locale = templateLiteral(Language, "-", Region);
  *
  * assertType<
- *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ",
- *   typeof Locale.Output
+ *   typeof Locale.Output,
+ *   "en-US" | "en-CZ" | "cs-US" | "cs-CZ"
  * >();
  * assertOk(Locale.fromUnknown("cs-CZ"), "cs-CZ");
  * assertFalse(Locale.is("fr-CZ"));
@@ -1957,7 +1953,7 @@ type TemplateLiteralStringWidth<Value extends string, Width extends ReadonlyArra
  * type Int64 = typeof Int64.Output;
  *
  * // Note the Brand.
- * assertType<bigint & Brand<"Int64">, Int64>();
+ * assertType<Int64, bigint & Brand<"Int64">>();
  *
  * interface Int64Error extends TypeError<"Int64"> {
  *   readonly value: bigint;
@@ -2132,7 +2128,7 @@ export interface UInt64Error extends TypeError<"UInt64"> {
  * const TrimmedString = trimmed(String);
  * type TrimmedString = typeof TrimmedString.Output;
  *
- * assertType<string & Brand<"Trimmed">, TrimmedString>();
+ * assertType<TrimmedString, string & Brand<"Trimmed">>();
  *
  * interface TrimmedError extends TypeError<"Trimmed"> {
  *   readonly value: string;
@@ -2201,8 +2197,8 @@ export type BrandFactory<Name extends TypeName, Value, Error extends TypeError<N
  * const LessThan100 = lessThan(100)(Number);
  * type LessThan100 = typeof LessThan100.Output;
  *
- * assertType<"LessThan100", typeof LessThan100.name>();
- * assertType<number & Brand<"LessThan100">, LessThan100>();
+ * assertType<typeof LessThan100.name, "LessThan100">();
+ * assertType<LessThan100, number & Brand<"LessThan100">>();
  *
  * interface LessThanError<
  *   Max extends number,
@@ -2241,7 +2237,7 @@ type BrandFactoryNumberError = CompileTimeError<"Brand Factory", "Parameter must
  * const CapitalizedString = capitalized(String);
  * type CapitalizedString = typeof CapitalizedString.Output;
  *
- * assertType<string & Brand<"Capitalized">, CapitalizedString>();
+ * assertType<CapitalizedString, string & Brand<"Capitalized">>();
  *
  * assertOk(CapitalizedString.fromUnknown("Evolu"), "Evolu");
  * const invalid = CapitalizedString.fromUnknown("evolu");
@@ -2461,7 +2457,7 @@ export interface LengthError<Exact extends number = number> extends TypeError<`L
  * )(String);
  * type UrlSafeString = typeof UrlSafeString.Output;
  *
- * assertType<string & Brand<"UrlSafeString">, UrlSafeString>();
+ * assertType<UrlSafeString, string & Brand<"UrlSafeString">>();
  *
  * assertOk(UrlSafeString.fromUnknown("abc-123_DEF"), "abc-123_DEF");
  * const invalid = UrlSafeString.fromUnknown("not safe");
@@ -2604,6 +2600,12 @@ export interface MnemonicError extends TypeError<"Mnemonic"> {
 /**
  * Evolu Id: 16 bytes encoded as a 22-character {@link Base64Url}.
  *
+ * Like [Nano ID](https://github.com/ai/nanoid), it is compact and URL-safe.
+ * Unlike Nano ID's 21-character default, an Evolu Id is the canonical Base64Url
+ * encoding of a full 128-bit value, so it round-trips directly between its
+ * string and byte representations with {@link idToIdBytes} and
+ * {@link idBytesToId}. These helpers use native Base64 APIs.
+ *
  * {@link createId} is the privacy-preserving default. Use
  * {@link createIdFromString} for stable mappings from external identifiers, or
  * {@link createIdAsUuidv7} only when insertion locality is worth exposing the
@@ -2642,7 +2644,7 @@ export interface IdError extends TypeError<"Id"> {
  * const userId = createId<"User">({ randomBytes: createRandomBytes() });
  *
  * assertTrue(Id.is(userId));
- * assertType<Id & Brand<"User">, typeof userId>();
+ * assertType<typeof userId, Id & Brand<"User">>();
  * ```
  *
  * @group String
@@ -2671,7 +2673,7 @@ export declare const createId: <B extends string = never>(deps: RandomBytesDep,
  * const todoId = createIdFromString<"Todo">("external-todo-456");
  *
  * assertEqual(first, second);
- * assertType<Id & Brand<"Todo">, typeof todoId>();
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
  * ```
  *
  * @group String
@@ -2726,7 +2728,7 @@ export declare const createIdAsUuidv7: <B extends string = never>(deps: RandomBy
  * const TodoId = id("Todo");
  * const todoId = TodoId.orThrow(createIdFromString("todo"));
  *
- * assertType<Id & Brand<"Todo">, typeof todoId>();
+ * assertType<typeof todoId, Id & Brand<"Todo">>();
  * ```
  *
  * @group String
@@ -3088,7 +3090,7 @@ export type PositiveFiniteNumber = typeof PositiveFiniteNumber.Output;
  * const Int = int(Number);
  * type Int = typeof Int.Output;
  *
- * assertType<number & Brand<"Int">, Int>();
+ * assertType<Int, number & Brand<"Int">>();
  *
  * assertOk(Int.fromUnknown(42), 42);
  * const invalid = Int.fromUnknown(1.5);
@@ -3519,8 +3521,8 @@ export type NegativeDecimalString = typeof NegativeDecimalString.Output;
  * const Tenths = multipleOf("0.1")(FiniteNumber);
  *
  * assertType<
- *   FiniteNumber & Brand<"MultipleOf0.1">,
- *   typeof Tenths.Output
+ *   typeof Tenths.Output,
+ *   FiniteNumber & Brand<"MultipleOf0.1">
  * >();
  *
  * assertOk(Tenths.fromUnknown(0.3), 0.3);
@@ -3623,8 +3625,8 @@ export interface BetweenError<Min extends number = number, Max extends number =
  * const result = UserIds.from.parent(["ada", "grace"]);
  *
  * assertType<
- *   Result<ReadonlyArray<string & Brand<"UserId">>>,
- *   typeof result
+ *   typeof result,
+ *   Result<ReadonlyArray<string & Brand<"UserId">>>
  * >();
  * assertOk(result, ["ada", "grace"]);
  * assertOk(UserIds.fromUnknown(["ada", "grace"]), ["ada", "grace"]);
@@ -4274,8 +4276,8 @@ export { _Object as Object };
  *
  * assertOk(scoresFromInput, { ada: 10n, grace: 20n });
  * assertType<
- *   Readonly<Partial<Record<string, Int64>>>,
- *   typeof scoresFromInput.value
+ *   typeof scoresFromInput.value,
+ *   Readonly<Partial<Record<string, Int64>>>
  * >();
  * ```
  *
@@ -4607,7 +4609,7 @@ type ObjectProperty = ObjectProps[string];
  * const userFromInput = User.from.parent(userInput.value);
  *
  * assertOk(userFromInput, { name: "Ada", loginCount: 42n });
- * assertType<typeof User.Output, typeof userFromInput.value>();
+ * assertType<typeof userFromInput.value, typeof User.Output>();
  * ```
  *
  * Note that TypeScript does not model an object's runtime prototype. This can
@@ -4712,7 +4714,7 @@ export declare function object<const Props extends ObjectProps>(props: Props, ..
  *   authorization: "Bearer token",
  *   "x-request-id": "request-1",
  * });
- * assertType<string | undefined, (typeof result.value)["x-request-id"]>();
+ * assertType<(typeof result.value)["x-request-id"], string | undefined>();
  * ```
  */
 export declare function object<const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(props: Props, record: Rest, ...validation: [
@@ -5122,10 +5124,10 @@ export type UnknownResult = typeof UnknownResult.Output;
  * });
  * assertFalse(Loading.is({ type: "Loading", progress: 1 }));
  * assertType<
- *   true,
  *   typeof Loading.Output extends { readonly type: "Loading" }
  *     ? true
- *     : false
+ *     : false,
+ *   true
  * >();
  * ```
  *
@@ -5177,7 +5179,7 @@ export declare function typed<const Tag extends TypeName, const Props extends Ob
  *   label: "Ready",
  *   note: "Connected",
  * });
- * assertType<string | undefined, typeof result.value.note>();
+ * assertType<typeof result.value.note, string | undefined>();
  * ```
  */
 export declare function typed<const Tag extends TypeName, const Props extends ObjectProps, const Rest extends RecordTypeNode & ConcreteTypeNode>(tag: ValidateTypedTag<Tag>, props: Props, record: Rest, ...validation: [
@@ -5260,7 +5262,7 @@ export interface Typed<Tag extends TypeName> {
  *
  * type CreateMessage = ExtractTyped<Message, "Create">;
  *
- * assertType<typeof Create.Output, CreateMessage>();
+ * assertType<CreateMessage, typeof Create.Output>();
  *
  * // @ts-expect-error "Cretae" is not a Message type.
  * type _Typo = ExtractTyped<Message, "Cretae">;
@@ -5603,7 +5605,7 @@ type DiscriminatedUnionDuplicateValueError<Key extends string, Expected extends
  *   value: "root",
  *   children: [{ value: "leaf", children: [] }],
  * });
- * assertType<Tree, typeof result.value>();
+ * assertType<typeof result.value, Tree>();
  * ```
  *
  * @group Recursive
@@ -5669,7 +5671,7 @@ type LazyTargetConcreteTypeError = CompileTimeError<"Type", "Lazy Type definitio
  *
  * assertOk(result);
  * assertSame(result.value, value);
- * assertType<Data, typeof result.value>();
+ * assertType<typeof result.value, Data>();
  * ```
  *
  * @group Base
@@ -5702,8 +5704,8 @@ export type Data = undefined | null | string | number | bigint | boolean | Reado
  *   readonly run: () => void;
  * }
  *
- * assertType<true, IsData<User>>();
- * assertType<false, IsData<Service>>();
+ * assertType<IsData<User>, true>();
+ * assertType<IsData<Service>, false>();
  * ```
  *
  * @group Base
@@ -5934,7 +5936,7 @@ export interface JsonError extends TypeError<"Json"> {
  * const result = JsonValue.fromUnknown(input);
  *
  * assertOk(result, input);
- * assertType<JsonValue, typeof result.value>();
+ * assertType<typeof result.value, JsonValue>();
  * ```
  *
  * @group JSON
@@ -6054,8 +6056,8 @@ export declare const JsonValueFromJson: TransformType<BrandType<Type<"String", s
  * const userJson = userToUserJson(user);
  *
  * assertType<
- *   string & Brand<"Json"> & Brand<"UserJson">,
- *   typeof userJson
+ *   typeof userJson,
+ *   string & Brand<"Json"> & Brand<"UserJson">
  * >();
  * assertEqual(userJson, '{"name":"Ada","age":37}');
  * assertEqual(UserJson.orThrow(userJson), userJson);