or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

branded-types-validation.mdcollection-codecs.mddate-handling.mdfunctional-programming-types.mdindex.mdjson-handling.mdstring-number-transformations.mdutility-functions-codec-modifiers.md
tile.json

tessl/npm-io-ts-types

A collection of codecs and combinators for use with io-ts

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/io-ts-types@0.5.x

To install, run

npx @tessl/cli install tessl/npm-io-ts-types@0.5.0

index.mddocs/

io-ts-types

io-ts-types is a comprehensive collection of runtime type validation codecs and combinators designed to work seamlessly with the io-ts library. It extends io-ts functionality by offering specialized codecs for common data transformations, validations, and functional programming patterns with excellent TypeScript integration.

Package Information

  • Package Name: io-ts-types
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install io-ts-types

Core Imports

import { 
  NumberFromString, 
  DateFromISOString, 
  option, 
  either,
  NonEmptyString,
  UUID
} from "io-ts-types";

For CommonJS:

const { 
  NumberFromString, 
  DateFromISOString, 
  option, 
  either,
  NonEmptyString,
  UUID
} = require("io-ts-types");

Basic Usage

import * as t from "io-ts";
import { NumberFromString, DateFromISOString, option, NonEmptyString } from "io-ts-types";

// Define a user codec with transformations
const User = t.type({
  id: t.number,
  name: NonEmptyString,
  age: NumberFromString,
  birthDate: DateFromISOString,
  avatar: option(t.string)
});

// Decode user data from JSON
const userData = {
  id: 1,
  name: "Alice",
  age: "25",
  birthDate: "1998-01-15T00:00:00Z",
  avatar: { _tag: "Some", value: "avatar.jpg" }
};

const result = User.decode(userData);
// Result contains: { id: 1, name: "Alice", age: 25, birthDate: Date, avatar: Some("avatar.jpg") }

Architecture

io-ts-types is built around several key concepts:

  • Transformation Codecs: Convert between string/number representations and typed values
  • Branded Types: Add compile-time safety to primitive values (UUID, NonEmptyString)
  • Functional Programming Types: Serialize/deserialize Option and Either types to/from JSON
  • Collection Codecs: Handle arrays, sets, and maps with proper encoding/decoding
  • Codec Utilities: Functions to create, modify, and compose codecs
  • Type Safety: Full TypeScript integration with proper type inference and branded types

Dependencies

io-ts-types requires the following peer dependencies:

  • fp-ts ^2.0.0 - Functional programming utilities
  • io-ts ^2.0.0 - Runtime type validation library
  • monocle-ts ^2.0.0 - Optics library for immutable data manipulation
  • newtype-ts ^0.3.2 - Newtype implementation for TypeScript

Capabilities

String and Number Transformations

Codecs for converting between string representations and typed values including numbers, integers, booleans, and big integers.

const NumberFromString: t.Type<number, string, unknown>;
const IntFromString: t.Type<t.Int, string, unknown>;
const BigIntFromString: t.Type<bigint, string, unknown>;
const BooleanFromString: t.Type<boolean, string, unknown>;
const BooleanFromNumber: t.Type<boolean, number, unknown>;

String and Number Transformations

Date Handling

Codecs for parsing and encoding dates from various formats including ISO strings, Unix timestamps, and millisecond timestamps.

const DateFromISOString: t.Type<Date, string, unknown>;
const DateFromNumber: t.Type<Date, number, unknown>;
const DateFromUnixTime: t.Type<Date, number, unknown>;
const date: t.Type<Date, Date, unknown>;

Date Handling

Branded Types and Validation

Branded types that add compile-time safety and runtime validation for special string formats and constraints.

type NonEmptyString = t.Branded<string, NonEmptyStringBrand>;
const NonEmptyString: t.Type<NonEmptyString, string, unknown>;

type UUID = t.Branded<string, UUIDBrand>;
const UUID: t.Type<UUID, string, unknown>;

const regexp: t.Type<RegExp, RegExp, unknown>;

Branded Types and Validation

Functional Programming Types

Codecs for fp-ts Option and Either types with JSON serialization support, enabling functional programming patterns in API communication.

function option<C extends t.Mixed>(codec: C, name?: string): OptionC<C>;
function either<L extends t.Mixed, R extends t.Mixed>(
  leftCodec: L, 
  rightCodec: R, 
  name?: string
): EitherC<L, R>;

function optionFromNullable<C extends t.Mixed>(
  codec: C, 
  name?: string
): OptionFromNullableC<C>;

Functional Programming Types

Collection Codecs

Codecs for working with arrays, sets, and maps including non-empty arrays and proper serialization of complex collection types.

function nonEmptyArray<C extends t.Mixed>(
  codec: C, 
  name?: string
): NonEmptyArrayC<C>;

function setFromArray<C extends t.Mixed>(
  codec: C, 
  O: Ord<t.TypeOf<C>>, 
  name?: string
): SetFromArrayC<C>;

function mapFromEntries<K extends t.Mixed, V extends t.Mixed>(
  keyCodec: K, 
  KO: Ord<t.TypeOf<K>>, 
  valueCodec: V, 
  name?: string
): MapFromEntriesC<K, V>;

Collection Codecs

Utility Functions and Codec Modifiers

Utility functions for creating, modifying, and composing codecs including fallback values, custom validation, and lens generation.

function withFallback<C extends t.Any>(
  codec: C, 
  a: t.TypeOf<C>, 
  name?: string
): C;

function withMessage<C extends t.Any>(
  codec: C, 
  message: (i: t.InputOf<C>, c: t.Context) => string
): C;

function fromRefinement<A>(
  name: string, 
  is: (u: unknown) => u is A
): t.Type<A, A, unknown>;

function getLenses<C extends HasLenses>(
  codec: C
): { [K in keyof t.TypeOf<C>]: Lens<t.TypeOf<C>, t.TypeOf<C>[K]> };

Utility Functions and Codec Modifiers

JSON Handling

Comprehensive JSON parsing and validation with proper type definitions for all JSON value types.

type Json = boolean | number | string | null | JsonArray | JsonRecord;
const Json: t.Type<Json>;
const JsonFromString: t.Type<Json, string, string>;

JSON Handling

Types

Core Interface Types

interface NonEmptyStringBrand {
  readonly NonEmptyString: unique symbol;
}

interface UUIDBrand {
  readonly UUID: unique symbol;
}

interface JsonRecord {
  readonly [key: string]: Json;
}

interface JsonArray extends ReadonlyArray<Json> {}

interface ReadonlyNonEmptyArray<A> extends ReadonlyArray<A> {
  readonly 0: A;
}

Codec Interface Types

interface EitherC<L extends t.Mixed, R extends t.Mixed> 
  extends t.Type<Either<t.TypeOf<L>, t.TypeOf<R>>, EitherOutput<t.OutputOf<L>, t.OutputOf<R>>, unknown> {}

interface OptionC<C extends t.Mixed> 
  extends t.Type<Option<t.TypeOf<C>>, OptionOutput<t.OutputOf<C>>, unknown> {}

interface NonEmptyArrayC<C extends t.Mixed> 
  extends t.Type<NonEmptyArray<t.TypeOf<C>>, NonEmptyArray<t.OutputOf<C>>, unknown> {}

Output Types for Serialization

type EitherOutput<L, R> = LeftOutput<L> | RightOutput<R>;
type LeftOutput<L> = { _tag: 'Left'; left: L };
type RightOutput<R> = { _tag: 'Right'; right: R };

type OptionOutput<A> = NoneOutput | SomeOutput<A>;
type SomeOutput<A> = { _tag: 'Some'; value: A };
type NoneOutput = { _tag: 'None' };