gremlin 3.8.1 → 4.0.0-beta.3

package/build/cjs/driver/dispatcher.d.cts

@@ -0,0 +1,48 @@
+import { Agent, buildConnector, Dispatcher } from 'undici';
+/** Default concurrent-connections-per-origin cap (Node's global fetch is uncapped). */
+export declare const DEFAULT_MAX_CONNECTIONS = 128;
+/** Canonical TinkerPop 4.x default TCP keep-alive idle time (30s), shared across the GLVs. */
+export declare const DEFAULT_KEEP_ALIVE_TIME = 30000;
+/** Options for the default undici {@link Dispatcher}; unset fields use undici defaults. */
+export type DispatcherOptions = {
+    /** Max concurrent connections per origin. Defaults to {@link DEFAULT_MAX_CONNECTIONS}. */
+    maxConnections?: number;
+    /** Read timeout in ms. Maps to undici `headersTimeout` (wait for first response byte) and `bodyTimeout` (idle between body chunks). */
+    readTimeoutMillis?: number;
+    /** Max response header size in bytes. Maps to undici `maxHeaderSize`. */
+    maxResponseHeaderBytes?: number;
+    /** Idle ms before TCP keep-alive probes begin. Defaults to 30s; `0` disables keep-alive. */
+    keepAliveTimeMillis?: number;
+    /** HTTP proxy URI. When set, a {@link ProxyAgent} is built instead of an {@link Agent}. */
+    proxy?: string;
+};
+/**
+ * Resolves the effective keep-alive idle delay: unset falls back to {@link DEFAULT_KEEP_ALIVE_TIME},
+ * a non-positive value disables keep-alive (returns `null`).
+ */
+export declare function resolveKeepAliveTime(keepAliveTime?: number): number | null;
+/**
+ * Builds an undici connector that sets `SO_KEEPALIVE` with the given idle delay on each new socket.
+ * `baseConnector` is parameterised so the wiring can be unit-tested with a fake connector.
+ */
+export declare function buildKeepAliveConnector(delay: number, baseConnector?: ReturnType<typeof buildConnector>): ReturnType<typeof buildConnector>;
+/**
+ * Maps the discrete driver options onto undici {@link Agent.Options} (the single source of truth
+ * for that mapping). Exported as a seam so the mapping can be asserted in unit tests.
+ */
+export declare function buildAgentOptions(options?: DispatcherOptions): Agent.Options;
+/**
+ * Builds the default undici {@link Dispatcher}: a {@link ProxyAgent} when `proxy` is set, otherwise
+ * a plain {@link Agent}. (Agent and ProxyAgent share one dispatcher slot, so only one is built.)
+ */
+export declare function buildDispatcher(options?: DispatcherOptions): Dispatcher;
+/**
+ * HTTP `fetch` for the Node build. Uses undici's own `fetch` (not the global one) so `fetch` and the
+ * {@link buildDispatcher} dispatcher share one undici version, whatever undici the Node runtime
+ * bundles (e.g. Node 26 ships undici 8, incompatible with an undici 6 dispatcher). A holder object,
+ * not a bare export, so tests can swap `fetch` (an ESM export can't be reassigned, an object
+ * property can). The cast aligns undici's `fetch` type with the global one.
+ */
+export declare const httpFetch: {
+    fetch: typeof globalThis.fetch;
+};

package/build/cjs/driver/driver-remote-connection.cjs

@@ -0,0 +1,153 @@
+"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 __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @author Jorge Bay Gondra
+ */
+const rcModule = __importStar(require("./remote-connection.cjs"));
+const RemoteConnection = rcModule.RemoteConnection;
+const RemoteTraversal = rcModule.RemoteTraversal;
+const client_js_1 = __importDefault(require("./client.cjs"));
+/**
+ * Represents the default `RemoteConnection` implementation.
+ */
+class DriverRemoteConnection extends RemoteConnection {
+    // Exposed as package-internal for Transaction to submit begin/commit/rollback.
+    // Not part of the public API contract.
+    _client;
+    _transactionId;
+    /**
+     * Creates a new instance of {@link DriverRemoteConnection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     * @param {String} [transactionId] Optional transaction ID to attach to all requests.
+     */
+    constructor(url, options = {}, transactionId) {
+        super(url, options);
+        this._client = new client_js_1.default(url, options);
+        this._transactionId = transactionId;
+    }
+    /**
+     * Returns the transaction ID if this connection is bound to a transaction, undefined otherwise.
+     */
+    get transactionId() {
+        return this._transactionId;
+    }
+    /** @override */
+    open() {
+        return this._client.open();
+    }
+    /** @override */
+    get isOpen() {
+        return this._client.isOpen;
+    }
+    /** @override */
+    submit(gremlinLang) {
+        const { gremlin, requestOptions } = this.#buildRequestArgs(gremlinLang);
+        // Use streaming internally — returns an AsyncGenerator backed RemoteTraversal
+        const generator = this._client.stream(gremlin, null, requestOptions);
+        return Promise.resolve(new RemoteTraversal(generator));
+    }
+    #buildRequestArgs(gremlinLang) {
+        let requestOptions = undefined;
+        const strategies = gremlinLang.getOptionsStrategies();
+        if (strategies.length > 0) {
+            requestOptions = {};
+            const allowedKeys = [
+                'timeoutMillis',
+                'batchSize',
+                'requestId',
+                'userAgent',
+                'materializeProperties',
+                'bulkResults',
+            ];
+            for (const strategy of strategies) {
+                for (const key in strategy.configuration) {
+                    if (allowedKeys.indexOf(key) > -1) {
+                        requestOptions[key] = strategy.configuration[key];
+                    }
+                }
+            }
+        }
+        if (!requestOptions) {
+            requestOptions = {};
+        }
+        if (!('bulkResults' in requestOptions)) {
+            requestOptions.bulkResults = true;
+        }
+        const parametersString = gremlinLang.getParametersAsString();
+        if (parametersString !== '[:]') {
+            requestOptions.parameters = parametersString;
+        }
+        // If this connection is bound to a transaction, attach the transactionId
+        if (this._transactionId) {
+            requestOptions.transactionId = this._transactionId;
+        }
+        return { gremlin: gremlinLang.getGremlin(), requestOptions };
+    }
+    close() {
+        return this._client.close();
+    }
+    /** @override */
+    addListener(event, handler) {
+        return this._client.addListener(event, handler);
+    }
+    /** @override */
+    removeListener(event, handler) {
+        return this._client.removeListener(event, handler);
+    }
+}
+exports.default = DriverRemoteConnection;

package/build/cjs/driver/driver-remote-connection.d.cts

@@ -0,0 +1,39 @@
+/**
+ * @author Jorge Bay Gondra
+ */
+import * as rcModule from './remote-connection.cjs';
+declare const RemoteConnection: typeof rcModule.RemoteConnection;
+import Client from './client.cjs';
+import GremlinLang from '../process/gremlin-lang.cjs';
+import { ConnectionOptions } from './connection.cjs';
+/**
+ * Represents the default `RemoteConnection` implementation.
+ */
+export default class DriverRemoteConnection extends RemoteConnection {
+    #private;
+    readonly _client: Client;
+    private _transactionId?;
+    /**
+     * Creates a new instance of {@link DriverRemoteConnection}.
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     * @param {String} [transactionId] Optional transaction ID to attach to all requests.
+     */
+    constructor(url: string, options?: ConnectionOptions, transactionId?: string);
+    /**
+     * Returns the transaction ID if this connection is bound to a transaction, undefined otherwise.
+     */
+    get transactionId(): string | undefined;
+    /** @override */
+    open(): Promise<void>;
+    /** @override */
+    get isOpen(): boolean;
+    /** @override */
+    submit(gremlinLang: GremlinLang): Promise<rcModule.RemoteTraversal>;
+    close(): Promise<void>;
+    /** @override */
+    addListener(event: string, handler: (...args: any[]) => unknown): void;
+    /** @override */
+    removeListener(event: string, handler: (...args: any[]) => unknown): void;
+}
+export {};

package/build/cjs/driver/http-request.cjs

@@ -0,0 +1,64 @@
+"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 });
+exports.HttpRequest = void 0;
+const buffer_1 = require("node:buffer");
+const request_message_js_1 = require("./request-message.cjs");
+/**
+ * Represents an HTTP request that is passed through interceptors before being sent to the server.
+ * Interceptors may mutate any field. The {@link serializeBody} method serializes the body to JSON
+ * if it is still a RequestMessage, or returns the existing bytes if already serialized.
+ */
+class HttpRequest {
+    url;
+    method;
+    headers;
+    body;
+    constructor(method, url, headers, body) {
+        this.method = method;
+        this.url = url;
+        this.headers = headers;
+        this.body = body;
+    }
+    /**
+     * Serializes the request body to JSON if it is still a RequestMessage.
+     * If body is already a Buffer, returns it as-is (idempotent).
+     * Sets Content-Type and Content-Length headers on successful serialization.
+     *
+     * @returns The serialized body as a Buffer.
+     * @throws Error if body is neither a RequestMessage nor a Buffer.
+     */
+    serializeBody() {
+        if (buffer_1.Buffer.isBuffer(this.body)) {
+            return this.body;
+        }
+        if (this.body instanceof request_message_js_1.RequestMessage) {
+            // RequestMessage.toJSON() produces the flattened wire object (standard + custom fields).
+            const data = buffer_1.Buffer.from(JSON.stringify(this.body), 'utf-8');
+            this.body = data;
+            this.headers['Content-Type'] = 'application/json';
+            this.headers['Content-Length'] = String(data.length);
+            return data;
+        }
+        const typeName = this.body === null ? 'null' : typeof this.body;
+        throw new Error(`unsupported body type: ${typeName}`);
+    }
+}
+exports.HttpRequest = HttpRequest;

package/build/cjs/driver/http-request.d.cts

@@ -0,0 +1,28 @@
+import { Buffer } from 'buffer';
+import { RequestMessage } from './request-message.cjs';
+/**
+ * Represents an HTTP request that is passed through interceptors before being sent to the server.
+ * Interceptors may mutate any field. The {@link serializeBody} method serializes the body to JSON
+ * if it is still a RequestMessage, or returns the existing bytes if already serialized.
+ */
+export declare class HttpRequest {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body: RequestMessage | Buffer | any;
+    constructor(method: string, url: string, headers: Record<string, string>, body: any);
+    /**
+     * Serializes the request body to JSON if it is still a RequestMessage.
+     * If body is already a Buffer, returns it as-is (idempotent).
+     * Sets Content-Type and Content-Length headers on successful serialization.
+     *
+     * @returns The serialized body as a Buffer.
+     * @throws Error if body is neither a RequestMessage nor a Buffer.
+     */
+    serializeBody(): Buffer;
+}
+/**
+ * A request interceptor receives an HttpRequest and mutates it in place.
+ * Interceptors must not return a value.
+ */
+export type RequestInterceptor = (request: HttpRequest) => void | Promise<void>;

package/build/cjs/driver/logger.cjs

@@ -0,0 +1,45 @@
+"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 });
+exports.normalizeLogger = normalizeLogger;
+/**
+ * Normalizes the user-supplied {@link Logger} option into a single callback. When no logger is
+ * provided, a no-op callback is returned so call sites do not need to null-check.
+ *
+ * @param {Logger} [logger] The user-supplied logger option.
+ * @returns {LoggerCallback} A callback that dispatches to the configured logger.
+ */
+function normalizeLogger(logger) {
+    if (logger === undefined || logger === null) {
+        return () => { };
+    }
+    if (typeof logger === 'function') {
+        return logger;
+    }
+    if (typeof logger === 'object') {
+        return (level, message, ...args) => {
+            const fn = logger[level];
+            if (typeof fn === 'function') {
+                fn.call(logger, message, ...args);
+            }
+        };
+    }
+    throw new TypeError('logger must be a function, a logger object, or undefined');
+}

package/build/cjs/driver/logger.d.cts

@@ -0,0 +1,29 @@
+/** The set of log levels emitted by the driver, ordered from least to most severe. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * A logger object with one method per {@link LogLevel}. This shape is compatible with the
+ * global `console` as well as common logging libraries.
+ */
+export interface LoggerObject {
+    debug(message: string, ...args: any[]): void;
+    info(message: string, ...args: any[]): void;
+    warn(message: string, ...args: any[]): void;
+    error(message: string, ...args: any[]): void;
+}
+/**
+ * A logger callback that receives the level alongside the message and any extra arguments.
+ */
+export type LoggerCallback = (level: LogLevel, message: string, ...args: any[]) => void;
+/**
+ * The `logger` connection option. It may be either a {@link LoggerObject} (e.g. the global
+ * `console`) or a {@link LoggerCallback}. Logging is disabled when no logger is provided.
+ */
+export type Logger = LoggerObject | LoggerCallback;
+/**
+ * Normalizes the user-supplied {@link Logger} option into a single callback. When no logger is
+ * provided, a no-op callback is returned so call sites do not need to null-check.
+ *
+ * @param {Logger} [logger] The user-supplied logger option.
+ * @returns {LoggerCallback} A callback that dispatches to the configured logger.
+ */
+export declare function normalizeLogger(logger?: Logger): LoggerCallback;

package/build/cjs/driver/remote-connection.cjs

@@ -0,0 +1,72 @@
+"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 });
+exports.RemoteStrategy = exports.RemoteTraversal = exports.RemoteConnection = void 0;
+const traversal_strategy_js_1 = require("../process/traversal-strategy.cjs");
+const traversal_js_1 = require("../process/traversal.cjs");
+/**
+ * Represents an abstraction of a "connection" to a "server" that is capable of processing a traversal and
+ * returning results.
+ */
+class RemoteConnection {
+    url;
+    options;
+    /**
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+    }
+}
+exports.RemoteConnection = RemoteConnection;
+/**
+ * Represents a traversal as a result of a {@link RemoteConnection} submission.
+ */
+class RemoteTraversal extends traversal_js_1.Traversal {
+    constructor(source, sideEffects) {
+        super(null, null);
+        this._resultsStream = source;
+    }
+}
+exports.RemoteTraversal = RemoteTraversal;
+class RemoteStrategy extends traversal_strategy_js_1.TraversalStrategy {
+    connection;
+    /**
+     * Creates a new instance of RemoteStrategy.
+     * @param {RemoteConnection} connection
+     */
+    constructor(connection) {
+        super();
+        this.connection = connection;
+    }
+    /** @override */
+    apply(traversal) {
+        if (traversal._resultsStream) {
+            return Promise.resolve();
+        }
+        return this.connection.submit(traversal.getGremlinLang()).then(function (remoteTraversal) {
+            traversal.sideEffects = remoteTraversal.sideEffects;
+            traversal._resultsStream = remoteTraversal._resultsStream;
+        });
+    }
+}
+exports.RemoteStrategy = RemoteStrategy;

package/build/cjs/driver/remote-connection.d.cts

@@ -0,0 +1,57 @@
+/**
+ * @author Jorge Bay Gondra
+ */
+import GremlinLang from '../process/gremlin-lang.cjs';
+import { TraversalStrategy } from '../process/traversal-strategy.cjs';
+import { Traversal } from '../process/traversal.cjs';
+import type { ConnectionOptions } from './connection.cjs';
+/**
+ * Represents an abstraction of a "connection" to a "server" that is capable of processing a traversal and
+ * returning results.
+ */
+export declare abstract class RemoteConnection {
+    url: string;
+    readonly options: ConnectionOptions;
+    /**
+     * @param {String} url The resource uri.
+     * @param {ConnectionOptions} [options] The connection options.
+     */
+    constructor(url: string, options?: ConnectionOptions);
+    /**
+     * Opens the connection, if its not already opened.
+     * @returns {Promise}
+     */
+    abstract open(): Promise<void>;
+    /**
+     * Returns true if connection is open
+     * @returns {Boolean}
+     */
+    abstract get isOpen(): boolean;
+    /**
+     * Submits the <code>GremlinLang</code> provided and returns a <code>RemoteTraversal</code>.
+     * @param {GremlinLang} gremlinLang
+     * @returns {Promise} Returns a <code>Promise</code> that resolves to a <code>RemoteTraversal</code>.
+     */
+    abstract submit(gremlinLang: GremlinLang): Promise<RemoteTraversal>;
+    /**
+     * Closes the connection and releases any associated resources.
+     * @returns {Promise}
+     */
+    abstract close(): Promise<void>;
+}
+/**
+ * Represents a traversal as a result of a {@link RemoteConnection} submission.
+ */
+export declare class RemoteTraversal extends Traversal {
+    constructor(source: AsyncGenerator<any>, sideEffects?: any[]);
+}
+export declare class RemoteStrategy extends TraversalStrategy {
+    connection: RemoteConnection;
+    /**
+     * Creates a new instance of RemoteStrategy.
+     * @param {RemoteConnection} connection
+     */
+    constructor(connection: RemoteConnection);
+    /** @override */
+    apply(traversal: Traversal): Promise<void>;
+}