@grafema/rfdb-client 0.2.12-beta → 0.3.0-beta

package/dist/base-client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * BaseRFDBClient - Abstract base class for RFDB transport clients
+ *
+ * Contains all graph operation methods that delegate to abstract _send().
+ * Subclasses provide the transport layer (Unix socket, WebSocket, etc.)
+ */
+import { EventEmitter } from 'events';
+import type { RFDBCommand, WireNode, WireEdge, RFDBResponse, IRFDBClient, AttrQuery, FieldDeclaration, DatalogResult, DatalogExplainResult, CypherResult, NodeType, EdgeType, HelloResponse, CreateDatabaseResponse, OpenDatabaseResponse, ListDatabasesResponse, CurrentDatabaseResponse, ServerStats, SnapshotRef, SnapshotDiff, SnapshotInfo, CommitDelta } from '@grafema/types';
+export declare abstract class BaseRFDBClient extends EventEmitter implements IRFDBClient {
+    abstract readonly socketPath: string;
+    abstract readonly clientName: string;
+    abstract connected: boolean;
+    /**
+     * Whether the connected server supports streaming responses.
+     * Defaults to false. Unix socket subclass may set this after hello().
+     */
+    get supportsStreaming(): boolean;
+    protected _batching: boolean;
+    protected _batchNodes: WireNode[];
+    protected _batchEdges: WireEdge[];
+    protected _batchFiles: Set<string>;
+    abstract connect(): Promise<void>;
+    abstract close(): Promise<void>;
+    /**
+     * Send a request to RFDB server and wait for response.
+     * Subclasses implement transport-specific send logic.
+     */
+    protected abstract _send(cmd: RFDBCommand, payload?: Record<string, unknown>, timeoutMs?: number): Promise<RFDBResponse>;
+    /**
+     * Add nodes to the graph.
+     * Extra properties beyond id/type/name/file/exported/metadata are merged into metadata.
+     */
+    addNodes(nodes: Array<Partial<WireNode> & {
+        id: string;
+        type?: string;
+        node_type?: string;
+        nodeType?: string;
+    }>): Promise<RFDBResponse>;
+    /**
+     * Add edges to the graph.
+     * Extra properties beyond src/dst/type are merged into metadata.
+     */
+    addEdges(edges: WireEdge[], skipValidation?: boolean): Promise<RFDBResponse>;
+    deleteNode(id: string): Promise<RFDBResponse>;
+    deleteEdge(src: string, dst: string, edgeType: EdgeType): Promise<RFDBResponse>;
+    getNode(id: string): Promise<WireNode | null>;
+    nodeExists(id: string): Promise<boolean>;
+    findByType(nodeType: NodeType): Promise<string[]>;
+    findByAttr(query: Record<string, unknown>): Promise<string[]>;
+    neighbors(id: string, edgeTypes?: EdgeType[]): Promise<string[]>;
+    bfs(startIds: string[], maxDepth: number, edgeTypes?: EdgeType[]): Promise<string[]>;
+    dfs(startIds: string[], maxDepth: number, edgeTypes?: EdgeType[]): Promise<string[]>;
+    reachability(startIds: string[], maxDepth: number, edgeTypes?: EdgeType[], backward?: boolean): Promise<string[]>;
+    /**
+     * Get outgoing edges from a node.
+     * Parses metadata JSON and spreads it onto the edge object for convenience.
+     */
+    getOutgoingEdges(id: string, edgeTypes?: EdgeType[] | null): Promise<(WireEdge & Record<string, unknown>)[]>;
+    /**
+     * Get incoming edges to a node.
+     * Parses metadata JSON and spreads it onto the edge object for convenience.
+     */
+    getIncomingEdges(id: string, edgeTypes?: EdgeType[] | null): Promise<(WireEdge & Record<string, unknown>)[]>;
+    nodeCount(): Promise<number>;
+    edgeCount(): Promise<number>;
+    countNodesByType(types?: NodeType[] | null): Promise<Record<string, number>>;
+    countEdgesByType(edgeTypes?: EdgeType[] | null): Promise<Record<string, number>>;
+    getStats(): Promise<ServerStats>;
+    flush(): Promise<RFDBResponse>;
+    compact(): Promise<RFDBResponse>;
+    clear(): Promise<RFDBResponse>;
+    /**
+     * Build a server query object from an AttrQuery.
+     */
+    protected _buildServerQuery(query: AttrQuery): Record<string, unknown>;
+    /**
+     * Query nodes (async generator).
+     * Default implementation fetches all matching nodes in a single request.
+     * Subclasses with streaming support can override.
+     */
+    queryNodes(query: AttrQuery): AsyncGenerator<WireNode, void, unknown>;
+    /**
+     * Stream nodes matching query.
+     * Default implementation delegates to queryNodes().
+     * Subclasses with streaming support can override.
+     */
+    queryNodesStream(query: AttrQuery): AsyncGenerator<WireNode, void, unknown>;
+    /**
+     * Get all nodes matching query.
+     */
+    getAllNodes(query?: AttrQuery): Promise<WireNode[]>;
+    /**
+     * Get all edges.
+     * Parses metadata JSON and spreads it onto the edge object for convenience.
+     */
+    getAllEdges(): Promise<(WireEdge & Record<string, unknown>)[]>;
+    isEndpoint(id: string): Promise<boolean>;
+    getNodeIdentifier(id: string): Promise<string | null>;
+    updateNodeVersion(id: string, version: string): Promise<RFDBResponse>;
+    declareFields(fields: FieldDeclaration[]): Promise<number>;
+    datalogLoadRules(source: string): Promise<number>;
+    datalogClearRules(): Promise<RFDBResponse>;
+    protected _parseExplainResponse(response: RFDBResponse): DatalogExplainResult;
+    datalogQuery(query: string): Promise<DatalogResult[]>;
+    datalogQuery(query: string, explain: true): Promise<DatalogExplainResult>;
+    checkGuarantee(ruleSource: string): Promise<DatalogResult[]>;
+    checkGuarantee(ruleSource: string, explain: true): Promise<DatalogExplainResult>;
+    executeDatalog(source: string): Promise<DatalogResult[]>;
+    executeDatalog(source: string, explain: true): Promise<DatalogExplainResult>;
+    cypherQuery(query: string): Promise<CypherResult>;
+    ping(): Promise<string | false>;
+    hello(protocolVersion?: number): Promise<HelloResponse>;
+    createDatabase(name: string, ephemeral?: boolean): Promise<CreateDatabaseResponse>;
+    openDatabase(name: string, mode?: 'rw' | 'ro'): Promise<OpenDatabaseResponse>;
+    closeDatabase(): Promise<RFDBResponse>;
+    dropDatabase(name: string): Promise<RFDBResponse>;
+    listDatabases(): Promise<ListDatabasesResponse>;
+    currentDatabase(): Promise<CurrentDatabaseResponse>;
+    /**
+     * Convert a SnapshotRef to wire format payload fields.
+     */
+    protected _resolveSnapshotRef(ref: SnapshotRef): Record<string, unknown>;
+    diffSnapshots(from: SnapshotRef, to: SnapshotRef): Promise<SnapshotDiff>;
+    tagSnapshot(version: number, tags: Record<string, string>): Promise<void>;
+    findSnapshot(tagKey: string, tagValue: string): Promise<number | null>;
+    listSnapshots(filterTag?: string): Promise<SnapshotInfo[]>;
+    beginBatch(): void;
+    /**
+     * Synchronously batch a single node.
+     */
+    batchNode(node: Partial<WireNode> & {
+        id: string;
+        type?: string;
+        node_type?: string;
+        nodeType?: string;
+    }): void;
+    /**
+     * Synchronously batch a single edge.
+     */
+    batchEdge(edge: WireEdge | Record<string, unknown>): void;
+    commitBatch(tags?: string[], deferIndex?: boolean, protectedTypes?: string[], overrideChangedFiles?: string[]): Promise<CommitDelta>;
+    /**
+     * Internal helper: send a commitBatch with chunking for large payloads.
+     * @internal
+     */
+    _sendCommitBatch(changedFiles: string[], allNodes: WireNode[], allEdges: WireEdge[], tags?: string[], deferIndex?: boolean, protectedTypes?: string[]): Promise<CommitDelta>;
+    rebuildIndexes(): Promise<void>;
+    abortBatch(): void;
+    isBatching(): boolean;
+    /**
+     * Find files that depend on the given changed files.
+     */
+    findDependentFiles(changedFiles: string[]): Promise<string[]>;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=base-client.d.ts.map

package/dist/base-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-client.d.ts","sourceRoot":"","sources":["../ts/base-client.ts"],"names":[],"mappings":"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"}