atpath/README.md

atpath

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

atPath(key, ...)(key, ...)...

Returns set of accessing / modifying function 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.

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.

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.

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 deget for getting and decow 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.

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}}}