# expand-object

> Expand a string into a JavaScript object using a simple notation. Use the CLI or as a node.js lib.

Latest version **0.4.2** (published 2016-01-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install expand-object
pnpm add expand-object
yarn add expand-object
bun add expand-object
```

Provides the command `expand-object`.

## Health

**Score 5/100 (F)** — status: abandoned.

Warnings: low downloads; no types; no esm support; has vulnerabilities; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2016-01-29 |
| First published | 2015-05-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 4 |
| Known vulnerabilities | 1 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 26 |
| Author | Jon Schlinkert |
| Maintainers | jonschlinkert, doowb |
| Keywords | get, has, hasown, key, keys, nested, notation, object, prop, properties, property, props, set, value, values |

## Links

- npm: https://www.npmjs.com/package/expand-object
- Repository: https://github.com/jonschlinkert/expand-object
- npm.io page: https://npm.io/package/expand-object

## Dependencies (4)

- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [get-stdin](https://npm.io/package/get-stdin.md) ^5.0.1
- [is-number](https://npm.io/package/is-number.md) ^2.1.0
- [set-value](https://npm.io/package/set-value.md) ^0.3.3

## Alternatives

- [@gemini-wallet/core](https://npm.io/package/@gemini-wallet/core.md) — 515.6K weekly downloads
- [utility](https://npm.io/package/utility.md) — 416.6K weekly downloads
- [@primno/dpapi](https://npm.io/package/@primno/dpapi.md) — 7.2K weekly downloads
- [pi-readseek](https://npm.io/package/pi-readseek.md) — 3.7K weekly downloads
- [@emilia-protocol/verify](https://npm.io/package/@emilia-protocol/verify.md) — 1.1K weekly downloads

## Recent versions

- 0.4.2 (latest) — 2016-01-29
- 0.4.1 — 2015-12-23
- 0.4.0 — 2015-11-03
- 0.3.8 — 2015-08-07
- 0.3.7 — 2015-08-07
- 0.3.6 — 2015-08-05
- 0.3.5 — 2015-08-05
- 0.3.4 — 2015-08-05
- 0.3.3 — 2015-08-05
- 0.3.2 — 2015-08-05
- 0.3.1 — 2015-08-05
- 0.2.3 — 2015-08-01
- 0.2.2 — 2015-08-01
- 0.2.1 — 2015-08-01
- 0.2.0 — 2015-08-01
- … 4 more at https://npm.io/package/expand-object/versions

## README

# expand-object [![NPM version](https://img.shields.io/npm/v/expand-object.svg)](https://www.npmjs.com/package/expand-object) [![Build Status](https://img.shields.io/travis/jonschlinkert/expand-object.svg)](https://travis-ci.org/jonschlinkert/expand-object)

> Expand a string into a JavaScript object using a simple notation. Use the CLI or as a node.js lib.

- [Install](#install)
  * [Type casting](#type-casting)
- [Install](#install-1)
- [CLI](#cli)
- [node.js](#nodejs)
  * [children](#children)
  * [siblings](#siblings)
    + [general siblings](#general-siblings)
    + [adjacent siblings](#adjacent-siblings)
    + [difference between sibling types](#difference-between-sibling-types)
  * [key-value pairs](#key-value-pairs)
  * [arrays](#arrays)
- [Usage examples](#usage-examples)
- [Related projects](#related-projects)
- [Running tests](#running-tests)
- [Contributing](#contributing)
- [Author](#author)
- [License](#license)

_(TOC generated by [verb](https://github.com/verbose/verb) using [markdown-toc](https://github.com/jonschlinkert/markdown-toc))_

## Install

Install with [npm](https://www.npmjs.com/)

```sh
$ npm i expand-object --save
```

Also see [collapse-object](https://github.com/jonschlinkert/collapse-object), for doing the reverse of this library.

**Examples**

```js
expand('a')
//=> {a: ''}

expand('a.b')
//=> {a: {b: ''}}

expand('a|b')
//=> {a: '', b: ''}

expand('a|b', {toBoolean: true})
//=> {a: true, b: true}

expand('a:b')
//=> {a: 'b'}

expand('a,b')
//=> ['a', 'b']
```

### Type casting

Introduced in v0.2.2, some values are cast to their JavaScript type.

**Booleans**

If the value is `"true"` or `"false"` it will be coerced to a boolean value.

```js
expand('a:true')
//=> {a: true}
expand('a:false')
//=> {a: false}
```

**Numbers**

If the value is an integer it will be coerced to a number.

```js
expand('a:1')
//=> {a: 1}
expand('a:123')
//=> {a: 123}
```

**Regex**

If the value is a simple regular expression it will be coerced to a `new RegExp()`.

```js
expand('a:/foo/')
//=> {a: /foo/}
expand('a.b.c:/^bar/gmi')
//=> {a: {b: {c: /^bar/gmi}}}
```

## Install

Install with [npm](https://www.npmjs.com/)

```sh
$ npm i expand-object --save
```

## CLI

Usage with cli:

```sh
❯ expand-object --help

  Usage: expand-object [options] <string>

  Expand a string into a JavaScript object using a simple notation.

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -r, --raw      Output as raw javascript object - not stringified

  Examples:

    $ expand-object "a:b"
    $ expand-object --raw "a:b"
    $ echo "a:b" | expand-object
```

## node.js

To use as a node.js library:

```js
var expand = require('expand-object');
```

### children

> Expand dots into **child objects**:

```js
expand('a')
//=> {a: ''}
expand('a.b')
//=> {a: {b: ''}}
expand('a.b.c')
//=> {a: {b: {c: ''}}}
expand('a.b.c.d')
//=> {a: {b: {c: {d: ''}}}}
```

### siblings

expand-object supports two kinds of siblings, **general** and **adjacent**. It's much easier to understand the difference in the last example.

#### general siblings

> Use pipes (`|`) to expand **general siblings**:

```js
expand('a|b')
//=> {a: '', b: ''}
expand('a|b|c')
//=> {a: '', b: '', c: ''}
expand('a|b|c|d')
//=> {a: '', b: '', c: '', d: ''}
expand('a:b|c:d')
//=> {a: 'b', c: 'd'}
```

#### adjacent siblings

> Use plus (`+`) to expand **adjacent siblings**:

Adjacent siblings are objects that immediately follow one another.

```js
expand('a:b+c:d')
//=> {a: 'b', c: 'd'}
expand('a.b:c+d:e')
//=> {a: {b: 'c', d: 'e'}}
```

#### difference between sibling types

In the example below:

* **general**: `d` is a sibling to `a`
* **adjacent**: `d` is a sibling to `b`

```js
// general siblings
expand('a.b:c|d:e')
//=> { a: { b: 'c' }, d: 'e' }

// adjacent siblings
expand('a.b:c+d:e')
//=> { a: { b: 'c', d: 'e' } }
```

### key-value pairs

> Expand colons into **key-value pairs**:

```js
expand('a:b')
//=> {a: 'b'}
expand('a.b:c')
//=> {a: {b: 'c'}}
expand('a.b.c:d')
//=> {a: {b: {c: 'd'}}}
```

### arrays

> Expand comma separated values into **arrays**:

```js
expand('a,b')
//=> ['a', 'b']
expand('a,b,c')
//=> ['a', 'b', 'c']
expand('a:b,c,d|e:f,g,h')
//=> {a: ['b', 'c', 'd'], e: ['f', 'g', 'h']}
```

## Usage examples

Expand siblings with comma separated values into arrays:

```js
expand('a:b,c,d|e:f,g,h')
//=> {a: ['b', 'c', 'd'], e: ['f', 'g', 'h']}
```

Expand children with comma separated values into arrays:

```js
expand('a.b.c:d,e,f|g.h:i,j,k')
//=> {a: { b: {c: ['d', 'e', 'f']}}, g: {h: ['i', 'j', 'k']}}
```

Expand sibling objects into key-value pairs:

```js
expand('a:b|c:d')
//=> {a: 'b', c: 'd'}
expand('a:b|c:d|e:f')
//=> {a: 'b', c: 'd', e: 'f'}
expand('a:b|c:d|e:f|g:h')
//=> {a: 'b', c: 'd', e: 'f', g: 'h'}
```

Expand child objects into key-value pairs:

```js
expand('a.b:c')
//=> {a: {b: 'c'}}
expand('a.b.c:d')
//=> {a: {b: {c: 'd'}}}
expand('a.b.c.d:e')
//=> {a: {b: {c: {d: 'e'}}}}
```

Expand sibling and child objects into key-value pairs:

```js
expand('a:b|c:d')
//=> {a: 'b', c: 'd'}
expand('a.b.c|d.e:f')
//=> {a: {b: {c: ''}}, d: {e: 'f'}}
expand('a.b:c|d.e:f')
//=> {a: {b: 'c'}, d: {e: 'f'}}
expand('a.b.c:d|e.f.g:h')
//=> {a: {b: {c: 'd'}}, e: {f: {g: 'h'}}}
```

## Related projects

[expand-args](https://www.npmjs.com/package/expand-args): Expand parsed command line arguments using expand-object. | [homepage](https://github.com/jonschlinkert/expand-args)

## Running tests

Install dev dependencies:

```sh
$ npm i -d && npm test
```

## Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/jonschlinkert/expand-object/issues/new).

## Author

**Jon Schlinkert**

* [github/jonschlinkert](https://github.com/jonschlinkert)
* [twitter/jonschlinkert](http://twitter.com/jonschlinkert)

## License

Copyright © 2015 [Jon Schlinkert](https://github.com/jonschlinkert)
Released under the MIT license.

***

_This file was generated by [verb](https://github.com/verbose/verb) on December 23, 2015._

---
_Source: https://npm.io/package/expand-object · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._