@hamak/navigation-utils 0.4.0

package/dist/itinerary/stack.spec.js

@@ -0,0 +1,34 @@
+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], []);
+        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/dist/path/pathway-resolver.d.ts

@@ -0,0 +1,20 @@
+import { Path, Pathway } from "./pathway";
+export interface PathwayResolver<T> {
+    resolve(path: string | string[] | Pathway): T | undefined;
+}
+export declare class RecordPathwayResolver<T> implements PathwayResolver<T> {
+    readonly record: Record<string, T>;
+    constructor(record: Record<string, T>);
+    resolve(path: string | string[] | Pathway): T | undefined;
+}
+export declare class EmptyPathwayResolver<T> implements PathwayResolver<T> {
+    resolve(path: string | string[] | Pathway): T | undefined;
+}
+export declare class RelativePathwayResolver<T> implements PathwayResolver<T> {
+    readonly parentResolver: PathwayResolver<T>;
+    readonly path: Path;
+    private relativePathway;
+    constructor(parentResolver: PathwayResolver<T>, path: Path);
+    resolve(path: string | string[] | Pathway): T | undefined;
+}
+//# sourceMappingURL=pathway-resolver.d.ts.map

package/dist/path/pathway-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathway-resolver.d.ts","sourceRoot":"","sources":["../../src/path/pathway-resolver.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAE,OAAO,EAAC,MAAM,WAAW,CAAC;AAExC,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,OAAO,CAAC,IAAI,EAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAI,CAAC,GAAG,SAAS,CAAA;CAC5D;AAED,qBAAa,qBAAqB,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;gBAA1B,MAAM,EAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAG/C,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,GAAG,SAAS;CAI1D;AAED,qBAAa,oBAAoB,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAChE,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,GAAG,SAAS;CAG1D;AAED,qBAAa,uBAAuB,CAAC,CAAC,CAAE,YAAW,eAAe,CAAC,CAAC,CAAC;IAEvD,QAAQ,CAAC,cAAc,EAAG,eAAe,CAAC,CAAC,CAAC;IAAE,QAAQ,CAAC,IAAI,EAAG,IAAI;IAD9E,OAAO,CAAC,eAAe,CAAU;gBACZ,cAAc,EAAG,eAAe,CAAC,CAAC,CAAC,EAAW,IAAI,EAAG,IAAI;IAG9E,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,GAAG,CAAC,GAAG,SAAS;CAQ1D"}

package/dist/path/pathway-resolver.js

@@ -0,0 +1,31 @@
+import { Pathway } from "./pathway";
+export class RecordPathwayResolver {
+    constructor(record) {
+        this.record = record;
+    }
+    resolve(path) {
+        const key = Pathway.asString(path);
+        return this.record[key];
+    }
+}
+export class EmptyPathwayResolver {
+    resolve(path) {
+        return undefined;
+    }
+}
+export class RelativePathwayResolver {
+    constructor(parentResolver, path) {
+        this.parentResolver = parentResolver;
+        this.path = path;
+        this.relativePathway = Pathway.of(path);
+    }
+    resolve(path) {
+        const pathway = Pathway.of(path);
+        if (pathway.isAbsolute()) {
+            return this.parentResolver.resolve(path);
+        }
+        else {
+            return this.parentResolver.resolve(this.relativePathway.resolve(pathway));
+        }
+    }
+}

package/dist/path/pathway.d.ts

@@ -0,0 +1,84 @@
+export type Path = string | string[] | Pathway;
+/**
+ * Class representing a normalized pathway.
+ */
+export declare class Pathway {
+    private segments;
+    private isAbsolutePath;
+    /**
+     * Creates a Pathway instance.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     *                An empty array or "." represents the current directory.
+     */
+    constructor(path: string | string[] | null | undefined);
+    /**
+     * Factory method to create a Pathway instance.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     * @returns A new Pathway instance.
+     */
+    static of(path: string | string[] | null | undefined | Pathway): Pathway;
+    /**
+     * Normalizes a pathway by converting it into an array of segments.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     * @returns An array of normalized path segments, or an empty array if the input is null or undefined.
+     */
+    private normalizePath;
+    /**
+     * Returns the normalized path segments.
+     * @returns An array of normalized path segments.
+     */
+    getSegments(): string[];
+    isCurrentDir(): boolean;
+    /**
+     * Converts the normalized path segments back to a string.
+     * @returns The normalized path as a string.
+     */
+    toString(): string;
+    /**
+     * Checks if the pathway is absolute.
+     * @returns True if the pathway is absolute, false otherwise.
+     */
+    isAbsolute(): boolean;
+    /**
+     * Checks if the pathway is relative.
+     * @returns True if the pathway is relative, false otherwise.
+     */
+    isRelative(): boolean;
+    /**
+     * Resolves the current pathway with another pathway or string.
+     * @param otherPath - The other pathway or string to resolve against.
+     * @returns A new Pathway instance representing the resolved path.
+     */
+    resolve(otherPath: Pathway | string | string[]): Pathway;
+    /**
+     * Gets the parent directory of the current pathway.
+     * @returns A new Pathway instance representing the parent directory.
+     */
+    getParent(): Pathway;
+    /**
+     * Gets the current directory of the pathway.
+     * @returns The current directory as a string.
+     */
+    getCurrentDirectory(): string;
+    /**
+     * Static method to get the absolute path of the root.
+     * @returns A new Pathway instance representing the root path.
+     */
+    static ofRoot(): Pathway;
+    /**
+     * Determines the relative path from this pathway to another pathway.
+     * @param otherPath - The other pathway to relativize against.
+     * @returns A new Pathway instance representing the relative path.
+     */
+    relativize(otherPath: Pathway | string | string[]): Pathway;
+    /**
+     * Checks if the given path is a descendant of the current pathway.
+     * @param otherPath - The other pathway to check.
+     * @returns True if the given path is a descendant, false otherwise.
+     */
+    isDescendant(otherPath: Pathway | string | string[]): boolean;
+    static isRelativePath(path: Path): boolean;
+    static asString(path: Path): string;
+    static getName(path: string | string[] | Pathway): string;
+}
+//# sourceMappingURL=pathway.d.ts.map

package/dist/path/pathway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathway.d.ts","sourceRoot":"","sources":["../../src/path/pathway.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAA;AAC9C;;GAEG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,cAAc,CAAU;IAEhC;;;;OAIG;gBACS,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS;IAUtD;;;;OAIG;WACW,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO;IAQ/E;;;;OAIG;IACH,OAAO,CAAC,aAAa;IAgBrB;;;OAGG;IACI,WAAW,IAAI,MAAM,EAAE;IAIvB,YAAY;IAInB;;;OAGG;IACI,QAAQ,IAAI,MAAM;IAIzB;;;OAGG;IACI,UAAU,IAAI,OAAO;IAI5B;;;OAGG;IACI,UAAU,IAAI,OAAO;IAI5B;;;;OAIG;IACI,OAAO,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO;IAuB/D;;;OAGG;IACI,SAAS,IAAI,OAAO;IAQ3B;;;OAGG;IACI,mBAAmB,IAAI,MAAM;IAOpC;;;OAGG;WACW,MAAM,IAAI,OAAO;IAI/B;;;;OAIG;IACI,UAAU,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO;IAsBlE;;;;OAIG;IACI,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO;IAiBpE,MAAM,CAAC,cAAc,CAAC,IAAI,EAAG,IAAI,GAAI,OAAO;IAK5C,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAG,IAAI,GAAI,MAAM;IASrC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO;CAgBjD"}

package/dist/path/pathway.js

@@ -0,0 +1,206 @@
+/**
+ * Class representing a normalized pathway.
+ */
+export class Pathway {
+    /**
+     * Creates a Pathway instance.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     *                An empty array or "." represents the current directory.
+     */
+    constructor(path) {
+        if (path == null || path === "." || (Array.isArray(path) && path.length === 0)) {
+            this.segments = [];
+            this.isAbsolutePath = false;
+        }
+        else {
+            this.isAbsolutePath = Array.isArray(path) ? path[0].startsWith('/') : path.startsWith('/');
+            this.segments = this.normalizePath(path);
+        }
+    }
+    /**
+     * Factory method to create a Pathway instance.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     * @returns A new Pathway instance.
+     */
+    static of(path) {
+        if (path !== undefined && path !== null && typeof path === "object" && !Array.isArray(path)) {
+            return path;
+        }
+        else {
+            return new Pathway(path);
+        }
+    }
+    /**
+     * Normalizes a pathway by converting it into an array of segments.
+     * @param path - The pathway to normalize, either as a string or an array of strings.
+     * @returns An array of normalized path segments, or an empty array if the input is null or undefined.
+     */
+    normalizePath(path) {
+        if (path == null) {
+            return [];
+        }
+        const segments = Array.isArray(path) ? path : path.split('/');
+        return segments
+            .reduce((acc, segment) => {
+            if (segment === "." || segment === "") {
+                return acc;
+            }
+            return acc.concat(segment.split('/'));
+        }, [])
+            .filter(segment => segment.length > 0);
+    }
+    /**
+     * Returns the normalized path segments.
+     * @returns An array of normalized path segments.
+     */
+    getSegments() {
+        return this.segments;
+    }
+    isCurrentDir() {
+        return this.getSegments().length === 0;
+    }
+    /**
+     * Converts the normalized path segments back to a string.
+     * @returns The normalized path as a string.
+     */
+    toString() {
+        return this.isAbsolute() ? '/' + this.segments.join('/') : this.segments.join('/');
+    }
+    /**
+     * Checks if the pathway is absolute.
+     * @returns True if the pathway is absolute, false otherwise.
+     */
+    isAbsolute() {
+        return this.isAbsolutePath;
+    }
+    /**
+     * Checks if the pathway is relative.
+     * @returns True if the pathway is relative, false otherwise.
+     */
+    isRelative() {
+        return !this.isAbsolutePath;
+    }
+    /**
+     * Resolves the current pathway with another pathway or string.
+     * @param otherPath - The other pathway or string to resolve against.
+     * @returns A new Pathway instance representing the resolved path.
+     */
+    resolve(otherPath) {
+        const otherSegments = otherPath instanceof Pathway ? otherPath.getSegments() : this.normalizePath(otherPath);
+        const resolvedSegments = [...this.segments];
+        if (otherPath instanceof Pathway ? otherPath.isAbsolute() : (Array.isArray(otherPath) ? otherPath[0].startsWith('/') : otherPath.startsWith('/'))) {
+            return new Pathway(otherSegments);
+        }
+        for (const segment of otherSegments) {
+            if (segment === '..') {
+                if (resolvedSegments.length > 0 && resolvedSegments[resolvedSegments.length - 1] !== '..') {
+                    resolvedSegments.pop();
+                }
+                else {
+                    resolvedSegments.push(segment);
+                }
+            }
+            else if (segment !== '.') {
+                resolvedSegments.push(segment);
+            }
+        }
+        return new Pathway(this.isAbsolute() ? ["/", ...resolvedSegments] : resolvedSegments);
+    }
+    /**
+     * Gets the parent directory of the current pathway.
+     * @returns A new Pathway instance representing the parent directory.
+     */
+    getParent() {
+        if (this.segments.length === 0) {
+            return new Pathway(null);
+        }
+        const parentSegments = this.segments.slice(0, -1);
+        return new Pathway(this.isAbsolute() ? ["/", ...parentSegments] : parentSegments);
+    }
+    /**
+     * Gets the current directory of the pathway.
+     * @returns The current directory as a string.
+     */
+    getCurrentDirectory() {
+        if (this.segments.length === 0) {
+            return '';
+        }
+        return this.segments[this.segments.length - 1];
+    }
+    /**
+     * Static method to get the absolute path of the root.
+     * @returns A new Pathway instance representing the root path.
+     */
+    static ofRoot() {
+        return new Pathway('/');
+    }
+    /**
+     * Determines the relative path from this pathway to another pathway.
+     * @param otherPath - The other pathway to relativize against.
+     * @returns A new Pathway instance representing the relative path.
+     */
+    relativize(otherPath) {
+        const otherSegments = otherPath instanceof Pathway ? otherPath.getSegments() : this.normalizePath(otherPath);
+        if (this.isAbsolute() !== (otherPath instanceof Pathway ? otherPath.isAbsolute() : (Array.isArray(otherPath) ? otherPath[0].startsWith('/') : otherPath.startsWith('/')))) {
+            throw new Error("Cannot relativize between absolute and relative paths");
+        }
+        let commonLength = 0;
+        const maxLength = Math.min(this.segments.length, otherSegments.length);
+        for (let i = 0; i < maxLength; i++) {
+            if (this.segments[i] !== otherSegments[i]) {
+                break;
+            }
+            commonLength++;
+        }
+        const upSegments = this.segments.slice(commonLength).map(() => '..');
+        const downSegments = otherSegments.slice(commonLength);
+        return new Pathway(upSegments.concat(downSegments));
+    }
+    /**
+     * Checks if the given path is a descendant of the current pathway.
+     * @param otherPath - The other pathway to check.
+     * @returns True if the given path is a descendant, false otherwise.
+     */
+    isDescendant(otherPath) {
+        const otherSegments = otherPath instanceof Pathway ? otherPath.getSegments() : this.normalizePath(otherPath);
+        if (otherSegments.length < this.segments.length) {
+            return false;
+        }
+        for (let i = 0; i < this.segments.length; i++) {
+            if (this.segments[i] !== otherSegments[i]) {
+                return false;
+            }
+        }
+        return true;
+    }
+    static isRelativePath(path) {
+        const pathway = typeof path === "object" && !Array.isArray(path) ? path : Pathway.of(path);
+        return pathway.isRelative();
+    }
+    static asString(path) {
+        if (typeof path === "string") {
+            return path;
+        }
+        else {
+            const pathway = typeof path === "object" && !Array.isArray(path) ? path : Pathway.of(path);
+            return pathway.toString();
+        }
+    }
+    static getName(path) {
+        let name;
+        switch (typeof path) {
+            case "string":
+                {
+                    name = path;
+                }
+                break;
+            case "object":
+                {
+                    const segments = Array.isArray(path) ? path : path.getSegments();
+                    name = segments[segments.length - 1];
+                }
+                break;
+        }
+        return name;
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hamak/navigation-utils",
+  "version": "0.4.0",
+  "private": false,
+  "type": "module",
+  "description": "Navigation utilities for path manipulation and data structure navigation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/utils/navigation-utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && tsc -p tsconfig.es2015.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "legacy": "./dist/es2015/index.js"
+    },
+    "./es2015": {
+      "import": "./dist/es2015/index.js",
+      "default": "./dist/es2015/index.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "~5.4.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/filesystem/fs-node-abstract.types.ts

@@ -0,0 +1,34 @@
+/**
+ * Schema information for file content
+ */
+export type FileContentSchema = string | { schemaObject: string, namespace?: string }
+
+/**
+ * Base interface for filesystem nodes (without state)
+ */
+export interface AbstractFileSystemNodeBase {
+  type: 'directory' | 'file'
+  name: string
+}
+
+/**
+ * Abstract directory node (without state management)
+ */
+export interface AbstractDirectoryNode<T extends AbstractFileSystemNodeBase = AbstractFileSystemNode> extends AbstractFileSystemNodeBase {
+  type: 'directory'
+  children: Record<string, T>
+}
+
+/**
+ * Abstract file node (without state management)
+ */
+export interface AbstractFileNode<T = any> extends AbstractFileSystemNodeBase {
+  type: 'file'
+  content: T
+  schema: string | FileContentSchema
+}
+
+/**
+ * Union type for abstract filesystem nodes
+ */
+export type AbstractFileSystemNode = AbstractDirectoryNode | AbstractFileNode

package/src/index.ts

@@ -0,0 +1,11 @@
+// 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/src/itinerary/hyper-layer-node.ts

@@ -0,0 +1,25 @@
+export interface HyperLayerNode<T> {
+  keys?: Record<PropertyKey, any> // Keys to use for property based navigation when applicable
+  data? : T
+  children? : Record<string, HyperLayerNode<T>> | Array<HyperLayerNode<T>>
+}
+
+export function hyper<T>(data : T, children?: Record<string, HyperLayerNode<T>> | Array<HyperLayerNode<T>>) : HyperLayerNode<T> {
+  return {data, children}
+}
+
+/**
+ * Utility function that create Overlay which mirror original object
+ * @param o
+ */
+export function hyperReflect(o : any) : HyperLayerNode<any> {
+  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]) => ({...acc, [k] : hyperReflect(v)}), {}))
+  } else {
+    return hyper(o)
+  }
+}