@hamak/navigation-utils 0.4.0

package/src/itinerary/itinerary.ts

@@ -0,0 +1,363 @@
+import stack, {StackElement} from "./stack";
+import {HyperLayerNode} from "./hyper-layer-node";
+
+export type ObjectId = string | number
+
+interface PropertyValuePair<P = string,V = any> {
+  propertyName : P
+  propertyValue : V
+}
+
+export interface ItineraryStepBase {
+  type : "property" | "lookup" | "position"
+}
+
+export interface PropertyStep extends ItineraryStepBase{
+  type : "property"
+  propertyName : string
+}
+
+export interface LookupStep extends ItineraryStepBase{
+  type : "lookup",
+  keys : PropertyValuePair[]
+}
+
+export interface PositionStep extends ItineraryStepBase{
+  type : "position",
+  position : number
+}
+
+export type ItineraryStep = PropertyStep | LookupStep | PositionStep
+
+export type Itinerary = StackElement<ItineraryStep>
+
+export interface ConstructiveItinerary {
+  itinerary : Itinerary | undefined
+  prototypes : StackElement<any> | undefined
+}
+
+export type StepValueNodeType = Array<any> | Record<string | number, any>
+
+export function constructiveItinerary(steps : Array<string | number | StepValueNodeType>) : ConstructiveItinerary {
+  const segments : Array<string | number> = []
+  const prototypes : Array<any> = []
+
+  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 : ItineraryStep | null | undefined, step2: ItineraryStep | null | undefined) : boolean {
+  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: PropertyValuePair, p2: PropertyValuePair) {
+  return p1.propertyName === p2.propertyName
+      && p1.propertyValue === p2.propertyValue
+}
+
+export function itineraryOf(... args : (string | number)[]) : Itinerary | undefined{
+  return args.reduce((parent, e) => {
+    const value = typeof e === 'string' ? propertyStep(e) : positionStep(e)
+    return {parent, value}
+  }, undefined as StackElement<ItineraryStep> | undefined)
+}
+
+const dataStep = propertyStep("data")
+const childrenStep = propertyStep("children")
+
+export function itineraryOverlay(it :  Itinerary | undefined) : Itinerary {
+  return {value:dataStep, parent:itineraryOverlayInner(it)}
+}
+
+function itineraryOverlayInner(it :  Itinerary | undefined) : Itinerary | undefined{
+  if(it === undefined){
+    return undefined
+  } else {
+    const {value, parent} = it
+    return {value, parent:{value:childrenStep, parent: itineraryOverlayInner(parent)}}
+  }
+}
+
+export function itineraryToStepArray(itinerary :Itinerary | undefined) : ItineraryStep[] {
+  let itn : Itinerary | undefined = itinerary
+  const result : ItineraryStep[] = []
+  while (itn !== undefined){
+    result.push(itn.value)
+    itn = itn.parent
+  }
+
+  return result.reverse()
+}
+
+export function propertyStep(propertyName: string) : PropertyStep {
+  return {type:"property", propertyName}
+}
+
+export function positionStep(position: number) : PositionStep {
+  return {type:"position", position}
+}
+
+export function lookupStep(criteria: Record<string, any>) : LookupStep {
+  return {type:"lookup", keys:Object.entries(criteria).map(([k, v]) => ({propertyName:k, propertyValue:v}))}
+}
+
+export function xpathFromStack(path?: StackElement<ItineraryStep>) : string{
+  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: any, itinerary : Itinerary | undefined, prototype? : StackElement<any>) : any {
+  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: any, step : ItineraryStep, prototype? : any) : any {
+  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: any,
+  itinerary: Itinerary | undefined,
+  originalPath: string = xpathFromStack(itinerary)
+): { value: any; path: string; originalPath: string } {
+  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<T>(from: HyperLayerNode<T>, itinerary : Itinerary | undefined) : HyperLayerNode<T>  | undefined{
+    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)
+  }
+
+  protected navigateStep<T>(from: HyperLayerNode<T>, step : ItineraryStep) : HyperLayerNode<T>  | undefined {
+    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: any, itinerary : Itinerary | undefined, prototype? : any) : any {
+ return navigate(from, itinerary, prototype)
+}
+
+interface PointerBase {
+  type : "absolute" | "relative"
+  itinerary : ItineraryStep[]
+}
+
+export interface AbsolutePointer extends PointerBase {
+  type : "absolute"
+}
+
+export interface RelativePointer extends PointerBase {
+  type : "relative"
+  originUuid : ObjectId
+}
+
+abstract class AbstractPointerBuilder {
+  readonly itinerary : ItineraryStep[] = []
+  public child(propertyName : string){
+    this.itinerary.push({type:"property", propertyName})
+    return this
+  }
+  public lookup(...criterion : [string, any]){
+    criterion.forEach(([propertyName, propertyValue]) => {
+      this.itinerary.push({type:"lookup", keys:[{propertyName, propertyValue}]})
+    })
+  }
+}
+
+class RelativePointerBuilder extends AbstractPointerBuilder implements RelativePointer {
+  readonly type = "relative"
+  public constructor(public originUuid : ObjectId){
+    super()
+  }
+}
+
+class AbsolutePointerBuilder extends AbstractPointerBuilder implements AbsolutePointer {
+  readonly type = "absolute"
+  public constructor(){
+    super()
+  }
+}
+
+type Pointer = AbsolutePointer | RelativePointer
+
+export function pointer(fromId?: ObjectId) : AbsolutePointerBuilder | RelativePointerBuilder {
+  if(fromId === undefined){
+    return new AbsolutePointerBuilder()
+  }
+
+  return new RelativePointerBuilder(fromId)
+}
+
+export const ROOT : AbsolutePointer = Object.freeze({type:"absolute", itinerary:[]})

package/src/itinerary/stack.spec.ts

@@ -0,0 +1,46 @@
+import stack from "./stack";
+import { describe, it, expect } from 'vitest';
+
+describe("Core util stack", () => {
+  it("fromArray should work", () => {
+    const itinerary = stack.fromArray([1, 2, 3, 4])
+
+    expect(itinerary?.value).toBe(4)
+    expect(itinerary?.parent?.parent?.parent?.value).toBe(1)
+
+    expect(stack.fromArray([])).toBe(undefined)
+    expect(stack.fromArray(undefined)).toBe(undefined)
+  })
+
+  it("reduce should work", () => {
+    const itinerary = stack.fromArray([1, 2, 3, 4])
+
+    const result = stack.reduce(itinerary, (acc, t) => acc + t, 0);
+    expect(result).toBe(10)
+  })
+
+  it("reduce order should work", () => {
+    const itinerary = stack.fromArray([1, 2, 3, 4])
+
+    const result = stack.reduce(itinerary, (acc, t) => [...acc, t], [] as number[]);
+    expect(result).toStrictEqual([1, 2, 3, 4])
+  })
+
+  it("equal should work", () => {
+    expect(stack.equal(undefined, undefined)).toBe(false)
+    expect(stack.equal(null, null)).toBe(false)
+    expect(stack.equal(undefined, null)).toBe(false)
+    expect(stack.equal(null, undefined)).toBe(false)
+
+    expect(stack.equal(stack.fromArray([1, 2, 3, 4]), undefined)).toBe(false)
+    expect(stack.equal(stack.fromArray([1, 2, 3, 4]), null)).toBe(false)
+
+    expect(stack.equal(undefined, stack.fromArray([1, 2, 3, 4]))).toBe(false)
+    expect(stack.equal(null, stack.fromArray([1, 2, 3, 4]))).toBe(false)
+
+    expect(stack.equal(stack.fromArray([1]), stack.fromArray([2]))).toBe(false)
+    expect(stack.equal(stack.fromArray([1]), stack.fromArray([1, 2]))).toBe(false)
+
+    expect(stack.equal(stack.fromArray([1, 2, 3, 4]), stack.fromArray([1, 2, 3, 4]))).toBe(true)
+  })
+})

package/src/itinerary/stack.ts

@@ -0,0 +1,62 @@
+export interface StackElement<T> {
+  value : T
+  parent? : StackElement<T>
+}
+
+export function head<T>(value : T) : StackElement<T> {
+  return {value}
+}
+
+export function push<T>(head : StackElement<T> | undefined, value : T) : StackElement<T> {
+  return {value, parent: head}
+}
+
+export function concat<T>(tail : StackElement<T> | undefined, stack : StackElement<T> | undefined) : StackElement<T> | undefined{
+  if(tail === undefined) return stack
+  if(stack === undefined) return tail
+
+  const {parent, value} = stack
+
+  return {value, parent:concat(tail, parent)}
+}
+
+export function fromArray<T = any>(t : T[] | undefined) : StackElement<T> | undefined {
+  return t?.reduce((acc, t) => push(acc, t), undefined as undefined | StackElement<T>)
+}
+
+export function reduce<T, R>(head : StackElement<T> | undefined, reducer : (r: R, t : T) => R, initial : R) : R {
+  if(head === undefined){
+    return initial
+  }
+
+  const {parent, value} = head
+  const acc = reduce(parent, reducer, initial)
+  return reducer(acc, value)
+}
+
+function equal<T>(a:StackElement<T> | null | undefined, b : StackElement<T> | null | undefined) : boolean {
+  // 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/src/path/pathway-resolver.ts

@@ -0,0 +1,36 @@
+import {Path, Pathway} from "./pathway";
+
+export interface PathwayResolver<T>{
+  resolve(path : string | string[] | Pathway) : T | undefined
+}
+
+export class RecordPathwayResolver<T> implements PathwayResolver<T> {
+  constructor(readonly record : Record<string, T>) {
+  }
+
+  resolve(path: string | string[] | Pathway): T | undefined {
+    const key = Pathway.asString(path)
+    return this.record[key]
+  }
+}
+
+export class EmptyPathwayResolver<T> implements PathwayResolver<T> {
+  resolve(path: string | string[] | Pathway): T | undefined {
+    return undefined
+  }
+}
+
+export class RelativePathwayResolver<T> implements PathwayResolver<T> {
+  private relativePathway : Pathway
+  constructor(readonly parentResolver : PathwayResolver<T>, readonly path : Path) {
+    this.relativePathway = Pathway.of(path)
+  }
+  resolve(path: string | string[] | Pathway): T | undefined {
+    const pathway = Pathway.of(path)
+    if(pathway.isAbsolute()){
+      return this.parentResolver.resolve(path)
+    } else {
+      return this.parentResolver.resolve(this.relativePathway.resolve(pathway))
+    }
+  }
+}