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

package/dist/index.d.ts

@@ -73,6 +73,8 @@ interface GeodeConfig {
     keepAliveInterval?: number;
     /** Maximum idle time in milliseconds (default: 30000) */
     maxIdleTime?: number;
+    /** Inline receive timeout in milliseconds (default: 5000) */
+    inlineTimeout?: number;
     /** Enable TLS for gRPC (default: true) */
     tls?: boolean;
 }
@@ -271,13 +273,24 @@ declare class StateError extends Error implements GeodeError {
  * 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;
+declare const ERR_CLOSED_MESSAGE = "geode: connection closed";
+declare const ERR_QUERY_IN_PROGRESS_MESSAGE = "geode: query already in progress";
+declare const ERR_TX_IN_PROGRESS_MESSAGE = "geode: transaction already in progress";
+declare const ERR_NO_TX_MESSAGE = "geode: no transaction in progress";
+declare const ERR_TX_DONE_MESSAGE = "geode: transaction already committed or rolled back";
+declare const ERR_ROWS_CLOSED_MESSAGE = "geode: rows closed";
+declare const ERR_BAD_CONN_MESSAGE = "geode: bad connection";
+declare function ErrClosed(): Error;
+declare function ErrQueryInProgress(): Error;
+declare function ErrTxInProgress(): Error;
+declare function ErrNoTx(): Error;
+declare function ErrTxDone(): Error;
+declare function ErrRowsClosed(): Error;
+declare function ErrBadConn(): Error;
+/**
+ * Check if an error is a specific sentinel error by message.
+ */
+declare function isSentinelError(err: unknown, message: string): boolean;
 /**
  * Type guard for DriverError.
  */
@@ -555,6 +568,12 @@ interface QuicServerMessage {
     restore?: unknown;
     uploadBackup?: unknown;
 }
+/**
+ * Initialize protobuf types synchronously.
+ * Safe to call multiple times; only loads on first call.
+ * Prefer ensureProtoInitialized() in async contexts to avoid blocking the event loop.
+ */
+declare function initProtoSync(): void;
 /**
  * Ensure proto is initialized.
  */
@@ -679,9 +698,12 @@ declare abstract class BaseTransport implements Transport {
 declare class QuicTransport extends BaseTransport {
     private _client;
     private _stream;
-    private _protoBuffer;
+    private _chunks;
+    private _totalLength;
+    private _maxMessageSize;
+    private _maxBufferBytes;
     private _pendingProtoReads;
-    constructor(address: string);
+    constructor(address: string, maxMessageSize?: number, maxBufferBytes?: number);
     /**
      * Connect to the Geode server using QUIC.
      */
@@ -694,10 +716,22 @@ declare class QuicTransport extends BaseTransport {
      * Reject all pending reads with an error.
      */
     private rejectPendingReads;
+    /**
+     * Consolidate the chunk list into a single buffer.
+     * Called only when we know we have enough data for at least one operation.
+     */
+    private consolidateChunks;
     /**
      * Process received data (length-prefixed protobuf messages).
+     *
+     * Uses a chunk list pattern instead of Buffer.concat on every call
+     * to avoid O(n^2) copying of the accumulated buffer.
      */
     private processData;
+    /**
+     * Handle oversized data by closing the transport.
+     */
+    private handleOversize;
     /**
      * Send a protobuf message with length prefix.
      */
@@ -741,6 +775,80 @@ declare class MockTransport extends BaseTransport {
  */
 declare function createTransport(cfg: GeodeConfig): Promise<Transport>;
 
+/**
+ * GQL Value Class
+ *
+ * Type-safe wrapper for GQL values in the ISO/IEC 39075:2024 type system.
+ * Extracted from types.ts for file size management.
+ */
+
+/**
+ * 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;
+}
+
 /**
  * GQL Type System
  *
@@ -820,72 +928,6 @@ 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.
  */
@@ -917,6 +959,7 @@ 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.
  *
@@ -982,6 +1025,11 @@ declare class QueryResult implements AsyncIterable<Row> {
      * Async iterator implementation.
      */
     [Symbol.asyncIterator](): AsyncIterator<Row>;
+    /**
+     * Collect all remaining rows as raw records without GQLValue conversion.
+     * This is the fast path used by queryAll() to avoid double-conversion.
+     */
+    _collectRawRecords(): Promise<Record<string, unknown>[]>;
     /**
      * Get all remaining rows as an array.
      */
@@ -1157,12 +1205,17 @@ declare class PreparedStatement {
     private _query;
     private _parameters;
     private _closed;
+    private _onClose?;
     /**
      * Create a new prepared statement.
      *
+     * @param conn - Connection to use for execution
+     * @param query - Query text with parameters
+     * @param onClose - Optional callback invoked when close() is called (e.g., to release a pooled connection)
+     *
      * @internal Use Connection.prepare() instead.
      */
-    constructor(conn: Connection, query: string);
+    constructor(conn: Connection, query: string, onClose?: () => void);
     /**
      * Get the query text.
      */
@@ -1221,6 +1274,8 @@ declare class PreparedStatement {
      * Close the prepared statement.
      *
      * After closing, the statement cannot be executed.
+     * If a release callback was provided (e.g., to return a pooled connection),
+     * it is invoked exactly once on the first call to close().
      */
     close(): void;
     /**
@@ -1415,6 +1470,14 @@ interface BatchOptions {
  * By default, queries are executed sequentially and all results are collected.
  * Set stopOnError to true to abort on the first failure.
  *
+ * When `options.concurrency` is greater than 1, the batch delegates to
+ * {@link batchParallel} for concurrent execution. Note that a single
+ * `Connection` can only execute one query at a time due to the connection
+ * state machine, so `batchParallel` will automatically fall back to
+ * sequential execution (concurrency=1) when given a single connection.
+ * For true parallelism, use a `ConnectionPool` to acquire separate
+ * connections per concurrent query.
+ *
  * @param conn - Connection to use
  * @param queries - Array of queries to execute
  * @param options - Batch execution options
@@ -1479,12 +1542,22 @@ declare function batchMap(conn: Connection, queryTemplate: string, items: QueryP
  * Unlike the sequential batch(), this executes multiple queries concurrently
  * up to the specified limit.
  *
- * Note: Results may be returned out of order.
+ * **Important:** A single `Connection` can only execute one query at a time
+ * (the connection state machine throws `ErrQueryInProgress` for concurrent
+ * queries). When a single connection is provided with concurrency > 1, this
+ * function automatically falls back to sequential execution (concurrency=1)
+ * to prevent runtime errors.
  *
- * @param conn - Connection to use
+ * For true parallel execution, use a connection pool or connection factory
+ * that provides separate connections per concurrent query.
+ *
+ * Note: When executing concurrently, results may arrive out of order but
+ * are sorted by index before returning.
+ *
+ * @param conn - Connection to use (single connection forces sequential execution)
  * @param queries - Array of queries to execute
  * @param options - Batch execution options with concurrency
- * @returns Batch summary (results in completion order)
+ * @returns Batch summary (results sorted by query index)
  */
 declare function batchParallel(conn: Connection, queries: BatchQuery[], options?: BatchOptions & {
     concurrency: number;
@@ -1532,109 +1605,67 @@ declare class Connection {
      * Create a connection with a custom transport (for testing).
      */
     static connectWithTransport(config: GeodeConfig, transport: Transport): Promise<Connection>;
-    /**
-     * Get connection configuration.
-     */
+    /** Get connection configuration. */
     get config(): Readonly<GeodeConfig>;
-    /**
-     * Get current connection state.
-     */
+    /** Get current connection state. */
     get state(): ConnectionState;
-    /**
-     * Check if connection is in a transaction.
-     */
+    /** Check if connection is in a transaction. */
     get inTransaction(): boolean;
-    /**
-     * Check if connection is closed.
-     */
+    /** Check if connection is closed. */
     get isClosed(): boolean;
-    /**
-     * Get session ID.
-     */
+    /** Get session ID. */
     get sessionId(): string;
-    /**
-     * Perform the HELLO handshake.
-     */
+    /** Perform the HELLO handshake. */
     private hello;
-    /**
-     * Execute a query that returns rows.
-     */
+    /** Execute a query that returns rows. */
     query(query: string, options?: QueryOptions): Promise<QueryResult>;
-    /**
-     * Execute a query and return all rows as an array.
-     */
+    /** 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.
-     */
+    /** Execute a query that doesn't return rows. */
     exec(query: string, options?: QueryOptions): Promise<void>;
-    /**
-     * Fetch the next page of results (internal).
-     */
+    /** @internal Fetch the next page of results. Called by QueryResult. */
     _fetchNextPage(pageSize: number, signal?: AbortSignal): Promise<{
         rows: Record<string, unknown>[];
         final: boolean;
     }>;
-    /**
-     * Try to receive an inline response with short timeout.
-     */
+    /** Try to receive an inline response with short timeout. */
     private _tryReceiveInline;
-    /**
-     * Release active result (internal).
-     */
+    /** Drain remaining data pages until final=true to prevent query corruption (QUAL-T7). */
+    private _drainRemainingPages;
+    /** @internal Release the active result, returning the connection to idle. */
     _releaseResult(result: QueryResult): void;
-    /**
-     * Begin a transaction.
-     */
+    /** Begin a transaction. */
     begin(signal?: AbortSignal): Promise<Transaction>;
-    /**
-     * Commit the current transaction (internal).
-     */
+    /** @internal Commit the current transaction. Called by Transaction. */
     _commit(signal?: AbortSignal): Promise<void>;
-    /**
-     * Rollback the current transaction (internal).
-     */
+    /** @internal Rollback the current transaction. Called by Transaction. */
     _rollback(signal?: AbortSignal): Promise<void>;
-    /**
-     * Create a savepoint (internal).
-     */
+    /** @internal Create a named savepoint. Called by Transaction. */
     _savepoint(name: string, signal?: AbortSignal): Promise<void>;
-    /**
-     * Rollback to a savepoint (internal).
-     */
+    /** @internal Rollback to a previously created savepoint. Called by Transaction. */
     _rollbackTo(name: string, signal?: AbortSignal): Promise<void>;
-    /**
-     * Ping the server to check connection health.
-     */
+    /** Ping the server to check connection health. */
     ping(signal?: AbortSignal): Promise<void>;
-    /**
-     * Reset the connection session.
-     */
+    /** Reset the connection session. */
     reset(signal?: AbortSignal): Promise<void>;
-    /**
-     * Close the connection.
-     */
+    /** Close the connection. */
     close(): Promise<void>;
-    /**
-     * Create a prepared statement.
-     */
+    /** Create a prepared statement. */
     prepare(query: string): Promise<PreparedStatement>;
-    /**
-     * Get the query execution plan without executing.
-     */
+    /** Get the query execution plan without executing. */
     explain(query: string, options?: ExplainOptions): Promise<QueryPlan>;
-    /**
-     * Execute a query with profiling.
-     */
+    /** Execute a query with profiling. */
     profile(query: string, options?: ExplainOptions): Promise<QueryProfile>;
-    /**
-     * Execute multiple queries in a batch.
-     */
+    /** Execute multiple queries in a batch. */
     batch(queries: BatchQuery[], options?: BatchOptions): Promise<BatchSummary>;
-    /**
-     * Check connection state before operation.
-     */
+    /** Check connection state before operation. */
     private checkState;
+    /** Send a protobuf message with request timeout enforcement. */
+    private _sendWithTimeout;
+    /** Receive a protobuf message with request timeout enforcement. */
+    private _receiveWithTimeout;
+    /** Create a combined abort signal from requestTimeout and optional caller signal (CWE-703). */
+    private _withRequestTimeout;
 }
 
 /**
@@ -1777,13 +1808,23 @@ interface PasswordPolicy {
 declare class AuthClient {
     private _conn;
     private _passwordPolicy;
+    private _onClose?;
+    private _closed;
     /**
      * Create a new auth client.
      *
      * @param conn - Connection to use
      * @param passwordPolicy - Optional password policy configuration
+     * @param onClose - Optional callback invoked when close() is called (e.g., to release a pooled connection)
+     */
+    constructor(conn: Connection, passwordPolicy?: PasswordPolicy, onClose?: () => void);
+    /**
+     * Close the auth client and release the underlying connection.
+     *
+     * If a release callback was provided (e.g., to return a pooled connection),
+     * it is invoked exactly once on the first call to close().
      */
-    constructor(conn: Connection, passwordPolicy?: PasswordPolicy);
+    close(): void;
     /**
      * Get the current password policy.
      */
@@ -1792,104 +1833,35 @@ declare class AuthClient {
      * Update the password policy.
      */
     setPasswordPolicy(policy: PasswordPolicy): void;
-    /**
-     * Create a new user.
-     *
-     * @param username - Username for the new user
-     * @param options - User creation options
-     */
+    /** Create a new user. */
     createUser(username: string, options: CreateUserOptions): Promise<void>;
-    /**
-     * Delete a user.
-     *
-     * @param username - Username to delete
-     */
+    /** Delete a user. */
     deleteUser(username: string): Promise<void>;
-    /**
-     * Get user information.
-     *
-     * @param username - Username to look up
-     * @returns User information or null if not found
-     */
+    /** Get user information, or null if not found. */
     getUser(username: string): Promise<User | null>;
-    /**
-     * List all users.
-     *
-     * @returns Array of users
-     */
+    /** List all users. */
     listUsers(): Promise<User[]>;
-    /**
-     * Change a user's password.
-     *
-     * @param username - Username
-     * @param newPassword - New password
-     */
+    /** Change a user's password. */
     changePassword(username: string, newPassword: string): Promise<void>;
-    /**
-     * Activate a user.
-     *
-     * @param username - Username to activate
-     */
+    /** Activate a user. */
     activateUser(username: string): Promise<void>;
-    /**
-     * Deactivate a user.
-     *
-     * @param username - Username to deactivate
-     */
+    /** Deactivate a user. */
     deactivateUser(username: string): Promise<void>;
-    /**
-     * Create a new role.
-     *
-     * @param name - Role name
-     * @param options - Role creation options
-     */
+    /** Create a new role. */
     createRole(name: string, options?: CreateRoleOptions): Promise<void>;
-    /**
-     * Delete a role.
-     *
-     * @param name - Role name to delete
-     */
+    /** Delete a role. */
     deleteRole(name: string): Promise<void>;
-    /**
-     * Get role information.
-     *
-     * @param name - Role name
-     * @returns Role information or null if not found
-     */
+    /** Get role information, or null if not found. */
     getRole(name: string): Promise<Role | null>;
-    /**
-     * List all roles.
-     *
-     * @returns Array of roles
-     */
+    /** List all roles. */
     listRoles(): Promise<Role[]>;
-    /**
-     * Assign a role to a user.
-     *
-     * @param username - Username
-     * @param roleName - Role to assign
-     */
+    /** Assign a role to a user. */
     assignRole(username: string, roleName: string): Promise<void>;
-    /**
-     * Revoke a role from a user.
-     *
-     * @param username - Username
-     * @param roleName - Role to revoke
-     */
+    /** Revoke a role from a user. */
     revokeRole(username: string, roleName: string): Promise<void>;
-    /**
-     * Grant a permission to a role.
-     *
-     * @param roleName - Role name
-     * @param permission - Permission to grant
-     */
+    /** Grant a permission to a role. */
     grantPermission(roleName: string, permission: Permission): Promise<void>;
-    /**
-     * Revoke a permission from a role.
-     *
-     * @param roleName - Role name
-     * @param permission - Permission to revoke
-     */
+    /** Revoke a permission from a role. */
     revokePermission(roleName: string, permission: Permission): Promise<void>;
     /**
      * Create an RLS policy.
@@ -1957,9 +1929,7 @@ declare class AuthClient {
      * @returns Whether permission is granted
      */
     hasPermission(resource: string, action: string, label?: string): Promise<boolean>;
-    private validateUsername;
     private validatePassword;
-    private validateRoleName;
     private validatePolicyName;
 }
 /**
@@ -2045,6 +2015,14 @@ declare class GeodeClient {
     exec(query: string, options?: QueryOptions): Promise<void>;
     /**
      * Execute multiple statements.
+     *
+     * When a connection pool is available, all queries are executed within a
+     * single transaction to reduce round-trips (one BEGIN + N queries + COMMIT
+     * instead of N independent round-trips with connection acquire/release).
+     *
+     * For non-pooled (single connection) clients, queries are executed
+     * sequentially without an implicit transaction wrapper, preserving the
+     * caller's control over transaction boundaries.
      */
     execBatch(queries: Array<{
         query: string;
@@ -2327,7 +2305,13 @@ declare class GrpcTransport implements Transport {
     private _closed;
     private _address;
     private _pendingResponses;
+    private _pendingProtoReads;
     private _activeStream;
+    private _streamPaused;
+    private _backpressureThreshold;
+    private _streamTimeoutMs;
+    private _streamTimeoutTimer;
+    private _streamComplete;
     constructor(address: string);
     /**
      * Connect to the Geode server using gRPC.
@@ -2340,16 +2324,9 @@ declare class GrpcTransport implements Transport {
     sendProto(msg: QuicClientMessage, signal?: AbortSignal): Promise<void>;
     /**
      * Receive a protobuf message from the queue.
+     * If no response is buffered, waits for the next streamed message.
      */
     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.
      */
@@ -2362,15 +2339,30 @@ declare class GrpcTransport implements Transport {
      * Get remote address.
      */
     getAddress(): string;
+    /**
+     * Enqueue a response, resolving a pending read if one exists.
+     */
+    private enqueueResponse;
     /**
      * Make a unary RPC call.
      */
     private callUnary;
     /**
      * Call the server-streaming Execute RPC.
-     * Collects all streamed ExecutionResponse messages into _pendingResponses.
+     * Uses backpressure to prevent unbounded buffering: pauses the stream when
+     * the pending response buffer exceeds the threshold, resumes when drained.
+     * Enforces a configurable timeout that fires when no data arrives within the period.
      */
     private callServerStream;
+    /**
+     * Reset the stream inactivity timeout. If no data arrives within
+     * _streamTimeoutMs, the stream is cancelled and the promise rejected.
+     */
+    private resetStreamTimeout;
+    /**
+     * Clear any active stream inactivity timeout.
+     */
+    private clearStreamTimeout;
     /**
      * Check if closed and throw if so.
      */
@@ -2429,6 +2421,124 @@ declare function validateSavepointName(name: string): void;
  */
 declare function sanitizeForLog(value: string): string;
 
+/**
+ * Predicate Builder
+ *
+ * Fluent API for building WHERE clause predicates in GQL queries.
+ * Extracted from query-builder.ts for file size management.
+ */
+
+/**
+ * Predicate operator.
+ */
+type PredicateOp = '=' | '<>' | '!=' | '<' | '<=' | '>' | '>=' | 'IN' | 'NOT IN' | 'CONTAINS' | 'STARTS WITH' | 'ENDS WITH' | 'IS NULL' | 'IS NOT NULL';
+/**
+ * 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.
+     *
+     * **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;
+    /**
+     * 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;
+}
+
 /**
  * Query Builder
  *
@@ -2443,10 +2553,6 @@ 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.
  */
@@ -2593,112 +2699,6 @@ declare class PatternBuilder {
      */
     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.
-     *
-     * **⚠️ 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;
-    /**
-     * 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.
  */
@@ -2715,26 +2715,6 @@ 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;
     /**
@@ -2788,23 +2768,7 @@ declare class QueryBuilder {
     /**
      * 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.
+     * **SECURITY WARNING: This method bypasses all input validation.**
      *
      * @param clause - Raw GQL clause (MUST be trusted input)
      * @param params - Parameters to bind (safe for user input)
@@ -2856,4 +2820,4 @@ declare function node(): NodePatternBuilder;
  */
 declare function edge(): EdgePatternBuilder;
 
-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 };
+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, ERR_BAD_CONN_MESSAGE, ERR_CLOSED_MESSAGE, ERR_NO_TX_MESSAGE, ERR_QUERY_IN_PROGRESS_MESSAGE, ERR_ROWS_CLOSED_MESSAGE, ERR_TX_DONE_MESSAGE, ERR_TX_IN_PROGRESS_MESSAGE, 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, initProtoSync, isDriverError, isGeodeError, isRetryableError, isSentinelError, 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 };