repository·master·Indexed 27 days ago
https://github.com/gcanti/io-tsA TypeScript runtime type system for IO decoding and encoding. Leveraging functional programming principles from fp-ts, io-ts provides tools for runtime type validation, including stable core features and experimental modules for Decoders, Encoders, Codecs, and Schemas. It allows developers to define composite types, extract static TypeScript types using TypeOf, and handle validation errors with PathReporter and DecodeError.
Note: This module is experimental.
Experimental features are in a high state of flux and may change without notice. This module provides tools for decoding data into typed structures using the Decoder<I, A> interface, which extends K.Kleisli.
Guard module is an experimental feature added in v2.2.0. It provides a set of combinators, constructors, and primitives for creating type guards. Because it is experimental, the API is subject to change without notice. Use it to define schemas that can validate if an input matches a specific type using the .is() method.This module is experimental.
Schemable provides a high-level, composable interface for defining schemas. It is designed to allow for more ergonomic schema construction compared to standard io-ts patterns. Because it is experimental, the API is subject to change without notice.
Added in v2.2.0.
io-ts provides tools for runtime type validation in TypeScript. It is divided into stable features and experimental modules (available in version 2.2+).
The core stable features are documented in the index.ts module.
2.2+)Experimental modules are independent and backward-incompatible with the stable API. They are in a high state of flux and may change without notice. These include:
Decoder.ts moduleEncoder.ts moduleCodec.ts moduleEq.ts moduleSchema.ts module (advanced feature)The TaskDecoder module is an experimental feature (added in v2.2.7) designed for asynchronous decoding. It provides a way to perform decoding operations that return a TaskEither, allowing for side-effectful or asynchronous validation logic.
Warning: As an experimental feature, the API is subject to change without notice.
The Kleisli module provides a functional approach to decoding, allowing you to compose and combine decoders.
Warning: This module is experimental. Features in this module are in a high state of flux and may change without notice. It was added in v2.2.7.
Schema.ts module provides an experimental way to define and manipulate schemas. Note that features in this module are in a high state of flux and may change without notice. This module was added in v2.2.0.In io-ts, a codec is a value of type Type<A, O, I> that represents the runtime version of a static type A.
It provides four primary capabilities:
I to type A via the decode method.A to type O via the encode method.is property.I can be decoded to A via the validate method.Decoding returns an Either type from fp-ts. By convention, Right represents success and Left represents failure.
class Type<A, O, I> {
constructor(
/** a unique name for this codec */
readonly name: string,
/** a custom type guard */
readonly is: (u: unknown) => u is A,
/** succeeds if a value of type I can be decoded to a value of type A */
readonly validate: (input: I, context: Context) => Either<Errors, A>,
/** converts a value of type A to a value of type O */
readonly encode: (a: A) => O
) {}
/** a version of `validate` with a default context */
decode(i: I): Either<Errors, A>
}The FreeSemigroup module is an experimental feature (added in v2.2.7) used to represent a semigroup structure. It allows for the construction of values using of and the combination of values using concat.
Warning: This module is experimental and subject to change without notice.
Since decode returns an Either type, you should handle success and failure cases using fold from fp-ts. This allows you to define specific handlers for errors (Left) and successful values (Right).
import * as t from 'io-ts'
import { pipe } from 'fp-ts/lib/pipeable'
import { fold } from 'fp-ts/lib/Either'
// failure handler
const onLeft = (errors: t.Errors): string => `${errors.length} error(s) found`
// success handler
const onRight = (s: string) => `No errors: ${s}`
pipe(t.string.decode('a string'), fold(onLeft, onRight))
// => "No errors: a string"
pipe(t.string.decode(null), fold(onLeft, onRight))
// => "1 error(s) found"To use io-ts, you must also install fp-ts as it is a required peer dependency.
Run the following command to install the stable version:
npm i io-ts fp-tst.type. To avoid duplicating type definitions, use the t.TypeOf operator to extract the TypeScript static type directly from the codec.