@hamak/navigation-utils 0.4.0

package/README.md

@@ -0,0 +1,82 @@
+# @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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```bash
+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

package/dist/es2015/filesystem/fs-node-abstract.types.js

@@ -0,0 +1 @@
+export {};

package/dist/es2015/index.js

@@ -0,0 +1,9 @@
+// Path utilities
+export * from './path/pathway';
+export * from './path/pathway-resolver';
+// Itinerary utilities
+export * from './itinerary/itinerary';
+export * from './itinerary/stack';
+export * from './itinerary/hyper-layer-node';
+// Filesystem abstractions
+export * from './filesystem/fs-node-abstract.types';

package/dist/es2015/itinerary/hyper-layer-node.js

@@ -0,0 +1,21 @@
+export function hyper(data, children) {
+    return { data, children };
+}
+/**
+ * Utility function that create Overlay which mirror original object
+ * @param o
+ */
+export function hyperReflect(o) {
+    if (o === null || o === undefined) {
+        return hyper(o);
+    }
+    else if (Array.isArray(o)) {
+        return hyper(o, o.map(e => hyperReflect(e)));
+    }
+    else if (typeof o === "object") {
+        return hyper(o, Object.entries(o).reduce((acc, [k, v]) => (Object.assign(Object.assign({}, acc), { [k]: hyperReflect(v) })), {}));
+    }
+    else {
+        return hyper(o);
+    }
+}

package/dist/es2015/itinerary/itinerary.js

@@ -0,0 +1,276 @@
+import stack from "./stack";
+export function constructiveItinerary(steps) {
+    const segments = [];
+    const prototypes = [];
+    for (let i = 0; i < steps.length; i += 2) {
+        const segment = steps[i];
+        const prototype = steps[i + 1];
+        switch (typeof segment) {
+            case "string":
+            case "number":
+                {
+                    const step = typeof segment === "number" ? positionStep(segment) : propertyStep(segment);
+                    switch (typeof prototype) {
+                        case "object":
+                            { // including Array
+                                segments.push(segment);
+                                prototypes.push(prototype);
+                            }
+                            break;
+                        default: {
+                            throw new Error(`Expecting array or object but got : '${typeof prototype}'`);
+                        }
+                    }
+                }
+                break;
+            default: {
+                throw new Error(`Expecting string or number but gor : '${typeof segment}'`);
+            }
+        }
+    }
+    return {
+        itinerary: itineraryOf(...segments),
+        prototypes: stack.fromArray(prototypes)
+    };
+}
+export function areSameItineraryStep(step1, step2) {
+    var _a, _b, _c;
+    if (step1 == undefined || step2 == undefined) {
+        return false;
+    }
+    else if (step1.type !== step2.type) {
+        return false;
+    }
+    else {
+        switch (step1.type) {
+            case "property": return step2.type === "property" && step1.propertyName === step2.propertyName;
+            case "position": return step2.type === "position" && step1.position === step2.position;
+            case "lookup": {
+                return step2.type === "lookup"
+                    && ((_a = step1.keys) === null || _a === void 0 ? void 0 : _a.length) === ((_b = step2.keys) === null || _b === void 0 ? void 0 : _b.length)
+                    && ((_c = step1.keys) === null || _c === void 0 ? void 0 : _c.every(pv1 => step2.keys.some(pv2 => areSamePropertyValuePair(pv1, pv2))));
+            }
+        }
+    }
+}
+function areSamePropertyValuePair(p1, p2) {
+    return p1.propertyName === p2.propertyName
+        && p1.propertyValue === p2.propertyValue;
+}
+export function itineraryOf(...args) {
+    return args.reduce((parent, e) => {
+        const value = typeof e === 'string' ? propertyStep(e) : positionStep(e);
+        return { parent, value };
+    }, undefined);
+}
+const dataStep = propertyStep("data");
+const childrenStep = propertyStep("children");
+export function itineraryOverlay(it) {
+    return { value: dataStep, parent: itineraryOverlayInner(it) };
+}
+function itineraryOverlayInner(it) {
+    if (it === undefined) {
+        return undefined;
+    }
+    else {
+        const { value, parent } = it;
+        return { value, parent: { value: childrenStep, parent: itineraryOverlayInner(parent) } };
+    }
+}
+export function itineraryToStepArray(itinerary) {
+    let itn = itinerary;
+    const result = [];
+    while (itn !== undefined) {
+        result.push(itn.value);
+        itn = itn.parent;
+    }
+    return result.reverse();
+}
+export function propertyStep(propertyName) {
+    return { type: "property", propertyName };
+}
+export function positionStep(position) {
+    return { type: "position", position };
+}
+export function lookupStep(criteria) {
+    return { type: "lookup", keys: Object.entries(criteria).map(([k, v]) => ({ propertyName: k, propertyValue: v })) };
+}
+export function xpathFromStack(path) {
+    if (path === undefined) {
+        return ''; // TODO may need to return '.' here, to be checked
+    }
+    else {
+        const { value, parent } = path;
+        const parentXPath = xpathFromStack(parent);
+        switch (value.type) {
+            case 'property': {
+                return `${parentXPath}/${value.propertyName}`;
+            }
+            case 'position': {
+                return `${parentXPath}/*[${value.position + 1}]`;
+            }
+            case 'lookup': {
+                const predicate = value.keys.map(({ propertyName, propertyValue }) => `${propertyName}=$${propertyName}`).join(' and ');
+                return `${parentXPath}/*[${predicate}]`;
+            }
+        }
+    }
+}
+export function navigate(from, itinerary, prototype) {
+    if (from === undefined) {
+        return undefined;
+    }
+    if (itinerary === undefined) {
+        return from;
+    }
+    const { parent, value: step } = itinerary;
+    const current = navigate(from, parent, prototype === null || prototype === void 0 ? void 0 : prototype.parent);
+    return navigateStep(current, step, prototype === null || prototype === void 0 ? void 0 : prototype.value);
+}
+export function navigateStep(from, step, prototype) {
+    if (from === undefined) {
+        return undefined;
+    }
+    if (step === undefined) {
+        return from;
+    }
+    if (Array.isArray(from)) {
+        if (step.type === 'lookup') {
+            const stp = step;
+            const result = from.find(e => e !== undefined && stp.keys.every(({ propertyName, propertyValue }) => e[propertyName] === propertyValue));
+            if (result === undefined && prototype !== undefined) {
+                from.push(prototype);
+                return prototype;
+            }
+            else {
+                return result;
+            }
+        }
+        else if (step.type === 'position') {
+            const result = from[step.position];
+            if (result === undefined && prototype !== undefined) {
+                from[step.position] = prototype;
+                return prototype;
+            }
+            else {
+                return result;
+            }
+        }
+    }
+    else if (typeof from === 'object') {
+        if (step.type === 'property') {
+            const result = from === null ? undefined : from[step.propertyName];
+            if (result === undefined && prototype !== undefined && from !== null && from !== undefined) {
+                from[step.propertyName] = prototype;
+                return prototype;
+            }
+            else {
+                return result;
+            }
+        }
+    }
+    return undefined;
+}
+export function navigationDepth(from, itinerary, originalPath = xpathFromStack(itinerary)) {
+    if (from === undefined || from === null) {
+        return { value: undefined, path: '', originalPath };
+    }
+    if (itinerary === undefined) {
+        return { value: from, path: '', originalPath };
+    }
+    const { parent, value: step } = itinerary;
+    const current = navigationDepth(from, parent, originalPath);
+    if (current.value === undefined || current.value === null) {
+        return current;
+    }
+    const next = navigateStep(current.value, step);
+    if (next === undefined || next === null) {
+        return { value: current.value, path: xpathFromStack(parent), originalPath };
+    }
+    else {
+        return { value: next, path: xpathFromStack(itinerary), originalPath };
+    }
+}
+class OverlayNavigator {
+    navigate(from, itinerary) {
+        if (from === undefined) {
+            return undefined;
+        }
+        if (itinerary === undefined) {
+            return from;
+        }
+        const { parent, value: step } = itinerary;
+        const current = this.navigate(from, parent);
+        return current === undefined ? undefined : this.navigateStep(current, step);
+    }
+    navigateStep(from, step) {
+        if (from === undefined) {
+            return undefined;
+        }
+        if (step === undefined) {
+            return from;
+        }
+        if (Array.isArray(from.children)) {
+            if (step.type === 'lookup') {
+                const stp = step;
+                const result = from.children.find(e => e !== undefined && stp.keys.every(({ propertyName, propertyValue }) => { var _a; return ((_a = e.keys) === null || _a === void 0 ? void 0 : _a[propertyName]) === propertyValue; }));
+                return result;
+            }
+            else if (step.type === 'position') {
+                const result = from.children[step.position];
+                return result;
+            }
+        }
+        else if (from.children !== null && typeof from.children === 'object') {
+            if (step.type === 'property') {
+                const result = from === null ? undefined : from.children[step.propertyName];
+                return result;
+            }
+        }
+        return undefined;
+    }
+}
+export const overlayNavigator = new OverlayNavigator();
+/**
+ * Same as {navigate} but try to path missing data node using prototype parameter
+ * @param from
+ * @param itinerary
+ * @param prototype
+ */
+export function ensurePath(from, itinerary, prototype) {
+    return navigate(from, itinerary, prototype);
+}
+class AbstractPointerBuilder {
+    constructor() {
+        this.itinerary = [];
+    }
+    child(propertyName) {
+        this.itinerary.push({ type: "property", propertyName });
+        return this;
+    }
+    lookup(...criterion) {
+        criterion.forEach(([propertyName, propertyValue]) => {
+            this.itinerary.push({ type: "lookup", keys: [{ propertyName, propertyValue }] });
+        });
+    }
+}
+class RelativePointerBuilder extends AbstractPointerBuilder {
+    constructor(originUuid) {
+        super();
+        this.originUuid = originUuid;
+        this.type = "relative";
+    }
+}
+class AbsolutePointerBuilder extends AbstractPointerBuilder {
+    constructor() {
+        super();
+        this.type = "absolute";
+    }
+}
+export function pointer(fromId) {
+    if (fromId === undefined) {
+        return new AbsolutePointerBuilder();
+    }
+    return new RelativePointerBuilder(fromId);
+}
+export const ROOT = Object.freeze({ type: "absolute", itinerary: [] });

package/dist/es2015/itinerary/itinerary.spec.js

@@ -0,0 +1,296 @@
+import { describe, it, expect } from 'vitest';
+import { areSameItineraryStep, constructiveItinerary, itineraryOf, itineraryOverlay, itineraryToStepArray, navigate, navigationDepth, overlayNavigator, positionStep, propertyStep, xpathFromStack } from './itinerary';
+import stack from './stack';
+import { hyperReflect } from './hyper-layer-node';
+describe('Navigate itinerary', () => {
+    it('should work', () => {
+        const itinerary = {
+            "value": {
+                "type": "property",
+                "propertyName": "schema"
+            },
+            "parent": {
+                "value": {
+                    "type": "position",
+                    "position": 0
+                }
+            }
+        };
+        const actual = navigate(sampleData(), itinerary);
+        const expected = schemaEntry1.schema;
+        expect(actual).toBe(expected);
+    });
+    it('Conversion to array should work', () => {
+        const path = [0, 'schema'];
+        const itinerary = itineraryOf(...path);
+        const actual = itineraryToStepArray(itinerary);
+        const expected = path.map(e => typeof e === 'string' ? propertyStep(e) : positionStep(e));
+        expect(actual).toStrictEqual(expected);
+    });
+    it('Ensure path should work', () => {
+        const person = [{
+                name: "Elon MUSK",
+            }];
+        const path = [0, 'address'];
+        const itinerary = itineraryOf(...path);
+        const proto = { street: "Wall Street" };
+        const result = navigate(person, itinerary, stack.fromArray([proto]));
+        expect(result).toBe(proto);
+        expect(person[0].address).toBe(proto);
+    });
+    it('Deep navigation with constructiveItinerary should work', () => {
+        var _a;
+        const person = [{
+                name: "Guezo",
+                children: []
+            }];
+        const { itinerary, prototypes } = constructiveItinerary(["children", [], 0, { name: "Glélé" }, "children", [], 0, { name: "Béhanzin" }]);
+        const result = navigate(person, stack.concat(itineraryOf(0), itinerary), prototypes);
+        expect((_a = person[0]) === null || _a === void 0 ? void 0 : _a.name).toBe("Guezo");
+        expect(result.name).toBe("Béhanzin");
+    });
+    it("Overlay navigation should work", () => {
+        var _a;
+        const person = {
+            name: "John Doe",
+            age: 40,
+            address: {
+                street: "123 Main Street",
+                lines: ["Apt 4B", "2nd Floor"],
+                country: "USA"
+            },
+            children: [
+                {
+                    name: "Jane Doe",
+                    age: 10,
+                    address: {
+                        street: "456 Maple Avenue",
+                        lines: ["House 12"],
+                        country: "USA"
+                    }
+                },
+                {
+                    name: "Jack Doe",
+                    age: 8
+                }
+            ]
+        };
+        const personOverlay = hyperReflect(person);
+        const itinerary = itineraryOf("children", 0, "address", "lines", 0);
+        expect(navigate(person, itinerary)).toBe("House 12");
+        expect(navigate(personOverlay, itineraryOverlay(itinerary))).toBe("House 12");
+        expect((_a = overlayNavigator.navigate(personOverlay, itinerary)) === null || _a === void 0 ? void 0 : _a.data).toBe("House 12");
+    });
+    it("Overlay itinerary rewrite should work", () => {
+        const toOverlay = (...path) => {
+            return xpathFromStack(itineraryOverlay(itineraryOf(...path)));
+        };
+        expect(toOverlay()).toBe("/data");
+        expect(toOverlay("name")).toBe("/children/name/data");
+        expect(toOverlay("persons", 0)).toBe("/children/persons/children/*[1]/data");
+    });
+});
+const schemaEntry1 = {
+    "id": "schema:User",
+    "schema": {
+        "schemaNodeType": "object",
+        "operator": false,
+        "facets": {},
+        "properties": [
+            {
+                "uuid": "172302fe-29de-462a-9e27-053463b6d118",
+                "schemaNodeType": "property",
+                "facets": {},
+                "name": "uuid",
+                "valueSchema": {
+                    "schemaNodeType": "scalar",
+                    "operator": false,
+                    "facets": {},
+                    "type": "string"
+                }
+            },
+            {
+                "uuid": "733675e6-543e-4013-a071-a9a45145321b",
+                "schemaNodeType": "property",
+                "facets": {},
+                "name": "name",
+                "valueSchema": {
+                    "schemaNodeType": "scalar",
+                    "operator": false,
+                    "facets": {},
+                    "type": "string"
+                }
+            },
+            {
+                "uuid": "8376b829-459a-4b40-b2f9-71a6aea506e5",
+                "schemaNodeType": "property",
+                "facets": {},
+                "name": "firstName",
+                "valueSchema": {
+                    "schemaNodeType": "scalar",
+                    "operator": false,
+                    "facets": {},
+                    "type": "string"
+                }
+            },
+            {
+                "uuid": "3c39bfc4-90ae-4525-9366-47c7866265f3",
+                "schemaNodeType": "property",
+                "facets": {},
+                "name": "lastName",
+                "valueSchema": {
+                    "schemaNodeType": "scalar",
+                    "operator": false,
+                    "facets": {},
+                    "type": "string"
+                }
+            },
+            {
+                "uuid": "a5f05908-8a9f-4879-8dc9-f5214a6aa693",
+                "schemaNodeType": "property",
+                "facets": {},
+                "name": "age",
+                "valueSchema": {
+                    "schemaNodeType": "scalar",
+                    "operator": false,
+                    "facets": {},
+                    "type": "integer"
+                }
+            }
+        ]
+    }
+};
+function sampleData() {
+    return [
+        schemaEntry1,
+        {
+            "id": "schema:Car",
+            "schema": {
+                "schemaNodeType": "object",
+                "operator": false,
+                "facets": {},
+                "properties": [
+                    {
+                        "uuid": "50fa33fe-03b4-45f2-b5df-da00e742bb89",
+                        "schemaNodeType": "property",
+                        "facets": {},
+                        "name": "uuid",
+                        "valueSchema": {
+                            "schemaNodeType": "scalar",
+                            "operator": false,
+                            "facets": {},
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "uuid": "6ff05784-dde5-4a70-a57b-d93cba8afb00",
+                        "schemaNodeType": "property",
+                        "facets": {},
+                        "name": "name",
+                        "valueSchema": {
+                            "schemaNodeType": "scalar",
+                            "operator": false,
+                            "facets": {},
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "uuid": "a8dae1ce-a82f-46f4-a2a0-4fc177988e3c",
+                        "schemaNodeType": "property",
+                        "facets": {},
+                        "name": "brand",
+                        "valueSchema": {
+                            "schemaNodeType": "scalar",
+                            "operator": false,
+                            "facets": {},
+                            "type": "string"
+                        }
+                    },
+                    {
+                        "uuid": "85342429-673f-420e-b0d0-7e019e7bea2a",
+                        "schemaNodeType": "property",
+                        "facets": {},
+                        "name": "color",
+                        "valueSchema": {
+                            "schemaNodeType": "scalar",
+                            "operator": false,
+                            "facets": {},
+                            "type": "string"
+                        }
+                    }
+                ]
+            }
+        }
+    ];
+}
+// Unit tests for areSameItineraryStep
+describe('areSameItineraryStep', () => {
+    it('returns true for two position steps with the same position', () => {
+        expect(areSameItineraryStep(positionStep(3), positionStep(3))).toBe(true);
+    });
+    it('returns false for two position steps with different positions', () => {
+        expect(areSameItineraryStep(positionStep(2), positionStep(5))).toBe(false);
+    });
+    it('returns true for two property steps with the same propertyName', () => {
+        expect(areSameItineraryStep(propertyStep('foo'), propertyStep('foo'))).toBe(true);
+    });
+    it('returns false for two property steps with different propertyNames', () => {
+        expect(areSameItineraryStep(propertyStep('foo'), propertyStep('bar'))).toBe(false);
+    });
+    it('returns false for steps of different types', () => {
+        expect(areSameItineraryStep(positionStep(1), propertyStep('1'))).toBe(false);
+    });
+    it('returns false if one or both steps are null or undefined', () => {
+        expect(areSameItineraryStep(positionStep(1), null)).toBe(false);
+        expect(areSameItineraryStep(undefined, propertyStep('foo'))).toBe(false);
+        expect(areSameItineraryStep(undefined, undefined)).toBe(false);
+    });
+});
+describe('navigationDepth with itineraryOf', () => {
+    it('should return root when itinerary is undefined', () => {
+        const obj = { a: 1 };
+        const result = navigationDepth(obj, undefined);
+        expect(result.value).toBe(obj);
+        expect(result.path).toBe('');
+    });
+    it('should navigate fully when path exists', () => {
+        const obj = { a: { b: { c: 42 } } };
+        const itinerary = itineraryOf('a', 'b', 'c');
+        const result = navigationDepth(obj, itinerary);
+        expect(result.value).toBe(42);
+        expect(result.path).toBe('/a/b/c');
+    });
+    it('should stop at last defined property (null)', () => {
+        const obj = { a: { b: null } };
+        const itinerary = itineraryOf('a', 'b', 'c');
+        const result = navigationDepth(obj, itinerary);
+        expect(result.value).toEqual({ b: null });
+        expect(result.path).toBe('/a/b');
+    });
+    it('should stop when root is undefined', () => {
+        const result = navigationDepth(undefined, itineraryOf('a', 'b'));
+        expect(result.value).toBeUndefined();
+        expect(result.path).toBe('');
+    });
+    it('should navigate inside array with position step', () => {
+        const obj = { list: [{ id: 1 }, { id: 2 }] };
+        const itinerary = itineraryOf('list', 1);
+        const result = navigationDepth(obj, itinerary);
+        expect(result.value).toEqual({ id: 2 });
+        expect(result.path).toBe('/list/*[2]');
+    });
+    it('should stop when lookup fails', () => {
+        const obj = { list: [{ id: 1 }, { id: 2 }] };
+        const lookupStep = {
+            type: 'lookup',
+            keys: [{ propertyName: 'id', propertyValue: 3 }]
+        };
+        const itinerary = {
+            value: lookupStep,
+            parent: itineraryOf('list')
+        };
+        const result = navigationDepth(obj, itinerary);
+        expect(result.value).toEqual(obj.list);
+        expect(result.path).toBe('/list');
+    });
+});