utilities/README.md

# @sapphirecode/utilities

version: 1.6.x

small utility functions to make much needed features easier to work with

## Installation

npm:

> npm i --save @sapphirecode/utilities

yarn:

> yarn add @sapphirecode/utilities

## Usage

```js
const util = require('@sapphirecode/utilities');
```

cut off decimal places to a specified point

```js
util.truncate_decimal(12.345678, 2);
// returns 12.34
```

will return null instead of throwing on invalid json

```js
util.try_parse_json('{{foo');
```

copy an object to prevent modification of the original

```js
const obj = {foo: 'bar'};
const copy = util.copy_object(obj);
copy.foo = 'baz';
console.log(obj.foo); // bar
```

run a regular expression and get a callback for every result

```js
const data = 'foobarfoo';
const regex = /foo/g;
util.run_regex(regex, data, (res) => {
  console.log(res[0]); // will output 'foo' 2 times
});
```

check if a variable is null, undefined or NaN

```js
console.log(util.is_nil(parseInt('abc'))); // true
console.log(util.is_nil('foo')); // false
console.log(util.is_nil(42)); // false
console.log(util.is_nil(null)); // true
console.log(util.is_nil(undefined)); // true
```

filter an array recursively

```js
const to_filter = [
  {name: 'include_foo'},
  {
    name: 'include_bar',
    children: [{name: 'foo'}, {name: 'bar'}],
  },
  {
    name: 'baz',
    children: [{name: 'include_foo'}, {name: 'bar'}],
  },
  {
    name: 'barbaz',
    children: [{name: 'foo'}, {name: 'bar'}],
  },
];
const filter = {
  field: 'name', // the field the filter will apply on
  filter: /^include_.*/iu, // regex filter
};

const result = util.recursive_filter(
  to_filter,
  [filter], // you can specify multiple filters, they will be connected using AND
  'children' // specify which field an objects children are stored in ('children' is default)
);

console.log(JSON.stringify(result, null, 2));
/* output:

[
  { name: 'include_foo' },
  {
    name:     'include_bar',
    children: [
      { name: 'foo' },
      { name: 'bar' }
    ]
  },
  {
    name:     'baz',
    children: [ { name: 'include_foo' } ]
  }
]*/
```

filters can also apply to multiple fields

```js
const result = util.recursive_filter(
  [{name: 'foo', name_2: 'bar'}],
  [
    {
      filter: /foo bar/iu,
      field: ['name', 'name_2'], // fields will be joined with a space in between
      // {name: 'foo', name_2: 'bar'} will become 'foo bar'
    },
  ]
);
```

filter groups can be used to connect filters with OR

```js
const result = util.recursive_filter(
  [...],
  [
    {
      filter: /foo bar/iu,
      field: 'name'
    },
    {
      or: [
        { filter: /foo/u, field: 'bar' },
        { filter: /bar/u, field: 'bar' }
      ]
    }
  ]
);
```

field values can be carried to filter runs on children to filter over the entire tree instead of just one element

```js
  const to_filter = [
    {
      name:     'foo',
      children: [
        { name: 'bar' },
        { name: 'baz' },
        { foo: 'bar' }
      ]
    }
  ];

  const res = util.recursive_filter (
    to_filter,
    [ { field: 'name', filter: /foo bar/ui } ], // values will be separaed by a space
    'children',
    [ 'name' ] // specify which fields should be carried
    // the filters will receive the carried values instead of the plain fields
  );
  
  /* result:
  
  [
    {
      name:     'foo',
      children: [ { name: 'bar' } ]
    }
  ]
  */
```

## License

MIT © Timo Hocker <timo@scode.ovh>