@shivaedev/contract 0.43.5 → 0.45.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 (139) hide show
  1. package/CHANGELOG.md +43 -0
  2. package/README.md +265 -45
  3. package/dist/adapters/activityState.d.ts +3 -2
  4. package/dist/adapters/activityState.d.ts.map +1 -1
  5. package/dist/adapters/activityState.js +11 -1
  6. package/dist/adapters/activityState.js.map +1 -1
  7. package/dist/adapters/clientConnection.d.ts +1 -0
  8. package/dist/adapters/clientConnection.d.ts.map +1 -1
  9. package/dist/adapters/clientConnection.js +18 -10
  10. package/dist/adapters/clientConnection.js.map +1 -1
  11. package/dist/adapters/servedHandlers.d.ts +8 -0
  12. package/dist/adapters/servedHandlers.d.ts.map +1 -0
  13. package/dist/adapters/servedHandlers.js +51 -0
  14. package/dist/adapters/servedHandlers.js.map +1 -0
  15. package/dist/automaticQuery.js +1 -1
  16. package/dist/automaticQuery.js.map +1 -1
  17. package/dist/clientActivities.d.ts +2 -0
  18. package/dist/clientActivities.d.ts.map +1 -1
  19. package/dist/clientActivities.js +7 -3
  20. package/dist/clientActivities.js.map +1 -1
  21. package/dist/clientActivity.d.ts +2 -2
  22. package/dist/clientActivity.d.ts.map +1 -1
  23. package/dist/clientActivity.js +1 -1
  24. package/dist/clientActivity.js.map +1 -1
  25. package/dist/clientContract.d.ts +51 -0
  26. package/dist/clientContract.d.ts.map +1 -0
  27. package/dist/clientContract.js +32 -0
  28. package/dist/clientContract.js.map +1 -0
  29. package/dist/clientMatchesModule.d.ts +18 -0
  30. package/dist/clientMatchesModule.d.ts.map +1 -0
  31. package/dist/clientMatchesModule.js +2 -0
  32. package/dist/clientMatchesModule.js.map +1 -0
  33. package/dist/contract.d.ts +23 -1
  34. package/dist/contract.d.ts.map +1 -1
  35. package/dist/contract.js +9 -6
  36. package/dist/contract.js.map +1 -1
  37. package/dist/declarationError.d.ts +1 -2
  38. package/dist/declarationError.d.ts.map +1 -1
  39. package/dist/declarationError.js +3 -1
  40. package/dist/declarationError.js.map +1 -1
  41. package/dist/defineModule.d.ts +41 -0
  42. package/dist/defineModule.d.ts.map +1 -0
  43. package/dist/defineModule.js +17 -0
  44. package/dist/defineModule.js.map +1 -0
  45. package/dist/live-server/subscribe.d.ts.map +1 -1
  46. package/dist/live-server/subscribe.js +64 -6
  47. package/dist/live-server/subscribe.js.map +1 -1
  48. package/dist/live.d.ts +1 -0
  49. package/dist/live.d.ts.map +1 -1
  50. package/dist/live.js +5 -0
  51. package/dist/live.js.map +1 -1
  52. package/dist/liveAnswers.d.ts +9 -0
  53. package/dist/liveAnswers.d.ts.map +1 -0
  54. package/dist/liveAnswers.js +12 -0
  55. package/dist/liveAnswers.js.map +1 -0
  56. package/dist/moduleHandlers.d.ts +15 -0
  57. package/dist/moduleHandlers.d.ts.map +1 -0
  58. package/dist/moduleHandlers.js +5 -0
  59. package/dist/moduleHandlers.js.map +1 -0
  60. package/dist/moduleProof.d.ts +79 -0
  61. package/dist/moduleProof.d.ts.map +1 -0
  62. package/dist/moduleProof.js +2 -0
  63. package/dist/moduleProof.js.map +1 -0
  64. package/dist/operation.d.ts +14 -12
  65. package/dist/operation.d.ts.map +1 -1
  66. package/dist/operation.js +10 -4
  67. package/dist/operation.js.map +1 -1
  68. package/dist/operationDeclaration.d.ts +9 -1
  69. package/dist/operationDeclaration.d.ts.map +1 -1
  70. package/dist/operationDeclaration.js.map +1 -1
  71. package/dist/queryDelivery.js +1 -1
  72. package/dist/queryDelivery.js.map +1 -1
  73. package/dist/querySubscription.d.ts +1 -1
  74. package/dist/querySubscription.d.ts.map +1 -1
  75. package/dist/querySubscription.js +6 -4
  76. package/dist/querySubscription.js.map +1 -1
  77. package/dist/readPolicy.d.ts +2 -1
  78. package/dist/readPolicy.d.ts.map +1 -1
  79. package/dist/readPolicy.js +9 -5
  80. package/dist/readPolicy.js.map +1 -1
  81. package/dist/retainQuery.d.ts +1 -0
  82. package/dist/retainQuery.d.ts.map +1 -1
  83. package/dist/retainQuery.js +5 -0
  84. package/dist/retainQuery.js.map +1 -1
  85. package/dist/rpcClient.d.ts +1 -0
  86. package/dist/rpcClient.d.ts.map +1 -1
  87. package/dist/runProof.d.ts +69 -0
  88. package/dist/runProof.d.ts.map +1 -0
  89. package/dist/runProof.js +2 -0
  90. package/dist/runProof.js.map +1 -0
  91. package/dist/servedOperation.d.ts +72 -0
  92. package/dist/servedOperation.d.ts.map +1 -0
  93. package/dist/servedOperation.js +11 -0
  94. package/dist/servedOperation.js.map +1 -0
  95. package/dist/servedReadPolicy.d.ts +11 -0
  96. package/dist/servedReadPolicy.d.ts.map +1 -0
  97. package/dist/servedReadPolicy.js +9 -0
  98. package/dist/servedReadPolicy.js.map +1 -0
  99. package/dist/serverMetadata.d.ts +1 -4
  100. package/dist/serverMetadata.d.ts.map +1 -1
  101. package/dist/serverMetadata.js +3 -6
  102. package/dist/serverMetadata.js.map +1 -1
  103. package/dist/successProof.d.ts +51 -0
  104. package/dist/successProof.d.ts.map +1 -0
  105. package/dist/successProof.js +2 -0
  106. package/dist/successProof.js.map +1 -0
  107. package/dist/wire.d.ts +25 -0
  108. package/dist/wire.d.ts.map +1 -0
  109. package/dist/wire.js +13 -0
  110. package/dist/wire.js.map +1 -0
  111. package/package.json +16 -16
  112. package/src/adapters/activityState.ts +12 -3
  113. package/src/adapters/clientConnection.ts +24 -16
  114. package/src/adapters/servedHandlers.ts +69 -0
  115. package/src/automaticQuery.ts +1 -1
  116. package/src/clientActivities.ts +7 -3
  117. package/src/clientActivity.ts +3 -1
  118. package/src/clientContract.ts +128 -0
  119. package/src/clientMatchesModule.ts +24 -0
  120. package/src/contract.ts +24 -17
  121. package/src/declarationError.ts +5 -2
  122. package/src/defineModule.ts +112 -0
  123. package/src/live-server/subscribe.ts +74 -6
  124. package/src/live.ts +7 -0
  125. package/src/liveAnswers.ts +13 -0
  126. package/src/moduleHandlers.ts +23 -0
  127. package/src/moduleProof.ts +101 -0
  128. package/src/operation.ts +47 -33
  129. package/src/operationDeclaration.ts +19 -1
  130. package/src/queryDelivery.ts +1 -1
  131. package/src/querySubscription.ts +6 -4
  132. package/src/readPolicy.ts +15 -5
  133. package/src/retainQuery.ts +7 -0
  134. package/src/runProof.ts +96 -0
  135. package/src/servedOperation.ts +145 -0
  136. package/src/servedReadPolicy.ts +19 -0
  137. package/src/serverMetadata.ts +3 -6
  138. package/src/successProof.ts +120 -0
  139. package/src/wire.ts +45 -0
@@ -4,7 +4,7 @@ import { isPermissionReadPolicy } from "#permissionReadPolicy.ts";
4
4
 
5
5
  export const DeclarationError = Context.Reference<string | undefined>("@shivaedev/contract/DeclarationError", { defaultValue: () => undefined });
6
6
 
7
- type Duplicated<TOperations extends readonly OperationShape[], TSeen extends string = never> = TOperations extends readonly [
7
+ export type Duplicated<TOperations extends readonly OperationShape[], TSeen extends string = never> = TOperations extends readonly [
8
8
  infer THead extends OperationShape,
9
9
  ...infer TTail extends readonly OperationShape[],
10
10
  ]
@@ -24,7 +24,10 @@ export function declarationError(contractName: string, operations: readonly (Que
24
24
  return `Operation names must be unique; duplicated: ${[...new Set(duplicated)].join(", ")}`;
25
25
  }
26
26
  const member = operations.find(
27
- (operation) => operation.kind === "query" && operation.readsCollections !== undefined && !isPermissionReadPolicy(operation.readPolicy),
27
+ (operation) =>
28
+ operation.kind === "query"
29
+ && operation.readsCollections !== undefined
30
+ && (operation.readPolicy === undefined || !isPermissionReadPolicy(operation.readPolicy)),
28
31
  );
29
32
  return member === undefined
30
33
  ? undefined
@@ -0,0 +1,112 @@
1
+ import { Context, type Effect } from "effect";
2
+ import type { Rpc, RpcMiddleware } from "effect/rpc";
3
+ import type { RequirementRecord } from "@shivaedev/service/ServiceRequirements.ts";
4
+ import { type Contract, declaredGroup } from "#contract.ts";
5
+ import type { Allowed, NameProof } from "#moduleProof.ts";
6
+ import type { CommandShape, QueryShape } from "#operation.ts";
7
+ import type { OperationRpc } from "#operationRpc.ts";
8
+ import type { ReadPolicyGuard } from "#ReadPolicyGuard.ts";
9
+ import type { changesRpc } from "#serverMetadata.ts";
10
+ import type { SubjectDeclaration, WithSubject } from "#subject.ts";
11
+ import { type Wire, type WiredAll, wired } from "#wire.ts";
12
+
13
+ export class DefinedModule extends Context.Service<DefinedModule, string>()("@shivaedev/contract/DefinedModule") {}
14
+
15
+ export type ModuleOperation = (QueryShape | CommandShape) & { readonly run: (payload: never) => Effect.Effect<unknown, unknown, unknown> };
16
+
17
+ type QueriesOf<TOperations extends readonly (QueryShape | CommandShape)[]> = readonly Extract<TOperations[number], { readonly kind: "query" }>[];
18
+ type CommandsOf<TOperations extends readonly (QueryShape | CommandShape)[]> = readonly Extract<TOperations[number], { readonly kind: "command" }>[];
19
+
20
+ // The module's handlers provide every service its operations use, read policies included, so its RPCs require none.
21
+ type Served<TRpc> =
22
+ TRpc extends Rpc.Rpc<infer TTag, infer TPayload, infer TSuccess, infer TError, infer TMiddleware, infer _TRequires>
23
+ ? Rpc.Rpc<TTag, TPayload, TSuccess, TError, TMiddleware, never>
24
+ : never;
25
+
26
+ type WithMiddleware<TRpcs extends Rpc.Any, TMiddleware extends RpcMiddleware.AnyService> = [TMiddleware] extends [never]
27
+ ? TRpcs
28
+ : Rpc.AddMiddleware<TRpcs, TMiddleware>;
29
+
30
+ export type ModuleContract<
31
+ TName extends string,
32
+ TOperations extends readonly (QueryShape | CommandShape)[],
33
+ TMiddleware extends RpcMiddleware.AnyService = never,
34
+ TSubject extends SubjectDeclaration | undefined = undefined,
35
+ TScope extends "session" | undefined = undefined,
36
+ > = Contract<
37
+ TName,
38
+ QueriesOf<TOperations>,
39
+ CommandsOf<TOperations>,
40
+ WithMiddleware<
41
+ WithSubject<
42
+ Served<
43
+ | OperationRpc<TName, TOperations[number]>
44
+ | Rpc.AddMiddleware<ReturnType<typeof changesRpc<TName, QueriesOf<TOperations>>>, typeof ReadPolicyGuard>
45
+ >,
46
+ TSubject
47
+ >,
48
+ TMiddleware
49
+ >,
50
+ readonly [],
51
+ TScope
52
+ >;
53
+
54
+ export type Module<
55
+ TName extends string,
56
+ TOperations extends readonly ModuleOperation[],
57
+ TRequirements extends RequirementRecord,
58
+ TMiddleware extends RpcMiddleware.AnyService = never,
59
+ TSubject extends SubjectDeclaration | undefined = undefined,
60
+ TScope extends "session" | undefined = undefined,
61
+ > = ModuleContract<TName, TOperations, TMiddleware, TSubject, TScope> & {
62
+ // The compiler checks the list and nothing reads it at run time, so, like Rpc's ~requires, it exists only in the type.
63
+ readonly "~requires": TRequirements;
64
+ };
65
+
66
+ export interface ModuleDefinition<
67
+ TName extends string,
68
+ TOperations extends readonly ModuleOperation[],
69
+ TRequirements extends RequirementRecord,
70
+ TMiddleware extends RpcMiddleware.AnyService,
71
+ TSubject extends SubjectDeclaration | undefined,
72
+ TScope extends "session" | undefined,
73
+ TWire extends Wire,
74
+ > {
75
+ readonly keyScope?: TScope;
76
+ readonly middleware?: TMiddleware;
77
+ readonly name: TName & NoInfer<NameProof<TOperations, TWire, Allowed<TRequirements, TMiddleware, TSubject>>>;
78
+ readonly operations: TOperations;
79
+ readonly requires: TRequirements;
80
+ readonly subject?: TSubject;
81
+ readonly wire?: TWire;
82
+ }
83
+
84
+ export function defineModule<
85
+ const TName extends string,
86
+ const TOperations extends readonly ModuleOperation[],
87
+ const TRequirements extends RequirementRecord,
88
+ TMiddleware extends RpcMiddleware.AnyService = never,
89
+ const TSubject extends SubjectDeclaration | undefined = undefined,
90
+ const TScope extends "session" | undefined = undefined,
91
+ const TWire extends Wire = Record<never, never>,
92
+ >(
93
+ definition: ModuleDefinition<TName, TOperations, TRequirements, TMiddleware, TSubject, TScope, TWire>,
94
+ ): Module<TName, WiredAll<TOperations, TWire> & readonly ModuleOperation[], TRequirements, TMiddleware, TSubject, TScope>;
95
+ export function defineModule(definition: {
96
+ readonly keyScope?: "session";
97
+ readonly middleware?: RpcMiddleware.AnyService;
98
+ readonly name: string;
99
+ readonly operations: readonly ModuleOperation[];
100
+ readonly subject?: SubjectDeclaration;
101
+ readonly wire?: Wire;
102
+ }): unknown {
103
+ const operations = definition.operations.map((operation) => wired(operation, definition.wire?.[operation.name]));
104
+ const group = declaredGroup(definition.name, {
105
+ annotations: Context.make(DefinedModule, definition.name),
106
+ commands: operations.filter((operation) => operation.kind === "command"),
107
+ queries: operations.filter((operation) => operation.kind === "query"),
108
+ ...(definition.keyScope === undefined ? {} : { keyScope: definition.keyScope }),
109
+ ...(definition.subject === undefined ? {} : { subject: definition.subject }),
110
+ });
111
+ return definition.middleware === undefined ? group : group.middleware(definition.middleware);
112
+ }
@@ -1,4 +1,6 @@
1
1
  import { Effect, Stream } from "effect";
2
+ import type { Key } from "@shivaedev/changes/keys.ts";
3
+ import { ReadRecorder, type RecordReadOptions } from "@shivaedev/changes/readRecorder.ts";
2
4
  import { refreshSubscription } from "#adapters/refreshSubscription.ts";
3
5
  import { compareQueries } from "#compareQueries.ts";
4
6
  import type { LiveHint } from "#live.ts";
@@ -6,6 +8,72 @@ import { LiveServer } from "#live-server/service.ts";
6
8
  import type { QueryRerun, QuerySubscription } from "#querySubscription.ts";
7
9
  import type { QueryUpdate } from "#queryUpdate.ts";
8
10
  import { QueryReadDenied } from "#readPolicyErrors.ts";
11
+ import type { QueryRequest } from "#serverMetadata.ts";
12
+
13
+ // Matching compares serialized keys, so the same serialization identifies a registered key.
14
+ function identity(key: Key) {
15
+ return JSON.stringify(key);
16
+ }
17
+
18
+ function subscriptionKeys<E, R>(subscription: QuerySubscription<E, R>, read: QueryRerun<E, R>, replaceKeys: (keys: readonly Key[]) => void) {
19
+ let scopes = subscription.scopes;
20
+ const recorded = subscription.queries.map((): readonly Key[] => []);
21
+ const recording = subscription.queries.map(() => new Map<string, Key>());
22
+ function merged() {
23
+ return scopes.map((declared, index) => [...declared, ...(recorded[index] ?? [])]);
24
+ }
25
+ let registered = new Set(merged().flat().map(identity));
26
+ function register() {
27
+ const current = new Map([...merged().flat(), ...recording.flatMap((run) => [...run.values()])].map((key) => [identity(key), key]));
28
+ if (current.size === registered.size && [...current.keys()].every((key) => registered.has(key))) {
29
+ return;
30
+ }
31
+ registered = new Set(current.keys());
32
+ replaceKeys([...current.values()]);
33
+ }
34
+ function recordInto(run: Map<string, Key>, declared: boolean) {
35
+ return (keys: readonly Key[], { inferred = false }: RecordReadOptions) =>
36
+ Effect.sync(() => {
37
+ if (inferred && declared) {
38
+ return;
39
+ }
40
+ let unregistered = false;
41
+ for (const key of keys) {
42
+ const id = identity(key);
43
+ run.set(id, key);
44
+ unregistered ||= !registered.has(id);
45
+ }
46
+ if (unregistered) {
47
+ register();
48
+ }
49
+ });
50
+ }
51
+ function keep(request: QueryRequest, index: number, run: ReadonlyMap<string, Key>) {
52
+ return Effect.suspend(() => {
53
+ recorded[index] = [...run.values()];
54
+ recording[index] = new Map();
55
+ // A handler may read nothing for some payloads, so an unheard query is reported, never failed.
56
+ return request.query.undeclaredReads === true && run.size === 0
57
+ ? Effect.logWarning(
58
+ `Live query ${request.query.name} declares no reads and recorded no key, so no write reruns it. Mark its raw SQL reads with their keys or declare reads; reads: () => [] states that it reads nothing.`,
59
+ )
60
+ : Effect.void;
61
+ });
62
+ }
63
+ function recordingRead(request: QueryRequest) {
64
+ const index = subscription.queries.indexOf(request);
65
+ const run = new Map<string, Key>();
66
+ recording[index] = run;
67
+ return read(request).pipe(
68
+ Effect.provideService(ReadRecorder, recordInto(run, request.query.undeclaredReads !== true)),
69
+ Effect.tap(() => keep(request, index, run)),
70
+ );
71
+ }
72
+ function replaceScopes(next: readonly (readonly Key[])[]) {
73
+ scopes = next;
74
+ }
75
+ return { merged, recordingRead, register, replaceScopes };
76
+ }
9
77
 
10
78
  function subscribeQueries<E, R>(
11
79
  subscription: QuerySubscription<E, R>,
@@ -17,18 +85,18 @@ function subscribeQueries<E, R>(subscription: QuerySubscription<E, R>, read: Que
17
85
  const hints = yield* server.register(subscription.keys);
18
86
  return hints.pipe(
19
87
  Stream.flatMap((registration) => {
20
- let scopes = subscription.scopes;
21
- let compare = compareQueries(subscription, read);
88
+ const keys = subscriptionKeys(subscription, read, registration.replaceKeys);
89
+ let compare = compareQueries(subscription, keys.recordingRead);
22
90
  const next = Effect.fnUntraced(function* (hint: LiveHint) {
23
91
  if (!(yield* subscription.authorized)) {
24
- compare = compareQueries(subscription, read, false);
92
+ compare = compareQueries(subscription, keys.recordingRead, false);
25
93
  return [new QueryReadDenied({ message: "Read no longer allowed for subscribed queries" })];
26
94
  }
27
- const updates = yield* compare(hint, scopes);
95
+ const updates = yield* compare(hint, keys.merged());
28
96
  if (subscription.readScopes !== undefined) {
29
- scopes = yield* subscription.readScopes;
30
- registration.replaceKeys(scopes.flat());
97
+ keys.replaceScopes(yield* subscription.readScopes);
31
98
  }
99
+ keys.register();
32
100
  return updates;
33
101
  });
34
102
  return registration.stream.pipe(
package/src/live.ts CHANGED
@@ -27,6 +27,12 @@ export interface LiveOptions<E, R> {
27
27
  readonly stream: Stream.Stream<SubscriptionEvent, E, R>;
28
28
  }
29
29
 
30
+ const connections = new WeakSet<Atom.Atom<unknown>>();
31
+
32
+ export function isLiveConnection(atom: Atom.Atom<unknown>): boolean {
33
+ return connections.has(atom);
34
+ }
35
+
30
36
  export function live<R, E, TRuntimeError>(runtime: Atom.AtomRuntime<R, TRuntimeError>, options: LiveOptions<E, R>) {
31
37
  const paused = Atom.make(false);
32
38
  const status = Atom.make<LiveStatus<E>>({ connection: "connecting", failure: Option.none(), needsResync: true, pending: 0 });
@@ -69,5 +75,6 @@ export function live<R, E, TRuntimeError>(runtime: Atom.AtomRuntime<R, TRuntimeE
69
75
  }),
70
76
  )
71
77
  .pipe(Atom.setIdleTTL(0));
78
+ connections.add(connection);
72
79
  return { connection, paused, status };
73
80
  }
@@ -0,0 +1,13 @@
1
+ import { Effect, Stream } from "effect";
2
+ import type * as Atom from "effect/reactivity/Atom";
3
+ import * as AtomRegistry from "effect/reactivity/AtomRegistry";
4
+ import { querySignals } from "#querySignals.ts";
5
+
6
+ export function liveAnswers(registry: AtomRegistry.AtomRegistry, name: string, query: Atom.Atom<unknown>) {
7
+ const signals = querySignals(query);
8
+ return {
9
+ answered: Stream.map(AtomRegistry.toStream(registry, signals), (state) => state.completed),
10
+ current: Effect.sync(() => registry.get(signals).completed),
11
+ name,
12
+ };
13
+ }
@@ -0,0 +1,23 @@
1
+ import type { Layer } from "effect";
2
+ import type { Rpc, RpcGroup } from "effect/rpc";
3
+ import type { RequirementRecord, RequirementsOf } from "@shivaedev/service/ServiceRequirements.ts";
4
+ import { servedHandlers } from "#adapters/servedHandlers.ts";
5
+ import type { Declared } from "#contract.ts";
6
+ import type { CommandShape, QueryShape, StreamShape } from "#operation.ts";
7
+
8
+ export interface AnyModule {
9
+ readonly "~requires": RequirementRecord;
10
+ readonly application: { readonly requests: ReadonlyMap<string, Rpc.Any> };
11
+ readonly declaration: Declared<string, readonly QueryShape[], readonly CommandShape[], readonly StreamShape[], "session" | undefined>;
12
+ }
13
+
14
+ export type ModuleHandlers<TModule extends AnyModule> = Layer.Layer<
15
+ Rpc.ToHandler<RpcGroup.Rpcs<TModule["application"]>>,
16
+ never,
17
+ RequirementsOf<TModule["~requires"]>
18
+ >;
19
+
20
+ export function moduleHandlers<TModule extends AnyModule>(module: TModule): ModuleHandlers<TModule>;
21
+ export function moduleHandlers(module: AnyModule): Layer.Layer<Rpc.Handler<string>, never, unknown> {
22
+ return servedHandlers(module.application, module.declaration);
23
+ }
@@ -0,0 +1,101 @@
1
+ import type { Effect, Scope } from "effect";
2
+ import type { RpcMiddleware } from "effect/rpc";
3
+ import type { InfrastructureFailure } from "@shivaedev/errors/infrastructure.ts";
4
+ import type { RequirementRecord, RequirementsOf } from "@shivaedev/service/ServiceRequirements.ts";
5
+ import type { Duplicated } from "#declarationError.ts";
6
+ import type { OperationShape } from "#operation.ts";
7
+ import type { QueryReadDenied } from "#readPolicyErrors.ts";
8
+ import type { RejectedBy, RejectionSpecs } from "#rejection.ts";
9
+ import type { Raised, RejectionProblem } from "#runProof.ts";
10
+ import type { SubjectDeclaration, SubjectProvides } from "#subject.ts";
11
+ import type { SuccessProblem } from "#successProof.ts";
12
+ import type { WireEntry, WireEntryOf } from "#wire.ts";
13
+
14
+ export interface OperationNeedsUndeclaredServices<TOperation extends string, TMissing> {
15
+ readonly missingServices: TMissing;
16
+ readonly operation: TOperation;
17
+ readonly problem: "run or readPolicy uses services that the module's requires and middleware do not provide";
18
+ }
19
+
20
+ export interface OperationFailsOutsideItsRejections<TOperation extends string, TUndeclared> {
21
+ readonly operation: TOperation;
22
+ readonly problem: "run or readPolicy fails with errors outside the operation's rejections";
23
+ readonly undeclaredFailures: TUndeclared;
24
+ }
25
+
26
+ type Regenerate = "the generated file is stale; run pnpm generate";
27
+
28
+ export interface WireSuccessStale<TOperation extends string, TFix extends Regenerate, TRun, TWire> {
29
+ readonly fix: TFix;
30
+ readonly operation: TOperation;
31
+ readonly runReturns: TRun;
32
+ readonly wireDeclares: TWire;
33
+ }
34
+
35
+ export interface WireRejectionsStale<TOperation extends string, TFix extends Regenerate, TRaised, TWire> {
36
+ readonly fix: TFix;
37
+ readonly operation: TOperation;
38
+ readonly runRaises: TRaised;
39
+ readonly wireDeclares: TWire;
40
+ }
41
+
42
+ export interface OperationMissingFromWire<TOperation extends string, TFix extends Regenerate> {
43
+ readonly fix: TFix;
44
+ readonly operation: TOperation;
45
+ readonly problem: "the operation declares no success and the module's wire has no entry for it";
46
+ }
47
+
48
+ export interface OperationNameRepeated<TOperation extends string> {
49
+ readonly operation: TOperation;
50
+ readonly problem: "another operation of the module has this name";
51
+ }
52
+
53
+ type Effectful = (...args: never) => Effect.Effect<unknown, unknown, unknown>;
54
+
55
+ type Parts<TOperation> =
56
+ | (TOperation extends { readonly run: infer TRun extends Effectful } ? ReturnType<TRun> : never)
57
+ | (TOperation extends { readonly kind: "query"; readonly readPolicy: infer TPolicy extends Effectful } ? ReturnType<TPolicy> : never);
58
+
59
+ type Returns<TOperation> = TOperation extends { readonly run: infer TRun extends Effectful } ? Effect.Success<ReturnType<TRun>> : never;
60
+ type Declared<TOperation> = TOperation extends { readonly rejections: infer TSpecs extends RejectionSpecs } ? RejectedBy<TSpecs> : never;
61
+ type Tags<E> = E extends { readonly _tag: infer TTag } ? TTag : E;
62
+ type Success<TOperation> = TOperation extends { readonly success: infer TSuccess } ? TSuccess : never;
63
+ type NameOf<TOperation> = TOperation extends { readonly name: infer TName extends string } ? TName : string;
64
+
65
+ type Missing<TOperation, TAllowed> = Exclude<Effect.Services<Parts<TOperation>>, TAllowed | Scope.Scope>;
66
+ type Undeclared<TOperation> = Exclude<Effect.Error<Parts<TOperation>>, Declared<TOperation> | InfrastructureFailure | QueryReadDenied>;
67
+
68
+ // An entry stands in for the operation's own success and rejections, so only the entry is compared with run.
69
+ type WireProblem<TOperation, TEntry extends WireEntry> = [SuccessProblem<NameOf<TOperation>, TEntry["success"], Returns<TOperation>>] extends [never]
70
+ ? [RejectionProblem<NameOf<TOperation>, TEntry["rejections"], Effect.Error<Parts<TOperation>>>] extends [never]
71
+ ? never
72
+ : WireRejectionsStale<NameOf<TOperation>, Regenerate, Tags<Raised<Effect.Error<Parts<TOperation>>>>, keyof TEntry["rejections"]>
73
+ : WireSuccessStale<NameOf<TOperation>, Regenerate, Returns<TOperation>, TEntry["success"]["Type"]>;
74
+
75
+ type OwnProblem<TOperation> = [Undeclared<TOperation>] extends [never]
76
+ ? [SuccessProblem<NameOf<TOperation>, Success<TOperation>, Returns<TOperation>>] extends [never]
77
+ ? never
78
+ : OperationMissingFromWire<NameOf<TOperation>, Regenerate>
79
+ : OperationFailsOutsideItsRejections<NameOf<TOperation>, Tags<Undeclared<TOperation>>>;
80
+
81
+ type OperationProblem<TOperation, TWire, TAllowed> = [Missing<TOperation, TAllowed>] extends [never]
82
+ ? WireEntryOf<TWire, NameOf<TOperation>> extends infer TEntry extends WireEntry
83
+ ? WireProblem<TOperation, TEntry>
84
+ : OwnProblem<TOperation>
85
+ : OperationNeedsUndeclaredServices<NameOf<TOperation>, Missing<TOperation, TAllowed>>;
86
+
87
+ type SubjectServices<TSubject> = TSubject extends SubjectDeclaration ? SubjectProvides<TSubject> : never;
88
+
89
+ export type Allowed<TRequirements extends RequirementRecord, TMiddleware extends RpcMiddleware.AnyService, TSubject> =
90
+ | RequirementsOf<TRequirements>
91
+ | RpcMiddleware.Provides<TMiddleware["Identifier"]>
92
+ | SubjectServices<TSubject>;
93
+
94
+ type Problems<TOperations extends readonly OperationShape[], TWire, TAllowed> =
95
+ | { readonly [TIndex in keyof TOperations]: OperationProblem<TOperations[TIndex], TWire, TAllowed> }[number]
96
+ | (Duplicated<TOperations> extends infer TName extends string ? (TName extends string ? OperationNameRepeated<TName> : never) : never);
97
+
98
+ // The proof sits on the module's name, so the first line of the compiler's message names the operation and its problem.
99
+ export type NameProof<TOperations extends readonly OperationShape[], TWire, TAllowed> = [Problems<TOperations, TWire, TAllowed>] extends [never]
100
+ ? unknown
101
+ : Problems<TOperations, TWire, TAllowed>;
package/src/operation.ts CHANGED
@@ -1,10 +1,13 @@
1
- import type { Option, Schema } from "effect";
1
+ import type { Effect, Option, Schema } from "effect";
2
2
  import type { Key } from "@shivaedev/changes/keys.ts";
3
3
  import type { Bivariant } from "@shivaedev/types/Bivariant.ts";
4
- import { type Declaration, type Loose, operation, type QueryDeclaration } from "#operationDeclaration.ts";
4
+ import { type CommandDeclaration, type Loose, operation, type QueryDeclaration, type StreamDeclaration } from "#operationDeclaration.ts";
5
5
  import type { QueryServerReads } from "#QueryServerReads.ts";
6
- import type { QueryReadPolicy, Viewer } from "#readPolicy.ts";
6
+ import { type QueryReadPolicy, signedIn, type Viewer } from "#readPolicy.ts";
7
7
  import type { Reject, RejectedBy, RejectionSpecs, Rejections, RejectionUnion } from "#rejection.ts";
8
+ import type { ClassRejections, Pending, RunEffect, SpecsOf, SuccessSchema } from "#runProof.ts";
9
+ import type { LooseCommand, LooseQuery, RunCommandDeclaration, RunQueryDeclaration, ServedCommand, ServedQueryOf } from "#servedOperation.ts";
10
+ import { runOf, withAutomatic } from "#servedOperation.ts";
8
11
 
9
12
  export type PayloadSchema<TPayload extends Schema.Top | Schema.Struct.Fields> = TPayload extends Schema.Struct.Fields
10
13
  ? Schema.Struct<TPayload>
@@ -25,10 +28,13 @@ export interface OperationShape {
25
28
 
26
29
  export interface QueryShape<E = unknown, R = unknown> extends OperationShape {
27
30
  readonly kind: "query";
28
- readonly readPolicy: Bivariant<QueryReadPolicy<unknown, E, R>>;
31
+ // A browser's contract declares no policy; a host refuses to serve a query without one.
32
+ readonly readPolicy?: Bivariant<QueryReadPolicy<unknown, E, R>>;
29
33
  reads: Bivariant<(payload: unknown, viewer: Option.Option<Viewer>) => readonly Key[]>;
30
34
  readonly readsCollections?: readonly { readonly name: string }[] | undefined;
31
35
  readonly serverReads?: Bivariant<QueryServerReads<unknown, E, R>>;
36
+ // Set when the query declares no keys, so its live subscription listens on what its repository reads infer.
37
+ readonly undeclaredReads?: true;
32
38
  }
33
39
 
34
40
  export interface StreamShape extends OperationShape {
@@ -41,7 +47,7 @@ export interface CommandShape extends OperationShape {
41
47
  readonly kind: "command";
42
48
  }
43
49
 
44
- interface Operation<TName extends string, TPayload extends Schema.Top, TSuccess extends Schema.Top, TSpecs extends RejectionSpecs>
50
+ export interface Operation<TName extends string, TPayload extends Schema.Top, TSuccess extends Schema.Top, TSpecs extends RejectionSpecs>
45
51
  extends OperationShape {
46
52
  readonly error: RejectionUnion<TSpecs>;
47
53
  readonly name: TName;
@@ -80,22 +86,33 @@ export function query<
80
86
  const TSpecs extends RejectionSpecs = NoRejections,
81
87
  R = never,
82
88
  >(name: TName, declaration: QueryDeclaration<TPayload, TSuccess, TSpecs, R>): NoInfer<Query<TName, PayloadSchema<TPayload>, TSuccess, TSpecs, R>>;
83
- export function query(
84
- name: string,
85
- declaration: Loose & {
86
- readonly reads: (payload: unknown, viewer: Option.Option<Viewer>) => readonly Key[];
87
- readonly readPolicy: QueryReadPolicy<unknown, unknown, unknown>;
88
- readonly readsCollections?: readonly { readonly name: string }[];
89
- readonly serverReads?: QueryServerReads<unknown, unknown, unknown>;
90
- },
91
- ): QueryShape {
89
+ export function query<
90
+ const TName extends string,
91
+ TYielded extends Effect.Effect<unknown, unknown, unknown> = never,
92
+ TReturn = Pending,
93
+ TPayload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
94
+ TSuccess extends Schema.Top | undefined = undefined,
95
+ const TSpecs extends ClassRejections | undefined = undefined,
96
+ TPolicyError = never,
97
+ TPolicyServices = never,
98
+ TReads extends Effect.Effect<readonly Key[], unknown, unknown> = never,
99
+ const TCollections extends readonly { readonly name: string }[] | undefined = undefined,
100
+ >(
101
+ name: TName,
102
+ declaration: RunQueryDeclaration<TName, TPayload, TYielded, TReturn, TSuccess, TSpecs, TPolicyError, TPolicyServices, TReads, TCollections>,
103
+ ): NoInfer<ServedQueryOf<TName, TPayload, TYielded, TReturn, TSuccess, TSpecs, TPolicyError, TPolicyServices, TReads>>;
104
+ export function query(name: string, declaration: LooseQuery): QueryShape {
92
105
  const collections: readonly Key[] = declaration.readsCollections?.map((collection) => ({ _tag: "List", collection: collection.name })) ?? [];
93
106
  return {
94
- ...operation("query", name, declaration),
95
- readPolicy: declaration.readPolicy,
96
- reads: (payload, viewer) => [...declaration.reads(payload, viewer), ...collections],
107
+ ...operation("query", name, withAutomatic(declaration)),
108
+ readPolicy: declaration.readPolicy ?? signedIn,
109
+ reads: (payload, viewer) => [...(declaration.reads?.(payload, viewer) ?? []), ...collections],
97
110
  readsCollections: declaration.readsCollections,
98
111
  ...(declaration.serverReads === undefined ? {} : { serverReads: declaration.serverReads }),
112
+ ...(declaration.reads === undefined && declaration.serverReads === undefined && declaration.readsCollections === undefined
113
+ ? { undeclaredReads: true }
114
+ : {}),
115
+ ...runOf(declaration),
99
116
  };
100
117
  }
101
118
 
@@ -104,17 +121,20 @@ export function command<
104
121
  TPayload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
105
122
  TSuccess extends Schema.Top = Schema.Void,
106
123
  const TSpecs extends RejectionSpecs = NoRejections,
124
+ >(name: TName, declaration: CommandDeclaration<TPayload, TSuccess, TSpecs>): NoInfer<Command<TName, PayloadSchema<TPayload>, TSuccess, TSpecs>>;
125
+ export function command<
126
+ const TName extends string,
127
+ TYielded extends Effect.Effect<unknown, unknown, unknown> = never,
128
+ TReturn = Pending,
129
+ TPayload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
130
+ TSuccess extends Schema.Top | undefined = undefined,
131
+ const TSpecs extends ClassRejections | undefined = undefined,
107
132
  >(
108
133
  name: TName,
109
- declaration: Declaration<TPayload, TSuccess, TSpecs> & {
110
- readonly invalidates: (payload: PayloadSchema<TPayload>["Type"], result: TSuccess["Type"], viewer?: Option.Option<Viewer>) => readonly Key[];
111
- },
112
- ): NoInfer<Command<TName, PayloadSchema<TPayload>, TSuccess, TSpecs>>;
113
- export function command(
114
- name: string,
115
- declaration: Loose & { readonly invalidates: (payload: unknown, result: unknown, viewer?: Option.Option<Viewer>) => readonly Key[] },
116
- ): CommandShape {
117
- return { ...operation("command", name, declaration), invalidates: declaration.invalidates };
134
+ declaration: RunCommandDeclaration<TName, TPayload, TYielded, TReturn, TSuccess, TSpecs>,
135
+ ): NoInfer<ServedCommand<TName, PayloadSchema<TPayload>, SuccessSchema<TSuccess>, SpecsOf<TSpecs>, RunEffect<TYielded, TReturn>>>;
136
+ export function command(name: string, declaration: LooseCommand): CommandShape {
137
+ return { ...operation("command", name, withAutomatic(declaration)), invalidates: declaration.invalidates ?? (() => []), ...runOf(declaration) };
118
138
  }
119
139
 
120
140
  export function stream<
@@ -122,13 +142,7 @@ export function stream<
122
142
  TPayload extends Schema.Top | Schema.Struct.Fields = Schema.Void,
123
143
  TSuccess extends Schema.Top = Schema.Void,
124
144
  const TSpecs extends RejectionSpecs = NoRejections,
125
- >(
126
- name: TName,
127
- declaration: Declaration<TPayload, TSuccess, TSpecs> & {
128
- readonly success: TSuccess;
129
- readonly reads: (payload: PayloadSchema<TPayload>["Type"]) => readonly Key[];
130
- },
131
- ): NoInfer<Streaming<TName, PayloadSchema<TPayload>, TSuccess, TSpecs>>;
145
+ >(name: TName, declaration: StreamDeclaration<TPayload, TSuccess, TSpecs>): NoInfer<Streaming<TName, PayloadSchema<TPayload>, TSuccess, TSpecs>>;
132
146
  export function stream(name: string, declaration: Loose & { readonly reads: (payload: unknown) => readonly Key[] }): StreamShape {
133
147
  return { ...operation("stream", name, declaration), reads: declaration.reads };
134
148
  }
@@ -9,6 +9,7 @@ import { type MatchingTags, type RejectedBy, type RejectionSpecs, rejectionSet }
9
9
  export interface Declaration<TPayload extends Schema.Top | Schema.Struct.Fields, TSuccess extends Schema.Top, TSpecs extends RejectionSpecs> {
10
10
  readonly payload?: TPayload;
11
11
  readonly rejections?: TSpecs & MatchingTags<TSpecs>;
12
+ readonly run?: never;
12
13
  readonly success?: TSuccess;
13
14
  }
14
15
 
@@ -19,10 +20,27 @@ export type QueryDeclaration<
19
20
  R,
20
21
  > = Declaration<TPayload, TSuccess, TSpecs> &
21
22
  CollectionReads<PayloadSchema<TPayload>["Type"], NoInfer<RejectedBy<TSpecs>>, R> & {
22
- readonly reads: (payload: PayloadSchema<TPayload>["Type"], viewer: Option.Option<Viewer>) => readonly Key[];
23
+ readonly reads?: (payload: PayloadSchema<TPayload>["Type"], viewer: Option.Option<Viewer>) => readonly Key[];
23
24
  readonly serverReads?: QueryServerReads<PayloadSchema<TPayload>["Type"], NoInfer<RejectedBy<TSpecs>>, R>;
24
25
  };
25
26
 
27
+ export type CommandDeclaration<
28
+ TPayload extends Schema.Top | Schema.Struct.Fields,
29
+ TSuccess extends Schema.Top,
30
+ TSpecs extends RejectionSpecs,
31
+ > = Declaration<TPayload, TSuccess, TSpecs> & {
32
+ readonly invalidates: (payload: PayloadSchema<TPayload>["Type"], result: TSuccess["Type"], viewer?: Option.Option<Viewer>) => readonly Key[];
33
+ };
34
+
35
+ export type StreamDeclaration<
36
+ TPayload extends Schema.Top | Schema.Struct.Fields,
37
+ TSuccess extends Schema.Top,
38
+ TSpecs extends RejectionSpecs,
39
+ > = Declaration<TPayload, TSuccess, TSpecs> & {
40
+ readonly reads: (payload: PayloadSchema<TPayload>["Type"]) => readonly Key[];
41
+ readonly success: TSuccess;
42
+ };
43
+
26
44
  export interface Loose {
27
45
  readonly payload?: Schema.Top | Schema.Struct.Fields;
28
46
  readonly rejections?: RejectionSpecs;
@@ -7,7 +7,7 @@ import type { QueryUpdate, SubscriptionEvent } from "#queryUpdate.ts";
7
7
 
8
8
  export function queryDelivery<A, E>(decode: (value: unknown) => A, paused: Atom.Atom<boolean>, signals: Atom.Writable<QuerySignals>) {
9
9
  const updates = Atom.make(0);
10
- const pushed = Atom.make<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial());
10
+ const pushed = Atom.make<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial(true));
11
11
  const deliver = Effect.fnUntraced(function* (update: QueryUpdate): Effect.fn.Return<SubscriptionEvent, never, AtomRegistry.AtomRegistry> {
12
12
  const registry = yield* AtomRegistry.AtomRegistry;
13
13
  registry.update(updates, (current) => current + 1);
@@ -1,10 +1,11 @@
1
- import { Context, Effect, type Option } from "effect";
1
+ import { Context, Effect, Option } from "effect";
2
2
  import { Rpc } from "effect/rpc";
3
3
  import type { Key } from "@shivaedev/changes/keys.ts";
4
4
  import { withPolicyContext } from "#adapters/withPolicyContext.ts";
5
5
  import { queryReadKeys } from "#queryReadKeys.ts";
6
- import { checkQuery, type PolicyChannels, type Viewer } from "#readPolicy.ts";
6
+ import { checkPolicy, type PolicyChannels, type Viewer } from "#readPolicy.ts";
7
7
  import type { MissingReadPolicy, QueryReadDenied } from "#readPolicyErrors.ts";
8
+ import { servedReadPolicy } from "#servedReadPolicy.ts";
8
9
  import { ChangesQueries, type QueryReference, type QueryRequest } from "#serverMetadata.ts";
9
10
 
10
11
  export type QueryRerun<E = unknown, R = never> = (request: QueryRequest) => Effect.Effect<unknown, E, R>;
@@ -35,12 +36,13 @@ export function querySubscription(rpc: Rpc.Any, references: readonly QueryRefere
35
36
  queries,
36
37
  Effect.fnUntraced(function* ({ query, payload }) {
37
38
  const policyRpc = Rpc.make(`${prefix}${query.name}`);
39
+ const policy = Option.getOrUndefined(yield* servedReadPolicy(policyRpc)) ?? query.readPolicy;
38
40
  return {
39
- check: withPolicyContext(policyRpc, checkQuery(query, payload, viewer)),
41
+ check: withPolicyContext(policyRpc, checkPolicy(query, policy, payload, viewer)),
40
42
  keys: withPolicyContext(policyRpc, queryReadKeys(query, payload, viewer)),
41
43
  permitted: withPolicyContext(
42
44
  policyRpc,
43
- Effect.suspend(() => query.readPolicy?.(payload, viewer) ?? Effect.succeed(false)),
45
+ Effect.suspend(() => policy?.(payload, viewer) ?? Effect.succeed(false)),
44
46
  ),
45
47
  };
46
48
  }),
package/src/readPolicy.ts CHANGED
@@ -4,6 +4,7 @@ import { withPolicyContext } from "#adapters/withPolicyContext.ts";
4
4
  import type { QueryShape } from "#operation.ts";
5
5
  import { isPermissionReadPolicy } from "#permissionReadPolicy.ts";
6
6
  import { MissingReadPolicy, QueryReadDenied } from "#readPolicyErrors.ts";
7
+ import { servedReadPolicy } from "#servedReadPolicy.ts";
7
8
  import { QueryDefinition } from "#serverMetadata.ts";
8
9
 
9
10
  export interface Viewer {
@@ -14,14 +15,23 @@ export type QueryReadPolicy<TPayload, E = never, R = never> = (payload: TPayload
14
15
  export const CurrentViewer = Context.Reference<Option.Option<Viewer>>("@shivaedev/contract/CurrentViewer", { defaultValue: Option.none });
15
16
  export const signedIn: QueryReadPolicy<unknown> = (_payload, viewer) => Effect.succeed(Option.isSome(viewer));
16
17
 
17
- export const checkQuery = Effect.fnUntraced(function* <E, R>(query: QueryShape<E, R>, payload: unknown, viewer: Option.Option<Viewer>) {
18
- if (query.readPolicy === undefined) {
18
+ export function checkQuery<E, R>(query: QueryShape<E, R>, payload: unknown, viewer: Option.Option<Viewer>) {
19
+ return checkPolicy(query, query.readPolicy, payload, viewer);
20
+ }
21
+
22
+ export const checkPolicy = Effect.fnUntraced(function* <E, R>(
23
+ query: QueryShape,
24
+ policy: QueryReadPolicy<unknown, E, R> | undefined,
25
+ payload: unknown,
26
+ viewer: Option.Option<Viewer>,
27
+ ) {
28
+ if (policy === undefined) {
19
29
  return yield* new MissingReadPolicy({ message: `Declare a readPolicy on query ${query.name} before reading it or subscribing` });
20
30
  }
21
- if (query.readsCollections !== undefined && !isPermissionReadPolicy(query.readPolicy)) {
31
+ if (query.readsCollections !== undefined && !isPermissionReadPolicy(policy)) {
22
32
  return yield* new QueryReadDenied({ message: `Collection reads require a permission policy on query ${query.name}` });
23
33
  }
24
- if (!(yield* query.readPolicy(payload, viewer))) {
34
+ if (!(yield* policy(payload, viewer))) {
25
35
  return yield* new QueryReadDenied({ message: `Read not allowed for query ${query.name}` });
26
36
  }
27
37
  });
@@ -48,7 +58,7 @@ export function authorizeReads(
48
58
  ) {
49
59
  return Effect.fnUntraced(function* () {
50
60
  const definition = Context.getOption(request.rpc.annotations, QueryDefinition);
51
- if (Option.isSome(definition)) {
61
+ if (Option.isSome(definition) && Option.isNone(yield* servedReadPolicy(request.rpc))) {
52
62
  yield* withPolicyContext(request.rpc, checkQuery(definition.value.definition, request.payload, viewer));
53
63
  }
54
64
  return yield* Effect.provideService(effect, CurrentViewer, viewer);