@plasius/graph-events

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

npm install @plasius/graph-events

Exports

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

Quick Start

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

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
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.