Brand
The Brand module adds compile-time names to ordinary TypeScript values so structurally identical values cannot be mixed accidentally. A branded value has the same runtime representation as its unbranded value; the extra information lives in the type system unless you choose a validating constructor.
Combining
Signature
declare function all<Brands extends readonly [Constructor<any>, Constructor<any>]>(
...brands: Brand.EnsureCommonBase<Brands>
): Constructor<
UnionToIntersection<
{ [B in string | number | symbol]: FromConstructor<Brands[B]> }[number]
> extends X
? X
: Brand<any>
>;Constructors
Creates a branded type Constructor from one or more schema checks.
When to use
Use when you need a branded type constructor that performs runtime validation via schema checks.
Details
Calling the returned constructor validates the unbranded value and throws on failure. Use the returned option, result, or is methods for non-throwing validation.
See
Signature
declare function check<A extends Brand<any>>(
...checks: readonly [Check<Unbranded<A>>, Check<Unbranded<A>>]
): Constructor<A>;Returns a Constructor that can construct a branded type from an unbranded value using the provided filter predicate as validation of the input data.
When to use
Use when you want validation while constructing the branded type.
See
nominalfor a brand constructor that performs no validation.
Signature
declare function make<A extends Brand<any>>(
filter: (unbranded: Unbranded<A>) => FilterOutput,
): Constructor<A>;Returns a Constructor that does not apply any runtime checks and just returns the provided value.
When to use
Use to create nominal types that allow distinguishing between two values of the same type but with different meanings.
See
Signature
declare function nominal<A extends Brand<any>>(): Constructor<A>;Errors
BrandError
Error returned when a branded type is constructed from an invalid value.
Details
The error wraps a SchemaIssue.Issue, exposes message through issue.toString(), and formats as BrandError(<message>).
Gotchas
BrandError is an error-like model with _tag, name, message, and toString; it does not extend JavaScript Error.
Signature
declare class BrandError {
constructor(issue: Issue);
readonly _tag: "BrandError";
readonly issue: Issue;
readonly name: string;
message: string;
toString(): string;
}Models
A generic interface that defines a branded type.
When to use
Use to define a branded type such as number & Brand<"Positive"> when TypeScript should keep structurally identical values separate without changing their runtime value.
See
Brandedfor applying a brand key to a base typeConstructorfor validating or constructing branded values
Signature
interface Brand<in out Keys extends string> {
readonly "~effect/Brand": { [K in string]: Keys };
}Constructor interface
A constructor for a branded type that provides validation and safe construction methods.
When to use
Use as the shared callable interface for branded values when an API accepts or returns a brand constructor and callers need throwing, Option, Result, or type-guard validation forms.
See
Signature
interface Constructor<in out B extends Brand<any>> {
(unbranded: Unbranded<B>): B;
is(unbranded: Unbranded<B>): unbranded is Unbranded<B> & B;
option(unbranded: Unbranded<B>): Option<B>;
result(unbranded: Unbranded<B>): Result<B, BrandError>;
}
Combines one or more brand constructors to form a single branded type.
When to use
Use to require an input to satisfy every runtime check collected by the provided brand constructors.
Details
If the provided constructors contain runtime checks, the combined constructor succeeds only when all checks pass. If no runtime checks are present, it behaves as a nominal constructor.