Graphmind TypeScript SDK

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:8080

  cause The Graphmind server is not running or is not accessible at the specified URL and port.
  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.

• TypeError: GraphmindClient is not a constructor

  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.
  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.

• TypeError: client.query is not a function

  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.
  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.

Warnings

• breaking 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.
  Fix: Upgrade your Node.js environment to version 18 or higher.
• breaking 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.
  Fix: Consult the official Graphmind SDK v0.8.0 changelog on GitHub for detailed breaking changes and migration steps.
• gotcha 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.
  Fix: Use `process.env.YOUR_TOKEN_VAR_NAME ?? ''` to retrieve authentication tokens, ensuring the environment variable is set in your deployment environment.

Install

• npm install graphmind-sdk npm
• yarn add graphmind-sdk yarn
• pnpm add graphmind-sdk pnpm

Imports

• GraphmindClient
  wrong:

  const GraphmindClient = require('graphmind-sdk').GraphmindClient;

  correct:

  import { GraphmindClient } from 'graphmind-sdk';

  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.
• GraphmindClientConfig
  wrong:

  import { GraphmindClientConfig } from 'graphmind-sdk';

  correct:

  import type { GraphmindClientConfig } from 'graphmind-sdk';

  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.

Quickstart

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.

import { GraphmindClient } from 'graphmind-sdk';

async function runExample() {
  const client = new GraphmindClient({ url: 'http://localhost:8080' });

  try {
    // Create data (semicolons separate multiple statements)
    console.log('Creating initial data...');
    await client.query(`
      CREATE (a:Person {name: "Alice", age: 30});
      CREATE (b:Person {name: "Bob", age: 25});
      MATCH (a:Person {name: "Alice"}), (b:Person {name: "Bob"})
      CREATE (a)-[:KNOWS]->(b)
    `);
    console.log('Initial data created.');

    // Or use shared variables (no semicolons needed)
    console.log('Creating more data...');
    await client.query(`
      CREATE (c:Person {name: "Charlie", age: 35})
      CREATE (d:Person {name: "Diana", age: 28})
      CREATE (c)-[:KNOWS {since: 2023}]->(d)
    `);
    console.log('More data created.');

    // Query existing data
    console.log('Querying all persons...');
    const result = await client.query('MATCH (n:Person) RETURN n.name, n.age ORDER BY n.name');
    console.log('Query Result:', result);

    // Get schema introspection
    console.log('Fetching database schema...');
    const schema = await client.schema();
    console.log('Database Schema:', JSON.stringify(schema, null, 2));

    // Example with authentication using environment variable
    const authenticatedClient = new GraphmindClient({
      url: 'http://localhost:8080',
      token: process.env.GRAPHMIND_TOKEN ?? '', // Ensure GRAPHMIND_TOKEN env var is set
    });
    console.log('Checking authenticated client status...');
    const status = await authenticatedClient.status();
    console.log('Authenticated Client Status:', status);

  } catch (error) {
    console.error('An error occurred:', error.message);
    if (error.response) {
        console.error('Server response data:', error.response.data);
    }
  }
}

runExample().catch(console.error);