@plasius/graph-client-core

Framework-agnostic graph client runtime with normalized cache and stale policy controls.

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

Requirements

• Node.js 24+ (matches .nvmrc and CI/CD)
• @plasius/graph-contracts

Installation

npm install @plasius/graph-client-core

Exports

import {
  GraphClient,
  type GraphTransport,
  type GraphTransportResponse,
  type GraphClientOptions,
  type GraphQueryOptions,
} from "@plasius/graph-client-core";

Quick Start

import { GraphClient } from "@plasius/graph-client-core";

const client = new GraphClient({
  transport: {
    async fetch(request) {
      return {
        data: { id: request.key },
        version: 1,
        tags: ["user"],
        source: request.resolver,
      };
    },
  },
  telemetry,
});

const result = await client.query({
  requests: [{ resolver: "user.profile", key: "user:1" }],
});

console.log(result.results["user:1"]?.data);

Development

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

Telemetry

GraphClientOptions accepts a telemetry sink (TelemetrySink from @plasius/graph-contracts).

Emitted metrics/errors include:

• graph.client.cache.outcome (fresh_hit / stale_hit / miss)
• graph.client.query.latency
• graph.client.refresh.latency
• graph.client.fetch.error
• graph.client.inflight.deduped

The client fails fast on invalid query payload shapes using isGraphQuery.

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.