npm package: @swjc1g11/objecttopaths
Description: Flattens an object to an object where each value is represented by its path in the object. Allows the object to be reassembled with depth from the flattened version of itself.
Author: Shaun Cook
Latest version: 0.0.1

# Object to Paths

This repository is a work in progress to create a small JavaScript library whose primary purpose is to deal with the flattening and reassembly of an object from the flattened data for the purposes of a personal project I am working on.

It can be installed as follows:

```console
npm install @swjc1g11/objecttopaths
```
Once installed, you only have to import the library to begin using it:

```javascript
const objecttopaths = require('@swjc1g11/objecttopaths')
```
It takes an object like this:

```javascript
const original = {
    title: "This is a title",
    description: "This is a description",
    nestedObject: {
        title: "This is a nested title",
        description: "This is a nested description"
    }
}
```

Turns it into this:

```javascript
const paths = {
    "title": "This is a title",
    "description": "This is a description",
    "nestedObject%~%title": "This is a nested title",
    "nestedObject%~%description": "This is an ested description" 
}
```

And then turns that back into this when or if desired:

```javascript
const reassembled = {
    title: "This is a title",
    description: "This is a description",
    nestedObject: {
        title: "This is a nested title",
        description: "This is a nested description"
    }
}
```
# Methods

## objecttopaths.objectToPaths

This function takes an object and returns a flattened version of this object.

In this flattened version of the object, each value is represented by a key formed of its path in the original object, as in the above examples.

## objecttopaths.mergePathsWithObject

This method takes the original object and a set of paths obtained from objectToPaths. It then returns a version of the original object whereby any changes made to the paths are applied to the corresponding value in the original object.

This allows for use cases whereby it is easier to build an application that edits the paths than the object, among other potential use cases.

## objecttopaths.buildObjectFromPaths

This method takes an object of paths and takes its best shot at guessing what the original object looked at, returning what it things the original object might have been.

It suffers from three primary weaknesses at this time:

1. You must choose whether solely numeric keys in an object at any nested level represent indexes in an array or keys in an object. More on this below.
2. If your keys use the chosen separator in their content, the object will be built incorrectly. More on this below, too.
3. Arrays containing mixed data types may not work as expected or cause an error.

To allow users to make a choice on whether purely numeric indexes should be built as part of an array or as an object, you can use a settings object as below:

```javascript
let flattened = objecttopaths.objectToPaths(objectWithNumericKeys)
let reassembled = objecttopaths.buildObjectFromPaths(flattened, {
    'numericKeysRepresentArrayItems': false
})
```

## objecttopaths.getPathSeparator

To view the current separator used to separate the keys that build the path of a value in an original object, it is possible to use the function. The default value is '%~%'.

## objecttopaths.setPathSeparator

In the unlikely event that your existing object keys needs the default value of '%~%', you are able to choose an alternate value with this function. It will stay in effect until the objecttopaths object is destroyed and created.

This will allow you to avoid any conflicts with your own keys. Alternatively, it can be used to set a common delimiter such as '.' that could allow you to re-interpret existing data sources. This could have a multitude of applications that would allow you to rebuild objects from existing data sources that use a path delimiter, or otherwise.