@alineo-labs/ledger 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -92,12 +92,20 @@ export declare class MemoryStorage implements LedgerStorage {
92
92
  /** Left-fold a stream of envelopes into a projection. */
93
93
  export declare function fold<S>(events: Iterable<LedgerEnvelope>, initial: S, apply: (state: S, envelope: LedgerEnvelope) => S): S;
94
94
  /**
95
- * Sort by `durable.seq` within each aggregate, then by timestamp across them.
95
+ * Put envelopes in ledger order: by `durable.seq` within an aggregate, by timestamp across them.
96
96
  *
97
97
  * A sink sees events in emission order, which is usually persist order but is not guaranteed
98
98
  * to be across two aggregates. Comparing a sink's stream against a store's rows means putting
99
99
  * them in the same order first, or the comparison fails for a reason that has nothing to do
100
100
  * with the thing being tested.
101
+ *
102
+ * "Seq within, ts across" is not a total order on its own: a clock that ran backwards inside
103
+ * one aggregate makes it cyclic (a < b by time, b < c by time, c < a by seq), and the result
104
+ * then depends on the sort algorithm, so two runtimes disagree. This resolves it by giving
105
+ * every event the highest timestamp seen so far in its aggregate, in seq order. Seq is the
106
+ * truth inside an aggregate, so an event never sorts earlier than one before it. For events
107
+ * whose timestamps do not run backwards, which is every event a healthy ledger holds, this
108
+ * is the plain ts-and-seq order. Ties break on aggregate, then seq, so the order is total.
101
109
  */
102
110
  export declare function inLedgerOrder(events: readonly LedgerEnvelope[]): LedgerEnvelope[];
103
111
  /** Only the events that earned a row — what a store holds and a rebuild sees. */
package/dist/index.mjs CHANGED
@@ -95,17 +95,36 @@ function fold(events, initial, apply) {
95
95
  return state;
96
96
  }
97
97
  /**
98
- * Sort by `durable.seq` within each aggregate, then by timestamp across them.
98
+ * Put envelopes in ledger order: by `durable.seq` within an aggregate, by timestamp across them.
99
99
  *
100
100
  * A sink sees events in emission order, which is usually persist order but is not guaranteed
101
101
  * to be across two aggregates. Comparing a sink's stream against a store's rows means putting
102
102
  * them in the same order first, or the comparison fails for a reason that has nothing to do
103
103
  * with the thing being tested.
104
+ *
105
+ * "Seq within, ts across" is not a total order on its own: a clock that ran backwards inside
106
+ * one aggregate makes it cyclic (a < b by time, b < c by time, c < a by seq), and the result
107
+ * then depends on the sort algorithm, so two runtimes disagree. This resolves it by giving
108
+ * every event the highest timestamp seen so far in its aggregate, in seq order. Seq is the
109
+ * truth inside an aggregate, so an event never sorts earlier than one before it. For events
110
+ * whose timestamps do not run backwards, which is every event a healthy ledger holds, this
111
+ * is the plain ts-and-seq order. Ties break on aggregate, then seq, so the order is total.
104
112
  */
105
113
  function inLedgerOrder(events) {
114
+ const effective = /* @__PURE__ */ new Map();
115
+ for (const group of byAggregate(events).values()) {
116
+ let high = Number.NEGATIVE_INFINITY;
117
+ for (const event of [...group].sort((a, b) => a.durable.seq - b.durable.seq)) {
118
+ high = Math.max(high, event.ts);
119
+ effective.set(event, high);
120
+ }
121
+ }
122
+ const when = (e) => effective.get(e) ?? e.ts;
106
123
  return [...events].sort((a, b) => {
107
- if (a.durable && b.durable && a.durable.aggregate === b.durable.aggregate) return a.durable.seq - b.durable.seq;
108
- return a.ts - b.ts;
124
+ if (when(a) !== when(b)) return when(a) - when(b);
125
+ const byAgg = (a.durable?.aggregate ?? "").localeCompare(b.durable?.aggregate ?? "");
126
+ if (byAgg !== 0) return byAgg;
127
+ return (a.durable?.seq ?? 0) - (b.durable?.seq ?? 0);
109
128
  });
110
129
  }
111
130
  /** Only the events that earned a row — what a store holds and a rebuild sees. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alineo-labs/ledger",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Behaviour for alineo's event ledger: sinks, fold helpers and an in-memory store. Shapes live in @alineo-labs/schema.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -30,7 +30,7 @@
30
30
  "test:watch": "vitest"
31
31
  },
32
32
  "dependencies": {
33
- "@alineo-labs/schema": "0.2.0"
33
+ "@alineo-labs/schema": "0.3.0"
34
34
  },
35
35
  "devDependencies": {
36
36
  "bun-types": "1.4.2",