open-index/open-npm huggingface dataset:
npm package: @plasius/graph-client-core
Description: Framework-agnostic graph client runtime with normalized cache and stale policy controls
Author: Plasius LTD
Latest version: 0.1.2

# @plasius/graph-client-core

[![npm version](https://img.shields.io/npm/v/@plasius/graph-client-core.svg)](https://www.npmjs.com/package/@plasius/graph-client-core)
[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/graph-client-core/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/graph-client-core/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/graph-client-core)](https://codecov.io/gh/Plasius-LTD/graph-client-core)
[![License](https://img.shields.io/github/license/Plasius-LTD/graph-client-core)](./LICENSE)
[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)

[![CI](https://github.com/Plasius-LTD/graph-client-core/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/graph-client-core/actions/workflows/ci.yml)
[![CD](https://github.com/Plasius-LTD/graph-client-core/actions/workflows/cd.yml/badge.svg)](https://github.com/Plasius-LTD/graph-client-core/actions/workflows/cd.yml)

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

```bash
npm install @plasius/graph-client-core
```

---

## Exports

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

---

## Quick Start

```ts
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

```bash
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`](./docs/adrs)
- Cross-package ADRs: `plasius-ltd-site/docs/adrs/adr-0020` to `adr-0024`

---

## License

Licensed under the [Apache-2.0 License](./LICENSE).
npm package: @plasius/graph-contracts
Description: Shared contracts and ports for the Plasius cached graph platform
Author: Plasius LTD
Latest version: 0.1.2

# @plasius/graph-contracts

[![npm version](https://img.shields.io/npm/v/@plasius/graph-contracts.svg)](https://www.npmjs.com/package/@plasius/graph-contracts)
[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/graph-contracts/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/graph-contracts/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/graph-contracts)](https://codecov.io/gh/Plasius-LTD/graph-contracts)
[![License](https://img.shields.io/github/license/Plasius-LTD/graph-contracts)](./LICENSE)
[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)

[![CI](https://github.com/Plasius-LTD/graph-contracts/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/graph-contracts/actions/workflows/ci.yml)
[![CD](https://github.com/Plasius-LTD/graph-contracts/actions/workflows/cd.yml/badge.svg)](https://github.com/Plasius-LTD/graph-contracts/actions/workflows/cd.yml)

Shared contracts, constants, ports, and runtime validators for the Plasius cached graph platform.

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

---

## Requirements

- Node.js 24+ (matches `.nvmrc` and CI/CD)

---

## Installation

```bash
npm install @plasius/graph-contracts
```

---

## Exports

```ts
import {
  DEFAULT_SOFT_TTL_SECONDS,
  DEFAULT_HARD_TTL_SECONDS,
  SUPPORTED_SCHEMA_VERSIONS,
  isGraphQuery,
  isDomainEvent,
  isWriteCommand,
  getSchemaSupportLevel,
  isSchemaVersionSupported,
  type GraphQuery,
  type CacheStore,
  type WriteCommand,
} from "@plasius/graph-contracts";
```

---

## Quick Start

```ts
import {
  isGraphQuery,
  type GraphQuery,
  DEFAULT_SOFT_TTL_SECONDS,
} from "@plasius/graph-contracts";

const query: GraphQuery = {
  traceId: "trace-1",
  requests: [{ resolver: "user.profile", key: "user:1" }],
};

if (!isGraphQuery(query)) {
  throw new Error("Invalid graph query payload");
}

console.log("softTtlSeconds", DEFAULT_SOFT_TTL_SECONDS);
```

---

## Development

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

---

## Contract Compatibility

- Versioning policy: [`docs/contract-versioning.md`](./docs/contract-versioning.md)
- Compatibility helpers:
  - `SUPPORTED_SCHEMA_VERSIONS`
  - `getSchemaSupportLevel`
  - `isSchemaVersionSupported`
- CI compatibility suite: `tests/compatibility.test.ts`

---

## Architecture

- Package ADRs: [`docs/adrs`](./docs/adrs)
- Cross-package ADRs: `plasius-ltd-site/docs/adrs/adr-0020` to `adr-0024`

---

## License

Licensed under the [Apache-2.0 License](./LICENSE).
npm package: @plasius/graph-events
Description: Event-driven cache invalidation and hydration pipeline for graph data
Author: Plasius LTD
Latest version: 0.1.3

# @plasius/graph-events

[![npm version](https://img.shields.io/npm/v/@plasius/graph-events.svg)](https://www.npmjs.com/package/@plasius/graph-events)
[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/graph-events/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/graph-events/actions/workflows/ci.yml)
[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/graph-events)](https://codecov.io/gh/Plasius-LTD/graph-events)
[![License](https://img.shields.io/github/license/Plasius-LTD/graph-events)](./LICENSE)
[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)

[![CI](https://github.com/Plasius-LTD/graph-events/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/graph-events/actions/workflows/ci.yml)
[![CD](https://github.com/Plasius-LTD/graph-events/actions/workflows/cd.yml/badge.svg)](https://github.com/Plasius-LTD/graph-events/actions/workflows/cd.yml)

Event-driven cache invalidation and hydration pipeline for graph data.

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

---

## Requirements

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

---

## Installation

```bash
npm install @plasius/graph-events
```

---

## Exports

```ts
import {
  GraphEventProcessor,
  InMemoryProcessedEventStore,
  type GraphEventProcessorOptions,
  type GraphEventProcessResult,
  type ProcessedEventStore,
} from "@plasius/graph-events";
```

---

## Quick Start

```ts
import { GraphEventProcessor } from "@plasius/graph-events";

const processor = new GraphEventProcessor({ cacheStore });

await processor.process({
  id: "evt_1",
  type: "graph.entity.updated",
  occurredAtEpochMs: Date.now(),
  aggregateKey: "user:1",
  entityKey: "user:1",
  version: 2,
  payload: { data: { id: 1, name: "Alice" } },
  tags: ["user"],
  schemaVersion: "1",
  source: "user-service",
});
```

---

## Development

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

---

## Processing Guarantees

- Idempotency/replay: processed event store prevents duplicate handling.
- Version ordering guard: older versions are skipped to prevent cache rollback.
- Schema compatibility guard: `supportedSchemaVersions` controls accepted envelope versions.
- Telemetry:
  - `graph.events.lag_ms`
  - `graph.events.processed`
  - `graph.events.failure`

Missed events rely on cache TTL fallback strategy (cross-package ADR 0021).

---

## Architecture

- Package ADRs: [`docs/adrs`](./docs/adrs)
- Cross-package ADRs: `plasius-ltd-site/docs/adrs/adr-0020` to `adr-0024`

---

## License

Licensed under the [Apache-2.0 License](./LICENSE).