@irongraph/client 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,57 @@
+export type TypedValue = {
+    type: 'null';
+} | {
+    type: 'boolean';
+    value: boolean;
+} | {
+    type: 'integer';
+    value: string;
+} | {
+    type: 'float';
+    value: number;
+} | {
+    type: 'string';
+    value: string;
+} | {
+    type: string;
+    value?: unknown;
+};
+export interface QueryRequest {
+    cypher: string;
+    projectId?: string;
+    parameters?: Record<string, unknown>;
+    bookmark?: {
+        term: number;
+        index: number;
+    };
+    limits?: Partial<QueryLimits>;
+    signal?: AbortSignal;
+}
+export interface QueryLimits {
+    rows: number;
+    bytes: number;
+    nodes: number;
+    edges: number;
+}
+export interface QueryColumn {
+    name: string;
+    value_type: string;
+    nullable: boolean;
+}
+export interface QueryResult {
+    catalog?: Record<string, unknown>;
+    columns: QueryColumn[];
+    rows: TypedValue[][];
+    summary: Record<string, unknown>;
+}
+export declare class IronGraphError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly retryAfterMs?: number | undefined;
+    constructor(message: string, code: string, retryable?: boolean, retryAfterMs?: number | undefined);
+}
+export declare class Client {
+    private readonly endpoint;
+    constructor(baseUrl: string | URL);
+    query(request: QueryRequest): Promise<QueryResult>;
+}

package/dist/index.js

@@ -0,0 +1,105 @@
+const MAXIMUM_EVENT_CHARACTERS = 64 * 1024 * 1024;
+export class IronGraphError extends Error {
+    code;
+    retryable;
+    retryAfterMs;
+    constructor(message, code, retryable = false, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'IronGraphError';
+    }
+}
+export class Client {
+    endpoint;
+    constructor(baseUrl) {
+        this.endpoint = new URL('/api/query', baseUrl);
+        const local = this.endpoint.hostname === 'localhost'
+            || this.endpoint.hostname === '127.0.0.1'
+            || this.endpoint.hostname === '[::1]';
+        if (this.endpoint.protocol !== 'https:' && !(this.endpoint.protocol === 'http:' && local)) {
+            throw new IronGraphError('Plain remote connections are forbidden; use HTTPS with a browser-managed client certificate', 'ConfigurationError');
+        }
+    }
+    async query(request) {
+        if (!request.cypher.trim())
+            throw new IronGraphError('Cypher is empty', 'ConfigurationError');
+        const response = await fetch(this.endpoint, {
+            method: 'POST',
+            headers: { Accept: 'application/x-ndjson', 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                request_id: crypto.randomUUID(),
+                project_id: request.projectId ?? null,
+                query: request.cypher,
+                parameters: request.parameters ?? {},
+                bookmark: request.bookmark ?? null,
+                ...(request.limits ? { limits: request.limits } : {}),
+            }),
+            signal: request.signal,
+        });
+        if (!response.ok)
+            throw new IronGraphError(`HTTP ${response.status}`, 'HttpError');
+        if (!response.body)
+            throw new IronGraphError('Query response has no body', 'ProtocolError');
+        const result = { columns: [], rows: [], summary: {} };
+        for await (const event of decodeNdjson(response.body)) {
+            if (event.type === 'error') {
+                throw new IronGraphError(String(event.message ?? 'Query failed'), String(event.code ?? 'QueryError'), Boolean(event.retryable), typeof event.retry_after_ms === 'number' ? event.retry_after_ms : undefined);
+            }
+            if (event.type === 'catalog') {
+                const { type: _type, ...catalog } = event;
+                result.catalog = catalog;
+            }
+            if (event.type === 'schema')
+                result.columns = (event.columns ?? []);
+            if (event.type === 'batch')
+                appendBatch(result, event);
+            if (event.type === 'summary') {
+                const { type: _type, ...summary } = event;
+                result.summary = summary;
+            }
+        }
+        return result;
+    }
+}
+function appendBatch(result, event) {
+    const columns = Array.isArray(event.columns) ? event.columns : [];
+    const rowCount = Number(event.row_count ?? 0);
+    if (!Number.isSafeInteger(rowCount) || rowCount < 0) {
+        throw new IronGraphError('Invalid batch row count', 'ProtocolError');
+    }
+    if (columns.some((column) => !Array.isArray(column.values) || column.values.length !== rowCount)) {
+        throw new IronGraphError('Misaligned batch columns', 'ProtocolError');
+    }
+    for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
+        result.rows.push(columns.map((column) => column.values[rowIndex]));
+    }
+}
+async function* decodeNdjson(stream) {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buffered = '';
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            buffered += decoder.decode(value, { stream: !done });
+            if (buffered.length > MAXIMUM_EVENT_CHARACTERS && !buffered.includes('\n')) {
+                throw new IronGraphError('One query event exceeds 64 MiB', 'ProtocolError');
+            }
+            const lines = buffered.split('\n');
+            buffered = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.trim())
+                    yield JSON.parse(line);
+            }
+            if (done)
+                break;
+        }
+        if (buffered.trim())
+            yield JSON.parse(buffered);
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/react.d.ts

@@ -0,0 +1,12 @@
+import { type ReactNode } from 'react';
+import { Client, type QueryRequest, type QueryResult } from './index.js';
+export declare function IronGraphProvider({ baseUrl, children }: {
+    baseUrl: string | URL;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<Client | null>>;
+export declare function useIronGraphClient(): Client;
+export declare function useIronGraphQuery(request: Omit<QueryRequest, 'signal'> | null): {
+    result: QueryResult | undefined;
+    error: unknown;
+    loading: boolean;
+};

package/dist/react.js

@@ -0,0 +1,41 @@
+import { createContext, createElement, useContext, useEffect, useMemo, useState } from 'react';
+import { Client } from './index.js';
+const IronGraphContext = createContext(null);
+export function IronGraphProvider({ baseUrl, children }) {
+    const client = useMemo(() => new Client(baseUrl), [String(baseUrl)]);
+    return createElement(IronGraphContext.Provider, { value: client }, children);
+}
+export function useIronGraphClient() {
+    const client = useContext(IronGraphContext);
+    if (!client)
+        throw new Error('useIronGraphClient must be used within IronGraphProvider');
+    return client;
+}
+export function useIronGraphQuery(request) {
+    const client = useIronGraphClient();
+    const [result, setResult] = useState();
+    const [error, setError] = useState();
+    const [loading, setLoading] = useState(request !== null);
+    const signature = JSON.stringify(request);
+    useEffect(() => {
+        if (!request) {
+            setLoading(false);
+            return;
+        }
+        const controller = new AbortController();
+        setLoading(true);
+        setError(undefined);
+        client.query({ ...request, signal: controller.signal })
+            .then(setResult)
+            .catch((caught) => {
+            if (!controller.signal.aborted)
+                setError(caught);
+        })
+            .finally(() => {
+            if (!controller.signal.aborted)
+                setLoading(false);
+        });
+        return () => controller.abort();
+    }, [client, signature]);
+    return { result, error, loading };
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@irongraph/client",
+  "version": "0.1.0",
+  "description": "JavaScript and React client for an embeddable graph database with automatic local embeddings and vector search.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentbusiness/IronGraph.git",
+    "directory": "bindings/javascript"
+  },
+  "homepage": "https://github.com/agentbusiness/IronGraph#readme",
+  "bugs": {
+    "url": "https://github.com/agentbusiness/IronGraph/issues"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt",
+    "THIRD_PARTY_NOTICES.txt"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  }
+}