# transmog

> Simple rule-based object transformer

Latest version **2.2.1** (published 2018-03-21) · MIT license · 0 weekly downloads

## Install

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

## 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.2.1 |
| Published | 2018-03-21 |
| First published | 2016-08-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 12.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | thrucker |
| Maintainers | trucker |

## Links

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

## Dependencies (1)

- [lodash](https://npm.io/package/lodash.md) ^4.17.0

## Recent versions

- 2.2.1 (latest) — 2018-03-21
- 2.2.0 — 2017-10-29
- 2.1.4 — 2017-10-29
- 2.1.3 — 2016-11-15
- 2.1.2 — 2016-09-05
- 2.1.1 — 2016-08-22
- 2.1.0 — 2016-08-21
- 2.0.0 — 2016-08-21
- 1.0.3 — 2016-08-14
- 1.0.2 — 2016-08-14
- 1.0.1 — 2016-08-14
- 1.0.0 — 2016-08-14

## README

# transmog

[![Greenkeeper badge](https://badges.greenkeeper.io/thrucker/transmog.svg)](https://greenkeeper.io/)

[![npm](https://img.shields.io/npm/v/transmog.svg?maxAge=2592000)](https://www.npmjs.org/package/transmog)
[![Build Status](https://travis-ci.org/thrucker/transmog.svg?branch=master)](https://travis-ci.org/thrucker/transmog)
[![codecov](https://codecov.io/gh/thrucker/transmog/branch/master/graph/badge.svg)](https://codecov.io/gh/thrucker/transmog)
[![dependencies Status](https://david-dm.org/thrucker/transmog/status.svg)](https://david-dm.org/thrucker/transmog)
[![devDependencies Status](https://david-dm.org/thrucker/transmog/dev-status.svg)](https://david-dm.org/thrucker/transmog?type=dev)

transmog is a utility for converting JavaScript objects of a certain shape to JavaScript objects of a different shape.
This transformation is based on standardized rules to make it easy to express and comprehend the transformation.

Features:
* reading/writing from/to nested properties
* whitelisting of properties
* conversion of property values
* default values for missing property values

## API

### `transmog()`

```
transmog(
  rules: object,
  object: object
): object
```

Transforms `object` according to `rules`.

`transmog` will apply the `rules` to `object` without mutating it and will always return a newly created object. Note
however that the property values of the resulting object may reference the same objects as the source `object` does.
There's no cloning of objects involved unless you specify individual rules which do so.

#### `rules`

The `rules` object consists of key-value pairs which specify how every property of the resulting object is determined.

```
rules = {
    "path.to.property": <boolean | function | string | object>,
    ...
}
```

The key of a rule specifies the property name or property path in the resulting object. A property path is a `.`
delimited string of valid property names and can be used to create nested objects.

The value of a rule is a description for how to calculate the property value based on the source `object`. Different
common use cases can be expressed based on the type of the rule.

##### boolean rule

`true | false`

If `true` the value of the source `object` under the same path is written to the resulting object. If `false` the rule
is ignored. (This is just for consistency. Instead of specifying `false` the rule can be omitted as well.)

##### function rule

```
function (
    sourceValue: any,
    sourceObject: object
): any
```

The specified function is called with
* the `sourceValue` which is the property value of the source `object` under the same path as the rule describes
* the source `object` itself.

It should return the value which will be written to the resulting object under the path which the rule describes.

##### string rule

`"source.property.path"`

The specified string is interpreted as a property path of the source `object` whose value will be written to the
resulting object.

##### object rule

```
{
    converter?: (sourceValue: any, sourceObject: object) => any,
    sourcePath?: string,
    defaultTo?: (sourceObject: object) => any
}
```

An object rule is the generalization of the `boolean`, `function` and `string` rule.

The `converter` function will be called with the `sourceValue` and `sourceObject` and should return the value which will
be written to the resulting object. If omitted the identity function will be used as a default.

The `sourcePath` specifies the property path under which the `sourceValue` for the `converter` function will be read. If
omitted the destination path of the rule will be used as a default.

The `defaultTo` function will be called if the `sourceValue` is `null`, `undefined` or the source `object` has no
property under the specified `sourcePath`. It will be called with the `sourceObject` as an argument and should return
the default value which will be written to the resulting object. If `defaultTo` is omitted no value will be written to
the resulting object if `sourceValue` is `null`, `undefined` or the source `object` has no property under the specified
`sourcePath`.

## Example

TODO

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