Class: ObjNavigator

ObjNavigator(rootopt, parentopt, stepopt)

Provides semantic helpers for navigating and manipulating nested JSON-compatible objects using dot-notation paths.

ObjNavigator supports:

  • Scoped navigation via within
  • Returning to parent objects via without
  • Declarative exploration of object hierarchies via search

Constructor

new ObjNavigator(rootopt, parentopt, stepopt)

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.
step string | undefined <optional>

Step from parent to this navigator (e.g. 'user.age').

Classes

ObjNavigator

Members

parent :ObjNavigator|undefined

Type:

root :Object

Type:
  • Object

step :string|undefined

Type:
  • string | undefined

Methods

delete(path) → {this}

Deletes a nested property from the object given a path.

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

Path to delete.
Returns:
Type
this

get(path) → {*}

Retrieves a value at a path relative to this navigator (read-only).

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

Path to retrieve.
Returns:

The value at the path, or undefined if not found.

Type
*
Example
const name = nav.get("user.profile.name");

path(byPropertyopt) → {Path}

Returns the path from the top-level ancestor navigator to this navigator.

Parameters:
Name Type Attributes Default Description
byProperty boolean <optional>
 false
  • false (default): returns the logical path, counting navigator steps (one per .within() / .with()).
  • true: returns the full property-based path, expanding each compound step into its constituent properties (e.g., "user.profile.name" → ["user", "profile", "name"]).
Returns:

A Path object representing the accumulated steps or properties.

Type
Path
Example
const ancestor = ObjNavigator.from({});
const nav = ancestor.set('user.profile.name', {}).with('user.profile');

console.log(nav.path().length);      // logical depth: 1
console.log(nav.path(true).length);   // property-based depth: 2
console.log(nav.path(true).last);     // 'profile'

Creates a Search instance that declaratively explores the structure of the object tree starting from this navigator.

Each expansion step maps the current navigator to a list of child navigators — one for each property of the underlying object.

This enables structural traversal across both nested objects and leaf primitives, as every property value is represented as its own ObjNavigator.

By default, the Search is driven by a FIFO queue. However, a custom exploration strategy can be provided by chaining .via(queue).
Subsequent fluent calls such as .which(), .sthen(), and .what() can further restrict, transform, or resolve the search.

Internally, each expansion applies:

nav => Object.entries(nav.root)
    .map(([key, value]) => new ObjNavigator(value, nav, key))
Returns:

A Search instance yielding ObjNavigator objects.

Type
Search.<ObjNavigator>
Example
// Declarative exploration of nested objects
const result = ObjNavigator.from(obj)
  .search()
  .which(nav => nav.get('a.b'))  // only navigators whose root object has an 'a.b' path
  .sthen(map)                    // transforms matching navigators
  .what();                       // resolves the first satisfying object

select(predicate) → {this}

Removes entries from this.root for which the given predicate returns false.

Parameters:
Name Type Description
predicate function
Returns:
Type
this

set(path, value, createMissingopt) → {this}

Sets a value at a path relative to this navigator. Missing intermediate objects are auto-created if createMissing is true.

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

Path to set.
value *

Value to assign.
createMissing boolean <optional>
 true

Auto-create missing objects.
Throws:

If a path segment exists but is not an object.

Type
Error
Returns:
Type
this

with()

Alias for within.

within(path) → {ObjNavigator}

Navigate into a sub-object and return a new ObjNavigator child. Throws if any intermediate object is missing or not an object.

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

Path to the sub-object.
Throws:

If any path segment does not exist or is not an object.

Type
Error
Returns:

Child navigator scoped to the sub-object.

Type
ObjNavigator
Example
const nav = ObjNavigator.from({ user: { profile: {} } });
const profileNav = 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) 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"]