@shivaedev/contract 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.18.0 - 2026-10-27
+
+### Added
+
+- SQL stories can declare domain read keys that cover written tables with `withChangeCoverage(body, { covers })` and assert committed change keys with `expectPublished(keys)`.
+- Contract stories can observe a viewer's live stream with `watchHints` and use `heard(viewer, keys)` to await allowed hints or report denied keys as unheard on the story clock.
+
 ## 0.17.0 - 2026-10-27
 
 ### Added

package/README.md

@@ -478,6 +478,20 @@ authorizeReads(effect, request, canRead, Effect.fail(new Denied())).pipe(
 );
 ```
 
+### Live hints in stories
+
+Use `watchHints` and `heard` from `@shivaedev/contract/testing.ts` in an application's story kit. Pass each viewer's authenticated live stream to `watchHints`; it starts a scoped subscription and waits for its first hint before returning the viewer handle. The contract's viewer story kit exposes these as `listen(viewer, queries)` and `heard(viewer, keys)`.
+
+```ts
+const alice = yield* watchHints(aliceChanges);
+const bob = yield* watchHints(bobChanges);
+yield* renameNote;
+expect(yield* heard(alice, [notes.item(1)])).toBe(true);
+expect(yield* heard(bob, [notes.item(1)], { within: "50 millis" })).toBe(false);
+```
+
+`heard` returns `true` once a delivered `Changed` hint contains all the requested keys, including hints received before the call. Extra keys are allowed; `Resync` does not count. It returns `false` when no matching hint arrives within `within` (one second by default). Waiting uses the story's Effect clock, so a test clock controls expiry. Stream failures stay in the typed error channel. Keep expectations in the spec; the support verbs need no retry loops or hidden assertions.
+
 ### API by module
 
 Import the module that defines the name; the package has no root entry.
@@ -494,6 +508,7 @@ Import the module that defines the name; the package has no root entry.
 | `readPolicy.ts` | `authorizeReads(effect, request, policy, denied)`; `ReadPolicy`, the request-local fallible key policy used by server hint streams; `ReadPolicyMemoWindow`, a `Context.Reference<Duration.Input>` controlling each stream's memo duration. |
 | `serverMetadata.ts` | `KeyScope`, `QueryReads`, `CommandInvalidation`, `ChangesReads`, `queryKeys(queries, references)` and `changesRpc(name, queries)` for server adapters. |
 | `resume.ts` | `resumeSignal({ window?, native? })`, returning a native numeric signal atom. |
+| `testing.ts` | `watchHints(stream)` starts a scoped viewer subscription; `heard(viewer, keys, { within? }?)` waits for matching changed keys. |
 
 A query atom takes native query options as its optional second argument, for example `api.get.query({ id: 1 }, { timeToLive: "1 minute" })`. A native resume source receives a callback and returns a cleanup function.
 

package/dist/testing.d.ts

@@ -0,0 +1,39 @@
+import { type Duration, Effect, Stream, SubscriptionRef } from "effect";
+import type { Key } from "./keys.ts";
+import type { LiveHint } from "./live.ts";
+export interface HintViewer<E> {
+    readonly finished: Effect.Effect<void, E>;
+    readonly hints: SubscriptionRef.SubscriptionRef<readonly LiveHint[]>;
+}
+export declare const watchHints: <E, R>(stream: Stream.Stream<{
+    readonly _tag: "Changed";
+    readonly keys: readonly ({
+        readonly _tag: "List";
+        readonly collection: string;
+    } | {
+        readonly _tag: "Item";
+        readonly collection: string;
+        readonly id: string | number;
+    })[];
+} | {
+    readonly _tag: "Resync";
+}, E, R>) => Effect.Effect<{
+    finished: Effect.Effect<void, E, never>;
+    hints: SubscriptionRef.SubscriptionRef<readonly ({
+        readonly _tag: "Changed";
+        readonly keys: readonly ({
+            readonly _tag: "List";
+            readonly collection: string;
+        } | {
+            readonly _tag: "Item";
+            readonly collection: string;
+            readonly id: string | number;
+        })[];
+    } | {
+        readonly _tag: "Resync";
+    })[]>;
+}, E, R | import("effect/Scope").Scope>;
+export declare const heard: <E>(viewer: HintViewer<E>, keys: readonly Key[], options?: {
+    readonly within?: Duration.Input;
+} | undefined) => Effect.Effect<boolean, E, never>;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,EAAS,MAAM,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,WAAW,UAAU,CAAC,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,eAAe,CAAC,SAAS,QAAQ,EAAE,CAAC,CAAC;CACrE;AAED,eAAO,MAAM,UAAU,GAA2C,CAAC,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;uCAYpE,CAAC;AAEH,eAAO,MAAM,KAAK,GAAsC,CAAC;sBAG3B,QAAQ,CAAC,KAAK;kDAU1C,CAAC"}

package/dist/testing.js

@@ -0,0 +1,20 @@
+import { Deferred, Effect, Fiber, Stream, SubscriptionRef } from "effect";
+export const watchHints = Effect.fn("Live.watchHints")(function* (stream) {
+    const hints = yield* SubscriptionRef.make([]);
+    const ready = yield* Deferred.make();
+    const fiber = yield* stream.pipe(Stream.runForEach((hint) => SubscriptionRef.update(hints, (received) => [...received, hint]).pipe(Effect.andThen(Deferred.succeed(ready, undefined)))), Effect.forkScoped);
+    const finished = Fiber.join(fiber);
+    yield* Effect.raceFirst(Deferred.await(ready), finished);
+    return { finished, hints };
+});
+export const heard = Effect.fn("Live.heard")(function* (viewer, keys, options = {}) {
+    const matching = SubscriptionRef.changes(viewer.hints).pipe(Stream.filter((hints) => hints.some((hint) => namesKeys(hint, keys))), Stream.runHead, Effect.as(true));
+    return yield* Effect.raceFirst(matching, Effect.as(viewer.finished, false)).pipe(Effect.timeoutOrElse({ duration: options.within ?? "1 second", orElse: () => Effect.succeed(false) }));
+});
+function namesKeys(hint, keys) {
+    return (hint._tag === "Changed"
+        && keys.every((key) => hint.keys.some((actual) => actual._tag === key._tag
+            && actual.collection === key.collection
+            && (key._tag === "List" || (actual._tag === "Item" && actual.id === key.id)))));
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAiB,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAC;AASzF,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,QAAQ,CAAC,EAAQ,MAAqC;IAC5G,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,eAAe,CAAC,IAAI,CAAsB,EAAE,CAAC,CAAC;IACnE,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAQ,CAAC;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAC/B,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,EAAE,CAC1B,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,GAAG,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CACzH,EACD,MAAM,CAAC,UAAU,CACjB,CAAC;IACF,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,CAAC;IACzD,OAAO,EAAE,QAAQ,EAAE,KAAK,EAA0B,CAAC;AACpD,CAAC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,QAAQ,CAAC,EACrD,MAAqB,EACrB,IAAoB,EACpB,OAAO,GAAyC,EAAE;IAElD,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,CAC1D,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,EACrE,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CACf,CAAC;IACF,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAC/E,MAAM,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,MAAM,IAAI,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CACrG,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,SAAS,SAAS,CAAC,IAAc,EAAE,IAAoB;IACtD,OAAO,CACN,IAAI,CAAC,IAAI,KAAK,SAAS;WACpB,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CACrB,IAAI,CAAC,IAAI,CAAC,IAAI,CACb,CAAC,MAAM,EAAE,EAAE,CACV,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI;eACrB,MAAM,CAAC,UAAU,KAAK,GAAG,CAAC,UAAU;eACpC,CAAC,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC,CAC7E,CACD,CACD,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shivaedev/contract",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Typed query and command contracts over native Effect RPC and reactivity",
   "keywords": [
     "effect"
@@ -51,8 +51,8 @@
     "@effect/vitest": "4.0.5",
     "@shivaedev/quality": "0.42.0",
     "@shivaedev/test": "0.10.0",
-    "@shivaedev/test-sql": "0.10.0",
-    "@shivaedev/test-story": "0.21.0",
+    "@shivaedev/test-sql": "0.10.1",
+    "@shivaedev/test-story": "0.21.1",
     "@types/node": "24.19.2",
     "effect": "4.0.5",
     "esbuild": "0.28.2",

package/src/testing.ts

@@ -0,0 +1,51 @@
+import { Deferred, type Duration, Effect, Fiber, Stream, SubscriptionRef } from "effect";
+import type { Key } from "./keys.ts";
+import type { LiveHint } from "./live.ts";
+
+export interface HintViewer<E> {
+	readonly finished: Effect.Effect<void, E>;
+	readonly hints: SubscriptionRef.SubscriptionRef<readonly LiveHint[]>;
+}
+
+export const watchHints = Effect.fn("Live.watchHints")(function* <E, R>(stream: Stream.Stream<LiveHint, E, R>) {
+	const hints = yield* SubscriptionRef.make<readonly LiveHint[]>([]);
+	const ready = yield* Deferred.make<void>();
+	const fiber = yield* stream.pipe(
+		Stream.runForEach((hint) =>
+			SubscriptionRef.update(hints, (received) => [...received, hint]).pipe(Effect.andThen(Deferred.succeed(ready, undefined))),
+		),
+		Effect.forkScoped,
+	);
+	const finished = Fiber.join(fiber);
+	yield* Effect.raceFirst(Deferred.await(ready), finished);
+	return { finished, hints } satisfies HintViewer<E>;
+});
+
+export const heard = Effect.fn("Live.heard")(function* <E>(
+	viewer: HintViewer<E>,
+	keys: readonly Key[],
+	options: { readonly within?: Duration.Input } = {},
+) {
+	const matching = SubscriptionRef.changes(viewer.hints).pipe(
+		Stream.filter((hints) => hints.some((hint) => namesKeys(hint, keys))),
+		Stream.runHead,
+		Effect.as(true),
+	);
+	return yield* Effect.raceFirst(matching, Effect.as(viewer.finished, false)).pipe(
+		Effect.timeoutOrElse({ duration: options.within ?? "1 second", orElse: () => Effect.succeed(false) }),
+	);
+});
+
+function namesKeys(hint: LiveHint, keys: readonly Key[]): boolean {
+	return (
+		hint._tag === "Changed"
+		&& keys.every((key) =>
+			hint.keys.some(
+				(actual) =>
+					actual._tag === key._tag
+					&& actual.collection === key.collection
+					&& (key._tag === "List" || (actual._tag === "Item" && actual.id === key.id)),
+			),
+		)
+	);
+}