@plasius/graph-client-react

React bindings for @plasius/graph-client-core query and mutation workflows.

Apache-2.0. ESM + CJS builds. TypeScript types included.

Requirements

• Node.js 24+ (matches .nvmrc and CI/CD)
• React 19 (peerDependencies)
• @plasius/graph-client-core

Installation

npm install @plasius/graph-client-react @plasius/graph-client-core

Exports

import {
  GraphClientProvider,
  useGraphClient,
  useGraphQuery,
  useGraphMutation,
  type UseGraphQueryOptions,
  type UseGraphQueryState,
  type UseGraphMutationOptions,
  type GraphMutationClient,
} from "@plasius/graph-client-react";

Quick Start

import { GraphClient } from "@plasius/graph-client-core";
import { GraphClientProvider, useGraphQuery } from "@plasius/graph-client-react";

const client = new GraphClient({ transport: { async fetch() { return { data: { ok: true }, version: 1 }; } } });

function Profile() {
  const { data, loading, revalidating, error, refresh } = useGraphQuery(
    {
      requests: [{ resolver: "user.profile", key: "user:1" }],
    },
    { retryAttempts: 1, retryDelayMs: 25 },
  );

  if (loading) return <p>Loading</p>;
  if (error) return <p>{error.message}</p>;

  return (
    <button onClick={() => void refresh()}>
      {revalidating ? "Refreshing..." : JSON.stringify(data?.results)}
    </button>
  );
}

export function App() {
  return (
    <GraphClientProvider client={client}>
      <Profile />
    </GraphClientProvider>
  );
}

Development

npm run clean
npm install
npm run lint
npm run typecheck
npm run test:coverage
npm run build

Query State Mapping

• loading: first request with no cached hook data.
• revalidating: refresh/rerender request when prior hook data exists.
• status: "loading" | "success" | "error" terminal state for last request.
• error: normalized to Error.

Suspense is intentionally disabled in current package scope (see ADR-0003). Passing suspense: true to useGraphQuery throws.

Both hooks support optional telemetry (from TelemetrySink) to emit analytics signals:

• Query: graph.react.query.run, graph.react.query.success, graph.react.query.retry, graph.react.query.error
• Mutation: graph.react.mutation.success, graph.react.mutation.error

Architecture

• Package ADRs: docs/adrs
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.