@geodedb/client 1.0.0-alpha.11

package/dist/index.d.mts

@@ -0,0 +1,2430 @@
+import * as tls from 'node:tls';
+import Decimal from 'decimal.js-light';
+export { default as Decimal } from 'decimal.js-light';
+
+/**
+ * Geode Client Configuration
+ *
+ * DSN parsing and configuration management.
+ */
+declare const DEFAULT_PORT = 3141;
+declare const DEFAULT_PAGE_SIZE = 1000;
+declare const DEFAULT_HELLO_NAME = "geode-nodejs";
+declare const DEFAULT_HELLO_VERSION = "1.0.0";
+declare const DEFAULT_CONFORMANCE = "min";
+declare const MAX_QUERY_LENGTH: number;
+declare const MAX_PAGE_SIZE = 100000;
+/**
+ * Geode connection configuration.
+ */
+interface GeodeConfig {
+    /** Server hostname or IP address */
+    host: string;
+    /** Server port (default: 3141) */
+    port: number;
+    /** Number of rows per page (default: 1000) */
+    pageSize: number;
+    /** Client name sent in HELLO message */
+    helloName: string;
+    /** Client version sent in HELLO message */
+    helloVersion: string;
+    /** GQL conformance level (default: "min") */
+    conformance: string;
+    /** Username for authentication */
+    username?: string;
+    /** Password for authentication */
+    password?: string;
+    /** Path to CA certificate file */
+    tlsCA?: string;
+    /** CA certificate as PEM string */
+    tlsCACert?: string;
+    /** Path to client certificate file (for mTLS) */
+    tlsCert?: string;
+    /** Client certificate as PEM string (for mTLS) */
+    tlsCertPEM?: string;
+    /** Path to client private key file (for mTLS) */
+    tlsKey?: string;
+    /** Client private key as PEM string (for mTLS) */
+    tlsKeyPEM?: string;
+    /** Skip TLS verification (DEVELOPMENT ONLY, never use in production) */
+    insecureSkipVerify?: boolean;
+    /** SNI server name override */
+    serverName?: string;
+    /** Connection timeout in milliseconds (default: 30000) */
+    connectTimeout?: number;
+    /** Request timeout in milliseconds (default: 120000) */
+    requestTimeout?: number;
+    /** Keep-alive interval in milliseconds (default: 10000) */
+    keepAliveInterval?: number;
+    /** Maximum idle time in milliseconds (default: 30000) */
+    maxIdleTime?: number;
+}
+/**
+ * Connection pool configuration.
+ */
+interface PoolConfig extends GeodeConfig {
+    /** Minimum number of connections in pool (default: 2) */
+    minConnections?: number;
+    /** Maximum number of connections in pool (default: 10) */
+    maxConnections?: number;
+    /** Time to wait for connection in milliseconds (default: 30000) */
+    acquireTimeout?: number;
+    /** Idle connection lifetime in milliseconds (default: 60000) */
+    idleTimeout?: number;
+}
+/**
+ * Create a default configuration.
+ */
+declare function defaultConfig(): GeodeConfig;
+/**
+ * Parse a DSN (Data Source Name) string into configuration.
+ *
+ * Supported formats:
+ *   - geode://host:port?options
+ *   - geode://username:password@host:port?options
+ *   - host:port?options
+ *   - host:port
+ *   - host (uses default port)
+ *
+ * Supported options:
+ *   - page_size: Results page size (default: 1000)
+ *   - hello_name: Client name (default: "geode-nodejs")
+ *   - hello_ver: Client version (default: "1.0.0")
+ *   - conformance: GQL conformance level (default: "min")
+ *   - username/user: Authentication username
+ *   - password/pass: Authentication password
+ *   - ca: Path to CA certificate
+ *   - cert: Path to client certificate (for mTLS)
+ *   - key: Path to client key (for mTLS)
+ *   - insecure: Skip TLS verification (testing only)
+ *   - server_name: SNI server name
+ *   - connect_timeout: Connection timeout in ms
+ *   - request_timeout: Request timeout in ms
+ *
+ * Environment variables (used as defaults):
+ *   - GEODE_HOST: Default host
+ *   - GEODE_PORT: Default port
+ *   - GEODE_TLS_CA: Default CA certificate path
+ *   - GEODE_USERNAME: Default username
+ *   - GEODE_PASSWORD: Default password
+ */
+declare function parseDSN(dsn: string): GeodeConfig;
+/**
+ * Validate configuration.
+ */
+declare function validateConfig(cfg: GeodeConfig): void;
+/**
+ * Get the server address in host:port format.
+ */
+declare function getAddress(cfg: GeodeConfig): string;
+/**
+ * Clone configuration.
+ */
+declare function cloneConfig(cfg: GeodeConfig): GeodeConfig;
+
+/**
+ * Geode Client Error Types
+ *
+ * Implements ISO/IEC 39075:2024 status codes for GQL error handling.
+ */
+declare const StatusClass: {
+    readonly SUCCESS: "00000";
+    readonly WARNING: "01000";
+    readonly NO_DATA: "02000";
+    readonly TRANSACTION_STATE: "25000";
+    readonly AUTH: "28000";
+    readonly SERIALIZATION: "40001";
+    readonly DEADLOCK: "40502";
+    readonly SYNTAX: "42000";
+    readonly CONSTRAINT: "23000";
+    readonly DUPLICATE: "42P07";
+    readonly INVALID_PARAM: "22023";
+    readonly SYSTEM: "58000";
+};
+type StatusClassType = (typeof StatusClass)[keyof typeof StatusClass];
+/**
+ * Base interface for all Geode errors.
+ */
+interface GeodeError extends Error {
+    /** ISO/IEC 39075 status class */
+    readonly statusClass: StatusClassType;
+    /** Whether this error can be retried */
+    readonly isRetryable: boolean;
+}
+/**
+ * Error returned from the Geode server.
+ */
+declare class DriverError extends Error implements GeodeError {
+    readonly statusClass: StatusClassType;
+    readonly subclass: string;
+    readonly code: string;
+    readonly anchor?: string;
+    readonly additional: string[];
+    readonly findings: string[];
+    constructor(options: {
+        statusClass: StatusClassType;
+        subclass: string;
+        code: string;
+        message: string;
+        anchor?: string;
+        additional?: string[];
+        findings?: string[];
+    });
+    get isRetryable(): boolean;
+}
+/**
+ * Transport layer error (QUIC/network failures).
+ */
+declare class TransportError extends Error implements GeodeError {
+    readonly statusClass: "58000";
+    readonly operation: string;
+    readonly address?: string;
+    readonly cause?: Error;
+    constructor(options: {
+        operation: string;
+        address?: string;
+        cause?: Error;
+    });
+    get isRetryable(): boolean;
+}
+/**
+ * Configuration/DSN parsing error.
+ */
+declare class ConfigError extends Error implements GeodeError {
+    readonly statusClass: "22023";
+    readonly field: string;
+    readonly value?: string;
+    constructor(options: {
+        field: string;
+        value?: string;
+        message: string;
+    });
+    get isRetryable(): boolean;
+}
+/**
+ * Security validation error (TLS, input validation).
+ */
+declare class SecurityError extends Error implements GeodeError {
+    readonly statusClass: "28000";
+    readonly type: 'tls' | 'input' | 'validation';
+    readonly cause?: Error;
+    constructor(options: {
+        type: 'tls' | 'input' | 'validation';
+        message: string;
+        cause?: Error;
+    });
+    get isRetryable(): boolean;
+}
+/**
+ * Connection state error.
+ */
+declare class StateError extends Error implements GeodeError {
+    readonly statusClass: "25000";
+    readonly currentState: ConnectionState;
+    readonly operation: string;
+    constructor(options: {
+        currentState: ConnectionState;
+        operation: string;
+        message?: string;
+    });
+    get isRetryable(): boolean;
+}
+/**
+ * Connection state enumeration.
+ */
+type ConnectionState = 'idle' | 'executing' | 'in_transaction' | 'fetching' | 'closed' | 'error';
+declare const ErrClosed: Error;
+declare const ErrQueryInProgress: Error;
+declare const ErrTxInProgress: Error;
+declare const ErrNoTx: Error;
+declare const ErrTxDone: Error;
+declare const ErrRowsClosed: Error;
+declare const ErrBadConn: Error;
+/**
+ * Type guard for DriverError.
+ */
+declare function isDriverError(err: unknown): err is DriverError;
+/**
+ * Type guard for GeodeError.
+ */
+declare function isGeodeError(err: unknown): err is GeodeError;
+/**
+ * Check if an error is retryable.
+ */
+declare function isRetryableError(err: unknown): boolean;
+
+/**
+ * QUIC Transport Layer
+ *
+ * Provides QUIC + TLS 1.3 transport for communication with Geode server.
+ */
+
+/**
+ * Transport interface for communication with Geode server.
+ */
+interface Transport {
+    /** Send a message to the server */
+    send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    /** Receive a message from the server */
+    receive(signal?: AbortSignal): Promise<Buffer>;
+    /** Close the transport */
+    close(): Promise<void>;
+    /** Check if transport is closed */
+    isClosed(): boolean;
+    /** Get remote address */
+    getAddress(): string;
+}
+/**
+ * Build TLS configuration from GeodeConfig.
+ */
+declare function buildTLSConfig(cfg: GeodeConfig): Promise<tls.SecureContextOptions>;
+/**
+ * Abstract base class for QUIC transports.
+ * Allows for different QUIC implementations.
+ */
+declare abstract class BaseTransport implements Transport {
+    protected _closed: boolean;
+    protected _address: string;
+    constructor(address: string);
+    abstract send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    abstract receive(signal?: AbortSignal): Promise<Buffer>;
+    abstract close(): Promise<void>;
+    isClosed(): boolean;
+    getAddress(): string;
+    protected checkClosed(): void;
+}
+/**
+ * QUIC transport using @matrixai/quic.
+ *
+ * This implementation uses the quiche QUIC library via native bindings.
+ */
+declare class MatrixQuicTransport extends BaseTransport {
+    private _client;
+    private _stream;
+    private _readBuffer;
+    private _lineBuffer;
+    private _pendingReads;
+    constructor(address: string);
+    /**
+     * Connect to the Geode server using QUIC.
+     */
+    static connect(cfg: GeodeConfig): Promise<MatrixQuicTransport>;
+    /**
+     * Start reading from the stream in the background.
+     */
+    private startReading;
+    /**
+     * Process received data, splitting by newlines.
+     */
+    private processData;
+    send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    receive(signal?: AbortSignal): Promise<Buffer>;
+    close(): Promise<void>;
+}
+/**
+ * Mock transport for testing purposes.
+ *
+ * This allows unit testing without a real QUIC connection.
+ */
+declare class MockTransport extends BaseTransport {
+    private _sendQueue;
+    private _receiveQueue;
+    private _pendingReads;
+    constructor(address?: string);
+    /**
+     * Queue a response to be returned by receive().
+     */
+    queueResponse(response: Record<string, unknown>): void;
+    /**
+     * Get all sent messages.
+     */
+    getSentMessages(): Record<string, unknown>[];
+    /**
+     * Clear sent messages.
+     */
+    clearSentMessages(): void;
+    send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
+    receive(signal?: AbortSignal): Promise<Buffer>;
+    close(): Promise<void>;
+}
+/**
+ * Create a transport for the given configuration.
+ *
+ * Uses MatrixQuicTransport by default.
+ */
+declare function createTransport(cfg: GeodeConfig): Promise<Transport>;
+
+/**
+ * GQL Type System
+ *
+ * Implements the GQL value type system for ISO/IEC 39075:2024 compliance.
+ */
+
+/**
+ * GQL value kind enumeration.
+ */
+type GQLValueKind = 'NULL' | 'BOOL' | 'INT' | 'FLOAT' | 'STRING' | 'DECIMAL' | 'BYTEA' | 'DATE' | 'TIME' | 'TIMETZ' | 'TIMESTAMP' | 'TIMESTAMPTZ' | 'INTERVAL' | 'JSON' | 'JSONB' | 'XML' | 'URL' | 'DOMAIN' | 'UUID' | 'ENUM' | 'BIT_STRING' | 'RANGE' | 'ARRAY' | 'OBJECT' | 'NODE' | 'EDGE' | 'PATH' | 'UNKNOWN';
+/**
+ * GQL type enumeration for wire protocol.
+ */
+type GQLType = 'INT' | 'INTEGER' | 'BIGINT' | 'FLOAT' | 'DOUBLE' | 'REAL' | 'DECIMAL' | 'STRING' | 'VARCHAR' | 'TEXT' | 'BOOL' | 'BOOLEAN' | 'NULL' | 'LIST' | 'ARRAY' | 'MAP' | 'RECORD' | 'NODE' | 'EDGE' | 'RELATIONSHIP' | 'PATH' | 'BYTEA' | 'DATE' | 'TIME' | 'TIMETZ' | 'TIMESTAMP' | 'TIMESTAMPTZ' | 'INTERVAL' | 'JSON' | 'JSONB' | 'XML' | 'UUID' | 'URL' | 'DOMAIN' | 'ENUM' | 'BIT' | 'VARBIT' | 'UNKNOWN';
+/**
+ * Range bounds for GQL range types.
+ */
+interface GQLRange<T = unknown> {
+    lower?: T;
+    upper?: T;
+    lowerInclusive: boolean;
+    upperInclusive: boolean;
+}
+/**
+ * Node structure from graph queries.
+ */
+interface GQLNode {
+    id: string | number;
+    labels: string[];
+    properties: Record<string, unknown>;
+}
+/**
+ * Edge structure from graph queries.
+ */
+interface GQLEdge {
+    id: string | number;
+    type: string;
+    startNode: string | number;
+    endNode: string | number;
+    properties: Record<string, unknown>;
+}
+/**
+ * Path structure from graph queries.
+ */
+interface GQLPath {
+    nodes: GQLNode[];
+    edges: GQLEdge[];
+}
+/**
+ * GQL Value wrapper for type-safe value handling.
+ */
+declare class GQLValue {
+    readonly kind: GQLValueKind;
+    private _intValue;
+    private _floatValue;
+    private _boolValue;
+    private _stringValue;
+    private _decimalValue?;
+    private _arrayValue;
+    private _objectValue;
+    private _bytesValue;
+    private _dateValue?;
+    private _rangeValue?;
+    private _nodeValue?;
+    private _edgeValue?;
+    private _pathValue?;
+    private _rawValue?;
+    private constructor();
+    static null(): GQLValue;
+    static bool(value: boolean): GQLValue;
+    static int(value: number | bigint): GQLValue;
+    static float(value: number): GQLValue;
+    static string(value: string): GQLValue;
+    static decimal(value: string | number | Decimal): GQLValue;
+    static array(values: GQLValue[]): GQLValue;
+    static object(values: Map<string, GQLValue> | Record<string, GQLValue>): GQLValue;
+    static bytes(value: Uint8Array | Buffer): GQLValue;
+    static date(value: Date): GQLValue;
+    static time(value: Date): GQLValue;
+    static timestamp(value: Date): GQLValue;
+    static uuid(value: string): GQLValue;
+    static json(value: unknown): GQLValue;
+    static node(value: GQLNode): GQLValue;
+    static edge(value: GQLEdge): GQLValue;
+    static path(value: GQLPath): GQLValue;
+    static range<T>(value: GQLRange<T>): GQLValue;
+    static unknown(value: unknown): GQLValue;
+    get isNull(): boolean;
+    get asBool(): boolean;
+    get asInt(): bigint;
+    get asNumber(): number;
+    get asFloat(): number;
+    get asString(): string;
+    get asDecimal(): Decimal;
+    get asArray(): GQLValue[];
+    get asObject(): Map<string, GQLValue>;
+    get asBytes(): Uint8Array;
+    get asDate(): Date;
+    get asNode(): GQLNode;
+    get asEdge(): GQLEdge;
+    get asPath(): GQLPath;
+    get asRange(): GQLRange;
+    get asJSON(): unknown;
+    get raw(): unknown;
+    toString(): string;
+    /**
+     * Convert to a plain JavaScript value.
+     */
+    toJS(): unknown;
+    /**
+     * Convert to JSON-serializable format.
+     */
+    toJSON(): unknown;
+}
+/**
+ * Parse a GQL type string to GQLValueKind.
+ */
+declare function parseGQLType(typeStr: string): GQLValueKind;
+/**
+ * Convert a JSON value from the server to a GQLValue.
+ */
+declare function fromJSON(value: unknown, typeHint?: GQLValueKind): GQLValue;
+/**
+ * Column definition from SCHEMA response.
+ */
+interface ColumnDef {
+    name: string;
+    type: GQLType;
+}
+/**
+ * Column metadata with parsed type.
+ */
+interface ColumnInfo {
+    name: string;
+    type: GQLType;
+    kind: GQLValueKind;
+}
+/**
+ * Query result row.
+ */
+type Row = Map<string, GQLValue>;
+/**
+ * Convert raw row data to typed Row.
+ */
+declare function parseRow(raw: Record<string, unknown>, columns: ColumnInfo[]): Row;
+/**
+ * Convert Row to plain object.
+ */
+declare function rowToObject(row: Row): Record<string, unknown>;
+
+/**
+ * Query Result Handling
+ *
+ * Implements async iteration over query results with pagination.
+ */
+
+/**
+ * Query result with async iteration support.
+ */
+declare class QueryResult implements AsyncIterable<Row> {
+    private _conn;
+    private _columns;
+    private _buffer;
+    private _final;
+    private _ordered;
+    private _orderKeys;
+    private _pageSize;
+    private _signal?;
+    private _closed;
+    private _bufferIndex;
+    private _rowCount;
+    constructor(conn: Connection, columns: ColumnInfo[], initialRows: Record<string, unknown>[], final: boolean, ordered: boolean, orderKeys: string[], pageSize: number, signal?: AbortSignal);
+    /**
+     * Get column definitions.
+     */
+    get columns(): readonly ColumnInfo[];
+    /**
+     * Get column names.
+     */
+    get columnNames(): string[];
+    /**
+     * Check if results are ordered.
+     */
+    get ordered(): boolean;
+    /**
+     * Get order keys (if ordered).
+     */
+    get orderKeys(): readonly string[];
+    /**
+     * Check if all results have been fetched.
+     */
+    get complete(): boolean;
+    /**
+     * Check if result is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Get the number of rows returned so far.
+     */
+    get rowCount(): number;
+    /**
+     * Async iterator implementation.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<Row>;
+    /**
+     * Get all remaining rows as an array.
+     */
+    toArray(): Promise<Row[]>;
+    /**
+     * Get all remaining rows as plain objects.
+     */
+    toObjects(): Promise<Record<string, unknown>[]>;
+    /**
+     * Get the first row (or null if empty).
+     */
+    first(): Promise<Row | null>;
+    /**
+     * Get the first row as plain object (or null if empty).
+     */
+    firstObject(): Promise<Record<string, unknown> | null>;
+    /**
+     * Apply a function to each row.
+     */
+    forEach(fn: (row: Row, index: number) => void | Promise<void>): Promise<void>;
+    /**
+     * Map rows to a new array.
+     */
+    map<T>(fn: (row: Row, index: number) => T | Promise<T>): Promise<T[]>;
+    /**
+     * Filter rows.
+     */
+    filter(predicate: (row: Row, index: number) => boolean | Promise<boolean>): Promise<Row[]>;
+    /**
+     * Reduce rows to a single value.
+     */
+    reduce<T>(fn: (acc: T, row: Row, index: number) => T | Promise<T>, initial: T): Promise<T>;
+    /**
+     * Close the result set.
+     */
+    close(): void;
+    /**
+     * Internal close (called by connection).
+     */
+    _close(): void;
+}
+/**
+ * Iterator for synchronous access to query results.
+ *
+ * This wraps the async iterator for cases where results are pre-fetched.
+ */
+declare class QueryResultIterator {
+    private _result;
+    private _iterator;
+    constructor(result: QueryResult);
+    /**
+     * Get the next row.
+     */
+    next(): Promise<{
+        done: boolean;
+        value?: Row;
+    }>;
+    /**
+     * Close the iterator.
+     */
+    close(): void;
+}
+
+/**
+ * Transaction Management
+ *
+ * Provides transaction and savepoint support.
+ */
+
+/**
+ * Transaction represents an active database transaction.
+ */
+declare class Transaction {
+    private _conn;
+    private _done;
+    private _savepoints;
+    constructor(conn: Connection);
+    /**
+     * Check if transaction is complete (committed or rolled back).
+     */
+    get isDone(): boolean;
+    /**
+     * Get the list of active savepoints.
+     */
+    get savepoints(): readonly string[];
+    /**
+     * Execute a query within the transaction.
+     */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and return all rows.
+     */
+    queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a statement that doesn't return rows.
+     */
+    exec(query: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Create a savepoint.
+     */
+    savepoint(name: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Rollback to a savepoint.
+     */
+    rollbackTo(name: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Release a savepoint.
+     *
+     * Note: Geode doesn't have explicit RELEASE SAVEPOINT, but we track it client-side.
+     */
+    release(name: string): void;
+    /**
+     * Commit the transaction.
+     */
+    commit(signal?: AbortSignal): Promise<void>;
+    /**
+     * Rollback the transaction.
+     */
+    rollback(signal?: AbortSignal): Promise<void>;
+    /**
+     * Execute a function within the transaction with automatic commit/rollback.
+     */
+    run<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;
+    /**
+     * Check if transaction is already done.
+     */
+    private checkDone;
+}
+/**
+ * Execute a function within a new transaction.
+ *
+ * Automatically commits on success or rolls back on error.
+ */
+declare function withTransaction<T>(conn: Connection, fn: (tx: Transaction) => Promise<T>, signal?: AbortSignal): Promise<T>;
+
+/**
+ * Prepared Statements
+ *
+ * Support for parameterized query preparation and efficient repeated execution.
+ */
+
+/**
+ * Parameter metadata extracted from a query.
+ */
+interface ParameterInfo {
+    /** Parameter name */
+    name: string;
+    /** Position in the query (1-indexed) */
+    position: number;
+    /** Whether this is a positional parameter (?) */
+    positional: boolean;
+}
+/**
+ * Prepared statement for efficient repeated execution.
+ *
+ * Prepared statements parse the query once and allow multiple executions
+ * with different parameter values.
+ *
+ * @example
+ * ```typescript
+ * const stmt = conn.prepare('MATCH (n:Person {name: $name}) RETURN n');
+ *
+ * // Execute with different parameters
+ * const result1 = await stmt.query({ name: 'Alice' });
+ * const result2 = await stmt.query({ name: 'Bob' });
+ *
+ * // Close when done
+ * stmt.close();
+ * ```
+ */
+declare class PreparedStatement {
+    private _conn;
+    private _query;
+    private _parameters;
+    private _closed;
+    /**
+     * Create a new prepared statement.
+     *
+     * @internal Use Connection.prepare() instead.
+     */
+    constructor(conn: Connection, query: string);
+    /**
+     * Get the query text.
+     */
+    get query(): string;
+    /**
+     * Get parameter information.
+     */
+    get parameters(): ReadonlyArray<ParameterInfo>;
+    /**
+     * Get the number of parameters.
+     */
+    get parameterCount(): number;
+    /**
+     * Get positional parameter count (number of ? placeholders).
+     */
+    get positionalCount(): number;
+    /**
+     * Get named parameter names.
+     */
+    get namedParameters(): string[];
+    /**
+     * Check if the statement is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Execute the prepared statement and return results.
+     *
+     * @param params - Parameter values (object for named, array for positional)
+     * @param options - Additional query options
+     * @returns Query result
+     */
+    execute(params?: QueryParams | unknown[], options?: Omit<QueryOptions, 'params'>): Promise<QueryResult>;
+    /**
+     * Execute the prepared statement and return all rows.
+     *
+     * @param params - Parameter values
+     * @param options - Additional query options
+     * @returns Array of row objects
+     */
+    executeAll(params?: QueryParams | unknown[], options?: Omit<QueryOptions, 'params'>): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute the prepared statement without returning results.
+     *
+     * @param params - Parameter values
+     * @param options - Additional query options
+     */
+    exec(params?: QueryParams | unknown[], options?: Omit<QueryOptions, 'params'>): Promise<void>;
+    /**
+     * Validate parameters without executing.
+     *
+     * @param params - Parameter values to validate
+     * @throws SecurityError if validation fails
+     */
+    validate(params?: QueryParams | unknown[]): void;
+    /**
+     * Close the prepared statement.
+     *
+     * After closing, the statement cannot be executed.
+     */
+    close(): void;
+    /**
+     * Resolve and validate parameters.
+     */
+    private resolveParams;
+    /**
+     * Check if statement is closed.
+     */
+    private checkClosed;
+}
+/**
+ * Extract parameter information from a query string.
+ *
+ * Supports both positional (?) and named ($name) parameters.
+ */
+declare function extractParameters(query: string): ParameterInfo[];
+/**
+ * Create a prepared statement from a query string.
+ *
+ * @param conn - Connection to use
+ * @param query - Query text
+ * @returns Prepared statement
+ */
+declare function prepare(conn: Connection, query: string): PreparedStatement;
+
+/**
+ * Query Explain and Profile
+ *
+ * Support for query plan analysis and execution profiling.
+ */
+
+/**
+ * A single operation in a query plan.
+ */
+interface PlanOperation {
+    /** Operation type (e.g., 'NodeScan', 'Filter', 'Expand') */
+    type: string;
+    /** Optional operator name */
+    operator?: string;
+    /** Estimated cost */
+    cost?: number;
+    /** Estimated rows */
+    rows?: number;
+    /** Details about the operation */
+    details?: Record<string, unknown>;
+    /** Child operations */
+    children?: PlanOperation[];
+}
+/**
+ * Query execution plan.
+ */
+interface QueryPlan {
+    /** Root operation */
+    root: PlanOperation;
+    /** Total estimated cost */
+    totalCost?: number;
+    /** Total estimated rows */
+    totalRows?: number;
+    /** Raw plan data from server */
+    raw: unknown;
+}
+/**
+ * Timing information for profiled operations.
+ */
+interface OperationTiming {
+    /** Operation type */
+    type: string;
+    /** Wall clock time in milliseconds */
+    wallTimeMs: number;
+    /** CPU time in milliseconds */
+    cpuTimeMs?: number;
+    /** Actual rows produced */
+    rows?: number;
+    /** Number of database page hits */
+    pageHits?: number;
+    /** Number of database page faults */
+    pageFaults?: number;
+    /** Child operation timings */
+    children?: OperationTiming[];
+}
+/**
+ * Query execution profile.
+ */
+interface QueryProfile {
+    /** Root operation timing */
+    root: OperationTiming;
+    /** Total execution time in milliseconds */
+    totalTimeMs: number;
+    /** Total rows processed */
+    totalRows?: number;
+    /** Planning time in milliseconds */
+    planningTimeMs?: number;
+    /** Execution time in milliseconds */
+    executionTimeMs?: number;
+    /** Memory used in bytes */
+    memoryBytes?: number;
+    /** Raw profile data from server */
+    raw: unknown;
+}
+/**
+ * Options for explain/profile operations.
+ */
+interface ExplainOptions extends Omit<QueryOptions, 'pageSize'> {
+    /** Include verbose details */
+    verbose?: boolean;
+    /** Analyze query costs */
+    analyze?: boolean;
+}
+/**
+ * Get the query execution plan without executing.
+ *
+ * @param conn - Connection to use
+ * @param query - Query to explain
+ * @param options - Options including parameters
+ * @returns Query execution plan
+ *
+ * @example
+ * ```typescript
+ * const plan = await explain(conn, 'MATCH (n:Person)-[:KNOWS]->(m) RETURN n, m');
+ * console.log('Plan:', plan.root.type);
+ * console.log('Estimated cost:', plan.totalCost);
+ * ```
+ */
+declare function explain(conn: Connection, query: string, options?: ExplainOptions): Promise<QueryPlan>;
+/**
+ * Execute a query with profiling and return execution statistics.
+ *
+ * Unlike explain(), profile() actually executes the query and measures
+ * real performance metrics.
+ *
+ * @param conn - Connection to use
+ * @param query - Query to profile
+ * @param options - Options including parameters
+ * @returns Query execution profile
+ *
+ * @example
+ * ```typescript
+ * const profile = await profile(conn, 'MATCH (n:Person) RETURN count(n)');
+ * console.log('Execution time:', profile.totalTimeMs, 'ms');
+ * console.log('Rows processed:', profile.totalRows);
+ * ```
+ */
+declare function profile(conn: Connection, query: string, options?: ExplainOptions): Promise<QueryProfile>;
+/**
+ * Format a query plan as a human-readable string.
+ */
+declare function formatPlan(plan: QueryPlan, indent?: number): string;
+/**
+ * Format a query profile as a human-readable string.
+ */
+declare function formatProfile(prof: QueryProfile, indent?: number): string;
+
+/**
+ * Batch Query Operations
+ *
+ * Support for executing multiple queries efficiently.
+ */
+
+/**
+ * A single query in a batch.
+ */
+interface BatchQuery {
+    /** Query text */
+    query: string;
+    /** Optional parameters */
+    params?: QueryParams;
+}
+/**
+ * Result of a batch query.
+ */
+interface BatchResult {
+    /** Index in the batch (0-based) */
+    index: number;
+    /** Query that was executed */
+    query: string;
+    /** Whether the query succeeded */
+    success: boolean;
+    /** Rows returned (if query was successful) */
+    rows?: Record<string, unknown>[];
+    /** Error (if query failed) */
+    error?: Error;
+    /** Execution time in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Summary of batch execution.
+ */
+interface BatchSummary {
+    /** Total number of queries */
+    total: number;
+    /** Number of successful queries */
+    successful: number;
+    /** Number of failed queries */
+    failed: number;
+    /** Total execution time in milliseconds */
+    totalDurationMs: number;
+    /** Individual results */
+    results: BatchResult[];
+}
+/**
+ * Options for batch execution.
+ */
+interface BatchOptions {
+    /** Stop on first error (default: false) */
+    stopOnError?: boolean;
+    /** Maximum concurrent queries (default: 1 - sequential) */
+    concurrency?: number;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Page size for result fetching */
+    pageSize?: number;
+    /** Execute within a transaction (default: false) */
+    transaction?: boolean;
+}
+/**
+ * Execute multiple queries in a batch.
+ *
+ * By default, queries are executed sequentially and all results are collected.
+ * Set stopOnError to true to abort on the first failure.
+ *
+ * @param conn - Connection to use
+ * @param queries - Array of queries to execute
+ * @param options - Batch execution options
+ * @returns Batch execution summary
+ *
+ * @example
+ * ```typescript
+ * const summary = await batch(conn, [
+ *   { query: 'CREATE (a:Person {name: "Alice"})' },
+ *   { query: 'CREATE (b:Person {name: "Bob"})' },
+ *   { query: 'MATCH (n:Person) RETURN count(n) AS cnt' },
+ * ]);
+ *
+ * console.log(`${summary.successful}/${summary.total} queries succeeded`);
+ * ```
+ */
+declare function batch(conn: Connection, queries: BatchQuery[], options?: BatchOptions): Promise<BatchSummary>;
+/**
+ * Execute multiple queries and return only successful results.
+ *
+ * Failed queries are silently ignored (but logged if a logger is provided).
+ *
+ * @param conn - Connection to use
+ * @param queries - Array of queries to execute
+ * @param options - Batch execution options
+ * @returns Array of successful row results
+ */
+declare function batchAll(conn: Connection, queries: BatchQuery[], options?: BatchOptions): Promise<Record<string, unknown>[][]>;
+/**
+ * Execute queries and return the first successful result.
+ *
+ * Useful for trying multiple query variants.
+ *
+ * @param conn - Connection to use
+ * @param queries - Array of queries to try
+ * @param options - Batch execution options
+ * @returns First successful result or null
+ */
+declare function batchFirst(conn: Connection, queries: BatchQuery[], options?: Omit<BatchOptions, 'stopOnError'>): Promise<Record<string, unknown>[] | null>;
+/**
+ * Execute a query for each item in an array.
+ *
+ * @param conn - Connection to use
+ * @param queryTemplate - Query with $item parameter placeholder
+ * @param items - Array of items to substitute
+ * @param options - Batch execution options
+ * @returns Batch summary
+ *
+ * @example
+ * ```typescript
+ * const summary = await batchMap(
+ *   conn,
+ *   'CREATE (n:Person {name: $name})',
+ *   [{ name: 'Alice' }, { name: 'Bob' }]
+ * );
+ * ```
+ */
+declare function batchMap(conn: Connection, queryTemplate: string, items: QueryParams[], options?: BatchOptions): Promise<BatchSummary>;
+/**
+ * Execute queries in parallel with limited concurrency.
+ *
+ * Unlike the sequential batch(), this executes multiple queries concurrently
+ * up to the specified limit.
+ *
+ * Note: Results may be returned out of order.
+ *
+ * @param conn - Connection to use
+ * @param queries - Array of queries to execute
+ * @param options - Batch execution options with concurrency
+ * @returns Batch summary (results in completion order)
+ */
+declare function batchParallel(conn: Connection, queries: BatchQuery[], options?: BatchOptions & {
+    concurrency: number;
+}): Promise<BatchSummary>;
+
+/**
+ * Geode Connection
+ *
+ * Connection management and query execution.
+ */
+
+/**
+ * Query parameters type.
+ */
+type QueryParams = Record<string, unknown>;
+/**
+ * Query options.
+ */
+interface QueryOptions {
+    /** Query parameters */
+    params?: QueryParams;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+    /** Page size for result pagination */
+    pageSize?: number;
+}
+/**
+ * Connection to a Geode database.
+ */
+declare class Connection {
+    private _config;
+    private _transport;
+    private _state;
+    private _inTransaction;
+    private _activeResult;
+    private _requestId;
+    private constructor();
+    /**
+     * Create a new connection to the Geode server.
+     */
+    static connect(config: GeodeConfig): Promise<Connection>;
+    /**
+     * Create a connection with a custom transport (for testing).
+     */
+    static connectWithTransport(config: GeodeConfig, transport: Transport): Promise<Connection>;
+    /**
+     * Get connection configuration.
+     */
+    get config(): Readonly<GeodeConfig>;
+    /**
+     * Get current connection state.
+     */
+    get state(): ConnectionState;
+    /**
+     * Check if connection is in a transaction.
+     */
+    get inTransaction(): boolean;
+    /**
+     * Check if connection is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Perform the HELLO handshake.
+     *
+     * Note: The server may return an ERROR frame with "Authentication required"
+     * even when no authentication is configured. This is a known server behavior
+     * that should be treated as a successful connection (matching other clients).
+     */
+    private hello;
+    /**
+     * Execute a query that returns rows.
+     */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and return all rows as an array.
+     */
+    queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a query that doesn't return rows.
+     */
+    exec(query: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Fetch the next page of results (internal).
+     */
+    _fetchNextPage(pageSize: number, signal?: AbortSignal): Promise<{
+        rows: Record<string, unknown>[];
+        final: boolean;
+    }>;
+    private _tryReceiveInlineFrame;
+    /**
+     * Release active result (internal).
+     */
+    _releaseResult(result: QueryResult): void;
+    /**
+     * Begin a transaction.
+     */
+    begin(signal?: AbortSignal): Promise<Transaction>;
+    /**
+     * Commit the current transaction (internal).
+     */
+    _commit(signal?: AbortSignal): Promise<void>;
+    /**
+     * Rollback the current transaction (internal).
+     */
+    _rollback(signal?: AbortSignal): Promise<void>;
+    /**
+     * Create a savepoint (internal).
+     */
+    _savepoint(name: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Rollback to a savepoint (internal).
+     */
+    _rollbackTo(name: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Ping the server to check connection health.
+     */
+    ping(signal?: AbortSignal): Promise<void>;
+    /**
+     * Reset the connection session.
+     */
+    reset(signal?: AbortSignal): Promise<void>;
+    /**
+     * Close the connection.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a prepared statement.
+     *
+     * @param query - Query text with parameters
+     * @returns Prepared statement
+     */
+    prepare(query: string): Promise<PreparedStatement>;
+    /**
+     * Get the query execution plan without executing.
+     *
+     * @param query - Query to explain
+     * @param options - Options including parameters
+     * @returns Query execution plan
+     */
+    explain(query: string, options?: ExplainOptions): Promise<QueryPlan>;
+    /**
+     * Execute a query with profiling.
+     *
+     * @param query - Query to profile
+     * @param options - Options including parameters
+     * @returns Query execution profile
+     */
+    profile(query: string, options?: ExplainOptions): Promise<QueryProfile>;
+    /**
+     * Execute multiple queries in a batch.
+     *
+     * @param queries - Array of queries to execute
+     * @param options - Batch execution options
+     * @returns Batch execution summary
+     */
+    batch(queries: BatchQuery[], options?: BatchOptions): Promise<BatchSummary>;
+    /**
+     * Check connection state before operation.
+     */
+    private checkState;
+}
+
+/**
+ * Authentication and Authorization Client
+ *
+ * Support for user management, role-based access control, and row-level security.
+ */
+
+/**
+ * User information.
+ */
+interface User {
+    /** Username */
+    username: string;
+    /** User roles */
+    roles: string[];
+    /** Whether the user is active */
+    active: boolean;
+    /** Creation timestamp */
+    createdAt?: Date;
+    /** Last login timestamp */
+    lastLoginAt?: Date;
+    /** User metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Role information.
+ */
+interface Role {
+    /** Role name */
+    name: string;
+    /** Role description */
+    description?: string;
+    /** Permissions granted to this role */
+    permissions: Permission[];
+    /** Whether the role is a system role */
+    system?: boolean;
+}
+/**
+ * Permission definition.
+ */
+interface Permission {
+    /** Resource type (e.g., 'NODE', 'EDGE', 'GRAPH') */
+    resource: string;
+    /** Action allowed (e.g., 'READ', 'WRITE', 'DELETE') */
+    action: string;
+    /** Optional label filter */
+    label?: string;
+    /** Optional property filters */
+    properties?: string[];
+}
+/**
+ * Row-Level Security (RLS) policy.
+ */
+interface RLSPolicy {
+    /** Policy name */
+    name: string;
+    /** Target label */
+    label: string;
+    /** Policy action ('READ', 'WRITE', 'ALL') */
+    action: 'READ' | 'WRITE' | 'ALL';
+    /** GQL predicate expression */
+    predicate: string;
+    /** Roles this policy applies to */
+    roles?: string[];
+    /** Whether the policy is enabled */
+    enabled: boolean;
+}
+/**
+ * Options for creating a user.
+ */
+interface CreateUserOptions {
+    /** Initial password */
+    password: string;
+    /** Roles to assign */
+    roles?: string[];
+    /** User metadata */
+    metadata?: Record<string, unknown>;
+    /** Whether to activate immediately */
+    active?: boolean;
+}
+/**
+ * Options for creating a role.
+ */
+interface CreateRoleOptions {
+    /** Role description */
+    description?: string;
+    /** Initial permissions */
+    permissions?: Permission[];
+}
+/**
+ * Options for creating an RLS policy.
+ */
+interface CreateRLSPolicyOptions {
+    /** Roles to apply policy to (empty = all roles) */
+    roles?: string[];
+    /** Whether to enable immediately */
+    enabled?: boolean;
+}
+/**
+ * Authentication and authorization client.
+ *
+ * Provides methods for managing users, roles, and row-level security policies.
+ *
+ * @example
+ * ```typescript
+ * const auth = new AuthClient(conn);
+ *
+ * // Create a user
+ * await auth.createUser('alice', { password: 'secret123' });
+ *
+ * // Create a role
+ * await auth.createRole('analyst', {
+ *   permissions: [{ resource: 'NODE', action: 'READ' }]
+ * });
+ *
+ * // Assign role to user
+ * await auth.assignRole('alice', 'analyst');
+ * ```
+ */
+declare class AuthClient {
+    private _conn;
+    /**
+     * Create a new auth client.
+     *
+     * @param conn - Connection to use
+     */
+    constructor(conn: Connection);
+    /**
+     * Create a new user.
+     *
+     * @param username - Username for the new user
+     * @param options - User creation options
+     */
+    createUser(username: string, options: CreateUserOptions): Promise<void>;
+    /**
+     * Delete a user.
+     *
+     * @param username - Username to delete
+     */
+    deleteUser(username: string): Promise<void>;
+    /**
+     * Get user information.
+     *
+     * @param username - Username to look up
+     * @returns User information or null if not found
+     */
+    getUser(username: string): Promise<User | null>;
+    /**
+     * List all users.
+     *
+     * @returns Array of users
+     */
+    listUsers(): Promise<User[]>;
+    /**
+     * Change a user's password.
+     *
+     * @param username - Username
+     * @param newPassword - New password
+     */
+    changePassword(username: string, newPassword: string): Promise<void>;
+    /**
+     * Activate a user.
+     *
+     * @param username - Username to activate
+     */
+    activateUser(username: string): Promise<void>;
+    /**
+     * Deactivate a user.
+     *
+     * @param username - Username to deactivate
+     */
+    deactivateUser(username: string): Promise<void>;
+    /**
+     * Create a new role.
+     *
+     * @param name - Role name
+     * @param options - Role creation options
+     */
+    createRole(name: string, options?: CreateRoleOptions): Promise<void>;
+    /**
+     * Delete a role.
+     *
+     * @param name - Role name to delete
+     */
+    deleteRole(name: string): Promise<void>;
+    /**
+     * Get role information.
+     *
+     * @param name - Role name
+     * @returns Role information or null if not found
+     */
+    getRole(name: string): Promise<Role | null>;
+    /**
+     * List all roles.
+     *
+     * @returns Array of roles
+     */
+    listRoles(): Promise<Role[]>;
+    /**
+     * Assign a role to a user.
+     *
+     * @param username - Username
+     * @param roleName - Role to assign
+     */
+    assignRole(username: string, roleName: string): Promise<void>;
+    /**
+     * Revoke a role from a user.
+     *
+     * @param username - Username
+     * @param roleName - Role to revoke
+     */
+    revokeRole(username: string, roleName: string): Promise<void>;
+    /**
+     * Grant a permission to a role.
+     *
+     * @param roleName - Role name
+     * @param permission - Permission to grant
+     */
+    grantPermission(roleName: string, permission: Permission): Promise<void>;
+    /**
+     * Revoke a permission from a role.
+     *
+     * @param roleName - Role name
+     * @param permission - Permission to revoke
+     */
+    revokePermission(roleName: string, permission: Permission): Promise<void>;
+    /**
+     * Create an RLS policy.
+     *
+     * @param name - Policy name
+     * @param label - Target label
+     * @param action - Policy action
+     * @param predicate - GQL predicate expression
+     * @param options - Additional options
+     */
+    createRLSPolicy(name: string, label: string, action: 'READ' | 'WRITE' | 'ALL', predicate: string, options?: CreateRLSPolicyOptions): Promise<void>;
+    /**
+     * Delete an RLS policy.
+     *
+     * @param name - Policy name
+     * @param label - Target label
+     */
+    deleteRLSPolicy(name: string, label: string): Promise<void>;
+    /**
+     * Get RLS policy information.
+     *
+     * @param name - Policy name
+     * @returns Policy information or null if not found
+     */
+    getRLSPolicy(name: string): Promise<RLSPolicy | null>;
+    /**
+     * List all RLS policies.
+     *
+     * @param label - Optional label to filter by
+     * @returns Array of policies
+     */
+    listRLSPolicies(label?: string): Promise<RLSPolicy[]>;
+    /**
+     * Enable an RLS policy.
+     *
+     * @param name - Policy name
+     * @param label - Target label
+     */
+    enableRLSPolicy(name: string, label: string): Promise<void>;
+    /**
+     * Disable an RLS policy.
+     *
+     * @param name - Policy name
+     * @param label - Target label
+     */
+    disableRLSPolicy(name: string, label: string): Promise<void>;
+    /**
+     * Get the current session user.
+     *
+     * @returns Current username
+     */
+    currentUser(): Promise<string>;
+    /**
+     * Get the current session roles.
+     *
+     * @returns Current roles
+     */
+    currentRoles(): Promise<string[]>;
+    /**
+     * Check if the current session has a specific permission.
+     *
+     * @param resource - Resource type
+     * @param action - Action to check
+     * @param label - Optional label filter
+     * @returns Whether permission is granted
+     */
+    hasPermission(resource: string, action: string, label?: string): Promise<boolean>;
+    private validateUsername;
+    private validatePassword;
+    private validateRoleName;
+    private validatePolicyName;
+}
+/**
+ * Create an auth client from a connection.
+ */
+declare function createAuthClient(conn: Connection): AuthClient;
+
+/**
+ * Geode Client
+ *
+ * High-level client for interacting with Geode graph database.
+ */
+
+/**
+ * Client configuration options.
+ */
+interface ClientOptions extends Partial<GeodeConfig> {
+    /** Use connection pooling */
+    pooling?: boolean;
+    /** Pool-specific options */
+    pool?: {
+        min?: number;
+        max?: number;
+        acquireTimeout?: number;
+        idleTimeout?: number;
+    };
+}
+/**
+ * Geode Client - main entry point for database operations.
+ */
+declare class GeodeClient {
+    private _config;
+    private _pool?;
+    private _connection?;
+    private constructor();
+    /**
+     * Create a new client from a DSN string.
+     */
+    static connect(dsn: string, options?: ClientOptions): Promise<GeodeClient>;
+    /**
+     * Create a new client from configuration.
+     */
+    static connectWithConfig(config: GeodeConfig, options?: ClientOptions): Promise<GeodeClient>;
+    /**
+     * Get the client configuration.
+     */
+    get config(): Readonly<GeodeConfig>;
+    /**
+     * Check if client is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Get pool statistics (if using pooling).
+     */
+    get poolStats(): {
+        total: number;
+        available: number;
+        inUse: number;
+        waiting: number;
+    } | null;
+    /**
+     * Execute a query and return results.
+     */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and return all rows as objects.
+     */
+    queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a query and return the first row.
+     */
+    queryFirst(query: string, options?: QueryOptions): Promise<Record<string, unknown> | null>;
+    /**
+     * Execute a query and return a scalar value.
+     */
+    queryScalar<T = unknown>(query: string, column: string, options?: QueryOptions): Promise<T | null>;
+    /**
+     * Execute a statement that doesn't return rows.
+     */
+    exec(query: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Execute multiple statements.
+     */
+    execBatch(queries: Array<{
+        query: string;
+        params?: QueryParams;
+    }>): Promise<void>;
+    /**
+     * Execute a function within a transaction.
+     */
+    withTransaction<T>(fn: (tx: Transaction) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Get a raw connection from the pool (or the single connection).
+     *
+     * The connection must be released after use.
+     */
+    getConnection(signal?: AbortSignal): Promise<Connection>;
+    /**
+     * Release a connection back to the pool.
+     *
+     * Only needed when using getConnection() with pooling.
+     */
+    releaseConnection(conn: Connection): Promise<void>;
+    /**
+     * Execute a function with a dedicated connection.
+     */
+    withConnection<T>(fn: (conn: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Ping the server to check connectivity.
+     */
+    ping(signal?: AbortSignal): Promise<void>;
+    /**
+     * Close the client and release all resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Create a node with labels and properties.
+     */
+    createNode(labels: string | string[], properties?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Find nodes by label and optional property filter.
+     */
+    findNodes(label: string, filter?: Record<string, unknown>, options?: {
+        limit?: number;
+        skip?: number;
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Find a single node by label and property.
+     */
+    findNode(label: string, property: string, value: unknown): Promise<Record<string, unknown> | null>;
+    /**
+     * Create a relationship between two nodes.
+     */
+    createRelationship(startLabel: string, startProp: string, startValue: unknown, type: string, endLabel: string, endProp: string, endValue: unknown, properties?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Delete a node by label and property.
+     */
+    deleteNode(label: string, property: string, value: unknown): Promise<number>;
+    /**
+     * Update node properties.
+     */
+    updateNode(label: string, matchProp: string, matchValue: unknown, updates: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /**
+     * Count nodes by label.
+     */
+    countNodes(label: string, filter?: Record<string, unknown>): Promise<number>;
+    /**
+     * Create a prepared statement.
+     *
+     * @param query - Query text with parameters
+     * @returns Prepared statement
+     *
+     * @example
+     * ```typescript
+     * const stmt = client.prepare('MATCH (n:Person {name: $name}) RETURN n');
+     * const result1 = await stmt.query({ name: 'Alice' });
+     * const result2 = await stmt.query({ name: 'Bob' });
+     * stmt.close();
+     * ```
+     */
+    prepare(query: string): Promise<PreparedStatement>;
+    /**
+     * Get the query execution plan without executing.
+     *
+     * @param query - Query to explain
+     * @param options - Options including parameters
+     * @returns Query execution plan
+     *
+     * @example
+     * ```typescript
+     * const plan = await client.explain('MATCH (n:Person)-[:KNOWS]->(m) RETURN n, m');
+     * console.log('Estimated cost:', plan.totalCost);
+     * ```
+     */
+    explain(query: string, options?: ExplainOptions): Promise<QueryPlan>;
+    /**
+     * Execute a query with profiling.
+     *
+     * @param query - Query to profile
+     * @param options - Options including parameters
+     * @returns Query execution profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.profile('MATCH (n:Person) RETURN count(n)');
+     * console.log('Execution time:', profile.totalTimeMs, 'ms');
+     * ```
+     */
+    profile(query: string, options?: ExplainOptions): Promise<QueryProfile>;
+    /**
+     * Execute multiple queries in a batch.
+     *
+     * @param queries - Array of queries to execute
+     * @param options - Batch execution options
+     * @returns Batch execution summary
+     *
+     * @example
+     * ```typescript
+     * const summary = await client.batch([
+     *   { query: 'CREATE (a:Person {name: "Alice"})' },
+     *   { query: 'CREATE (b:Person {name: "Bob"})' },
+     * ]);
+     * console.log(`${summary.successful}/${summary.total} succeeded`);
+     * ```
+     */
+    batch(queries: BatchQuery[], options?: BatchOptions): Promise<BatchSummary>;
+    /**
+     * Get an auth client for user and role management.
+     *
+     * @returns Auth client
+     *
+     * @example
+     * ```typescript
+     * const auth = await client.auth();
+     * await auth.createUser('alice', { password: 'secret123' });
+     * await auth.assignRole('alice', 'analyst');
+     * ```
+     */
+    auth(): Promise<AuthClient>;
+}
+/**
+ * Create a Geode client from a DSN string.
+ *
+ * @example
+ * ```typescript
+ * const client = await createClient('geode://localhost:3141');
+ * const rows = await client.queryAll('MATCH (n) RETURN n LIMIT 10');
+ * await client.close();
+ * ```
+ */
+declare function createClient(dsn: string, options?: ClientOptions): Promise<GeodeClient>;
+/**
+ * Create a Geode client from configuration.
+ */
+declare function createClientWithConfig(config: GeodeConfig, options?: ClientOptions): Promise<GeodeClient>;
+
+/**
+ * Connection Pool
+ *
+ * Manages a pool of connections for efficient resource utilization.
+ */
+
+/**
+ * Connection pool for managing multiple connections.
+ */
+declare class ConnectionPool {
+    private _config;
+    private _connections;
+    private _waitQueue;
+    private _closed;
+    private _maintenanceInterval?;
+    private _minConnections;
+    private _maxConnections;
+    private _acquireTimeout;
+    private _idleTimeout;
+    constructor(config: PoolConfig);
+    /**
+     * Create a new connection pool.
+     */
+    static create(config: PoolConfig): Promise<ConnectionPool>;
+    /**
+     * Get pool statistics.
+     */
+    get stats(): {
+        total: number;
+        available: number;
+        inUse: number;
+        waiting: number;
+    };
+    /**
+     * Check if pool is closed.
+     */
+    get isClosed(): boolean;
+    /**
+     * Acquire a connection from the pool.
+     */
+    acquire(signal?: AbortSignal): Promise<Connection>;
+    /**
+     * Release a connection back to the pool.
+     */
+    release(conn: Connection): Promise<void>;
+    /**
+     * Execute a function with a connection from the pool.
+     */
+    withConnection<T>(fn: (conn: Connection) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Execute a query using a pooled connection.
+     */
+    query(query: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and return all rows.
+     */
+    queryAll(query: string, options?: QueryOptions): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a statement that doesn't return rows.
+     */
+    exec(query: string, options?: QueryOptions): Promise<void>;
+    /**
+     * Execute a function within a transaction.
+     */
+    withTransaction<T>(fn: (tx: Transaction) => Promise<T>, signal?: AbortSignal): Promise<T>;
+    /**
+     * Ping to verify pool health.
+     */
+    ping(signal?: AbortSignal): Promise<void>;
+    /**
+     * Close the pool and all connections.
+     */
+    close(): Promise<void>;
+    /**
+     * Add a new connection to the pool.
+     */
+    private addConnection;
+    /**
+     * Remove a connection from the pool.
+     */
+    private removeConnection;
+    /**
+     * Perform pool maintenance.
+     */
+    private maintenance;
+}
+
+/**
+ * Geode Wire Protocol
+ *
+ * JSON line protocol implementation for communication with Geode server.
+ */
+
+declare const MsgType: {
+    readonly HELLO: "HELLO";
+    readonly RUN_GQL: "RUN_GQL";
+    readonly PULL: "PULL";
+    readonly BEGIN: "BEGIN";
+    readonly COMMIT: "COMMIT";
+    readonly ROLLBACK: "ROLLBACK";
+    readonly SAVEPOINT: "SAVEPOINT";
+    readonly ROLLBACK_TO: "ROLLBACK_TO";
+    readonly PING: "PING";
+};
+type MsgType = (typeof MsgType)[keyof typeof MsgType];
+declare const RespType: {
+    readonly HELLO: "HELLO";
+    readonly SCHEMA: "SCHEMA";
+    readonly BINDINGS: "BINDINGS";
+    readonly ERROR: "ERROR";
+    readonly EXPLAIN: "EXPLAIN";
+    readonly PROFILE: "PROFILE";
+    readonly RESULT: "RESULT";
+    readonly STATUS: "STATUS";
+};
+type RespType = (typeof RespType)[keyof typeof RespType];
+/**
+ * Additional diagnostic information from error frames.
+ */
+interface AdditionalInfo {
+    code?: string;
+    message?: string;
+}
+/**
+ * Frame result structure.
+ */
+interface FrameResult {
+    type: RespType;
+    columns?: ColumnDef[];
+    rows?: Record<string, unknown>[];
+    ordered?: boolean;
+    order_keys?: string[];
+    final?: boolean;
+    code?: string;
+    message?: string;
+    anchor?: string;
+    additional?: AdditionalInfo[];
+    flagger_findings?: string[];
+    json?: unknown;
+}
+/**
+ * Wire protocol frame structure.
+ */
+interface Frame {
+    status_class: string;
+    status_subclass: string;
+    result: FrameResult;
+}
+/**
+ * Parse a JSON frame from raw bytes.
+ */
+declare function parseFrame(data: Buffer | string): Frame;
+/**
+ * Check if a frame represents an error.
+ */
+declare function isErrorFrame(frame: Frame): boolean;
+/**
+ * Check if a frame represents a schema.
+ */
+declare function isSchemaFrame(frame: Frame): boolean;
+/**
+ * Check if a frame represents bindings (rows).
+ */
+declare function isBindingsFrame(frame: Frame): boolean;
+/**
+ * Check if a frame is the final frame in a result set.
+ */
+declare function isFinalFrame(frame: Frame): boolean;
+/**
+ * Convert an error frame to a DriverError.
+ */
+declare function frameToError(frame: Frame): DriverError;
+/**
+ * Get column info from a schema frame.
+ */
+declare function getColumnsFromSchema(frame: Frame): ColumnInfo[];
+/**
+ * Build a HELLO message.
+ */
+declare function buildHelloMessage(cfg: GeodeConfig): Record<string, unknown>;
+/**
+ * Build a RUN_GQL message.
+ */
+declare function buildRunGQLMessage(query: string, params?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Build a PULL message.
+ */
+declare function buildPullMessage(requestId: number, pageSize: number): Record<string, unknown>;
+/**
+ * Build a BEGIN message.
+ */
+declare function buildBeginMessage(): Record<string, unknown>;
+/**
+ * Build a COMMIT message.
+ */
+declare function buildCommitMessage(): Record<string, unknown>;
+/**
+ * Build a ROLLBACK message.
+ */
+declare function buildRollbackMessage(): Record<string, unknown>;
+/**
+ * Build a SAVEPOINT message.
+ */
+declare function buildSavepointMessage(name: string): Record<string, unknown>;
+/**
+ * Build a ROLLBACK_TO message.
+ */
+declare function buildRollbackToMessage(name: string): Record<string, unknown>;
+/**
+ * Build a PING message.
+ */
+declare function buildPingMessage(): Record<string, unknown>;
+/**
+ * Serialize a message to JSON line format.
+ */
+declare function serializeMessage(msg: Record<string, unknown>): Buffer;
+/**
+ * Rewrite positional placeholders (?) to named parameters ($p1, $p2, ...).
+ */
+declare function rewritePlaceholders(query: string, args: unknown[]): {
+    query: string;
+    params: Record<string, unknown>;
+};
+/**
+ * Count the number of ? placeholders in a query.
+ */
+declare function countPlaceholders(query: string): number;
+/**
+ * Merge named parameters with positional parameters.
+ */
+declare function mergeParams(positionalParams: Record<string, unknown>, namedParams?: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Input Validation Module
+ *
+ * Security-focused validation for user inputs to prevent injection attacks.
+ */
+/**
+ * Validate a GQL query string.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validateQuery(query: string): void;
+/**
+ * Validate a parameter name.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validateParamName(name: string): void;
+/**
+ * Validate a parameter value.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validateParamValue(value: unknown): void;
+/**
+ * Validate a hostname.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validateHostname(hostname: string): void;
+/**
+ * Validate a port number.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validatePort(port: number): void;
+/**
+ * Validate a page size.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validatePageSize(pageSize: number): void;
+/**
+ * Validate a savepoint name.
+ *
+ * @throws SecurityError if validation fails
+ */
+declare function validateSavepointName(name: string): void;
+/**
+ * Sanitize a string for safe logging (remove sensitive data patterns).
+ */
+declare function sanitizeForLog(value: string): string;
+
+/**
+ * Query Builder
+ *
+ * Fluent API for building GQL queries programmatically.
+ */
+
+/**
+ * Edge direction for pattern matching.
+ */
+type EdgeDirection = 'outgoing' | 'incoming' | 'both';
+/**
+ * Sort direction.
+ */
+type SortDirection = 'ASC' | 'DESC';
+/**
+ * Predicate operator.
+ */
+type PredicateOp = '=' | '<>' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'CONTAINS' | 'STARTS WITH' | 'ENDS WITH' | 'IS NULL' | 'IS NOT NULL';
+/**
+ * Node pattern for MATCH clauses.
+ */
+interface NodePattern {
+    variable?: string;
+    labels?: string[];
+    properties?: Record<string, unknown>;
+}
+/**
+ * Edge pattern for MATCH clauses.
+ */
+interface EdgePattern {
+    variable?: string;
+    type?: string;
+    direction: EdgeDirection;
+    properties?: Record<string, unknown>;
+    minHops?: number;
+    maxHops?: number;
+}
+/**
+ * Pattern element (node or edge).
+ */
+type PatternElement = {
+    kind: 'node';
+    pattern: NodePattern;
+} | {
+    kind: 'edge';
+    pattern: EdgePattern;
+};
+/**
+ * Build a node pattern.
+ */
+declare class NodePatternBuilder {
+    private _variable?;
+    private _labels;
+    private _properties;
+    /**
+     * Set the variable name.
+     */
+    as(variable: string): this;
+    /**
+     * Add a label.
+     */
+    label(label: string): this;
+    /**
+     * Add multiple labels.
+     */
+    labels(...labels: string[]): this;
+    /**
+     * Set a property.
+     */
+    prop(key: string, value: unknown): this;
+    /**
+     * Set multiple properties.
+     */
+    props(properties: Record<string, unknown>): this;
+    /**
+     * Build the pattern.
+     */
+    build(): NodePattern;
+    /**
+     * Convert to GQL string.
+     */
+    toGQL(): string;
+}
+/**
+ * Build an edge pattern.
+ */
+declare class EdgePatternBuilder {
+    private _variable?;
+    private _type?;
+    private _direction;
+    private _properties;
+    private _minHops?;
+    private _maxHops?;
+    /**
+     * Set the variable name.
+     */
+    as(variable: string): this;
+    /**
+     * Set the relationship type.
+     */
+    type(type: string): this;
+    /**
+     * Set outgoing direction.
+     */
+    outgoing(): this;
+    /**
+     * Set incoming direction.
+     */
+    incoming(): this;
+    /**
+     * Set bidirectional.
+     */
+    both(): this;
+    /**
+     * Set direction.
+     */
+    direction(dir: EdgeDirection): this;
+    /**
+     * Set a property.
+     */
+    prop(key: string, value: unknown): this;
+    /**
+     * Set multiple properties.
+     */
+    props(properties: Record<string, unknown>): this;
+    /**
+     * Set variable length path.
+     */
+    hops(min?: number, max?: number): this;
+    /**
+     * Build the pattern.
+     */
+    build(): EdgePattern;
+    /**
+     * Convert to GQL string.
+     */
+    toGQL(): string;
+}
+/**
+ * Build a path pattern.
+ */
+declare class PatternBuilder {
+    private _elements;
+    /**
+     * Add a node to the pattern.
+     */
+    node(builder?: (n: NodePatternBuilder) => void): this;
+    /**
+     * Add an outgoing edge to the pattern.
+     */
+    outgoing(builder?: (e: EdgePatternBuilder) => void): this;
+    /**
+     * Add an incoming edge to the pattern.
+     */
+    incoming(builder?: (e: EdgePatternBuilder) => void): this;
+    /**
+     * Add a bidirectional edge to the pattern.
+     */
+    related(builder?: (e: EdgePatternBuilder) => void): this;
+    /**
+     * Convert to GQL string.
+     */
+    toGQL(): string;
+}
+/**
+ * Build a predicate for WHERE clauses.
+ */
+declare class PredicateBuilder {
+    private _predicates;
+    private _params;
+    private _paramCounter;
+    /**
+     * Add a comparison predicate.
+     */
+    compare(left: string, op: PredicateOp, right: unknown): this;
+    /**
+     * Add an equality predicate.
+     */
+    eq(left: string, right: unknown): this;
+    /**
+     * Add a not-equal predicate.
+     */
+    neq(left: string, right: unknown): this;
+    /**
+     * Add a less-than predicate.
+     */
+    lt(left: string, right: unknown): this;
+    /**
+     * Add a less-than-or-equal predicate.
+     */
+    lte(left: string, right: unknown): this;
+    /**
+     * Add a greater-than predicate.
+     */
+    gt(left: string, right: unknown): this;
+    /**
+     * Add a greater-than-or-equal predicate.
+     */
+    gte(left: string, right: unknown): this;
+    /**
+     * Add an IN predicate.
+     */
+    in(left: string, values: unknown[]): this;
+    /**
+     * Add a NOT IN predicate.
+     */
+    notIn(left: string, values: unknown[]): this;
+    /**
+     * Add a CONTAINS predicate.
+     */
+    contains(left: string, value: string): this;
+    /**
+     * Add a STARTS WITH predicate.
+     */
+    startsWith(left: string, value: string): this;
+    /**
+     * Add an ENDS WITH predicate.
+     */
+    endsWith(left: string, value: string): this;
+    /**
+     * Add an IS NULL predicate.
+     */
+    isNull(expr: string): this;
+    /**
+     * Add an IS NOT NULL predicate.
+     */
+    isNotNull(expr: string): this;
+    /**
+     * Add a raw predicate expression.
+     */
+    raw(expr: string, params?: QueryParams): this;
+    /**
+     * Combine predicates with AND.
+     */
+    and(builder: PredicateBuilder): this;
+    /**
+     * Combine predicates with OR.
+     */
+    or(builder: PredicateBuilder): this;
+    /**
+     * Build the predicate.
+     */
+    build(): {
+        predicate: string;
+        params: QueryParams;
+    };
+    private nextParam;
+}
+/**
+ * GQL Query Builder.
+ */
+declare class QueryBuilder {
+    private _clauses;
+    private _params;
+    /**
+     * Add a MATCH clause.
+     */
+    match(pattern: string | PatternBuilder): this;
+    /**
+     * Add an OPTIONAL MATCH clause.
+     */
+    optionalMatch(pattern: string | PatternBuilder): this;
+    /**
+     * Add a WHERE clause.
+     */
+    where(predicate: string | PredicateBuilder, params?: QueryParams): this;
+    /**
+     * Add a WITH clause.
+     */
+    with(...expressions: string[]): this;
+    /**
+     * Add a RETURN clause.
+     */
+    return(...expressions: string[]): this;
+    /**
+     * Add RETURN DISTINCT.
+     */
+    returnDistinct(...expressions: string[]): this;
+    /**
+     * Add an ORDER BY clause.
+     */
+    orderBy(...expressions: Array<string | [string, SortDirection]>): this;
+    /**
+     * Add a SKIP clause.
+     */
+    skip(count: number): this;
+    /**
+     * Add a LIMIT clause.
+     */
+    limit(count: number): this;
+    /**
+     * Add a CREATE clause.
+     */
+    create(pattern: string | PatternBuilder): this;
+    /**
+     * Add a MERGE clause.
+     */
+    merge(pattern: string | PatternBuilder): this;
+    /**
+     * Add a DELETE clause.
+     */
+    delete(...variables: string[]): this;
+    /**
+     * Add a DETACH DELETE clause.
+     */
+    detachDelete(...variables: string[]): this;
+    /**
+     * Add a SET clause.
+     */
+    set(...assignments: string[]): this;
+    /**
+     * Add a REMOVE clause.
+     */
+    remove(...items: string[]): this;
+    /**
+     * Add raw clause.
+     */
+    raw(clause: string, params?: QueryParams): this;
+    /**
+     * Add a parameter.
+     */
+    param(name: string, value: unknown): this;
+    /**
+     * Add multiple parameters.
+     */
+    params(params: QueryParams): this;
+    /**
+     * Build the query string.
+     */
+    build(): {
+        query: string;
+        params: QueryParams;
+    };
+    /**
+     * Get the query string.
+     */
+    toGQL(): string;
+    /**
+     * Get the parameters.
+     */
+    getParams(): QueryParams;
+}
+/**
+ * Create a new QueryBuilder.
+ */
+declare function query(): QueryBuilder;
+/**
+ * Create a new PatternBuilder.
+ */
+declare function pattern(): PatternBuilder;
+/**
+ * Create a new PredicateBuilder.
+ */
+declare function predicate(): PredicateBuilder;
+/**
+ * Create a new NodePatternBuilder.
+ */
+declare function node(): NodePatternBuilder;
+/**
+ * Create a new EdgePatternBuilder.
+ */
+declare function edge(): EdgePatternBuilder;
+
+export { type AdditionalInfo, AuthClient, BaseTransport, type BatchOptions, type BatchQuery, type BatchResult, type BatchSummary, type ClientOptions, type ColumnDef, type ColumnInfo, ConfigError, Connection, ConnectionPool, type ConnectionState, type CreateRLSPolicyOptions, type CreateRoleOptions, type CreateUserOptions, DEFAULT_CONFORMANCE, DEFAULT_HELLO_NAME, DEFAULT_HELLO_VERSION, DEFAULT_PAGE_SIZE, DEFAULT_PORT, DriverError, type EdgeDirection, type EdgePattern, EdgePatternBuilder, ErrBadConn, ErrClosed, ErrNoTx, ErrQueryInProgress, ErrRowsClosed, ErrTxDone, ErrTxInProgress, type ExplainOptions, type Frame, type FrameResult, type GQLEdge, type GQLNode, type GQLPath, type GQLRange, type GQLType, GQLValue, type GQLValueKind, GeodeClient, type GeodeConfig, type GeodeError, MAX_PAGE_SIZE, MAX_QUERY_LENGTH, MockTransport, MsgType, type NodePattern, NodePatternBuilder, type OperationTiming, type ParameterInfo, PatternBuilder, type PatternElement, type Permission, type PlanOperation, type PoolConfig, PredicateBuilder, type PredicateOp, PreparedStatement, QueryBuilder, type QueryOptions, type QueryParams, type QueryPlan, type QueryProfile, QueryResult, QueryResultIterator, MatrixQuicTransport as QuicheTransport, type RLSPolicy, RespType, type Role, type Row, SecurityError, type SortDirection, StateError, StatusClass, type StatusClassType, Transaction, type Transport, TransportError, type User, batch, batchAll, batchFirst, batchMap, batchParallel, buildBeginMessage, buildCommitMessage, buildHelloMessage, buildPingMessage, buildPullMessage, buildRollbackMessage, buildRollbackToMessage, buildRunGQLMessage, buildSavepointMessage, buildTLSConfig, cloneConfig, countPlaceholders, createAuthClient, createClient, createClientWithConfig, createTransport, defaultConfig, edge, explain, extractParameters, formatPlan, formatProfile, frameToError, fromJSON, getAddress, getColumnsFromSchema, isBindingsFrame, isDriverError, isErrorFrame, isFinalFrame, isGeodeError, isRetryableError, isSchemaFrame, mergeParams, node, parseDSN, parseFrame, parseGQLType, parseRow, pattern, predicate, prepare, profile, query, rewritePlaceholders, rowToObject, sanitizeForLog, serializeMessage, validateConfig, validateHostname, validatePageSize, validateParamName, validateParamValue, validatePort, validateQuery, validateSavepointName, withTransaction };