gremlin 3.8.1 → 4.0.0-beta.3

package/build/cjs/process/gremlin-lang.cjs

@@ -0,0 +1,308 @@
+"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 });
+const traversal_js_1 = require("./traversal.cjs");
+const traversal_strategy_js_1 = require("./traversal-strategy.cjs");
+const utils_js_1 = require("../utils.cjs");
+const graph_js_1 = require("../structure/graph.cjs");
+const gvalue_js_1 = require("./gvalue.cjs");
+const node_util_1 = require("node:util");
+const buffer_1 = require("node:buffer");
+const PARAM_NAME_PATTERN = /^[\p{L}_$][\p{L}\p{Nd}_$]*$/u;
+class GremlinLang {
+    gremlin = '';
+    optionsStrategies = [];
+    parameters = new Map();
+    pdtRegistry = null;
+    constructor(toClone) {
+        if (toClone) {
+            this.gremlin = toClone.gremlin;
+            this.optionsStrategies = [...toClone.optionsStrategies];
+            this.parameters = new Map(toClone.parameters);
+            this.pdtRegistry = toClone.pdtRegistry;
+        }
+    }
+    getOptionsStrategies() {
+        return this.optionsStrategies;
+    }
+    appendGremlin(text) {
+        this.gremlin += text;
+    }
+    getParameters() {
+        return this.parameters;
+    }
+    _predicateAsString(p) {
+        if (p.operator === 'and' || p.operator === 'or') {
+            return `${this._predicateAsString(p.value)}.${p.operator}(${this._predicateAsString(p.other)})`;
+        }
+        let result = p.operator + '(';
+        if (Array.isArray(p.value)) {
+            // If all elements are traversals, serialize as comma-separated args (no brackets)
+            // This matches the server grammar: within(trav1, trav2) via genericArgumentVarargs
+            const allTraversals = p.value.length > 0 && p.value.every((v) => v != null && typeof v.getGremlinLang === 'function');
+            if (allTraversals) {
+                result += p.value.map((v) => this._argAsString(v)).join(',');
+            }
+            else {
+                result += '[' + p.value.map((v) => this._argAsString(v)).join(',') + ']';
+            }
+        }
+        else {
+            result += this._argAsString(p.value);
+            if (p.other !== undefined && p.other !== null) {
+                result += ',' + this._argAsString(p.other);
+            }
+        }
+        result += ')';
+        return result;
+    }
+    _argAsString(arg) {
+        if (arg === null || arg === undefined)
+            return 'null';
+        if (typeof arg === 'boolean')
+            return arg ? 'true' : 'false';
+        if (arg instanceof utils_js_1.Long) {
+            return String(arg.value) + 'L';
+        }
+        if (arg instanceof utils_js_1.Float) {
+            return GremlinLang._fpAsString(arg.value, 'F');
+        }
+        if (arg instanceof utils_js_1.Double) {
+            return GremlinLang._fpAsString(arg.value, 'D');
+        }
+        if (arg instanceof utils_js_1.Short) {
+            return String(arg.value) + 'S';
+        }
+        if (arg instanceof utils_js_1.Byte) {
+            return String(arg.value) + 'B';
+        }
+        if (arg instanceof utils_js_1.Int) {
+            return String(arg.value);
+        }
+        if (typeof arg === 'bigint') {
+            return String(arg) + 'N';
+        }
+        if (typeof arg === 'number') {
+            if (Number.isNaN(arg))
+                return 'NaN';
+            if (arg === Infinity)
+                return '+Infinity';
+            if (arg === -Infinity)
+                return '-Infinity';
+            if (!Number.isInteger(arg))
+                return String(arg) + 'D';
+            if (arg >= utils_js_1.INT32_MIN && arg <= utils_js_1.INT32_MAX)
+                return String(arg);
+            // Outside safe integer range, values have lost precision and may exceed Java Long - emit as Double.
+            if (arg > Number.MAX_SAFE_INTEGER || arg < -Number.MAX_SAFE_INTEGER)
+                return String(arg) + 'D';
+            return String(arg) + 'L';
+        }
+        if (arg instanceof Date) {
+            const iso = arg.toISOString();
+            return `datetime("${iso}")`;
+        }
+        if (typeof arg === 'string') {
+            // JSON.stringify handles all special character escaping in one call.
+            // Strip the outer double quotes and re-wrap in single quotes for Gremlin.
+            const escaped = JSON.stringify(arg).slice(1, -1).replace(/'/g, "\\'");
+            return `'${escaped}'`;
+        }
+        if (arg instanceof gvalue_js_1.GValue) {
+            const key = arg.name;
+            if (!PARAM_NAME_PATTERN.test(key)) {
+                throw new Error(`Invalid parameter name [${key}].`);
+            }
+            if (this.parameters.has(key)) {
+                if (!(0, node_util_1.isDeepStrictEqual)(this.parameters.get(key), arg.value)) {
+                    throw new Error(`Parameter with name ${key} already exists.`);
+                }
+            }
+            else {
+                this.parameters.set(key, arg.value);
+            }
+            return key;
+        }
+        if (arg instanceof traversal_js_1.P || arg instanceof traversal_js_1.TextP) {
+            return this._predicateAsString(arg);
+        }
+        if (arg instanceof traversal_js_1.EnumValue) {
+            return arg.toString();
+        }
+        if (arg instanceof traversal_strategy_js_1.TraversalStrategy && !(arg instanceof traversal_strategy_js_1.OptionsStrategy)) {
+            const simpleName = arg.strategyName;
+            const configEntries = Object.entries(arg.configuration);
+            if (configEntries.length === 0) {
+                return simpleName;
+            }
+            const configStr = configEntries.map(([k, v]) => `${k}:${this._argAsString(v)}`).join(',');
+            return `new ${simpleName}(${configStr})`;
+        }
+        if (typeof arg === 'function' && arg.prototype instanceof traversal_strategy_js_1.TraversalStrategy) {
+            return arg.name;
+        }
+        if (arg instanceof graph_js_1.PrimitivePDT) {
+            // PDT literals use double-quoted strings (consistent with the composite PDT form below);
+            // JSON.stringify handles special-character escaping, then the outer quotes are stripped.
+            const escapedName = JSON.stringify(arg.name).slice(1, -1);
+            const escapedValue = JSON.stringify(arg.value).slice(1, -1);
+            return `PDT("${escapedName}","${escapedValue}")`;
+        }
+        if (arg instanceof graph_js_1.CompositePDT) {
+            const fields = arg.fields;
+            const keys = Object.keys(fields);
+            const escapedName = JSON.stringify(arg.name).slice(1, -1);
+            if (keys.length === 0)
+                return `PDT("${escapedName}",[:])`;
+            const entries = keys.map(k => `${this._argAsString(k)}:${this._argAsString(fields[k])}`);
+            return `PDT("${escapedName}",[${entries.join(',')}])`;
+        }
+        if (arg instanceof graph_js_1.Vertex) {
+            return this._argAsString(arg.id);
+        }
+        if (arg instanceof GremlinLang) {
+            // Merge the child's parameters so GValue bindings nested inside a child
+            // traversal are still sent to the server alongside the rendered query.
+            arg.parameters.forEach((v, k) => this.parameters.set(k, v));
+            return arg.getGremlin('__');
+        }
+        if (typeof arg.getGremlinLang === 'function') {
+            // This is a Traversal - render as anonymous traversal
+            if (arg.graph != null) {
+                throw new Error('Child traversal must be anonymous - use __ not g');
+            }
+            const childLang = arg.getGremlinLang();
+            // Merge the child's parameters so GValue bindings nested inside a child
+            // traversal are still sent to the server alongside the rendered query.
+            childLang.parameters.forEach((v, k) => this.parameters.set(k, v));
+            return childLang.getGremlin('__');
+        }
+        if (arg instanceof Uint8Array) {
+            return `Binary("${buffer_1.Buffer.from(arg.buffer, arg.byteOffset, arg.byteLength).toString('base64')}")`;
+        }
+        if (arg instanceof Set) {
+            const items = [...arg];
+            if (items.length === 0)
+                return '{}';
+            return '{' + items.map(a => this._argAsString(a)).join(',') + '}';
+        }
+        if (arg instanceof Map) {
+            if (arg.size === 0)
+                return '[:]';
+            const entries = [];
+            arg.forEach((v, k) => {
+                const ks = this._argAsString(k);
+                const vs = this._argAsString(v);
+                entries.push(typeof k === 'string' ? `${ks}:${vs}` : `(${ks}):${vs}`);
+            });
+            return '[' + entries.join(',') + ']';
+        }
+        if (Array.isArray(arg)) {
+            return '[' + arg.map(a => this._argAsString(a)).join(',') + ']';
+        }
+        if (typeof arg === 'object' && arg.constructor === Object) {
+            const entries = Object.entries(arg);
+            if (entries.length === 0)
+                return '[:]';
+            return '[' + entries.map(([k, v]) => `${this._argAsString(k)}:${this._argAsString(v)}`).join(',') + ']';
+        }
+        // Registry-based dehydration
+        if (this.pdtRegistry && typeof arg === 'object' && arg.constructor) {
+            const primitiveEntry = this.pdtRegistry.getPrimitiveAdapterByClass(arg.constructor);
+            if (primitiveEntry) {
+                const value = primitiveEntry.toValue(arg);
+                return this._argAsString(new graph_js_1.PrimitivePDT(primitiveEntry.typeName, value));
+            }
+            const entry = this.pdtRegistry.getAdapterByClass(arg.constructor);
+            if (entry) {
+                const fields = entry.serialize(arg);
+                return this._argAsString(new graph_js_1.CompositePDT(entry.typeName, fields));
+            }
+        }
+        throw new TypeError(`GremlinLang contains at least one type [${arg?.constructor?.name ?? typeof arg}] that cannot be represented as text.`);
+    }
+    addStep(name, args) {
+        const argsStr = args?.length ? args.map(a => this._argAsString(a)).join(',') : '';
+        this.gremlin += `.${name}(${argsStr})`;
+        return this;
+    }
+    addSource(name, args) {
+        if (name === 'CardinalityValueTraversal' && args) {
+            const card = args[0];
+            this.gremlin += `Cardinality.${card.elementName}(${this._argAsString(args[1])})`;
+            return this;
+        }
+        if (name === 'withStrategies' && args) {
+            const nonOptionsStrategies = [];
+            for (const strategy of args) {
+                if (strategy instanceof traversal_strategy_js_1.OptionsStrategy) {
+                    this.optionsStrategies.push(strategy);
+                    // Render multilabel/singlelabel in gremlin text (temporary until these options are removed)
+                    if (strategy.configuration['multilabel'] !== undefined) {
+                        this.gremlin += '.with("multilabel")';
+                    }
+                    if (strategy.configuration['singlelabel'] !== undefined) {
+                        this.gremlin += '.with("singlelabel")';
+                    }
+                }
+                else {
+                    nonOptionsStrategies.push(strategy);
+                }
+            }
+            if (nonOptionsStrategies.length > 0) {
+                const argsStr = nonOptionsStrategies.map(a => this._argAsString(a)).join(',');
+                this.gremlin += `.withStrategies(${argsStr})`;
+            }
+            return this;
+        }
+        const argsStr = args?.length ? args.map(a => this._argAsString(a)).join(',') : '';
+        this.gremlin += `.${name}(${argsStr})`;
+        return this;
+    }
+    static _fpAsString(v, suffix) {
+        if (v === Infinity)
+            return '+Infinity';
+        if (v === -Infinity)
+            return '-Infinity';
+        if (Number.isNaN(v))
+            return 'NaN';
+        return Number.isInteger(v) ? `${v}.0${suffix}` : `${v}${suffix}`;
+    }
+    getGremlin(prefix = 'g') {
+        if (this.gremlin.length > 0 && this.gremlin[0] !== '.') {
+            return this.gremlin;
+        }
+        return prefix + this.gremlin;
+    }
+    getParametersAsString() {
+        return GremlinLang.convertParametersToString(this.parameters);
+    }
+    static convertParametersToString(params) {
+        if (params == null || params.size === 0)
+            return '[:]';
+        const helper = new GremlinLang();
+        const parts = [];
+        params.forEach((v, k) => {
+            parts.push(`${helper._argAsString(k)}:${helper._argAsString(v)}`);
+        });
+        return '[' + parts.join(',') + ']';
+    }
+}
+exports.default = GremlinLang;

package/build/cjs/process/gremlin-lang.d.cts

@@ -0,0 +1,20 @@
+import { OptionsStrategy } from './traversal-strategy.cjs';
+import { PDTRegistry } from '../structure/PDTRegistry.cjs';
+export default class GremlinLang {
+    private gremlin;
+    private optionsStrategies;
+    private parameters;
+    pdtRegistry: PDTRegistry | null;
+    constructor(toClone?: GremlinLang);
+    getOptionsStrategies(): OptionsStrategy[];
+    appendGremlin(text: string): void;
+    getParameters(): Map<string, any>;
+    private _predicateAsString;
+    private _argAsString;
+    addStep(name: string, args?: any[]): GremlinLang;
+    addSource(name: string, args?: any[]): GremlinLang;
+    private static _fpAsString;
+    getGremlin(prefix?: string): string;
+    getParametersAsString(): string;
+    static convertParametersToString(params: Map<string, any> | null): string;
+}

package/{lib/driver/response-error.js → build/cjs/process/gvalue.cjs}

@@ -1,3 +1,4 @@
+"use strict";
 /*
  *  Licensed to the Apache Software Foundation (ASF) under one
  *  or more contributor license agreements.  See the NOTICE file
@@ -16,32 +17,26 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-
-'use strict';
-
-/**
- * Represents an error obtained from the server.
- */
-class ResponseError extends Error {
-  constructor(message, responseStatus) {
-    super(message);
-    this.name = 'ResponseError';
-
-    /**
-     * Gets the server status code.
-     */
-    this.statusCode = responseStatus.code;
-
-    /**
-     * Gets the server status message.
-     */
-    this.statusMessage = responseStatus.message;
-
-    /**
-     * Gets the server status attributes as a Map (may contain provider specific status information).
-     */
-    this.statusAttributes = responseStatus.attributes || {};
-  }
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GValue = void 0;
+class GValue {
+    name;
+    value;
+    constructor(name, value) {
+        if (value instanceof GValue) {
+            throw new Error('GValues cannot be nested');
+        }
+        if (name == null) {
+            throw new Error('GValue name cannot be null.');
+        }
+        this.name = name;
+        this.value = value;
+    }
+    isNull() {
+        return this.value == null;
+    }
+    toString() {
+        return `${this.name}=${this.value}`;
+    }
 }
-
-module.exports = ResponseError;
+exports.GValue = GValue;

package/build/cjs/process/gvalue.d.cts

@@ -0,0 +1,7 @@
+export declare class GValue<T = any> {
+    readonly name: string;
+    readonly value: T;
+    constructor(name: string, value: T);
+    isNull(): boolean;
+    toString(): string;
+}

package/build/cjs/process/transaction.cjs

@@ -0,0 +1,171 @@
+"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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Transaction = void 0;
+const remote_connection_js_1 = require("../driver/remote-connection.cjs");
+const driver_remote_connection_js_1 = __importDefault(require("../driver/driver-remote-connection.cjs"));
+const gremlin_lang_js_1 = __importDefault(require("./gremlin-lang.cjs"));
+const graph_traversal_js_1 = require("./graph-traversal.cjs");
+const traversal_strategy_js_1 = require("./traversal-strategy.cjs");
+/**
+ * Controls an explicit remote transaction. A thin wrapper around a Client that
+ * adds transaction lifecycle (begin/commit/rollback/close) and attaches a
+ * transactionId to every request.
+ *
+ * Created via Client.transact() or g.tx(). The traversal source (g alias) is
+ * inherited from the Client and cannot be changed.
+ *
+ * Transactions are short-lived and single-use. After commit or rollback, the
+ * transaction ID is invalid and the object cannot be reused.
+ *
+ * Each traversal on the transaction-bound source must be awaited before
+ * submitting the next, to ensure the server receives requests in order.
+ *
+ * This class is NOT thread-safe. Do not share a Transaction across concurrent
+ * async contexts without external synchronization.
+ */
+class Transaction {
+    _transactionId;
+    _isOpen = false;
+    _failed = false;
+    _client;
+    /**
+     * Creates a Transaction. Accepts a Client which provides the connection
+     * and traversal source for all transaction requests.
+     */
+    constructor(client) {
+        if (!client) {
+            throw new Error('Client is required for transactions');
+        }
+        this._client = client;
+    }
+    /**
+     * Spawns a GraphTraversalSource that is bound to a remote transaction.
+     *
+     * begin() is idempotent: calling it while a transaction is already open does not send a
+     * second begin to the server and does not throw - it reuses the existing transaction ID and
+     * returns a source bound to the same transaction. A transaction is single-use, so calling
+     * begin() after it has been closed (commit/rollback/failed begin) throws.
+     * @returns {Promise<GraphTraversalSource>}
+     */
+    async begin() {
+        if (this._failed) {
+            throw new Error('Transaction is closed and cannot be reused; begin a new transaction');
+        }
+        // idempotent: if a transaction is already open, reuse the existing transactionId without
+        // sending a second begin to the server, and return a source bound to the same transaction
+        if (!this._isOpen) {
+            let result;
+            try {
+                result = await this._client.submit('g.tx().begin()', null);
+            }
+            catch (e) {
+                this._failed = true;
+                throw e;
+            }
+            const resultArray = result.toArray();
+            if (!resultArray || resultArray.length === 0) {
+                this._failed = true;
+                throw new Error('Server did not return transaction ID');
+            }
+            const resultMap = resultArray[0];
+            if (!resultMap || !(resultMap instanceof Map) || !resultMap.get('transactionId')) {
+                this._failed = true;
+                throw new Error('Server did not return transaction ID in expected format');
+            }
+            this._transactionId = resultMap.get('transactionId');
+            this._isOpen = true;
+            this._client.trackTransaction(this);
+        }
+        // Create a DriverRemoteConnection bound to this transaction. The DRC
+        // will automatically attach the transactionId to all requests.
+        const txConnection = new driver_remote_connection_js_1.default(this._client.url, this._client.options, this._transactionId);
+        const strategies = new traversal_strategy_js_1.TraversalStrategies();
+        strategies.addStrategy(new remote_connection_js_1.RemoteStrategy(txConnection));
+        const gtx = new graph_traversal_js_1.GraphTraversalSource(null, strategies, new gremlin_lang_js_1.default());
+        gtx._boundTransaction = this;
+        return gtx;
+    }
+    /**
+     * Commits the transaction.
+     * @returns {Promise<void>}
+     */
+    async commit() {
+        await this.#closeTransaction('g.tx().commit()');
+    }
+    /**
+     * Rolls back the transaction.
+     * @returns {Promise<void>}
+     */
+    async rollback() {
+        await this.#closeTransaction('g.tx().rollback()');
+    }
+    /**
+     * Returns true if transaction is open.
+     */
+    get isOpen() {
+        return this._isOpen;
+    }
+    /**
+     * Returns the server-generated transaction ID, or undefined if not yet begun.
+     */
+    get transactionId() {
+        return this._transactionId;
+    }
+    /**
+     * Closes the transaction. Default behavior is rollback: partial work is
+     * discarded rather than accidentally persisted.
+     * @returns {Promise<void>}
+     */
+    async close() {
+        if (this._isOpen) {
+            await this.rollback();
+        }
+    }
+    /**
+     * Submits a gremlin-lang string within this transaction. The transactionId
+     * is automatically attached. Has the same signature as Client.submit().
+     */
+    async submit(gremlin, parameters, requestOptions) {
+        if (!this._isOpen) {
+            throw new Error('Transaction is not open');
+        }
+        const opts = {
+            ...requestOptions,
+            transactionId: this._transactionId,
+        };
+        return this._client.submit(gremlin, parameters || null, opts);
+    }
+    async #closeTransaction(script) {
+        if (!this._isOpen) {
+            throw new Error('Transaction is not open');
+        }
+        await this._client.submit(script, null, {
+            transactionId: this._transactionId
+        });
+        this._isOpen = false;
+        this._failed = true; // Terminal state: transaction cannot be reused
+        this._client.untrackTransaction(this);
+    }
+}
+exports.Transaction = Transaction;

package/build/cjs/process/transaction.d.cts

@@ -0,0 +1,70 @@
+import Client from '../driver/client.cjs';
+import { GraphTraversalSource } from './graph-traversal.cjs';
+/**
+ * Controls an explicit remote transaction. A thin wrapper around a Client that
+ * adds transaction lifecycle (begin/commit/rollback/close) and attaches a
+ * transactionId to every request.
+ *
+ * Created via Client.transact() or g.tx(). The traversal source (g alias) is
+ * inherited from the Client and cannot be changed.
+ *
+ * Transactions are short-lived and single-use. After commit or rollback, the
+ * transaction ID is invalid and the object cannot be reused.
+ *
+ * Each traversal on the transaction-bound source must be awaited before
+ * submitting the next, to ensure the server receives requests in order.
+ *
+ * This class is NOT thread-safe. Do not share a Transaction across concurrent
+ * async contexts without external synchronization.
+ */
+export declare class Transaction {
+    #private;
+    private _transactionId?;
+    private _isOpen;
+    private _failed;
+    private readonly _client;
+    /**
+     * Creates a Transaction. Accepts a Client which provides the connection
+     * and traversal source for all transaction requests.
+     */
+    constructor(client: Client);
+    /**
+     * Spawns a GraphTraversalSource that is bound to a remote transaction.
+     *
+     * begin() is idempotent: calling it while a transaction is already open does not send a
+     * second begin to the server and does not throw - it reuses the existing transaction ID and
+     * returns a source bound to the same transaction. A transaction is single-use, so calling
+     * begin() after it has been closed (commit/rollback/failed begin) throws.
+     * @returns {Promise<GraphTraversalSource>}
+     */
+    begin(): Promise<GraphTraversalSource>;
+    /**
+     * Commits the transaction.
+     * @returns {Promise<void>}
+     */
+    commit(): Promise<void>;
+    /**
+     * Rolls back the transaction.
+     * @returns {Promise<void>}
+     */
+    rollback(): Promise<void>;
+    /**
+     * Returns true if transaction is open.
+     */
+    get isOpen(): boolean;
+    /**
+     * Returns the server-generated transaction ID, or undefined if not yet begun.
+     */
+    get transactionId(): string | undefined;
+    /**
+     * Closes the transaction. Default behavior is rollback: partial work is
+     * discarded rather than accidentally persisted.
+     * @returns {Promise<void>}
+     */
+    close(): Promise<void>;
+    /**
+     * Submits a gremlin-lang string within this transaction. The transactionId
+     * is automatically attached. Has the same signature as Client.submit().
+     */
+    submit(gremlin: string, parameters?: any, requestOptions?: any): Promise<any>;
+}