@shivaedev/changes 0.5.0 → 0.5.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.
Files changed (3) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +70 -73
  3. package/package.json +5 -5
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.5.1 - 2026-10-30
4
+
5
+ ### Changed
6
+
7
+ - Require Effect 4.0.6 and align the Effect companion package peers and generated starter catalog to the same exact release. Install the 4.0.6 Effect stack together.
8
+
9
+ ### Fixed
10
+
11
+ - Register hosted RPC cache-control handling through Effect 4.0.6's request-scoped pre-response API so responses keep `private, no-store`.
12
+ - Accept native RPC's `application/x-ndjson` media type while preserving `application/ndjson` callers at the transport guard.
13
+ - Keep subscriptions open after their HTTP request body completes; closing the socket still cancels them.
14
+
3
15
  ## 0.5.0 - 2026-10-28
4
16
 
5
17
  ### Added
package/README.md CHANGED
@@ -18,33 +18,6 @@ yield* Effect.gen(function* () {
18
18
 
19
19
  `membershipChanges` is the channel defined below. It groups notifications by subject and domain, so another write to the same member inside this transaction does not add a second notification. A nested transaction that rolls back contributes no notification, and a failed outer commit publishes nothing. Feature code describes what changed; the native transaction decides whether it happened.
20
20
 
21
- ## Record keys and buckets
22
-
23
- `keys.ts` owns the shared dependency format for contract queries, committed writes and subscriptions. An item key identifies a record by id. A bucket identifies every row with a declared field value; a collection list key covers the whole collection.
24
-
25
- ```ts
26
- import { Schema } from "effect";
27
- import { collection, invalidationKeys } from "@shivaedev/changes/keys.ts";
28
-
29
- const notes = collection("notes", Schema.Number, { userId: Schema.String, listId: Schema.Number });
30
- const keys = [notes.item(1), notes.bucket.userId("alice"), notes.bucket.listId(42)];
31
- const invalidations = invalidationKeys(keys);
32
- ```
33
-
34
- Use `readKeys(keys)` to register dependencies with native Reactivity and `invalidationKeys(keys)` when announcing committed writes. A bucket changes when the writer names it; SQL repositories derive those names from model fields marked with `bucket`. Its value is typed by the declared field schema. A filtered list query still reads its entire bucket and reruns when any row there changes. Record changes also invalidate the collection list, while buckets remain explicit. The channel can buffer these keys until commit just like any other change vocabulary.
35
-
36
- `bucket(schema)` from `@shivaedev/changes/buckets.ts` declares a model field as a write bucket without changing its schema type or variants:
37
-
38
- ```ts
39
- import { bucket } from "@shivaedev/changes/buckets.ts";
40
-
41
- const listId = bucket(Schema.NumberFromString);
42
- ```
43
-
44
- The SQL binding reads these declarations with `declaredBuckets(model.fields)` and decodes old and new stored values into the same identity values queries use. Bucket schemas decode to strings, numbers, null or undefined and require no services. Absent values contribute no key. See the [SQL guide](../sql/README.md#transactions-and-invalidation) for repository writes and PostgreSQL requirements.
45
-
46
- Query read policies belong to the contract. The query checks its session viewer before its record or bucket scope can become a subscription; a change key grants no read permission. See the [contract query guide](../contract/README.md#query-policies-record-keys-and-buckets).
47
-
48
21
  ## Using it
49
22
 
50
23
  ### How to think about it
@@ -56,7 +29,6 @@ Owners matter when a program uses more than one database or client. Owner B comm
56
29
  The channel owns notifications, not writes. Record descriptions of what needs refreshing beside the write that affects it. Choose a key that identifies notifications that can share one refresh; this boundary is for coalescing refresh work, rather than storing every business event.
57
30
 
58
31
  The work has three parts:
59
-
60
32
  1. Once per binding, define the change type, owner, key and publish function, and bind the native transaction.
61
33
  2. Once per feature, record the subjects affected by each write.
62
34
  3. In each operation, run the feature through the transaction boundary or group autocommitted work with a batch.
@@ -69,19 +41,20 @@ import { Effect } from "effect";
69
41
  import { SqlClient } from "effect/sql";
70
42
 
71
43
  interface MembershipChange {
72
- readonly subject: string;
73
- readonly domain: string;
44
+ readonly subject: string;
45
+ readonly domain: string;
74
46
  }
75
47
 
76
48
  const published: Array<MembershipChange> = [];
77
49
 
78
50
  const membershipChanges = makeChannel<MembershipChange, SqlClient.SqlClient>({
79
- name: "MembershipChanges",
80
- owner: Effect.map(SqlClient.SqlClient, (sql) => sql.transactionService),
81
- key: (change) => `${change.subject}:${change.domain}`,
82
- publish: (changes) => Effect.sync(() => {
83
- published.push(...changes);
84
- }),
51
+ name: "MembershipChanges",
52
+ owner: Effect.map(SqlClient.SqlClient, (sql) => sql.transactionService),
53
+ key: (change) => `${change.subject}:${change.domain}`,
54
+ publish: (changes) =>
55
+ Effect.sync(() => {
56
+ published.push(...changes);
57
+ }),
85
58
  });
86
59
  ```
87
60
 
@@ -93,14 +66,14 @@ The owner is the native SQL client's transaction-service identity. The key group
93
66
 
94
67
  ```ts
95
68
  const grantMembership = (owner: string, member: string) =>
96
- Effect.gen(function* () {
97
- const sql = yield* SqlClient.SqlClient;
98
- yield* sql`insert into membership (owner, member) values (${owner}, ${member})`;
99
- yield* membershipChanges.record([
100
- { subject: owner, domain: "memberships" },
101
- { subject: member, domain: "memberships" },
102
- ]);
103
- });
69
+ Effect.gen(function* () {
70
+ const sql = yield* SqlClient.SqlClient;
71
+ yield* sql`insert into membership (owner, member) values (${owner}, ${member})`;
72
+ yield* membershipChanges.record([
73
+ { subject: owner, domain: "memberships" },
74
+ { subject: member, domain: "memberships" },
75
+ ]);
76
+ });
104
77
  ```
105
78
 
106
79
  One write can name several subjects. `record` deduplicates the supplied changes by the channel's key, and the transaction frame deduplicates across later records and committed nested frames. Keys retain their first-seen order.
@@ -111,12 +84,10 @@ Record while the transaction body is still running. A record or a nested frame o
111
84
 
112
85
  ```ts
113
86
  const grant = (owner: string, member: string) =>
114
- Effect.gen(function* () {
115
- const sql = yield* SqlClient.SqlClient;
116
- return yield* grantMembership(owner, member).pipe(
117
- membershipChanges.within(sql.withTransaction),
118
- );
119
- });
87
+ Effect.gen(function* () {
88
+ const sql = yield* SqlClient.SqlClient;
89
+ return yield* grantMembership(owner, member).pipe(membershipChanges.within(sql.withTransaction));
90
+ });
120
91
  ```
121
92
 
122
93
  Provide the application's native SQL layer when running `grant`. Publication happens after the native transaction succeeds and before the wrapper returns. A typed failure, defect, body interruption or failed commit discards the root frame. A nested commit merges into its parent; a nested rollback leaves the parent's own changes intact.
@@ -125,12 +96,39 @@ When interruption arrives while commit is in flight, the boundary waits for the
125
96
 
126
97
  Concurrent records from Effects that inherit the same frame join that frame and publish together. Keep all write-related work within the transaction's lifetime.
127
98
 
99
+ ### Record keys and buckets
100
+
101
+ `keys.ts` owns the shared dependency format for contract queries, committed writes and subscriptions. An item key identifies a record by id. A bucket identifies every row with a declared field value; a collection list key covers the whole collection.
102
+
103
+ ```ts
104
+ import { Schema } from "effect";
105
+ import { collection, invalidationKeys } from "@shivaedev/changes/keys.ts";
106
+
107
+ const notes = collection("notes", Schema.Number, { userId: Schema.String, listId: Schema.Number });
108
+ const keys = [notes.item(1), notes.bucket.userId("alice"), notes.bucket.listId(42)];
109
+ const invalidations = invalidationKeys(keys);
110
+ ```
111
+
112
+ Use `readKeys(keys)` to register dependencies with native Reactivity and `invalidationKeys(keys)` when announcing committed writes. A bucket changes when the writer names it; SQL repositories derive those names from model fields marked with `bucket`. Its value is typed by the declared field schema. A filtered list query still reads its entire bucket and reruns when any row there changes. Record changes also invalidate the collection list, while buckets remain explicit. The channel can buffer these keys until commit just like any other change vocabulary.
113
+
114
+ `bucket(schema)` from `@shivaedev/changes/buckets.ts` declares a model field as a write bucket without changing its schema type or variants:
115
+
116
+ ```ts
117
+ import { bucket } from "@shivaedev/changes/buckets.ts";
118
+
119
+ const listId = bucket(Schema.NumberFromString);
120
+ ```
121
+
122
+ The SQL binding reads these declarations with `declaredBuckets(model.fields)` and decodes old and new stored values into the same identity values queries use. Bucket schemas decode to strings, numbers, null or undefined and require no services. Absent values contribute no key. See the [SQL guide](https://github.com/ShivaeDev/platform/blob/main/packages/sql/README.md#transactions-and-invalidation) for repository writes and PostgreSQL requirements.
123
+
124
+ Query read policies belong to the contract. The query checks its session viewer before its record or bucket scope can become a subscription; a change key grants no read permission. See the [contract query guide](https://github.com/ShivaeDev/platform/blob/main/packages/contract/README.md#query-policies-record-keys-and-buckets).
125
+
128
126
  ### Group already-autocommitted writes
129
127
 
130
128
  ```ts
131
129
  const grantSeveral = Effect.gen(function* () {
132
- yield* grantMembership("ada", "bob");
133
- yield* grantMembership("ada", "cyd");
130
+ yield* grantMembership("ada", "bob");
131
+ yield* grantMembership("ada", "cyd");
134
132
  }).pipe(membershipChanges.batch);
135
133
  ```
136
134
 
@@ -165,23 +163,19 @@ import { Layer } from "effect";
165
163
  const captured: Array<MembershipChange> = [];
166
164
  const observations: Array<Observation<MembershipChange>> = [];
167
165
 
168
- const captureSink = Layer.succeed(
169
- membershipChanges.Sink,
170
- (changes: readonly MembershipChange[]) => Effect.sync(() => {
171
- captured.push(...changes);
172
- }),
166
+ const captureSink = Layer.succeed(membershipChanges.Sink, (changes: readonly MembershipChange[]) =>
167
+ Effect.sync(() => {
168
+ captured.push(...changes);
169
+ }),
173
170
  );
174
171
 
175
- const observe = Layer.succeed(
176
- membershipChanges.Observer,
177
- (observation: Observation<MembershipChange>) => Effect.sync(() => {
178
- observations.push(observation);
179
- }),
172
+ const observe = Layer.succeed(membershipChanges.Observer, (observation: Observation<MembershipChange>) =>
173
+ Effect.sync(() => {
174
+ observations.push(observation);
175
+ }),
180
176
  );
181
177
 
182
- const capturedGrant = grant("ada", "bob").pipe(
183
- Effect.provide(Layer.merge(captureSink, observe)),
184
- );
178
+ const capturedGrant = grant("ada", "bob").pipe(Effect.provide(Layer.merge(captureSink, observe)));
185
179
  ```
186
180
 
187
181
  `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.
@@ -196,23 +190,26 @@ A direct driver binding using `open` must run `frame.beforeCommit` inside its tr
196
190
 
197
191
  Import from the module that defines the name; the package has no root entry.
198
192
 
199
- | Module | Names |
200
- | --- | --- |
201
- | `channel.ts` | `makeChannel`, `ChannelOptions`, `Channel`, `BeforeCommit` |
202
- | `frame.ts` | `Frame`, `CommitFrame`, `Outcome` |
203
- | `observe.ts` | `Observation`, `Observer` |
204
- | `publish.ts` | `Publish`, `PublishFailure` |
193
+ | Module | Names |
194
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
195
+ | `@shivaedev/changes/channel.ts` | `makeChannel`, `ChannelOptions`, `Channel`, `BeforeCommit` |
196
+ | `@shivaedev/changes/frame.ts` | `Frame`, `CommitFrame`, `Outcome` |
197
+ | `@shivaedev/changes/observe.ts` | `Observation`, `Observer` |
198
+ | `@shivaedev/changes/publish.ts` | `Publish`, `PublishFailure` |
199
+ | `@shivaedev/changes/keys.ts` | `collection`, `readKeys`, `invalidationKeys`, `Key`, `ListKey`, `ItemKey`, `BucketKey`, `Collection`, `Identity`, `KeyContext` |
200
+ | `@shivaedev/changes/buckets.ts` | `bucket`, `declaredBuckets` |
201
+
202
+ A `Channel` exposes `record`, `within`, `batch` and `open`, and the scoped references `Sink`, `CommittedSink`, `Observer` and `BeforeCommit`.
205
203
 
206
204
  `key` is optional; for string changes, omitting it deduplicates repeated strings. A custom key is useful when a change is a structured description of an affected subject.
207
205
 
208
206
  ### Install, setup and limits
209
207
 
210
208
  ```sh
211
- pnpm add @shivaedev/changes effect@4.0.5
209
+ pnpm add @shivaedev/changes effect
212
210
  ```
213
211
 
214
212
  `effect` is a peer dependency, so the application's Effect version runs the channel. The package declares Node 24 or newer. The SQL example also needs the application's native SQL driver and layer; neither the channel nor its installation creates a database connection or table.
215
-
216
213
  - The channel is an in-process notification boundary. It has no persistent outbox, replay or cross-process transport; deployment delivery requires a separate design.
217
214
  - Only explicitly recorded changes reach the channel. Trigger, cascade and raw SQL write discovery belongs to a binding or the application.
218
215
  - A native adapter must observe the real commit outcome. Wrapping only the body of a transaction does not establish that outcome.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/changes",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Commit-bound change channels for Effect: publish recorded changes only after the transaction commits",
5
5
  "keywords": [
6
6
  "effect"
@@ -43,15 +43,15 @@
43
43
  "README.md"
44
44
  ],
45
45
  "devDependencies": {
46
- "@shivaedev/quality": "0.43.0",
47
- "@shivaedev/test-story": "0.22.0",
46
+ "@shivaedev/quality": "0.45.0",
47
+ "@shivaedev/test-story": "0.24.0",
48
48
  "@types/node": "24.19.2",
49
- "effect": "4.0.5",
49
+ "effect": "4.0.6",
50
50
  "typescript": "7.0.2",
51
51
  "vitest": "5.0.5"
52
52
  },
53
53
  "peerDependencies": {
54
- "effect": "4.0.5"
54
+ "effect": "4.0.6"
55
55
  },
56
56
  "engines": {
57
57
  "node": ">=24"