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

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

@@ -1,34 +1,70 @@
+import Client from '../driver/client.js';
 import { GraphTraversalSource } from './graph-traversal.js';
 /**
- * A controller for a remote transaction that is constructed from <code>g.tx()</code>. Calling <code>begin()</code>
- * on this object will produce a new <code>GraphTraversalSource</code> that is bound to a remote transaction over which
- * multiple traversals may be executed in that context. Calling <code>commit()</code> or <code>rollback()</code> will
- * then close the transaction and thus, the session. This feature only works with transaction enabled graphs.
+ * 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 readonly g;
-    private _sessionBasedConnection?;
-    constructor(g: GraphTraversalSource);
+    #private;
+    private _transactionId?;
+    private _isOpen;
+    private _failed;
+    private readonly _client;
     /**
-     * Spawns a <code>GraphTraversalSource</code> that is bound to a remote session which enables a transaction.
-     * @returns {GraphTraversalSource}
+     * Creates a Transaction. Accepts a Client which provides the connection
+     * and traversal source for all transaction requests.
      */
-    begin(): GraphTraversalSource;
+    constructor(client: Client);
     /**
-     * @returns {Promise}
+     * 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>;
     /**
-     * @returns {Promise}
+     * Rolls back the transaction.
+     * @returns {Promise<void>}
      */
     rollback(): Promise<void>;
     /**
      * Returns true if transaction is open.
-     * @returns {Boolean}
      */
     get isOpen(): boolean;
     /**
-     * @returns {Promise}
+     * 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

@@ -16,50 +16,149 @@
  *  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';
 /**
- * A controller for a remote transaction that is constructed from <code>g.tx()</code>. Calling <code>begin()</code>
- * on this object will produce a new <code>GraphTraversalSource</code> that is bound to a remote transaction over which
- * multiple traversals may be executed in that context. Calling <code>commit()</code> or <code>rollback()</code> will
- * then close the transaction and thus, the session. This feature only works with transaction enabled graphs.
+ * 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 {
-    g;
-    _sessionBasedConnection = undefined;
-    constructor(g) {
-        this.g = g;
+    _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 <code>GraphTraversalSource</code> that is bound to a remote session which enables a transaction.
-     * @returns {GraphTraversalSource}
+     * 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() {
-        throw new Error("Transactions are not yet implemented");
+    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;
     }
     /**
-     * @returns {Promise}
+     * Commits the transaction.
+     * @returns {Promise<void>}
      */
-    commit() {
-        throw new Error("Transactions are not yet implemented");
+    async commit() {
+        await this.#closeTransaction('g.tx().commit()');
     }
     /**
-     * @returns {Promise}
+     * Rolls back the transaction.
+     * @returns {Promise<void>}
      */
-    rollback() {
-        throw new Error("Transactions are not yet implemented");
+    async rollback() {
+        await this.#closeTransaction('g.tx().rollback()');
     }
     /**
      * Returns true if transaction is open.
-     * @returns {Boolean}
      */
     get isOpen() {
-        return this._sessionBasedConnection?.isOpen ?? false;
+        return this._isOpen;
     }
     /**
-     * @returns {Promise}
+     * 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._sessionBasedConnection) {
-            this._sessionBasedConnection.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);
     }
 }

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

@@ -13,13 +13,29 @@ export declare class Traversal {
     graph: Graph | null;
     traversalStrategies: TraversalStrategies | null;
     gremlinLang: GremlinLang;
-    results: any[] | null;
+    /** @internal Async results stream set by RemoteStrategy */
+    _resultsStream: AsyncGenerator<any> | null;
+    /** @internal Buffered traverser for bulk expansion and hasNext peek */
+    private _currentTraverser;
+    /** Trailing response status from the server, populated after iteration completes. */
+    private _status;
     sideEffects?: any;
     private _traversalStrategiesPromise;
-    private _resultsIteratorIndex;
+    private _done;
     constructor(graph: Graph | null, traversalStrategies: TraversalStrategies | null, gremlinLang?: GremlinLang);
     /** @returns {GremlinLang} */
     getGremlinLang(): GremlinLang;
+    /**
+     * Gets the trailing response status from the server.
+     * Available after the traversal has been fully iterated (via toList(), iterate(), or manual iteration).
+     * Returns null if the traversal has not completed.
+     * @returns {{ code: number, message: string | null, exception: string | null } | null}
+     */
+    getStatus(): {
+        code: number;
+        message: string | null;
+        exception: string | null;
+    } | null;
     /**
      * Returns an Array containing the traverser objects.
      * @returns {Promise.<Array>}
@@ -36,16 +52,27 @@ export declare class Traversal {
      */
     iterate(): Promise<void>;
     /**
-     * Async iterator method implementation.
-     * Returns a promise containing an iterator item.
-     * @returns {Promise.<{value, done}>}
+     * Returns the next result from the traversal.
+     *
+     * When called without an argument, returns a Promise that resolves to an iterator
+     * item ({value, done}), following the async iterator protocol.
+     *
+     * When called with an amount, returns a Promise that resolves to an Array containing
+     * up to {@code amount} result values. The Array form is always used when an amount is
+     * supplied, including {@code next(1)}, which resolves to an Array of one value rather
+     * than a bare value, matching the behavior of next(n) in the other Gremlin language
+     * variants. If fewer results remain, the Array contains only those that remain, and an
+     * amount of zero or less yields an empty Array.
+     * @param {Number} [amount] The number of results to retrieve.
+     * @returns {Promise.<{value, done}>|Promise.<Array>}
      */
     next<T>(): Promise<IteratorResult<T, null>>;
+    next<T>(amount: number): Promise<T[]>;
     /**
-     * Synchronous iterator of traversers including
+     * Pull the next value, handling Traverser bulk expansion.
      * @private
      */
-    _getNext<T>(): IteratorResult<T, null>;
+    _getNext<T>(): Promise<IteratorResult<T, null>>;
     _applyStrategies(): Promise<void>;
     /**
      * Returns step instructions during JSON serialization
@@ -81,8 +108,8 @@ export declare class P<T1 = any, T2 = any> {
     toString(): string;
     and(arg?: any): P<this, any>;
     or(arg?: any): P<this, any>;
-    static within(...args: any[]): P<any[], null>;
-    static without(...args: any[]): P<any[], null>;
+    static within(...args: any[]): P<any, null>;
+    static without(...args: any[]): P<any, null>;
     /** @param {...Object} args */
     static between(...args: any[]): any;
     /** @param {...Object} args */
@@ -173,7 +200,6 @@ export declare const dt: Record<string, EnumValue>;
 export declare const gType: {
     [key: string]: any;
 };
-export declare const graphSONVersion: Record<string, EnumValue>;
 export declare const gryoVersion: Record<string, EnumValue>;
 export declare const merge: Record<string, EnumValue>;
 export declare const operator: Record<string, EnumValue>;

package/build/esm/process/traversal.js

@@ -23,10 +23,15 @@ export class Traversal {
     graph;
     traversalStrategies;
     gremlinLang;
-    results = null;
+    /** @internal Async results stream set by RemoteStrategy */
+    _resultsStream = null;
+    /** @internal Buffered traverser for bulk expansion and hasNext peek */
+    _currentTraverser = null;
+    /** Trailing response status from the server, populated after iteration completes. */
+    _status = null;
     sideEffects = null;
     _traversalStrategiesPromise = null;
-    _resultsIteratorIndex = 0;
+    _done = false;
     constructor(graph, traversalStrategies, gremlinLang = new GremlinLang()) {
         this.graph = graph;
         this.traversalStrategies = traversalStrategies;
@@ -42,75 +47,122 @@ export class Traversal {
     getGremlinLang() {
         return this.gremlinLang;
     }
+    /**
+     * Gets the trailing response status from the server.
+     * Available after the traversal has been fully iterated (via toList(), iterate(), or manual iteration).
+     * Returns null if the traversal has not completed.
+     * @returns {{ code: number, message: string | null, exception: string | null } | null}
+     */
+    getStatus() {
+        return this._status;
+    }
     /**
      * Returns an Array containing the traverser objects.
      * @returns {Promise.<Array>}
      */
-    toList() {
-        return this._applyStrategies().then(() => {
-            const result = [];
-            let it;
-            while ((it = this._getNext()) && !it.done) {
-                result.push(it.value);
-            }
-            return result;
-        });
+    async toList() {
+        await this._applyStrategies();
+        const result = [];
+        while (true) {
+            const it = await this._getNext();
+            if (it.done)
+                break;
+            result.push(it.value);
+        }
+        return result;
     }
     /**
      * Determines if there are any more items to iterate from the traversal.
      * @returns {Promise.<boolean>}
      */
-    hasNext() {
-        return this._applyStrategies().then(() => {
-            if (!this.results || this.results.length <= 0 || this._resultsIteratorIndex >= this.results.length) {
+    async hasNext() {
+        await this._applyStrategies();
+        // If we have a current traverser with remaining bulk, there's more
+        if (this._currentTraverser && this._currentTraverser.bulk > 0) {
+            return true;
+        }
+        if (this._done)
+            return false;
+        // Try to pull the next item from the source to check
+        if (this._resultsStream) {
+            const { value, done } = await this._resultsStream.next();
+            if (done) {
+                this._done = true;
                 return false;
             }
-            if (this.results[this._resultsIteratorIndex] instanceof Traverser) {
-                return this.results[this._resultsIteratorIndex].bulk > 0 || this._resultsIteratorIndex + 1 < this.results.length;
-            }
-            else {
-                return true;
-            }
-        });
+            // Buffer it as a traverser for the next _getNext() call
+            this._currentTraverser = value instanceof Traverser ? value : new Traverser(value, 1);
+            return true;
+        }
+        return false;
     }
     /**
      * Iterates all Traverser instances in the traversal.
      * @returns {Promise}
      */
-    iterate() {
+    async iterate() {
         this.gremlinLang.addStep('discard');
-        return this._applyStrategies().then(() => {
-            let it;
-            while ((it = this._getNext()) && !it.done) {
-                //
-            }
-        });
+        await this._applyStrategies();
+        while (true) {
+            const it = await this._getNext();
+            if (it.done)
+                break;
+        }
     }
-    /**
-     * Async iterator method implementation.
-     * Returns a promise containing an iterator item.
-     * @returns {Promise.<{value, done}>}
-     */
-    next() {
-        return this._applyStrategies().then(() => this._getNext());
+    async next(amount) {
+        await this._applyStrategies();
+        if (amount === undefined || amount === null) {
+            return this._getNext();
+        }
+        const result = [];
+        for (let i = 0; i < amount; i++) {
+            const it = await this._getNext();
+            if (it.done) {
+                break;
+            }
+            result.push(it.value);
+        }
+        return result;
     }
     /**
-     * Synchronous iterator of traversers including
+     * Pull the next value, handling Traverser bulk expansion.
      * @private
      */
-    _getNext() {
-        while (this.results && this._resultsIteratorIndex < this.results.length) {
-            const next = this.results[this._resultsIteratorIndex];
-            if (next instanceof Traverser) {
-                if (next.bulk > 0) {
-                    next.bulk--;
-                    return { value: next.object, done: false };
+    async _getNext() {
+        // Drain current traverser's bulk first
+        if (this._currentTraverser) {
+            if (this._currentTraverser.bulk > 0) {
+                this._currentTraverser.bulk--;
+                const value = this._currentTraverser.object;
+                if (this._currentTraverser.bulk <= 0) {
+                    this._currentTraverser = null;
                 }
+                return { value, done: false };
             }
-            this._resultsIteratorIndex++;
-            if (!(next instanceof Traverser)) {
-                return { value: next, done: false };
+            this._currentTraverser = null;
+        }
+        // Streaming source path
+        if (this._resultsStream) {
+            if (this._done)
+                return itemDone;
+            const { value, done } = await this._resultsStream.next();
+            if (done) {
+                this._done = true;
+                this._status = value ?? null;
+                return itemDone;
             }
+            if (value instanceof Traverser) {
+                if (value.bulk > 0) {
+                    value.bulk--;
+                    const result = value.object;
+                    if (value.bulk > 0) {
+                        this._currentTraverser = value;
+                    }
+                    return { value: result, done: false };
+                }
+                return itemDone;
+            }
+            return { value, done: false };
         }
         return itemDone;
     }
@@ -255,12 +307,18 @@ export class P {
         if (args.length === 1 && Array.isArray(args[0])) {
             return new P('within', args[0], null);
         }
+        if (args.length === 1 && args[0] != null && typeof args[0].getGremlinLang === 'function') {
+            return new P('within', args[0], null);
+        }
         return new P('within', args, null);
     }
     static without(...args) {
         if (args.length === 1 && Array.isArray(args[0])) {
             return new P('without', args[0], null);
         }
+        if (args.length === 1 && args[0] != null && typeof args[0].getGremlinLang === 'function') {
+            return new P('without', args[0], null);
+        }
         return new P('without', args, null);
     }
     /** @param {...Object} args */
@@ -457,7 +515,6 @@ export const column = toEnum('Column', 'keys values');
 export const direction = toDirectionEnum('Direction', 'BOTH IN OUT from_ to');
 export const dt = toEnum('DT', 'second minute hour day');
 export const gType = toGTypeEnum('GType', 'bigDecimal bigInt binary boolean byte char datetime double duration edge float graph int list long map null number path property set short string tree uuid vertex vproperty');
-export const graphSONVersion = toEnum('GraphSONVersion', 'V1_0 V2_0 V3_0');
 export const gryoVersion = toEnum('GryoVersion', 'V1_0 V3_0');
 export const merge = toEnum('Merge', 'onCreate onMatch outV inV');
 export const operator = toEnum('Operator', 'addAll and assign div max min minus mult or sum sumLong');

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

@@ -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;
+}