@hamak/navigation-utils 0.4.0

package/dist/itinerary/itinerary.js

@@ -0,0 +1,275 @@
+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) {
+    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"
+                    && step1.keys?.length === step2.keys?.length
+                    && step1.keys?.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?.parent);
+    return navigateStep(current, step, 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 }) => e.keys?.[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/itinerary/itinerary.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=itinerary.spec.d.ts.map

package/dist/itinerary/itinerary.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"itinerary.spec.d.ts","sourceRoot":"","sources":["../../src/itinerary/itinerary.spec.ts"],"names":[],"mappings":""}

package/dist/itinerary/itinerary.spec.js

@@ -0,0 +1,294 @@
+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', () => {
+        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(person[0]?.name).toBe("Guezo");
+        expect(result.name).toBe("Béhanzin");
+    });
+    it("Overlay navigation should work", () => {
+        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(overlayNavigator.navigate(personOverlay, itinerary)?.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');
+    });
+});

package/dist/itinerary/stack.d.ts

@@ -0,0 +1,20 @@
+export interface StackElement<T> {
+    value: T;
+    parent?: StackElement<T>;
+}
+export declare function head<T>(value: T): StackElement<T>;
+export declare function push<T>(head: StackElement<T> | undefined, value: T): StackElement<T>;
+export declare function concat<T>(tail: StackElement<T> | undefined, stack: StackElement<T> | undefined): StackElement<T> | undefined;
+export declare function fromArray<T = any>(t: T[] | undefined): StackElement<T> | undefined;
+export declare function reduce<T, R>(head: StackElement<T> | undefined, reducer: (r: R, t: T) => R, initial: R): R;
+declare function equal<T>(a: StackElement<T> | null | undefined, b: StackElement<T> | null | undefined): boolean;
+declare const stack: {
+    push: typeof push;
+    head: typeof head;
+    concat: typeof concat;
+    reduce: typeof reduce;
+    fromArray: typeof fromArray;
+    equal: typeof equal;
+};
+export default stack;
+//# sourceMappingURL=stack.d.ts.map

package/dist/itinerary/stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/itinerary/stack.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,KAAK,EAAG,CAAC,CAAA;IACT,MAAM,CAAC,EAAG,YAAY,CAAC,CAAC,CAAC,CAAA;CAC1B;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAG,CAAC,GAAI,YAAY,CAAC,CAAC,CAAC,CAEnD;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,EAAG,CAAC,GAAI,YAAY,CAAC,CAAC,CAAC,CAEvF;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,EAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,GAAI,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAO/H;AAED,wBAAgB,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,EAAG,CAAC,EAAE,GAAG,SAAS,GAAI,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAEpF;AAED,wBAAgB,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAG,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,EAAE,OAAO,EAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAG,CAAC,KAAK,CAAC,EAAE,OAAO,EAAG,CAAC,GAAI,CAAC,CAQ9G;AAED,iBAAS,KAAK,CAAC,CAAC,EAAE,CAAC,EAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,CAAC,EAAG,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,GAAI,OAAO,CAqBxG;AAED,QAAA,MAAM,KAAK;;;;;;;CAAiD,CAAA;AAE5D,eAAe,KAAK,CAAC"}

package/dist/itinerary/stack.js

@@ -0,0 +1,47 @@
+export function head(value) {
+    return { value };
+}
+export function push(head, value) {
+    return { value, parent: head };
+}
+export function concat(tail, stack) {
+    if (tail === undefined)
+        return stack;
+    if (stack === undefined)
+        return tail;
+    const { parent, value } = stack;
+    return { value, parent: concat(tail, parent) };
+}
+export function fromArray(t) {
+    return t?.reduce((acc, t) => push(acc, t), undefined);
+}
+export function reduce(head, reducer, initial) {
+    if (head === undefined) {
+        return initial;
+    }
+    const { parent, value } = head;
+    const acc = reduce(parent, reducer, initial);
+    return reducer(acc, value);
+}
+function equal(a, b) {
+    // Not equal if both are nullish
+    if (a === undefined || a === null || b === undefined || b === null) {
+        return false;
+    }
+    while (a !== undefined && b !== undefined) {
+        if (a.value !== b.value) {
+            return false;
+        }
+        a = a.parent;
+        b = b.parent;
+    }
+    // Equal if traversed all stack at both side
+    if ((a === undefined || a === null) && (b === undefined || b === null)) {
+        return true;
+    }
+    else {
+        return false;
+    }
+}
+const stack = { push, head, concat, reduce, fromArray, equal };
+export default stack;

package/dist/itinerary/stack.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stack.spec.d.ts.map

package/dist/itinerary/stack.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.spec.d.ts","sourceRoot":"","sources":["../../src/itinerary/stack.spec.ts"],"names":[],"mappings":""}