g11n-pipeline-flatten

Un/Flattener for jsonpath
=========================

Experimental adjunct to the
Globalization Pipeline Node.js SDK.


Purpose
-------

The purpose of this utility is to flatten key/value pairs so that all keys and values are strings. Some types are ignored, such as empty right hand side values.

Also simple keys and values are by default left alone, so {key: "value"}=flatten({key:"value"}).
The flattenAll: true option will include these keys in the flattening.

News
----

In version 2.x, single quotes are used. This conforms with the Java client as well as jsonpath standards. See https://github.com/IBM-Cloud/gp-js-flatten/issues/18

Usage
-----

Given input=:


{
"foo": "foo",
"bar": "bar",
"baz": {
"quux": true,
"hey": "hi",
"π": 3.14159,
"ignored1": [],
"ignored2": {}
},
"list": [ "a", "b", "c" ]
}


and

``js
const flatten = require('g11n-pipeline-flatten');
const flat = flatten.flatten(input);
`

gives


{
"foo": "foo",
"bar": "bar",
"$.baz.quux": "true",
"$.baz.hey": "hi",
"$.baz['π']": "3.14159",
"$.list[0]": "a",
"$.list[1]": "b",
"$.list[2]": "c"
}


and then

`js
const expand = flatten.expand(flat);
`

gives



{
"foo": "foo",
"bar": "bar",
"baz": {
"quux": "true",
"hey": "hi",
"π": "3.14159"
},
"list": [ "a", "b", "c" ]
}


Using with the Globalization Pipeline
-------------------------------------

The flattener allows you to use deeply nested JSON structures with the Globalization Pipeline Node.js SDK, which service otherwise only supports flat key/value pairs.

See ./sample/SAMPLE-README.md for a full tutorial. The below gives a simple quickstart.

For example, you can “flatten” a JSON object before uploading to the Globalization Pipeline.

`js
const flattener = require('g11n-pipeline-flatten')
var gpClient = require('g11n-pipeline').getClient(…);
gpClient.bundle('mybundle').uploadStrings({
languageId: 'en',
strings: flattener.flatten(require('./en.json'));
}, …);
`

Conversely, you can then “expand” the results when downloading from it.

`js
const flattener = require('g11n-pipeline-flatten')
var gpClient = require('g11n-pipeline').getClient(…);
gpClient.bundle('mybundle').getStrings({
languageId: 'en',
}, (err, result) => {
…
const expanded = flattener.expand(result.resourceStrings);
// “expanded” is now the nested structure
});
``

API reference
-------------

Functions

flatten(obj, [opts])

Flatten a deeply nested object into its jsonpath equivalent

expand(flattened, [opts])

Expand a flattened object into its deep equivalent

flatten(obj, [opts])

Flatten a deeply nested object into its jsonpath equivalent

Kind: global function

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| obj | Object | | The input object |
| [opts] | Object | | Optional input parameters |
| [opts.flattenAll] | Boolean | false | If true, flatten all values, even simple top level keys. |

expand(flattened, [opts])

Expand a flattened object into its deep equivalent

Kind: global function

| Param | Type | Description |
| --- | --- | --- |
| flattened | Object.<string, string> | The flattened object |
| [opts] | Object | Optional input parameters |

docs autogenerated via jsdoc2md

Contributing
------------

See CONTRIBUTING.md.

License
-------

Apache 2.0. See LICENSE.txt

> Licensed under the Apache License, Version 2.0 (the "License");
> you may not use this file except in compliance with the License.
> You may obtain a copy of the License at
>
> http://www.apache.org/licenses/LICENSE-2.0
>
> Unless required by applicable law or agreed to in writing, software
> distributed under the License is distributed on an "AS IS" BASIS,
> WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
> See the License for the specific language governing permissions and
> limitations under the License.