shadowing

Light-weighted object/array analyse tool.

Description

shadowing offers an easy way to judge whether the object / array / string / number is what you want.

Table of Contents

• Get Started
• APIs
• Move Forward
  • Deep Comparation Between Objects
  • Shadow of Array
  • More Than Strictly Equal
  • Shadowing Mode
  • Number Range
• Examples
• CHANGELOG
• Homepage

Get Started

var shadowing = require('shadowing');

shadowing(
    /* origin */ { name: 'YounGoat', gender: 'male' },
    /* shadow */ { gender: 'male' }
);
// RETURN true

shadowing(
    /* origin */ { linkman: { name: 'YounGoat', gender: 'male' } },
    /* shadow */ { linkman: { gender: 'male' } }
);
// RETURN true

shadowing(
    /* origin */ { name: 'YounGoat', gender: 'male' },
    /* shadow */ { gender: shadowing.or('male', 'female') }
);
// RETURN true

shadowing(
    /* data */ 99,
    /* definition */ shadowing.numberRange('>90 <=120')
);
// RETURN true

APIs

const shadowing = require('shadowing');
const NumberRange = require('shadowing/NumberRange');

• boolean shadowing( origin, shadow )
• boolean shadowing( origin, shadow, string mode )
• class shadowing.Shadow( Function judge )
• symbol shadowing.EXIST
• shadowing.Shadow shadowing.or( Shadow shadow1, Shadow shadow2 [, ...] )
• shadowing.Shadow shadowing.and( Shadow shadow1, Shadow shadow2 [, ...] )
• shadowing.Shadow shadowing.has( string propertyName [, ...] )
• shadowing.Shadow shadowing.hasnot( string propertyName [, ...] )
• shadowing.Shadow shadowing.numberRange( string numberRangeCode )

Move Forward

• Deep Comparation Between Objects
• Shadow of Array
• More Than Strictly Equal

Deep Comparation Between Objects

Suppose that we want an object which:

• has property named "linkman",
  and property "linkman" is an object with property "gender",
  which valued "male";

• has property named "city",
  and property "city" is an object with property "name",
  which valued "Shanghai".

Before, we will code like:

if (foo
    && foo.linkman
    && foo.linkman.gender === 'male'
    && foo.city
    && foo.city.name === 'Shanghai') {
        // ...
    }

Or, JSON Schema may be a more formal choice:

// To run this snippet, do "npm install ajv" firstly.

var foo = {
    linkman: {
        name: 'YounGoat',
        gender: 'male'
    },
    city: {
        name: 'Shanghai'
    }
};

var schema = {
    type: 'object',
    properties: {
        linkman: {
            type: 'object',
            properties: {
                gender: {
                    type: 'string',
                    enum: ['male']
                }
            }
        },
        city: {
            type: 'object',
            properties: {
                name: {
                    type: 'string',
                    enum: ['Shanghai']
                }
            }
        }
    }
};

var Ajv = require('ajv');
if ((new Ajv).validate(schema, foo)) {
    // ...
}

Now, it is easier and more natural to achieve the target by shadowing:

var foo = {
    linkman: {
        name: 'YounGoat',
        gender: 'male'
    },
    city: {
        name: 'Shanghai'
    }
};

var shadow = {
    linkman: { gender: 'male' },
    city: { name: 'Shanghai' }
};

var shadowing = require('shadowing');
if (shadowing(foo, shadow)) {
    // ...
}

Shadow of Array

The module can also be used to calculate the shadow of an array. E.g.

shadowing( [ 1, 2, 3 ], [ 2 ] );
// RETURN true

shadowing( [ 1, 2, 3 ], [ 4 ] );
// RETURN false

shadowing( [ 1, 2, 3 ], 2 );
// RETURN false

According to shadowing, as you can see, the shadow of an array origin MUST be an array too. And, if items of origin array are scalar values, each items of the shadow array SHOULD be found in the origin array. However, while the origin array has vectorial items, the items of the shadow array NEED NOT strictly equal to any item of the origin. Instead, they MAY be shadow of at least one item of the origin. E.g.

var origin = [ { gender: 'male', age: 22 }, { gender: 'female', age: 20 } ];

shadowing( origin, [ { gender: 'male' }] );
// RETURN true

More Than Strictly Equal

Sometime, we wanna make little changes. The module offers following ways for you to create shadows a little more adaptable,

var shadow = {
    // The origin SHOULD have property "linkman".
    linkman: shadowing.EXIST
};

var shadow = {
    // The origin SHOULD have property "linkman",
    // and sub-property "gender" valued string "male" or "female".
    linkman: {
        gender: shadowing.or('male', 'female')
    }
};

/**
 * The origin SHOULD have both property "linkman" and "city", equals to
 * { linkman: shadowing.EXIST, city: shadowing.EXIST }
 */
var shadow = shadowing.and(
    { linkman: shadowing.EXIST },
    { city: shadowing.EXIST }
);

If there is some numbers, it is usual to know whether it belongs to a number set instead of whether it equals to some exact value. NumberRange is designed for such purpose. E.g.

var shadow = {
    year: shadowing.numberRange('1980 1987 >2017')
};

Shadowing Mode

Beyond the default mode named "strict", there are other two mode available: "normal" and "loose".

• strict Mode
  This is the default mode. Each scalar value in origin SHOULD find its strict equal or an instance of shadowing.Shadow covering itself in shadow.

• normal Mode
  This mode is close to strict mode but equal is accepted as replacement of strict equal. E.g.

  // Falsy values will shadow each other in normal mode.
  // So do truthy values.
  
  shadowing(0, false);
  // RETURN false
  
  shadowing(0, false, 'normal');
  // RETURN true

• loose Mode
  Just as the name implies, this mode is looser than normal mode in:

  1. A string may be regarded as shadow of a number if the former string can be successfully construc a NumberRange which covers the latter number.

Examples

We offer some examples to explain how shadowing works. There will be an array of test cases in each example file. A test unit is also an array with four items:

[
    origin,  /* The origin object/array/others */
    shadow,  /* The shadow to be tested */
    ifValid, /* If the shadow is valid shadow to the origin according to shadowing */
    description
]

• Basic Usage
• Shadow of Arrays
• Logic Operators
• Ranged Shadow
• Edge Cases