@geodedb/client 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/index.d.ts

@@ -1,27 +1,42 @@
 import * as tls from 'node:tls';
-import Decimal from 'decimal.js-light';
+import { Decimal } from 'decimal.js-light';
 export { default as Decimal } from 'decimal.js-light';
 
 /**
  * Geode Client Configuration
  *
  * DSN parsing and configuration management.
+ * Supports quic:// and grpc:// transport schemes.
+ *
+ * See geode/docs/DSN.md for the complete DSN specification.
  */
 declare const DEFAULT_PORT = 3141;
+declare const DEFAULT_GRPC_PORT = 50051;
 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;
+/**
+ * Transport type for client connections.
+ */
+type TransportType = 'quic' | 'grpc';
+/**
+ * Supported DSN schemes.
+ */
+declare const SUPPORTED_SCHEMES: readonly ["quic", "grpc"];
+type DSNScheme = (typeof SUPPORTED_SCHEMES)[number];
 /**
  * Geode connection configuration.
  */
 interface GeodeConfig {
     /** Server hostname or IP address */
     host: string;
-    /** Server port (default: 3141) */
+    /** Server port (default: 3141 for QUIC, 50051 for gRPC) */
     port: number;
+    /** Transport type (default: 'quic') */
+    transport: TransportType;
     /** Number of rows per page (default: 1000) */
     pageSize: number;
     /** Client name sent in HELLO message */
@@ -58,14 +73,16 @@ interface GeodeConfig {
     keepAliveInterval?: number;
     /** Maximum idle time in milliseconds (default: 30000) */
     maxIdleTime?: number;
+    /** Enable TLS for gRPC (default: true) */
+    tls?: boolean;
 }
 /**
  * Connection pool configuration.
  */
 interface PoolConfig extends GeodeConfig {
-    /** Minimum number of connections in pool (default: 2) */
+    /** Minimum number of connections in pool (default: 1) */
     minConnections?: number;
-    /** Maximum number of connections in pool (default: 10) */
+    /** Maximum number of connections in pool (default: 3) */
     maxConnections?: number;
     /** Time to wait for connection in milliseconds (default: 30000) */
     acquireTimeout?: number;
@@ -80,9 +97,9 @@ 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
+ *   - quic://host:port?options (QUIC transport, default)
+ *   - grpc://host:port?options (gRPC transport)
+ *   - host:port?options (defaults to QUIC)
  *   - host:port
  *   - host (uses default port)
  *
@@ -97,6 +114,7 @@ declare function defaultConfig(): GeodeConfig;
  *   - cert: Path to client certificate (for mTLS)
  *   - key: Path to client key (for mTLS)
  *   - insecure: Skip TLS verification (testing only)
+ *   - tls: Enable/disable TLS for gRPC (default: true)
  *   - server_name: SNI server name
  *   - connect_timeout: Connection timeout in ms
  *   - request_timeout: Request timeout in ms
@@ -107,6 +125,7 @@ declare function defaultConfig(): GeodeConfig;
  *   - GEODE_TLS_CA: Default CA certificate path
  *   - GEODE_USERNAME: Default username
  *   - GEODE_PASSWORD: Default password
+ *   - GEODE_TRANSPORT: Default transport type (quic or grpc)
  */
 declare function parseDSN(dsn: string): GeodeConfig;
 /**
@@ -121,6 +140,28 @@ declare function getAddress(cfg: GeodeConfig): string;
  * Clone configuration.
  */
 declare function cloneConfig(cfg: GeodeConfig): GeodeConfig;
+/**
+ * Redact credentials from a DSN string for safe logging.
+ *
+ * Replaces username and password with '***' to prevent credential exposure
+ * in logs, error messages, or other output.
+ *
+ * @example
+ * ```typescript
+ * redactDSN('quic://admin:secret@localhost:3141')
+ * // Returns: 'quic://***:***@localhost:3141'
+ *
+ * redactDSN('grpc://localhost:50051?username=admin&password=secret')
+ * // Returns: 'grpc://localhost:50051?username=***&password=***'
+ * ```
+ */
+declare function redactDSN(dsn: string): string;
+/**
+ * Redact credentials from a configuration object for safe logging.
+ *
+ * Returns a new config object with password set to '***'.
+ */
+declare function redactConfig(cfg: GeodeConfig): GeodeConfig;
 
 /**
  * Geode Client Error Types
@@ -187,9 +228,6 @@ declare class TransportError extends Error implements GeodeError {
     });
     get isRetryable(): boolean;
 }
-/**
- * Configuration/DSN parsing error.
- */
 declare class ConfigError extends Error implements GeodeError {
     readonly statusClass: "22023";
     readonly field: string;
@@ -254,19 +292,359 @@ declare function isGeodeError(err: unknown): err is GeodeError;
 declare function isRetryableError(err: unknown): boolean;
 
 /**
- * QUIC Transport Layer
+ * Geode Protobuf Wire Protocol
+ *
+ * Uses protobufjs for encoding/decoding protocol messages.
+ * Wire format for QUIC: 4-byte Big Endian length prefix + protobuf message body.
+ */
+interface HelloRequest {
+    username: string;
+    password: string;
+    tenantId?: string;
+    clientName: string;
+    clientVersion: string;
+    wantedConformance: string;
+}
+interface HelloResponse {
+    success: boolean;
+    sessionId: string;
+    errorMessage: string;
+    capabilities: string[];
+}
+interface Param {
+    name: string;
+    value: ProtoValue;
+}
+interface ExecuteRequest {
+    sessionId: string;
+    query: string;
+    params: Param[];
+}
+interface PullRequest {
+    requestId: bigint | number;
+    pageSize: number;
+    sessionId: string;
+}
+interface PullResponse {
+    response?: ExecutionResponse;
+}
+interface Status {
+    statusClass: string;
+    statusSubclass: string;
+    additionalStatuses: string[];
+    flaggerFindings: string[];
+}
+interface ColumnDefinition {
+    name: string;
+    type: string;
+}
+interface SchemaDefinition {
+    columns: ColumnDefinition[];
+}
+interface ProtoValue {
+    nullVal?: NullValue;
+    intVal?: IntValue;
+    doubleVal?: DoubleValue;
+    boolVal?: boolean;
+    stringVal?: StringValue;
+    decimalVal?: DecimalValue;
+    bytesVal?: BytesValue;
+    listVal?: ListValue;
+    mapVal?: MapValue;
+    nodeVal?: NodeValue;
+    edgeVal?: EdgeValue;
+    pathVal?: PathValue;
+    extVal?: ExtendedValue;
+}
+interface NullValue {
+}
+interface IntValue {
+    value: bigint | number;
+    kind: number;
+}
+interface DoubleValue {
+    value: number;
+    kind: number;
+}
+interface StringValue {
+    value: string;
+    kind: number;
+}
+interface DecimalValue {
+    coeff: string;
+    scale: number;
+    origScale: number;
+    origRepr: string;
+}
+interface BytesValue {
+    value: Uint8Array;
+    kind: number;
+}
+interface ListValue {
+    values: ProtoValue[];
+}
+interface MapEntry {
+    key: string;
+    value: ProtoValue;
+}
+interface MapValue {
+    entries: MapEntry[];
+}
+interface NodeValue {
+    id: bigint | number;
+    labels: string[];
+    properties: MapEntry[];
+}
+interface EdgeValue {
+    id: bigint | number;
+    fromId: bigint | number;
+    toId: bigint | number;
+    label: string;
+    properties: MapEntry[];
+}
+interface PathValue {
+    nodes: NodeValue[];
+    edges: EdgeValue[];
+}
+interface ExtendedValue {
+    typeName: string;
+    text?: string;
+    bytes?: Uint8Array;
+    intVal?: bigint | number;
+    doubleVal?: number;
+    boolVal?: boolean;
+}
+interface Row$1 {
+    values: ProtoValue[];
+}
+interface DataPage {
+    rows: Row$1[];
+    final: boolean;
+    ordered: boolean;
+    orderKeys: string[];
+}
+interface ProtoError {
+    code: string;
+    message: string;
+    type: string;
+    anchor: string;
+}
+interface ExecutionMetrics {
+    parseDurationNs: bigint | number;
+    planDurationNs: bigint | number;
+    executeDurationNs: bigint | number;
+    totalDurationNs: bigint | number;
+}
+interface ExplainTotals {
+    cost?: number;
+    est_rows?: number;
+}
+interface ExplainPayload {
+    schema: string;
+    ops: unknown[];
+    totals?: ExplainTotals;
+    properties: unknown;
+    calibration: unknown;
+    profileVersion: number;
+}
+interface ProfileMemory {
+    netBytes?: number | bigint;
+    peakBytes?: number | bigint;
+    totalAllocBytes?: number | bigint;
+}
+interface ProfilePayload {
+    profileVersion: number;
+    ops: unknown[];
+    peakContributors: unknown[];
+    totals: unknown;
+    totalTimeNs: bigint | number;
+    spills: unknown;
+    memory?: ProfileMemory;
+    plannerEstimates: unknown;
+    memCurve: unknown[];
+    setop: unknown;
+    hashaggSpills: bigint | number;
+    hashaggSpillReason: string;
+    committedTxns: bigint | number;
+    graphStoreNodes: bigint | number;
+    graphStoreEdges: bigint | number;
+    graphStoreDirty: boolean;
+    flaggerFindings: string[];
+    compact: boolean;
+}
+interface Heartbeat {
+}
+interface ExecutionResponse {
+    status?: Status;
+    schema?: SchemaDefinition;
+    page?: DataPage;
+    error?: ProtoError;
+    metrics?: ExecutionMetrics;
+    explain?: ExplainPayload;
+    profile?: ProfilePayload;
+    heartbeat?: Heartbeat;
+}
+interface PingRequest {
+}
+interface PingResponse {
+    ok: boolean;
+}
+interface BeginRequest {
+    readOnly: boolean;
+    sessionId: string;
+}
+interface BeginResponse {
+    sessionId: string;
+    txId: string;
+}
+interface CommitRequest {
+    sessionId: string;
+}
+interface CommitResponse {
+    success: boolean;
+}
+interface RollbackRequest {
+    sessionId: string;
+}
+interface RollbackResponse {
+    success: boolean;
+}
+interface SavepointRequest {
+    name: string;
+    sessionId: string;
+}
+interface SavepointResponse {
+    success: boolean;
+}
+interface RollbackToRequest {
+    name: string;
+    sessionId: string;
+}
+interface RollbackToResponse {
+    success: boolean;
+}
+interface QuicClientMessage {
+    hello?: HelloRequest;
+    execute?: ExecuteRequest;
+    pull?: PullRequest;
+    ping?: PingRequest;
+    cdcDiag?: unknown;
+    cdcCtrl?: unknown;
+    begin?: BeginRequest;
+    commit?: CommitRequest;
+    rollback?: RollbackRequest;
+    savepoint?: SavepointRequest;
+    rollbackTo?: RollbackToRequest;
+    backup?: unknown;
+    restore?: unknown;
+    uploadBackup?: unknown;
+}
+interface QuicServerMessage {
+    hello?: HelloResponse;
+    execute?: ExecutionResponse;
+    pull?: PullResponse;
+    ping?: PingResponse;
+    cdcDiag?: unknown;
+    cdcCtrl?: unknown;
+    begin?: BeginResponse;
+    commit?: CommitResponse;
+    rollback?: RollbackResponse;
+    savepoint?: SavepointResponse;
+    rollbackTo?: RollbackToResponse;
+    backup?: unknown;
+    restore?: unknown;
+    uploadBackup?: unknown;
+}
+/**
+ * Ensure proto is initialized.
+ */
+declare function ensureProtoInitialized(): Promise<void>;
+/**
+ * Convert a JavaScript value to a protobuf Value message.
+ */
+declare function jsToProtoValue(value: unknown): ProtoValue;
+/**
+ * Convert a protobuf Value to a JavaScript value.
+ */
+declare function protoValueToJS(val: ProtoValue): unknown;
+/**
+ * Encode a QuicClientMessage to protobuf bytes.
+ */
+declare function encodeQuicClientMessage(msg: QuicClientMessage): Buffer;
+/**
+ * Encode a QuicClientMessage with 4-byte big-endian length prefix.
+ */
+declare function encodeWithLengthPrefix(msg: QuicClientMessage): Buffer;
+/**
+ * Decode a QuicServerMessage from protobuf bytes.
+ */
+declare function decodeQuicServerMessage(data: Buffer | Uint8Array): QuicServerMessage;
+/**
+ * Decode 4-byte big-endian length prefix.
+ */
+declare function decodeLengthPrefix(data: Buffer): number;
+/**
+ * Build a HelloRequest message.
+ */
+declare function buildHelloRequest(username: string, password: string, clientName: string, clientVersion: string, conformance: string, tenantId?: string): QuicClientMessage;
+/**
+ * Build an ExecuteRequest message.
+ */
+declare function buildExecuteRequest(sessionId: string, query: string, params?: Record<string, unknown>): QuicClientMessage;
+/**
+ * Build a PullRequest message.
+ */
+declare function buildPullRequest(requestId: number, pageSize: number, sessionId: string): QuicClientMessage;
+/**
+ * Build a PingRequest message.
+ */
+declare function buildPingRequest(): QuicClientMessage;
+/**
+ * Build a BeginRequest message.
+ */
+declare function buildBeginRequest(readOnly: boolean, sessionId: string): QuicClientMessage;
+/**
+ * Build a CommitRequest message.
+ */
+declare function buildCommitRequest(sessionId: string): QuicClientMessage;
+/**
+ * Build a RollbackRequest message.
+ */
+declare function buildRollbackRequest(sessionId: string): QuicClientMessage;
+/**
+ * Build a SavepointRequest message.
+ */
+declare function buildSavepointRequest(name: string, sessionId: string): QuicClientMessage;
+/**
+ * Build a RollbackToRequest message.
+ */
+declare function buildRollbackToRequest(name: string, sessionId: string): QuicClientMessage;
+/**
+ * Convert a DataPage row to a record of column name -> value.
+ */
+declare function rowToRecord(row: Row$1, columns: ColumnDefinition[]): Record<string, unknown>;
+/**
+ * Get proto file path for gRPC loader.
+ */
+declare function getProtoPath(): string;
+
+/**
+ * Transport Layer
+ *
+ * Provides transport abstraction for communication with Geode server.
+ * Supports both QUIC (default) and gRPC transports.
  *
- * Provides QUIC + TLS 1.3 transport for communication with Geode server.
+ * Wire format for QUIC: 4-byte Big Endian length prefix + protobuf message body.
  */
 
 /**
  * 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>;
+    /** Send a protobuf message to the server */
+    sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
+    /** Receive a protobuf message from the server */
+    receiveProto(signal?: AbortSignal): Promise<QuicServerMessage>;
     /** Close the transport */
     close(): Promise<void>;
     /** Check if transport is closed */
@@ -279,15 +657,14 @@ interface Transport {
  */
 declare function buildTLSConfig(cfg: GeodeConfig): Promise<tls.SecureContextOptions>;
 /**
- * Abstract base class for QUIC transports.
- * Allows for different QUIC implementations.
+ * Abstract base class for transports.
  */
 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 sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
+    abstract receiveProto(signal?: AbortSignal): Promise<QuicServerMessage>;
     abstract close(): Promise<void>;
     isClosed(): boolean;
     getAddress(): string;
@@ -297,60 +674,70 @@ declare abstract class BaseTransport implements Transport {
  * QUIC transport using @matrixai/quic.
  *
  * This implementation uses the quiche QUIC library via native bindings.
+ * Wire format: 4-byte Big Endian length prefix + protobuf message body.
  */
-declare class MatrixQuicTransport extends BaseTransport {
+declare class QuicTransport extends BaseTransport {
     private _client;
     private _stream;
-    private _readBuffer;
-    private _lineBuffer;
-    private _pendingReads;
+    private _protoBuffer;
+    private _pendingProtoReads;
     constructor(address: string);
     /**
      * Connect to the Geode server using QUIC.
      */
-    static connect(cfg: GeodeConfig): Promise<MatrixQuicTransport>;
+    static connect(cfg: GeodeConfig): Promise<QuicTransport>;
     /**
      * Start reading from the stream in the background.
      */
     private startReading;
     /**
-     * Process received data, splitting by newlines.
+     * Reject all pending reads with an error.
+     */
+    private rejectPendingReads;
+    /**
+     * Process received data (length-prefixed protobuf messages).
      */
     private processData;
-    send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
-    receive(signal?: AbortSignal): Promise<Buffer>;
+    /**
+     * Send a protobuf message with length prefix.
+     */
+    sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
+    /**
+     * Receive a protobuf message.
+     */
+    receiveProto(signal?: AbortSignal): Promise<QuicServerMessage>;
     close(): Promise<void>;
 }
 /**
  * Mock transport for testing purposes.
  *
- * This allows unit testing without a real QUIC connection.
+ * This allows unit testing without a real connection.
  */
 declare class MockTransport extends BaseTransport {
-    private _sendQueue;
-    private _receiveQueue;
-    private _pendingReads;
+    private _protoSendQueue;
+    private _protoReceiveQueue;
+    private _pendingProtoReads;
     constructor(address?: string);
     /**
-     * Queue a response to be returned by receive().
+     * Queue a protobuf response.
      */
-    queueResponse(response: Record<string, unknown>): void;
+    queueProtoResponse(response: QuicServerMessage): void;
     /**
-     * Get all sent messages.
+     * Get all sent protobuf messages.
      */
-    getSentMessages(): Record<string, unknown>[];
+    getSentProtoMessages(): QuicClientMessage[];
     /**
      * Clear sent messages.
      */
     clearSentMessages(): void;
-    send(msg: Record<string, unknown>, signal?: AbortSignal): Promise<void>;
-    receive(signal?: AbortSignal): Promise<Buffer>;
+    sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
+    receiveProto(signal?: AbortSignal): Promise<QuicServerMessage>;
     close(): Promise<void>;
 }
 /**
  * Create a transport for the given configuration.
  *
- * Uses MatrixQuicTransport by default.
+ * Selects between QUIC and gRPC based on config.transport.
  */
 declare function createTransport(cfg: GeodeConfig): Promise<Transport>;
 
@@ -377,24 +764,55 @@ interface GQLRange<T = unknown> {
     lowerInclusive: boolean;
     upperInclusive: boolean;
 }
+/**
+ * Type alias for node/edge IDs.
+ *
+ * IDs can be:
+ * - string: String-based IDs or hex format IDs
+ * - number: Integer IDs within JavaScript's safe integer range
+ * - bigint: Integer IDs larger than Number.MAX_SAFE_INTEGER (2^53 - 1)
+ *
+ * Note: Geode's internal IDs often exceed JavaScript's safe integer limit,
+ * so bigint is used to preserve full precision.
+ */
+type GQLId = string | number | bigint;
 /**
  * Node structure from graph queries.
  */
 interface GQLNode {
-    id: string | number;
+    id: GQLId;
     labels: string[];
     properties: Record<string, unknown>;
 }
 /**
  * Edge structure from graph queries.
+ *
+ * Note: The server may return edge endpoints as either:
+ * - `startNode`/`endNode` (normalized form used by the client)
+ * - `from`/`to` (alternative wire format)
+ *
+ * The client normalizes both formats to `startNode`/`endNode`.
  */
 interface GQLEdge {
-    id: string | number;
+    id: GQLId;
     type: string;
-    startNode: string | number;
-    endNode: string | number;
+    startNode: GQLId;
+    endNode: GQLId;
     properties: Record<string, unknown>;
 }
+/**
+ * Raw edge structure as it may appear in wire format.
+ * Used internally for parsing before normalization.
+ */
+interface RawEdge {
+    id: GQLId;
+    type: string;
+    startNode?: GQLId;
+    endNode?: GQLId;
+    from?: GQLId;
+    to?: GQLId;
+    properties?: Record<string, unknown>;
+}
 /**
  * Path structure from graph queries.
  */
@@ -501,6 +919,12 @@ type Row = Map<string, GQLValue>;
 declare function parseRow(raw: Record<string, unknown>, columns: ColumnInfo[]): Row;
 /**
  * Convert Row to plain object.
+ *
+ * Security: Uses Object.create(null) to create a prototype-free object
+ * and rejects dangerous keys (__proto__, constructor, prototype) that
+ * could lead to prototype pollution attacks.
+ *
+ * @throws {Error} If a row contains a dangerous key
  */
 declare function rowToObject(row: Row): Record<string, unknown>;
 
@@ -826,7 +1250,7 @@ declare function prepare(conn: Connection, query: string): PreparedStatement;
 /**
  * Query Explain and Profile
  *
- * Support for query plan analysis and execution profiling.
+ * Support for query plan analysis and execution profiling using protobuf protocol.
  */
 
 /**
@@ -908,37 +1332,10 @@ interface ExplainOptions extends Omit<QueryOptions, 'pageSize'> {
 }
 /**
  * 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>;
 /**
@@ -1096,7 +1493,7 @@ declare function batchParallel(conn: Connection, queries: BatchQuery[], options?
 /**
  * Geode Connection
  *
- * Connection management and query execution.
+ * Connection management and query execution using protobuf wire protocol.
  */
 
 /**
@@ -1124,6 +1521,8 @@ declare class Connection {
     private _inTransaction;
     private _activeResult;
     private _requestId;
+    private _sessionId;
+    private _columns;
     private constructor();
     /**
      * Create a new connection to the Geode server.
@@ -1149,12 +1548,12 @@ declare class Connection {
      * Check if connection is closed.
      */
     get isClosed(): boolean;
+    /**
+     * Get session ID.
+     */
+    get sessionId(): string;
     /**
      * 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;
     /**
@@ -1176,7 +1575,10 @@ declare class Connection {
         rows: Record<string, unknown>[];
         final: boolean;
     }>;
-    private _tryReceiveInlineFrame;
+    /**
+     * Try to receive an inline response with short timeout.
+     */
+    private _tryReceiveInline;
     /**
      * Release active result (internal).
      */
@@ -1215,33 +1617,18 @@ declare class 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>;
     /**
@@ -1347,6 +1734,25 @@ interface CreateRLSPolicyOptions {
     /** Whether to enable immediately */
     enabled?: boolean;
 }
+/**
+ * Password policy configuration.
+ */
+interface PasswordPolicy {
+    /** Minimum password length (default: 8) */
+    minLength?: number;
+    /** Maximum password length (default: 256) */
+    maxLength?: number;
+    /** Require at least one uppercase letter */
+    requireUppercase?: boolean;
+    /** Require at least one lowercase letter */
+    requireLowercase?: boolean;
+    /** Require at least one digit */
+    requireDigit?: boolean;
+    /** Require at least one special character */
+    requireSpecialChar?: boolean;
+    /** Special characters to accept (default: !@#$%^&*()_+-=[]{}|;:,.<>?) */
+    specialChars?: string;
+}
 /**
  * Authentication and authorization client.
  *
@@ -1370,12 +1776,22 @@ interface CreateRLSPolicyOptions {
  */
 declare class AuthClient {
     private _conn;
+    private _passwordPolicy;
     /**
      * Create a new auth client.
      *
      * @param conn - Connection to use
+     * @param passwordPolicy - Optional password policy configuration
      */
-    constructor(conn: Connection);
+    constructor(conn: Connection, passwordPolicy?: PasswordPolicy);
+    /**
+     * Get the current password policy.
+     */
+    get passwordPolicy(): Readonly<PasswordPolicy>;
+    /**
+     * Update the password policy.
+     */
+    setPasswordPolicy(policy: PasswordPolicy): void;
     /**
      * Create a new user.
      *
@@ -1548,8 +1964,11 @@ declare class AuthClient {
 }
 /**
  * Create an auth client from a connection.
+ *
+ * @param conn - Connection to use
+ * @param passwordPolicy - Optional password policy configuration
  */
-declare function createAuthClient(conn: Connection): AuthClient;
+declare function createAuthClient(conn: Connection, passwordPolicy?: PasswordPolicy): AuthClient;
 
 /**
  * Geode Client
@@ -1769,7 +2188,7 @@ declare class GeodeClient {
  *
  * @example
  * ```typescript
- * const client = await createClient('geode://localhost:3141');
+ * const client = await createClient('quic://localhost:3141');
  * const rows = await client.queryAll('MATCH (n) RETURN n LIMIT 10');
  * await client.close();
  * ```
@@ -1786,6 +2205,21 @@ declare function createClientWithConfig(config: GeodeConfig, options?: ClientOpt
  * Manages a pool of connections for efficient resource utilization.
  */
 
+/**
+ * Rate limiter configuration.
+ */
+interface RateLimiterConfig {
+    /** Maximum number of connection attempts per window (default: 10) */
+    maxAttempts: number;
+    /** Time window in milliseconds (default: 1000) */
+    windowMs: number;
+    /** Initial backoff delay in milliseconds (default: 100) */
+    initialBackoffMs: number;
+    /** Maximum backoff delay in milliseconds (default: 30000) */
+    maxBackoffMs: number;
+    /** Backoff multiplier (default: 2) */
+    backoffMultiplier: number;
+}
 /**
  * Connection pool for managing multiple connections.
  */
@@ -1795,11 +2229,12 @@ declare class ConnectionPool {
     private _waitQueue;
     private _closed;
     private _maintenanceInterval?;
+    private _rateLimiter;
     private _minConnections;
     private _maxConnections;
     private _acquireTimeout;
     private _idleTimeout;
-    constructor(config: PoolConfig);
+    constructor(config: PoolConfig, rateLimiterConfig?: Partial<RateLimiterConfig>);
     /**
      * Create a new connection pool.
      */
@@ -1854,7 +2289,7 @@ declare class ConnectionPool {
      */
     close(): Promise<void>;
     /**
-     * Add a new connection to the pool.
+     * Add a new connection to the pool with rate limiting and exponential backoff.
      */
     private addConnection;
     /**
@@ -1868,149 +2303,79 @@ declare class ConnectionPool {
 }
 
 /**
- * Geode Wire Protocol
+ * gRPC Transport Layer
  *
- * JSON line protocol implementation for communication with Geode server.
+ * Provides gRPC transport for communication with Geode server.
+ * Uses @grpc/grpc-js with dynamic proto loading.
+ *
+ * Method mapping (QuicClientMessage field -> gRPC service RPC):
+ *   hello     -> Handshake (unary)
+ *   execute   -> Execute   (server-streaming: schema + data pages)
+ *   pull      -> reads next buffered message from the Execute stream
+ *   ping      -> Ping      (unary)
+ *   begin     -> Begin     (unary)
+ *   commit    -> Commit    (unary)
+ *   rollback  -> Rollback  (unary)
+ *   savepoint / rollbackTo -> not supported over gRPC
  */
 
-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.
+ * gRPC transport for Geode database.
  */
-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;
+declare class GrpcTransport implements Transport {
+    private _client;
+    private _closed;
+    private _address;
+    private _pendingResponses;
+    private _activeStream;
+    constructor(address: string);
+    /**
+     * Connect to the Geode server using gRPC.
+     */
+    static connect(cfg: GeodeConfig): Promise<GrpcTransport>;
+    /**
+     * Send a protobuf message and queue the response.
+     * For gRPC, this makes the appropriate RPC call based on the message type.
+     */
+    sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
+    /**
+     * Receive a protobuf message from the queue.
+     */
+    receiveProto(signal?: AbortSignal): Promise<QuicServerMessage>;
+    /**
+     * Legacy JSON send (not supported for gRPC).
+     */
+    send(_msg: Record<string, unknown>, _signal?: AbortSignal): Promise<void>;
+    /**
+     * Legacy JSON receive (not supported for gRPC).
+     */
+    receive(_signal?: AbortSignal): Promise<Buffer>;
+    /**
+     * Close the transport.
+     */
+    close(): Promise<void>;
+    /**
+     * Check if transport is closed.
+     */
+    isClosed(): boolean;
+    /**
+     * Get remote address.
+     */
+    getAddress(): string;
+    /**
+     * Make a unary RPC call.
+     */
+    private callUnary;
+    /**
+     * Call the server-streaming Execute RPC.
+     * Collects all streamed ExecutionResponse messages into _pendingResponses.
+     */
+    private callServerStream;
+    /**
+     * Check if closed and throw if so.
+     */
+    private checkClosed;
 }
-/**
- * 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
@@ -2293,6 +2658,28 @@ declare class PredicateBuilder {
     isNotNull(expr: string): this;
     /**
      * Add a raw predicate expression.
+     *
+     * **⚠️ SECURITY WARNING: This method bypasses all input validation.**
+     *
+     * Using raw() with user-supplied input can lead to GQL injection attacks.
+     * Only use this method when:
+     * 1. The expression is entirely constructed from trusted, hardcoded strings
+     * 2. All dynamic values are passed via the `params` argument (using $paramName syntax)
+     *
+     * @example
+     * ```typescript
+     * // SAFE: Using parameters for dynamic values
+     * predicate().raw('n.custom_field CONTAINS $pattern', { pattern: userInput })
+     *
+     * // UNSAFE: Never interpolate user input directly
+     * predicate().raw(`n.name = '${userInput}'`) // VULNERABLE TO INJECTION!
+     * ```
+     *
+     * Consider using the typed predicate methods (eq, gt, contains, etc.) instead.
+     *
+     * @param expr - Raw predicate expression (MUST be trusted input)
+     * @param params - Parameters to bind (safe for user input)
+     * @deprecated Consider using typed predicate methods instead for better security.
      */
     raw(expr: string, params?: QueryParams): this;
     /**
@@ -2328,6 +2715,26 @@ declare class QueryBuilder {
     optionalMatch(pattern: string | PatternBuilder): this;
     /**
      * Add a WHERE clause.
+     *
+     * **⚠️ SECURITY WARNING when using string predicates:**
+     *
+     * When passing a string predicate, this method does NOT validate or sanitize input.
+     * Using string predicates with user-supplied data can lead to GQL injection attacks.
+     *
+     * @example
+     * ```typescript
+     * // RECOMMENDED: Use PredicateBuilder for type-safe, injection-resistant queries
+     * query().where(predicate().eq('n.name', userInput))
+     *
+     * // SAFE: Using parameters with string predicates
+     * query().where('n.name = $name', { name: userInput })
+     *
+     * // UNSAFE: Never interpolate user input directly in string predicates
+     * query().where(`n.name = '${userInput}'`) // VULNERABLE TO INJECTION!
+     * ```
+     *
+     * @param predicate - A PredicateBuilder (recommended) or raw predicate string
+     * @param params - Parameters to bind when using string predicates
      */
     where(predicate: string | PredicateBuilder, params?: QueryParams): this;
     /**
@@ -2379,7 +2786,29 @@ declare class QueryBuilder {
      */
     remove(...items: string[]): this;
     /**
-     * Add raw clause.
+     * Add a raw GQL clause.
+     *
+     * **⚠️ SECURITY WARNING: This method bypasses all input validation.**
+     *
+     * Using raw() with user-supplied input can lead to GQL injection attacks.
+     * Only use this method when:
+     * 1. The clause is entirely constructed from trusted, hardcoded strings
+     * 2. All dynamic values are passed via the `params` argument (using $paramName syntax)
+     *
+     * @example
+     * ```typescript
+     * // SAFE: Using parameters for dynamic values
+     * query().raw('CALL db.index.fulltext.queryNodes("idx", $term)', { term: userInput })
+     *
+     * // UNSAFE: Never interpolate user input directly
+     * query().raw(`MATCH (n:${userLabel})`) // VULNERABLE TO INJECTION!
+     * ```
+     *
+     * Consider using the typed query builder methods instead.
+     *
+     * @param clause - Raw GQL clause (MUST be trusted input)
+     * @param params - Parameters to bind (safe for user input)
+     * @deprecated Consider using typed query builder methods instead for better security.
      */
     raw(clause: string, params?: QueryParams): this;
     /**
@@ -2427,4 +2856,4 @@ declare function node(): NodePatternBuilder;
  */
 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 };
+export { AuthClient, BaseTransport, type BatchOptions, type BatchQuery, type BatchResult, type BatchSummary, type BeginRequest, type BeginResponse, type ClientOptions, type ColumnDef, type ColumnDefinition, type ColumnInfo, type CommitRequest, type CommitResponse, ConfigError, Connection, ConnectionPool, type ConnectionState, type CreateRLSPolicyOptions, type CreateRoleOptions, type CreateUserOptions, DEFAULT_CONFORMANCE, DEFAULT_GRPC_PORT, DEFAULT_HELLO_NAME, DEFAULT_HELLO_VERSION, DEFAULT_PAGE_SIZE, DEFAULT_PORT, type DSNScheme, type DataPage, DriverError, type EdgeDirection, type EdgePattern, EdgePatternBuilder, ErrBadConn, ErrClosed, ErrNoTx, ErrQueryInProgress, ErrRowsClosed, ErrTxDone, ErrTxInProgress, type ExecuteRequest, type ExecutionResponse, type ExplainOptions, type GQLEdge, type GQLId, type GQLNode, type GQLPath, type GQLRange, type GQLType, GQLValue, type GQLValueKind, GeodeClient, type GeodeConfig, type GeodeError, GrpcTransport, type HelloRequest, type HelloResponse, MAX_PAGE_SIZE, MAX_QUERY_LENGTH, MockTransport, type NodePattern, NodePatternBuilder, type OperationTiming, type Param, type ParameterInfo, PatternBuilder, type PatternElement, type Permission, type PingRequest, type PingResponse, type PlanOperation, type PoolConfig, PredicateBuilder, type PredicateOp, PreparedStatement, type ProtoError, type Row$1 as ProtoRow, type ProtoValue, type PullRequest, type PullResponse, QueryBuilder, type QueryOptions, type QueryParams, type QueryPlan, type QueryProfile, QueryResult, QueryResultIterator, type QuicClientMessage, type QuicServerMessage, QuicTransport, QuicTransport as QuicheTransport, type RLSPolicy, type RawEdge, type Role, type RollbackRequest, type RollbackResponse, type Row, SUPPORTED_SCHEMES, type SchemaDefinition, SecurityError, type SortDirection, StateError, type Status, StatusClass, type StatusClassType, Transaction, type Transport, TransportError, type TransportType, type User, batch, batchAll, batchFirst, batchMap, batchParallel, buildBeginRequest, buildCommitRequest, buildExecuteRequest, buildHelloRequest, buildPingRequest, buildPullRequest, buildRollbackRequest, buildRollbackToRequest, buildSavepointRequest, buildTLSConfig, cloneConfig, createAuthClient, createClient, createClientWithConfig, createTransport, decodeLengthPrefix, decodeQuicServerMessage, defaultConfig, edge, encodeQuicClientMessage, encodeWithLengthPrefix, ensureProtoInitialized, explain, extractParameters, formatPlan, formatProfile, fromJSON, getAddress, getProtoPath, isDriverError, isGeodeError, isRetryableError, jsToProtoValue, node, parseDSN, parseGQLType, parseRow, pattern, predicate, prepare, profile, protoValueToJS, query, redactConfig, redactDSN, rowToObject, rowToRecord, sanitizeForLog, validateConfig, validateHostname, validatePageSize, validateParamName, validateParamValue, validatePort, validateQuery, validateSavepointName, withTransaction };