npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

runtype-check

v1.1.0

Published

Runtime type-checking of any value in javascript

Downloads

2

Readme

Runtype

A zero-dependency library to check any javascript type with error messages pointing to mistakes.

Example

const runType = require('runtype');

// somehow obtain an object
let person = {
  name: 'Actual Human',
  relativeLocation: '21 km away',
  age: 19,
  picture: 'some/picture.png',
  description: `Hello, I am real human.
I enjoy normal activities such as breathing air and walking with my leg`
}

let badPerson = {
  name: 'no',
  relativeLocation: 50,
  age: '61 y.o.',
  picture: { url: '/404.html' }
}

const schema = {
  name: 'string',
  relativeLocation: 'string',
  age: 'number',
  picture: 'string',
  description: 'string'
}

runType(person, schema) // -> true
runType(badPerson, schema)
// Returns a string:
/*
There were multiple problems with this object:
    - Key "relativeLocation" is not valid:
        Value "50" (type number) is not assignable to type string.
    - Key "age" is not valid:
        Value "61 y.o." (type string) is not assignable to type number.
    - Key "picture" is not valid:
        Value "[object Object]" (type object) is not assignable to type string.
    - The key "description" is required but missing from this object.
*/

Usage

runType(value: any, schema: Schema): true | string

Checks the value against the schema and returns either true if value matches all types, or string with an error, that points to a mismatch.

Schema

Schema is always an array of different types, if schema is not an array, it is converted to an array with one value.

If any of the items of the schema's array matches the value, the value is considered valid. That means that schema's array works like an "or".

runType({
  nice: 'a string, but could be a number'
}, {
  nice: ['string', 'number']
})
// NOTE:
runType('valid', 'string'); /* is the same as */ runType('valid', ['string'])

For each of schema's items:

If it's a string:

  • If it is one of the following, it is assumed that schema is a type:

    • any or * - Always returns true.

    • string, boolean, number, object, function, bigint, symbol, undefined - self-explanatory, but object does not match null

    • nullish - Matches null, undefined, false, "", 0, NaN

    • infinite - Positive and negative infinity

    • realnumber - Number that is not NaN or infinite.

    • integer - Matches any integer (not NaN or infinite)

    A type can also be inverted if you put a bang (!) before its name.

    Inverted types are the opposite of their normal counterpart, except for realnumber and integer - these two still only match numbers.

  • If it is not one of the following, it is a literal string and runtype just checks for equality.

  • If the string is wrapped in double quotes ("), they are stripped and the string is literal

// To match with "string"
runType({
  a_key: 'string'
}, {
  a_key: `"string"` // <-- notice the quotes
}) // -> true

The best practice is to always wrap literal strings with double quotes

If it's an array:

  • If it has no items, matches any kind of array

  • If it has items, tries to match at least one of these items to each element in the target array.

// This matches an array with either strings or objects with key "value"
runType([
  'a string',
  { value: 'string in an object' }
], [[
  'string', { value: 'string' } // Notice the double brackets
]])

Keep in mind that [ ['string'], [{ value: 'string' }] ] is invalid, because it will first try to check if both elements of the array are strings and then try to check if both elements are objects with a "value" key.

If it's an object:

  • Matches an object with the same set of keys. Keys can be marked as optional by appending a question mark (?) to them.

  • If there is a generic key type (*), runtype will try to match the unknown keys to it.

runType({
  required_value: 'some string',
  another_value: 1_000,
  obj: {
    any_key: 'but the value is string'
  }
}, {
  required_value: 'string',
  another_value: 'realnumber',
  obj: {
    '*': 'string'
  },
  'optional?': 'any'
}) // -> true

If the type is a function, it will get called with:

  • val: any - the value to check

  • betterTypeof: function - like the typeof operator, but returns "null" if the value is null

It must return:

  • Either true, if the check was successful

  • Or a string with an error.

  • If it returns anything else, that will be considered an error and will generate a generic error message:

    Type assertion by function failed on value "${val}" (type ${better typeof val}): ${return value from the function}.

runType({
  value: -15
}, {
  value: (v) => v < 0 ? `Value cannot be less than zero` : true
})

If the type is anything else, it will just get strictly compared (===) to the value.