# atpath

Access and copy-on-modify JavaScript objects, including maps, using deep paths.

### `atPath(key, ...)(key, ...)...`

Returns set of accessing / modifying functions for specified
path of keys.

Specify keys by passing a list of keys to `atPath`.
Key can be either:
 - number
 - `keyInMap(obj)`
 - array of Keys
 - anything else, which is `toString()`ed and dot-split.

### `atPath(key, ...)(key, ...)... .get`

An accessor function allowing
to get specified key from any object.

```js
const name = atPath("name").get;
  
name({name: "Tom"});
// => "Tom"
  
const city = atPath("address.city").get;
const city2 = atPath("address", "city").get;
// and other forms, like:
// const city3 = atPath(["address", "city"]).get;
// const city4 = atPath("address")([[], "city"]).get;
// const city5 = atPath()([[], "address.city"])().get;
// etc.
const object = {address: {city: "New York"}};
  
city(object);
// => "New York"
city2(object);
// => "New York"
  
city(undefined);
// => undefined
city(null);
// => undefined
city({});
// => undefined
city({address: null});
// => undefined
city({address: {}});
// => undefined
city({address: {city: null}});
// => null
```

If you put a number in a list of keys to use,
an object will be treated as an array.

If you put a `keyInMap(obj)` in a list of keys to use,
an object will be treated as a `Map`.

That way you can create eg. `const c = atPath("person", 34, "name").get`
to access `obj.person[34].name` with `c(obj)`.

### `atPath(key, ...)(key, ...)... .put(val)`

A modifier function allowing
to "set" specified key to any object
in an immutable fashion, eg. creating a modified copy
when actual write happens.

If properties that are to be parents of a sub-value
are not present, they are created.

In case no change actually happens (same value is set which is
already present), returns the original object.

```js
const setName = atPath("name").put;
  
setName("Jerry")({name: "Tom"});
// => {name: "Jerry"}
  
const setCity = atPath("address.city").put;
const setCity2 = atPath("address", "city").put;
// and other forms, like:
// const setCity3 = atPath(["address", "city"]).put;
// const setCity4 = atPath("address")([[], "city"]).put;
// const setCity5 = atPath()([[], "address.city"])().put;
// etc.
const object = {address: {city: "New York"}};
  
setCity("London")(object);
// => {address: {city: "London"}}
setCity2("London")(object);
// => {address: {city: "London"}}
object;
// => {address: {city: "New York"}}
setCity("New York")(object) === object;
// => true
setCity2("New York")(object) === object;
// => true
  
const setCityLondon = setCity("London");
  
setCityLondon(undefined);
// => {address: {city: "London"}}
setCityLondon(null);
// => {address: {city: "London"}}
setCityLondon({});
// => {address: {city: "London"}}
setCityLondon({address: null});
// => {address: {city: "London"}}
setCityLondon({address: {}});
// => {address: {city: "London"}}
setCityLondon({address: {city: null}});
// => {address: {city: "London"}}
```

If you put a number in a list of keys to use,
an object will be treated as an array (unlike the default string case,
where it is treated as an object), so copy wil be created
using `[...obj]`, not using `{...obj}`.

That way you can create eg. `const c = atPath("person", 34, "name").put`
to "set" `obj.person[34].name` with `c(val)(obj)`.

If you put a `keyInMap(key)` in a list of keys to use,
an object will be treated as a `Map` (unlike the default string case,
where it is treated as an object), so copy wil be created
using `new Map(obj)`, not using `{...obj}`.

### `atPath(key, ...)(key, ...)... .map(fn)`

A modifier function allowing
to "map" value at specified key
in an immutable fashion, eg. creating a modified copy
when actual modification happens.

If properties that are to be parents of a sub-value
are not present, they are _not_ created.
In other words, if the key to modify does not exist,
no change happens.

In case no change actually happens (same value is set which is
already present), returns the original object.

```js
const mapName = atPath("name").map;
  
mapName(x => x.toUpperCase())({name: "Tom"});
// => {name: "TOM"}
  
const mapCity = atPath("address.city").map;
const mapCity2 = atPath("address", "city").map;
// and other forms, like:
// const mapCity3 = atPath(["address", "city"]).map;
// const mapCity4 = atPath("address")([[], "city"]).map
// const mapCity5 = atPath()([[], "address.city"])().map
// etc.
const object = {address: {city: "New York"}};
  
mapCity(x => "London")(object);
// => {address: {city: "London"}}
mapCity2(x => "London")(object);
// => {address: {city: "London"}}
object;
// => {address: {city: "New York"}}
mapCity(x => "New York")(object) === object;
// => true
mapCity2(x => "New York")(object) === object;
// => true
  
const mapCityLondon = mapCity(x => "London");
  
mapCityLondon(undefined);
// => undefined
mapCityLondon(null);
// => null
mapCityLondon({});
// => {}
mapCityLondon({address: null});
// => {address: null}
mapCityLondon({address: {}});
// => {address: {}}
mapCityLondon({address: {city: null}});
// => {address: {city: "London"}}
```

If you put a number in a list of keys to use,
an object will be treated as an array (unlike the default string case,
where it is treated as an object), so copy wil be created
using `[...obj]`, not using `{...obj}`.

That way you can create eg. `const c = atPath("person", 34, "name").map`
to "map" `obj.person[34].name` with `c(fn)(obj)`.

If you put a `keyInMap(key)` in a list of keys to use,
an object will be treated as a `Map` (unlike the default string case,
where it is treated as an object), so copy wil be created
using `new Map(obj)`, not using `{...obj}`.

### `keyInMap(obj)`
### `kim(obj)`

Creates "`obj` as an index in a map".

### `pathWorkshop(keys, fn = x => x)(obj, [options])`

This is multipurpose enumerate-and-act function to manipulate objects
using `atPath`. The `options` argument can contain these additional fields:
  - `result` -- where to put elements (`obj` by default),
  - `resultKeys` -- what keys to use to put into `result` (`keys` by default)
  - `diff` -- where to put diffing elements (`undefined` by default)

Function enumerates over keys and performs
"get key from obj, call fn on value, put transformed value into resultKey in result"
operations over them, using `.get` for getting and `.put` for putting.
Additionally, if putting actually resulted in change,
the result key and value is also put into `diff`.
It then returns `{result, diff}` object.

```js
pathWorkshop(["a", "b.c"])();
// does nothing
// => {result: undefined, diff: undefined}
  
pathWorkshop(["a", "b.c"], () => null)();
// sets a and b.c to null
// => {result: {a: null, b: {c: null}}, diff: {a: null, b: {c: null}}}
  
const data = {a: 'foo', b: {c: null}};
pathWorkshop(["a", "b.c"], JSON.stringify)(data);
// changes a and b.c to string representation; change to a is noop
// => {result: {a: 'foo', b: {c: 'null'}}, diff: {b: {c: 'null'}}}
  
const stored = {ay: 'bar', beecee: 'baz', cee: 'quux'};
const data = {a: 'foo', b: {c: null}};
pathWorkshop(["a", "b.c"])(data, {result: stored, resultKeys: ["ay", "beecee"]});
// "copies" a and b.c into `stored` under different keys
// => {result: {ay: 'foo', beecee: null, cee: 'quux'}, diff: {ay: 'foo', beecee: null}}
  
const data = {a: 'foo', b: {c: 'bar'}, c: 'quux'};
pathWorkshop(["a", "b.c"], () => null)(data);
// "nulls" a few fields
// => {result: {a: null, b: {c: null}, c: 'quux'}, diff: {a: null, b: {c: null}}}
```