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
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.
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
- nominal for 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, renders message with the default
schema issue formatter, 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
- Branded for applying a brand key to a base type
- Constructor for 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>;}