@hamak/navigation-utils

Path and data structure navigation utilities for the app-framework ecosystem.

Overview

This package provides utilities for:

• Path manipulation - Normalize, resolve, and navigate filesystem-like paths
• Data structure navigation - Navigate deep object/array structures using itineraries

Features

Pathway - Path Manipulation

The Pathway class provides a robust way to manipulate filesystem-like paths:

import { Pathway } from '@hamak/navigation-utils';

// Create pathways
const path1 = new Pathway('/users/documents');
const path2 = Pathway.of('projects/readme.md');

// Resolve paths
const resolved = path1.resolve(path2); // /users/documents/projects/readme.md

// Get parent
const parent = path1.getParent(); // /users

// Check relationships
path1.isDescendant('/users/documents/projects'); // true

Itinerary - Data Structure Navigation

Navigate complex object/array structures using itinerary steps:

import { itineraryOf, navigate, propertyStep, positionStep } from '@hamak/navigation-utils';

const data = {
  users: [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
};

// Create itinerary: users -> [1] -> name
const itinerary = itineraryOf('users', 1, 'name');

// Navigate
const result = navigate(data, itinerary); // 'Bob'

Installation

npm install @hamak/navigation-utils

API Reference

Pathway

• Pathway.of(path) - Factory method to create a Pathway
• pathway.resolve(otherPath) - Resolve with another path
• pathway.relativize(otherPath) - Get relative path
• pathway.getParent() - Get parent directory
• pathway.isAbsolute() - Check if absolute
• pathway.isDescendant(otherPath) - Check if descendant

Itinerary

• itineraryOf(...segments) - Create itinerary from segments
• navigate(from, itinerary) - Navigate data structure
• propertyStep(name) - Create property step
• positionStep(index) - Create position step
• lookupStep(criteria) - Create lookup step

License

MIT