notation

Notation.js

for Node and Browser.

© 2018, Onur Yıldırım (@onury). MIT License.

Utility for modifying / processing the contents of Javascript objects via object notation strings or globs.

Note that this library will only deal with enumerable properties of the source object; so it should be used to manipulate data objects. It will not deal with preserving the prototype-chain of the given object.

Usage

Install via NPM:

npm i notation --save

Notation

Modify the contents of a data object:

const Notation = require('notation');

const obj = { car: { brand: "Dodge", model: "Charger" }, dog: { breed: "Akita" } };
const notation = new Notation(obj);
notation.get('car.model');           // "Charger"
notation
    .set('car.color', 'red')         // { car: { brand: "Dodge", model: "Charger", color: "red" }, dog: { breed: "Akita" } }
    .remove('car.model')             // { car: { brand: "Dodge", color: "red" }, dog: { breed: "Akita" } }
    .filter(['*', '!car'])           // { dog: { breed: "Akita" } }
    .flatten()                       // { "dog.breed": "Akita" }
    .expand()                        // { dog: { breed: "Akita" } }
    .merge({ 'dog.color': 'white' }) // { dog: { breed: "Akita", color: "white" } }
    .copyFrom(other, 'boat.name')    // { dog: { breed: "Akita", color: "white" }, boat: { name: "Mojo" } }
    .rename('boat.name', 'dog.name') // { dog: { breed: "Akita", color: "white", name: "Mojo" } }
    .value;                          // modified source object ^

Glob Notation

With a glob-notation, you can use wildcard stars * and bang ! prefixes. A wildcard star will include all the properties at that level and a bang negates that notation for exclusion.

• Only Notation#filter() method accepts glob notations. Regular notations (without any wildcard or !) should be used with all other members of the Notation class.
• For raw Glob operations, you can use the Notation.Glob class.

Normalize a glob notation list

Removes duplicates, redundant items and logically sorts the array:

const globs = ['*', '!id', 'name', 'car.model', '!car.*', 'id', 'name', 'age'];
console.log(Notation.Glob.normalize(globs));
// => ['*', '!car.*', '!id', 'car.model']

In the normalized result ['*', '!car.*', '!id', 'car.model']:

• id is removed and !id (negated version) is kept. (In normalization, negated wins over the positive, if both are same).
• Duplicate glob, name is removed. The remaining name is also removed bec. * renders it redundant; which covers all possible notations.
• car.model is kept (although * matches it) bec. we have a negated glob that also matches it: !car.*.

Union two glob notation lists

Unites two glob arrays optimistically and sorts the result array logically:

const globsA = ['*', '!car.model', 'car.brand', '!*.age'];
const globsB = ['car.model', 'user.age', 'user.name'];
const union = Notation.Glob.union(globsA, globsB); 
console.log(union);
// => ['*', '!*.age', 'user.age']

In the united result ['*', '!*.age', 'user.age']:

• (negated) !car.model of globsA is removed because globsB has the exact positive version of it. (In union, positive wins over the negated, if both are same.)
• But then, car.model is redundant and removed bec. we have * wildcard, which covers all possible notations.
• Same applies to other redundant globs except user.age bec. we have a !*.age in globsA, which matches user.age. So both are kept in the final array.

Now, filter a data object with this united globs array:

const data = {
    car: {
        brand: 'Ford',
        model: 'Mustang',
        age: 52
    },
    user: {
        name: 'John',
        age: 40
    }
};
const globs = ['*', '!*.age', 'user.age']; // our union'ed globs
const filtered = Notation.create(data).filter(globs).value;
console.log(filtered);
// =>
// {
//     car: {
//         brand: 'Ford',
//         model: 'Mustang'
//     },
//     user: {
//         name: 'John',
//         age: 40
//     }
// }

Note: Notation#filter() and Notation.Glob.union() methods automtically normalizes the given glob list(s).

Documentation

You can read the full API reference here.

Change-Log

1.3.6 (2018-02-24)

• Fixed an issue with Notation.Glob.toRegExp() method that would cause some globs to be cleared out incorrectly when .normalize()d. e.g. "!password" would match "!password_reset" and remove the later. Fixes issue #7.

1.3.5 (2017-10-04)

• Redundant, negated globs are also removed when normalized. Fixes issue #5.
• Fixed shifted index issue with Notation.Glob.normalize(array).
• Fixed countNotes() method.
• Minor revisions.

1.3.0 (2017-09-30)

• Completely re-wrote Notation.Glob.union() static method.
  • Fixed the array mutation issue. Fixes issue #2.
  • Fixed an issue where a glob with wildcard is not properly union'ed. Fixes issue #3.
  • sort (boolean) argument is removed (the output is now always sorted.)
  • Union output is now properly normalized, duplicates and redundant globs are removed, etc...
• Fixed an issue where negated wildcards would be filtered incorrectly in some edge cases (e.g. !*.*.*).
• Added Notation.Glob.normalize(array) static method.
• Added Notation.Glob.toRegExp(glob) static method.
• Added Notation.countNotes(notation) convenience method.
• Improved glob validation.
• Fix import typo that prevents Travis builds succeed.
• Minor revisions, clean-up.
• (dev) Removed dev-dependencies (Grunt and plugins) in favor of NPM scripts. Updated other dev-dependencies. Added more, comprehensive tests.

1.1.0 (2016-09-27)

• Added Notation#expand() method (alias Notation#aggregate()).
• Refactored Notation#getFlat() to Notation#flatten(). Returns instance (chainable) instead of source.
• Notation#separate() returns instance (chainable) instead of source.
• Minor revisions.

v1.0.0 (2016-04-10)

• initial release.

License

MIT.