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'
    }
  ]
);
```

to improve the performance of recursive_filter you can generate a search index before running the function

```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'}],
  },
];

util.filter_index(
  to_filter, // object to index
  'name', // fields to search on (array or string depending on the amount of fields)
  'children', // field where the children are stored (default: children)
  'search_index' // field where the index should be stored (default: search_index)
)

const filter = {
  field: 'search_index', // filter based on the index field instead
  filter: /^include_.*/iu,
};

const result = util.recursive_filter(
  to_filter,
  [filter],
  'children',
  true // let the function know, that it is running on an indexed object
);
```

## License

MIT © Timo Hocker <timo@scode.ovh>