gremlin 3.8.1 → 4.0.0-beta.3

package/build/esm/structure/graph.d.ts

@@ -0,0 +1,176 @@
+/**
+ * @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.
+ */
+export declare class Graph {
+    readonly vertices: Map<any, Vertex>;
+    readonly edges: Map<any, Edge>;
+    constructor();
+    toString(): string;
+}
+declare class Element<TLabel extends string = string, TId = any> {
+    readonly id: TId;
+    readonly label: TLabel;
+    readonly properties: Property[];
+    constructor(id: TId, label: TLabel, properties?: Property[]);
+    /**
+     * Compares this instance to another and determines if they can be considered as equal.
+     */
+    equals(other: any): boolean;
+}
+export declare class Vertex<TLabel extends string = string, TProperties extends Record<string, any> = Record<string, any>, TId = number, TVertexProperties = {
+    [P in keyof TProperties]: P extends string ? VertexProperties<P, TProperties[P]> : never;
+}> extends Element<TLabel, TId> {
+    readonly labels: Set<string>;
+    constructor(id: TId, label: TLabel | string[], properties?: Property[] | null, labels?: string[]);
+    toString(): string;
+}
+export declare class Edge<TOutVertex extends Vertex = Vertex, TLabel extends string = string, TInVertex extends Vertex = Vertex, TProperties extends Record<string, any> = Record<string, any>, TId = number> extends Element<TLabel, TId> {
+    readonly outV: TOutVertex;
+    readonly inV: TInVertex;
+    readonly labels: Set<string>;
+    constructor(id: TId, outV: TOutVertex, label: TLabel | string[], inV: TInVertex, properties?: Property[] | null, labels?: string[]);
+    toString(): string;
+}
+export declare class VertexProperty<TLabel extends string = string, TValue = any, TProperties extends Record<string, any> | null | undefined = Record<string, any>, TId = any> extends Element<TLabel, TId> {
+    readonly value: TValue;
+    readonly key: string;
+    constructor(id: TId, label: TLabel, value: TValue, properties?: Property[] | null);
+    toString(): string;
+}
+export type VertexProperties<TLabel extends string = string, TValue = any, TProperties extends Record<string, any> = Record<string, any>, TId = any> = [VertexProperty<TLabel, TValue, TProperties, TId>, ...Array<VertexProperty<TLabel, TValue, TProperties, TId>>];
+export declare class Property<T = any> {
+    readonly key: string;
+    readonly value: T;
+    constructor(key: string, value: T);
+    toString(): string;
+    equals(other: any): boolean;
+}
+/**
+ * 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.
+ */
+export declare class Tree {
+    #private;
+    constructor(...rootValues: any[]);
+    /**
+     * Locates the entry whose key is structurally equal to the given key.
+     * @returns the matching entry, or undefined if none exists.
+     */
+    private _findEntry;
+    /**
+     * Returns the keys at the root of this tree.
+     */
+    rootNodes(): any[];
+    /**
+     * Returns the child subtree for the given key.
+     * @throws {Error} if no child exists for the given key.
+     */
+    childAt(key: any): Tree;
+    /**
+     * Returns true if the given key is an immediate child of this tree.
+     */
+    hasChild(key: any): boolean;
+    /**
+     * Returns true if the given value appears as a key anywhere in this tree (recursive).
+     */
+    contains(value: any): boolean;
+    /**
+     * Recursively searches the tree for the first subtree rooted at key.
+     * @returns the matching subtree, or undefined if absent.
+     */
+    findSubtree(key: any): Tree | undefined;
+    /**
+     * Returns the existing child for key, or inserts and returns a new empty Tree if absent.
+     */
+    getOrCreateChild(key: any): Tree;
+    /**
+     * Returns true if this tree has no children. An empty tree is considered a leaf.
+     */
+    isLeaf(): boolean;
+    /**
+     * Returns the total number of nodes (keys) in the tree, counted recursively.
+     */
+    nodeCount(): number;
+    /**
+     * 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: number): any[];
+    /**
+     * 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: number): Tree[];
+    /**
+     * Returns all keys whose subtrees are leaves.
+     */
+    getLeafNodes(): any[];
+    private _collectLeafKeys;
+    /**
+     * Returns single-key trees representing each leaf key in this tree, preserving the original
+     * key-to-empty-subtree mapping.
+     */
+    getLeafTrees(): Tree[];
+    private _collectLeafTrees;
+    /**
+     * 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: Tree): void;
+    /**
+     * Splits this tree into one tree per root key. If the tree has a single root, returns a singleton list
+     * containing this tree.
+     */
+    splitParents(): Tree[];
+    /**
+     * 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(): string;
+    private _prettyPrint;
+    /**
+     * 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: any): boolean;
+    toString(): string;
+}
+/**
+ * Represents a walk through a graph as defined by a traversal.
+ */
+export declare class Path {
+    readonly labels: string[][];
+    readonly objects: any[];
+    constructor(labels: string[][], objects: any[]);
+    toString(): string;
+    equals(other: any): any;
+}
+/**
+ * Represents a composite Provider Defined Type (PDT).
+ */
+export declare class CompositePDT {
+    readonly name: string;
+    readonly fields: Readonly<Record<string, any>>;
+    constructor(name: string, fields?: Record<string, any>);
+    toString(): string;
+}
+/**
+ * Represents a primitive Provider Defined Type (PDT).
+ */
+export declare class PrimitivePDT {
+    readonly name: string;
+    readonly value: string;
+    constructor(name: string, value: string);
+    toString(): string;
+}
+export {};

package/build/esm/structure/graph.js

@@ -0,0 +1,488 @@
+/*
+ *  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.
+ */
+/**
+ * @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.
+ */
+export class Graph {
+    vertices;
+    edges;
+    constructor() {
+        this.vertices = new Map();
+        this.edges = new Map();
+    }
+    toString() {
+        return `graph[vertices:${this.vertices.size} edges:${this.edges.size}]`;
+    }
+}
+class Element {
+    id;
+    label;
+    properties;
+    // properties are stored as list of property objects
+    constructor(id, label, properties = []) {
+        this.id = id;
+        this.label = label;
+        this.properties = properties;
+        this.properties = properties ?? [];
+    }
+    /**
+     * Compares this instance to another and determines if they can be considered as equal.
+     */
+    equals(other) {
+        return other instanceof Element && this.id === other.id;
+    }
+}
+export class Vertex extends Element {
+    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}]`;
+    }
+}
+export class Edge extends Element {
+    outV;
+    inV;
+    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.inV = inV;
+        this.labels = new Set(resolvedLabels);
+    }
+    toString() {
+        const outVId = this.outV ? this.outV.id : '?';
+        const inVId = this.inV ? this.inV.id : '?';
+        return `e[${this.id}][${outVId}-${this.label}->${inVId}]`;
+    }
+}
+export class VertexProperty extends Element {
+    value;
+    key;
+    constructor(id, label, value, properties = []) {
+        super(id, label, properties ?? []);
+        this.value = value;
+        this.value = value;
+        this.key = this.label;
+    }
+    toString() {
+        return `vp[${this.label}->${summarize(this.value)}]`;
+    }
+}
+export class Property {
+    key;
+    value;
+    constructor(key, value) {
+        this.key = key;
+        this.value = value;
+    }
+    toString() {
+        return `p[${this.key}->${summarize(this.value)}]`;
+    }
+    equals(other) {
+        return other instanceof Property && this.key === other.key && this.value === other.value;
+    }
+}
+/**
+ * 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.
+ */
+export 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(', ')}}`;
+    }
+}
+/**
+ * Represents a walk through a graph as defined by a traversal.
+ */
+export class Path {
+    labels;
+    objects;
+    constructor(labels, objects) {
+        this.labels = labels;
+        this.objects = objects;
+    }
+    toString() {
+        return `path[${(this.objects || []).join(', ')}]`;
+    }
+    equals(other) {
+        if (!(other instanceof Path)) {
+            return false;
+        }
+        if (other === this) {
+            return true;
+        }
+        return areEqual(this.objects, other.objects) && areEqual(this.labels, other.labels);
+    }
+}
+/**
+ * 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;
+    }
+    if (typeof obj1.equals === 'function') {
+        return obj1.equals(obj2);
+    }
+    if (Array.isArray(obj1) && Array.isArray(obj2)) {
+        if (obj1.length !== obj2.length) {
+            return false;
+        }
+        for (let i = 0; i < obj1.length; i++) {
+            if (!areEqual(obj1[i], obj2[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * Represents a composite Provider Defined Type (PDT).
+ */
+export 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)}`;
+    }
+}
+/**
+ * Represents a primitive Provider Defined Type (PDT).
+ */
+export 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}]`;
+    }
+}
+function summarize(value) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    const strValue = value.toString();
+    return strValue.length > 20 ? strValue.substr(0, 20) : strValue;
+}