Introduction to the TypeScript libraries

Description

Explore TrustGraph TypeScript libraries for building web applications

Difficulty

Intermediate

Duration

30 min

You will need
  • Basic TypeScript/JavaScript familiarity
Goal

Understand the TrustGraph TypeScript libraries and choose the right one for your application.

Overview

TrustGraph provides three TypeScript/JavaScript libraries for different use cases:

Library Description Use Case
trustgraph-client Pure TypeScript WebSocket client Backend services, CLI tools, non-React applications
trustgraph-react-provider React Context provider wrapper Basic React integration with direct client access
trustgraph-react-state React hooks with Tanstack Query Full-featured React applications with state management

Choosing the right library:

  • Building a React app? → Use trustgraph-react-state for the best developer experience
  • Need React Context integration? → Use trustgraph-react-provider for simpler needs
  • Building without React? → Use trustgraph-client for Node.js, CLIs, or vanilla JavaScript

trustgraph-client

The core TypeScript client for TrustGraph, built on WebSockets with minimal dependencies.

Links:

Key features:

  • Pure TypeScript with full type safety
  • WebSocket-based for streaming and non-streaming operations
  • Minimal dependencies (only websocket and promises)
  • No React dependency - works anywhere JavaScript runs
  • Suitable for backend services, CLI tools, and non-UI applications

Installation:

npm install trustgraph-client

Basic usage:

import { TrustGraphClient } from 'trustgraph-client';

// Create client
const client = new TrustGraphClient({
  url: 'http://localhost:8088',
  flowId: 'default'
});

// Query using Graph RAG (streaming)
const stream = client.graphRag({
  query: 'What is the scientific name for cats?',
  user: 'trustgraph',
  collection: 'default',
  streaming: true
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

The client can be used in:

  • Node.js backend services
  • Command-line tools
  • Build scripts and automation
  • Browser applications without React
  • Electron apps

trustgraph-react-provider

A React Context provider that makes the TrustGraph client available throughout your component tree.

Links:

Key features:

  • Wraps trustgraph-client with React Context
  • Provides direct access to the client instance
  • Minimal abstraction - you control client interactions
  • Good for simple React integrations

Installation:

npm install trustgraph-react-provider trustgraph-client

Basic usage:

import { TrustGraphProvider, useTrustGraph } from 'trustgraph-react-provider';

// Wrap your app with the provider
function App() {
  return (
    <TrustGraphProvider
      url="http://localhost:8088"
      flowId="default"
    >
      <YourComponents />
    </TrustGraphProvider>
  );
}

// Access the client in components
function QueryComponent() {
  const client = useTrustGraph();

  const handleQuery = async () => {
    const stream = client.graphRag({
      query: 'What is the scientific name for cats?',
      user: 'trustgraph',
      collection: 'default',
      streaming: true
    });

    for await (const chunk of stream) {
      // Handle streaming chunks
    }
  };

  return <button onClick={handleQuery}>Query</button>;
}

Use this when:

  • You want direct control over client interactions
  • You’re comfortable managing your own state
  • You have simple integration needs

trustgraph-react-state

The most React-friendly library, providing hooks built on Tanstack Query for automatic state management and caching.

Links:

Key features:

  • React hooks for all TrustGraph operations
  • Built on Tanstack Query (React Query)
  • Automatic state management (loading, error, success states)
  • Intelligent caching and request deduplication
  • Optimistic updates and background refetching
  • Best developer experience for React applications

Installation:

npm install trustgraph-react-state @tanstack/react-query

Basic usage:

import { TrustGraphProvider } from 'trustgraph-react-state';
import { useGraphRag } from 'trustgraph-react-state/hooks';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

// Create QueryClient
const queryClient = new QueryClient();

// Wrap your app with providers
function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <TrustGraphProvider
        url="http://localhost:8088"
        flowId="default"
      >
        <YourComponents />
      </TrustGraphProvider>
    </QueryClientProvider>
  );
}

// Use hooks in components
function QueryComponent() {
  const { data, isLoading, error } = useGraphRag({
    query: 'What is the scientific name for cats?',
    user: 'trustgraph',
    collection: 'default'
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return <div>{data}</div>;
}

Available hooks:

  • useGraphRag - Graph RAG queries
  • useDocumentRag - Document RAG queries
  • useAgent - Agent queries
  • useTextCompletion - LLM text completion
  • useTriplesQuery - Knowledge graph triple queries
  • And more…

Each hook provides:

  • data - Query results
  • isLoading - Loading state
  • error - Error state
  • refetch - Manual refetch function
  • Automatic caching and deduplication

Use this when:

  • Building a full React application
  • You want automatic state management
  • You need caching and performance optimization
  • You want the best developer experience

Next Steps