@shivaedev/changes 0.12.0 → 0.13.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.13.0 - 2026-11-18
4
+
5
+ ### Added
6
+
7
+ - `CommandPublication.publish(keys, sync)` takes the command's sync token, a `SyncToken` from `@shivaedev/changes/syncToken.ts`, and delivers it behind the keys. The default publisher hands it to the `SyncDelivery` reference from the same module.
8
+
3
9
  ## 0.12.0 - 2026-11-11
4
10
 
5
11
  ### Added
package/README.md CHANGED
@@ -109,6 +109,18 @@ const publication = yield* CommandPublication;
109
109
  yield* publication.publish(["notes:1"]);
110
110
  ```
111
111
 
112
+ `publish(keys, sync)` also takes the command's sync token, a `SyncToken` from `@shivaedev/changes/syncToken.ts` holding the `client` that sent the command and that client's number for it. A publisher delivers the token behind the keys, including when there are none, so a live stream that passes it has already seen them. The default publisher hands it to `SyncDelivery` from the same module, a reference the host provides with the function that reaches its streams; without one the token is dropped.
113
+
114
+ ```ts
115
+ import { CommandPublication } from "@shivaedev/changes/commandPublication.ts";
116
+ import { SyncDelivery } from "@shivaedev/changes/syncToken.ts";
117
+
118
+ const publication = yield* CommandPublication;
119
+ yield* publication.publish(["notes:1"], { client: "tab-a", id: 3 }).pipe(Effect.provideService(SyncDelivery, deliver));
120
+ ```
121
+
122
+ Here `deliver` is the host's `(token) => Effect<void>`, such as the live server's `synced`.
123
+
112
124
  Both `publish` and `recover` have `CommandPublicationError` in their typed failure channel; its `cause` preserves the Effect cause. A failed announcement does not undo a committed write. The command boundary handles publication failure separately from the write and can run `publication.recover`. The PostgreSQL binding resynchronizes local streams and broadcasts Resync to other hosts; the server's command publication in `@shivaedev/server` keeps the committed result even when publication or recovery fails, as its [command publication stories](https://github.com/ShivaeDev/platform/blob/main/packages/server/src/commandPublication.spec.ts) show.
113
125
 
114
126
  ### Record keys and buckets
@@ -226,17 +238,19 @@ A direct driver binding using `open` must run `frame.beforeCommit` inside its tr
226
238
 
227
239
  Import from the module that defines the name; the package has no root entry.
228
240
 
229
- | Module | Names |
230
- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
231
- | `@shivaedev/changes/channel.ts` | `makeChannel`, `ChannelOptions`, `Channel`, `BeforeCommit` |
232
- | `@shivaedev/changes/frame.ts` | `Frame`, `CommitFrame`, `Outcome` |
233
- | `@shivaedev/changes/capture.ts` | `makeCapture`, `Capture` |
234
- | `@shivaedev/changes/observe.ts` | `Observation`, `Observer` |
235
- | `@shivaedev/changes/publish.ts` | `Publish`, `PublishFailure` |
236
- | `@shivaedev/changes/keys.ts` | `collection`, `collectionInvalidationKeys`, `compositeId`, `recordKey`, `readKeys`, `invalidationKeys`, `Key`, `ListKey`, `ItemKey`, `BucketKey`, `Collection`, `Identity` |
237
- | `@shivaedev/changes/compositeKeys.ts` | `isComposite`, `isCompositeId`, `CompositeItemKey`, `CompositeBucketKey`, `CompositeId`, `Composite` |
238
- | `@shivaedev/changes/buckets.ts` | `bucket`, `declaredBuckets`, `decodeBucketValue` |
239
- | `@shivaedev/changes/readRecorder.ts` | `ReadRecorder`, `recordRead` |
241
+ | Module | Names |
242
+ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
243
+ | `@shivaedev/changes/channel.ts` | `makeChannel`, `ChannelOptions`, `Channel`, `BeforeCommit` |
244
+ | `@shivaedev/changes/frame.ts` | `Frame`, `CommitFrame`, `Outcome` |
245
+ | `@shivaedev/changes/capture.ts` | `makeCapture`, `Capture` |
246
+ | `@shivaedev/changes/observe.ts` | `Observation`, `Observer` |
247
+ | `@shivaedev/changes/publish.ts` | `Publish`, `PublishFailure` |
248
+ | `@shivaedev/changes/keys.ts` | `collection`, `collectionInvalidationKeys`, `compositeId`, `recordKey`, `readKeys`, `invalidationKeys`, `Key`, `ListKey`, `ItemKey`, `BucketKey`, `Collection`, `Identity` |
249
+ | `@shivaedev/changes/compositeKeys.ts` | `isComposite`, `isCompositeId`, `CompositeItemKey`, `CompositeBucketKey`, `CompositeId`, `Composite` |
250
+ | `@shivaedev/changes/buckets.ts` | `bucket`, `declaredBuckets`, `decodeBucketValue` |
251
+ | `@shivaedev/changes/commandPublication.ts` | `CommandPublication`, `CommandPublisher`, `CommandPublicationError` |
252
+ | `@shivaedev/changes/syncToken.ts` | `SyncToken`, `SyncDelivery` |
253
+ | `@shivaedev/changes/readRecorder.ts` | `ReadRecorder`, `recordRead` |
240
254
 
241
255
  A `Channel` exposes `record`, `within`, `batch` and `open`, and the scoped references `Sink`, `CommittedSink`, `Observer` and `BeforeCommit`.
242
256
 
@@ -1,5 +1,6 @@
1
1
  import { type Cause, Context, Effect } from "effect";
2
2
  import * as Reactivity from "effect/reactivity/Reactivity";
3
+ import { type SyncToken } from "#syncToken.ts";
3
4
  declare const CommandPublicationError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
4
5
  readonly _tag: "CommandPublicationError";
5
6
  } & Readonly<A>;
@@ -8,7 +9,7 @@ export declare class CommandPublicationError extends CommandPublicationError_bas
8
9
  }> {
9
10
  }
10
11
  export interface CommandPublisher {
11
- readonly publish: (keys: readonly unknown[]) => Effect.Effect<void, CommandPublicationError, Reactivity.Reactivity>;
12
+ readonly publish: (keys: readonly unknown[], sync?: SyncToken) => Effect.Effect<void, CommandPublicationError, Reactivity.Reactivity>;
12
13
  readonly recover: Effect.Effect<void, CommandPublicationError>;
13
14
  }
14
15
  export declare const CommandPublication: Context.Reference<CommandPublisher>;
@@ -1 +1 @@
1
- {"version":3,"file":"commandPublication.d.ts","sourceRoot":"","sources":["../src/commandPublication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,8BAA8B,CAAC;;;;AAE3D,qBAAa,uBAAwB,SAAQ,6BAA4C;IACxF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;CACrC,CAAC;CAAG;AAEL,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,uBAAuB,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACpH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;CAC/D;AAED,eAAO,MAAM,kBAAkB,qCAK7B,CAAC"}
1
+ {"version":3,"file":"commandPublication.d.ts","sourceRoot":"","sources":["../src/commandPublication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,OAAO,EAAQ,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;;;;AAE7D,qBAAa,uBAAwB,SAAQ,6BAA4C;IACxF,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;CACrC,CAAC;CAAG;AAEL,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,uBAAuB,EAAE,UAAU,CAAC,UAAU,CAAC,CAAC;IACtI,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;CAC/D;AAED,eAAO,MAAM,kBAAkB,qCAS7B,CAAC"}
@@ -1,10 +1,11 @@
1
1
  import { Context, Data, Effect } from "effect";
2
2
  import * as Reactivity from "effect/reactivity/Reactivity";
3
+ import { SyncDelivery } from "#syncToken.ts";
3
4
  export class CommandPublicationError extends Data.TaggedError("CommandPublicationError") {
4
5
  }
5
6
  export const CommandPublication = Context.Reference("@shivaedev/changes/CommandPublication", {
6
7
  defaultValue: () => ({
7
- publish: (keys) => Reactivity.invalidate(keys).pipe(Effect.catchCause((cause) => Effect.fail(new CommandPublicationError({ cause })))),
8
+ publish: (keys, sync) => Reactivity.invalidate(keys).pipe(Effect.andThen(sync === undefined ? Effect.void : Effect.flatMap(SyncDelivery, (deliver) => deliver(sync))), Effect.catchCause((cause) => Effect.fail(new CommandPublicationError({ cause })))),
8
9
  recover: Effect.void,
9
10
  }),
10
11
  });
@@ -1 +1 @@
1
- {"version":3,"file":"commandPublication.js","sourceRoot":"","sources":["../src/commandPublication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,8BAA8B,CAAC;AAE3D,MAAM,OAAO,uBAAwB,SAAQ,IAAI,CAAC,WAAW,CAAC,yBAAyB,CAErF;CAAG;AAOL,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAmB,uCAAuC,EAAE;IAC9G,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;QACpB,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,uBAAuB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QACtI,OAAO,EAAE,MAAM,CAAC,IAAI;KACpB,CAAC;CACF,CAAC,CAAC"}
1
+ {"version":3,"file":"commandPublication.js","sourceRoot":"","sources":["../src/commandPublication.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC3D,OAAO,KAAK,UAAU,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAkB,MAAM,eAAe,CAAC;AAE7D,MAAM,OAAO,uBAAwB,SAAQ,IAAI,CAAC,WAAW,CAAC,yBAAyB,CAErF;CAAG;AAOL,MAAM,CAAC,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAmB,uCAAuC,EAAE;IAC9G,YAAY,EAAE,GAAG,EAAE,CAAC,CAAC;QACpB,OAAO,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CACvB,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,IAAI,CAC/B,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAC3G,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,uBAAuB,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CACjF;QACF,OAAO,EAAE,MAAM,CAAC,IAAI;KACpB,CAAC;CACF,CAAC,CAAC"}
@@ -0,0 +1,8 @@
1
+ import { Context, Effect, Schema } from "effect";
2
+ export declare const SyncToken: Schema.Struct<{
3
+ readonly client: Schema.String;
4
+ readonly id: Schema.Int;
5
+ }>;
6
+ export type SyncToken = typeof SyncToken.Type;
7
+ export declare const SyncDelivery: Context.Reference<(token: SyncToken) => Effect.Effect<void>>;
8
+ //# sourceMappingURL=syncToken.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"syncToken.d.ts","sourceRoot":"","sources":["../src/syncToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjD,eAAO,MAAM,SAAS;;;EAGpB,CAAC;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,SAAS,CAAC,IAAI,CAAC;AAE9C,eAAO,MAAM,YAAY,4BAA6B,SAAS,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAErF,CAAC"}
@@ -0,0 +1,9 @@
1
+ import { Context, Effect, Schema } from "effect";
2
+ export const SyncToken = Schema.Struct({
3
+ client: Schema.String.check(Schema.isPattern(/^[\w-]{1,64}$/u)),
4
+ id: Schema.Int.check(Schema.isGreaterThan(0)),
5
+ });
6
+ export const SyncDelivery = Context.Reference("@shivaedev/changes/SyncDelivery", {
7
+ defaultValue: () => () => Effect.void,
8
+ });
9
+ //# sourceMappingURL=syncToken.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"syncToken.js","sourceRoot":"","sources":["../src/syncToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEjD,MAAM,CAAC,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC;IAC/D,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;CAC7C,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC,SAAS,CAA4C,iCAAiC,EAAE;IAC3H,YAAY,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI;CACrC,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/changes",
3
- "version": "0.12.0",
3
+ "version": "0.13.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.77.0",
47
- "@shivaedev/test-story": "0.47.0",
46
+ "@shivaedev/quality": "0.78.2",
47
+ "@shivaedev/test-story": "0.47.3",
48
48
  "@types/node": "24.19.2",
49
49
  "effect": "4.1.2",
50
50
  "typescript": "7.0.2",
@@ -1,18 +1,23 @@
1
1
  import { type Cause, Context, Data, Effect } from "effect";
2
2
  import * as Reactivity from "effect/reactivity/Reactivity";
3
+ import { SyncDelivery, type SyncToken } from "#syncToken.ts";
3
4
 
4
5
  export class CommandPublicationError extends Data.TaggedError("CommandPublicationError")<{
5
6
  readonly cause: Cause.Cause<unknown>;
6
7
  }> {}
7
8
 
8
9
  export interface CommandPublisher {
9
- readonly publish: (keys: readonly unknown[]) => Effect.Effect<void, CommandPublicationError, Reactivity.Reactivity>;
10
+ readonly publish: (keys: readonly unknown[], sync?: SyncToken) => Effect.Effect<void, CommandPublicationError, Reactivity.Reactivity>;
10
11
  readonly recover: Effect.Effect<void, CommandPublicationError>;
11
12
  }
12
13
 
13
14
  export const CommandPublication = Context.Reference<CommandPublisher>("@shivaedev/changes/CommandPublication", {
14
15
  defaultValue: () => ({
15
- publish: (keys) => Reactivity.invalidate(keys).pipe(Effect.catchCause((cause) => Effect.fail(new CommandPublicationError({ cause })))),
16
+ publish: (keys, sync) =>
17
+ Reactivity.invalidate(keys).pipe(
18
+ Effect.andThen(sync === undefined ? Effect.void : Effect.flatMap(SyncDelivery, (deliver) => deliver(sync))),
19
+ Effect.catchCause((cause) => Effect.fail(new CommandPublicationError({ cause }))),
20
+ ),
16
21
  recover: Effect.void,
17
22
  }),
18
23
  });
@@ -0,0 +1,11 @@
1
+ import { Context, Effect, Schema } from "effect";
2
+
3
+ export const SyncToken = Schema.Struct({
4
+ client: Schema.String.check(Schema.isPattern(/^[\w-]{1,64}$/u)),
5
+ id: Schema.Int.check(Schema.isGreaterThan(0)),
6
+ });
7
+ export type SyncToken = typeof SyncToken.Type;
8
+
9
+ export const SyncDelivery = Context.Reference<(token: SyncToken) => Effect.Effect<void>>("@shivaedev/changes/SyncDelivery", {
10
+ defaultValue: () => () => Effect.void,
11
+ });