Class: ObjNavigator

ObjNavigator(rootopt, parentopt)

Provides semantic helpers for navigating and manipulating nested JSON-compatible objects.

Constructor

new ObjNavigator(rootopt, parentopt)

Creates a new ObjNavigator instance.

Parameters:
Name Type Attributes Default Description
root Object <optional>
 {}

The underlying JSON object to wrap.
parent ObjNavigator | undefined <optional>

Optional parent navigator.

Classes

ObjNavigator

Members

depth :number

Type:
  • number

failed :boolean

Type:
  • boolean

parent :ObjNavigator|undefined

Type:

root :Object

Type:
  • Object

Methods

bubble(event, …args) → {this}

Emits an event on this navigator and propagates it upward through all ancestor navigators.

The event is emitted with exactly the same arguments (event, ...args) at each level. No arguments are added, removed, or modified while bubbling.

Use this method when an event is semantically relevant beyond the current navigator scope. For local-only events, use EventEmitter#emit directly.

Parameters:
Name Type Attributes Description
event string | symbol

Event name.
args any <repeatable>

Arguments to pass to event listeners; forwarded unchanged.
Returns:

The current navigator instance (chainable).

Type
this
Examples
// Bubble a validation error to the root navigator
nav.bubble('validateError', nav, { message: 'page must be an integer' });
// Local-only emission (no bubbling)
nav.emit('debug', 'checking query params');

coerce(path, value, optsopt) → {ObjNavigator}

Coerces the value at a given static path using a user-defined handler.

The value handler is a function (currentValue, opts) that receives the current value at the path and returns a coerced value. The function is bound to this context.

Error handling is supported via opts (see ObjNavigator.fail).

If coercion fails, the navigator enters a failed state and subsequent operations become no-ops.

Parameters:
Name Type Attributes Default Description
path string | Array.<(string|number)>

Path to the value to coerce.
value function

Coercion handler function (currentValue, opts) => any.
opts Object <optional>
 {}

Optional error-handling options.
Returns:

The current navigator, allowing method chaining.

Type
ObjNavigator
Example
nav.coerce("user.age", Number);

delete(path) → {ObjNavigator}

Deletes a property at a path relative to this navigator.

This operation is idempotent:

  • Missing paths are ignored
  • Non-object intermediates are ignored
  • Deleting a missing key is a no-op
Parameters:
Name Type Description
path string | Array.<(string|number)>

Path of the property to delete.
Returns:

The current navigator, allowing method chaining.

Type
ObjNavigator

fail(erropt, optsopt) → {ObjNavigator}

Centralized failure handler used across ObjNavigator.

Marks the current navigator as failed and applies a consistent error-handling policy.

Failure semantics

  • this.failed is always set to true.

  • The payload to handle can be:

    • Provided directly via opts.payload
    • Executed if payload is a function (receives err and opts as arguments)

  • opts.onError is invoked with the resolved payload (if provided)

  • opts.errorEvent is emitted or bubbled (if provided)

  • If opts.throws is truthy, the payload is thrown after emission/callback

  • Otherwise, the current navigator is returned

This allows centralized, flexible, and dynamic error handling in one place.

This:
Parameters:
Name Type Attributes Description
err Error | any <optional>

Optional source error that caused the failure. Can be undefined.
opts Object <optional>
Properties
Name Type Attributes Default Description
payload any | function <optional>

The payload to emit/callback/throw. Can be:

  • A direct value
  • A function (err, opts) => any By default, it is the identity function err => err.
onError function <optional>

Callback invoked immediately with the resolved payload.
errorEvent string | symbol <optional>

Event name emitted or bubbled with the resolved payload.
bubbles boolean <optional>
 false

Whether the error event should bubble to parent navigators.
throws boolean <optional>
 false

Whether to throw the resolved payload after handling.
Throws:

The resolved payload if opts.throws is truthy.

Type
*
Returns:

The current navigator instance, marked as failed, unless the payload is thrown.

Type
ObjNavigator
Examples
// Throws and marks navigator as failed
nav.fail(new Error("Something went wrong"));
// Emits an event and calls callback, does not throw
nav.fail(undefined, {
  payload: { ctx: nav, err: new Error("fail") },
  onError: console.error,
  errorEvent: "myError"
});
// Uses a function to dynamically create payload
nav.fail(new Error("fail"), {
  payload: (err) => ({ message: 'Dynamic: ' + err.message }),
  onError: console.error
});

get(expr, optsopt) → {*}

Retrieves a value at a path relative to this navigator or computes a function binding it to this navigator and passing this.root as argument.

In the common case, expr is a static string or array (e.g., "a.b.c" or ["a","b","c"]). Strings and arrays are promoted into functions that retrieve the corresponding path from this.root.

Advanced error-handling options are supported via opts.

Parameters:
Name Type Attributes Default Description
expr string | Array.<(string|number)> | function

Path to retrieve or function to compute. May be:

  • A string using dot notation
  • An array of keys
  • A function returning any object/value
opts Object <optional>
 {}

Optional error-handling options (see ObjNavigator.fail).
Returns:

The value at the resolved path, or undefined if the path does not exist.

Type
*
Examples
nav.get("user.profile.name");
nav.get(["user", "profile", "name"]);
nav.get(root => root.querySelector("#profile"));

select(predicate, optsopt) → {ObjNavigator}

Removes entries from the underlying object for which the predicate returns false.

predicate is a function receiving (key, value, index) which is bound to this context.

Optional error-handling behavior is supported via opts.

Parameters:
Name Type Attributes Default Description
predicate function

Function called for each entry: (key, value, index) => boolean. Entries for which the predicate returns false are deleted.
opts Object <optional>
 {}

Optional error-handling options (see ObjNavigator.fail).
Returns:

The current navigator, allowing method chaining.

Type
ObjNavigator
Example
nav.select((key, value) => value.active);

set(path, value, optsopt) → {ObjNavigator}

Sets a value at a path relative to this navigator.

path and value are required to be static constants (e.g., "user.profile.name" or ["user","profile","name"]).

Error-handling behavior is supported via opts.

Parameters:
Name Type Attributes Default Description
path string | Array.<(string|number)>

Path where the value should be set.
value *

Value to assign at the target path.
opts Object <optional>
 {}

Optional behavior and error-handling options.

Properties
Name Type Attributes Default Description
createMissing boolean <optional>
 true

Whether to create missing intermediate objects along the path.
Returns:

The current navigator, allowing method chaining.

Type
ObjNavigator
Examples
nav.set("user.profile.name", "Alice");
nav.set(["user", "profile", "age"], 42);

validate(expr, predicate, optsopt) → {this}

Validates the result of the given expr using a user-defined predicate.

Error handling is supported via opts (see ObjNavigator.fail).

Parameters:
Name Type Attributes Default Description
expr string | Array.<string> | function

Can be:

  • A static string path (e.g., "user.age")
  • An array of keys (e.g., ["user","age"])
  • A function returning the value to validate
predicate function | string

Function returning true if the value is valid, false otherwise.
opts Object <optional>
 {}

Optional behavior and error-handling options.

Properties
Name Type Attributes Default Description
payload any | function <optional>

Payload passed to fail() in case of failure. Can be a direct value or a function (err, opts) => any.
onError function <optional>

Callback invoked with the failure payload if validation fails.
errorEvent string | symbol <optional>

Event emitted or bubbled if validation fails.
bubbles boolean <optional>
 false

Whether the error event should bubble to parent navigators.
throws boolean <optional>
 false

Whether to throw the failure payload.
Throws:

The failure payload if opts.throws is true.

Type
*
Returns:

The current navigator instance, allowing method chaining.

Type
this
Example
nav.validate("user.age", val => val >= 18);

with()

Alias for within.

within(expr, stepopt, optsopt) → {ObjNavigator}

Navigate to an arbitrary next object and return a new ObjNavigator child.

The next object is defined by a function calculating it. The function takes this.root as argument and it is bound to this context.

Strings (e.g., 'user.profile') and string arrays (e.g., ['user', 'profile']) are promoted to a function returning the object addressed by the given path of properties.

This enables navigation across derived objects, filtered views, DOM nodes, or any other computed targets.

Error-handling behavior is delegated to ObjNavigator.fail.

Parameters:
Name Type Attributes Default Description
expr any | function | string | Array.<string>

The next navigation root. May be:

  • A direct object
  • A function returning an object
  • A path of properties described by a string or an array of strings
step string <optional>
 expr

A synthetic key describing this navigation step. Used only for navigation history and without() symmetry.
opts Object <optional>
 {}

Optional error-handling options (see ObjNavigator.fail).
Returns:

A child navigator scoped to the provided object.

Type
ObjNavigator
Examples
nav.within(root => root.querySelector('#profile'));
nav.within("user.profile");

without() → {ObjNavigator|null}

Returns the parent ObjNavigator, or null if none exists.

Returns:
Type
ObjNavigator | null
Example
const parentNav = profileNav.without();

(static) from(obj) → {ObjNavigator}

Create a new ObjNavigator from a plain object.

Parameters:
Name Type Description
obj Object

The object to wrap.
Returns:

A new navigator instance.

Type
ObjNavigator
Example
const nav = ObjNavigator.from({ user: { profile: {} } });

(static) get(root, path) → {*}

Retrieve a nested property from an object by a path.

The path may be:

  • A string using dot notation, e.g., 'user.profile.name'
  • An array of strings, e.g., ['user', 'profile', 'name']
Parameters:
Name Type Description
root Object

The root object to navigate
path string | Array.<string>

The path of keys to traverse
Throws:

If any key along the path is missing

Type
Error
Returns:

The value at the specified path

Type
*

(static) normalizePath(path) → {Array.<string>}

Normalize a path argument into an array of string keys.

Parameters:
Name Type Description
path string | Array.<string>

Dot-separated string or array of keys.
Returns:

Array of keys.

Type
Array.<string>
Example
ObjNavigator.normalizePath("user.profile.name"); // ["user", "profile", "name"]

(static) promote(path) → {function|*}

Centralized logic consistent across the class. Promotes a string or array argument into a function that retrieves a property path from nav.root. Any other argument is returned as-is.

Examples: promote('name') -> root => ObjNavigator.get(root, 'name'); promote(['user', 'id']) -> root => ObjNavigator.get(root, ['user', 'id']) promote(fn) => fn

Parameters:
Name Type Description
path *

The value to promote
Returns:

A function if path is a string or array, otherwise the original value

Type
function | *