newtype-ts

library0.3.5jsnpmunverified

newtype-ts provides a robust and performant implementation of newtypes in TypeScript, allowing developers to define distinct types that share the same underlying runtime representation. This helps enforce type safety at compile time, preventing logical errors such as accidentally assigning a `USD` value to a `EUR` variable. The library is currently at version 0.3.5 and is actively maintained, with recent releases focusing on polish and bug fixes. Its key differentiators include a strong reliance on `fp-ts` and `monocle-ts` for functional programming patterns and optics, ensuring no runtime overhead, and offering built-in refinements for common data types like `Integer` or `NonEmptyString`. It supports TypeScript 3.5.1+ and is designed for performance, with newtype operations showing negligible overhead compared to raw type operations.

type-stubs

npm install newtype-ts

github ↗package ↗

INSTALL

IMPORT

SIG · NEWTYPE-TS

newtype-ts

type-stubsjavascriptv0.3.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Newtype

✓ import { Newtype, iso } from 'newtype-ts'

✗ const { Newtype } = require('newtype-ts')

newtype-ts is primarily designed for ESM usage with TypeScript. CJS `require` is generally not recommended for this library, especially with its functional programming paradigms.

iso

✓ import { iso } from 'newtype-ts'

✗ import * as NewtypeTs from 'newtype-ts'; const iso = NewtypeTs.iso;

`iso` is a named export. While the `* as` import works, direct named import is idiomatic and often tree-shakable.

prism

✓ import { prism } from 'newtype-ts'

`prism` is used for creating newtypes with refinements. It's a named export, similar to `iso`.

NonZero

✓ import { NonZero, prismNonZero } from 'newtype-ts/lib/NonZero'

✗ import { NonZero } from 'newtype-ts'

Built-in refinements and their associated prisms are typically imported from their specific paths under `newtype-ts/lib/`.

This quickstart demonstrates how to define a custom newtype (`Email`) using `newtype-ts`, wrap a base type into it, and then use it in a type-safe function, preventing direct usage of the underlying primitive type.

import { Newtype, iso } from 'newtype-ts'; interface Email extends Newtype<{ readonly Email: unique symbol }, string> {} // Create an Iso for Email, allowing wrapping and unwrapping const isoEmail = iso<Email>(); // Example: a function that strictly requires an Email newtype declare function sendEmail(to: Email, subject: string, body: string): Promise<boolean>; // Wrap a string into an Email newtype const userEmail: Email = isoEmail.wrap('test@example.com'); // Use the newtype in a type-safe context sendEmail(userEmail, 'Hello', 'This is a test email.').then(success => { if (success) { console.log('Email sent successfully!'); } else { console.error('Failed to send email.'); } }); // This would cause a static type error: // sendEmail('wrong@example.com', 'Subject', 'Body'); // Unwrap the email for operations requiring the base type const emailString: string = isoEmail.unwrap(userEmail); console.log(`Unwrapped email: ${emailString}`);

Debug

Known issues

breakingVersion 0.3.0 introduced significant breaking changes by upgrading to `fp-ts@2.x` and `monocle-ts@2.x`. This includes removal of deprecated APIs like `Carrier` type, `over` function, and `unsafeCoerce` function.

fix

Upgrade `fp-ts` and `monocle-ts` to their respective v2.x versions. Review your code for usages of `Carrier`, `over`, or `unsafeCoerce` and replace them with modern `newtype-ts` patterns, typically involving `iso` or `prism`.

affects: >=0.3.0

gotchaSince version 0.3.0, `fp-ts` and `monocle-ts` are listed as `peerDependencies` and must be installed manually. Failing to do so will result in runtime errors about missing modules.

fix

Ensure `fp-ts` and `monocle-ts` are installed in your project: `npm install fp-ts@^2.0.0 monocle-ts@^2.0.0` or `yarn add fp-ts@^2.0.0 monocle-ts@^2.0.0`.

affects: >=0.3.0

gotchaThe library heavily relies on TypeScript's structural typing and `unique symbol` for newtype enforcement. Incorrectly defining the `Newtype` interface or directly coercing types can bypass type safety.

fix

Always use `iso.wrap` or `prism.getOption` (or `prism.reverseGet` for safe unwrapping) to create newtype instances. Avoid explicit type assertions (`as Newtype`) unless absolutely necessary and you understand the implications.

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'wrap') OR Cannot access 'iso' before initialization

The `iso` or `prism` function was imported incorrectly or `newtype-ts` was not properly initialized.

fix

Ensure you are using `import { iso } from 'newtype-ts'` and not a CommonJS `require` call, especially in modern TypeScript projects. Verify that your TypeScript configuration correctly handles ESM imports.

Argument of type 'number' is not assignable to parameter of type 'Integer'

Attempting to pass a primitive type (e.g., `number`, `string`) directly to a function or variable expecting a `Newtype`.

fix

You must explicitly wrap the primitive type into the `Newtype` using its associated `iso.wrap()` or `prism.getOption().map(...)` (for refined newtypes). For example, `f(prismInteger.getOption(2).getOrElse(() => throw new Error('not an integer')))`.

Module not found: Error: Can't resolve 'fp-ts'

`fp-ts` or `monocle-ts` peer dependency is missing.

fix

Install the required peer dependencies: `npm install fp-ts@^2.0.0 monocle-ts@^2.0.0`.

Upgrade

Version history

0.3.5latest on npm

Audit

Dependencies

fp-tsrequiredCore dependency for functional programming utilities, required since v0.3.0.

monocle-tsrequiredCore dependency for optics (Iso, Prism), required since v0.3.0.

Agent activity

23 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/gcanti/newtype-ts ↗

packagehttps://www.npmjs.com/package/newtype-ts ↗