@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.
- package/CHANGELOG.md +12 -0
- package/README.md +70 -73
- 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
|
-
|
|
73
|
-
|
|
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
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
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
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
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
|
-
|
|
133
|
-
|
|
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
|
-
|
|
170
|
-
|
|
171
|
-
|
|
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
|
-
|
|
177
|
-
|
|
178
|
-
|
|
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
|
|
200
|
-
|
|
|
201
|
-
|
|
|
202
|
-
|
|
|
203
|
-
|
|
|
204
|
-
|
|
|
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
|
|
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.
|
|
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.
|
|
47
|
-
"@shivaedev/test-story": "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.
|
|
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.
|
|
54
|
+
"effect": "4.0.6"
|
|
55
55
|
},
|
|
56
56
|
"engines": {
|
|
57
57
|
"node": ">=24"
|