@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,
  type ProjectedEvent,
  type GraphProjectorCheckpoint,
  ReplayableProjector,
  InMemoryProjectorCheckpointStore,
} 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",
});

Replayable checkpointing for downstream projections

import { InMemoryProjectorCheckpointStore, ReplayableProjector } from "@plasius/graph-events";

const checkpointStore = new InMemoryProjectorCheckpointStore();
const projector = new ReplayableProjector(
  async (event, _checkpoint) => {
    // apply event into a projection or materialized view
  },
  {
    streamId: "world-events:stream",
    checkpointStore,
  },
);

await projector.processBatch([
  { streamId: "world-events:stream", eventId: "evt-1", version: 1 },
  { streamId: "world-events:stream", eventId: "evt-2", version: 2 },
]);

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
• Replayable projection checkpoints:
  • resume safely from checkpointed stream state
  • skip stale versions and duplicate event ids at checkpoint level
  • enforce stream correctness per batch input

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.