@shivaedev/contract 0.45.0 → 0.46.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.
Files changed (196) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/README.md +71 -37
  3. package/dist/AutomaticQueryOptions.d.ts +2 -0
  4. package/dist/AutomaticQueryOptions.d.ts.map +1 -1
  5. package/dist/CommandGuard.d.ts +2 -1
  6. package/dist/CommandGuard.d.ts.map +1 -1
  7. package/dist/CommandGuard.js +3 -2
  8. package/dist/CommandGuard.js.map +1 -1
  9. package/dist/HostVersion.d.ts +6 -1
  10. package/dist/HostVersion.d.ts.map +1 -1
  11. package/dist/LiveSync.d.ts +18 -0
  12. package/dist/LiveSync.d.ts.map +1 -0
  13. package/dist/LiveSync.js +9 -0
  14. package/dist/LiveSync.js.map +1 -0
  15. package/dist/adapters/activityState.d.ts.map +1 -1
  16. package/dist/adapters/activityState.js +1 -0
  17. package/dist/adapters/activityState.js.map +1 -1
  18. package/dist/adapters/liveHintStream.d.ts +3 -19
  19. package/dist/adapters/liveHintStream.d.ts.map +1 -1
  20. package/dist/adapters/liveHintStream.js +2 -2
  21. package/dist/adapters/liveHintStream.js.map +1 -1
  22. package/dist/adapters/openLiveHints.d.ts +3 -19
  23. package/dist/adapters/openLiveHints.d.ts.map +1 -1
  24. package/dist/adapters/openLiveHints.js +21 -3
  25. package/dist/adapters/openLiveHints.js.map +1 -1
  26. package/dist/adapters/standaloneLiveServer.d.ts +5 -18
  27. package/dist/adapters/standaloneLiveServer.d.ts.map +1 -1
  28. package/dist/adapters/standaloneLiveServer.js +6 -1
  29. package/dist/adapters/standaloneLiveServer.js.map +1 -1
  30. package/dist/automaticLive.d.ts.map +1 -1
  31. package/dist/automaticLive.js +21 -1
  32. package/dist/automaticLive.js.map +1 -1
  33. package/dist/automaticQuery.d.ts +1 -1
  34. package/dist/automaticQuery.d.ts.map +1 -1
  35. package/dist/automaticQuery.js +7 -1
  36. package/dist/automaticQuery.js.map +1 -1
  37. package/dist/bind.js +3 -2
  38. package/dist/bind.js.map +1 -1
  39. package/dist/catchUp.d.ts +6 -0
  40. package/dist/catchUp.d.ts.map +1 -0
  41. package/dist/catchUp.js +9 -0
  42. package/dist/catchUp.js.map +1 -0
  43. package/dist/changesSuccess.d.ts +2 -1
  44. package/dist/changesSuccess.d.ts.map +1 -1
  45. package/dist/changesSuccess.js +3 -0
  46. package/dist/changesSuccess.js.map +1 -1
  47. package/dist/clientActivities.d.ts +2 -0
  48. package/dist/clientActivities.d.ts.map +1 -1
  49. package/dist/clientActivities.js +1 -0
  50. package/dist/clientActivities.js.map +1 -1
  51. package/dist/clientActivity.d.ts +1 -0
  52. package/dist/clientActivity.d.ts.map +1 -1
  53. package/dist/clientActivity.js +1 -1
  54. package/dist/clientActivity.js.map +1 -1
  55. package/dist/clientOperations.d.ts +1 -0
  56. package/dist/clientOperations.d.ts.map +1 -1
  57. package/dist/clientOperations.js +17 -1
  58. package/dist/clientOperations.js.map +1 -1
  59. package/dist/clientOptions.d.ts +1 -0
  60. package/dist/clientOptions.d.ts.map +1 -1
  61. package/dist/commandSignal.d.ts +5 -0
  62. package/dist/commandSignal.d.ts.map +1 -0
  63. package/dist/commandSignal.js +25 -0
  64. package/dist/commandSignal.js.map +1 -0
  65. package/dist/connectionProtocol.d.ts +10 -14
  66. package/dist/connectionProtocol.d.ts.map +1 -1
  67. package/dist/connectionProtocol.js +8 -3
  68. package/dist/connectionProtocol.js.map +1 -1
  69. package/dist/live-server/initialize.d.ts +1 -0
  70. package/dist/live-server/initialize.d.ts.map +1 -1
  71. package/dist/live-server/initialize.js +2 -1
  72. package/dist/live-server/initialize.js.map +1 -1
  73. package/dist/live-server/register.d.ts +2 -19
  74. package/dist/live-server/register.d.ts.map +1 -1
  75. package/dist/live-server/register.js +2 -2
  76. package/dist/live-server/register.js.map +1 -1
  77. package/dist/live-server/service.d.ts +7 -37
  78. package/dist/live-server/service.d.ts.map +1 -1
  79. package/dist/live-server/service.js +2 -0
  80. package/dist/live-server/service.js.map +1 -1
  81. package/dist/live-server/stream.d.ts +1 -18
  82. package/dist/live-server/stream.d.ts.map +1 -1
  83. package/dist/live-server/stream.js +2 -2
  84. package/dist/live-server/stream.js.map +1 -1
  85. package/dist/live-server/subscribe.d.ts.map +1 -1
  86. package/dist/live-server/subscribe.js +6 -2
  87. package/dist/live-server/subscribe.js.map +1 -1
  88. package/dist/live-server/syncFrames.d.ts +5 -0
  89. package/dist/live-server/syncFrames.d.ts.map +1 -0
  90. package/dist/live-server/syncFrames.js +16 -0
  91. package/dist/live-server/syncFrames.js.map +1 -0
  92. package/dist/live-server/synced.d.ts +7 -0
  93. package/dist/live-server/synced.d.ts.map +1 -0
  94. package/dist/live-server/synced.js +11 -0
  95. package/dist/live-server/synced.js.map +1 -0
  96. package/dist/liveHintQueue.d.ts +5 -19
  97. package/dist/liveHintQueue.d.ts.map +1 -1
  98. package/dist/liveHintQueue.js +4 -2
  99. package/dist/liveHintQueue.js.map +1 -1
  100. package/dist/liveRetry.d.ts +1 -0
  101. package/dist/liveRetry.d.ts.map +1 -1
  102. package/dist/liveRetry.js +5 -2
  103. package/dist/liveRetry.js.map +1 -1
  104. package/dist/liveSyncRequest.d.ts +6 -0
  105. package/dist/liveSyncRequest.d.ts.map +1 -0
  106. package/dist/liveSyncRequest.js +7 -0
  107. package/dist/liveSyncRequest.js.map +1 -0
  108. package/dist/liveSyncRpc.d.ts +7 -0
  109. package/dist/liveSyncRpc.d.ts.map +1 -0
  110. package/dist/liveSyncRpc.js +10 -0
  111. package/dist/liveSyncRpc.js.map +1 -0
  112. package/dist/makeLiveServer.d.ts +5 -18
  113. package/dist/makeLiveServer.d.ts.map +1 -1
  114. package/dist/publicConfig.d.ts +6 -1
  115. package/dist/publicConfig.d.ts.map +1 -1
  116. package/dist/queryDelivery.d.ts +2 -1
  117. package/dist/queryDelivery.d.ts.map +1 -1
  118. package/dist/queryDelivery.js +20 -4
  119. package/dist/queryDelivery.js.map +1 -1
  120. package/dist/querySubscription.d.ts +1 -0
  121. package/dist/querySubscription.d.ts.map +1 -1
  122. package/dist/querySubscription.js.map +1 -1
  123. package/dist/queryUpdate.d.ts +15 -1
  124. package/dist/queryUpdate.d.ts.map +1 -1
  125. package/dist/queryUpdate.js +4 -0
  126. package/dist/queryUpdate.js.map +1 -1
  127. package/dist/reflectCommand.d.ts +10 -0
  128. package/dist/reflectCommand.d.ts.map +1 -0
  129. package/dist/reflectCommand.js +35 -0
  130. package/dist/reflectCommand.js.map +1 -0
  131. package/dist/reflectedStream.d.ts +18 -0
  132. package/dist/reflectedStream.d.ts.map +1 -0
  133. package/dist/reflectedStream.js +35 -0
  134. package/dist/reflectedStream.js.map +1 -0
  135. package/dist/reflection.d.ts +26 -0
  136. package/dist/reflection.d.ts.map +1 -0
  137. package/dist/reflection.js +94 -0
  138. package/dist/reflection.js.map +1 -0
  139. package/dist/rpcClient.d.ts +3 -2
  140. package/dist/rpcClient.d.ts.map +1 -1
  141. package/dist/rpcClient.js +12 -6
  142. package/dist/rpcClient.js.map +1 -1
  143. package/dist/screenSync.d.ts +8 -0
  144. package/dist/screenSync.d.ts.map +1 -0
  145. package/dist/screenSync.js +6 -0
  146. package/dist/screenSync.js.map +1 -0
  147. package/dist/socketProtocol.d.ts +1 -1
  148. package/dist/socketProtocol.d.ts.map +1 -1
  149. package/dist/syncHeader.d.ts +7 -0
  150. package/dist/syncHeader.d.ts.map +1 -0
  151. package/dist/syncHeader.js +22 -0
  152. package/dist/syncHeader.js.map +1 -0
  153. package/package.json +9 -9
  154. package/src/AutomaticQueryOptions.ts +2 -0
  155. package/src/CommandGuard.ts +12 -4
  156. package/src/LiveSync.ts +9 -0
  157. package/src/adapters/activityState.ts +1 -0
  158. package/src/adapters/liveHintStream.ts +6 -2
  159. package/src/adapters/openLiveHints.ts +25 -3
  160. package/src/adapters/standaloneLiveServer.ts +6 -1
  161. package/src/automaticLive.ts +24 -2
  162. package/src/automaticQuery.ts +7 -0
  163. package/src/bind.ts +3 -2
  164. package/src/catchUp.ts +21 -0
  165. package/src/changesSuccess.ts +4 -1
  166. package/src/clientActivities.ts +2 -1
  167. package/src/clientActivity.ts +2 -1
  168. package/src/clientOperations.ts +28 -10
  169. package/src/clientOptions.ts +1 -0
  170. package/src/commandSignal.ts +27 -0
  171. package/src/connectionProtocol.ts +9 -3
  172. package/src/live-server/initialize.ts +2 -1
  173. package/src/live-server/register.ts +2 -2
  174. package/src/live-server/service.ts +2 -0
  175. package/src/live-server/stream.ts +2 -2
  176. package/src/live-server/subscribe.ts +10 -4
  177. package/src/live-server/syncFrames.ts +19 -0
  178. package/src/live-server/synced.ts +13 -0
  179. package/src/liveHintQueue.ts +9 -4
  180. package/src/liveRetry.ts +6 -2
  181. package/src/liveSyncRequest.ts +17 -0
  182. package/src/liveSyncRpc.ts +11 -0
  183. package/src/queryDelivery.ts +29 -5
  184. package/src/querySubscription.ts +1 -0
  185. package/src/queryUpdate.ts +7 -1
  186. package/src/reflectCommand.ts +48 -0
  187. package/src/reflectedStream.ts +54 -0
  188. package/src/reflection.ts +110 -0
  189. package/src/rpcClient.ts +12 -6
  190. package/src/screenSync.ts +10 -0
  191. package/src/syncHeader.ts +27 -0
  192. package/dist/liveAnswers.d.ts +0 -9
  193. package/dist/liveAnswers.d.ts.map +0 -1
  194. package/dist/liveAnswers.js +0 -12
  195. package/dist/liveAnswers.js.map +0 -1
  196. package/src/liveAnswers.ts +0 -13
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shivaedev/contract",
3
- "version": "0.45.0",
3
+ "version": "0.46.0",
4
4
  "description": "Typed query and command contracts over native Effect RPC and reactivity",
5
5
  "keywords": [
6
6
  "effect"
@@ -43,7 +43,7 @@
43
43
  "README.md"
44
44
  ],
45
45
  "dependencies": {
46
- "@shivaedev/changes": "0.12.0",
46
+ "@shivaedev/changes": "0.13.0",
47
47
  "@shivaedev/errors": "0.12.0",
48
48
  "@shivaedev/service": "0.9.1",
49
49
  "@shivaedev/types": "0.4.0"
@@ -51,13 +51,13 @@
51
51
  "devDependencies": {
52
52
  "@effect/platform-node": "4.1.2",
53
53
  "@effect/vitest": "4.1.2",
54
- "@shivaedev/identity": "0.32.1",
55
- "@shivaedev/quality": "0.78.1",
56
- "@shivaedev/server": "0.34.2",
57
- "@shivaedev/sql": "0.48.0",
58
- "@shivaedev/test-kits": "0.13.0",
59
- "@shivaedev/test-sql": "0.25.1",
60
- "@shivaedev/test-story": "0.47.2",
54
+ "@shivaedev/identity": "0.32.2",
55
+ "@shivaedev/quality": "0.78.2",
56
+ "@shivaedev/server": "0.35.0",
57
+ "@shivaedev/sql": "0.49.0",
58
+ "@shivaedev/test-kits": "0.13.1",
59
+ "@shivaedev/test-sql": "0.25.2",
60
+ "@shivaedev/test-story": "0.47.3",
61
61
  "@types/node": "24.19.2",
62
62
  "effect": "4.1.2",
63
63
  "happy-dom": "21.0.4",
@@ -3,8 +3,10 @@ import type * as Atom from "effect/reactivity/Atom";
3
3
  import type { LiveBound, LiveConnection } from "#automaticLive.ts";
4
4
  import type { LiveStatus } from "#live.ts";
5
5
  import type { QuerySignals } from "#querySignals.ts";
6
+ import type { StreamAnchor } from "#reflectedStream.ts";
6
7
 
7
8
  export interface AutomaticQueryOptions<A, E> {
9
+ readonly anchor: (registry: object) => StreamAnchor;
8
10
  readonly clientStatuses: Atom.Writable<ReadonlyMap<object, LiveStatus<unknown>>> | undefined;
9
11
  readonly equivalent: (left: A, right: A) => boolean;
10
12
  readonly paused: Atom.Writable<boolean>;
@@ -1,17 +1,23 @@
1
1
  import { Context, Effect, Layer, Option, Ref } from "effect";
2
2
  import { type Rpc, type RpcGroup, RpcMiddleware } from "effect/rpc";
3
3
  import { invalidationKeys, type Key } from "@shivaedev/changes/keys.ts";
4
+ import type { SyncToken } from "@shivaedev/changes/syncToken.ts";
4
5
  import { CommandResultKeys } from "#CommandResultKeys.ts";
5
6
  import { prependMiddleware } from "#prependMiddleware.ts";
6
7
  import { CurrentViewer } from "#readPolicy.ts";
7
8
  import { CommandInvalidation } from "#serverMetadata.ts";
9
+ import { syncToken } from "#syncHeader.ts";
8
10
 
9
- export type CommandBoundary = <A, E, R>(effect: Effect.Effect<A, E, R>, keys: (result: A) => readonly unknown[]) => Effect.Effect<A, E, R>;
11
+ export type CommandBoundary = <A, E, R>(
12
+ effect: Effect.Effect<A, E, R>,
13
+ keys: (result: A) => readonly unknown[],
14
+ sync?: SyncToken,
15
+ ) => Effect.Effect<A, E, R>;
10
16
 
11
17
  export class CommandGuard extends RpcMiddleware.Service<CommandGuard>()("@shivaedev/contract/CommandGuard") {}
12
18
 
13
19
  export function commandGuardLayer(boundary: CommandBoundary): Layer.Layer<CommandGuard> {
14
- return Layer.succeed(CommandGuard, (effect, { rpc, payload }) => {
20
+ return Layer.succeed(CommandGuard, (effect, { rpc, payload, headers }) => {
15
21
  const declaration = Context.getOption(rpc.annotations, CommandInvalidation);
16
22
  return Option.isNone(declaration)
17
23
  ? effect
@@ -22,8 +28,10 @@ export function commandGuardLayer(boundary: CommandBoundary): Layer.Layer<Comman
22
28
  Effect.provideService(CommandResultKeys, keys),
23
29
  Effect.flatMap((result) => Effect.map(Ref.get(keys), (extra) => ({ extra, result }))),
24
30
  );
25
- const published = yield* boundary(completed, ({ extra, result }) =>
26
- invalidationKeys([...declaration.value.invalidates(payload, result, viewer), ...extra]),
31
+ const published = yield* boundary(
32
+ completed,
33
+ ({ extra, result }) => invalidationKeys([...declaration.value.invalidates(payload, result, viewer), ...extra]),
34
+ syncToken(headers),
27
35
  );
28
36
  return published.result;
29
37
  });
@@ -0,0 +1,9 @@
1
+ import { Schema } from "effect";
2
+ import { contract } from "#contract.ts";
3
+ import { LIVE_SYNC_COMMAND, LIVE_SYNC_CONTRACT } from "#liveSyncRpc.ts";
4
+ import { command } from "#operation.ts";
5
+
6
+ // A command that writes nothing: its sync token alone travels the change channel, behind every earlier commit.
7
+ export const LiveSync = contract(LIVE_SYNC_CONTRACT, {
8
+ commands: [command(LIVE_SYNC_COMMAND, { invalidates: () => [], success: Schema.Void })],
9
+ });
@@ -14,6 +14,7 @@ export function activityState() {
14
14
  liveHints: 0,
15
15
  refreshingAtoms: 0,
16
16
  rpcCalls: 0,
17
+ unreflectedCommands: 0,
17
18
  }),
18
19
  );
19
20
  function publish() {
@@ -5,10 +5,14 @@ import { LiveDispatcher } from "#adapters/LiveDispatcher.ts";
5
5
  import { openLiveHints } from "#adapters/openLiveHints.ts";
6
6
  import type { initialize } from "#live-server/initialize.ts";
7
7
 
8
- export const liveHintStream = Effect.fn("LiveServer.liveHintStream")(function* (state: Effect.Success<typeof initialize>, keys: readonly Key[]) {
8
+ export const liveHintStream = Effect.fn("LiveServer.liveHintStream")(function* (
9
+ state: Effect.Success<typeof initialize>,
10
+ keys: readonly Key[],
11
+ syncClient?: string,
12
+ ) {
9
13
  const reactivity = yield* Reactivity.Reactivity;
10
14
  const dispatcher = yield* LiveDispatcher;
11
- return Stream.unwrap(Effect.map(openLiveHints(state, keys), Stream.succeed)).pipe(
15
+ return Stream.unwrap(Effect.map(openLiveHints(state, keys, syncClient), Stream.succeed)).pipe(
12
16
  Stream.provideService(Reactivity.Reactivity, reactivity),
13
17
  Stream.provideService(LiveDispatcher, dispatcher),
14
18
  );
@@ -5,12 +5,17 @@ import { LiveDispatcher } from "#adapters/LiveDispatcher.ts";
5
5
  import type { initialize } from "#live-server/initialize.ts";
6
6
  import { liveHintQueue } from "#liveHintQueue.ts";
7
7
 
8
- export const openLiveHints = Effect.fn("LiveServer.openLiveHints")(function* (state: Effect.Success<typeof initialize>, keys: readonly Key[]) {
8
+ export const openLiveHints = Effect.fn("LiveServer.openLiveHints")(function* (
9
+ state: Effect.Success<typeof initialize>,
10
+ keys: readonly Key[],
11
+ syncClient?: string,
12
+ ) {
9
13
  const reactivity = yield* Reactivity.Reactivity;
10
- const { openStreams, resyncKey } = state;
14
+ const { openStreams, resyncKey, syncClients } = state;
11
15
  const { dispatcher } = yield* LiveDispatcher;
12
16
  const { offer, queue } = yield* liveHintQueue;
13
17
  const pending = new Map<string, Key>();
18
+ const synced = new Set<number>();
14
19
  let scheduled = false;
15
20
  let resync = false;
16
21
  let active = true;
@@ -22,9 +27,11 @@ export const openLiveHints = Effect.fn("LiveServer.openLiveHints")(function* (st
22
27
  dispatcher.scheduleTask(() => {
23
28
  scheduled = false;
24
29
  if (active) {
25
- offer(resync ? { _tag: "Resync" } : { _tag: "Changed", keys: [...pending.values()] });
30
+ const tokens = synced.size === 0 ? {} : { synced: [...synced] };
31
+ offer(resync ? { _tag: "Resync", ...tokens } : { _tag: "Changed", keys: [...pending.values()], ...tokens });
26
32
  }
27
33
  pending.clear();
34
+ synced.clear();
28
35
  resync = false;
29
36
  }, 0);
30
37
  }
@@ -48,6 +55,21 @@ export const openLiveHints = Effect.fn("LiveServer.openLiveHints")(function* (st
48
55
  flush();
49
56
  }),
50
57
  ];
58
+ // The token joins the keys already waiting for the flush, so it stays behind every rerun they cause.
59
+ function sync(id: number) {
60
+ synced.add(id);
61
+ flush();
62
+ }
63
+ if (syncClient !== undefined) {
64
+ syncClients.set(syncClient, (syncClients.get(syncClient) ?? new Set()).add(sync));
65
+ cancel.push(() => {
66
+ const subscriptions = syncClients.get(syncClient);
67
+ subscriptions?.delete(sync);
68
+ if (subscriptions?.size === 0) {
69
+ syncClients.delete(syncClient);
70
+ }
71
+ });
72
+ }
51
73
  yield* Ref.update(openStreams, (count) => count + 1);
52
74
  yield* Effect.addFinalizer(() =>
53
75
  Effect.sync(() => {
@@ -11,5 +11,10 @@ export const standaloneLiveServer = Effect.gen(function* () {
11
11
  function subscribe<E, R>(subscription: QuerySubscription<E, R>, read: QueryRerun<E, R>) {
12
12
  return Stream.unwrap(Effect.provideContext(subscribeQueries(subscription, read), context));
13
13
  }
14
- return { resync: server.resync(), stream: (keys: readonly Key[]) => Stream.unwrap(server.stream(keys)), subscribe };
14
+ return {
15
+ resync: server.resync(),
16
+ stream: (keys: readonly Key[], syncClient?: string) => Stream.unwrap(server.stream(keys, syncClient)),
17
+ subscribe,
18
+ synced: server.synced,
19
+ };
15
20
  });
@@ -2,6 +2,7 @@ import { Cause, Effect, Option, type Schema, Stream } from "effect";
2
2
  import type { Headers } from "effect/http";
3
3
  import type * as AsyncResult from "effect/reactivity/AsyncResult";
4
4
  import * as Atom from "effect/reactivity/Atom";
5
+ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
5
6
  import type * as AtomRpc from "effect/reactivity/AtomRpc";
6
7
  import type { Rpc, RpcSchema } from "effect/rpc";
7
8
  import type { Key } from "@shivaedev/changes/keys.ts";
@@ -14,6 +15,7 @@ import { queryDelivery } from "#queryDelivery.ts";
14
15
  import { queryProgress } from "#queryProgress.ts";
15
16
  import { querySignals, shareQuerySignals } from "#querySignals.ts";
16
17
  import type { QueryUpdate } from "#queryUpdate.ts";
18
+ import { followReflection, type StreamAnchor } from "#reflectedStream.ts";
17
19
  import { type ResumeSource, type ResumeWindow, resumeSignal } from "#resume.ts";
18
20
  import { socketIdentity } from "#rpcClient.ts";
19
21
  import type { QueryReference } from "#serverMetadata.ts";
@@ -83,15 +85,35 @@ export function automaticLive(
83
85
  const signals = querySignals(atom);
84
86
  const delivery = queryDelivery(decode, paused, signals);
85
87
  const source = delivery.atom;
88
+ const anchors = new WeakMap<object, StreamAnchor>();
89
+ function anchor(registry: object) {
90
+ const existing = anchors.get(registry);
91
+ if (existing !== undefined) {
92
+ return existing;
93
+ }
94
+ const made: StreamAnchor = { armedAt: undefined, mounted: false, reflection: undefined, supported: undefined };
95
+ anchors.set(registry, made);
96
+ return made;
97
+ }
86
98
  const subscription = live(service.runtime, {
87
99
  keyContext: owner?.context,
88
100
  resume: signal,
89
101
  retryKeys: keys,
90
- stream: Stream.unwrap(service.use((client) => Effect.succeed(client(`${name}.$changes`, { queries: [reference] }, { headers })))).pipe(
91
- delivery.stream,
102
+ stream: Stream.unwrap(
103
+ service.use((client) =>
104
+ Effect.map(AtomRegistry.AtomRegistry, (registry) => {
105
+ const reflected = followReflection(client, anchor(registry));
106
+ if (reflected === undefined) {
107
+ return delivery.stream(client(`${name}.$changes`, { queries: [reference] }, { headers }));
108
+ }
109
+ const opened = client(`${name}.$changes`, { queries: [reference] }, { headers: reflected.headers(headers) });
110
+ return delivery.stream(reflected.lifetime(opened), reflected.follower);
111
+ }),
112
+ ),
92
113
  ),
93
114
  });
94
115
  const gated = automaticQuery({
116
+ anchor,
95
117
  clientStatuses: clientActivities.get(service)?.statuses,
96
118
  equivalent,
97
119
  ownerFailure,
@@ -8,6 +8,7 @@ import { queryResult } from "#queryResult.ts";
8
8
 
9
9
  type GateOptions<A, E> = AutomaticQueryOptions<A, E> & { readonly ownerFailure: (get: Atom.AtomContext) => Error | undefined };
10
10
  export function automaticQuery<A, E>({
11
+ anchor,
11
12
  clientStatuses,
12
13
  equivalent,
13
14
  ownerFailure,
@@ -28,6 +29,12 @@ export function automaticQuery<A, E>({
28
29
  get.set(signals, recordCompletion(get.once(signals), failure));
29
30
  return failure;
30
31
  }
32
+ const mounted = anchor(get.registry);
33
+ mounted.mounted = true;
34
+ get.addFinalizer(() => {
35
+ mounted.mounted = false;
36
+ mounted.reflection?.detach(mounted);
37
+ });
31
38
  get.mount(subscriptionVersion);
32
39
  const openingVersion = get.once(subscriptionVersion);
33
40
  get.refresh(subscription.connection);
package/src/bind.ts CHANGED
@@ -135,6 +135,7 @@ export function makeClient(
135
135
  bindingOptions.live,
136
136
  bindingOptions.resumeWindow,
137
137
  );
138
- const api = bindOperations(contract.declaration, clientOperations(connection.Client, automatic, owner), automatic.subscription);
139
- return Object.assign(connection, { api });
138
+ const operations = clientOperations(connection.Client, automatic, owner);
139
+ const api = bindOperations(contract.declaration, operations, automatic.subscription);
140
+ return Object.assign(connection, { api, sync: operations.sync });
140
141
  }
package/src/catchUp.ts ADDED
@@ -0,0 +1,21 @@
1
+ import { Effect, Queue } from "effect";
2
+ import type { Rpc, RpcClient } from "effect/rpc";
3
+ import type { RpcClientError } from "effect/rpc/RpcClientError";
4
+ import { liveSyncRequest } from "#liveSyncRequest.ts";
5
+ import type { Reflection } from "#reflection.ts";
6
+
7
+ // A stream that may have opened behind a command's token passes a later one, sent on its own once the stream confirms tokens.
8
+ export function catchUp(
9
+ reflection: Reflection,
10
+ client: RpcClient.RpcClient.Flat<Rpc.Any, RpcClientError>,
11
+ connected: Effect.Effect<void, RpcClientError>,
12
+ ) {
13
+ return Queue.take(reflection.catchUps).pipe(
14
+ Effect.andThen(connected),
15
+ Effect.andThen(Effect.suspend(() => liveSyncRequest(client, { client: reflection.client, id: reflection.token() }))),
16
+ // A host that cannot answer the sync will never confirm it, so the waits it covered end here.
17
+ Effect.catchCause(() => Effect.sync(reflection.abandon)),
18
+ Effect.forever,
19
+ Effect.forkScoped,
20
+ );
21
+ }
@@ -1,5 +1,6 @@
1
1
  import { Schema } from "effect";
2
2
  import type { QueryShape } from "#operation.ts";
3
+ import { QuerySynced, QuerySyncing } from "#queryUpdate.ts";
3
4
  import { QueryReadDenied } from "#readPolicyErrors.ts";
4
5
 
5
6
  export const QueryUnchanged = Schema.Struct({ _tag: Schema.Literal("Unchanged"), queryIndex: Schema.Number });
@@ -17,10 +18,12 @@ type ResultSchema<TQuery extends QueryShape> = TQuery extends QueryShape
17
18
 
18
19
  export function changesSuccess<const TQueries extends readonly QueryShape[]>(
19
20
  queries: TQueries,
20
- ): Schema.Union<readonly [typeof QueryReadDenied, ...ResultSchema<TQueries[number]>[]]>;
21
+ ): Schema.Union<readonly [typeof QueryReadDenied, typeof QuerySyncing, typeof QuerySynced, ...ResultSchema<TQueries[number]>[]]>;
21
22
  export function changesSuccess(queries: readonly QueryShape[]) {
22
23
  return Schema.Union([
23
24
  QueryReadDenied,
25
+ QuerySyncing,
26
+ QuerySynced,
24
27
  ...queries.flatMap((query) => [
25
28
  QueryUnchanged,
26
29
  Schema.Struct({
@@ -11,7 +11,7 @@ export const clientActivities = new WeakMap<object, ActivityTracker>();
11
11
  export function makeActivity(factory: Atom.RuntimeFactory) {
12
12
  const { activity, answered, change, hold, setConnection } = activityState();
13
13
  const connection = clientConnection(factory, setConnection, activity);
14
- function begin(key: "rpcCalls" | "commands") {
14
+ function begin(key: "rpcCalls" | "commands" | "unreflectedCommands") {
15
15
  change(key, 1);
16
16
  return () => change(key, -1);
17
17
  }
@@ -91,6 +91,7 @@ export function makeActivity(factory: Atom.RuntimeFactory) {
91
91
  ),
92
92
  true,
93
93
  ),
94
+ reflecting: () => begin("unreflectedCommands"),
94
95
  statuses: connection.statuses,
95
96
  track,
96
97
  watch,
@@ -11,6 +11,7 @@ export interface ClientActivityState {
11
11
  readonly liveHints: number;
12
12
  readonly refreshingAtoms: number;
13
13
  readonly rpcCalls: number;
14
+ readonly unreflectedCommands: number;
14
15
  }
15
16
 
16
17
  export type ClientActivity = Stream.Stream<ClientActivityState> & {
@@ -34,7 +35,7 @@ export function isClientIdle(state: ClientActivityState): boolean {
34
35
  }
35
36
 
36
37
  export function isClientSettled(state: ClientActivityState): boolean {
37
- return state.commands === 0 && state.initialQueries === 0;
38
+ return state.commands === 0 && state.initialQueries === 0 && state.unreflectedCommands === 0;
38
39
  }
39
40
 
40
41
  export function activityScreenSignal(activity: ClientActivity, settled = isClientSettled) {
@@ -12,9 +12,12 @@ import type { QueryOptions } from "#bind.ts";
12
12
  import { clientActivities } from "#clientActivities.ts";
13
13
  import { clientInvalidationKeys, clientReadKeys } from "#clientKeys.ts";
14
14
  import { commandPayload } from "#commandPayload.ts";
15
+ import { CommandSignal, untilReflected } from "#commandSignal.ts";
15
16
  import { waitForConnection } from "#connectionReadiness.ts";
17
+ import { LIVE_SYNC } from "#liveSyncRpc.ts";
16
18
  import type { CommandShape, QueryShape } from "#operation.ts";
17
19
  import { shareQuerySignals } from "#querySignals.ts";
20
+ import { type CommandObserver, reflectCommand } from "#reflectCommand.ts";
18
21
  import { retainQuery } from "#retainQuery.ts";
19
22
 
20
23
  type ErasedClient = AtomRpc.AtomRpcClient<unknown, string, Rpc.Rpc<string, Schema.Top, Schema.Top, Schema.Top>>;
@@ -35,6 +38,11 @@ export function clientOperations(
35
38
  return owner === undefined ? effect : Effect.suspend(() => AtomRegistry.getResult(owner.registry, ordinaryClient.runtime.atom(effect)));
36
39
  }
37
40
 
41
+ const observed = Effect.map(
42
+ CommandSignal,
43
+ (signal): CommandObserver => ({ pending: () => clientActivities.get(ordinaryClient)?.reflecting() ?? (() => undefined), signal }),
44
+ );
45
+
38
46
  function boundQuery(tag: string, query: QueryShape) {
39
47
  const cached = new WeakMap<ReturnType<typeof ordinaryClient.query>, ReturnType<typeof ordinaryClient.query>>();
40
48
  return {
@@ -75,20 +83,29 @@ export function clientOperations(
75
83
  ];
76
84
  return Reactivity.invalidate(clientInvalidationKeys(keys, owner?.context));
77
85
  }
78
- return {
79
- run: (payload: unknown) =>
80
- run(
81
- ordinaryClient.use((client) =>
82
- commandPayload(command, payload).pipe(
83
- Effect.tap(() => waitForConnection(client)),
84
- Effect.flatMap((validated) => client(tag, validated)),
85
- Effect.tap((result) => invalidate(payload, result)),
86
- ),
87
- ),
86
+ function send(observer: CommandObserver, payload: unknown) {
87
+ return ordinaryClient.use((client) =>
88
+ commandPayload(command, payload).pipe(
89
+ Effect.tap(() => waitForConnection(client)),
90
+ Effect.flatMap((validated) => reflectCommand(client, observer, (options) => client(tag, validated, options))),
91
+ Effect.tap((result) => invalidate(payload, result)),
88
92
  ),
93
+ );
94
+ }
95
+ return {
96
+ run: (payload: unknown) => Effect.flatMap(observed, (observer) => run(send(observer, payload))),
89
97
  };
90
98
  }
91
99
 
100
+ function synchronize(observer: CommandObserver) {
101
+ return ordinaryClient.use((client) => {
102
+ const request = reflectCommand(client, observer, (options) => Effect.asVoid(client(LIVE_SYNC, undefined, options)), true);
103
+ return Effect.andThen(waitForConnection(client), request);
104
+ });
105
+ }
106
+ // A sync writes nothing and waits like a command, so it returns once every open live query shows the commits before it.
107
+ const sync = untilReflected(Effect.flatMap(observed, (observer) => run(synchronize(observer))));
108
+
92
109
  function boundStream(tag: string) {
93
110
  return {
94
111
  run: (payload: unknown) => {
@@ -107,5 +124,6 @@ export function clientOperations(
107
124
  command: (tag: string, command: CommandShape) => boundCommand(tag, command),
108
125
  query: (tag: string, query: QueryShape) => boundQuery(tag, query),
109
126
  stream: (tag: string) => boundStream(tag),
127
+ sync,
110
128
  };
111
129
  }
@@ -40,4 +40,5 @@ export type MadeClient<
40
40
  readonly Client: AtomRpc.AtomRpcClient<ClientService<TName, TRpcs | TExtra>, `${TName}/Client`, TRpcs | TExtra>;
41
41
  readonly client: Effect.Effect<RpcClient.RpcClient<TRpcs | TExtra, RpcClientError>, never, Scope.Scope | Rpc.MiddlewareClient<TRpcs | TExtra>>;
42
42
  readonly runtime: Atom.AtomRuntime<ClientService<TName, TRpcs | TExtra>>;
43
+ readonly sync: Effect.Effect<void, RpcClientError, ClientService<TName, TRpcs | TExtra>>;
43
44
  };
@@ -0,0 +1,27 @@
1
+ import { Context, Effect, Latch } from "effect";
2
+
3
+ export type CommandState = "sent" | "accepted" | "reflected";
4
+
5
+ export const CommandSignal = Context.Reference<(state: CommandState) => void>("@shivaedev/contract/CommandSignal", {
6
+ defaultValue: () => () => undefined,
7
+ });
8
+
9
+ export const untilReflected = Effect.fnUntraced(function* <A, E, R>(command: Effect.Effect<A, E, R>) {
10
+ const outer = yield* CommandSignal;
11
+ const reflected = Latch.makeUnsafe(true);
12
+ let accepted = 0;
13
+ const result = yield* Effect.provideService(command, CommandSignal, (state) => {
14
+ outer(state);
15
+ if (state === "accepted") {
16
+ accepted += 1;
17
+ reflected.closeUnsafe();
18
+ } else if (state === "reflected") {
19
+ accepted -= 1;
20
+ if (accepted === 0) {
21
+ reflected.openUnsafe();
22
+ }
23
+ }
24
+ });
25
+ yield* reflected.await;
26
+ return result;
27
+ });
@@ -2,15 +2,21 @@ import { Context, Effect, Layer, Option } from "effect";
2
2
  import * as Atom from "effect/reactivity/Atom";
3
3
  import { RpcClient } from "effect/rpc";
4
4
  import { ConnectionReadiness, connectionReadiness } from "#connectionReadiness.ts";
5
+ import { makeReflection, type Reflection } from "#reflection.ts";
5
6
 
6
- export const protocolConnections = new WeakMap<RpcClient.Protocol["Service"], Effect.Success<typeof connectionReadiness>>();
7
+ // Clients that share one transport share its readiness and its reflection, so a command waits on every stream of its connection.
8
+ export class ConnectionScope extends Context.Service<
9
+ ConnectionScope,
10
+ { readonly connection: Effect.Success<typeof connectionReadiness>; readonly reflection: Reflection }
11
+ >()("@shivaedev/contract/ConnectionScope") {}
7
12
 
8
13
  export const connectionProtocol = Atom.family((protocol: Layer.Layer<RpcClient.Protocol, never, ConnectionReadiness>) =>
9
14
  Layer.unwrap(
10
15
  Effect.gen(function* () {
11
16
  const connection = yield* connectionReadiness;
17
+ const reflection = yield* makeReflection;
12
18
  const hooks = yield* Effect.serviceOption(RpcClient.ConnectionHooks);
13
- return protocol.pipe(
19
+ const managed = protocol.pipe(
14
20
  Layer.provide(
15
21
  Layer.merge(
16
22
  Layer.succeed(ConnectionReadiness, connection),
@@ -20,8 +26,8 @@ export const connectionProtocol = Atom.family((protocol: Layer.Layer<RpcClient.P
20
26
  }),
21
27
  ),
22
28
  ),
23
- Layer.tap((context) => Effect.sync(() => protocolConnections.set(Context.get(context, RpcClient.Protocol), connection))),
24
29
  );
30
+ return Layer.merge(managed, Layer.succeed(ConnectionScope, { connection, reflection }));
25
31
  }),
26
32
  ),
27
33
  );
@@ -3,5 +3,6 @@ import { Effect, Random, Ref } from "effect";
3
3
  export const initialize = Effect.gen(function* () {
4
4
  const openStreams = yield* Ref.make(0);
5
5
  const resyncKey = `@shivaedev/contract/resync/${yield* Random.nextInt}`;
6
- return { openStreams, resyncKey };
6
+ const syncClients = new Map<string, Set<(id: number) => void>>();
7
+ return { openStreams, resyncKey, syncClients };
7
8
  });
@@ -4,7 +4,7 @@ import { liveHintStream } from "#adapters/liveHintStream.ts";
4
4
  import type { initialize } from "#live-server/initialize.ts";
5
5
 
6
6
  export function register(state: Effect.Success<typeof initialize>) {
7
- return Effect.fn("LiveServer.register")(function* (keys: readonly Key[]) {
8
- return yield* liveHintStream(state, keys);
7
+ return Effect.fn("LiveServer.register")(function* (keys: readonly Key[], syncClient?: string) {
8
+ return yield* liveHintStream(state, keys, syncClient);
9
9
  });
10
10
  }
@@ -6,6 +6,7 @@ import { initialize } from "#live-server/initialize.ts";
6
6
  import { register } from "#live-server/register.ts";
7
7
  import { resync } from "#live-server/resync.ts";
8
8
  import { stream } from "#live-server/stream.ts";
9
+ import { synced } from "#live-server/synced.ts";
9
10
 
10
11
  export const LiveServer = defineService({
11
12
  id: "@shivaedev/contract/LiveServer",
@@ -14,6 +15,7 @@ export const LiveServer = defineService({
14
15
  register: register(state),
15
16
  resync: resync(state),
16
17
  stream: stream(state),
18
+ synced: synced(state),
17
19
  }),
18
20
  requires: [Reactivity.Reactivity, LiveDispatcher, Random.Random],
19
21
  });
@@ -4,7 +4,7 @@ import { liveHintStream } from "#adapters/liveHintStream.ts";
4
4
  import type { initialize } from "#live-server/initialize.ts";
5
5
 
6
6
  export function stream(state: Effect.Success<typeof initialize>) {
7
- return Effect.fn("LiveServer.stream")(function* (keys: readonly Key[]) {
8
- return (yield* liveHintStream(state, keys)).pipe(Stream.flatMap((registration) => registration.stream));
7
+ return Effect.fn("LiveServer.stream")(function* (keys: readonly Key[], syncClient?: string) {
8
+ return (yield* liveHintStream(state, keys, syncClient)).pipe(Stream.flatMap((registration) => registration.stream));
9
9
  });
10
10
  }
@@ -3,8 +3,9 @@ import type { Key } from "@shivaedev/changes/keys.ts";
3
3
  import { ReadRecorder, type RecordReadOptions } from "@shivaedev/changes/readRecorder.ts";
4
4
  import { refreshSubscription } from "#adapters/refreshSubscription.ts";
5
5
  import { compareQueries } from "#compareQueries.ts";
6
- import type { LiveHint } from "#live.ts";
7
6
  import { LiveServer } from "#live-server/service.ts";
7
+ import { carriesOnlyTokens, syncFrames } from "#live-server/syncFrames.ts";
8
+ import type { SubscriptionHint } from "#liveHintQueue.ts";
8
9
  import type { QueryRerun, QuerySubscription } from "#querySubscription.ts";
9
10
  import type { QueryUpdate } from "#queryUpdate.ts";
10
11
  import { QueryReadDenied } from "#readPolicyErrors.ts";
@@ -82,12 +83,13 @@ function subscribeQueries<E, R>(
82
83
  function subscribeQueries<E, R>(subscription: QuerySubscription<E, R>, read: QueryRerun<E, R>) {
83
84
  return Effect.fnUntraced(function* () {
84
85
  const server = yield* LiveServer;
85
- const hints = yield* server.register(subscription.keys);
86
+ const syncing = subscription.syncClient !== undefined;
87
+ const hints = yield* server.register(subscription.keys, subscription.syncClient);
86
88
  return hints.pipe(
87
89
  Stream.flatMap((registration) => {
88
90
  const keys = subscriptionKeys(subscription, read, registration.replaceKeys);
89
91
  let compare = compareQueries(subscription, keys.recordingRead);
90
- const next = Effect.fnUntraced(function* (hint: LiveHint) {
92
+ const next = Effect.fnUntraced(function* (hint: SubscriptionHint) {
91
93
  if (!(yield* subscription.authorized)) {
92
94
  compare = compareQueries(subscription, keys.recordingRead, false);
93
95
  return [new QueryReadDenied({ message: "Read no longer allowed for subscribed queries" })];
@@ -100,7 +102,11 @@ function subscribeQueries<E, R>(subscription: QuerySubscription<E, R>, read: Que
100
102
  return updates;
101
103
  });
102
104
  return registration.stream.pipe(
103
- Stream.mapEffect((hint) => refreshSubscription(subscription, next(hint))),
105
+ Stream.mapEffect((hint) =>
106
+ carriesOnlyTokens(hint)
107
+ ? Effect.succeed(syncFrames(syncing, hint, []))
108
+ : Effect.map(refreshSubscription(subscription, next(hint)), (updates) => syncFrames(syncing, hint, updates)),
109
+ ),
104
110
  Stream.flatMap(Stream.fromIterable),
105
111
  );
106
112
  }),
@@ -0,0 +1,19 @@
1
+ import type { SubscriptionHint } from "#liveHintQueue.ts";
2
+ import type { QueryUpdate } from "#queryUpdate.ts";
3
+
4
+ // A token alone changed nothing the stream reads, so it is confirmed without rechecking the session or the policy.
5
+ export function carriesOnlyTokens(hint: SubscriptionHint): boolean {
6
+ return hint._tag === "Changed" && hint.keys.length === 0;
7
+ }
8
+
9
+ // A stream of a client that named itself opens every full read with Syncing and closes every round with the tokens it passed.
10
+ export function syncFrames(syncing: boolean, hint: SubscriptionHint, updates: readonly QueryUpdate[]): readonly QueryUpdate[] {
11
+ if (!syncing) {
12
+ return updates;
13
+ }
14
+ return [
15
+ ...(hint._tag === "Resync" ? [{ _tag: "Syncing" } as const] : []),
16
+ ...updates,
17
+ ...(hint.synced === undefined ? [] : [{ _tag: "Synced", ids: hint.synced } as const]),
18
+ ];
19
+ }
@@ -0,0 +1,13 @@
1
+ import { Effect } from "effect";
2
+ import type { SyncToken } from "@shivaedev/changes/syncToken.ts";
3
+ import type { initialize } from "#live-server/initialize.ts";
4
+
5
+ export function synced(state: Effect.Success<typeof initialize>) {
6
+ return Effect.fn("LiveServer.synced")(function* (token: SyncToken) {
7
+ yield* Effect.sync(() => {
8
+ for (const push of state.syncClients.get(token.client) ?? []) {
9
+ push(token.id);
10
+ }
11
+ });
12
+ });
13
+ }