Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/etianen/js-types

Runtime type checking of untrusted data.
https://github.com/etianen/js-types

Last synced: 25 days ago
JSON representation

Runtime type checking of untrusted data.

Awesome Lists containing this project

README 

        
# @etianen/types



Runtime type checking of untrusted data.



## Installing



``` bash

npm install '@etianen/types'

```



**TypeScript:** To take advantage of typings, be sure to set `moduleResolution` to `"node"` in your `tsconfig.json`.



## Overview



When receiving JSON data from an untrusted source, it's tempting to just assume the data is of the expected type and shape. This can lead to confusing errors appearing deep in your code.



@etianen/types provides a mechanism to check that untrusted data is the correct shape, or throw a useful debugging error.



``` ts

import {numberType, arrayOf, ValueError, fromJSON} from "@etianen/types";



const numberArrayType = arrayOf(numberType);

numberArrayType.isTypeOf([1]);  // => true

numberArrayType.isTypeOf(["foo"]);  // => false

numberArrayType.isTypeOf(true);  // => false



try {

    const trustedValue = fromJSON(untrustedString);

} catch (ex) {

    if (ex instanceof ValueError) {

        console.log(ex.toString());

    }

}

```



## API



### fromJS()



Casts `value` to `Type`, or throws a `ValueError`.



``` ts

fromJS(value: Object, type: Type): T;

```



### fromJSON()



Parses `value` as JSON and casts to `Type`, or throws a `ValueError`.



``` ts

fromJSON(value: string, type: Type): T;

```



### Type



A description of a runtime type.



#### Type.isTypeOf()



Checks that `value` is of this `Type`.



``` ts

Type.isTypeOf(value: Object): value is T;

```



#### Type.getName()



Returns the descriptive name of `Type`.



``` ts

Type.getName(): string;

```



#### Type.equals()



Performs a value equality check on two values of this `Type`.



``` ts

Type.equals(a: T, b: T): boolean;

```



### ValueError



Error thrown when a value is of the incorrect type.



#### ValueError.message



A description of the problem.



``` ts

ValueError.message: string;

```



#### ValueError.stack



A stack trace to the source of the problem.



``` ts

ValueError.message: string;

```



#### ValueError.value



The value that caused the error.



``` ts

ValueError.value: T;

```



#### ValueError.toString



A description of the problem, including the value that caused the error.



``` ts

ValueError.toString(): string;

```



## Built-in types



The library of built-in types is designed to be as strict as possible, avoiding

unexpected behavior deep within your code. This means:



* A `Type` does not accept `null` unless explicitly allowed via `nullableOf()`.

* A `Type` does not accept `undefined` unless explicitly allowed via `optionalOf()`.



### stringType



A `Type` representing `string`.



```ts

const stringType: Type;

```



### numberType



A `Type` representing `number`.



```ts

const numberType: Type;

```



### booleanType



A `Type` representing `boolean`.



```ts

const booleanType: Type;

```



### anyType



A `Type` representing any value that is not `null` or `undefined`.



``` ts

const anyType: Type;

```



**Typescript note:** The `Object` type is used in place of `any` to avoid "poisoning" the rest of your codebase with cascading `any`. Use explicit type casts to convert `Object` to known types elsewhere in your codebase, or use `intersectionOf()` if multiple types are allowed.



### `nullableOf()`



A `Type` modifier representing a value that may be `null`.



``` ts

nullableOf(value: Object): Type;

```



### `optionalOf()`



A `Type` modifier representing a value that may be `undefined`.



``` ts

optionalOf(value: Object): Type;

```



### `intersectionOf()`



A `Type` modifier representing a value that must be either of two `Type`s.



``` ts

intersectionOf(typeA: Type, typeB: Type): Type;

```



### `unionOf()`



A `Type` modifier representing a value must be both of two `Type`s.



``` ts

unionOf(typeA: Type, typeB: Type): Type;

```



### `arrayOf()`



A container `Type` representing a homogenous array of another `Type`.



``` ts

arrayOf(valueType: Type): Type>;

```



### `objectOf()`



A container `Type` representing a homogenous object of another `Type`.



``` ts

objectOf(valueType: Type): ObjectOf;

```



### `tupleOf()`



A container `Type` representing a heterogenous array of other `Type`s.



``` ts

tupleOf(types: Array>): Type<[A]>;

tupleOf(types: Array, Type>): Type<[A, B]>;

tupleOf(types: Array, Type, Type>): Type<[A, B, C]>;

tupleOf(types: Array, Type, Type, Type>): Type<[A, B, C, D]>;

tupleOf(types: Array, Type, Type, Type, Type>): Type<[A, B, C, D, E]>;

tupleOf(types: Array>): Type>

```



**Typescript note:** For tuples of more than 5 items, an explicit type cast will be required.



``` ts

// No explicit type cast required.

const smallTupleType: Type<[string, string]> = tupleOf([stringType, stringType]);



// Explicit type cast required.

type BigTuple = [string, string, string, string, string, string];

const bigTupleType: Type = tupleOf([stringType, stringType, stringType, stringType, stringType, stringType]) as Type[BigTuple];

```



### `shapeOf()`



A container `Type` representing a heterogenous object of other `Type`s.



``` ts

shapeOf(types: ObjectOf>): Type;

```



**Typescript note:** Due to lack of support in the Typescript compiler, an explicit type cast is always required.



``` ts

interface MyShape {

    foo: string;

    bar: number;

}



// Explicit type cast required.

const myShapeType: Type = shapeOf({

    foo: stringType,

    bar: stringType,

}) as Type;

```



### `referenceOf()`



A reference `Type`, representing a reference to another `Type`.



``` ts

referenceOf(getType: () => Type): Type;

```



Use this to implement circular references in `Type`s.



``` js

const circularType = shapeOf({

    title: stringType,

    children: arrayOf(referenceOf(circularType)),

});

```



## Build status



This project is built on every push using the Travis-CI service.



[![Build Status](https://travis-ci.org/etianen/js-types.svg?branch=master)](https://travis-ci.org/etianen/js-types)



## Support and announcements



Downloads and bug tracking can be found at the [main project website](http://github.com/etianen/js-types).



## More information



This project was developed by Dave Hall. You can get the code

from the [project site](http://github.com/etianen/js-types).



Dave Hall is a freelance web developer, based in Cambridge, UK. You can usually

find him on the Internet:



- [Website](http://www.etianen.com/)

- [Google Profile](http://www.google.com/profiles/david.etianen)