- Notifications
You must be signed in to change notification settings - Fork29
mov37/is.js
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Minimalistic predicate library.
This is a general purpose check library, you may foundtagOf useful if all you want is just check types.
Node:
$ npm install --save @pwn/is
Browser:
<scriptsrc="path/to/is.min.js"></script>
- Zero dependencies.
- Un-opinionated — includes only the bare minimum predicates you're likely to use.
- Works with Node, AMD and all browsers, including IE6.
- Extensible.
A code sample is worth a thousand words:
letis=require('@pwn/is')is.array([])// trueis.not.integer(0)// falseis.propertyDefined({foo :{bar :0}},'foo.bar')// trueis.equal([1,[2,3]],[1,[2,3]])// falseis.deepEqual([1,[2,3]],[1,[2,3]])// true// use a third-party bundleis.use(require('path/to/some/math/bundle'))is.prime(7)// true
All checks, orpredicates inis.js terminology, takes two general forms:
- POSITIVE CHECK:
is.predicate( ...args )- Checks whether certain condition met. - NEGATIVE CHECK:
is.not.predicate( ...args )- The inverse of its corresponding positive check.
That's it! What's next?
- Cheatsheet - List of available predicates shipped with
is.js. - API reference - Detailed documentation on each predicate.
- Writing new predicates - Learn how to define new predicates.
- Annotated source - Source code, annotated.
TL;DR
Abundle is simply a way of organizing related predicates.
bundle:nil
bundle:number
- is.number( value )
- is.numeral( value )
- is.nan( value )
- is.odd( number )
- is.even( number )
- is.finite( number )
- is.infinite( number )
- is.integer( number )
- is.safeInteger( number )
bundle:string
- is.string( value )
- is.emptyString( string )
- is.substring( substring , string , [offset=0] )
- is.prefix( prefix , string )
- is.suffix( suffix , string )
bundle:boolean
bundle:object
- is.object( value )
- is.emptyObject( object )
- is.propertyDefined( object , path )
- is.conforms( object , schema , [strict=false] )
bundle:array
- is.array( value )
- is.arrayLikeObject( value )
- is.inArray( value , array , [offset=0] , [comparator=is.equal] )
bundle:type
- is.sameType( value , other )
- is.primitive( value )
- is.date( value )
- is.error( value )
- is.function( value )
- is.map( value )
- is.regexp( value )
- is.set( value )
- is.symbol( value )
bundle:equality
Checks whether given value isnull.
is.null(null)// trueis.null(undefined)// false
Checks whether given value isundefined.
is.undefined(null)// falseis.undefined(undefined)// true
Checks whether given value exists, i.e, notnull norundefined.
is.exist(null)// falseis.exist(undefined)// false
Checks whether given value is eithernull orundefined.
is.nil(null)// trueis.nil(undefined)// true
Checks whether given value is a number.
is.number(0)// trueis.number(Number.NaN)// trueis.number(Number.POSITIVE_INFINITY)// trueis.number(Number.NEGATIVE_INFINITY)// trueis.number('0')// falseis.number(newNumber(0))// false
Checks whether given value is a numeral, i.e:
- a genuine finite number
- or a string that represents a finite number
is.numeral(null)// falseis.numeral(undefined)// falseis.numeral(true)// falseis.numeral(false)// falseis.numeral(Symbol(0))// falseis.numeral(Symbol.for(0))// falseis.numeral({valueOf(){return0}})// falseis.numeral([0])// falseis.numeral(()=>0)// falseis.numeral('')// falseis.numeral('one')// falseis.numeral('1px')// falseis.numeral(' 0xFF ')// trueis.numeral('1e1')// trueis.numeral('1.1E-1')// trueis.numeral('-1')// trueis.numeral('1.1')// trueis.numeral(newNumber(1))// trueis.numeral(newString('-1.1'))// trueis.numeral(Number.NaN)// falseis.numeral(Number.POSITIVE_INFINITY)// falseis.numeral(Number.NEGATIVE_INFINITY)// false
Checks whether given value isNaN.
is.nan(0)// falseis.nan(Number.NaN)// trueis.nan(newNumber(Number.NaN))// falseis.nan(Number.POSITIVE_INFINITY)// falseis.nan(Number.NEGATIVE_INFINITY)// falseis.nan('one')// false
Checks whether given value is an odd number.
is.odd(1)// trueis.odd(2)// falseis.odd('1')// falseis.odd('2')// falseis.odd(newNumber(1))// falseis.odd(newNumber(2))// falseis.odd(Number.NaN)// falseis.odd(Number.POSITIVE_INFINITY)// falseis.odd(Number.NEGATIVE_INFINITY)// false
Checks whether given value is an even number.
is.even(1)// falseis.even(2)// trueis.even('1')// falseis.even('2')// falseis.even(newNumber(1))// falseis.even(newNumber(2))// falseis.even(Number.NaN)// falseis.even(Number.POSITIVE_INFINITY)// falseis.even(Number.NEGATIVE_INFINITY)// false
Checks whether given value is a finite number.
is.finite(0)// trueis.finite('0')// falseis.finite(Number.NaN)// falseis.finite(Number.POSITIVE_INFINITY)// falseis.finite(Number.NEGATIVE_INFINITY)// false
Checks whether given value is an infinite number, i.e,Number.POSITIVE_INFINITY orNumber.NEGATIVE_INFINITY.
is.infinite(0)// falseis.infinite('0')// falseis.infinite(Number.NaN)// falseis.infinite(Number.POSITIVE_INFINITY)// trueis.infinite(Number.NEGATIVE_INFINITY)// true
Checks whether given value is an integer.
is.integer(0)// trueis.integer('0')// falseis.integer(newNumber(0))// falseis.integer(0.1)// falseis.integer(Number.NaN)// falseis.integer(Number.POSITIVE_INFINITY)// falseis.integer(Number.NEGATIVE_INFINITY)// falseis.integer(Number.MAX_SAFE_INTEGER)// trueis.integer(Number.MIN_SAFE_INTEGER)// trueis.integer(Number.MAX_SAFE_INTEGER+1)// trueis.integer(Number.MIN_SAFE_INTEGER-1)// true
Checks whether given value is a safe integer.
is.safeInteger(0)// trueis.safeInteger('0')// falseis.safeInteger(newNumber(0))// falseis.safeInteger(0.1)// falseis.safeInteger(Number.NaN)// falseis.safeInteger(Number.POSITIVE_INFINITY)// falseis.safeInteger(Number.NEGATIVE_INFINITY)// falseis.safeInteger(Number.MAX_SAFE_INTEGER)// trueis.safeInteger(Number.MIN_SAFE_INTEGER)// trueis.safeInteger(Number.MAX_SAFE_INTEGER+1)// falseis.safeInteger(Number.MIN_SAFE_INTEGER-1)// false
Checks whether given value is a string.
is.string('lipsum')// trueis.string(newString('lipsum'))// false
Checks whether given value is an empty string, i.e, a string with whitespace characters only.
is.emptyString('')// trueis.emptyString(' ')// trueis.emptyString('\f\n\r\t')// trueis.emptyString('\u0009\u000A\u000B\u000C\u000D\u0020')// trueis.emptyString('lipsum')// false
Checks whether one string may be found within another string.
is.substring('ps','lipsum')// trueis.substring('sp','lipsum')// falseis.substring(['ps'],'lipsum')// true; `substring` will be converted to a string as neededis.substring('ps',['lipsum'])// false; `string` must be a stringis.substring('ps','lipsum',2)// trueis.substring('ps','lipsum',3)// falseis.substring('ps','lipsum',3.14)// true; non-integer offset will be omitted and defaults to 0is.substring('ps','lipsum',-4)// true; supports negative offsetis.substring('ps','lipsum',6)// false; offset out of rangeis.substring('ps','lipsum',-7)// false; offset out of range
Checks whetherstring starts withprefix.
is.prefix('lip','lipsum')// trueis.prefix('sum','lipsum')// falseis.prefix('lip',['lipsum'])// false; `string` must be a stringis.prefix(['lip'],'lipsum')// true - `prefix` will be converted to a string as needed
Checks whetherstring ends withsuffix.
is.suffix('sum','lipsum')// trueis.suffix('lip','lipsum')// falseis.suffix('sum',['lipsum'])// false; `string` must be a stringis.suffix(['sum'],'lipsum')// true - `suffix` will be converted to a string as needed
Checks whether given value is a boolean.
is.boolean(1)// falseis.boolean(0)// falseis.boolean(true)// trueis.boolean(false)// trueis.boolean(newBoolean(true))// falseis.boolean(newBoolean(false))// false
Checks whether given value is an object.
is.object(null)// falseis.object(undefined)// falseis.object(0)// falseis.object(newNumber(0))// trueis.object('')// falseis.object(newString(''))// trueis.object(true)// falseis.object(newBoolean(true))// trueis.object(Symbol())// falseis.object(Symbol.for('is'))// falseis.object({})// trueis.object([])// trueis.object(function(){})// true
Checks whether given value is an empty object, i.e, an object without any own, enumerable, string keyed properties.
is.emptyObject({})// trueis.emptyObject({foo :'bar'})// falseis.emptyObject(Object.create({foo :'bar'}))// true; ignore inherited propertiesis.emptyObject(Object.defineProperty({},'foo',{value :'bar'}))// true; ignore non-enumerable propertiesis.emptyObject({[Symbol()] :0})// true; ignore non-string-keyed properties
Checks whetherpath is a direct or inherited property ofobject.
is.propertyDefined(Object.create({foo :'bar'}),'foo')// trueis.propertyDefined({foo :{bar :{baz :0}}},'foo')// trueis.propertyDefined({foo :{bar :{baz :0}}},'foo.bar')// trueis.propertyDefined({foo :{bar :{baz :0}}},'foo.bar.baz')// trueis.propertyDefined({foo :{bar :{baz :0}}},'foo.qux.baz')// falseis.propertyDefined({foo :{bar :{baz :0}}},'foo.bar.baz.qux')// false
Checks whetherobject conforms toschema.
Aschema is an object whose properties are functions that takesthese parameters(in order):
- value:any - The value of current iteration.
- key:string - The corresponding key of current iteration.
- context:object - The object in question.
These functions, orvalidators, are called for each corresponding keyinobject to check whether object conforms to the schema. An object issaid to be conforms to the schema if all validators passed.
In strict mode(wherestrict=true),is.conforms also checks whetherobject andschema has the same set of own, enumerable, string-keyedproperties, in addition to check whether all validators passed.
is.conforms({name :'@pwn/is',access :'public'},{name :is.exist})// trueis.conforms({name :'@pwn/is',access :'public'},{description :is.string})// false; key `description` does not exist on `object`is.conforms({name :'@pwn/is',access :'public'},{name(value,key,context){returnis.exist(value)&&context.access==='public'}})// true//// strict mode//is.conforms({name :'@pwn/is',access :'public'},{name(value,key,context){returnis.string(value)&&value.length>=3}},true// enable strict mode)// false; `object` has extraneous properties
Checks whether given value is an array.
is.array([])// trueis.array('')// falseis.array(document.scripts)// falseis.array(function(){})// false
Checks whether given value is anarray-like object.
An object is qualified asarray-like if it has a property namedlength that is a positive safe integer. As a special case, functionsare never qualified asarray-like.
is.arrayLikeObject([])// trueis.arrayLikeObject('')// falseis.arrayLikeObject(document.scripts)// trueis.arrayLikeObject(function(){})// false
Checks whether given array or array-like object contains certain element.
- value: The element to search.
- array: The array or array-like object to search from.
- offset: The index to search from, inclusive.
- comparator: The comparator invoked per element against
value.
is.inArray(2,[1,2,3])// trueis.inArray(4,[1,2,3])// falseis.inArray(2,[1,2,3],1)// trueis.inArray(2,[1,2,3],2)// falseis.inArray(2,[1,2,3],-2)// true; supports negative offsetis.inArray(2,[1,2,3],3)// false; offset out of rangeis.inArray(2,[1,2,3],-4)// false; offset out of rangeis.inArray([2],[1,[2],3])// false; default comparator is `is.equal`is.inArray([2],[1,[2],3],0,is.deepEqual)// trueis.inArray([2],[1,[2],3],is.deepEqual)// true; `offset` can be omitted when passing a custom comparator onlyis.inArray(2,[1,2,3],(val,arrMember)=>val===arrMember)// true; `comparator` takes two parameters, the element to search and the array element of current iteration
Checks whether given values are of the same type.
is.sameType(0,0)// trueis.sameType(0,'0')// falseis.sameType(0,newNumber(0))// falseis.sameType(0,Number.NaN)// trueis.sameType([],{})// false
Checks whether given value is aprimitive.
is.primitive(null)// trueis.primitive(undefined)// trueis.primitive(0)// trueis.primitive(newNumber(0))// falseis.primitive('')// trueis.primitive(newString(''))// falseis.primitive(true)// trueis.primitive(newBoolean(true))// falseis.primitive(Symbol())// trueis.primitive(Symbol.for('is'))// trueis.primitive({})// falseis.primitive([])// falseis.primitive(function(){})// false
Checks whether given value is aDate object.
is.date(newDate())// true
Checks whether given value is anError object.
is.error(newError())// trueis.error(newTypeError())// true
Checks whether given value is a function.
is.function(function(){})// trueis.function(()=>null)// trueis.function(newFunction())// true
Checks whether given value is aMap object.
is.map(newMap())// true
Checks whether given value is aRegExp object.
is.regexp(/^/)// trueis.regexp(newRegExp())// true
Checks whether given value is aSet object.
is.set(newSet())// true
Checks whether given value is a symbol.
is.symbol(Symbol())// trueis.symbol(Symbol.for('is'))// true
Checks whether given values are equal, usingSameValueZero algorithm.
is.equal(null,undefined)// falseis.equal(0,0)// trueis.equal(0,'0')// falseis.equal(+0,-0)// true; SameValueZerois.equal(Number.NaN,Number.NaN)// true; SameValueZerois.equal([],[])// false
Checks whether given values are deeply equal, i.e:
- If
Type( value ) !== Type( other ), returnsfalse. - For primitives, checks whether they are equal usingSameValueZero.
- For arrays, checks whether they have same set of members, all of which are deeply equal.
- Otherwise, checks whether they have same set of own, enumerable, string keyed properties, all of which are deeply equal.
is.deepEqual(null,undefined)// falseis.deepEqual(0,0)// trueis.deepEqual(0,'0')// falseis.deepEqual(+0,-0)// true; SameValueZerois.deepEqual(Number.NaN,Number.NaN)// true; SameValueZerois.deepEqual([1,{foo :[2,[3,4]],bar :{baz :5}}],[1,{foo :[2,[3,4]],bar :{baz :5}}])// trueis.deepEqual(Object.create({foo :1}),Object.create({foo :2}))// true; only own, enumerable, string-keyed properties are checked
Predicates are essentially functions that checks whether certain condition met based on passed in arguments. They are packaged in variousbundles. Conceptually, a bundle is simply a wayof organizing related predicates. Implementation-wise, a bundle is a just afunction that takes two parameters:
util:object- The utility object.is:object- Theisexport.
Theutil object defines a method calledaddPredicate that allows you to define new predicates:
util.addPredicate( name:string , predicate:function )
- name - The name of the predicate.
- predicate - The predicate function.
Once defined, the predicate will be available on bothis andis.not —util.addPredicate wraps the predicate in a delegate function and automatically handles positive/negative cases for you.
Still confused? Take a look at this sample bundle:
// my_bundle.js// `util` and `is` are passed in as free variables, so you don't// need to call `require( '@pwn/is' )`module.exports=functionbundle(util,is){util.addPredicate('positive',functionisPositive(value){returnis.number(value)&&value>0})util.addPredicate('negative',functionisNegative(value){returnis.number(value)&&value<0})}
To use a bundle, simple callis.use:
is.use( bundle:function )
letis=require('@pwn/is')// import all predicates from my_bundle.jsis.use(require('path/to/my_bundle'))is.positive(+1)// trueis.not.positive(-1)// trueis.negative(-1)// trueis.not.negative(+1)// true
About
Minimalistic predicate library.