@evolu/common 8.3.0 → 8.3.2

package/dist/src/Type.d.ts

@@ -88,7 +88,7 @@ export interface Type<Name extends TypeName, in out Input, in out Output, Error
     readonly fromUnknown: (value: unknown, options?: ValidationOptions) => Result<Output, Errors>;
     /**
      * Formats an error returned by `fromUnknown` or `from` as one human-readable
-     * message. Built-in Types use English; {@link localizeTypes} derives Types
+     * message. Predefined Types use English; {@link localizeTypes} derives Types
      * with localized formatters.
      *
      * Structural errors retain nested errors and their locations in the typed
@@ -376,8 +376,8 @@ export declare const assertType: <T extends TypeNode>(type: T, value: unknown) =
  * Pass the Types used together in one localization scope and formatter maps
  * keyed by locale. TypeScript infers every formatter required by the selected
  * Types, including errors from nested structural Types and recursive Lazy
- * Types. Every locale must provide the complete inferred formatter set;
- * missing and unrelated formatters are compile-time errors.
+ * Types. Every locale must provide the complete inferred formatter set; missing
+ * and unrelated formatters are compile-time errors.
  *
  * The result preserves the locale names, selected Type names, and exact
  * TypeScript types. A localized Type validates exactly like its source Type;
@@ -429,8 +429,8 @@ export declare const assertType: <T extends TypeNode>(type: T, value: unknown) =
  *
  * ### Supported locales
  *
- * English is built in; use {@link Type} directly for its default formatters.
- * The following additional locales are available:
+ * English is built in; use {@link Type} directly for its default formatters. The
+ * following additional locales are available:
  *
  * - Arabic (`ar`)
  * - Bengali (`bn`)
@@ -738,9 +738,9 @@ export declare function createType<Name extends TypeName, ParentType extends Con
  * canonicalize multiple parent representations, but it must be total and must
  * 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
+ * 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`.
@@ -756,13 +756,7 @@ export declare function createType<Name extends TypeName, ParentType extends Con
  * ### Example
  *
  * ```ts
- * import {
- *   Boolean,
- *   literal,
- *   ok,
- *   transform,
- *   union,
- * } from "@evolu/common";
+ * import { Boolean, literal, ok, transform, union } from "@evolu/common";
  *
  * const BooleanString = union(literal("false"), literal("true"));
  * const BooleanFromString = transform(
@@ -1052,18 +1046,18 @@ interface ObjectTagOutputByName {
 /**
  * Realm-neutral {@link Type} trusting an object's reported tag.
  *
- * Predefined built-in tags expose their native Output type under the assumption
- * that trusted code does not forge their tags. They do not verify native
- * internal slots. A custom tag refines the supplied Type and adds nominal
- * evidence to its Output, so only a value validated by the resulting Type is
- * accepted by its typed operations.
+ * Predefined tags for JavaScript built-ins expose their native Output type
+ * under the assumption that trusted code does not forge their tags. They do not
+ * verify native internal slots. A custom tag refines the supplied Type and adds
+ * nominal evidence to its Output, so only a value validated by the resulting
+ * Type is accepted by its typed operations.
  *
- * `Object.prototype.toString` recognizes legitimate built-ins from another
- * realm, but any object can customize the result with `Symbol.toStringTag`.
- * Types returned by this factory therefore classify trusted values; they are
- * not security boundaries. Passing a forged built-in tag violates the trust
- * assumption of the predefined Type. Primitive Outputs are rejected at compile
- * time.
+ * `Object.prototype.toString` recognizes legitimate JavaScript built-ins from
+ * another realm, but any object can customize the result with
+ * `Symbol.toStringTag`. Types returned by this factory therefore classify
+ * trusted values; they are not security boundaries. Passing a forged JavaScript
+ * built-in tag violates the trust assumption of the predefined Type. Primitive
+ * Outputs are rejected at compile time.
  *
  * ### Example
  *
@@ -2234,8 +2228,8 @@ export type UrlSafeString = typeof UrlSafeString.Output;
 /**
  * Base64Url text without padding.
  *
- * Encode bytes with {@link uint8ArrayToBase64Url} and decode them with
- * {@link base64UrlToUint8Array}.
+ * Convert bytes to Base64Url with {@link uint8ArrayToBase64Url} and convert
+ * Base64Url to bytes with {@link base64UrlToUint8Array}.
  *
  * @group String
  */
@@ -2250,7 +2244,7 @@ export interface Base64UrlError extends TypeError<"Base64Url"> {
     readonly value: string;
 }
 /**
- * Encodes bytes as {@link Base64Url}.
+ * Converts bytes to {@link Base64Url}.
  *
  * ### Example
  *
@@ -2266,7 +2260,7 @@ export interface Base64UrlError extends TypeError<"Base64Url"> {
  */
 export declare const uint8ArrayToBase64Url: (bytes: Uint8Array) => Base64Url;
 /**
- * Decodes {@link Base64Url} as bytes.
+ * Converts {@link Base64Url} to bytes.
  *
  * ### Example
  *
@@ -2551,7 +2545,9 @@ export interface Int64StringError extends TypeError<"Int64String"> {
  * const result = Int64FromInt64String.fromUnknown("9223372036854775807");
  *
  * expectOk(result, 9223372036854775807n);
- * expect(Int64FromInt64String.to(result.value)).toBe("9223372036854775807");
+ * expect(Int64FromInt64String.to(result.value)).toBe(
+ *   "9223372036854775807",
+ * );
  * ```
  *
  * @group Number
@@ -3732,7 +3728,8 @@ type PlainObjectError = ObjectError<Readonly<Record<never, never>>, ObjectProper
  *
  * @group Base
  */
-export declare const Object: Type<"Object", Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>, PlainObjectError, null, PlainObjectError, never, Readonly<Record<string, unknown>>>;
+declare const _Object: Type<"Object", Readonly<Record<string, unknown>>, Readonly<Record<string, unknown>>, PlainObjectError, null, PlainObjectError, never, Readonly<Record<string, unknown>>>;
+export { _Object as Object };
 /**
  * Record {@link Type}.
  *
@@ -4277,10 +4274,10 @@ export interface ObjectNotObjectError extends TypeError<"Object"> {
  *
  * Object Types accept a `null` prototype or a prototype whose own prototype is
  * `null`. This includes ordinary and cross-realm plain objects as well as
- * objects created from an immediate root prototype. Arrays, built-in objects,
- * class instances, and objects with deeper custom prototype chains return this
- * error instead of having their prototype or inherited state discarded.
- * `reason.value` is the rejected object.
+ * objects created from an immediate root prototype. Arrays, JavaScript built-in
+ * objects, class instances, and objects with deeper custom prototype chains
+ * return this error instead of having their prototype or inherited state
+ * discarded. `reason.value` is the rejected object.
  *
  * @group Objects
  */
@@ -4440,8 +4437,8 @@ type OmitKeyConcreteTypeError = CompileTimeError<"Type", "Each omitted key must
  * Creates a {@link Type} for {@link Result} values.
  *
  * Use this to validate Results crossing a storage, worker, API, or other
- * serialization boundary. `fromUnknown` returns an outer validation Result.
- * Its successful value is the inner domain Result described by `okType` and
+ * serialization boundary. `fromUnknown` returns an outer validation Result. Its
+ * successful value is the inner domain Result described by `okType` and
  * `errorType`.
  *
  * ### Example
@@ -4580,7 +4577,8 @@ export interface Typed<Tag extends TypeName> {
  * Extracts members of a {@link Typed} Output union by their `type` literal.
  *
  * The requested tag is constrained to the union's actual discriminator values,
- * so a misspelling is a TypeScript error instead of silently producing `never`.
+ * so a misspelling is a TypeScript error instead of silently producing
+ * `never`.
  *
  * ### Example
  *
@@ -5119,7 +5117,7 @@ export declare const JsonObject: JsonObjectType;
  * A {@link String} Brand proving that its exact text parses to {@link JsonValue}.
  *
  * The Brand preserves whitespace, property order, and number spelling. Convert
- * it totally to {@link JsonValue} through {@link JsonValueFromJson} or
+ * it to {@link JsonValue} through {@link JsonValueFromJson} or
  * {@link jsonToJsonValue}.
  *
  * @group JSON
@@ -5127,7 +5125,7 @@ export declare const JsonObject: JsonObjectType;
 export declare const Json: BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Json", JsonError>;
 export type Json = typeof Json.Output;
 /**
- * Totally parses proven {@link Json} text into an exact {@link JsonValue}.
+ * Converts proven {@link Json} text to an exact {@link JsonValue}.
  *
  * ### Example
  *
@@ -5143,7 +5141,7 @@ export type Json = typeof Json.Output;
  */
 export declare const jsonToJsonValue: (value: Json) => JsonValue;
 /**
- * Totally encodes an exact {@link JsonValue} as canonical {@link Json} text.
+ * Converts an exact {@link JsonValue} to canonical {@link Json} text.
  *
  * ### Example
  *
@@ -5179,67 +5177,48 @@ export declare const jsonValueToJson: (value: JsonValue) => Json;
  */
 export declare const JsonValueFromJson: TransformType<BrandType<Type<"String", string, string, TypeOfError<"String">, null, TypeOfError<"String">, never, string, true>, "Json", JsonError>, JsonValueType, "JsonValueFromJson", never, string & Brand<"Json">>;
 /**
- * Branded {@link Json} Type and total conversions for another Type.
- *
- * Use this factory when a domain value must be stored as JSON text while its
- * exact Type remains visible to TypeScript, such as a JSON column in an Evolu
- * Schema. The returned tuple contains the branded Json Type, an encoder from
- * the supplied Type's Output to Json, and a decoder from Json back to that
- * Output.
- *
- * The supplied Type's `CanonicalInput` must be JSON-compatible. The encoder
- * first uses the Type's canonical `to` operation, then encodes that
- * representation as canonical Json. Runtime representation constraints
- * TypeScript cannot prove, such as dense Arrays and enumerable data properties,
- * are asserted as developer errors.
- *
- * The branded Json Type is the validation boundary for unknown JSON text. It
- * grants its {@link Brand} only when the text is valid Json and decoding it
- * through the supplied Type succeeds. The supplied Type is responsible for
- * preserving semantic Outputs across canonical JSON encoding and decoding. This
- * law cannot be checked generically because Types do not define semantic
- * equality. Before granting the Brand, the encoder asserts the weaker runtime
- * guarantee that the final Json successfully decodes through the supplied Type.
- * Failed decodability therefore throws as a developer error.
- *
- * Consequently, the two typed conversions return their values directly without
- * exposing a validation {@link Result}: an Output satisfying the JSON
- * representation contract of a correctly declared Type can always be encoded,
- * and the branded Json proves decoding will succeed. Decoding still runs the
- * Type pipeline because transformations may need to construct different Output
- * values.
+ * Branded {@link Json} Type and conversions for another {@link Type}.
+ *
+ * Use this when a value must be stored as JSON text, such as in a JSON column
+ * in an Evolu Schema. It returns a branded Json Type and functions for
+ * converting the supplied Type's Output to and from that branded JSON
+ * representation.
  *
  * ### Example
  *
  * ```ts
  * import {
  *   Age,
+ *   NonEmptyTrimmedString100,
  *   json,
  *   object,
- *   String,
  *   type Brand,
- *   type InferType,
- *   type Json,
  * } from "@evolu/common";
  *
- * const Person = object({ name: String, age: Age });
- * interface Person extends InferType<typeof Person> {}
+ * const User = object({
+ *   name: NonEmptyTrimmedString100,
+ *   age: Age,
+ * });
  *
- * const [PersonJson, personToPersonJson, personJsonToPerson] = json(
- *   Person,
- *   "PersonJson",
+ * const [UserJson, userToUserJson, userJsonToUser] = json(
+ *   User,
+ *   "UserJson",
  * );
- * type PersonJson = typeof PersonJson.Output;
  *
- * expectTypeOf<PersonJson>().toEqualTypeOf<Json & Brand<"PersonJson">>();
- *
- * const person = Person.orThrow({ name: "Ada", age: 42 });
- * const personJson = personToPersonJson(person);
- * const decodedPerson = personJsonToPerson(personJson);
+ * const user = User.orThrow({ name: "Ada", age: 37 });
+ * const userJson = userToUserJson(user);
  *
- * expect(decodedPerson).toEqual(person);
+ * expectTypeOf(userJson).toEqualTypeOf<
+ *   string & Brand<"Json"> & Brand<"UserJson">
+ * >();
+ * expect(userJson).toBe('{"name":"Ada","age":37}');
+ * expect(userJsonToUser(userJson)).toEqual(user);
  * ```
  *
+ * The supplied Type must have a JSON-compatible `CanonicalInput`. The branded
+ * Json Type accepts only valid JSON text whose parsed value can be decoded by
+ * the supplied Type.
+ *
  * @group JSON
  */
 export declare const json: <T extends ConcreteTypeNode, Name extends TypeName>(type: T, name: ValidateChildTypeName<Name, typeof Json>, ..._validation: [JsonTypeValidationError<T>] extends [never] ? [] : [ValidationFailure<JsonTypeValidationError<T>>]) => readonly [jsonType: BrandType<typeof Json, Name, TypeError<Name> & TransparentTypeError & {
@@ -5258,5 +5237,4 @@ type JsonNumberCompatible<Value extends number> = [Value] extends [FiniteNumber]
 type JsonObjectCompatible<Value extends object, Seen extends ReadonlyArray<unknown>> = [keyof Value] extends [never] ? false : string extends keyof Value ? Exclude<keyof Value, string | number> extends never ? Value extends Readonly<Partial<Record<string, infer Item>>> ? IsJsonCompatible<Item, Seen> : false : false : false extends {
     readonly [Key in keyof Value]-?: Key extends string ? IsJsonCompatible<{} extends Pick<Value, Key> ? Required<Pick<Value, Key>>[Key] : Value[Key], Seen> : false;
 }[keyof Value] ? false : true;
-export {};
 //# sourceMappingURL=Type.d.ts.map