@grafema/rfdb-client 0.1.0-alpha.1

package/dist/client.js

@@ -0,0 +1,429 @@
+/**
+ * RFDBClient - Unix socket client for RFDB server
+ *
+ * Provides the same API as GraphEngine NAPI binding but communicates
+ * with a separate rfdb-server process over Unix socket + MessagePack.
+ */
+import { createConnection } from 'net';
+import { encode, decode } from '@msgpack/msgpack';
+import { EventEmitter } from 'events';
+export class RFDBClient extends EventEmitter {
+    socketPath;
+    socket;
+    connected;
+    pending;
+    reqId;
+    buffer;
+    constructor(socketPath = '/tmp/rfdb.sock') {
+        super();
+        this.socketPath = socketPath;
+        this.socket = null;
+        this.connected = false;
+        this.pending = new Map();
+        this.reqId = 0;
+        this.buffer = Buffer.alloc(0);
+    }
+    /**
+     * Connect to RFDB server
+     */
+    async connect() {
+        if (this.connected)
+            return;
+        return new Promise((resolve, reject) => {
+            this.socket = createConnection(this.socketPath);
+            this.socket.on('connect', () => {
+                this.connected = true;
+                this.emit('connected');
+                resolve();
+            });
+            this.socket.on('error', (err) => {
+                if (!this.connected) {
+                    reject(err);
+                }
+                else {
+                    this.emit('error', err);
+                }
+            });
+            this.socket.on('close', () => {
+                this.connected = false;
+                this.emit('disconnected');
+                // Reject all pending requests
+                for (const [, { reject }] of this.pending) {
+                    reject(new Error('Connection closed'));
+                }
+                this.pending.clear();
+            });
+            this.socket.on('data', (chunk) => {
+                this._handleData(chunk);
+            });
+        });
+    }
+    /**
+     * Handle incoming data, parse framed messages
+     */
+    _handleData(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        while (this.buffer.length >= 4) {
+            // Read length prefix (4 bytes, big-endian)
+            const msgLen = this.buffer.readUInt32BE(0);
+            if (this.buffer.length < 4 + msgLen) {
+                // Not enough data yet
+                break;
+            }
+            // Extract message
+            const msgBytes = this.buffer.subarray(4, 4 + msgLen);
+            this.buffer = this.buffer.subarray(4 + msgLen);
+            // Decode and dispatch
+            try {
+                const response = decode(msgBytes);
+                this._handleResponse(response);
+            }
+            catch (err) {
+                this.emit('error', new Error(`Failed to decode response: ${err.message}`));
+            }
+        }
+    }
+    /**
+     * Handle decoded response
+     */
+    _handleResponse(response) {
+        if (this.pending.size === 0) {
+            this.emit('error', new Error('Received response with no pending request'));
+            return;
+        }
+        // Get the oldest pending request (FIFO)
+        const [id, { resolve, reject }] = this.pending.entries().next().value;
+        this.pending.delete(id);
+        if (response.error) {
+            reject(new Error(response.error));
+        }
+        else {
+            resolve(response);
+        }
+    }
+    /**
+     * Send a request and wait for response
+     */
+    async _send(cmd, payload = {}) {
+        if (!this.connected || !this.socket) {
+            throw new Error('Not connected to RFDB server');
+        }
+        const request = { cmd, ...payload };
+        const msgBytes = encode(request);
+        return new Promise((resolve, reject) => {
+            const id = this.reqId++;
+            this.pending.set(id, { resolve, reject });
+            // Write length prefix + message
+            const header = Buffer.alloc(4);
+            header.writeUInt32BE(msgBytes.length);
+            this.socket.write(Buffer.concat([header, Buffer.from(msgBytes)]));
+        });
+    }
+    // ===========================================================================
+    // Write Operations
+    // ===========================================================================
+    /**
+     * Add nodes to the graph
+     */
+    async addNodes(nodes) {
+        const wireNodes = nodes.map(n => ({
+            id: String(n.id),
+            nodeType: (n.node_type || n.nodeType || n.type || 'UNKNOWN'),
+            name: n.name || '',
+            file: n.file || '',
+            exported: n.exported || false,
+            metadata: typeof n.metadata === 'string' ? n.metadata : JSON.stringify(n.metadata || {}),
+        }));
+        return this._send('addNodes', { nodes: wireNodes });
+    }
+    /**
+     * Add edges to the graph
+     */
+    async addEdges(edges, skipValidation = false) {
+        const wireEdges = edges.map(e => ({
+            src: String(e.src),
+            dst: String(e.dst),
+            edgeType: (e.edge_type || e.edgeType || e.type || 'UNKNOWN'),
+            metadata: typeof e.metadata === 'string' ? e.metadata : JSON.stringify(e.metadata || {}),
+        }));
+        return this._send('addEdges', { edges: wireEdges, skipValidation });
+    }
+    /**
+     * Delete a node
+     */
+    async deleteNode(id) {
+        return this._send('deleteNode', { id: String(id) });
+    }
+    /**
+     * Delete an edge
+     */
+    async deleteEdge(src, dst, edgeType) {
+        return this._send('deleteEdge', {
+            src: String(src),
+            dst: String(dst),
+            edgeType
+        });
+    }
+    // ===========================================================================
+    // Read Operations
+    // ===========================================================================
+    /**
+     * Get a node by ID
+     */
+    async getNode(id) {
+        const response = await this._send('getNode', { id: String(id) });
+        return response.node || null;
+    }
+    /**
+     * Check if node exists
+     */
+    async nodeExists(id) {
+        const response = await this._send('nodeExists', { id: String(id) });
+        return response.value;
+    }
+    /**
+     * Find nodes by type
+     */
+    async findByType(nodeType) {
+        const response = await this._send('findByType', { nodeType });
+        return response.ids || [];
+    }
+    /**
+     * Find nodes by attributes
+     */
+    async findByAttr(query) {
+        const response = await this._send('findByAttr', { query });
+        return response.ids || [];
+    }
+    // ===========================================================================
+    // Graph Traversal
+    // ===========================================================================
+    /**
+     * Get neighbors of a node
+     */
+    async neighbors(id, edgeTypes = []) {
+        const response = await this._send('neighbors', {
+            id: String(id),
+            edgeTypes
+        });
+        return response.ids || [];
+    }
+    /**
+     * Breadth-first search
+     */
+    async bfs(startIds, maxDepth, edgeTypes = []) {
+        const response = await this._send('bfs', {
+            startIds: startIds.map(String),
+            maxDepth,
+            edgeTypes
+        });
+        return response.ids || [];
+    }
+    /**
+     * Depth-first search
+     */
+    async dfs(startIds, maxDepth, edgeTypes = []) {
+        const response = await this._send('dfs', {
+            startIds: startIds.map(String),
+            maxDepth,
+            edgeTypes
+        });
+        return response.ids || [];
+    }
+    /**
+     * Get outgoing edges from a node
+     */
+    async getOutgoingEdges(id, edgeTypes = null) {
+        const response = await this._send('getOutgoingEdges', {
+            id: String(id),
+            edgeTypes
+        });
+        return response.edges || [];
+    }
+    /**
+     * Get incoming edges to a node
+     */
+    async getIncomingEdges(id, edgeTypes = null) {
+        const response = await this._send('getIncomingEdges', {
+            id: String(id),
+            edgeTypes
+        });
+        return response.edges || [];
+    }
+    // ===========================================================================
+    // Stats
+    // ===========================================================================
+    /**
+     * Get node count
+     */
+    async nodeCount() {
+        const response = await this._send('nodeCount');
+        return response.count;
+    }
+    /**
+     * Get edge count
+     */
+    async edgeCount() {
+        const response = await this._send('edgeCount');
+        return response.count;
+    }
+    /**
+     * Count nodes by type
+     */
+    async countNodesByType(types = null) {
+        const response = await this._send('countNodesByType', { types });
+        return response.counts || {};
+    }
+    /**
+     * Count edges by type
+     */
+    async countEdgesByType(edgeTypes = null) {
+        const response = await this._send('countEdgesByType', { edgeTypes });
+        return response.counts || {};
+    }
+    // ===========================================================================
+    // Control
+    // ===========================================================================
+    /**
+     * Flush data to disk
+     */
+    async flush() {
+        return this._send('flush');
+    }
+    /**
+     * Compact the database
+     */
+    async compact() {
+        return this._send('compact');
+    }
+    /**
+     * Clear the database
+     */
+    async clear() {
+        return this._send('clear');
+    }
+    // ===========================================================================
+    // Bulk Read Operations
+    // ===========================================================================
+    /**
+     * Query nodes (async generator)
+     */
+    async *queryNodes(query) {
+        const serverQuery = {};
+        if (query.nodeType)
+            serverQuery.nodeType = query.nodeType;
+        if (query.type)
+            serverQuery.nodeType = query.type;
+        if (query.name)
+            serverQuery.name = query.name;
+        if (query.file)
+            serverQuery.file = query.file;
+        if (query.exported !== undefined)
+            serverQuery.exported = query.exported;
+        const response = await this._send('queryNodes', { query: serverQuery });
+        const nodes = response.nodes || [];
+        for (const node of nodes) {
+            yield node;
+        }
+    }
+    /**
+     * Get all nodes matching query
+     */
+    async getAllNodes(query = {}) {
+        const nodes = [];
+        for await (const node of this.queryNodes(query)) {
+            nodes.push(node);
+        }
+        return nodes;
+    }
+    /**
+     * Get all edges
+     */
+    async getAllEdges() {
+        const response = await this._send('getAllEdges');
+        return response.edges || [];
+    }
+    // ===========================================================================
+    // Node Utility Methods
+    // ===========================================================================
+    /**
+     * Check if node is an endpoint (has no outgoing edges)
+     */
+    async isEndpoint(id) {
+        const response = await this._send('isEndpoint', { id: String(id) });
+        return response.value;
+    }
+    /**
+     * Get node identifier string
+     */
+    async getNodeIdentifier(id) {
+        const response = await this._send('getNodeIdentifier', { id: String(id) });
+        return response.identifier || null;
+    }
+    /**
+     * Update node version
+     */
+    async updateNodeVersion(id, version) {
+        return this._send('updateNodeVersion', { id: String(id), version });
+    }
+    // ===========================================================================
+    // Datalog API
+    // ===========================================================================
+    /**
+     * Load Datalog rules
+     */
+    async datalogLoadRules(source) {
+        const response = await this._send('datalogLoadRules', { source });
+        return response.count;
+    }
+    /**
+     * Clear Datalog rules
+     */
+    async datalogClearRules() {
+        return this._send('datalogClearRules');
+    }
+    /**
+     * Execute Datalog query
+     */
+    async datalogQuery(query) {
+        const response = await this._send('datalogQuery', { query });
+        return response.results || [];
+    }
+    /**
+     * Check a guarantee (Datalog rule) and return violations
+     */
+    async checkGuarantee(ruleSource) {
+        const response = await this._send('checkGuarantee', { ruleSource });
+        return response.violations || [];
+    }
+    /**
+     * Ping the server
+     */
+    async ping() {
+        const response = await this._send('ping');
+        return response.pong && response.version ? response.version : false;
+    }
+    /**
+     * Close connection
+     */
+    async close() {
+        if (this.socket) {
+            this.socket.destroy();
+            this.socket = null;
+            this.connected = false;
+        }
+    }
+    /**
+     * Shutdown the server
+     */
+    async shutdown() {
+        try {
+            await this._send('shutdown');
+        }
+        catch {
+            // Expected - server closes connection
+        }
+        await this.close();
+    }
+}
+export default RFDBClient;

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @grafema/rfdb-client - High-performance graph database for code analysis
+ *
+ * This package provides:
+ * - RFDBClient: Socket-based client for out-of-process communication
+ * - Protocol types: Wire format types for RFDB communication
+ *
+ * For NAPI bindings (in-process), see the platform-specific packages.
+ */
+export { RFDBClient } from './client.js';
+export type { RFDBCommand, WireNode, WireEdge, RFDBRequest, RFDBResponse, AttrQuery, DatalogResult, IRFDBClient, } from './protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../ts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,YAAY,EACV,WAAW,EACX,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,SAAS,EACT,aAAa,EACb,WAAW,GACZ,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * @grafema/rfdb-client - High-performance graph database for code analysis
+ *
+ * This package provides:
+ * - RFDBClient: Socket-based client for out-of-process communication
+ * - Protocol types: Wire format types for RFDB communication
+ *
+ * For NAPI bindings (in-process), see the platform-specific packages.
+ */
+// Client
+export { RFDBClient } from './client.js';

package/dist/protocol.d.ts

@@ -0,0 +1,7 @@
+/**
+ * RFDB Protocol Types - re-export from @grafema/types
+ *
+ * This module provides wire format types for RFDB client-server communication.
+ */
+export type { RFDBCommand, WireNode, WireEdge, RFDBRequest, AddNodesRequest, AddEdgesRequest, DeleteNodeRequest, DeleteEdgeRequest, GetNodeRequest, NodeExistsRequest, FindByTypeRequest, FindByAttrRequest, NeighborsRequest, BfsRequest, GetOutgoingEdgesRequest, GetIncomingEdgesRequest, CountNodesByTypeRequest, CountEdgesByTypeRequest, RFDBResponse, AddNodesResponse, AddEdgesResponse, GetNodeResponse, NodeExistsResponse, FindByTypeResponse, FindByAttrResponse, NeighborsResponse, BfsResponse, GetEdgesResponse, CountResponse, CountsByTypeResponse, PingResponse, AttrQuery, DatalogBinding, DatalogResult, IRFDBClient, } from '@grafema/types';
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../ts/protocol.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAEV,WAAW,EAGX,QAAQ,EACR,QAAQ,EAGR,WAAW,EACX,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EAGvB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,oBAAoB,EACpB,YAAY,EAGZ,SAAS,EACT,cAAc,EACd,aAAa,EAGb,WAAW,GACZ,MAAM,gBAAgB,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,6 @@
+/**
+ * RFDB Protocol Types - re-export from @grafema/types
+ *
+ * This module provides wire format types for RFDB client-server communication.
+ */
+export {};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@grafema/rfdb-client",
+  "version": "0.1.0-alpha.1",
+  "description": "TypeScript client for RFDB graph database",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js"
+    }
+  },
+  "files": [
+    "dist",
+    "ts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "grafema",
+    "graph",
+    "database",
+    "code-analysis",
+    "rust"
+  ],
+  "license": "Apache-2.0",
+  "author": "Vadim Reshetnikov",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Disentinel/rfdb.git"
+  },
+  "dependencies": {
+    "@grafema/types": "workspace:*",
+    "@msgpack/msgpack": "^3.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.8",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">= 18"
+  }
+}