gremlin 3.8.1 → 4.0.0-beta.3

package/build/esm/process/gremlin-lang.d.ts

@@ -0,0 +1,20 @@
+import { OptionsStrategy } from './traversal-strategy.js';
+import { PDTRegistry } from '../structure/PDTRegistry.js';
+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/build/esm/process/gremlin-lang.js

@@ -0,0 +1,305 @@
+/*
+ *  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.
+ */
+import { P, TextP, EnumValue } from './traversal.js';
+import { OptionsStrategy, TraversalStrategy } from './traversal-strategy.js';
+import { Long, Int, Float, Double, Short, Byte, INT32_MIN, INT32_MAX } from '../utils.js';
+import { Vertex, CompositePDT, PrimitivePDT } from '../structure/graph.js';
+import { GValue } from './gvalue.js';
+import { isDeepStrictEqual } from 'node:util';
+import { Buffer } from 'buffer';
+const PARAM_NAME_PATTERN = /^[\p{L}_$][\p{L}\p{Nd}_$]*$/u;
+export default 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 Long) {
+            return String(arg.value) + 'L';
+        }
+        if (arg instanceof Float) {
+            return GremlinLang._fpAsString(arg.value, 'F');
+        }
+        if (arg instanceof Double) {
+            return GremlinLang._fpAsString(arg.value, 'D');
+        }
+        if (arg instanceof Short) {
+            return String(arg.value) + 'S';
+        }
+        if (arg instanceof Byte) {
+            return String(arg.value) + 'B';
+        }
+        if (arg instanceof 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 >= INT32_MIN && arg <= 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) {
+            const key = arg.name;
+            if (!PARAM_NAME_PATTERN.test(key)) {
+                throw new Error(`Invalid parameter name [${key}].`);
+            }
+            if (this.parameters.has(key)) {
+                if (!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 P || arg instanceof TextP) {
+            return this._predicateAsString(arg);
+        }
+        if (arg instanceof EnumValue) {
+            return arg.toString();
+        }
+        if (arg instanceof TraversalStrategy && !(arg instanceof 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 TraversalStrategy) {
+            return arg.name;
+        }
+        if (arg instanceof 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 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 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.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 PrimitivePDT(primitiveEntry.typeName, value));
+            }
+            const entry = this.pdtRegistry.getAdapterByClass(arg.constructor);
+            if (entry) {
+                const fields = entry.serialize(arg);
+                return this._argAsString(new 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 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(',') + ']';
+    }
+}

package/build/esm/process/gvalue.d.ts

@@ -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/{lib/driver/auth/authenticator.js → build/esm/process/gvalue.js}

@@ -16,23 +16,23 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-
-'use strict';
-
-/** @abstract */
-class Authenticator {
-  constructor(options) {
-    this._options = options;
-  }
-
-  /**
-   * @abstract
-   * Evaluates the challenge from the server and returns appropriate response.
-   * @param {String} challenge Challenge string presented by the server.
-   */
-  evaluateChallenge(challenge) {
-    throw new Error('evaluateChallenge should be implemented');
-  }
+export 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 = Authenticator;

package/build/esm/process/transaction.d.ts

@@ -0,0 +1,70 @@
+import Client from '../driver/client.js';
+import { GraphTraversalSource } from './graph-traversal.js';
+/**
+ * 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>;
+}

package/build/esm/process/transaction.js

@@ -0,0 +1,164 @@
+/*
+ *  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.
+ */
+import { RemoteStrategy } from '../driver/remote-connection.js';
+import DriverRemoteConnection from '../driver/driver-remote-connection.js';
+import GremlinLang from './gremlin-lang.js';
+import { GraphTraversalSource } from './graph-traversal.js';
+import { TraversalStrategies } from './traversal-strategy.js';
+/**
+ * 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 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 DriverRemoteConnection(this._client.url, this._client.options, this._transactionId);
+        const strategies = new TraversalStrategies();
+        strategies.addStrategy(new RemoteStrategy(txConnection));
+        const gtx = new GraphTraversalSource(null, strategies, new GremlinLang());
+        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);
+    }
+}