Home

Awesome

sanctuary-type-identifiers

A type is a set of values. Boolean, for example, is the type comprising true and false. A value may be a member of multiple types (42 is a member of Number, PositiveNumber, Integer, and many other types).

In certain situations it is useful to divide JavaScript values into non-overlapping types. The language provides two constructs for this purpose: the typeof operator and Object.prototype.toString. Each has pros and cons, but neither supports user-defined types.

sanctuary-type-identifiers comprises:

Specification

For a type to be compatible with the algorithm:

If the type identifier does not conform to the format specified above, it is assumed that the entire string represents the name of the type; namespace will be null and version will be 0.

If the version is not given, it is assumed to be 0.

Usage

const type = require ('sanctuary-type-identifiers');
> const Identity$prototype = {
.   '@@type': 'my-package/Identity@1',
.   '@@show': function() {
.     return 'Identity (' + show (this.value) + ')';
.   },
. }

> const Identity = value => (
.   Object.assign (Object.create (Identity$prototype), {value})
. )

> type (Identity (0))
'my-package/Identity@1'

> type.parse (type (Identity (0)))
{namespace: 'my-package', name: 'Identity', version: 1}

API

<a name="type" href="https://github.com/sanctuary-js/sanctuary-type-identifiers/blob/v4.0.0/index.js#L116">type :: Any -⁠> String</a>

Takes any value and returns a string which identifies its type. If the value conforms to the specification, the custom type identifier is returned.

> type (null)
'Null'

> type (true)
'Boolean'

> type (Identity (0))
'my-package/Identity@1'

<a name="type.parse" href="https://github.com/sanctuary-js/sanctuary-type-identifiers/blob/v4.0.0/index.js#L142">type.parse :: String -⁠> { namespace :: Nullable String, name :: String, version :: Number }</a>

Takes any string and parses it according to the specification, returning an object with namespace, name, and version fields.

> type.parse ('my-package/List@2')
{namespace: 'my-package', name: 'List', version: 2}

> type.parse ('nonsense!')
{namespace: null, name: 'nonsense!', version: 0}

> type.parse (type (Identity (0)))
{namespace: 'my-package', name: 'Identity', version: 1}