jshape
jshape lets you shape any kind of value in JavaScript. It is ideal for mocking, validating, and fixing potentially unreliable data, which makes it both invaluable and unfortunate.
const asShape = ; ; // returns true; // returns 'true'; // returns 5; // returns { name: 'Amelia', age: 5 }
jshape is 616 bytes when minified and gzipped.
Usage
Add jshape to your project:
npm install jshape --save
Use jshape to apply shapes to any value in JS:
const asShape = ; const currentYear = ; const example = titles: 0: title: 'Something A' isSomething: '1' year: '2018' 1: title: 'Something B' isSomething: null year: '2018' 2: title: 'Something C' isSomething: null ; ; /* returns { titles: [ { title: 'Something A', isSomething: true, year: 2018 }, { title: 'Something B', isSomething: false, year: 2018 }, { title: 'Something C', isSomething: false, year: currentYear } ]} */
jshape runs in all Node environements and browsers including Internet Explorer 9+.
Test jshape in the browser:
Shapers
asShape
Returns any value as a specific kind of value determined by a shape.
const asShape = ; ;
value
: The value being guaranteed as a specific shape.shape
: The function or value used to shape the value.source
: The (optional) source being shaped, which is otherwise the value.
The source
option is helpful when you want to create a new object, rather
than mutate the original.
asShape Usage
const asShape = ; ;
asArray
Returns any value as an array, conditionally preserving the original array.
const asArray = ; ;
value
: The value being guaranteed as an array.
asArray Usage
const asArray = ; ; // returns ['foo', 'bar']
Primative Shapers
asBoolean
Returns any value as a primative boolean.
const asBoolean = ; ;
value
: The value being guaranteed as a primative boolean.
asBoolean Usage
const asBoolean = ; ; // returns true; // returns true; // returns false; // returns false
asNumber
Returns any value as a primative number.
const asNumber = ; ;
value
: The value being guaranteed as a primative number.
asNumber Usage
const asNumber = ; ; // returns 1.337; // returns NaN
asString
Returns any value as a primative string.
const asString = ; ;
value
: The value being guaranteed as a primative string.
asString Usage
const asString = ; ; // returns ''; // returns '0'; // returns 'false'
Advanced Shaping
asHashmap
Returns a hashmap shape for inner element shaping.
const asHashmap = ; ;;
shape
: The value being used to guarantee each element in the object hashmap.match
: The (optional) pattern being used to shape hashmap keys.
asHashmap Usage
const asShape asHashmap = ; ;/* returns { '111': 1, '222': 2} */
asOptional
Returns an optional shape for conditional shaping.
const asOptional = ; ;
shape
: The value used to conditionally shape another value.
asOptional Usage
const asShape asOptional = ; // returns { year: 2018 } // returns { year: null }
How things are shapes
How Booleans are shaped
Booleans are shaped by the truthiness of a value. Values that are false
, or
omitted, or that are 0
, -0
, null
, false
, NaN
, undefined
, or an
empty string return a Boolean primative of false
. All other values, including
any object or the string "false"
, return a Boolean primative of true
.
const asBoolean = ; ; // returns true; // returns true; // returns false; // returns false
How Numbers are shaped
Numbers are shaped by numeric conversion. All values are returned as the numerified version of the value.
const asNumber = ; ; // returns 1.337; // returns NaN
How Strings are shaped
Strings are shaped by any identification. Values that are null
or undefined
are returned as an empty string, and all other values are returned as the
stringified version of the value.
const asString = ; ; // returns ''; // returns '0'; // returns 'false'
How Arrays are shaped
Arrays are shaped by the iterableness of a value. Values that are Arrays are
returned as-is. Values that are array-like objects with a length
property
return an Arrays of that length and their corresponding indexed elements.
Values that are array-like objects with indexed elements and no length
property are returned as Arrays with their length inferred by the length of the
value's own property names. Values that are null
or undefined
return an
empty Array, and all other values are returned as Array with one element which
is the value.
How Hashmaps are shaped
Hashmaps are shaped by a shape and potentially a regular expression. Values are converted into objects, with keys omitted that do not match their optional regular expression.
const asShape asHashmap = ; ;/* returns { '111': 1, '222': 2 'ccc': 3} */
const asShape asHashmap = ; ;/* returns { '111': 1, '222': 2} */