type-control
v0.1.3
Published
a utility which allows you to check the types of values at runtime with a TypeScript like+ type syntax
Downloads
1
Maintainers
Readme
type-control
type-control
is a utility which allows you to check the types of values at runtime with a TypeScript like+ type syntax.
Install
npm install type-control
Quick Examples
import { isValidType, assertType } from "type-control";
isValidType("number", 1); // true
isValidType("boolean | string", "foo"); // true
isValidType("none", undefined); // true
isValidType("any, number[], string", false, [2, 3, 4], "bar"); // true
isValidType("Array<number|bigint>", [5, 6, 7n]); // true
isValidType('[boolean, "foo"]', [true, "foo", "bar"]); // false
isValidType('[boolean, "foo", ...]', [true, "foo", "bar"]); // true
isValidType("{ a: number, b: string }", { a: 1, b: "foo" }); // true
isValidType("Error{ message: 'error', ... }", new Error("error")); // true
assertType("string, number", 8, 9); // throws TypeError
see index.test.js for more examples.
Usage
import { isValidType, assertType } from "type-control";
isValidType("type, type, ...", item, item, ...)
Checks item
s value against the type
s and returns boolean
- whether the item
s matches the type
s.
assertType("type, type, ...", item, item, ...)
Checks item
s value against the type
s and throws TypeError: Type mismatch
if the types does not match.
Types
The primitives: undefined
, null
, boolean
, number
, bigint
, string
, symbol
.
isValidType("number", 1); // true
isValidType("undefined", "foo"); // false
isValidType("symbol", Symbol("bar")); // true
none
JavaScript has two primitive values used to signal absent or uninitialized value: null
and undefined
.
A special type none
combines these two types.
isValidType("undefined", undefined); // true
isValidType("null", undefined); // false
isValidType("undefined", null); // false
isValidType("none", undefined); // true
isValidType("none", null); // true
Other types: function
, RegExp
, Error
, Date
, Map
, etc...
isValidType("function", () => {}); // true
isValidType("RegExp", /\s*/); // true
isValidType("Error", new Error("error")); // true
isValidType("Date", new Date()); // true
isValidType("Map", new Map()); // true
isValidType("String", new String("foo")); // true
isValidType("string", new String("foo")); // false
isValidType("string", "foo"); // true
any
There is also a special type any
, that you can use whenever you don’t want a particular value to cause typechecking errors.
isValidType("any", 1); // true
isValidType("any", "foo"); // true
isValidType("any", null); // true
Arrays
To specify the type of an array like [1, 2, 3]
, you can use the syntax number[]
; this syntax works for any type (e.g. string[]
is an array of strings
, and so on). You may also see this written as Array<number>
, which means the same thing.
isValidType("number[]", [1, 2, 3]); // true
isValidType("boolean[]", [true, false, 4]); // false
isValidType("Array<number>", [5, 6, 7]); // true
When an array containing various types:
isValidType("[number, boolean]", [1, true]); // true
isValidType("[number, boolean]", [1, true, 2, 3]); // false
isValidType("[number, boolean, ...]", [1, true, 2, 3]); // true
isValidType("[number, , number]", [1, true, 2]); // true // (eq "[number, any, number]")
isValidType("Array", [1, true, 2]); // true
When another array like object is used:
class MyArray extends Array {}
isValidType("MyArray[number, boolean]", new MyArray(1, true)); // true
isValidType("MyArray<boolean>", new MyArray(true, true, false)); // true
isValidType("any[string, boolean, ...]", ["foo", true, 2]); // true
Objects Types
To define an object type, we simply list its properties and their types.
isValidType("{ a: number, b: string }", { a: 1, b: "foo" }); // true
isValidType("{ a: number, b: string }", { a: 1, b: "foo", c: "bar" }); // false
isValidType("{ a: number, b: string, ... }", { a: 1, b: "foo", c: "bar" }); // true
isValidType("{ '!, _ ]': boolean }", { "!, _ ]": true }); // true
Optional Properties
Object types can also specify that some or all of their properties are optional. To do this, add a ?
after the property name:
isValidType("{ a: number; b?: string }", { a: 1 }); // true
isValidType('{ a: number; " "?: string }', { a: 1, " ": "foo" }); // true
Other objects
class MyArray extends ArrayBuffer {}
isValidType("MyArray{ byteLength: number }", new MyArray()); // true
isValidType("RegExp{ source: '\\s+' }", /\s+/); // true
isValidType('Error{ message: "error" }', new Error("error")); // true
Union Types
A union type is a type formed from two or more other types, representing values that may be any one of these types.
isValidType("number | string", "bar"); // true
isValidType("number | string", 1); // true
isValidType("number | string", null); // false
isValidType("string | string[]", ["foo", "bar"]); // true
Literal Types
In addition to the general types number
, string
, etc., we can refer to specific value in type positions.
isValidType('"bar"', "bar"); // true
isValidType("{ a: 'foo' }", { a: "bar" }); // false
isValidType('{ align: "left" | "center" | "right" }', { align: "left" }); // true
isValidType("{ compare: -1 | 0 | 1 }", { compare: 2 }); // false
isValidType("number|`auto`|null", 5); // true