nn-traverse v1.0.0

nn-traverse

Traverse an object or array.

Setup

To implement, import the traverse function.

import { traverse } from 'nn-traverse';

The traverse function

Walks through an container (i.e. object/array) and each nested container. The function readContainer will be called for each container encountered and the function readValue will be called for each value encountered.

• data: any - Content to traverse.
• configuration: object maxLevel: integer (optional) - Indicates how deep to traverse. Default is Infinity. pathDelimiter: string (optional) - Indicates the path delimiter. Default is ".". pathJoiner: function (optional) - A custom path joiner. Default is Array.join. readContainer: function (optional) - The container reader. * readValue: function (optional) - The value reader.

Note: Omitting both readContainer and readValue is not permitted.

The readContainer function

This function is called for each encounter of a container. The function will receive the container object and the traverse agent object. Return agent.skip to skip traversing the referenced container.

The readValue function

This function is called for each encounter of a value. The function will receive the value and the traverse agent object. Returning a value will let traverse know what to do next.

TraverseAgent Actions

Returning an action from readContainer or readValue will indicate to traverse what to do next. For example: returning agent.stop from readValue will cause traverse to stop traversing.

The TraverseAgent object

The traverse agent object will be passed to readContainer and readValue functions and has the properties:

Properties

• base {object|any[]|undefined} - A reference to the base container or undefined if no base container. The base container is the container that is passed to traverse.
• container {object|any[]|undefined} - A reference to the parent container or undefined if no parent container.
• key {string} - The name of the referenced property.
• level {number} - The current depth.
• path {{string}} - The referenced path.
• movement {{number}} - The amount of movement that will occur when readValue function is complete. See TraverseAgent Actions for more information.

Actions

• insertAfter( value: any ) - Insert value before referenced value. Ignored when referenced container is an object.
• insertBefore( value: any ) - Insert value before referenced value. Ignored when referenced container is an object.
• remove() - Removes the referenced value.
• replaceWith( value: any ) - Replaces the referenced value.
• skip() - Skip traversing the referenced container. Ignored when returned from readValue.
• stop() - Stop traversing object/array.

Usage

const data =
{
	"A": 1,
	"B":
	{
		"X": 2,
		"Y": 3,
		"Z": [ 4, 5, 6 ]
	},
	"C": [ 7, 8 9 ]
};

traverse( data,
{
	maxLevel: 2,
	readContainer ( container, agent )
	{
		// Do somethings.
		// return agent.skip; // Skip traversing the container.
		// return agent.stop; // Stop traversing.
	},
	readValue ( value, agent )
	{
		// Do somethings.
		// return agent.insertBefore( 'some value' ); // Insert a value before current value.
		// return agent.insertAfter( 'some value' ); // Insert a value after current value.
		// return agent.remove; // Remove value.
		// return agent.replaceWith( 'some value' ); // Replace value.
	}
} );

Custom path

const data =
{
	"A": 1,
	"B":
	{
		"a": 2,
		"b":
		{
			"alpha": 3,
			"beta": 4
		},
		"c": 5
	},
	"C": 6
};

traverse( data,
{
	maxLevel: 2,
	pathJoiner ( path, delimiter ) {},
	pathDelimiter: '/',
	readContainer ( container, agent )
	{
		// Do somethings.
	},
	readValue ( value, agent )
	{
		// Do somethings.
	}
} );