BrandType - API reference

API reference › @evolu/common › Type › BrandType

Defined in: packages/common/src/Type.ts:5197

The Type returned by brand.

Extends

Type<Name, ParentType["Input"], ParentType["Output"] & Brand<Name>, Error, ParentType, | Error | InferErrors<ParentType>, ChildCustomFrom<ParentType, ParentType["Output"] & Brand<Name>, Error>, CanonicalInputForChild<ParentType, ParentType["Output"] & Brand<Name>>, IdentityEncodingOf<ParentType>>

Properties

[concreteTypeSymbol]

readonly [concreteTypeSymbol]: true;

Defined in: packages/common/src/Type.ts:585

Inherited from

Type.[concreteTypeSymbol]

[customFromSymbol]

readonly [customFromSymbol]: ChildCustomFrom;

Defined in: packages/common/src/Type.ts:589

Inherited from

Type.[customFromSymbol]

[errorsSymbol]

readonly [errorsSymbol]:
  | Error
| InferErrors<ParentType>;

Defined in: packages/common/src/Type.ts:581

Inherited from

Type.[errorsSymbol]

[identityEncodingSymbol]

readonly [identityEncodingSymbol]: IdentityEncodingOf;

Defined in: packages/common/src/Type.ts:592

Inherited from

Type.[identityEncodingSymbol]

~standard

readonly ~standard: Props<ParentType["Input"], ParentType["Output"] & Brand<Name>>;

Defined in: packages/common/src/Type.ts:532

Standard Schema V1 interoperability.

Validation runs the complete fromUnknown pipeline synchronously and reports every structured failure as a localized message with a separate property path.

Inherited from

Type.~standard

CanonicalInput

CanonicalInput: CanonicalInputForChild<
  ParentType,
  ParentType["Output"] & Brand<Name>
>;

Defined in: packages/common/src/Type.ts:517

The statically known subtype of Input returned by the complete to operation.

Compared with Input, CanonicalInput can exclude invalid candidates and alternative representations that encoding cannot emit. It can remain wider than the values actually emitted when a refinement follows an arbitrary transformation. Structural Types derive it from the CanonicalInput of their contained Types.

This is a type-only phantom property. Use it through typeof Type.CanonicalInput; it does not exist at runtime.

Inherited from

Type.CanonicalInput

Error

Error: Error;

Defined in: packages/common/src/Type.ts:511

The error introduced at this Type node.

This is a type-only phantom property. Use it through typeof Type.Error; it does not exist at runtime.

Inherited from

Type.Error

formatError

readonly formatError: TypeErrorFormatter<
  | Error
| InferErrors<ParentType>>;

Defined in: packages/common/src/Type.ts:651

Formats an error returned by fromUnknown or from as one human-readable message. Predefined Types use English; localizeTypes derives Types with localized formatters.

Structural errors retain nested errors and their locations in the typed error value. This formatter does not encode paths or enumerate nested errors in its message.

Example

import {
  assertEqual,
  assertType,
  Data,
  assertErr,
  String,
} from "@evolu/common";

const result = String.fromUnknown(42);

assertErr(result);
assertType(Data, result.error);
assertEqual(result.error, {
  type: "TypeOf",
  expected: "String",
  value: 42,
});
assertEqual(String.formatError(result.error), "A value 42 is not a string.");

Inherited from

Type.formatError

from

readonly from: [ChildCustomFrom<ParentType, ParentType["Output"] & Brand<Name>, Error>] extends [never] ? [ParentType] extends [P] ? FromOperation<ParentType["Output"] & Brand<Name>, Error, P> : (value: ParentType["Output"] & Brand<Name>, options?: ValidationOptions) => Result<ParentType["Output"] & Brand<Name>, never> : ChildCustomFrom<ParentType, ParentType["Output"] & Brand<Name>, Error>;

Defined in: packages/common/src/Type.ts:743

Runs the remaining Type pipeline from a typed boundary.

from accepts this Type's Output. Its first .parent accepts the immediate parent Output, and each additional suffix moves the boundary one 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 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

A form already guarantees every constraint on a title, while a new note input guarantees only trimmed text. The note's parent boundary validates only the constraints that the form does not guarantee:

import {
  assertOk,
  assertType,
  flatMapResult,
  NonEmptyTrimmedString100,
  object,
  TrimmedString,
  type MaxLengthError,
  type MinLengthError,
  type Result,
} from "@evolu/common";

const Todo = object({
  title: NonEmptyTrimmedString100,
  note: NonEmptyTrimmedString100,
});

const saveTodo = (title: NonEmptyTrimmedString100, note: TrimmedString) => {
  // @ts-expect-error TrimmedString does not guarantee a non-empty value
  // with at most 100 characters.
  Todo.from({ title, note });

  return flatMapResult(Todo.props.note.from.parent.parent(note), (note) =>
    Todo.from({ title, note }),
  );
};

const title = NonEmptyTrimmedString100.orThrow("Buy milk");
const note = TrimmedString.orThrow("Remember oat milk");
const result = saveTodo(title, note);

assertType<
  typeof result,
  Result<typeof Todo.Output, MaxLengthError<100> | MinLengthError<1>>
>();
assertOk(result, { title, note });

Inherited from

Type.from

fromUnknown

readonly fromUnknown: (value: unknown, options?: ValidationOptions) => Result<ParentType["Output"] & Brand<Name>,
  | Error
| InferErrors<ParentType>>;

Defined in: packages/common/src/Type.ts:611

Decodes an unknown value through the complete Type pipeline.

Example

import { assertOk, PositiveInt } from "@evolu/common";

const value: unknown = 42;
const result = PositiveInt.fromUnknown(value);

assertOk(result, 42);

Inherited from

Type.fromUnknown

Input

Input: ParentType["Input"];

Defined in: packages/common/src/Type.ts:509

The complete typed decoding boundary accepted by orThrow, orNull, and the deepest available from operation.

Input includes candidates that validation can reject and noncanonical representations that decoding can normalize.

This is a type-only phantom property. Use it through typeof Type.Input; it does not exist at runtime.

Inherited from

Type.Input

is

readonly is: (value: unknown) => value is ParentType["Output"] & Brand<Name>;

Defined in: packages/common/src/Type.ts:679

Checks whether an unknown value is a valid semantic Output.

This is an exact Output-membership check, not a test of whether an encoded Input could be decoded. It can be used directly as a TypeScript type guard, including as an Array filter predicate.

Example

import {
  assertFalse,
  assertType,
  assertTrue,
  Int64FromInt64String,
  type Int64,
} from "@evolu/common";

const values: ReadonlyArray<unknown> = [42n, "42", null];
const integers = values.filter(Int64FromInt64String.is);

assertType<typeof integers, Array<Int64>>();
assertTrue(Int64FromInt64String.is(42n));
assertFalse(Int64FromInt64String.is("42"));

Inherited from

Type.is

name

readonly name: Name;

Defined in: packages/common/src/Type.ts:523

The name identifying this Type node.

Inherited from

Type.name

orNull

readonly orNull: (value: ParentType["Input"]) =>
  | ParentType["Output"] & Brand<Name>
  | null;

Defined in: packages/common/src/Type.ts:870

Shorthand for calling getOrNull with the result of the deepest from operation, which accepts this Type's Input.

The typed Input boundary is asserted before the remaining pipeline runs. 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 operation.

Use orNull when absence is the complete meaning of failure and the error is intentionally irrelevant. Use fromUnknown or a typed from operation when the caller needs to inspect, format, or otherwise handle the error.

Example

import { assertEqual, getOrNull, minLength, String } from "@evolu/common";

const NonEmptyString = minLength(1)(String);

const value = NonEmptyString.orNull("Evolu");

// Equivalent because `from.parent` is this Type's deepest `from` operation:
const sameValue = getOrNull(NonEmptyString.from.parent("Evolu"));

assertEqual(value, "Evolu");
assertEqual(sameValue, value);
assertEqual(NonEmptyString.orNull(""), null);

Inherited from

Type.orNull

orThrow

readonly orThrow: (value: ParentType["Input"], options?: ValidationOptions) => ParentType["Output"] & Brand<Name>;

Defined in: packages/common/src/Type.ts:830

Runs the deepest from operation, which accepts this Type's Input, and returns its decoded value or throws an Error.

Returned validation errors use this Type's Type.formatError as the Error message and preserve the original validation error as cause. With { errors: "all" }, the cause retains all collected errors; the message still follows formatError, which describes the first issue.

The typed Input boundary is asserted before the remaining pipeline runs. A boundary violation is a bug, so it throws directly with its assertion message instead of formatting a returned validation error.

Type.orThrow.parent(value) does not exist. To throw after starting from a typed boundary, call getOrThrow with the corresponding from operation. Its generic Error message differs from this operation's message.

Use orThrow for startup and configuration, module constants, test fixtures, and internal invariants where failure must stop the current flow. Prefer fromUnknown or a typed from operation for ordinary application input whose validation failure can be reported or recovered from.

Example

import {
  assertEqual,
  assertInstanceOf,
  assertErr,
  minLength,
  String,
  trySync,
} from "@evolu/common";

const NonEmptyString = minLength(1)(String);

const value = NonEmptyString.orThrow("Evolu");

assertEqual(value, "Evolu");

const failed = trySync(() => NonEmptyString.orThrow(""));
assertErr(failed);
assertInstanceOf(failed.error, Error);
assertEqual(
  failed.error.message,
  'The value "" does not meet the minimum length of 1.',
);
assertEqual(failed.error.cause, {
  type: "MinLength1",
  value: "",
  min: 1,
});

Inherited from

Type.orThrow

Output

Output: ParentType["Output"] & Brand<Name>;

Defined in: packages/common/src/Type.ts:510

The semantic value produced by decoding and accepted by bare from and to.

This is a type-only phantom property. Use it through typeof Type.Output; it does not exist at runtime.

Inherited from

Type.Output

parent

readonly parent: ParentType;

Defined in: packages/common/src/Type.ts:595

The one preceding Type node, or null for a root Type.

Inherited from

Type.parent

to

readonly to: [ParentType] extends [P] ? ToOperation<ParentType["Output"] & Brand<Name>, CanonicalInputForChild<ParentType, ParentType["Output"] & Brand<Name>>, P> : (value: ParentType["Output"] & Brand<Name>) => CanonicalInputForChild;

Defined in: packages/common/src/Type.ts:771

Asserts and encodes an Output toward its canonical Input representation.

to runs the complete encoding pipeline. Its first .parent stops at the immediate parent Output, and each additional suffix stops one Type closer to the root. Every entry point accepts this Type's Output.

Example

import { assertEqual, Int64, Int64FromInt64String } from "@evolu/common";

const value = Int64.orThrow(42n);

assertEqual(Int64FromInt64String.to(value), "42");

Inherited from

Type.to