# obstruction

> Declarative parser for remapping object schemas and data

Latest version **2.1.0** (published 2016-08-31) · MIT license · 0 weekly downloads

## Install

```sh
npm install obstruction
pnpm add obstruction
yarn add obstruction
bun add obstruction
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.1.0 |
| Published | 2016-08-31 |
| First published | 2015-06-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 5 |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 14 |
| Author | Ben Drucker |
| Maintainers | bendrucker |
| Keywords | object, parse, schema, map |

## Links

- npm: https://www.npmjs.com/package/obstruction
- Repository: https://github.com/bendrucker/obstruction
- Homepage: https://github.com/bendrucker/obstruction#readme
- Issues: https://github.com/bendrucker/obstruction/issues
- npm.io page: https://npm.io/package/obstruction

## Dependencies (5)

- [ap](https://npm.io/package/ap.md) ~0.2.0
- [isarray](https://npm.io/package/isarray.md) 0.0.1
- [map-obj](https://npm.io/package/map-obj.md) ~1.0.1
- [dot-prop](https://npm.io/package/dot-prop.md) ~2.1.0
- [is-object](https://npm.io/package/is-object.md) ~1.0.1

## Alternatives

- [babylon](https://npm.io/package/babylon.md) — 5.1M weekly downloads
- [csscolorparser](https://npm.io/package/csscolorparser.md) — 3.7M weekly downloads
- [expr-eval-fork](https://npm.io/package/expr-eval-fork.md) — 1.5M weekly downloads
- [@leeoniya/ufuzzy](https://npm.io/package/@leeoniya/ufuzzy.md) — 247.7K weekly downloads
- [xml-parser](https://npm.io/package/xml-parser.md) — 78.4K weekly downloads

## Recent versions

- 2.1.0 (latest) — 2016-08-31
- 2.0.0 — 2015-09-18
- 1.2.0 — 2015-07-21
- 1.1.0 — 2015-06-08
- 1.0.0 — 2015-06-07

## README

# obstruction [![Build Status](https://travis-ci.org/bendrucker/obstruction.svg?branch=master)](https://travis-ci.org/bendrucker/obstruction)

> Declarative parser for remapping object schemas and data

## Install

```
$ npm install --save obstruction
```


## Usage

```js
var Obstruct = require('obstruction')
var parse = Obstruct({
  title: 'name',
  description: true,
  author: 'author.login'
})
parse({
  name: 'obstruction',
  description: 'Object restructuring and parsing',
  author: {
    login: 'bendrucker'
  }
})
```

Returns:

```js
{
  title: 'obstruction',
  description: 'Object restructuring and parsing',
  author: 'bendrucker'
}
```

## API

#### `Obstruct(schema, [object])` -> `function` / `object`

If only a schema is passed, a function with the `schema` partially applied will be returned. You can call that function with your `object`.

##### schema

*Required*  
Type: `object`

A schema object. See the [schema definition options](#schema-definition) for more details.

##### object

Type: `object`  

The object to parse. If omitted, a partially applied function will be returned instead.

#### `Obstruct.array(schema)` -> `function`

A convenience function for easily mapping arrays over a schema.

##### schema

*Required*  
Type: `object` / `function`

The schema used to map array items. This can be a plain object (which will be passed to `Obstruct`) or the result of calling `Obstruct(schema)` earlier. It can also any generic function for mapping values. The following are equivalent:

Without `Obstruct.array`:

```js
var parseState = Obstruct({
  abbrevation: 'abbrev'
})
Obstruct({
  states: function (states) {
    return states.map(function (state) {
      return parseState(state)
    })
  }
})
```

With `Obstruct.array`:

```js
Obstruct({
  states: Obstruct.array({
    abbreviation: 'abbrev'
  })
})
```

#### `Obstruct.optional(schema)` -> `function`

A convenience function for easily mapping arrays over a schema.

##### schema

*Required*  
Type: `object` / `function`

The schema used to parse the value, if defined (not `undefined` or `null`). This can be a plain object (which will be passed to `Obstruct`) or the result of calling `Obstruct(schema)` earlier. It can also any generic function for transforming values.

If the source value is undefined, Obstruct will immediately return `undefined` without calling your `schema`. This allows you to cleanly handle cases where a missing value might throw.

#### `Obstruct.parent(schema)` -> `function`

A convenience function for nested parent data within your output object.

##### schema

*Required*  
Type: `object` / `function`

The schema used to parse the parent object rather than the value at the specified key.

## Schema Definitions

A schema object represents the target object structure after parsing. You can nest schema objects to re-map nested objects. Schema nodes (the values in the schema object) control what value ultimately appears at a particular keypath in the final object.

Schema nodes can be:

#### `true`

The value will be copied directly from the source object:

```js
Obstruct({foo: true})({foo: 'bar'})
// => {foo: 'bar'}
```

#### a string

The value will be copied from the source object using the supplied string as the source key:

```js
Obstruct({foo: 'bar'})({foo: 'bar', bar: 'baz'})
// => {foo: 'baz'}
```

Strings can also use dot syntax to access deep properties:

```js
Obstruct({foo: 'a.bar'})({a: {bar: 'baz'}})
// => {foo: 'baz'}
```

#### a function

The value from the source object will be passed through the supplied function:

```js
function uppercase (string) {
  return string.toUpperCase()
}
Obstruct({foo: uppercase})({foo: 'bar'})
// => {foo: 'BAR'}
```

The function also receives the original object and the source key as additional arguments.

#### an object

`Obstruct` is called with the object and the source value at that keypath.

```js
Obstruct({foo: {bar: uppercase}})({foo: {bar: 'baz'}})
// => {foo: {bar: 'BAZ'}}
```

#### an array

Schema nodes can be an array where:

* the first value is the source key to use (dot syntax is supported)
* the second value is any other valid schema node value (`true`, string, function, object)

```js
Obstruct({a: ['foo', uppercase]})({foo: 'bar'})
// => {a: 'BAR'}
Obstruct({b: ['foo.bar', uppercase]})({foo: {bar: 'baz'}})
// => {b: 'BAZ'}
Obstruct({c: ['foo', {bar: uppercase}]})({foo: {bar: 'baz'}})
// => {c: {bar: 'BAZ'}}
```

## License

MIT © [Ben Drucker](http://bendrucker.me)

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