gcyphrq 0.12.6

package/dist/indexes.d.ts

@@ -0,0 +1,38 @@
+import type { GraphFile } from './lib';
+import type { GraphIndexes } from './types/cypher';
+import type { GraphInstance } from './graph';
+/**
+ * Build pre-computed indexes directly from a Graphology graph instance.
+ *
+ * Iterates nodes and edges on the graph to build label, property, and
+ * edge-type adjacency indexes. No original `GraphFile` data is required.
+ *
+ * This is the preferred path when you already have a Graphology `Graph`
+ * (e.g. built externally or programmatically) and want to use it with
+ * `GraphEngine` for optimal query performance.
+ *
+ * Note: property values are coerced to strings via `String(value)`, so
+ * `true`/`false` become `"true"`/`"false"` and `0` becomes `"0"`.
+ *
+ * @param graph - Any Graphology graph instance (must satisfy `GraphInstance`)
+ * @returns Indexes for use with `GraphEngine`
+ */
+export declare function buildGraphIndexesFromGraph(graph: GraphInstance): GraphIndexes;
+/**
+ * Build pre-computed indexes from validated graph data and a constructed graph.
+ *
+ * Indexes enable O(1) label/property lookups and typed adjacency traversal,
+ * avoiding full-graph scans during query execution.
+ *
+ * The graph instance is required to get real Graphology edge IDs for the
+ * edge-type adjacency index.
+ *
+ * Note: property values are coerced to strings via `String(value)`, so
+ * `true`/`false` become `"true"`/`"false"` and `0` becomes `"0"`.
+ *
+ * @param data - Validated graph data (nodes + edges)
+ * @param graph - Constructed Graphology graph (provides real edge IDs)
+ * @returns Indexes for use with `GraphEngine`
+ */
+export declare function buildGraphIndexesFromData(data: GraphFile, graph: GraphInstance): GraphIndexes;
+//# sourceMappingURL=indexes.d.ts.map

package/dist/indexes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexes.d.ts","sourceRoot":"","sources":["../src/indexes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA0F7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAI7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,GAAG,YAAY,CAG7F"}

package/dist/lib.d.ts

@@ -0,0 +1,189 @@
+import { AdvancedCypherGraphologyEngine } from './engine/cypher-engine';
+import { Graph, type GraphInstance } from './graph';
+import type { AdvancedCypherAST, ResultRow, GraphIndexes } from './types/cypher';
+export interface GraphFileNode {
+    id: string;
+    label?: string;
+    [key: string]: unknown;
+}
+export interface GraphFileEdge {
+    source: string;
+    target: string;
+    type?: string;
+    [key: string]: unknown;
+}
+export interface GraphFile {
+    nodes: GraphFileNode[];
+    edges: GraphFileEdge[];
+}
+/**
+ * Thrown when graph data validation fails or a query cannot be executed.
+ */
+export declare class GraphError extends Error {
+    constructor(message: string);
+}
+/**
+ * Build a `GraphInstance` from a graph data object.
+ *
+ * Validates the data and constructs a Graphology-backed graph that the
+ * Cypher engine can query.
+ *
+ * @example
+ * ```ts
+ * import { createGraph } from 'gcyphrq';
+ *
+ * const graph = createGraph({
+ *   nodes: [
+ *     { id: 'alice', label: 'User', name: 'Alice' },
+ *     { id: 'bob', label: 'User', name: 'Bob' },
+ *   ],
+ *   edges: [
+ *     { source: 'alice', target: 'bob', type: 'FRIEND' },
+ *   ],
+ * });
+ * ```
+ *
+ * @see https://graphology.github.io/
+ */
+export declare function createGraph(data: GraphFile): GraphInstance;
+/**
+ * Build pre-computed indexes for fast query execution.
+ *
+ * **Three overloads:**
+ *
+ * 1. `buildGraphIndexes(graph)` — from an existing Graphology graph instance.
+ *    Builds indexes by iterating the graph (no original data needed).
+ * 2. `buildGraphIndexes(data)` — from graph data alone.
+ *    Builds the graph internally and indexes from it.
+ * 3. `buildGraphIndexes(data, graph)` — from graph data + graph instance.
+ *
+ * Pass the returned indexes to `GraphEngine` constructor for O(1) label
+ * and property lookups instead of full-graph scans.
+ *
+ * @example
+ * ```ts
+ * // From an existing Graphology graph
+ * import { buildGraphIndexes, GraphEngine } from 'gcyphrq';
+ * import Graph from 'graphology';
+ *
+ * const graph = new Graph();
+ * graph.addNode('alice', { label: 'User', name: 'Alice' });
+ * const indexes = buildGraphIndexes(graph);
+ * const engine = new GraphEngine(graph, indexes);
+ *
+ * // From graph data alone
+ * const indexes = buildGraphIndexes(graphData);
+ *
+ * // From graph data + graph instance (original API)
+ * import { buildGraphIndexes, GraphEngine, createGraph } from 'gcyphrq';
+ *
+ * const graph = createGraph(graphData);
+ * const indexes = buildGraphIndexes(graphData, graph);
+ * const engine = new GraphEngine(graph, indexes);
+ * ```
+ */
+export declare function buildGraphIndexes(graph: GraphInstance): GraphIndexes;
+export declare function buildGraphIndexes(data: GraphFile): GraphIndexes;
+export declare function buildGraphIndexes(data: GraphFile, graph: GraphInstance): GraphIndexes;
+/**
+ * Parse a Cypher query string into an AST.
+ *
+ * The returned AST can be passed to `GraphEngine.execute()` or inspected
+ * programmatically.
+ *
+ * @example
+ * ```ts
+ * import { parseCypher } from 'gcyphrq';
+ *
+ * const ast = parseCypher('MATCH (u:User) RETURN u');
+ * ```
+ */
+export declare function parseCypher(query: string): AdvancedCypherAST;
+/**
+ * Execute a Cypher query against a graph and return results as plain JSON.
+ *
+ * This is the simplest way to use gcyphrq. Indexes are built automatically.
+ *
+ * **Two overloads:**
+ *
+ * 1. `executeQuery(graph, query)` — from an existing Graphology graph instance.
+ * 2. `executeQuery(graphData, query)` — from graph data (original API).
+ *
+ * @example
+ * ```ts
+ * // From an existing Graphology graph
+ * import { executeQuery } from 'gcyphrq';
+ * import Graph from 'graphology';
+ *
+ * const graph = new Graph();
+ * graph.addNode('alice', { label: 'User', name: 'Alice' });
+ * const results = executeQuery(graph, 'MATCH (u:User) RETURN u.name');
+ *
+ * // From graph data (original API)
+ * const results = executeQuery(graphData, 'MATCH (u:User) RETURN u.name');
+ * ```
+ *
+ * @param graphOrData - Graph data or an existing Graphology graph instance
+ * @param query - A Cypher query string
+ * @returns Array of result rows
+ * @throws {GraphError} If graph data is invalid
+ * @throws {Error} If the query is invalid or cannot be executed
+ */
+export declare function executeQuery(graph: GraphInstance, query: string): ResultRow[];
+export declare function executeQuery(graphData: GraphFile, query: string): ResultRow[];
+/**
+ * The Cypher query engine. Accepts a `GraphInstance` and executes parsed ASTs.
+ *
+ * For best performance, pass pre-computed indexes as the second argument.
+ * Note: indexes are invalidated after any CREATE/SET/DELETE mutation so that
+ * subsequent MATCH/WITH stages see the updated graph state via full-graph scan.
+ *
+ * @example
+ * ```ts
+ * import { GraphEngine, createGraph, buildGraphIndexes } from 'gcyphrq';
+ *
+ * const graph = createGraph(graphData);
+ * const indexes = buildGraphIndexes(graphData, graph);
+ * const engine = new GraphEngine(graph, indexes);
+ * const results = engine.execute(ast);
+ * ```
+ */
+export { AdvancedCypherGraphologyEngine as GraphEngine };
+/**
+ * The Graphology wrapper class. Use this when you need to build a graph
+ * programmatically (node-by-node) instead of from a data object.
+ *
+ * @example
+ * ```ts
+ * import { Graph, GraphEngine } from 'gcyphrq';
+ *
+ * const graph = new Graph();
+ * graph.addNode('alice', { label: 'User', name: 'Alice' });
+ * graph.addNode('bob', { label: 'User', name: 'Bob' });
+ * graph.addEdge('alice', 'bob', { type: 'FRIEND' });
+ *
+ * const engine = new GraphEngine(graph);
+ * ```
+ */
+export { Graph };
+/**
+ * @module gcyphrq
+ *
+ * A Cypher graph query engine for in-memory graphs built on Graphology.
+ *
+ * Can be used as a CLI tool or as a library in Node.js / TypeScript projects.
+ *
+ * @example
+ * ```ts
+ * import { executeQuery } from 'gcyphrq';
+ *
+ * const results = executeQuery(graphData, 'MATCH (u:User) RETURN u');
+ * ```
+ *
+ * @see https://github.com/plelevier/gcyphrq
+ * @see https://graphology.github.io/
+ */
+export type { GraphInstance } from './graph';
+export type { GraphIndexes } from './types/cypher';
+export type { AdvancedCypherAST, Stage, MatchClause, WithClause, ReturnClause, WriteClause, CreateClause, DeleteClause, SetClause, NodePattern, RelationPattern, Direction, Expression, PropertyAccessExpression, LiteralExpression, AggregationExpression, BinaryExpression, Projection, OrderByItem, ResultRow, QueryContext, CypherNode, CypherEdge, CypherValue, CypherLiteral, } from './types/cypher';
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,8BAA8B,EAAE,MAAM,wBAAwB,CAAC;AAExE,OAAO,EAAE,KAAK,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAIjF,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,KAAK,EAAE,aAAa,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAmED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAG1D;AAmBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAAC;AACtE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,GAAG,YAAY,CAAC;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,GAAG,YAAY,CAAC;AAmBvF;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAE5D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;AAC/E,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC;AAsB/E;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,8BAA8B,IAAI,WAAW,EAAE,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,KAAK,EAAE,CAAC;AAIjB;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG7C,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,YAAY,EACV,iBAAiB,EACjB,KAAK,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,WAAW,EACX,eAAe,EACf,SAAS,EACT,UAAU,EACV,wBAAwB,EACxB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,UAAU,EACV,UAAU,EACV,WAAW,EACX,aAAa,GACd,MAAM,gBAAgB,CAAC"}