@plasius/graph-write-coordinator

Queue-first write coordinator with synchronous fast-path, timeout fallback, and hot-key batching.

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-write-coordinator

Exports

import {
  WriteCoordinator,
  HotKeyBatcher,
  type WriteCoordinatorOptions,
  type WriteCommitHandler,
  type SubmitWriteOptions,
  type MergeWriteCommands,
} from "@plasius/graph-write-coordinator";

Quick Start

import { WriteCoordinator, HotKeyBatcher } from "@plasius/graph-write-coordinator";

const coordinator = new WriteCoordinator({
  queue,
  operationStore,
  telemetry,
  commitHandler: {
    async commit(command) {
      return { version: Date.now() };
    },
  },
});

const operation = await coordinator.submit(command);
const status = await coordinator.getOperationStatus(operation.operationId);

const batcher = new HotKeyBatcher({
  windowMs: 50,
  merge: (commands) => commands[commands.length - 1]!,
  onFlush: async (partitionKey, merged) => {
    await coordinator.submit(merged, { forceQueue: true });
  },
});

console.log(operation.state, status.recommendedHttpStatus);

Development

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

Operation Status Contract

• submit validates command shape (isWriteCommand) and returns an operation with deterministic state progression.
• getOperationStatus(operationId) returns:
  • found + operation,
  • terminal flag,
  • recommendedHttpStatus mapping for adapter/HTTP layers.
• Suggested host mapping:
  • 202 for accepted/queued/processing,
  • 200 for succeeded,
  • 409 for failed/cancelled,
  • 404 when operation is unknown.

Hot-Key Batching

• HotKeyBatcher supports localized write collapse by partition key.
• Target window for high-contention workloads is 50-200ms (windowMs).
• High-contention tests validate single-window merges under parallel submissions.

Telemetry

WriteCoordinatorOptions accepts optional telemetry (TelemetrySink) and emits:

• graph.write.submit.latency
• graph.write.submit.degraded
• graph.write.process.result
• graph.write.status.lookup

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.