{"id":16626,"library":"graphmind-sdk","title":"Graphmind TypeScript SDK","description":"The `graphmind-sdk` is a TypeScript/Node.js client library designed to facilitate interaction with the Graphmind high-performance graph database, which natively supports OpenCypher. As of version 0.8.6, the SDK provides a comprehensive API for executing Cypher queries, managing graph schemas, performing health checks, and interacting with multi-tenant graph namespaces. It maintains a relatively active release cadence, frequently publishing patch versions. Key features include robust methods for standard query execution, schema introspection, query profiling, and an experimental natural language to Cypher (NLQ) translation capability. The SDK differentiates itself through its direct integration with Graphmind's performance optimizations and its support for distinct graph namespaces, enabling robust multi-tenancy scenarios.","status":"active","version":"0.8.6","language":"javascript","source_language":"en","source_url":"https://github.com/fab679/graphmind","tags":["javascript","graph","database","cypher","graphmind","typescript"],"install":[{"cmd":"npm install graphmind-sdk","lang":"bash","label":"npm"},{"cmd":"yarn add graphmind-sdk","lang":"bash","label":"yarn"},{"cmd":"pnpm add graphmind-sdk","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The SDK is primarily designed for ESM usage. Direct `require` calls for named exports might lead to issues in some environments or require specific Babel/TypeScript configurations.","wrong":"const GraphmindClient = require('graphmind-sdk').GraphmindClient;","symbol":"GraphmindClient","correct":"import { GraphmindClient } from 'graphmind-sdk';"},{"note":"While not explicitly shown in the README, the configuration object passed to `GraphmindClient` constructor is typed as `GraphmindClientConfig`. It's a type import, not a runtime value.","wrong":"import { GraphmindClientConfig } from 'graphmind-sdk';","symbol":"GraphmindClientConfig","correct":"import type { GraphmindClientConfig } from 'graphmind-sdk';"}],"quickstart":{"code":"import { GraphmindClient } from 'graphmind-sdk';\n\nasync function runExample() {\n  const client = new GraphmindClient({ url: 'http://localhost:8080' });\n\n  try {\n    // Create data (semicolons separate multiple statements)\n    console.log('Creating initial data...');\n    await client.query(`\n      CREATE (a:Person {name: \"Alice\", age: 30});\n      CREATE (b:Person {name: \"Bob\", age: 25});\n      MATCH (a:Person {name: \"Alice\"}), (b:Person {name: \"Bob\"})\n      CREATE (a)-[:KNOWS]->(b)\n    `);\n    console.log('Initial data created.');\n\n    // Or use shared variables (no semicolons needed)\n    console.log('Creating more data...');\n    await client.query(`\n      CREATE (c:Person {name: \"Charlie\", age: 35})\n      CREATE (d:Person {name: \"Diana\", age: 28})\n      CREATE (c)-[:KNOWS {since: 2023}]->(d)\n    `);\n    console.log('More data created.');\n\n    // Query existing data\n    console.log('Querying all persons...');\n    const result = await client.query('MATCH (n:Person) RETURN n.name, n.age ORDER BY n.name');\n    console.log('Query Result:', result);\n\n    // Get schema introspection\n    console.log('Fetching database schema...');\n    const schema = await client.schema();\n    console.log('Database Schema:', JSON.stringify(schema, null, 2));\n\n    // Example with authentication using environment variable\n    const authenticatedClient = new GraphmindClient({\n      url: 'http://localhost:8080',\n      token: process.env.GRAPHMIND_TOKEN ?? '', // Ensure GRAPHMIND_TOKEN env var is set\n    });\n    console.log('Checking authenticated client status...');\n    const status = await authenticatedClient.status();\n    console.log('Authenticated Client Status:', status);\n\n  } catch (error) {\n    console.error('An error occurred:', error.message);\n    if (error.response) {\n        console.error('Server response data:', error.response.data);\n    }\n  }\n}\n\nrunExample().catch(console.error);","lang":"typescript","description":"This quickstart initializes a Graphmind client, demonstrates creating and querying data using Cypher, fetches the database schema, and shows how to configure a client with an authentication token from environment variables."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or higher.","message":"The `graphmind-sdk` requires Node.js version 18 or newer. Older Node.js versions are not supported and will likely result in runtime errors or unexpected behavior.","severity":"breaking","affected_versions":"<18.0.0"},{"fix":"Consult the official Graphmind SDK v0.8.0 changelog on GitHub for detailed breaking changes and migration steps.","message":"Major version changes from v0.6.x to v0.8.x likely introduce breaking API changes. The changelog indicates a significant jump (v0.6.5 to v0.8.0), suggesting refactoring or interface modifications. Users upgrading across this boundary should thoroughly review the full changelog on GitHub for specific breaking changes.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Use `process.env.YOUR_TOKEN_VAR_NAME ?? ''` to retrieve authentication tokens, ensuring the environment variable is set in your deployment environment.","message":"Authentication tokens passed to `GraphmindClient` configuration should be securely managed, ideally through environment variables or a secure configuration management system, rather than hardcoding them directly in source code.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure the Graphmind server is running and listening on `http://localhost:8080`, or update the `url` in `GraphmindClient` configuration to the correct server address.","cause":"The Graphmind server is not running or is not accessible at the specified URL and port.","error":"Error: connect ECONNREFUSED 127.0.0.1:8080"},{"fix":"Ensure you are using `import { GraphmindClient } from 'graphmind-sdk';` in an ESM-enabled Node.js environment or TypeScript project. If using CommonJS, configure your build system to handle ESM imports correctly or explicitly use dynamic imports if available.","cause":"This error often occurs when attempting to import a TypeScript ESM-first library using CommonJS `require()` syntax without proper transpilation or when the default export is expected but named export is provided.","error":"TypeError: GraphmindClient is not a constructor"},{"fix":"Double-check the method name (e.g., `query` vs `Query`). Ensure `new GraphmindClient(...)` was successfully called and that you `await` any asynchronous operations before trying to access methods on the returned client instance.","cause":"This typically indicates a typo in the method name, or the `client` object was not correctly instantiated, or a Promise chain was not `await`ed, leading to an undefined object.","error":"TypeError: client.query is not a function"}],"ecosystem":"npm"}