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

package/build/esm/driver/auth.js

@@ -20,13 +20,15 @@ import { Buffer } from 'buffer';
 export function basic(username, password) {
     return (request) => {
         request.headers['authorization'] = 'Basic ' + Buffer.from(`${username}:${password}`).toString('base64');
-        return request;
     };
 }
 export function sigv4(region, service, credentialsProvider) {
     let signer;
     let resolvedProvider;
     return async (request) => {
+        // Ensure body is serialized to JSON bytes before signing.
+        // serializeBody is idempotent: safe to call even if already serialized.
+        request.serializeBody();
         // Lazy-initialize signer and credentials provider on first use
         if (!signer) {
             const { SignatureV4 } = await import('@smithy/signature-v4');
@@ -47,6 +49,11 @@ export function sigv4(region, service, credentialsProvider) {
             });
         }
         const url = new URL(request.url);
+        // Sign only the Host header; the signer itself adds (and signs) x-amz-date, the payload hash,
+        // and x-amz-security-token for session credentials. The request's own headers (accept,
+        // content-type, ...) are deliberately NOT fed into the signature: the HTTP stack may add or
+        // rewrite transport-managed headers such as accept-encoding after this interceptor runs, so a
+        // signature covering them would no longer match the bytes actually sent.
         const signed = await signer.sign({
             method: request.method,
             protocol: url.protocol,
@@ -54,12 +61,12 @@ export function sigv4(region, service, credentialsProvider) {
             port: url.port ? Number(url.port) : undefined,
             path: url.pathname + url.search,
             headers: {
-                ...request.headers,
                 host: url.host,
             },
             body: request.body,
         });
-        request.headers = signed.headers;
-        return request;
+        // Merge the signed auth headers onto the request; the request's other headers (accept,
+        // content-type, ...) still reach the wire, they are simply not part of the signature.
+        request.headers = { ...request.headers, ...signed.headers };
     };
 }

package/build/esm/driver/client.d.ts

@@ -1,15 +1,16 @@
 import { ConnectionOptions } from './connection.js';
-import { Readable } from 'stream';
+import { Transaction } from '../process/transaction.js';
 export type RequestOptions = {
-    bindings?: any;
+    parameters?: any;
     language?: string;
     accept?: string;
-    evaluationTimeout?: number;
+    timeoutMillis?: number;
     batchSize?: number;
     userAgent?: string;
     materializeProperties?: string;
     bulkResults?: boolean;
     params?: Record<string, any>;
+    transactionId?: string;
 };
 export type ClientOptions = ConnectionOptions & RequestOptions & {
     processor?: string;
@@ -18,13 +19,16 @@ export type ClientOptions = ConnectionOptions & RequestOptions & {
  * A {@link Client} contains methods to send messages to a Gremlin Server.
  */
 export default class Client {
-    private readonly options;
+    #private;
+    readonly url: string;
+    readonly options: ClientOptions;
     private readonly _connection;
     /**
      * Creates a new instance of {@link Client}.
      * @param {String} url The resource uri.
      * @param {ClientOptions} [options] The connection options.
      */
+    private readonly _trackedTransactions;
     constructor(url: string, options?: ClientOptions);
     /**
      * Opens the underlying connection to the Gremlin Server, if it's not already opened.
@@ -37,39 +41,38 @@ export default class Client {
      */
     get isOpen(): boolean;
     /**
-     * Configuration specific to the current request.
-     * @typedef {Object} RequestOptions
-     * @property {any} bindings - The parameter bindings to apply to the script.
-     * @property {String} language - The language of the script to execute. Defaults to 'gremlin-lang'.
-     * @property {String} accept - The MIME type expected in the response.
-     * @property {Boolean} bulkResults - Indicates whether results should be returned in bulk format.
-     * @property {Object} params - Additional parameters to include with the request.
-     * @property {Number} batchSize - The size in which the result of a request is to be 'batched' back to the client.
-     * @property {String} userAgent - The user agent string to send with the request.
-     * @property {Number} evaluationTimeout - The timeout for the evaluation of the request.
-     * @property {String} materializeProperties - Indicates whether element properties should be returned or not.
-     */
-    /**
-     * Send a request to the Gremlin Server.
+     * Send a request to the Gremlin Server and buffer the entire response.
      * @param {string} message The script to send
-     * @param {Object|null} [bindings] The script bindings, if any.
+     * @param {Object|null} [parameters] The query parameters, if any.
      * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-     * @returns {Promise}
-     */ submit(message: string, bindings: any | null, requestOptions?: RequestOptions): Promise<any>;
+     * @returns {Promise<ResultSet>}
+     */
+    submit(message: string, parameters: any | null, requestOptions?: RequestOptions): Promise<any>;
     /**
-     * Send a request to the Gremlin Server and receive a stream for the results.
+     * Send a request to the Gremlin Server and stream results incrementally.
+     * Returns an AsyncGenerator that yields individual result items as they are
+     * deserialized from the response. For bulked responses, yields Traverser objects.
      * @param {string} message The script to send
-     * @param {Object} [bindings] The script bindings, if any.
+     * @param {Object|null} [parameters] The query parameters, if any.
      * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-     * @returns {ReadableStream}
+     * @returns {AsyncGenerator<any>}
      */
-    stream(message: string, bindings: any, requestOptions?: RequestOptions): Readable;
+    stream(message: string, parameters: any | null, requestOptions?: RequestOptions): AsyncGenerator<any>;
     /**
      * Closes the underlying connection
-     * send session close request before connection close if session mode
      * @returns {Promise}
      */
     close(): Promise<void>;
+    trackTransaction(tx: any): void;
+    untrackTransaction(tx: any): void;
+    /**
+     * Creates a new Transaction for executing operations within an explicit transaction.
+     * Transactions are short-lived and single-use. After commit or rollback,
+     * create a new Transaction for the next unit of work.
+     * The traversal source (g alias) is inherited from this Client.
+     * @returns {Transaction}
+     */
+    transact(): Transaction;
     /**
      * Adds an event listener to the connection
      * @param {String} event The event name that you want to listen to.
@@ -77,7 +80,7 @@ export default class Client {
      */
     addListener(event: string, handler: (...args: any[]) => unknown): void;
     /**
-     * Removes a previowsly added event listener to the connection
+     * Removes a previously added event listener to the connection
      * @param {String} event The event name that you want to listen to.
      * @param {Function} handler The event handler to be removed.
      */

package/build/esm/driver/client.js

@@ -18,10 +18,12 @@
  */
 import Connection from './connection.js';
 import { RequestMessage } from "./request-message.js";
+import { Transaction } from '../process/transaction.js';
 /**
  * A {@link Client} contains methods to send messages to a Gremlin Server.
  */
 export default class Client {
+    url;
     options;
     _connection;
     /**
@@ -29,7 +31,12 @@ export default class Client {
      * @param {String} url The resource uri.
      * @param {ClientOptions} [options] The connection options.
      */
+    // Tracks open transactions for cascade rollback on close. JS Set iteration
+    // is safe during concurrent modification (deleting the current element during
+    // for-of is spec-guaranteed to not affect remaining iterations).
+    _trackedTransactions = new Set();
     constructor(url, options = {}) {
+        this.url = url;
         this.options = options;
         this._connection = new Connection(url, options);
     }
@@ -48,67 +55,104 @@ export default class Client {
         return this._connection.isOpen;
     }
     /**
-     * Configuration specific to the current request.
-     * @typedef {Object} RequestOptions
-     * @property {any} bindings - The parameter bindings to apply to the script.
-     * @property {String} language - The language of the script to execute. Defaults to 'gremlin-lang'.
-     * @property {String} accept - The MIME type expected in the response.
-     * @property {Boolean} bulkResults - Indicates whether results should be returned in bulk format.
-     * @property {Object} params - Additional parameters to include with the request.
-     * @property {Number} batchSize - The size in which the result of a request is to be 'batched' back to the client.
-     * @property {String} userAgent - The user agent string to send with the request.
-     * @property {Number} evaluationTimeout - The timeout for the evaluation of the request.
-     * @property {String} materializeProperties - Indicates whether element properties should be returned or not.
+     * Send a request to the Gremlin Server and buffer the entire response.
+     * @param {string} message The script to send
+     * @param {Object|null} [parameters] The query parameters, if any.
+     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
+     * @returns {Promise<ResultSet>}
      */
+    submit(message, parameters, requestOptions) {
+        return this._connection.submit(this.#buildRequest(message, parameters, requestOptions));
+    }
     /**
-     * Send a request to the Gremlin Server.
+     * Send a request to the Gremlin Server and stream results incrementally.
+     * Returns an AsyncGenerator that yields individual result items as they are
+     * deserialized from the response. For bulked responses, yields Traverser objects.
      * @param {string} message The script to send
-     * @param {Object|null} [bindings] The script bindings, if any.
+     * @param {Object|null} [parameters] The query parameters, if any.
      * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-     * @returns {Promise}
-     */ //TODO:: tighten return type to Promise<ResultSet>
-    submit(message, bindings, requestOptions) {
+     * @returns {AsyncGenerator<any>}
+     */
+    async *stream(message, parameters, requestOptions) {
+        return yield* this._connection.stream(this.#buildRequest(message, parameters, requestOptions));
+    }
+    #buildRequest(message, parameters, requestOptions) {
         const requestBuilder = RequestMessage.build(message)
             .addG(this.options.traversalSource || 'g');
         if (requestOptions?.language) {
             requestBuilder.addLanguage(requestOptions.language);
         }
-        if (requestOptions?.bindings) {
-            requestBuilder.addBindings(requestOptions.bindings);
+        if (requestOptions?.parameters) {
+            if (typeof requestOptions.parameters === 'string') {
+                requestBuilder.addParametersString(requestOptions.parameters);
+            }
+            else {
+                requestBuilder.addParameters(requestOptions.parameters);
+            }
         }
-        if (bindings) {
-            requestBuilder.addBindings(bindings);
+        if (parameters) {
+            if (typeof parameters === 'string') {
+                requestBuilder.addParametersString(parameters);
+            }
+            else {
+                requestBuilder.addParameters(parameters);
+            }
         }
         if (requestOptions?.materializeProperties) {
             requestBuilder.addMaterializeProperties(requestOptions.materializeProperties);
         }
-        if (requestOptions?.evaluationTimeout) {
-            requestBuilder.addTimeoutMillis(requestOptions.evaluationTimeout);
+        if (requestOptions?.timeoutMillis) {
+            requestBuilder.addTimeoutMillis(requestOptions.timeoutMillis);
         }
-        if (requestOptions?.bulkResults) {
+        // Per-request value wins (including an explicit `false`); otherwise apply the
+        // connection-level default only when it is true.
+        if (requestOptions?.bulkResults !== undefined) {
             requestBuilder.addBulkResults(requestOptions.bulkResults);
         }
-        return this._connection.submit(requestBuilder.create());
-    }
-    /**
-     * Send a request to the Gremlin Server and receive a stream for the results.
-     * @param {string} message The script to send
-     * @param {Object} [bindings] The script bindings, if any.
-     * @param {RequestOptions} [requestOptions] Configuration specific to the current request.
-     * @returns {ReadableStream}
-     */
-    //TODO:: Update stream() to mirror submit()
-    stream(message, bindings, requestOptions) {
-        throw new Error("Stream not yet implemented");
+        else if (this._connection.bulkResults) {
+            requestBuilder.addBulkResults(true);
+        }
+        // Fill the per-request batchSize from the connection-level default when unset.
+        const batchSize = requestOptions?.batchSize ?? this._connection.batchSize;
+        if (batchSize !== undefined) {
+            requestBuilder.addBatchSize(batchSize);
+        }
+        if (requestOptions?.transactionId) {
+            requestBuilder.addField('transactionId', requestOptions.transactionId);
+        }
+        return requestBuilder.create();
     }
     /**
      * Closes the underlying connection
-     * send session close request before connection close if session mode
      * @returns {Promise}
      */
-    close() {
+    async close() {
+        // Best-effort rollback of any open transactions before closing connections
+        for (const tx of this._trackedTransactions) {
+            try {
+                await tx.close();
+            }
+            catch { }
+        }
+        this._trackedTransactions.clear();
         return this._connection.close();
     }
+    trackTransaction(tx) {
+        this._trackedTransactions.add(tx);
+    }
+    untrackTransaction(tx) {
+        this._trackedTransactions.delete(tx);
+    }
+    /**
+     * Creates a new Transaction for executing operations within an explicit transaction.
+     * Transactions are short-lived and single-use. After commit or rollback,
+     * create a new Transaction for the next unit of work.
+     * The traversal source (g alias) is inherited from this Client.
+     * @returns {Transaction}
+     */
+    transact() {
+        return new Transaction(this);
+    }
     /**
      * Adds an event listener to the connection
      * @param {String} event The event name that you want to listen to.
@@ -118,7 +162,7 @@ export default class Client {
         this._connection.on(event, handler);
     }
     /**
-     * Removes a previowsly added event listener to the connection
+     * Removes a previously added event listener to the connection
      * @param {String} event The event name that you want to listen to.
      * @param {Function} handler The event handler to be removed.
      */

package/build/esm/driver/connection.d.ts

@@ -1,32 +1,48 @@
-/**
- * @author Jorge Bay Gondra
- */
-import { Buffer } from 'buffer';
 import { EventEmitter } from 'eventemitter3';
-import type { Agent } from 'node:http';
 import ResultSet from './result-set.js';
 import { RequestMessage } from "./request-message.js";
-import { Readable } from "stream";
-export type HttpRequest = {
-    url: string;
-    method: string;
-    headers: Record<string, string>;
-    body: any;
-};
-export type RequestInterceptor = (request: HttpRequest) => HttpRequest | Promise<HttpRequest>;
+import { RequestInterceptor } from './http-request.js';
+import { Logger } from './logger.js';
+/**
+ * Selects the content encoding requested from, and decoded for, the server. `'deflate'` (the
+ * default) sends an `Accept-Encoding: deflate` header and decodes deflate responses; `'none'`
+ * turns compression off.
+ */
+export type Compression = 'none' | 'deflate';
 export type ConnectionOptions = {
-    ca?: string[];
-    cert?: string | string[] | Buffer;
-    pfx?: string | Buffer;
-    reader?: any;
-    rejectUnauthorized?: boolean;
+    preciseNumbers?: boolean;
+    pdtRegistry?: any;
+    responseSerializer?: any;
     traversalSource?: string;
-    writer?: any | null;
-    headers?: Record<string, string | string[]>;
     enableUserAgentOnConnect?: boolean;
-    agent?: Agent;
+    /** Maximum number of concurrent connections per origin. Defaults to 128. */
+    maxConnections?: number;
+    /** Read timeout in ms, applied to the default dispatcher. Maps to undici `headersTimeout` (wait for first response byte) and `bodyTimeout` (idle between body chunks). */
+    readTimeoutMillis?: number;
+    /** Maximum size of the response headers in bytes, applied to the default dispatcher. */
+    maxResponseHeaderBytes?: number;
+    /**
+     * Idle time in milliseconds before TCP keep-alive probes begin on a connection. Defaults to
+     * 30000 (30s) when unset. Set to `0` to disable keep-alive entirely.
+     */
+    keepAliveTimeMillis?: number;
+    /** HTTP proxy URI. When set, requests are routed through an undici `ProxyAgent`. */
+    proxy?: string;
+    /** Response compression codec. Defaults to `'deflate'` (on). */
+    compression?: Compression;
+    /** Connection-level default that fills a request's `batchSize` when it is left unset. Defaults to 64. */
+    batchSize?: number;
+    /** Connection-level default for `bulkResults`, applied to every request unless overridden per-request. Defaults to `false`. */
+    bulkResults?: boolean;
+    /** An optional logger (a logger object or a callback). Logging is disabled when unset. */
+    logger?: Logger;
     interceptors?: RequestInterceptor | RequestInterceptor[];
+    /** An optional auth interceptor. As a convenience, this is always appended to the end of the
+     *  interceptor list so it runs last, after any user interceptors have modified the request. */
+    auth?: RequestInterceptor;
 };
+/** The default per-request batch size used when neither the request nor the connection sets one. */
+export declare const DEFAULT_BATCH_SIZE = 64;
 /**
  * Represents a single connection to a Gremlin Server.
  */
@@ -34,27 +50,54 @@ export default class Connection extends EventEmitter {
     #private;
     readonly url: string;
     readonly options: ConnectionOptions;
-    private readonly _reader;
-    private readonly _writer;
+    private readonly _responseSerializer;
     isOpen: boolean;
     traversalSource: string;
     private readonly _enableUserAgentOnConnect;
     private readonly _interceptors;
+    private readonly _dispatcher;
+    private readonly _compression;
+    private readonly _batchSize;
+    private readonly _bulkResults;
+    private readonly _log;
     /**
      * Creates a new instance of {@link Connection}.
      * @param {String} url The resource uri.
      * @param {ConnectionOptions} [options] The connection options.
      */
     constructor(url: string, options?: ConnectionOptions);
+    /**
+     * The connection-level default batch size, used to fill a request's `batchSize` when unset.
+     */
+    get batchSize(): number;
+    /**
+     * The connection-level default for `bulkResults`, applied to every request unless overridden
+     * per-request. Defaults to `false`.
+     */
+    get bulkResults(): boolean;
     /**
      * Opens the connection, if its not already opened.
      * @returns {Promise}
      */
     open(): Promise<void>;
-    /** @override */
+    /**
+     * Send a request and buffer the entire response. Returns a Promise<ResultSet>.
+     */
     submit(request: RequestMessage): Promise<ResultSet>;
-    /** @override */
-    stream(request: RequestMessage): Readable;
+    /**
+     * Send a request and stream the response incrementally.
+     * Returns an AsyncGenerator that yields deserialized result items.
+     * For bulked responses, yields Traverser objects.
+     *
+     * In the GraphBinary v4 streaming protocol, the server sends the status after all
+     * result data. If the server encounters an error mid-traversal, values yielded before
+     * the error are valid partial results. A ResponseError is thrown after the last value
+     * has been yielded.
+     *
+     * @param {RequestMessage} request
+     * @returns {AsyncGenerator<any>}
+     */
+    stream(request: RequestMessage): AsyncGenerator<any>;
     /**
      * Closes the Connection.
      * @return {Promise}