Library API

import { executeQuery } from 'gcyphrq';

const graphData = {
  nodes: [
    { key: 'alice', attributes: { label: 'User', name: 'Alice', age: 30 } },
    { key: 'bob',   attributes: { label: 'User', name: 'Bob',   age: 25 } },
  ],
  edges: [
    { source: 'alice', target: 'bob', attributes: { type: 'FRIEND' } },
  ],
};

const results = await executeQuery(graphData, 'MATCH (u:User) RETURN u.name, u.age');
console.log(results);
// [ { name: 'Alice', age: 30 }, { name: 'Bob', age: 25 } ]

import { executeQuery } from 'gcyphrq';
import Graph from 'graphology';

const graph = new Graph();
graph.addNode('alice', { label: 'User', name: 'Alice', age: 30 });
graph.addNode('bob', { label: 'User', name: 'Bob', age: 25 });
graph.addEdge('alice', 'bob', { type: 'FRIEND' });

const results = await executeQuery(graph, 'MATCH (u:User) RETURN u.name, u.age');
console.log(results);
// [ { name: 'Alice', age: 30 }, { name: 'Bob', age: 25 } ]

import { executeQuery } from 'gcyphrq';

const results = await executeQuery(graphData, 'MATCH (u:User) RETURN u.name');

import { executeQuery } from 'gcyphrq';

const results = await executeQuery(graphData, 'MATCH (s:Service) RETURN s.name', {
  config: { labelProperty: 'kind', edgeTypeProperty: 'rel' },
});

import { executeQuery } from 'gcyphrq';

// Increase depth limit for sparse graphs where you need deeper traversal
const results = await executeQuery(graphData,
  'MATCH (a:Service)-[*1..]->(b:Database) RETURN a, b',
  {
    config: { maxVariableLengthDepth: 50 },
  },
);

// Tighten path limit for interactive use
const results2 = await executeQuery(graphData,
  'MATCH (a)-[*1..]->(b) RETURN a, b',
  {
    config: { maxVariableLengthPaths: 10_000 },
  },
);

import { executeQuery } from 'gcyphrq';
import Graph from 'graphology';

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 results = await executeQuery(graph, 'MATCH (u:User) RETURN u.name');

import { createGraph } from 'gcyphrq';

const graph = createGraph(graphData);

import { parseCypher } from 'gcyphrq';

const ast = parseCypher('MATCH (u:User) RETURN u');
// ast.type is 'Query' for single queries, 'UnionQuery' for UNION queries
if (ast.type === 'Query') {
  console.log(ast.stages[0].clause.sourcePattern.labels); // ['User']
}

import { explainQuery } from 'gcyphrq';

const plan = explainQuery('MATCH (u:User)-[r:FRIEND]->(f:User) RETURN u, f');
console.log(JSON.stringify(plan, null, 2));
// {
//   query: 'MATCH (u:User)-[r:FRIEND]->(f:User) RETURN u, f',
//   stages: [
//     { index: 0, type: 'MATCH', description: '...', variables: ['u', 'f', 'r'], details: {...} },
//     { index: 1, type: 'RETURN', description: '...', variables: ['u', 'f'], details: {...} }
//   ],
//   finalVariables: ['u', 'f']
// }

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);

import { buildGraphIndexes, GraphEngine } from 'gcyphrq';

const graph = createGraph(graphData);
const indexes = buildGraphIndexes(graph, {
  config: { labelProperty: 'kind', edgeTypeProperty: 'rel' },
});
const engine = new GraphEngine(graph, indexes);

import { GraphEngine, buildGraphIndexes, parseCypher } 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);
const ast = parseCypher('MATCH (u:User) RETURN u.name');
const results = await engine.execute(ast);

new Graph(options?: { type?: 'directed' | 'undirected' | 'mixed' })

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);

import { GraphError, createGraph } from 'gcyphrq';

try {
  createGraph({ nodes: [], edges: [] });
} catch (err) {
  if (err instanceof GraphError) {
    console.error('Graph validation failed:', err.message);
  }
}

import { convertWithExtension, executeQuery } from 'gcyphrq';
import { readFileSync } from 'fs';

const content = readFileSync('data.gexf', 'utf-8');
const { graph } = await convertWithExtension('gexf', {
  content,
  filePath: 'data.gexf',
});
const results = await executeQuery(graph, 'MATCH (n) RETURN n');

import { registerFunctionExtension, executeQuery } from 'gcyphrq';

await registerFunctionExtension('apoc-commons');
await registerFunctionExtension('apoc-crypto');

const results = await executeQuery(graphData, 'RETURN apoc.text.join(", ", ["a","b"])');

import { listExtensions } from 'gcyphrq';

const extensions = listExtensions();
for (const ext of extensions) {
  console.log(`${ext.name} (${ext.type}) — ${ext.description}`);
}

import { helpers, validate, FunctionError } from 'gcyphrq';

// Type predicates
helpers.isString(value);
helpers.isNumber(value);
helpers.isArray(value);

// Argument validator
const { sep, values } = validate(args, (v) => {
  v.minCount(2);
  v.arg(0, 'sep', helpers.isString);
  v.argsFrom(1, 'values');
});

// User-facing validation error
throw new FunctionError('Cannot convert null to integer');
// Engine reports: "Error in apoc.toInt: Cannot convert null to integer"

import { executeQuery } from 'gcyphrq';

const results = await executeQuery(graphData, 'MATCH (u:User) RETURN u.name');

import { createGraph, GraphEngine, parseCypher } from 'gcyphrq';

const graph = createGraph(graphData);
const engine = new GraphEngine(graph);

const users = await engine.execute(parseCypher('MATCH (u:User) RETURN u.name'));
const counts = await engine.execute(parseCypher('MATCH (u:User) RETURN count(u)'));

import { Graph, GraphEngine, parseCypher } from 'gcyphrq';

const graph = new Graph();

// Build from a database query, API response, etc.
for (const user of users) {
  graph.addNode(user.id, { label: 'User', ...user.properties });
}
for (const rel of relationships) {
  graph.addEdge(rel.from, rel.to, { type: rel.type });
}

const engine = new GraphEngine(graph);
const results = await engine.execute(parseCypher('MATCH (u:User) RETURN u'));

import { executeQuery, buildGraphIndexes, GraphEngine, parseCypher } from 'gcyphrq';
import Graph from 'graphology';

// Build graph from any source (database, API, file, etc.)
const graph = new Graph();
for (const node of nodesFromDatabase) {
  graph.addNode(node.id, { label: node.label, ...node.properties });
}
for (const edge of edgesFromDatabase) {
  graph.addEdge(edge.source, edge.target, { type: edge.type });
}

// One-shot query (indexes built automatically)
const results = await executeQuery(graph, 'MATCH (u:User) RETURN u.name');

// Or with reusable engine and indexes for multiple queries
const indexes = buildGraphIndexes(graph);
const engine = new GraphEngine(graph, indexes);
const users = await engine.execute(parseCypher('MATCH (u:User) RETURN u.name'));
const count = await engine.execute(parseCypher('MATCH (u:User) RETURN count(u)'));

import { parseCypher } from 'gcyphrq';

const ast = parseCypher('MATCH (u:User {name: "Alice"}) RETURN u');
if (ast.type === 'Query') {
  console.log(ast.stages[0].clause.sourcePattern.properties);
  // { name: 'Alice' }
}

import { executeQuery } from 'gcyphrq';

const results = await executeQuery(graphData,
  'MATCH (u:User {name: "Alice"}) RETURN u.name UNION ALL MATCH (u:User {name: "Bob"}) RETURN u.name',
);
// [ { name: 'Alice' }, { name: 'Bob' } ]

import { createGraph, GraphEngine, parseCypher } from 'gcyphrq';

const graph = createGraph(graphData);
const engine = new GraphEngine(graph);

// Create a new node
await engine.execute(parseCypher('CREATE (n:User {name: "Charlie"}) RETURN n'));

// Update a node
await engine.execute(parseCypher('MATCH (u:User {name: "Alice"}) SET u.age = 31 RETURN u'));

// Query after mutation
const results = await engine.execute(parseCypher('MATCH (u:User) RETURN u.name, u.age'));

import type {
  // Graph data (Graphology JSON format)
  GraphInput,
  GraphologyFile,
  GraphologyNode,
  GraphologyEdge,
  GraphologyGraphOptions,

  // Graph instance
  GraphInstance,
  GraphIndexes,

  // Options
  GraphOptions,
  IndexBuildOptions,
  GraphConfig,

  // AST types
  AdvancedCypherAST,
  UnionQueryAST,
  UnionType,
  CypherAST,
  Stage,
  MatchClause,
  WithClause,
  ReturnClause,
  WriteClause,
  SetClause,
  SetItem,
  CallClause,
  LoadCsvClause,
  NodePattern,
  RelationPattern,
  Direction,

  // Expression types
  Expression,
  PropertyAccessExpression,
  LiteralExpression,
  AggregationExpression,
  BinaryExpression,
  Projection,
  OrderByItem,
  UnwindClause,

  // Result types
  ResultRow,
  QueryContext,
  CypherNode,
  CypherEdge,
  CypherValue,
  CypherLiteral,
  SubgraphResult,

  // Extension types
  GraphInputExtension,
  GraphInputExtensionContext,
  FunctionExtension,
  FunctionRegistry,
  ScalarFunction,
  AggregationFunction,
  ExtensionManifest,
  ResolvedExtension,
  LoadedExtension,
  ArgHelpers,
  ArgValidator,
} from 'gcyphrq';

type GraphInput = GraphologyFile;

interface IndexBuildOptions extends GraphOptions {
  /** Partial config for label/edge-type property names. */
  config?: Partial<GraphConfig>;
}

interface GraphConfig {
  /** Node attribute key used as the Cypher label (default: `"label"`). */
  labelProperty: string;
  /** Edge attribute key used as the Cypher relationship type (default: `"type"`). */
  edgeTypeProperty: string;
  /** Max depth for unbounded variable-length patterns like [*1..] (default: 10). */
  maxVariableLengthDepth?: number;
  /** Max paths per (startNode, hop) in variable-length traversal (default: 100_000). */
  maxVariableLengthPaths?: number;
}

interface GraphOptions {
  /** Callback for non-fatal warnings during graph construction. */
  onWarning?: (message: string) => void;
}

interface GraphologyFile {
  options?: GraphologyGraphOptions;
  attributes?: Record<string, unknown>;
  nodes: GraphologyNode[];
  edges: GraphologyEdge[];
}

interface GraphologyNode {
  key: string;
  attributes: Record<string, unknown>;
}

interface GraphologyEdge {
  key?: string;
  source: string;
  target: string;
  undirected?: boolean; // only effective in mixed graphs; makes the edge bidirectional
  attributes: Record<string, unknown>;
}

interface GraphologyGraphOptions {
  type?: 'directed' | 'undirected' | 'mixed'; // all three are supported
  allowSelfLoops?: boolean;                    // enables self-loop edges
  multi?: boolean;                             // enables parallel edges between same nodes
}

type ResultRow = Record<string, CypherNode | CypherEdge[] | CypherLiteral | null | undefined>;

interface SubgraphResult {
  nodes: CypherNode[];
  edges: CypherEdge[];
}

interface AdvancedCypherAST {
  type: 'Query';
  stages: Stage[];
  return: ReturnClause | undefined;
}

type Stage =
  | { type: 'MATCH'; clause: MatchClause }
  | { type: 'WITH'; clause: WithClause }
  | { type: 'WRITE'; clause: WriteClause }
  | { type: 'MERGE'; clause: MergeClause }
  | { type: 'UNWIND'; clause: UnwindClause }
  | { type: 'FOREACH'; clause: ForeachClause }
  | { type: 'CALL'; clause: CallClause }
  | { type: 'LOAD_CSV'; clause: LoadCsvClause };

interface UnionQueryAST {
  type: 'UnionQuery';
  branches: AdvancedCypherAST[];
  unionTypes: (UnionType | null)[]; // null for first branch, then 'UNION' or 'UNION ALL'
  orderBy: OrderByItem[] | undefined; // ORDER BY on combined result
  skip: number | undefined;           // SKIP on combined result
  limit: number | undefined;          // LIMIT on combined result
}

type UnionType = 'UNION' | 'UNION ALL';

type CypherAST = AdvancedCypherAST | UnionQueryAST;

import { executeQuery, GraphError } from 'gcyphrq';

try {
  const results = await executeQuery(graphData, query);
} catch (err) {
  if (err instanceof GraphError) {
    // Graph data is invalid
    console.error('Invalid graph:', err.message);
  } else {
    // Query error
    console.error('Query failed:', err.message);
  }
}