Newtype
Creates compile-time-only wrappers around existing value types.
A newtype lets TypeScript distinguish values with the same runtime shape, such as two different ids that are both strings. The tag exists only in the type system, so wrapping does not allocate a runtime object. This module includes the base Newtype interface, wrapping and unwrapping helpers, optics, and helpers for reusing carrier instances such as Equivalence, Order, Combiner, and Reducer.
Constructors
makeCombiner
Signature
declare const makeCombiner: <N extends Newtype.Any>(
combiner: Combiner.Combiner<Newtype.Carrier<N>>,
) => Combiner.Combiner<N>;makeEquivalence
Lifts an Equivalence for the carrier type into an Equivalence for the newtype.
When to use
Use when you need equality for newtype-wrapped values to behave like equality for the wrapped carrier value, without manually unwrapping.
Details
The returned equivalence delegates to the provided carrier equivalence and has zero runtime cost beyond the underlying equivalence check.
See
makeOrder— lift anOrderfor the carrier
Signature
declare const makeEquivalence: <N extends Newtype.Any>(
equivalence: Equivalence.Equivalence<Newtype.Carrier<N>>,
) => Equivalence.Equivalence<N>;Creates an Optic.Iso for a newtype, providing both wrapping (set) and unwrapping (get).
When to use
Use as the primary way to construct and deconstruct newtype values.
Details
The returned iso composes with other optics via the standard Optic API. Both directions have zero runtime cost because they are identity casts.
See
value— unwrap only
Signature
declare function makeIso<N extends Any>(): Iso<N, Carrier<N>>;Lifts an Order for the carrier type into an Order for the newtype.
When to use
Use when you need to sort newtype-wrapped values according to the ordering of the wrapped carrier value, without manually unwrapping.
Details
The returned order delegates to the provided carrier order.
See
makeEquivalence— lift anEquivalencefor the carrier
Signature
declare const makeOrder: <N extends Newtype.Any>(
order: Order.Order<Newtype.Carrier<N>>,
) => Order.Order<N>;makeReducer
Lifts a Reducer for the carrier type into a Reducer for the newtype.
When to use
Use when you need to reduce a collection of newtype-wrapped values with the carrier's reducer, without manually unwrapping.
Details
The returned reducer delegates to the provided carrier reducer.
See
makeCombiner— lift aCombinerfor the carrier
Signature
declare const makeReducer: <N extends Newtype.Any>(
reducer: Reducer.Reducer<Newtype.Carrier<N>>,
) => Reducer.Reducer<N>;Getters
Unwraps a newtype value, returning the underlying carrier value.
When to use
Use when you need the carrier value from an existing newtype without constructing a new newtype value at the same call site.
Details
This has zero runtime cost because it is an identity cast.
See
makeIso— two-way conversion (wrap and unwrap)
Signature
declare const value: <N extends Newtype.Any>(newtype: N) => Newtype.Carrier<N>;Models
A tagged interface that wraps a carrier type under a unique key, preventing accidental interchange of structurally identical values.
When to use
Use to define a newtype as an interface extending Newtype<"MyKey", CarrierType> when structurally identical carrier types should remain distinct in TypeScript.
Details
The tag is compile-time only, so no runtime wrapper is allocated. Use makeIso to create a two-way conversion, or value to unwrap.
See
Signature
interface Newtype<in out Key extends string, out Carrier> {
readonly "~effect/Newtype": {
readonly carrier: Carrier;
readonly key: Key;
};
}
Lifts a
Combinerfor the carrier type into aCombinerfor the newtype.When to use
Use when you need to combine newtype-wrapped values with the carrier's combining logic, without manually unwrapping.
Details
The returned combiner delegates to the provided carrier combiner.
See
makeReducer— lift aReducerfor the carrier