@etchedjs/type NPM

@etchedjs/type

Type all your JS code, only in JS, even on the runtime

A utility to type the @etchedjs/etched models.

Install

npm i @etchedjs/type

API

`type(name, wantedType, throwable, canBeNullish = false)`

Used create a typing model

name: the setter name
wantedType: the wanted type, one of the types or a type extending one of them
throwable: a callback function to throw the error on the current line, always just e => e()
canBeNullish: an optional boolean to allow a nullish value

Example:

// a module exporting a user model
import { model } from '@etchedjs/etched'
import type, * as types from '@etchedjs/type'

const user = model() // just used for a self-reference

export default model(
  user,
  type('id', types.number, e => e()), // must be a number
  type('name', types.string, e => e()), // must be a string
  type('createdAt', types.instance(Date), e => e()), // must be a date
  type('updatedAt', types.instance(Date), e => e(), true), // must be a date or nullish
  type('sponsor', types.fulfill(user), e => e(), true) // must be a user or nullish
)

Types

`boolean`

A type to validate a boolean

`bigint`

A type to validate a bigint

`number`

A type to validate a number

`object`

A type to validate an object

`string`

A type to validate a string

`symbol`

A type to validate a symbol

`array`

A type to validate an array

`key`

A type to validate a key (string or symbol)

`syncFunction`

A type to validate a function

`asyncFunction`

A type to validate an asynchronous function

`syncGenerator`

A type to validate a generator function

`asyncGenerator`

A type to validate an asynchronous generator function

Methods

`etched(model)`

Returns a type to validate an object that etches the provided model

`fulfilled(model)`

Returns a type to validate an object that fulfills the provided model

`instance(constructor)`

Returns a type to validate an object that inherit from the provided constructor prototype

`iterableOf(type)`

Returns a type to validate an etched iterable of provided type

`arg(type, expected, throwable, canBeNullish = false)`

type: Must be one of param/rest
expected: Must be a type to validate the param value
throwable: a callback function to throw the error on the current line, always just e => e()
canBeNullish: an optional boolean to allow a nullish value

`expected(expected, throwable, canBeNullish = false)`

expected: Must be a type to validate the return value (or any promised/yielded one)
throwable: a callback function to throw the error on the current line, always just e => e()
canBeNullish: an optional boolean to allow a nullish value

`fn(type, expected, [...args], throwable)`

type: Must be one of syncFunction/asyncFunction/syncGenerator/asyncGenerator
expected: Must be a type to validate the return value (or any promised/yielded one)
params: An optional array containing the argument types, inheriting from param or rest
throwable: A callback function to throw the error on the current line, always just e => e()

Returns a type to validate a function, with a .of(fn) that returns a typed function that wraps the provided one.

Example

const fnType = types.fn(
  types.asyncGenerator,
  types.expected(types.string, e => e()),
  [
     types.arg(types.param, types.string, e => e()),
     types.arg(types.rest, types.string, e => e())
  ],
  e => e())

const fn = fnType.of(async function * (first, ...rest) {
   const values = [first, ...rest]

   while (values.length > 1) {
      yield values.shift()
   }

   return values.shift()
})

const generator = fn('first', 'second', 'third')

console.log(await generator.next()) // { value: 'first', done: false }
console.log(await generator.next()) // { value: 'second', done: false }
console.log(await generator.next()) // { value: 'third', done: false }

`transformer(inputType, outputType, throwable, fn)`

inputType: The required input type
outputType: The required output type
throwable: A callback function to throw the error on the current line, always just e => e()
fn: A function transforming an etched instance to another one

Returns your function type guarded.

It enforces

inputType & outputType to be some etched object
fn to be a function
the instance to satisfy the inputType
the fn result to satisfy the outputType

Example

const inputModel = model(
  type('a', types.number, e => e()),
  type('b', types.number, e => e()),
  type('c', types.number, e => e())
)

const outputModel = model(
  type('d', types.number, e => e()),
  type('e', types.number, e => e()),
  type('f', types.number, e => e())
)

const instance = fulfill(inputModel, {
  a: 1,
  b: 2,
  c: 3
})

const transform = types.transformer(
  types.fulfilled(inputModel),
  types.fulfilled(outputModel),
  e => e(),
  ({a: d, b: e, c: f}) => fulfill(outputModel, {d, e, f})
)

console.log(transform(instance)) // { d: 1, e: 2, f: 3 }

Flags

The flags are some special types to add a specific behavior on a type

`nullish`

A flag to allow a nullish value

model(nullish, { type })

`param`

A flag to mark a type as a function parameter

model(param, type)

`rest`

A flag that extends param but for a rest parameter

model(rest, type)

Extend a type

// a module exporting an integer type, extending number 
import { model } from '@etchedjs/etched'
import { number } from '@etchedjs/type'

export default model(number, {
  set value (value) {
    if (!Number.isInteger(value)) {
      throw new TypeError('Must be an integer')
    }
  }
})

More some complex type examples: https://gist.github.com/Lcfvs/4b1523653bfe54605b82113170299f61