Wondering what’s next for npm?Check out our public roadmap! »

    jshape

    1.0.0 • Public • Published

    jshape jshape

    NPM Version Build Status Support Chat

    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 } = require('jshape');
     
    asShape('true', Boolean); // returns true
    asShape(true, String); // returns 'true'
    asShape('5', Number); // returns 5
    asShape(
      { name: 'Amelia', age: '5' },
      { name: String, age: Number }
    ); // 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 } = require('jshape');
     
    const currentYear = new Date().getFullYear();
     
    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 }
      }
    };
     
    asShape(example, {
      titles: [{
        title: String,
        isSomething: Boolean,
        year: currentYear
      }]
    }); /* 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:

    <script src="https://unpkg.com/jshape/browser.js"></script>

    Shapers

    asShape

    Returns any value as a specific kind of value determined by a shape.

    const { asShape } = require('jshape');
     
    asShape(value, shape, source);
    • 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 } = require('jshape');
     
    asShape(objectNotBeingMutated, shape, { /* new object */ });

    asArray

    Returns any value as an array, conditionally preserving the original array.

    const { asArray } = require('jshape');
     
    asArray(value);
    • value: The value being guaranteed as an array.
    asArray Usage
    const { asArray } = require('jshape');
     
    asArray({ 0: 'foo', 1: 'bar' }); // returns ['foo', 'bar']

    Primative Shapers

    asBoolean

    Returns any value as a primative boolean.

    const { asBoolean } = require('jshape');
     
    asBoolean(value);
    • value: The value being guaranteed as a primative boolean.
    asBoolean Usage
    const { asBoolean } = require('jshape');
     
    asBoolean('1'); // returns true
    asBoolean(1); // returns true
    asBoolean(0); // returns false
    asBoolean(NaN); // returns false

    asNumber

    Returns any value as a primative number.

    const { asNumber } = require('jshape');
     
    asNumber(value);
    • value: The value being guaranteed as a primative number.
    asNumber Usage
    const { asNumber } = require('jshape');
     
    asNumber('1.337'); // returns 1.337
    asNumber(true); // returns NaN

    asString

    Returns any value as a primative string.

    const { asString } = require('jshape');
     
    asString(value);
    • value: The value being guaranteed as a primative string.
    asString Usage
    const { asString } = require('jshape');
     
    asString(null); // returns ''
    asString(0); // returns '0'
    asString(false); // returns 'false'

    Advanced Shaping

    asHashmap

    Returns a hashmap shape for inner element shaping.

    const { asHashmap } = require('jshape');
     
    asHashmap(shape);
    asHashmap(shape, match);
    • 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 } = require('jshape');
     
    asShape({ '111': '1', '222': 2, 'ccc': 3 }, asHashmap(Number, /^\d+$/));
    /* returns {
      '111': 1,
      '222': 2
    */

    asOptional

    Returns an optional shape for conditional shaping.

    const { asOptional } = require('jshape');
     
    asOptional(shape);
    • shape: The value used to conditionally shape another value.
    asOptional Usage
    const { asShape, asOptional } = require('jshape');
     
    asShape({ year: '2018' }, { year: asOptional(number) }) // returns { year: 2018 }
    asShape({ year: null }, { year: asOptional(number) }) // 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 } = require('jshape');
     
    asBoolean('1'); // returns true
    asBoolean(1); // returns true
    asBoolean(0); // returns false
    asBoolean(NaN); // 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 } = require('jshape');
     
    asNumber('1.337'); // returns 1.337
    asNumber(true); // 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 } = require('jshape');
     
    asString(null); // returns ''
    asString(0); // returns '0'
    asString(false); // 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 } = require('jshape');
     
    asShape({ '111': '1', '222': 2, 'ccc': 3 }, asHashmap(Number));
    /* returns {
      '111': 1,
      '222': 2
      'ccc': 3
    */
    const { asShape, asHashmap } = require('jshape');
     
    asShape({ '111': '1', '222': 2, 'ccc': 3 }, asHashmap(Number, /^\d+$/));
    /* returns {
      '111': 1,
      '222': 2
    */

    Install

    npm i jshape

    DownloadsWeekly Downloads

    1

    Version

    1.0.0

    License

    CC0-1.0

    Unpacked Size

    46 kB

    Total Files

    9

    Last publish

    Collaborators

    • avatar