typed-contracts - GitLite

KO | EN

gitlite — search

#hacktoberfest #react #typescript #android #machine-learning #deep-learning #docker #macos #nodejs #awesome #awesome-list #vue #pytorch #mcp

typed-contracts

(★ 95)

Validation with good Flow and TypeScript type inference

File Explorer

Download Latest Version (.zip)

- - check.yml
  - release.yml
- - array.js
  - boolean.js
  - intersection.js
  - literal.js
  - null.js
  - number.js
  - object.js
  - string.js
  - union.js
  - void.js
- .eslintrc.yml
- Contract.js
- ValidationError.js
- - flow-bin_v0.x.x.js
  - jest_v23.x.x.js
  - prettier_v1.x.x.js
- .eslintrc.yml
- mdlint.js
- - array.js
  - boolean.js
  - index.js
  - intersection.js
  - literal.js
  - null.js
  - number.js
  - string.js
  - union.js
  - void.js
- Contract.js
- index.d.ts
- index.js
- ValidationError.js
.eslintignore
.eslintrc.yml
.flowconfig
.gitignore
.markdownlint.json
babel.config.js
CHANGELOG.md
LICENSE.md
package.json
README.md
release.config.js
rollup.config.js
tsconfig.json
yarn.lock

# Installation Guide

1. Get the code

git clone https://github.com/bigslycat/typed-contracts

Downloads the entire project code from GitHub to your computer.

cd typed-contracts

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

npm install

Downloads and installs the libraries listed in package.json.

npm start

Starts the development/run server.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# typed-contracts

[![Lint and test](https://github.com/bigslycat/typed-contracts/workflows/Lint%20and%20test/badge.svg)](https://github.com/bigslycat/typed-contracts/actions?query=workflow%3A%22Lint+and+test%22)

Validation with good Flow and TypeScript type inference

## What it is

`Contract` is a function that receives an arbitrary value and validates it.
`Сontract` returns the value if it passed the validation, or an instance of `ValidationError` otherwise.
Contracts are a 100% guarantee that the data that passed validation matches your expected type definitions.

## Install

npm: `npm install --save typed-contracts`

yarn: `yarn add typed-contracts`

## How it works

All contracts have this interface:

```js
type Contract<+T> = {
  (valueName: string): {
    (value: mixed): ValidationError | T,
    optional(value: mixed): ValidationError | void | T,
    maybe(value: mixed): ValidationError | ?T,
  },

(valueName: string, value: mixed): ValidationError | T,

optional(valueName: string): (value: mixed) => ValidationError | void | T,
  optional(valueName: string, value: mixed): ValidationError | void | T,

maybe(valueName: string): (value: mixed) => ValidationError | ?T,
  maybe(valueName: string, value: mixed): ValidationError | ?T,
}
```

Interface usage:

```js
contract('my value', value)               // => ValidationError | ValidValue
contract.maybe('my value', null)          // => null
contract.maybe('my value', undefined)     // => undefined
contract.maybe('my value', value)         // => ValidationError | ValidValue
contract.optional('my value', undefined)  // => undefined
contract.optional('my value', value)      // => ValidationError | ValidValue
```

Contracts are curried:

```js
contract('my value')(value)
contract('my value').maybe(value)
contract('my value').optional(value)
contract.maybe('my value')(value)
contract.optional('my value')(value)
```

## Contracts can be combined

```js
/* @flow */

const {
  array, object, string,
  union, ValidationError,
} = require('typed-contracts')

type Person = {
  +name: string,
  +gender: 'm' | 'f',
  +friends: $ReadOnlyArray<Person>,
  +email?: string | $ReadOnlyArray<string>,
}

// person returns Person-compatible value or ValidationError
const person = object({
  name: string,
  gender: union('m', 'f'),
  friends: array((valueName, value) => person(valueName, value)),
  email: union(string, array(string)).optional,
})

// We need to control compatibility of the return value type with Person
const userValidate:
  (value: mixed) => Person | ValidationError =
    person('user')

const user = userValidate({ name: 'Vasya' })
```

## Contracts API

### `array`

Aliases: `isArray`, `passArray`, `arr`, `isArr`, `passArr`.

Creates a contract which expects an array of values that are validated by the initial contract.

```js
(...contracts: Array<
  (valueName: string, value: mixed) => ValidationError | T,
>) => Contract
```

### `literal`

Aliases: `isLiteral`, `passLiteral`, `lit`, `isLit`, `passLit`.

Creates a contract which expects a specific string, number or boolean value.

```js
(expected: string | number | boolean) => Contract
```

### `nul`

Aliases: `isNull`, `passNull`.

Creates a contract which expects null.

### `number`

Aliases: `isNumber`, `passNumber`, `num`, `isNum`, `passNum`.

Creates a contract which expects a number.

### `boolean`

Aliases: `isBoolean`, `passBoolean`, `bool`, `isBool`, `passBool`.

Creates a contract which expects a boolean.

### `object`

Aliases: `isObject`, `passObject`, `obj`, `isObj`, `passObj`.

Creates a contract which expects an object whose properties are validated by the corresponding
contracts in the spec.

```js
(spec: { [key: string] (valueName: string, value: mixed) => (ValidationError | T) }) => Contract
```

### `shape`

```js
(spec: { [key: string] (valueName: string, value: mixed) => (ValidationError | void | T) }) => Contract
```

### `objectOf`

Aliases: `isObjectOf`, `passObjectOf`, `objOf`, `isObjOf`, `passObjOf`.

Creates a contract which expects an object whose properties are validated by the corresponding
contracts in the spec.

```js
(...contracts: Array<
  | string
  | number
  | boolean
  | ((valueName: string, value: mixed) => ValidationError | T),
>) => Contract
```

### `string`

Aliases: `isString`, `passString`, `str`, `isStr`, `passStr`.

Creates a contract which expects a string.

### `union`

Aliases: `isUnion`, `passUnion`, `uni`, `isUni`, `passUni`.

Creates a contract which expects a value, validating one of the initial contracts.

```js
(...contracts: Array<
  | string
  | number
  | boolean
  | ((valueName: string, value: mixed) => ValidationError | T),
>) => Contract
```

### `undef`

Aliases: `isUndefined`, `passUndefined`, `isUndef`, `passUndef`, `isVoid`, `passVoid`.

Creates a contract which expects `undefined`.

## Using with ADT

```js
import * as t from 'typed-contracts';
import { type Either, Right, Left } from 'igogo';

const transform = <T>(
  result: t.ValidationError | T,
): Either<t.ValidationError, T> =>
  result instanceof t.ValidationError ? Left(result) : Right(result);

const string = t.string.mapResult(transform);

const number = t.number.match<Either<*, *>>(Right, Left);
```