@ultipa-graph/ultipa-driver 5.1.5-s5.2 → 6.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 GQLDB Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Ultipa Node.js Driver
+
+Official Node.js/TypeScript driver for Ultipa graph database (GQL).
+
+## Requirements
+
+- Node.js 18+
+
+## Installation
+
+```bash
+npm install @ultipa-graph/ultipa-driver
+```
+
+> **Note:** This is the v6.x driver for Ultipa Graph. If you are using Ultipa v5.x, please install [@ultipa-graph/ultipa-driver@5.1.5-s5.2](https://www.npmjs.com/package/@ultipa-graph/ultipa-driver/v/5.1.5-s5.2). If you are using Ultipa v4.x, please install [@ultipa-graph/ultipa-node-sdk@4.5.0-s4.4](https://www.npmjs.com/package/@ultipa-graph/ultipa-node-sdk/v/4.5.0-s4.4).
+
+## Quick Start
+
+```typescript
+import { GqldbClient, ConfigBuilder } from '@ultipa-graph/ultipa-driver';
+
+async function main() {
+  const client = new GqldbClient(
+    new ConfigBuilder()
+      .hosts('localhost:60061')
+      .username('admin')
+      .password('password')
+      .defaultGraph('myGraph')
+      .build()
+  );
+
+  try {
+    await client.login('admin', 'password');
+
+    const response = await client.gql('MATCH (n) RETURN n LIMIT 10');
+
+    console.log('Rows:', response.rowCount);
+    console.log('Columns:', response.columns);
+    console.log('Data:', response.toObjects());
+  } finally {
+    await client.close();
+  }
+}
+
+main().catch(console.error);
+```
+
+## Features
+
+- GQL query execution with parameters
+- Streaming results for large datasets
+- Transaction support (begin, commit, rollback)
+- Graph management (create, drop, list)
+- Bulk import for high-throughput loading
+- Algorithm support (CALL algo.pagerank, algo.degree, etc.)
+- TypeScript support
+- Health checks
+
+## Documentation
+
+See [GUIDE.md](GUIDE.md) for detailed usage.
+
+## License
+
+[MIT License](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Main client for GQLDB Node.js driver.
+ */
+import { EventEmitter } from 'events';
+import { GqldbConfig } from './config';
+import { Response, InsertNodesResult, InsertEdgesResult, DeleteResult, ExportNodesResult, ExportEdgesResult, ExportConfig, ExportChunk } from './response';
+import { Session } from './session';
+import { Transaction } from './transaction';
+import { GraphInfo, GraphType, HealthStatus, CacheStats, CacheType, Statistics, CompactResult, ComputeTopologyResult, NodeData, EdgeData, BulkCreateNodesOptions, BulkCreateEdgesOptions, BulkImportOptions, BulkImportSession, CheckpointResult, EndBulkImportResult, AbortBulkImportResult, BulkImportStatus, TransactionInfo } from './types';
+/** Configuration for a query */
+export interface QueryConfig {
+    graphName?: string;
+    parameters?: Record<string, any>;
+    transactionId?: number;
+    timeout?: number;
+    readOnly?: boolean;
+    /** Max paths to return from path queries (0 = unlimited) */
+    maxPathResults?: number;
+}
+/** Configuration for insert nodes */
+export interface InsertNodesConfig {
+    options?: BulkCreateNodesOptions;
+    bulkImportSessionId?: string;
+}
+/** Configuration for insert edges */
+export interface InsertEdgesConfig {
+    options?: BulkCreateEdgesOptions;
+    bulkImportSessionId?: string;
+}
+/**
+ * Health watcher interface for streaming health updates.
+ * Emits 'status' events with HealthStatus and 'error' events on failure.
+ */
+export interface HealthWatcher extends EventEmitter {
+    /** Stop watching health updates */
+    stop(): void;
+}
+/** Main client for interacting with GQLDB */
+export declare class GqldbClient {
+    private config;
+    private clients;
+    private sessions;
+    private txManager;
+    private closed;
+    private sessionService;
+    private queryService;
+    private graphService;
+    private transactionService;
+    private dataService;
+    private healthService;
+    private adminService;
+    private bulkImportService;
+    /** Get session metadata for authenticated requests */
+    private getSessionMetadata;
+    constructor(config: GqldbConfig);
+    /** Close the client and all connections */
+    close(): Promise<void>;
+    /** Authenticate the user and create a session */
+    login(username: string, password: string): Promise<Session>;
+    /** Terminate the current session */
+    logout(): Promise<void>;
+    /** Check the connection and return the latency in nanoseconds */
+    ping(): Promise<number>;
+    /** Execute a GQL query and return the result */
+    gql(query: string, config?: QueryConfig): Promise<Response>;
+    /** Execute a GQL query and stream the results */
+    gqlStream(query: string, config?: QueryConfig, callback?: (response: Response) => void): Promise<void>;
+    /** Return the execution plan for a query */
+    explain(query: string, config?: QueryConfig): Promise<string>;
+    /** Execute a query with profiling and return statistics */
+    profile(query: string, config?: QueryConfig): Promise<string>;
+    /** Create a new graph */
+    createGraph(name: string, graphType?: GraphType, description?: string): Promise<void>;
+    /** Delete a graph */
+    dropGraph(name: string, ifExists?: boolean): Promise<void>;
+    /** Set the current graph for the session */
+    useGraph(name: string): Promise<void>;
+    /** Return all available graphs */
+    listGraphs(): Promise<GraphInfo[]>;
+    /** Return information about a specific graph */
+    getGraphInfo(name: string): Promise<GraphInfo>;
+    /** Start a new transaction */
+    beginTransaction(graphName: string, readOnly?: boolean, timeout?: number): Promise<Transaction>;
+    /** Commit a transaction */
+    commit(transactionId: number): Promise<boolean>;
+    /** Rollback a transaction */
+    rollback(transactionId: number): Promise<boolean>;
+    /** Return active transactions */
+    listTransactions(): Promise<TransactionInfo[]>;
+    /** Execute a function within a transaction */
+    withTransaction<T>(graphName: string, fn: (txId: number) => Promise<T>, readOnly?: boolean): Promise<T>;
+    /** Insert multiple nodes into a graph */
+    insertNodes(graphName: string, nodes: NodeData[], config?: InsertNodesConfig): Promise<InsertNodesResult>;
+    /** Insert multiple edges into a graph */
+    insertEdges(graphName: string, edges: EdgeData[], config?: InsertEdgesConfig): Promise<InsertEdgesResult>;
+    /** Delete nodes from a graph */
+    deleteNodes(graphName: string, nodeIds?: string[], labels?: string[], where?: string): Promise<DeleteResult>;
+    /** Delete edges from a graph */
+    deleteEdges(graphName: string, edgeIds?: string[], label?: string, where?: string): Promise<DeleteResult>;
+    /**
+     * Export graph data in JSON Lines format (streaming).
+     * @param config Export configuration
+     * @param callback Callback for each exported chunk
+     */
+    export(config: ExportConfig, callback?: (chunk: ExportChunk) => void): Promise<void>;
+    /**
+     * Stream nodes from a graph
+     * @deprecated Use export() with ExportConfig instead
+     */
+    exportNodes(graphName: string, labels?: string[], limit?: number, callback?: (result: ExportNodesResult) => void): Promise<void>;
+    /**
+     * Stream edges from a graph
+     * @deprecated Use export() with ExportConfig instead
+     */
+    exportEdges(graphName: string, labels?: string[], limit?: number, callback?: (result: ExportEdgesResult) => void): Promise<void>;
+    /** Check the health of a service */
+    healthCheck(service?: string): Promise<HealthStatus>;
+    /**
+     * Watch health status changes via server-side streaming.
+     * Returns a HealthWatcher that emits 'status' events with HealthStatus values.
+     * Call stop() to cancel the stream.
+     *
+     * @param service - Optional service name to watch
+     * @returns HealthWatcher - EventEmitter with stop() method
+     *
+     * @example
+     * ```typescript
+     * const watcher = client.watch();
+     * watcher.on('status', (status: HealthStatus) => {
+     *   console.log('Health status:', status);
+     * });
+     * watcher.on('error', (err) => {
+     *   console.error('Watch error:', err);
+     * });
+     * watcher.on('end', () => {
+     *   console.log('Watch stream ended');
+     * });
+     * // Later, to stop watching:
+     * watcher.stop();
+     * ```
+     */
+    watch(service?: string): HealthWatcher;
+    /** Pre-allocate parser instances */
+    warmupParser(count: number): Promise<void>;
+    /** Return cache statistics */
+    getCacheStats(cacheType?: CacheType): Promise<CacheStats>;
+    /** Clear the specified cache */
+    clearCache(cacheType?: CacheType): Promise<void>;
+    /** Return database statistics */
+    getStatistics(graphName?: string): Promise<Statistics>;
+    /** Invalidate the RBAC permission cache */
+    invalidatePermissionCache(username?: string): Promise<void>;
+    /** Trigger manual compaction of the database storage */
+    compact(): Promise<CompactResult>;
+    /** Wait for the computing engine topology to be ready */
+    waitForComputeTopology(graphName: string, timeoutMs?: number): Promise<ComputeTopologyResult>;
+    /**
+     * Start a bulk import session for optimized high-throughput inserts.
+     * @param graphName Target graph name
+     * @param options Optional bulk import configuration
+     */
+    startBulkImport(graphName: string, options?: BulkImportOptions): Promise<BulkImportSession>;
+    /**
+     * @deprecated Checkpoint is no longer needed. Use endBulkImport() which performs a final flush.
+     */
+    checkpoint(sessionId: string): Promise<CheckpointResult>;
+    /**
+     * End the bulk import session with a final checkpoint.
+     * @param sessionId Bulk import session ID
+     */
+    endBulkImport(sessionId: string): Promise<EndBulkImportResult>;
+    /**
+     * Cancel the bulk import session without final sync.
+     * @param sessionId Bulk import session ID
+     */
+    abortBulkImport(sessionId: string): Promise<AbortBulkImportResult>;
+    /**
+     * Return the current status of a bulk import session.
+     * @param sessionId Bulk import session ID
+     */
+    getBulkImportStatus(sessionId: string): Promise<BulkImportStatus>;
+    /** Get the current session */
+    getSession(): Session | null;
+    /** Check if there is an active session */
+    isLoggedIn(): boolean;
+    /** Get the client configuration */
+    getConfig(): GqldbConfig;
+    /** Whether this client is connected to a cluster deployment */
+    get isCluster(): boolean;
+    /** Get the cluster ID (empty string if not a cluster) */
+    get clusterId(): string;
+    /** Get the partition count (0 if not a cluster) */
+    get partitionCount(): number;
+}