npm package: @gko/transform
Description: transform any object asyncronously as well as in workers
Author: Konstantin Gorodinskii
Latest version: 0.0.3

# Transform [![Build Status](https://travis-ci.com/gko/transform.svg?token=nYxioWfzD4WFnAcmcDxe&branch=master)](https://travis-ci.com/gko/transform)

## Installation

`npm i @gko/transform`

## Usage

### Basic use case

Given that you have following json input:

<details><summary>very long JSON input</summary>
<p>

```json
[
	{
		"sha": "e74eab828e658de3eca089f82b84fb67ed4c3a75",
		"node_id": "MDY6Q29tbWl0NTEwMTE0MTplNzRlYWI4MjhlNjU4ZGUzZWNhMDg5ZjgyYjg0ZmI2N2VkNGMzYTc1",
		"commit": {
			"author": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-11-21T22:53:12Z"
			},
			"committer": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-11-21T22:53:12Z"
			},
			"message": "Fix nesting try/catch inside internal errors",
			"tree": {
				"sha": "843f4e7a3467cde286af373d5c4ec2d74fbfcaa7",
				"url": "https://api.github.com/repos/stedolan/jq/git/trees…41 more…"
			},
			"url": "https://api.github.com/repos/stedolan/jq/git/commits/e74eab828e658de3eca089f82b84fb67ed4c3a75",
			"comment_count": 0,
			"verification": {
				"verified": false,
				"reason": "unsigned",
				"signature": null,
				"payload": null
			}
		},
		"url": "https://api.github.com/repos/stedolan/jq/commits/e74eab828e658de3eca089f82b84fb67ed4c3a75",
		"html_url": "https://github.com/stedolan/jq/commit/e74eab828e658de3eca089f82b84fb67ed4c3a75",
		"comments_url": "https://api.github.com/repos/stedolan/jq/commits/e74eab828e658de3eca089f82b84fb67ed4c3a75/comments",
		"author": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"committer": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"parents": [
			{
				"sha": "bda75c3142d969e2a52301a1eaead0cc05ec2c13",
				"url": "https://api.github.com/repos/stedolan/jq/commits/b…39 more…",
				"html_url": "https://github.com/stedolan/jq/commit/bda75c3142d9…28 more…"
			}
		]
	},
	{
		"sha": "bda75c3142d969e2a52301a1eaead0cc05ec2c13",
		"node_id": "MDY6Q29tbWl0NTEwMTE0MTpiZGE3NWMzMTQyZDk2OWUyYTUyMzAxYTFlYWVhZDBjYzA1ZWMyYzEz",
		"commit": {
			"author": {
				"name": "William Langford",
				"email": "wlangford@digitalocean.com",
				"date": "2019-10-22T17:14:33Z"
			},
			"committer": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-10-24T01:31:05Z"
			},
			"message": "Ensure travis has a python version we expect",
			"tree": {
				"sha": "757fa76c9eda123e4b9d6b4de3e9685a472ba845",
				"url": "https://api.github.com/repos/stedolan/jq/git/trees…41 more…"
			},
			"url": "https://api.github.com/repos/stedolan/jq/git/commits/bda75c3142d969e2a52301a1eaead0cc05ec2c13",
			"comment_count": 0,
			"verification": {
				"verified": false,
				"reason": "unsigned",
				"signature": null,
				"payload": null
			}
		},
		"url": "https://api.github.com/repos/stedolan/jq/commits/bda75c3142d969e2a52301a1eaead0cc05ec2c13",
		"html_url": "https://github.com/stedolan/jq/commit/bda75c3142d969e2a52301a1eaead0cc05ec2c13",
		"comments_url": "https://api.github.com/repos/stedolan/jq/commits/bda75c3142d969e2a52301a1eaead0cc05ec2c13/comments",
		"author": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"committer": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"parents": [
			{
				"sha": "9b51a0852a0f91fbc987f5f2b302ff65e22f6399",
				"url": "https://api.github.com/repos/stedolan/jq/commits/9…39 more…",
				"html_url": "https://github.com/stedolan/jq/commit/9b51a0852a0f…28 more…"
			}
		]
	},
	{
		"sha": "9b51a0852a0f91fbc987f5f2b302ff65e22f6399",
		"node_id": "MDY6Q29tbWl0NTEwMTE0MTo5YjUxYTA4NTJhMGY5MWZiYzk4N2Y1ZjJiMzAyZmY2NWUyMmY2Mzk5",
		"commit": {
			"author": {
				"name": "Leonid S. Usov",
				"email": "leonid@practi.net",
				"date": "2019-04-04T17:47:35Z"
			},
			"committer": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-10-22T18:11:04Z"
			},
			"message": "Remove an accidentally committed debug file",
			"tree": {
				"sha": "bfb42d10b16ee12d45e23e824d0e01afa7ce437e",
				"url": "https://api.github.com/repos/stedolan/jq/git/trees…41 more…"
			},
			"url": "https://api.github.com/repos/stedolan/jq/git/commits/9b51a0852a0f91fbc987f5f2b302ff65e22f6399",
			"comment_count": 0,
			"verification": {
				"verified": false,
				"reason": "unsigned",
				"signature": null,
				"payload": null
			}
		},
		"url": "https://api.github.com/repos/stedolan/jq/commits/9b51a0852a0f91fbc987f5f2b302ff65e22f6399",
		"html_url": "https://github.com/stedolan/jq/commit/9b51a0852a0f91fbc987f5f2b302ff65e22f6399",
		"comments_url": "https://api.github.com/repos/stedolan/jq/commits/9b51a0852a0f91fbc987f5f2b302ff65e22f6399/comments",
		"author": null,
		"committer": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"parents": [
			{
				"sha": "74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17",
				"url": "https://api.github.com/repos/stedolan/jq/commits/7…39 more…",
				"html_url": "https://github.com/stedolan/jq/commit/74c44bc9a35f…28 more…"
			}
		]
	},
	{
		"sha": "74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17",
		"node_id": "MDY6Q29tbWl0NTEwMTE0MTo3NGM0NGJjOWEzNWZmN2RhNDQ4MWI2ZThjNTAzNmMwZmZhOTNhYTE3",
		"commit": {
			"author": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-04-04T01:55:39Z"
			},
			"committer": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-10-22T18:11:04Z"
			},
			"message": "Add configure guards around literal jv_numbers\n\nAllow building jq in a mode that doesn't use decnumber for benchmarking\npurposes. decnumber support is…98 more…",
			"tree": {
				"sha": "46223409def975188a4b1b35d2b3bd78306e47ee",
				"url": "https://api.github.com/repos/stedolan/jq/git/trees…41 more…"
			},
			"url": "https://api.github.com/repos/stedolan/jq/git/commits/74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17",
			"comment_count": 0,
			"verification": {
				"verified": false,
				"reason": "unsigned",
				"signature": null,
				"payload": null
			}
		},
		"url": "https://api.github.com/repos/stedolan/jq/commits/74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17",
		"html_url": "https://github.com/stedolan/jq/commit/74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17",
		"comments_url": "https://api.github.com/repos/stedolan/jq/commits/74c44bc9a35ff7da4481b6e8c5036c0ffa93aa17/comments",
		"author": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"committer": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"parents": [
			{
				"sha": "4860ed439605ded0964fad0ae7b43d0ae8600174",
				"url": "https://api.github.com/repos/stedolan/jq/commits/4…39 more…",
				"html_url": "https://github.com/stedolan/jq/commit/4860ed439605…28 more…"
			}
		]
	},
	{
		"sha": "4860ed439605ded0964fad0ae7b43d0ae8600174",
		"node_id": "MDY6Q29tbWl0NTEwMTE0MTo0ODYwZWQ0Mzk2MDVkZWQwOTY0ZmFkMGFlN2I0M2QwYWU4NjAwMTc0",
		"commit": {
			"author": {
				"name": "Leonid S. Usov",
				"email": "leonid@practi.net",
				"date": "2018-10-30T12:51:49Z"
			},
			"committer": {
				"name": "William Langford",
				"email": "wlangfor@gmail.com",
				"date": "2019-10-22T18:11:04Z"
			},
			"message": "[tests] print test # from the start of the tests file to help with skip and take",
			"tree": {
				"sha": "834ec89571e946a69cec1046a8f0604ed3d11567",
				"url": "https://api.github.com/repos/stedolan/jq/git/trees…41 more…"
			},
			"url": "https://api.github.com/repos/stedolan/jq/git/commits/4860ed439605ded0964fad0ae7b43d0ae8600174",
			"comment_count": 0,
			"verification": {
				"verified": false,
				"reason": "unsigned",
				"signature": null,
				"payload": null
			}
		},
		"url": "https://api.github.com/repos/stedolan/jq/commits/4860ed439605ded0964fad0ae7b43d0ae8600174",
		"html_url": "https://github.com/stedolan/jq/commit/4860ed439605ded0964fad0ae7b43d0ae8600174",
		"comments_url": "https://api.github.com/repos/stedolan/jq/commits/4860ed439605ded0964fad0ae7b43d0ae8600174/comments",
		"author": null,
		"committer": {
			"login": "wtlangford",
			"id": 3422295,
			"node_id": "MDQ6VXNlcjM0MjIyOTU=",
			"avatar_url": "https://avatars2.githubusercontent.com/u/3422295?v=4",
			"gravatar_id": "",
			"url": "https://api.github.com/users/wtlangford",
			"html_url": "https://github.com/wtlangford",
			"followers_url": "https://api.github.com/users/wtlangford/followers",
			"following_url": "https://api.github.com/users/wtlangford/following{/other_user}",
			"gists_url": "https://api.github.com/users/wtlangford/gists{/gist_id}",
			"starred_url": "https://api.github.com/users/wtlangford/starred{/owner}{/repo}",
			"subscriptions_url": "https://api.github.com/users/wtlangford/subscriptions",
			"organizations_url": "https://api.github.com/users/wtlangford/orgs",
			"repos_url": "https://api.github.com/users/wtlangford/repos",
			"events_url": "https://api.github.com/users/wtlangford/events{/privacy}",
			"received_events_url": "https://api.github.com/users/wtlangford/received_events",
			"type": "User",
			"site_admin": false
		},
		"parents": [
			{
				"sha": "cf4b48c7ba30cb30e116b523cff036ea481459f6",
				"url": "https://api.github.com/repos/stedolan/jq/commits/c…39 more…",
				"html_url": "https://github.com/stedolan/jq/commit/cf4b48c7ba30…28 more…"
			}
		]
	}
]
```

</p>
</details>

you can call the following code:

```javascript
import transformData from "@gko/transform";

const transform = {
    commitMessage: ([
        {
            commit: { message }
        }
    ]) => message,
    committerName: "$[0].commit.committer.name"
};

transformData(input, transform).then(console.log);
```

this will output:

```json
{
    "commitMessage": "Fix nesting try/catch inside internal errors",
    "commiterName": ["William Langford"]
}
```

So here the `commitMessage` is a function that accepts input as an argument.
And `committerName` is a `json-path`. See more info on `json-path` [here](https://github.com/dchester/jsonpath#readme).

## Chaining transformations

With the same `json` in mind you can also do following:

```javascript
import transformData from "@gko/transform";

const transform = {
    committerName: [
        "$[0].commit",
        ({ committer }) => committer.name
    ]
};

transformData(input, transform).then(console.log);
```

it will output:

```json
{
    "committerName": "William Langford"
}
```

so besides functions(`async` as well) and json path, you can actually chain
transformations. Each node within a chain will wait for the previous to finish
and will recieve its result.

for instance here we want to switch between two inputs:
```javascript
import transformData from "@gko/transform";

const transform = {
    message: [
        ([first, second]) => (first && first.length ? first : second),
        ([{ commit }]) => commit.message
    ]
};

transformData([null, input], transform).then(console.log);
```

will output:
```json
{
    "message": "Fix nesting try/catch inside internal errors"
}
```

## Async transformations

As mentioned before, any transformations can be asyncronous.

### Promise.race example

```javascript
const transform = {
    message: [async promises => {
        const first = await Promise.race(promises);

        return first;
    },
    ({
        commit: { message }
    }) => message]
};

transformData(
    [fetch1, fetch2],
    transform
).then(console.log);
```

will pass the first fetch that arrives to the second transform step and then it
will be destructured.

### Doing transformations within a Worker

You can do transformations within a `Worker` by using the [workerize](https://github.com/developit/workerize) or [comlink](https://github.com/GoogleChromeLabs/comlink) packages.