@neumann/client

TypeScript SDK for the Neumann database.

Installation

npm install @neumann/client

For browser support with gRPC-Web:

npm install @neumann/client grpc-web

Quick Start

import { NeumannClient, isRowsResult, rowToObject } from '@neumann/client';

// Connect to a remote server
const client = await NeumannClient.connect('localhost:9200', {
  apiKey: 'your-api-key',
  tls: true,
});

// Execute a query
const result = await client.execute('SELECT users');

if (isRowsResult(result)) {
  for (const row of result.rows) {
    console.log(rowToObject(row));
  }
}

// Close the connection
client.close();

Features

• Dual environment support: Node.js (gRPC) and browser (gRPC-Web)
• Type-safe: Full TypeScript support with discriminated unions
• Streaming: Support for streaming query results
• Batch queries: Execute multiple queries efficiently
• Error handling: Typed error hierarchy with error codes

Connection Options

Node.js (gRPC)

const client = await NeumannClient.connect('localhost:9200', {
  apiKey: 'your-api-key',
  tls: true,
  metadata: { 'custom-header': 'value' },
});

Browser (gRPC-Web)

const client = await NeumannClient.connectWeb('https://api.example.com', {
  apiKey: 'your-api-key',
});

Query Execution

Single Query

const result = await client.execute('SELECT users WHERE age > 21');

Streaming Query

for await (const result of client.executeStream('SELECT large_table')) {
  if (isRowsResult(result)) {
    console.log(`Batch of ${result.rows.length} rows`);
  }
}

Batch Queries

const results = await client.executeBatch([
  'SELECT users',
  'SELECT orders',
  'SELECT products',
]);

Result Types

Query results use discriminated unions for type safety:

import {
  isRowsResult,
  isNodesResult,
  isEdgesResult,
  isPathsResult,
  isSimilarResult,
  isErrorResult,
} from '@neumann/client';

const result = await client.execute(query);

switch (result.type) {
  case 'rows':
    for (const row of result.rows) {
      console.log(rowToObject(row));
    }
    break;
  case 'nodes':
    for (const node of result.nodes) {
      console.log(nodeToObject(node));
    }
    break;
  case 'similar':
    for (const item of result.items) {
      console.log(`${item.key}: ${item.score}`);
    }
    break;
  case 'error':
    console.error(result.message);
    break;
}

Value Types

The SDK provides type-safe value handling:

import {
  intValue,
  stringValue,
  valueToNative,
  valueFromNative,
} from '@neumann/client';

// Create typed values
const age = intValue(25);
const name = stringValue('Alice');

// Convert to native JavaScript types
const nativeAge = valueToNative(age); // number: 25

// Convert from native JavaScript values
const value = valueFromNative(42); // { type: 'int', data: 42 }

Error Handling

import {
  NeumannError,
  ConnectionError,
  AuthenticationError,
  QueryError,
  ErrorCode,
} from '@neumann/client';

try {
  const result = await client.execute(query);
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('Connection failed:', error.message);
  } else if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof QueryError) {
    console.error('Query failed:', error.message);
  } else if (error instanceof NeumannError) {
    console.error(`Error [${ErrorCode[error.code]}]:`, error.message);
  }
}

API Reference

NeumannClient

| Method | Description | | ------ | ----------- | | connect(address, options) | Connect via gRPC (Node.js) | | connectWeb(address, options) | Connect via gRPC-Web (browser) | | execute(query, options) | Execute a single query | | executeStream(query, options) | Stream query results | | executeBatch(queries, options) | Execute multiple queries | | close() | Close the connection | | isConnected | Check connection status | | clientMode | Get client mode (remote/embedded) |

ConnectOptions

| Option | Type | Description | | ------ | ---- | ----------- | | apiKey | string | API key for authentication | | tls | boolean | Enable TLS encryption | | metadata | Record<string, string> | Custom headers |

QueryOptions

| Option | Type | Description | | ------ | ---- | ----------- | | identity | string | Identity for vault access |

Requirements

• Node.js 18.0.0 or later
• TypeScript 5.0+ (for type definitions)

License

MIT