gremlin 4.0.0-beta.2 → 4.0.0-beta.3

package/build/cjs/structure/PDTRegistry.cjs

@@ -0,0 +1,116 @@
+"use strict";
+/*
+ *  Licensed to the Apache Software Foundation (ASF) under one
+ *  or more contributor license agreements.  See the NOTICE file
+ *  distributed with this work for additional information
+ *  regarding copyright ownership.  The ASF licenses this file
+ *  to you under the Apache License, Version 2.0 (the
+ *  "License"); you may not use this file except in compliance
+ *  with the License.  You may obtain a copy of the License at
+ *
+ *  http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed on an
+ *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ *  KIND, either express or implied.  See the License for the
+ *  specific language governing permissions and limitations
+ *  under the License.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PDTRegistry = void 0;
+const graph_js_1 = require("./graph.cjs");
+/**
+ * A standalone registry that allows users to register adapters for hydrating
+ * raw {@link CompositePDT} and {@link PrimitivePDT} instances
+ * into domain-specific objects.
+ */
+class PDTRegistry {
+    _adapters = new Map();
+    _adaptersByClass = new Map();
+    _primitiveAdapters = new Map();
+    _primitiveAdaptersByClass = new Map();
+    register(typeName, adapter, targetClass) {
+        this._adapters.set(typeName, adapter);
+        if (targetClass) {
+            this._adaptersByClass.set(targetClass, { typeName, adapter });
+        }
+    }
+    registerPrimitive(typeName, adapter, targetClass) {
+        this._primitiveAdapters.set(typeName, adapter);
+        if (targetClass) {
+            this._primitiveAdaptersByClass.set(targetClass, { typeName, adapter });
+        }
+    }
+    hydrate(pdt) {
+        if (!(pdt instanceof graph_js_1.CompositePDT))
+            return pdt;
+        const adapter = this._adapters.get(pdt.name);
+        const hydratedFields = {};
+        let changed = false;
+        for (const [k, v] of Object.entries(pdt.fields)) {
+            if (v instanceof graph_js_1.CompositePDT) {
+                const h = this.hydrate(v);
+                hydratedFields[k] = h;
+                if (h !== v)
+                    changed = true;
+            }
+            else if (v instanceof graph_js_1.PrimitivePDT) {
+                const h = this.hydratePrimitive(v);
+                hydratedFields[k] = h;
+                if (h !== v)
+                    changed = true;
+            }
+            else {
+                hydratedFields[k] = v;
+            }
+        }
+        if (!adapter) {
+            return changed ? new graph_js_1.CompositePDT(pdt.name, hydratedFields) : pdt;
+        }
+        try {
+            return adapter.deserialize(hydratedFields);
+        }
+        catch (e) {
+            console.warn(`PDT hydration failed for '${pdt.name}': ${e.message}`);
+            return pdt;
+        }
+    }
+    hydratePrimitive(pdt) {
+        if (!(pdt instanceof graph_js_1.PrimitivePDT))
+            return pdt;
+        const adapter = this._primitiveAdapters.get(pdt.name);
+        if (!adapter)
+            return pdt;
+        try {
+            return adapter.fromValue(pdt.value);
+        }
+        catch (e) {
+            console.warn(`Primitive PDT hydration failed for '${pdt.name}': ${e.message}`);
+            return pdt;
+        }
+    }
+    hasAdapter(typeName) {
+        return this._adapters.has(typeName);
+    }
+    hasPrimitiveAdapter(typeName) {
+        return this._primitiveAdapters.has(typeName);
+    }
+    getSerializer(typeName) {
+        const adapter = this._adapters.get(typeName);
+        return adapter ? adapter.serialize : null;
+    }
+    getAdapterByClass(cls) {
+        const entry = this._adaptersByClass.get(cls);
+        if (!entry)
+            return null;
+        return { typeName: entry.typeName, serialize: entry.adapter.serialize };
+    }
+    getPrimitiveAdapterByClass(cls) {
+        const entry = this._primitiveAdaptersByClass.get(cls);
+        if (!entry)
+            return null;
+        return { typeName: entry.typeName, toValue: entry.adapter.toValue };
+    }
+}
+exports.PDTRegistry = PDTRegistry;

package/build/cjs/structure/PDTRegistry.d.cts

@@ -0,0 +1,34 @@
+export interface PdtAdapter {
+    serialize: (obj: any) => Record<string, any>;
+    deserialize: (fields: Record<string, any>) => any;
+}
+export interface PrimitivePdtAdapter {
+    toValue: (obj: any) => string;
+    fromValue: (value: string) => any;
+}
+/**
+ * A standalone registry that allows users to register adapters for hydrating
+ * raw {@link CompositePDT} and {@link PrimitivePDT} instances
+ * into domain-specific objects.
+ */
+export declare class PDTRegistry {
+    private readonly _adapters;
+    private readonly _adaptersByClass;
+    private readonly _primitiveAdapters;
+    private readonly _primitiveAdaptersByClass;
+    register(typeName: string, adapter: PdtAdapter, targetClass?: Function): void;
+    registerPrimitive(typeName: string, adapter: PrimitivePdtAdapter, targetClass?: Function): void;
+    hydrate(pdt: any): any;
+    hydratePrimitive(pdt: any): any;
+    hasAdapter(typeName: string): boolean;
+    hasPrimitiveAdapter(typeName: string): boolean;
+    getSerializer(typeName: string): ((obj: any) => Record<string, any>) | null;
+    getAdapterByClass(cls: Function): {
+        typeName: string;
+        serialize: (obj: any) => Record<string, any>;
+    } | null;
+    getPrimitiveAdapterByClass(cls: Function): {
+        typeName: string;
+        toValue: (obj: any) => string;
+    } | null;
+}

package/build/cjs/structure/graph.cjs

@@ -18,16 +18,25 @@
  *  under the License.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Path = exports.Property = exports.VertexProperty = exports.Edge = exports.Vertex = exports.Graph = void 0;
+exports.PrimitivePDT = exports.CompositePDT = exports.Path = exports.Tree = exports.Property = exports.VertexProperty = exports.Edge = exports.Vertex = exports.Graph = void 0;
 /**
  * @author Jorge Bay Gondra
  */
 /**
  * An "empty" graph object to server only as a reference.
+ *
+ * Holds in-memory collections of vertices and edges so that GraphBinary
+ * Graph (0x10) deserialization can return a usable data container.
  */
 class Graph {
+    vertices;
+    edges;
+    constructor() {
+        this.vertices = new Map();
+        this.edges = new Map();
+    }
     toString() {
-        return 'graph[]';
+        return `graph[vertices:${this.vertices.size} edges:${this.edges.size}]`;
     }
 }
 exports.Graph = Graph;
@@ -50,8 +59,17 @@ class Element {
     }
 }
 class Vertex extends Element {
-    constructor(id, label, properties = []) {
-        super(id, label, properties ?? []);
+    labels;
+    constructor(id, label, properties = [], labels) {
+        // Determine the canonical labels array from either explicit labels param or label param
+        const resolvedLabels = labels
+            ? labels
+            : Array.isArray(label) ? label
+                : label ? [label]
+                    : ['vertex'];
+        const primaryLabel = (resolvedLabels.length > 0 ? resolvedLabels[0] : 'vertex');
+        super(id, primaryLabel, properties ?? []);
+        this.labels = new Set(resolvedLabels);
     }
     toString() {
         return `v[${this.id}]`;
@@ -60,13 +78,20 @@ class Vertex extends Element {
 exports.Vertex = Vertex;
 class Edge extends Element {
     outV;
-    label;
     inV;
-    constructor(id, outV, label, inV, properties = []) {
-        super(id, label, properties ?? []);
+    labels;
+    constructor(id, outV, label, inV, properties = [], labels) {
+        // Determine the canonical labels array from either explicit labels param or label param
+        const resolvedLabels = labels
+            ? labels
+            : Array.isArray(label) ? label
+                : label ? [label]
+                    : ['edge'];
+        const primaryLabel = (resolvedLabels.length > 0 ? resolvedLabels[0] : 'edge');
+        super(id, primaryLabel, properties ?? []);
         this.outV = outV;
-        this.label = label;
         this.inV = inV;
+        this.labels = new Set(resolvedLabels);
     }
     toString() {
         const outVId = this.outV ? this.outV.id : '?';
@@ -104,6 +129,270 @@ class Property {
     }
 }
 exports.Property = Property;
+/**
+ * A tree data structure with a tree-shaped public API.
+ *
+ * Children are kept in a private, ordered array of {key, value} entries (not a
+ * native {@link Map}, whose reference-identity keys would break value-equality).
+ * Access is only through the read API; lookups use {@link treeKeysEqual}, which
+ * compares keys by value and treats null/undefined as a distinct key.
+ */
+class Tree {
+    #entries;
+    constructor(...rootValues) {
+        this.#entries = [];
+        for (const value of rootValues) {
+            this.#entries.push({ key: value, value: new Tree() });
+        }
+    }
+    /**
+     * Locates the entry whose key is structurally equal to the given key.
+     * @returns the matching entry, or undefined if none exists.
+     */
+    _findEntry(key) {
+        for (const entry of this.#entries) {
+            if (treeKeysEqual(entry.key, key)) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the keys at the root of this tree.
+     */
+    rootNodes() {
+        return this.#entries.map((e) => e.key);
+    }
+    /**
+     * Returns the child subtree for the given key.
+     * @throws {Error} if no child exists for the given key.
+     */
+    childAt(key) {
+        const entry = this._findEntry(key);
+        if (entry === undefined) {
+            throw new Error(`Tree has no child for key: ${key}`);
+        }
+        return entry.value;
+    }
+    /**
+     * Returns true if the given key is an immediate child of this tree.
+     */
+    hasChild(key) {
+        return this._findEntry(key) !== undefined;
+    }
+    /**
+     * Returns true if the given value appears as a key anywhere in this tree (recursive).
+     */
+    contains(value) {
+        for (const entry of this.#entries) {
+            if (treeKeysEqual(entry.key, value)) {
+                return true;
+            }
+        }
+        for (const entry of this.#entries) {
+            if (entry.value.contains(value)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Recursively searches the tree for the first subtree rooted at key.
+     * @returns the matching subtree, or undefined if absent.
+     */
+    findSubtree(key) {
+        const entry = this._findEntry(key);
+        if (entry !== undefined) {
+            return entry.value;
+        }
+        for (const e of this.#entries) {
+            const found = e.value.findSubtree(key);
+            if (found !== undefined) {
+                return found;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Returns the existing child for key, or inserts and returns a new empty Tree if absent.
+     */
+    getOrCreateChild(key) {
+        const entry = this._findEntry(key);
+        if (entry !== undefined) {
+            return entry.value;
+        }
+        const child = new Tree();
+        this.#entries.push({ key, value: child });
+        return child;
+    }
+    /**
+     * Returns true if this tree has no children. An empty tree is considered a leaf.
+     */
+    isLeaf() {
+        return this.#entries.length === 0;
+    }
+    /**
+     * Returns the total number of nodes (keys) in the tree, counted recursively.
+     */
+    nodeCount() {
+        let count = this.#entries.length;
+        for (const entry of this.#entries) {
+            count += entry.value.nodeCount();
+        }
+        return count;
+    }
+    /**
+     * Returns the keys at the given depth. Depth 0 returns the root keys.
+     * Negative depths or depths beyond the tree's height return an empty array.
+     */
+    getNodesAtDepth(depth) {
+        const list = [];
+        for (const t of this.getTreesAtDepth(depth)) {
+            for (const entry of t.#entries) {
+                list.push(entry.key);
+            }
+        }
+        return list;
+    }
+    /**
+     * Returns the trees at the given depth. Depth 0 returns a singleton list containing this tree.
+     * Negative depths or depths beyond the tree's height return an empty array.
+     */
+    getTreesAtDepth(depth) {
+        if (depth < 0) {
+            return [];
+        }
+        let currentDepth = [this];
+        for (let i = 0; i < depth; i++) {
+            const next = [];
+            for (const t of currentDepth) {
+                for (const entry of t.#entries) {
+                    next.push(entry.value);
+                }
+            }
+            if (next.length === 0) {
+                return [];
+            }
+            currentDepth = next;
+        }
+        return currentDepth;
+    }
+    /**
+     * Returns all keys whose subtrees are leaves.
+     */
+    getLeafNodes() {
+        const leaves = [];
+        this._collectLeafKeys(leaves);
+        return leaves;
+    }
+    _collectLeafKeys(out) {
+        for (const entry of this.#entries) {
+            if (entry.value.isLeaf()) {
+                out.push(entry.key);
+            }
+            else {
+                entry.value._collectLeafKeys(out);
+            }
+        }
+    }
+    /**
+     * Returns single-key trees representing each leaf key in this tree, preserving the original
+     * key-to-empty-subtree mapping.
+     */
+    getLeafTrees() {
+        const leaves = [];
+        this._collectLeafTrees(leaves);
+        return leaves;
+    }
+    _collectLeafTrees(out) {
+        for (const entry of this.#entries) {
+            if (entry.value.isLeaf()) {
+                const leaf = new Tree();
+                leaf.#entries.push({ key: entry.key, value: entry.value });
+                out.push(leaf);
+            }
+            else {
+                entry.value._collectLeafTrees(out);
+            }
+        }
+    }
+    /**
+     * Recursively merges other into this tree. For overlapping keys, child subtrees are merged in turn.
+     * For keys present only in other, the corresponding subtree reference is adopted directly.
+     */
+    addTree(other) {
+        for (const entry of other.#entries) {
+            const existing = this._findEntry(entry.key);
+            if (existing !== undefined) {
+                existing.value.addTree(entry.value);
+            }
+            else {
+                this.#entries.push({ key: entry.key, value: entry.value });
+            }
+        }
+    }
+    /**
+     * Splits this tree into one tree per root key. If the tree has a single root, returns a singleton list
+     * containing this tree.
+     */
+    splitParents() {
+        if (this.#entries.length === 1) {
+            return [this];
+        }
+        const parents = [];
+        for (const entry of this.#entries) {
+            const parentTree = new Tree();
+            parentTree.#entries.push({ key: entry.key, value: entry.value });
+            parents.push(parentTree);
+        }
+        return parents;
+    }
+    /**
+     * Produces a formatted string representation of the tree structure using a |-- ASCII style,
+     * Uses a |-- ASCII style with a 3-space indent per level and no trailing newline.
+     */
+    prettyPrint() {
+        const lines = [];
+        this._prettyPrint(lines, '');
+        return lines.join('\n');
+    }
+    _prettyPrint(lines, prefix) {
+        for (const entry of this.#entries) {
+            lines.push(`${prefix}|--${entry.key}`);
+            entry.value._prettyPrint(lines, `${prefix}   `);
+        }
+    }
+    /**
+     * Structural recursive equality. Order across siblings is irrelevant; two trees are equal if they have the
+     * same set of keys and each key's subtree is recursively equal.
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+        if (!(other instanceof Tree)) {
+            return false;
+        }
+        if (this.#entries.length !== other.#entries.length) {
+            return false;
+        }
+        for (const entry of this.#entries) {
+            const match = other._findEntry(entry.key);
+            if (match === undefined) {
+                return false;
+            }
+            if (!entry.value.equals(match.value)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    toString() {
+        const parts = this.#entries.map((e) => `${e.key}=${e.value.toString()}`);
+        return `{${parts.join(', ')}}`;
+    }
+}
+exports.Tree = Tree;
 /**
  * Represents a walk through a graph as defined by a traversal.
  */
@@ -128,6 +417,24 @@ class Path {
     }
 }
 exports.Path = Path;
+/**
+ * Null-safe structural key comparison for Tree keys, built on {@link areEqual}.
+ * areEqual dereferences obj.equals, so null/undefined keys are handled here first.
+ * Element keys also require matching concrete type (the shared {@link Element.equals}
+ * compares by id only), so a Vertex and an Edge with the same id stay distinct keys.
+ */
+function treeKeysEqual(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a === null || a === undefined || b === null || b === undefined) {
+        return false;
+    }
+    if (a instanceof Element && b instanceof Element && a.constructor !== b.constructor) {
+        return false;
+    }
+    return areEqual(a, b);
+}
 function areEqual(obj1, obj2) {
     if (obj1 === obj2) {
         return true;
@@ -148,6 +455,42 @@ function areEqual(obj1, obj2) {
     }
     return false;
 }
+/**
+ * Represents a composite Provider Defined Type (PDT).
+ */
+class CompositePDT {
+    name;
+    fields;
+    constructor(name, fields) {
+        if (!name)
+            throw new Error('CompositePDT name cannot be null or empty');
+        this.name = name;
+        this.fields = Object.freeze(fields || {});
+    }
+    toString() {
+        return `pdt[${this.name}]${JSON.stringify(this.fields)}`;
+    }
+}
+exports.CompositePDT = CompositePDT;
+/**
+ * Represents a primitive Provider Defined Type (PDT).
+ */
+class PrimitivePDT {
+    name;
+    value;
+    constructor(name, value) {
+        if (!name)
+            throw new Error('PrimitivePDT name cannot be null or empty');
+        if (value === null || value === undefined)
+            throw new Error('PrimitivePDT value cannot be null');
+        this.name = name;
+        this.value = value;
+    }
+    toString() {
+        return `pdt[${this.name}:${this.value}]`;
+    }
+}
+exports.PrimitivePDT = PrimitivePDT;
 function summarize(value) {
     if (value === null || value === undefined) {
         return value;