# Nested

[![npm](https://img.shields.io/npm/v/@basd/nested?style=flat&logo=npm)](https://www.npmjs.com/package/@basd/nested)
[![pipeline](https://gitlab.com/frenware/utils/nested/badges/master/pipeline.svg)](https://gitlab.com/frenware/utils/nested/-/pipelines)
[![license](https://img.shields.io/npm/l/@basd/nested)](https://gitlab.com/frenware/utils/nested/-/blob/master/LICENSE)
[![downloads](https://img.shields.io/npm/dw/@basd/nested)](https://www.npmjs.com/package/@basd/nested) 

[![Gitlab](https://img.shields.io/badge/Gitlab%20-%20?logo=gitlab&color=%23383a40)](https://gitlab.com/frenware/utils/nested)
[![Github](https://img.shields.io/badge/Github%20-%20?logo=github&color=%23383a40)](https://github.com/basedwon/@basd/nested)
[![Twitter](https://img.shields.io/badge/@basdwon%20-%20?logo=twitter&color=%23383a40)](https://twitter.com/basdwon)
[![Discord](https://img.shields.io/badge/Basedwon%20-%20?logo=discord&color=%23383a40)](https://discordapp.com/users/basedwon)

Provides nesting capabilities to classes allowing you to create deeply nested object structures, while also enabling you to traverse them efficiently.

## Features

- Simple API for creating nested object hierarchies.
- Built-in `.root` property for accessing the root of the hierarchy.
- `.sub()` method for creating sub-nodes.

## Installation

```bash
npm install @basd/nested
```

## Usage

Import the `Nested` class mixin from the package:

```js
import Nested from '@basd/nested'
```
or
```js
const Nested = require('@basd/nested')
```

Create a nested instance

```js
const nested = new Nested()
```

Extend your own class with the `Nested` mixin:

```js
class MyClass extends Nested {
  // Your implementation here
}

const root = new MyClass()
```

### Create a Nested Object

```js
const nodeA = root.sub('nodeA')
const nodeB = nodeA.sub('nodeB')
```

### Access Parent and Root Nodes

```js
console.log(nodeB.parent === nodeA) // true
console.log(nodeB.root === root)    // true
```

### Dynamic Options

You can use a function as options to `sub()`:

```js
const dynamicNode = root.sub('dynamic', (node, part) => ({
  someOption: `${node.someOption}/${part}`
}))
```

## Documentation

- [API Reference](/docs/api.md)

### `Nested.mixin(childClass)`

Mix the `Nested` functionality into a `childClass`.

### `root()`

Returns the root node of the current hierarchy.

### `sub(path, opts, ...args)`

Creates a sub-node at the specified `path`. You can optionally pass a custom `opts` object or a function for dynamic configuration.

## Tests

In order to run the test suite, simply clone the repository and install its dependencies:

```bash
git clone https://gitlab.com/frenware/utils/nested.git
cd nested
npm install
```

To run the tests:

```bash
npm test
```

## Contributing

Thank you! Please see our [contributing guidelines](/docs/contributing.md) for details.

## Donations

If you find this project useful and want to help support further development, please send us some coin. We greatly appreciate any and all contributions. Thank you!

**Bitcoin (BTC):**
```
1JUb1yNFH6wjGekRUW6Dfgyg4J4h6wKKdF
```

**Monero (XMR):**
```
46uV2fMZT3EWkBrGUgszJCcbqFqEvqrB4bZBJwsbx7yA8e2WBakXzJSUK8aqT4GoqERzbg4oKT2SiPeCgjzVH6VpSQ5y7KQ
```

## License

Nested is [MIT licensed](https://gitlab.com/frenware/utils/nested/-/blob/master/LICENSE).