insist-types
v1.4.3
Published
Insist on types!
Downloads
2,190
Maintainers
Readme
Insist
Insist on types! Make your code more readable by explicitly requiring type for function parameters.
Install
npm install insist-types
Supports both Node and the browser. On the browser, exported as window.insist
.
Basic Usage
var insist = require('insist-types');
var foo = function (arg1, arg2) {
insist.args(arguments, String, Boolean);
// ...
};
foo('hi', true); // works!
foo('hi', 'true'); // throws error
More interesting stuff
Insist can understand multiple types, optional arguments, nullable types, typed arrays, and classes.
Multiple Types
Just put the desired types in an array.
var insist = require('insist-types');
var foo = function (arg1, arg2) {
insist.args(arguments, [String, Boolean, Object], String);
// ...
};
foo('hi', 'hello'); // works!
foo(true, 'hello'); // works!
foo({}, 'hello'); // works!
foo(1, 'hello'); // throws error
Optional Types
insist.args
always returns an array of the arguments and shifts each argument into the proper
index when dealing with optional types.
var insist = require('insist-types');
var foo = function (arg1, optionalArg2, arg3) {
var args = insist.args(arguments, Number, insist.optional(Object), Function);
// args will be [{number}, {object or null}, {function}]
};
foo(1, function () {}); // works!
foo(2, null, function () {}); // works!
foo(3, {}) // throws error
foo(4) // throws error
Nullable Types
var insist = require('insist-types');
var foo = function (arg1) {
insist.args(arguments, insist.nullable(Function));
// ...
};
foo(null); // works!
foo(function () {}); // works!
foo(); // throws error
foo('wrong') // throws error
Both insist.optional
and insist.nullable
really just augment the type. In the above example, it would have worked to use [Function, null]
instead of insist.nullable(Function)
. If you want to include undefined
make sure you use insist.optional
instead of insist.nullable
.
Typed Arrays
var insist = require('insist-types');
var foo = function (arg1) {
insist.args(arguments, insist.arrayOf(Number));
// ...
};
foo([]); // works!
foo([1]); // works!
foo([1, 2]); // works!
foo([1, '2']); // throws error
You can also nest arrays.
var insist = require('insist-types');
var foo = function (arg1) {
insist.args(arguments, insist.arrayOf([Number, insist.arrayOf(Number)));
// ...
};
foo([]); // works!
foo([1]); // works!
foo([1, [2, 3]]); // works!
foo([1, [2, 3, [4]]]); // throws error
To handle the last case (foo([1, [2, 3, [4]]]);
), you can just use an array instead.
var insist = require('insist-types');
var foo = function (arg1) {
insist.args(arguments, insist.arrayOf([Number, Array]));
// ...
};
foo([]); // works!
foo([1]); // works!
foo([1, [2, 3]]); // works!
foo([1, [2, 3, [4]]]); // works!
Classes
var insist = require('insist-types');
function Bar() {};
var foo = function (arg1) {
insist.args(arguments, Bar);
// ...
};
foo(new Bar()); // works!
foo({}); // throws error
Sublasses work too!
var insist = require('insist-types');
var util = require('util');
var events = require('events');
function Foo() {
events.EventEmitter.call(this);
};
util.inherits(Foo, events.EventEmitter);
var fn = function (arg1) {
insist.args(arguments, events.EventEmitter);
// ...
};
fn(new Foo()); // works!
Anything
Sometimes it's handy to have a definition that'll take anything.
var insist = require('insist-types');
foo = function (arg1) {
insist.args(arguments, insist.anything());
// ...
};
foo(null); // works!
foo(true); // works!
foo("true"); // works!
foo(1); // works!
foo(["true"]); // works!
foo({}); // works!
foo(); // throws error
I've debated a lot about whether null
and undefined
should be include in insist.anything
. Currently, null
is acceptable and undefined
is not because I've found this to be the most useful anything
. Open an issue if you have some input!
Type
It can be valuable to assert that a parameter is actually a type.
var insist = require('insist-types');
foo = function (arg1) {
insist.args(arguments, insist.type());
// ...
};
foo(String); // works!
foo(null); // works!
foo(undefined); // works!
foo(insist.arrayOf(Number)); // works!
foo("bar"); // throws error
Enum
var insist = require('insist-types');
Colors = {
RED: "red",
GREEN: "green",
BLUE: "blue"
};
foo = function (arg1) {
insist.args(arguments, insist.enum(Colors));
// ...
};
foo(Colors.GREEN); // works!
foo("red"); // works!
foo("yellow"); // throws error
foo(Colors); // throws error
Options
You can set options on insist.
insist({isDisabled: true});
// or
var insist = require('insist')({isDisabled: true});
Available Options
isDisabled
When set to true
, all asserts are set to noops, except for insist.args
, which checks for optional expected types (so as to not break argument shifting). In Node, when NODE_ENV
is set to production
, isDisabled is set to true by default, unless INSIST_IN_PROD
is set to true
.
Remover
It's recommended that insist is removed from production code, especially client-side JavaScript, for both size and efficiency. The Remover class makes this simple. It is worth noting, before removing a reference, the reference is checked to make sure that it is not being used to shift arguments. If it is, the reference will not be removed.
var insist = require('insist-types');
var source = fs.readFileSync('source/file.js').toString();
var remover = new insist.Remover();
var newSource remover.removeInsist(source);
fs.writeFileSync('source/out.js', newSource);
Options
Currently, there is only one option for the remover: aliases. This option allows for when insist methods of been aliased to something else in a codebase.
var insist = require('insist-types');
var source = fs.readFileSync('source/file.js').toString();
var remover = new insist.Remover({
aliases: {
args: 'assertArgs',
ofType: 'assertOfType'
}
});
var newSource remover.removeInsist(source);
fs.writeFileSync('source/out.js', newSource);
CLI
The remover is also available through the CLI.
usage: insist-types [-h] [-v] -i [DIR|FILE [DIR|FILE ...]] [-a STRING]
[-t STRING]
Removes insist-types from matching files.
Optional arguments:
-h, --help Show this help message and exit.
-v, --version Show program's version number and exit.
-i [DIR|FILE [DIR|FILE ...]], --include [DIR|FILE [DIR|FILE ...]]
Adds the directory or file to be included in the
processing. At least one required.
-a STRING, --argsAlias STRING
Specifies the alias for insist.args. Defaults to
'insist.args'.
-t STRING, --ofTypeAlias STRING
Specifies the alias for insist.ofType. Defaults to
'insist.ofType'.
Full API
insist.args(arguments, types...) // asserts the type of an arguments object and returns the shifted arguments
insist.ofType(value, type) // asserts the type of a value
insist.isType(type) // asserts that the supplied type is actually a type
insist.isValidType(type) // returns true|false for whether the type is actually a type
insist.isOptionalType(type) // returns true|flase for whether the type is an optional type
insist.isOfType(value, type) // returns true|false for whether the value is of the type
insist.getNameForType(type) // returns the name of the type
insist.getNameForValue(value) // returns the name of the value (ex. String, Anonymous function)
insist.arrayOf(type) // used for creating an array type
insist.nullable(type) // used for creating a nullable type
insist.optional() // used for creating an optional type
insist.anything() // used for a type that can be anything
insist.type() // used for a type that expects a type
insist.enum(SomeEnumObject) // used for creating an enum type
insist.Remover // used to remove references from source
insist.Remover.prototype.removeInsist(source) // removes references
Changelist
1.4.3
- Fixed bug where references that were not calls were still being removed.
1.4.2
- Fixed bug with cyclical references
1.4.1
- Properly exported insist.Remover
1.4.0
- Added CLI for insist.Remover
1.3.0
- Adds insist.Remover for removing references from source. Recommended to be used before shipping code to production.
- Relaxed restriction that types must be functions. Fixes #2.
1.2.1
- Fixed bug with exporting to browser
1.2.0
- Added browser support, now exports to window.insist when module doesn't exist
- Added option support
- Added isDisabled option to explicitly enable or disable (useful for browser environments)
1.1.0
- Added support for checking for types (insist.type)
- Added support for enums