gcyphrq 0.12.6

package/docs/examples.md

@@ -0,0 +1,223 @@
+---
+layout: default
+title: Examples
+description: 19 ready-to-run Cypher queries against the bundled cloud infrastructure graph.
+---
+
+<div class="breadcrumb">
+  <a href="{{ '/' | relative_url }}">Home</a> <span>›</span> Examples
+</div>
+
+# Examples
+
+This page provides ready-to-run Cypher queries against the bundled example graphs.
+
+## Available Graphs
+
+| File | Description |
+|---|---|
+| `social-graph.json` | A small social network with three users connected by `FRIEND` relationships |
+| `cloud-infra.json` | A full startup cloud infrastructure — 52 nodes, 110 edges — with RPC services, message queues, databases, workers, monitoring, and external APIs |
+
+## Usage
+
+```bash
+# Load a graph from file
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u'
+
+# Pipe a graph from stdin
+cat examples/social-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'
+```
+
+---
+
+## `cloud-infra.json` — Query Examples
+
+This graph models an entire startup's cloud service infrastructure. Use it to explore real-world queries like impact analysis, dependency chains, and service topology.
+
+### 1. List all RPC services
+
+Find every service of type `RPC` running in the infrastructure:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service {type: "RPC"}) RETURN s'
+```
+
+### 2. Trace the full request path from the public API to databases
+
+Follow the call chain from the API Gateway, 2–4 hops deep, to see which databases a request can reach:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (api:Service {name: "API Gateway"})-[r*2..4]->(db:Database) RETURN api, r, db'
+```
+
+### 3. Find all services that depend on a specific database
+
+Discover every service that has a direct connection to the PostgreSQL primary:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[:TCP]->(db:Database {name: "PostgreSQL Primary"}) RETURN s'
+```
+
+### 4. Count how many services each message queue feeds into
+
+Group by message queue and count the downstream consumers:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (mq:Infrastructure {type: "MessageQueue"})-[:TCP]->(w:Service) WITH mq, count(w) AS consumerCount RETURN mq, consumerCount'
+```
+
+### 5. Find the blast radius of a service failure
+
+If the Kafka cluster goes down, which services are directly or indirectly affected (up to 2 hops)?
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (kafka:Infrastructure {name: "Kafka Cluster"})-[r*1..2]-(affected) RETURN kafka, r, affected'
+```
+
+### 6. List all external dependencies per service
+
+For each RPC service, find which external APIs it calls (directly or through intermediaries, up to 3 hops):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service {type: "RPC"})-[r*1..3]->(ext:External) RETURN s, ext'
+```
+
+### 7. Find which services call Stripe
+
+Trace from any service through up to 3 hops to find which ones reach the Stripe API:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[r*1..3]->(stripe:External {name: "Stripe API"}) RETURN s, stripe'
+```
+
+### 8. Map the replication topology
+
+Find all replication relationships between databases:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (primary:Database)-[r:Replication]->(replica:Database) RETURN primary, r, replica'
+```
+
+### 9. Find the longest dependency chain
+
+Trace paths from the CDN (edge) down through the infrastructure to storage or databases (up to 6 hops):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (cdn:Service {name: "CloudFront CDN"})-[r*1..6]->(leaf:Database) RETURN cdn, r, leaf'
+```
+
+### 10. List all services hosted on the primary EKS cluster
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (eks:Infrastructure {name: "EKS Cluster"})-[:Hosts]->(s:Service) RETURN s'
+```
+
+### 11. Find which services talk to Vault for secrets
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[:HTTPS]->(v:Security {name: "Vault"}) RETURN s'
+```
+
+### 12. Count outgoing connections per service
+
+Rank services by how many direct dependencies they have:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[]->(target) WITH s, count(target) AS outDegree WHERE outDegree > 2 RETURN s, outDegree'
+```
+
+### 13. Sort services by name (ORDER BY)
+
+Return all services sorted alphabetically by name:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name ORDER BY s.name ASC'
+```
+
+### 14. Top-N services by connection count (ORDER BY + LIMIT)
+
+Find the 3 services with the most outgoing connections:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service)-[]->(target) WITH s, count(target) AS outDegree ORDER BY outDegree DESC LIMIT 3 RETURN s.name, outDegree'
+```
+
+### 15. Limit results to first N (LIMIT)
+
+Return only the first 5 databases in the infrastructure:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (d:Database) RETURN d.name LIMIT 5'
+```
+
+### 16. Sort by multiple columns
+
+Sort services first by type (ascending), then by name (descending):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.type, s.name ORDER BY s.type ASC, s.name DESC'
+```
+
+### 17. Skip first N results (SKIP)
+
+Skip the first 5 services when listing all services:
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name SKIP 5'
+```
+
+### 18. Pagination with ORDER BY + SKIP + LIMIT
+
+Get page 2 of services sorted by name (10 per page):
+
+```bash
+gcyphrq -g examples/cloud-infra.json -e 'MATCH (s:Service) RETURN s.name ORDER BY s.name ASC SKIP 10 LIMIT 10'
+```
+
+### 19. Average, min, max aggregations
+
+Compute average, minimum, and maximum across all users:
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN avg(u.age) AS avgAge, min(u.age) AS minAge, max(u.age) AS maxAge'
+```
+
+---
+
+## `social-graph.json` — Query Examples
+
+This small graph contains three users connected by `FRIEND` relationships:
+
+```
+Alice --FRIEND--> Bob --FRIEND--> Charlie
+```
+
+### List all users
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (u:User) RETURN u.name'
+```
+
+### Find Alice's friends
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (a:User {name: "Alice"})-[:FRIEND]->(f) RETURN f.name'
+```
+
+### Find friends of friends (2-hop path)
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH (a:User {name: "Alice"})-[:FRIEND*2..2]-(fof:User) RETURN fof.name'
+```
+
+### Count total friendships
+
+```bash
+gcyphrq -g examples/social-graph.json -e 'MATCH ()-[r:FRIEND]->() RETURN count(r) AS totalFriendships'
+```
+
+## Next Steps
+
+- **[Query Guide](query-guide)** — Full Cypher syntax reference and query patterns
+- **[Library API](library-api)** — Use gcyphrq programmatically in your code

package/docs/getting-started.md

@@ -0,0 +1,158 @@
+---
+layout: default
+title: Getting Started
+description: Install gcyphrq and run your first Cypher query.
+---
+
+<div class="breadcrumb">
+  <a href="{{ '/' | relative_url }}">Home</a> <span>›</span> Getting Started
+</div>
+
+# Getting Started
+
+This guide will help you install `gcyphrq` and run your first Cypher query against an in-memory graph.
+
+## Prerequisites
+
+- **Node.js** {{ site.node_version }} or later
+- **npm** (or any compatible package manager)
+
+## Installation
+
+### Global CLI
+
+```bash
+npm install -g gcyphrq
+```
+
+This makes the `gcyphrq` command available globally on your PATH.
+
+### Project dependency
+
+```bash
+npm install gcyphrq
+```
+
+### From source
+
+```bash
+git clone https://github.com/plelevier/gcyphrq.git
+cd gcyphrq
+npm install
+npm run build
+npm link
+```
+
+## Your First Query
+
+### 1. Create a graph file
+
+Create a file called `social-graph.json`:
+
+```json
+{
+  "nodes": [
+    { "id": "alice", "label": "User", "name": "Alice", "age": 30 },
+    { "id": "bob",   "label": "User", "name": "Bob",   "age": 25 },
+    { "id": "charlie","label": "User", "name": "Charlie","age": 35 }
+  ],
+  "edges": [
+    { "source": "alice", "target": "bob", "type": "FRIEND" },
+    { "source": "bob", "target": "charlie", "type": "FRIEND" }
+  ]
+}
+```
+
+### 2. Run a query
+
+```bash
+gcyphrq -g social-graph.json -e 'MATCH (u:User) RETURN u.name, u.age'
+```
+
+**Output:**
+
+```json
+[
+  { "name": "Alice", "age": 30 },
+  { "name": "Bob", "age": 25 },
+  { "name": "Charlie", "age": 35 }
+]
+```
+
+### 3. Pipe to `jq`
+
+The CLI outputs raw JSON, so you can pipe it directly to `jq`:
+
+```bash
+gcyphrq -g social-graph.json -e 'MATCH (u:User) RETURN u.name' | jq '.[].name'
+```
+
+## Graph File Format
+
+Graphs are described as JSON files with two arrays:
+
+```json
+{
+  "nodes": [
+    { "id": "<unique-id>", "label": "<label>", "<property>": "<value>", ... }
+  ],
+  "edges": [
+    { "source": "<source-id>", "target": "<target-id>", "type": "<edge-type>", ... }
+  ]
+}
+```
+
+### Node properties
+
+- **`id`** — required, unique string identifier for each node
+- **`label`** — optional, used for filtering in Cypher queries (e.g., `(u:User)`)
+- Additional properties become node attributes accessible in queries
+
+### Edge properties
+
+- **`source`** — required, the `id` of the source node
+- **`target`** — required, the `id` of the target node
+- **`type`** — optional, used for filtering in Cypher queries (e.g., `[:FRIEND]`)
+- Additional properties become edge attributes
+- Edge IDs are auto-generated by Graphology (you cannot specify custom edge IDs)
+
+<div class="callout">
+  <p><strong>Note:</strong> Multi-graphs (multiple edges between the same pair of nodes) are not supported.</p>
+</div>
+
+## Reading from stdin
+
+Instead of a file, you can pipe the graph from stdin using `-g -`:
+
+```bash
+cat my-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'
+```
+
+## Using as a Library
+
+For programmatic access, import `gcyphrq` in your TypeScript or Node.js project:
+
+```ts
+import { executeQuery } from 'gcyphrq';
+
+const graphData = {
+  nodes: [
+    { id: 'alice', label: 'User', name: 'Alice', age: 30 },
+    { id: 'bob', label: 'User', name: 'Bob', age: 25 },
+  ],
+  edges: [
+    { source: 'alice', target: 'bob', type: 'FRIEND' },
+  ],
+};
+
+const results = executeQuery(graphData, 'MATCH (u:User) RETURN u.name, u.age');
+console.log(results);
+// [ { name: 'Alice', age: 30 }, { name: 'Bob', age: 25 } ]
+```
+
+## Next Steps
+
+- **[CLI Reference](cli)** — Full documentation of CLI options and usage patterns
+- **[Query Guide](query-guide)** — Cypher syntax reference, supported features, and query patterns
+- **[Library API](library-api)** — Complete API reference for Node.js / TypeScript usage
+- **[Examples](examples)** — 18 ready-to-run queries against the bundled cloud infrastructure graph

package/docs/index.md

@@ -0,0 +1,89 @@
+---
+layout: default
+title: Home
+description: A Cypher graph query engine for in-memory graphs built on Graphology.
+---
+
+<div class="hero">
+  <h1>gcyphrq</h1>
+  <p class="tagline">A Cypher graph query engine for in-memory graphs. Parse a graph from JSON, run a Cypher query, get raw JSON results.</p>
+  <div class="hero-actions">
+    <a href="{{ '/getting-started/' | relative_url }}" class="btn btn-primary">Getting Started →</a>
+    <a href="https://github.com/plelevier/gcyphrq" class="btn btn-secondary" target="_blank" rel="noopener noreferrer">View on GitHub ↗</a>
+  </div>
+</div>
+
+<div class="feature-grid">
+  <div class="feature-card">
+    <h3>🔍 Cypher Queries</h3>
+    <p>Full support for <code>MATCH</code>, <code>OPTIONAL MATCH</code>, <code>WITH</code>, <code>RETURN</code>, <code>ORDER BY</code>, <code>SKIP</code>, <code>LIMIT</code>, and mutations.</p>
+  </div>
+  <div class="feature-card">
+    <h3>📐 Variable-Length Paths</h3>
+    <p>Traverse graphs with variable-depth paths like <code>-[r:FRIEND*1..3]-</code> to explore connections at any depth.</p>
+  </div>
+  <div class="feature-card">
+    <h3>📦 CLI &amp; Library</h3>
+    <p>Use as a CLI tool for quick queries or import as a TypeScript/Node.js library in your projects.</p>
+  </div>
+  <div class="feature-card">
+    <h3>📊 Aggregations</h3>
+    <p>Group and aggregate with <code>count()</code>, <code>sum()</code>, <code>avg()</code>, <code>min()</code>, <code>max()</code> and implicit grouping via <code>WITH</code> pipelining.</p>
+  </div>
+  <div class="feature-card">
+    <h3>✏️ Mutations</h3>
+    <p>Create, update, and delete nodes and edges with <code>CREATE</code>, <code>SET</code>, and <code>DELETE</code> clauses.</p>
+  </div>
+  <div class="feature-card">
+    <h3>🔧 TypeScript</h3>
+    <p>Full type declarations shipped with the package. Works seamlessly in TypeScript projects.</p>
+  </div>
+</div>
+
+---
+
+## Quick Start
+
+Install and run your first query in seconds:
+
+```bash
+# Install globally
+npm install -g gcyphrq
+
+# Run a query against a JSON graph
+gcyphrq -g my-graph.json -e 'MATCH (u:User) RETURN u.name'
+```
+
+Or use it as a library:
+
+```ts
+import { executeQuery } from 'gcyphrq';
+
+const results = executeQuery(graphData, 'MATCH (u:User) RETURN u.name');
+```
+
+## Supported Cypher Features
+
+| Feature | Status |
+|---|---|
+| `MATCH` with node labels and properties | <span class="badge badge-success">✅</span> |
+| Variable-length paths `*min..max` | <span class="badge badge-success">✅</span> |
+| Directional edges `->`, `<-`, `-` | <span class="badge badge-success">✅</span> |
+| `OPTIONAL MATCH` | <span class="badge badge-success">✅</span> |
+| `RETURN` with aliases | <span class="badge badge-success">✅</span> |
+| `WITH` + implicit grouping | <span class="badge badge-success">✅</span> |
+| `count()`, `sum()`, `avg()`, `min()`, `max()` aggregations | <span class="badge badge-success">✅</span> |
+| `WHERE` with `>`, `<`, `=`, `CONTAINS` | <span class="badge badge-success">✅</span> |
+| `CREATE`, `SET`, `DELETE` mutations | <span class="badge badge-success">✅</span> |
+| `ORDER BY` (single/multi-column) | <span class="badge badge-success">✅</span> |
+| `SKIP` / `LIMIT` | <span class="badge badge-success">✅</span> |
+| Subqueries, `CALL`, APOC | <span class="badge badge-danger">❌</span> |
+
+## Example Graphs
+
+Two example graphs are bundled with the package:
+
+- **`social-graph.json`** — A small social network with three users connected by `FRIEND` relationships
+- **`cloud-infra.json`** — A full startup cloud infrastructure with 52 nodes and 110 edges
+
+See the [Examples](examples) page for 19 ready-to-run queries against the cloud infrastructure graph.