Skip to content

Newtype Pattern

In one line

Newtype creates a distinct type from an existing one — same runtime value, different compile-time type.

In simple words

The Newtype pattern (from Haskell) creates a new type that wraps an existing type, giving it a distinct identity without runtime overhead.

type Celsius = number & { readonly _tag: "Celsius" } type Fahrenheit = number & { readonly _tag: "Fahrenheit" }

At runtime, both are just numbers. At compile time, they're distinct — you can't accidentally add Celsius and Fahrenheit. This is similar to branded types but specifically for creating new types from primitives.

Use cases: units of measurement, IDs, domain-specific wrappers. The newtype has the same performance as the underlying type — no boxing, no allocation.

Example

typescript
type Celsius = number & { readonly _tag: "Celsius" };
type Fahrenheit = number & { readonly _tag: "Fahrenheit" };

const celsius = (n: number): Celsius => n as Celsius;
const fahrenheit = (n: number): Fahrenheit => n as Fahrenheit;

function toFahrenheit(c: Celsius): Fahrenheit {
  return fahrenheit((c as number) * 9/5 + 32);
}

const temp = celsius(100);
const converted = toFahrenheit(temp); // Fahrenheit
// temp + converted; // Error! Can't mix Celsius and Fahrenheit

Celsius and Fahrenheit are both numbers at runtime but distinct types at compile time. You can't mix them without explicit conversion.

Common confusions

  • Confused with: branded type

    The difference: Branded types and Newtypes are essentially the same pattern in TypeScript — both use intersection with a phantom property. The term 'Newtype' comes from Haskell where it creates a truly new type. In TypeScript, both are implemented identically using intersection types.

Related terms

Related Resources

Related Lessons

Decode error messages

Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.

View errors

← Back to glossary