TypeScript Newtypes

Common errors

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

  cause 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'

  cause 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'

  cause `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`.

Warnings

• breaking Version 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`.
• gotcha Since 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`.
• gotcha The 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.

Install

• npm install newtype-ts npm
• yarn add newtype-ts yarn
• pnpm add newtype-ts pnpm

Imports

• Newtype
  wrong:

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

  correct:

  import { Newtype, iso } from '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
  wrong:

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

  correct:

  import { iso } from 'newtype-ts'

  `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
  wrong:

  import { NonZero } from 'newtype-ts'

  correct:

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

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

Quickstart

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}`);