orderEvents()

Signature

function orderEvents<T>(
  events: EventEnvelope<T>[],
  options?: OrderOptions<T>,
): OrderResult<T>

This is the main bounded-batch entry point. It validates input, builds ordering constraints from supported causal evidence, and emits a deterministic result even when full proof is not available.

Usage

import { orderEvents } from "causal-order"

const result = orderEvents(events, {
  strict: false,
  detectAnomalies: true,
  tieBreaker: "event_id",
})

console.log(result.ordered)
console.log(result.anomalies)
console.log(result.stats)

Details

• ordered: ordered events with orderIndex, orderBasis, and confidence.
• anomalies: invalid, suspicious, or operationally important records.
• stats: counts for total, valid, invalid, ordered, and anomaly totals.
• tieBreaker: deterministic tie breaker such as event_id or ingestion_order.
• strict: the main fail-fast switch for ordering and validation; translation fail-fast remains separately controlled through translateBatch() policy.
• detectAnomalies: include emitted anomaly analysis in the returned batch result; turning it off reduces diagnostic output rather than upgrading confidence.
• allowUnknownOrder: keep unresolved ordering explicit in non-strict mode; setting it to false strengthens severity posture rather than inventing stronger certainty.
• maxClockDriftMs: validation bound for future clock drift checks.