Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/s-leroux/obut


https://github.com/s-leroux/obut

Last synced: about 1 month ago
JSON representation

Awesome Lists containing this project

README 

        
getpro

======



A collection of object--and only objects--utilities.



[![Build Status](https://travis-ci.org/s-leroux/obut.png?branch=master)](https://travis-ci.org/s-leroux/obut)



## Installation



    npm install --save obut



## API



### obut.coverage(object, [refFieldName])



Return a copy of the object with all duplicate object references removed

("coverage tree").



Duplicate objects are replaced with a reference construct similar to the

JSON Referece Draft (https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03).



The reference field name can be changed using the refFieldName argument.



```

    const { coverage } = require('obut');



    const inner = {};

    const object = { a : inner, b: inner};



    // object now contains two references to the same inner object



    const actual = coverage({ a : inner, b: inner});

    console.log(actual);



    // one of the reference is replaced by a JSON path object.

    // > { a: {}, b: { '$ref': '#/a' } }

```



### obut.filter(object, test)



_New in 0.2.3_



Return a new object containing only own properties of `object` having passed `test`.



```

    const { filter } = require('obut');



    let original = { a: 1, b: undefined, c: { d: undefined } };

    let actual = filter(original, (key, value) => typeof value !== 'undefined');

    console.log(actual);



    // > { a: 1, c: { d: undefined } }

```



### obut.defined(object)



_New in 0.2.3_



Synonym for `(object) => _filter(object, (key, value) => (typeof value !== 'undefined'))`



### obut.pick(object, desc)



Yet another `pick` function to extract a subset of object properties.



This particular version is considering only object own properties.

It performs a deep walk through the description `desc` to extract

the corresponding fields from `object`:



```

    const { pick } = require('obut');



    let original = { a: 1, b: { c: 3, d: 4 }, f: 6 };

    let actual = pick(original, { a: 10, b: { d: 40 }});

    console.log(actual);



    // > { a: 1, b: { d: 4 } }

```



In `object` a field set to `undefined` is handled the same way as

a missing field, and the default value provided in `desc` is substituted.



```

    let original = { a: 1, b: { c: undefined, d: 4 }, f: 6 };

    let actual = pick(original, { a: 10, b: { c: 30, d: 40, e: 50 }});

    console.log(actual);



    // > { a: 1, b: { c: 30, d: 4, e: 50 } }

```



The `pick` function never produces an `undefined` value. So if a field of

`desc` is `undefined` if will be present in the output only if it was

defined in the original object:



```

    let original = { a: 1, b: undefined };

    let actual = pick(original, { a: undefined, b: undefined, f: undefined});

    console.log(actual);



    // > { a: 1 } }

```



`null` is considered both as a value and as an object. When used in `desc`,

a `null` value is used to copy a field verbatim, regardless if its type.

The only exception is for undefined values, since the output of the `pick` function never contains an `undefined` field:



```

    let original = { a: 1, b: { c: undefined, d: 4 }, f: 6 };

    let actual = pick(original, { a: 10, b: null, f: null, g: null });

    console.log(actual);



    // > { a: 1, b: { d: 4 }, f: 6, g: null }

```



In the example above:

 * the object `b` is copied, excluding the `undefined` value;

 * the value `f` is copied;

 * the missing `g` field is added with the `null` value.



In `object` a field set to `null` is set to `null` in the result too,

regardless of the type of the corresponding field in `desc`.



```

    let original = { a: null, b: null, f: 6 };

    let actual = pick(original, { a: 10, b: { c: 30 }});

    console.log(actual);



    // > { a: null, b: null }

```



Except in the cases explained above, if a field is an _object_ in `desc` but

*not* in the original object, and error is thrown.



#### Working with arrays

`obut.pick` handles array mostly like objects with numerical indexes. So you

can write something like that:



```

    obut.pick([1,2,3],[10,20,30,40])

    // > [ 1, 2, 3, 40 ]

```



You can also mix objects and arrays, `obut.pick` will be able to match fields.

Useful if you want a sparse array containing a sub-set of the original array.



```

    obut.pick([1,2,3],{ 0:0, 5:50}); // BEWARE: in JS arrays are 0-based!

    // > [ 1, <4 empty items>, 50 ]

```



## Node version

Require NodeJS >= v10.0

Tested with v10.0 and v14.15



## License



(The MIT License)



Copyright (c) 2018 [Sylvain Leroux](mailto:[email protected])



Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the

'Software'), to deal in the Software without restriction, including

without limitation the rights to use, copy, modify, merge, publish,

distribute, sublicense, and/or sell copies of the Software, and to

permit persons to whom the Software is furnished to do so, subject to

the following conditions:



The above copyright notice and this permission notice shall be

included in all copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.