Utility for modifying / processing the contents of Javascript objects via object notation strings or globs.
Clone or download
Latest commit 956d8cd Aug 2, 2018
Failed to load latest commit information.
lib build 1.3.6 Feb 24, 2018
src fix #7 Feb 24, 2018
test add test for #7 Feb 24, 2018
.editorconfig v1.0.0 May 6, 2016
.eslintrc.json eslint config Aug 2, 2018
.gitattributes v1.0.0 May 6, 2016
.gitignore v1.0.0 May 6, 2016
.npmrc no lock Sep 30, 2017
.travis.yml update travis ci config Sep 30, 2017
LICENSE update license [skip ci] Jan 12, 2018
README.md minor [skip ci] Mar 28, 2018
docma.config.json update docma config Sep 30, 2017
package-lock.json 1.3.6 Feb 24, 2018
package.json update dev deps Feb 24, 2018
webpack.config.js set strict to fix build on Node v4 Sep 30, 2017



for Node and Browser.

build-status npm release dependencies license maintained documentation

© 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.


Install via NPM:

npm i notation --save


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"
    .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'];
// => ['*', '!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); 
// => ['*', '!*.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;
// =>
// {
//     car: {
//         brand: 'Ford',
//         model: 'Mustang'
//     },
//     user: {
//         name: 'John',
//         age: 40
//     }
// }

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


You can read the full API reference here.


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.