saunter v0.11.0

Saunter

Walk through data. Do things as you go.

Install

npm install saunter

Usage

Saunter is meant to be used with libraries like Ramda, Transducers.js, or Lodash.

walk

The walk function takes an object or array and walks through it. Calling walk will return a generator. The generator yields a walkObject for every value it finds with the following properties.

The walkObject signature:

• path (array) - The path to the value. It will be an array of object properties and array indexes.
• value (any) - The value for the given path.

Note: this will find every value, even objects, and then it will return the values of those objects. The same is true for arrays. To remove these, filter out objects and array.

If walk gets a string, number, or boolean, it will yield a single object.

Arguments

walk: (any) -> array[walkObject]

walkObject: {path, value}
path: array[string | number]
value: any

The walk function takes any kind of value and returns an array of the walkObject.

Example

const { walk } = require("saunter");
const subject = {
  name: "Jane Doe",
  email: "jdoe@example.com",
  address: {
    city: "New York",
    state: "New York",
    zip: "10101",
  },
};
const walker = walk(subject);
console.log([...walker]);

This prints:

[
  { path: ["name"], value: "Jane Doe" },
  { path: ["email"], value: "jdoe@example.com" },
  { path: ["address", "city"], value: "New York" },
  { path: ["address", "state"], value: "New York" },
  { path: ["address", "zip"], value: "10101" }
]

updateWalk

This walks through an object or an array, looks for a match, calls a handler, and replaces the value with the returned value. The purpose for this function is so you can walk through data and make updates as you go.

Arguments

See walk function for walkObject definition.

updateWalk: (subject, array[matcher]) -> any

subject: any
matcher: {match, handle}
match: (walkObject, subject) -> boolean
handle: (walkObject, subject) -> any
remove: (walkObject, subject) -> boolean

The subject is passed into the match and handle functions to allow you to get other information, such as parents or children. If a remove function is given, it will remove the values if the function returns true.

Example

This example walks over an object, looks for even numbers, and when found, multiples them by 10.

const { updateWalk } = require("saunter");
const subject = {
  a: 1,
  b: 2,
  c: 3,
  d: 4,
};
const result = updateWalk(subject, [
  {
    match: ({ value }) => value % 2 === 0,
    handle: ({ value }) => value * 10,
  },
]);
console.log(result);

This prints:

{
  a: 1,
  b: 20,
  c: 3,
  d: 40
}

pathMatch

Function for matching paths. This can be used for filtering or searching through data.

Arguments

The pathMatch function will return a function that takes a walkObject.

pathMatch: (array[string | integer | check]) -> (walkObject) -> boolean

check: (string | integer) -> boolean

The function can take an array of three types of values. A check function can be provided as a way to do logic during a check.

Examples

Matching strings and integers:

const { pathMatch } = require("saunter");
const matcher = pathMatch(["foo", 1, "bar"]);
console.log(matcher(["foo", 1, "bar"]));
// prints true

Matching with functions:

const { pathMatch } = require("saunter");
function isOdd(value) {
  return value % 2 !== 0;
}
const matcher = pathMatch(["foo", isOdd]);
console.log(matcher(["foo", 1]));
// prints true

pathStartsWith

Similar to pathMatch, but only checks to see if the given path starts with the pattern given.

Arguments

Same as pathMatch.

Example

const { pathStartsWith } = require("saunter");
const matcher = pathStartsWith(["foo"]);
console.log(matcher(["foo", 1, "bar"]));
// prints true

getPath

Helper function to get the path from the walkObject.

Arguments

See walk function for walkObject definition.

getPath: (walkObject) -> path

Example

const { getPath } = require("saunter");
getPath({ path: ["foo", 1], value: 42 });
// returns ["foo", 1]

getValue

Helper function to get the value from the walkObject.

Arguments

getValue: (walkObject) -> any

Example

const { getValue } = require("saunter");
getValue({ path: ["foo", 1], value: 42 });
// returns 42