@shivaedev/changes 0.7.0 → 0.8.0

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/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.8.0 - 2026-11-02
4
+
5
+ ### Added
6
+
7
+ - Capture recorded, attempted and discarded change batches through `makeCapture` and its Layer while preserving delivery and enclosing observations.
8
+
3
9
  ## 0.7.0 - 2026-11-02
4
10
 
5
11
  ### Added
package/README.md CHANGED
@@ -161,28 +161,21 @@ Set `onPublishFailure: "die"` when that same delivery failure should raise a def
161
161
  ### Capture notifications in tests
162
162
 
163
163
  ```ts
164
- import type { Observation } from "@shivaedev/changes/observe.ts";
165
- import { Layer } from "effect";
164
+ import { makeCapture } from "@shivaedev/changes/capture.ts";
166
165
 
167
- const captured: Array<MembershipChange> = [];
168
- const observations: Array<Observation<MembershipChange>> = [];
166
+ const capture = yield* makeCapture<MembershipChange>();
167
+ yield* grant("ada", "bob").pipe(Effect.provide(capture.layer(membershipChanges.Observer)));
169
168
 
170
- const captureSink = Layer.succeed(membershipChanges.Sink, (changes: readonly MembershipChange[]) =>
171
- Effect.sync(() => {
172
- captured.push(...changes);
173
- }),
174
- );
169
+ const recorded = yield* capture.recorded;
170
+ const attempted = yield* capture.attempted;
171
+ const discarded = yield* capture.discarded;
172
+ ```
175
173
 
176
- const observe = Layer.succeed(membershipChanges.Observer, (observation: Observation<MembershipChange>) =>
177
- Effect.sync(() => {
178
- observations.push(observation);
179
- }),
180
- );
174
+ Create a capture for each test, then provide its `layer(observer)` around the complete operation, including the transaction boundary. Each readout returns a snapshot of change batches in observation order. `recorded` contains the distinct changes from each record call; `attempted` contains the deduplicated changes passed to publication; `discarded` contains rolled-back changes, including rolled-back savepoints. Repeated record calls remain separate in `recorded` even when the transaction publishes their shared key once.
181
175
 
182
- const capturedGrant = grant("ada", "bob").pipe(Effect.provide(Layer.merge(captureSink, observe)));
183
- ```
176
+ An attempt is observed before the sink runs, so `attempted` does not prove delivery. The Layer leaves the sink in place and forwards observations to the enclosing observer. Writes outside the Layer do not enter its readouts. Capture does not infer inserts from refresh keys: retain the write's returned ids when a story needs to identify created rows.
184
177
 
185
- `Sink` and `Observer` are channel-specific `Context.Reference`s. Within the provided scope, the sink receives the changes instead of the configured publish function; the configured sink resumes outside it. The observer receives `Recorded` for the distinct changes in a record call, `Published` for the buffer passed to publication and `Discarded` for a rolled-back frame's changes. `Published` is emitted before the sink runs; it does not prove successful delivery. Discarded parent changes include changes merged from children that committed earlier. A rollback therefore remains visible to a coverage check through its earlier `Recorded` observation. A synchronous throw or Effect defect from the observer is logged without blocking sink delivery or changing the transaction's outcome.
178
+ `Sink` and `Observer` are channel-specific `Context.Reference`s. Provide `Sink` to replace delivery in a scope. The observer receives `Recorded`, `Published` and `Discarded` observations; `Published` names a publication attempt. A synchronous throw or Effect defect from the observer is logged without blocking sink delivery or changing the transaction's outcome.
186
179
 
187
180
  ### Work inside the committing transaction
188
181
 
@@ -198,6 +191,7 @@ Import from the module that defines the name; the package has no root entry.
198
191
  | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
199
192
  | `@shivaedev/changes/channel.ts` | `makeChannel`, `ChannelOptions`, `Channel`, `BeforeCommit` |
200
193
  | `@shivaedev/changes/frame.ts` | `Frame`, `CommitFrame`, `Outcome` |
194
+ | `@shivaedev/changes/capture.ts` | `makeCapture`, `Capture` |
201
195
  | `@shivaedev/changes/observe.ts` | `Observation`, `Observer` |
202
196
  | `@shivaedev/changes/publish.ts` | `Publish`, `PublishFailure` |
203
197
  | `@shivaedev/changes/keys.ts` | `collection`, `compositeId`, `recordKey`, `readKeys`, `invalidationKeys`, `Key`, `ListKey`, `ItemKey`, `BucketKey`, `Collection`, `Identity`, `KeyContext` |
@@ -0,0 +1,15 @@
1
+ import { type Context, Effect, Layer } from "effect";
2
+ import type { Observer } from "./observe.ts";
3
+ export interface Capture<A> {
4
+ readonly attempted: Effect.Effect<readonly (readonly A[])[]>;
5
+ readonly discarded: Effect.Effect<readonly (readonly A[])[]>;
6
+ readonly layer: (observer: Context.Reference<Observer<A>>) => Layer.Layer<never>;
7
+ readonly recorded: Effect.Effect<readonly (readonly A[])[]>;
8
+ }
9
+ export declare const makeCapture: <A>() => Effect.Effect<{
10
+ attempted: Effect.Effect<A[][], never, never>;
11
+ discarded: Effect.Effect<A[][], never, never>;
12
+ layer: (observer: Context.Reference<Observer<A>>) => Layer.Layer<never>;
13
+ recorded: Effect.Effect<A[][], never, never>;
14
+ }, never, never>;
15
+ //# sourceMappingURL=capture.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,EAAE,KAAK,EAAO,MAAM,QAAQ,CAAC;AAC1D,OAAO,KAAK,EAAe,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE1D,MAAM,WAAW,OAAO,CAAC,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CAC5D;AAED,eAAO,MAAM,WAAW,GAA+C,CAAC;;;sBAE9C,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAG,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC;;gBAkB3E,CAAC"}
@@ -0,0 +1,12 @@
1
+ import { Effect, Layer, Ref } from "effect";
2
+ export const makeCapture = Effect.fn("Changes.makeCapture")(function* () {
3
+ const observations = yield* Ref.make([]);
4
+ function layer(observer) {
5
+ return Layer.effect(observer, Effect.map(observer, (parent) => (event) => Effect.andThen(Ref.update(observations, (events) => [...events, { ...event, changes: [...event.changes] }]), Effect.suspend(() => parent(event)))));
6
+ }
7
+ function read(tag) {
8
+ return Effect.map(Ref.get(observations), (events) => events.filter((event) => event._tag === tag).map((event) => [...event.changes]));
9
+ }
10
+ return { attempted: read("Published"), discarded: read("Discarded"), layer, recorded: read("Recorded") };
11
+ });
12
+ //# sourceMappingURL=capture.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAU1D,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC,EAAE,CAAC,qBAAqB,CAAC,CAAC,QAAQ,CAAC;IACpE,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAA4B,EAAE,CAAC,CAAC;IACpE,SAAS,KAAK,CAAC,QAAwC;QACtD,OAAO,KAAK,CAAC,MAAM,CAClB,QAAQ,EACR,MAAM,CAAC,GAAG,CACT,QAAQ,EACR,CAAC,MAAM,EAAe,EAAE,CACvB,CAAC,KAAK,EAAE,EAAE,CACT,MAAM,CAAC,OAAO,CACb,GAAG,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,GAAG,MAAM,EAAE,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAC5F,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACnC,CACH,CACD,CAAC;IACH,CAAC;IACD,SAAS,IAAI,CAAC,GAA2B;QACxC,OAAO,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACvI,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,EAAuB,CAAC;AAC/H,CAAC,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/changes",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "Commit-bound change channels for Effect: publish recorded changes only after the transaction commits",
5
5
  "keywords": [
6
6
  "effect"
@@ -43,8 +43,8 @@
43
43
  "README.md"
44
44
  ],
45
45
  "devDependencies": {
46
- "@shivaedev/quality": "0.55.0",
47
- "@shivaedev/test-story": "0.33.0",
46
+ "@shivaedev/quality": "0.56.0",
47
+ "@shivaedev/test-story": "0.34.0",
48
48
  "@types/node": "24.19.2",
49
49
  "effect": "4.0.6",
50
50
  "typescript": "7.0.2",
package/src/capture.ts ADDED
@@ -0,0 +1,31 @@
1
+ import { type Context, Effect, Layer, Ref } from "effect";
2
+ import type { Observation, Observer } from "./observe.ts";
3
+
4
+ export interface Capture<A> {
5
+ readonly attempted: Effect.Effect<readonly (readonly A[])[]>;
6
+ readonly discarded: Effect.Effect<readonly (readonly A[])[]>;
7
+ readonly layer: (observer: Context.Reference<Observer<A>>) => Layer.Layer<never>;
8
+ readonly recorded: Effect.Effect<readonly (readonly A[])[]>;
9
+ }
10
+
11
+ export const makeCapture = Effect.fn("Changes.makeCapture")(function* <A>() {
12
+ const observations = yield* Ref.make<readonly Observation<A>[]>([]);
13
+ function layer(observer: Context.Reference<Observer<A>>): Layer.Layer<never> {
14
+ return Layer.effect(
15
+ observer,
16
+ Effect.map(
17
+ observer,
18
+ (parent): Observer<A> =>
19
+ (event) =>
20
+ Effect.andThen(
21
+ Ref.update(observations, (events) => [...events, { ...event, changes: [...event.changes] }]),
22
+ Effect.suspend(() => parent(event)),
23
+ ),
24
+ ),
25
+ );
26
+ }
27
+ function read(tag: Observation<A>["_tag"]) {
28
+ return Effect.map(Ref.get(observations), (events) => events.filter((event) => event._tag === tag).map((event) => [...event.changes]));
29
+ }
30
+ return { attempted: read("Published"), discarded: read("Discarded"), layer, recorded: read("Recorded") } satisfies Capture<A>;
31
+ });