gcyphrq 0.12.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pascal Le Levier
+
+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,179 @@
+# gcyphrq
+
+A Cypher graph query engine for in-memory graphs built on [Graphology](https://graphology.github.io/).
+
+Available as a **CLI tool** and as a **library** for Node.js / TypeScript projects.
+
+## Features
+
+- **Cypher query engine** — supports `MATCH`, `OPTIONAL MATCH`, `WITH`, `RETURN`, `CREATE`, `SET`, `DELETE`
+- **Variable-length paths** — e.g. `-[r:FRIEND*1..3]->`
+- **Aggregations** — `count()`, `sum()`, `avg()`, `min()`, `max()` with implicit grouping via `WITH`
+- **Directional filtering** — `->`, `<-`, `-`
+- **Library or CLI** — use as a dependency in your project or run from the terminal
+- **TypeScript support** — full type declarations shipped with the package
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Build the project
+npm run build
+
+# Link globally so `gcyphrq` is available everywhere
+npm link
+```
+
+## Quick Start
+
+```bash
+# Load a graph from a JSON file
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+
+# Pipe a graph from stdin
+cat my-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'
+```
+
+## Usage
+
+```
+Usage: gcyphrq [options]
+
+Options:
+  -e, --expr <query>   Cypher query expression (required)
+  -g, --graph <file>   Path to a JSON graph file (or "-" to read from stdin)
+  -h, --help           Show this help message
+```
+
+## Graph File Format
+
+Graphs are described as JSON files with two arrays:
+
+```json
+{
+  "nodes": [
+    { "id": "alice", "label": "User", "name": "Alice" }
+  ],
+  "edges": [
+    { "source": "alice", "target": "bob", "type": "FRIEND" }
+  ]
+}
+```
+
+This format follows the [Graphology](https://graphology.github.io/) project's JSON representation for graphs.
+
+See the [`examples/`](examples/) directory for sample graphs.
+
+## Documentation
+
+📖 **[Full documentation](https://plelevier.github.io/gcyphrq/)** — Getting Started, CLI Reference, Query Guide, Library API, and Examples
+
+Local docs (source):
+- **[Library API](docs/library-api.md)** — how to use gcyphrq as a library (Node.js / TypeScript)
+- **[Query Guide](docs/query-guide.md)** — full Cypher syntax reference, supported features, and query examples
+- **[Example Graphs](examples/README.md)** — graph file format and available examples
+
+## Using as a Library
+
+Install gcyphrq as a dependency:
+
+```bash
+npm install gcyphrq
+```
+
+### One-shot query
+
+```ts
+import { executeQuery } from 'gcyphrq';
+
+const results = executeQuery(graphData, 'MATCH (u:User) RETURN u.name');
+```
+
+### Multiple queries on the same graph
+
+```ts
+import { createGraph, GraphEngine, parseCypher } from 'gcyphrq';
+
+const graph = createGraph(graphData);
+const engine = new GraphEngine(graph);
+
+const users = engine.execute(parseCypher('MATCH (u:User) RETURN u.name'));
+const counts = engine.execute(parseCypher('MATCH (u:User) RETURN count(u)'));
+```
+
+### Building a graph programmatically
+
+```ts
+import { Graph, GraphEngine, parseCypher } 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);
+const results = engine.execute(parseCypher('MATCH (u:User) RETURN u.name'));
+```
+
+See the [Library API documentation](https://plelevier.github.io/gcyphrq/library-api/) for the full reference.
+
+## Running without installing
+
+You can also run the tool directly from the source without a global install:
+
+```bash
+npx tsx src/index.ts -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Benchmarking
+
+The `bench.ts` script measures query performance with and without pre-computed indexes:
+
+```bash
+# Default: 5 queries against examples/cloud-infra.json
+npx tsx bench.ts
+
+# Different graph
+npx tsx bench.ts -g examples/social-graph.json
+
+# Custom queries
+npx tsx bench.ts -q 'MATCH (s:Service) RETURN s' 'MATCH (n) RETURN count(n) AS total'
+```
+
+See the [Benchmark documentation](docs/benchmark.md) for details on output format and interpretation.
+
+## AI Agent Skill
+
+This project includes a [skill](skills/gcyphrq/SKILL.md) that teaches AI agents how to use `gcyphrq` — supported Cypher features, query patterns, limitations, and ready-made examples against the bundled `cloud-infra.json` graph.
+
+Install the skill so your AI agent knows how to query your graphs without you having to explain the syntax every time.
+
+### pi
+
+```bash
+ln -s $(pwd)/skills/gcyphrq ~/.pi/agent/skills/gcyphrq
+```
+
+The skill is auto-discovered on next invocation.
+
+### Claude Code
+
+```bash
+ln -s $(pwd)/skills/gcyphrq ~/.claude/skills/gcyphrq
+```
+
+The skill is auto-discovered on next invocation.
+
+### OpenCode
+
+```bash
+ln -s $(pwd)/skills/gcyphrq ~/.opencode/skills/gcyphrq
+```

package/dist/engine/cypher-engine.d.ts

@@ -0,0 +1,39 @@
+import type { AdvancedCypherAST, ResultRow, GraphIndexes } from '../types/cypher';
+import type { GraphInstance } from '../graph';
+export declare class AdvancedCypherGraphologyEngine {
+    private graph;
+    private indexes;
+    constructor(graph: GraphInstance, indexes?: GraphIndexes);
+    /**
+     * MAIN ENTRY POINT
+     * Sequentially executes query stages and formats the return projection.
+     */
+    execute(ast: AdvancedCypherAST): ResultRow[];
+    /**
+     * Resolve node IDs matching a pattern using indexes when available.
+     * Falls back to full-graph scan when indexes are absent.
+     */
+    private getMatchingNodeIds;
+    private executeMatch;
+    /**
+     * Build a neighbor iterator using the edge-type adjacency index when available.
+     * Falls back to graph iteration for untyped edges or missing indexes.
+     */
+    private buildNeighborGetter;
+    private executeWith;
+    private computeAggregations;
+    private executeWrite;
+    private executeReturn;
+    private evaluateExpression;
+    private evaluateWhere;
+    private applyOrderByToContexts;
+    /**
+     * Compare two values for sorting. Handles nulls, numbers, strings, booleans.
+     * null < boolean < number < string < object
+     * Mixed-type coercion differs from Neo4j (which throws). Here we stringify
+     * for pragmatic compatibility in exploratory queries.
+     */
+    private compareValues;
+    private matchNodeCriteria;
+}
+//# sourceMappingURL=cypher-engine.d.ts.map

package/dist/engine/cypher-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypher-engine.d.ts","sourceRoot":"","sources":["../../src/engine/cypher-engine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EAcjB,SAAS,EACT,YAAY,EAEb,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AA0D9C,qBAAa,8BAA8B;IACzC,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,OAAO,CAA2B;gBAE9B,KAAK,EAAE,aAAa,EAAE,OAAO,CAAC,EAAE,YAAY;IAKxD;;;OAGG;IACI,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,SAAS,EAAE;IAsBnD;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwE1B,OAAO,CAAC,YAAY;IA6IpB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAqE3B,OAAO,CAAC,WAAW;IAyDnB,OAAO,CAAC,mBAAmB;IAoE3B,OAAO,CAAC,YAAY;IAoEpB,OAAO,CAAC,aAAa;IA8DrB,OAAO,CAAC,kBAAkB;IAa1B,OAAO,CAAC,aAAa;IA4BrB,OAAO,CAAC,sBAAsB;IAsB9B;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAiBrB,OAAO,CAAC,iBAAiB;CAQ1B"}

package/dist/engine/cypher-parser.d.ts

@@ -0,0 +1,3 @@
+import type { AdvancedCypherAST } from '../types/cypher';
+export declare function parseCypher(query: string): AdvancedCypherAST;
+//# sourceMappingURL=cypher-parser.d.ts.map

package/dist/engine/cypher-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypher-parser.d.ts","sourceRoot":"","sources":["../../src/engine/cypher-parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EAalB,MAAM,iBAAiB,CAAC;AAozBzB,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAuD5D"}

package/dist/graph.d.ts

@@ -0,0 +1,24 @@
+export interface GraphInstance {
+    addNode(id: string, attrs?: Record<string, unknown>): void;
+    addEdge(a: string, b: string, attrs?: Record<string, unknown>): void;
+    getNodeAttributes(id: string): Record<string, unknown>;
+    getEdgeAttributes(id: string): Record<string, unknown>;
+    filterNodes(fn: (id: string, attrs: Record<string, unknown>) => boolean): string[];
+    forEachOutboundEdge(id: string, cb: (e: string, a: Record<string, unknown>, s: string, t: string) => void): void;
+    forEachInboundEdge(id: string, cb: (e: string, a: Record<string, unknown>, s: string, t: string) => void): void;
+    /**
+     * Iterate edges incident to a specific node, or all edges when no node ID is given.
+     * (Wraps Graphology's `forEachEdge` which accepts an optional node parameter.)
+     */
+    forEachEdge(id: string, cb: (e: string, a: Record<string, unknown>, s: string, t: string) => void): void;
+    forEachEdge(cb: (e: string, a: Record<string, unknown>, s: string, t: string) => void): void;
+    setNodeAttribute(id: string, attr: string, value: unknown): void;
+    hasNode(id: string): boolean;
+    dropNode(id: string): void;
+    order: number;
+}
+declare const Graph: {
+    new (): GraphInstance;
+};
+export { Graph };
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC3D,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACrE,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,WAAW,CAAC,EAAE,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,GAAG,MAAM,EAAE,CAAC;IACnF,mBAAmB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACjH,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAChH;;;OAGG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IACzG,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC7F,gBAAgB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACjE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,QAAA,MAAM,KAAK,EAA6B;IAAE,QAAQ,aAAa,CAAA;CAAE,CAAC;AAkClE,OAAO,EAAE,KAAK,EAAE,CAAC"}