https://github.com/mcmath/deep-map
Transforms nested values of complex objects
https://github.com/mcmath/deep-map
Last synced: 8 months ago
JSON representation
Transforms nested values of complex objects
- Host: GitHub
- URL: https://github.com/mcmath/deep-map
- Owner: mcmath
- License: mit
- Created: 2016-02-09T21:30:26.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2019-02-01T08:17:45.000Z (over 7 years ago)
- Last Synced: 2025-09-20T22:59:24.273Z (9 months ago)
- Language: TypeScript
- Homepage:
- Size: 61.5 KB
- Stars: 44
- Watchers: 4
- Forks: 6
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Deep Map
[![Version][version-badge]][npm]
[![License][license-badge]][license]
[![Build][build-badge]][travis]
[![Coverage][coverage-badge]][coveralls]
[Install](#install) | [Usage](#usage) | [API](#api) | [TypeScript](#typescript) | [License](#license)
**Deep Map** recurses through an object and transforms its primitive values
– including nested values – according to some function. Essentially,
it's a deep version of [`Array.prototype.map()`][array-prototype-map] that
works on all objects rather than just on Arrays. Circular references are
supported.
To transform the *keys* of an object rather than its values, use
[Deep Map Keys][deep-map-keys].
## Install
Install Deep Map via [npm][npm].
```sh
npm install --save deep-map
```
## Usage
Let's say we have an object like this:
```js
const info = {
name: '<%- name %>',
email: '<%- email %>',
keywords: ['<%- keyword1 %>', '<%- keyword2 %>'],
hobbies: {
primary: '<%- hobby1 %>',
secondary: '<%- hobby2 %>'
}
};
```
And we want to fill it with this data:
```js
const data = {
name: 'Samuel Johnson',
email: 'sam.johnson@dictionary.com',
keyword1: 'dictionary',
keyword2: 'lexicography',
hobby1: 'writing',
hobby2: 'torying',
};
```
We can use Deep Map like this:
```js
const deepMap = require('deep-map');
const template = require('lodash/template');
let result = deepMap(info, value => template(value)(data));
```
And the result looks like this:
```js
{
name: 'Samuel Johnson',
email: 'sam.johnson@dictionary.com',
keywords: ['dictionary', 'lexicography'],
hobbies: {
primary: 'writing',
secondary: 'torying'
}
}
```
## API
#### `deepMap(object, mapFn, [options])`
#### Parameters
Param
Type
Description
object
any
The object whose values are to be transformed. Typically, this will be
a complex object containing other nested objects. This object may be an
Array, and may contain nested arrays whose values will
be deeply transformed in the same way. The object may contain circular
references.
mapFn
function
The function used to transform each primitive value. The function is
called with two arguments:
-
value <any>
The value being transformed.
-
key <string | number>
The key or index of the value being transformed. In the case
of plain objects, this will be a string; in the case of arrays,
this will be a number.
The return value determines the value at the same position on the
resulting object.
[options]
object
An optional options object. The following options are accepted:
-
inPlace <boolean=false>
Mutateobjectrather than constructing a new
object. Nested objects will also be mutated.
-
thisArg <any=undefined>
Sets the value of
this
withinmapFn().
#### Returns
Returns a new object with the same keys as `object`. If `options.inPlace` is set
to `true`, the original object is returned, mutated.
## TypeScript
[TypeScript][typescript] declarations are included in the package. Just import
the module, and things will just work.
By default, the compiler will assume that the return value will have the same
shape as the input object. In most use cases, this is likely to be true. But in
some cases – like the one below – the assumption breaks down.
```ts
function isPositive(n: number): boolean {
return n >= 0;
}
// COMPILER ERROR: number not assignable to boolean :(
let bool: boolean = deepMap({n: 2}, isPositive).n;
```
Pass a type argument to describe the shape of the return value, and everything
will be happy.
```ts
let bool: boolean = deepMap<{n: boolean}>({n: 2}, isPositive).n; // :)
```
## License
Copyright © 2016–2019 Akim McMath. Licensed under the [MIT License][license].
[version-badge]: https://img.shields.io/npm/v/deep-map.svg?style=flat-square
[license-badge]: https://img.shields.io/npm/l/deep-map.svg?style=flat-square
[build-badge]: https://img.shields.io/travis/mcmath/deep-map/master.svg?style=flat-square
[coverage-badge]: https://img.shields.io/coveralls/mcmath/deep-map/master.svg?style=flat-square&service=github
[npm]: https://www.npmjs.com/package/deep-map
[license]: LICENSE
[travis]: https://travis-ci.org/mcmath/deep-map
[coveralls]: https://coveralls.io/github/mcmath/deep-map?branch=master
[deep-map-keys]: https://github.com/mcmath/deep-map-keys
[typescript]: http://www.typescriptlang.org/
[array-prototype-map]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map