@shivaedev/contract 0.43.5 → 0.44.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 (122) hide show
  1. package/CHANGELOG.md +37 -0
  2. package/README.md +262 -44
  3. package/dist/adapters/servedHandlers.d.ts +8 -0
  4. package/dist/adapters/servedHandlers.d.ts.map +1 -0
  5. package/dist/adapters/servedHandlers.js +51 -0
  6. package/dist/adapters/servedHandlers.js.map +1 -0
  7. package/dist/automaticQuery.js +1 -1
  8. package/dist/automaticQuery.js.map +1 -1
  9. package/dist/clientActivity.d.ts +0 -2
  10. package/dist/clientActivity.d.ts.map +1 -1
  11. package/dist/clientActivity.js +1 -1
  12. package/dist/clientActivity.js.map +1 -1
  13. package/dist/clientContract.d.ts +51 -0
  14. package/dist/clientContract.d.ts.map +1 -0
  15. package/dist/clientContract.js +32 -0
  16. package/dist/clientContract.js.map +1 -0
  17. package/dist/clientMatchesModule.d.ts +18 -0
  18. package/dist/clientMatchesModule.d.ts.map +1 -0
  19. package/dist/clientMatchesModule.js +2 -0
  20. package/dist/clientMatchesModule.js.map +1 -0
  21. package/dist/contract.d.ts +23 -1
  22. package/dist/contract.d.ts.map +1 -1
  23. package/dist/contract.js +9 -6
  24. package/dist/contract.js.map +1 -1
  25. package/dist/declarationError.d.ts +1 -2
  26. package/dist/declarationError.d.ts.map +1 -1
  27. package/dist/declarationError.js +3 -1
  28. package/dist/declarationError.js.map +1 -1
  29. package/dist/defineModule.d.ts +41 -0
  30. package/dist/defineModule.d.ts.map +1 -0
  31. package/dist/defineModule.js +17 -0
  32. package/dist/defineModule.js.map +1 -0
  33. package/dist/live-server/subscribe.d.ts.map +1 -1
  34. package/dist/live-server/subscribe.js +64 -6
  35. package/dist/live-server/subscribe.js.map +1 -1
  36. package/dist/live.d.ts +1 -0
  37. package/dist/live.d.ts.map +1 -1
  38. package/dist/live.js +5 -0
  39. package/dist/live.js.map +1 -1
  40. package/dist/liveAnswers.d.ts +9 -0
  41. package/dist/liveAnswers.d.ts.map +1 -0
  42. package/dist/liveAnswers.js +12 -0
  43. package/dist/liveAnswers.js.map +1 -0
  44. package/dist/moduleHandlers.d.ts +15 -0
  45. package/dist/moduleHandlers.d.ts.map +1 -0
  46. package/dist/moduleHandlers.js +5 -0
  47. package/dist/moduleHandlers.js.map +1 -0
  48. package/dist/moduleProof.d.ts +79 -0
  49. package/dist/moduleProof.d.ts.map +1 -0
  50. package/dist/moduleProof.js +2 -0
  51. package/dist/moduleProof.js.map +1 -0
  52. package/dist/operation.d.ts +14 -12
  53. package/dist/operation.d.ts.map +1 -1
  54. package/dist/operation.js +10 -4
  55. package/dist/operation.js.map +1 -1
  56. package/dist/operationDeclaration.d.ts +9 -1
  57. package/dist/operationDeclaration.d.ts.map +1 -1
  58. package/dist/operationDeclaration.js.map +1 -1
  59. package/dist/queryDelivery.js +1 -1
  60. package/dist/queryDelivery.js.map +1 -1
  61. package/dist/querySubscription.d.ts +1 -1
  62. package/dist/querySubscription.d.ts.map +1 -1
  63. package/dist/querySubscription.js +6 -4
  64. package/dist/querySubscription.js.map +1 -1
  65. package/dist/readPolicy.d.ts +2 -1
  66. package/dist/readPolicy.d.ts.map +1 -1
  67. package/dist/readPolicy.js +9 -5
  68. package/dist/readPolicy.js.map +1 -1
  69. package/dist/retainQuery.d.ts +1 -0
  70. package/dist/retainQuery.d.ts.map +1 -1
  71. package/dist/retainQuery.js +5 -0
  72. package/dist/retainQuery.js.map +1 -1
  73. package/dist/runProof.d.ts +69 -0
  74. package/dist/runProof.d.ts.map +1 -0
  75. package/dist/runProof.js +2 -0
  76. package/dist/runProof.js.map +1 -0
  77. package/dist/servedOperation.d.ts +72 -0
  78. package/dist/servedOperation.d.ts.map +1 -0
  79. package/dist/servedOperation.js +11 -0
  80. package/dist/servedOperation.js.map +1 -0
  81. package/dist/servedReadPolicy.d.ts +11 -0
  82. package/dist/servedReadPolicy.d.ts.map +1 -0
  83. package/dist/servedReadPolicy.js +9 -0
  84. package/dist/servedReadPolicy.js.map +1 -0
  85. package/dist/serverMetadata.d.ts +1 -4
  86. package/dist/serverMetadata.d.ts.map +1 -1
  87. package/dist/serverMetadata.js +3 -6
  88. package/dist/serverMetadata.js.map +1 -1
  89. package/dist/successProof.d.ts +51 -0
  90. package/dist/successProof.d.ts.map +1 -0
  91. package/dist/successProof.js +2 -0
  92. package/dist/successProof.js.map +1 -0
  93. package/dist/wire.d.ts +25 -0
  94. package/dist/wire.d.ts.map +1 -0
  95. package/dist/wire.js +13 -0
  96. package/dist/wire.js.map +1 -0
  97. package/package.json +16 -16
  98. package/src/adapters/servedHandlers.ts +69 -0
  99. package/src/automaticQuery.ts +1 -1
  100. package/src/clientActivity.ts +1 -1
  101. package/src/clientContract.ts +128 -0
  102. package/src/clientMatchesModule.ts +24 -0
  103. package/src/contract.ts +24 -17
  104. package/src/declarationError.ts +5 -2
  105. package/src/defineModule.ts +112 -0
  106. package/src/live-server/subscribe.ts +74 -6
  107. package/src/live.ts +7 -0
  108. package/src/liveAnswers.ts +13 -0
  109. package/src/moduleHandlers.ts +23 -0
  110. package/src/moduleProof.ts +101 -0
  111. package/src/operation.ts +47 -33
  112. package/src/operationDeclaration.ts +19 -1
  113. package/src/queryDelivery.ts +1 -1
  114. package/src/querySubscription.ts +6 -4
  115. package/src/readPolicy.ts +15 -5
  116. package/src/retainQuery.ts +7 -0
  117. package/src/runProof.ts +96 -0
  118. package/src/servedOperation.ts +145 -0
  119. package/src/servedReadPolicy.ts +19 -0
  120. package/src/serverMetadata.ts +3 -6
  121. package/src/successProof.ts +120 -0
  122. package/src/wire.ts +45 -0
@@ -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);
@@ -5,6 +5,12 @@ import { retainedQueries } from "#adapters/retainedQueries.ts";
5
5
  import { querySignals, shareQuerySignals } from "#querySignals.ts";
6
6
  import { wrapAtom } from "#wrapAtom.ts";
7
7
 
8
+ const runtimes = new WeakMap<Atom.Atom<unknown>, Atom.AtomRuntime<unknown, unknown>>();
9
+
10
+ export function queryRuntime(query: Atom.Atom<unknown>): Atom.AtomRuntime<unknown, unknown> | undefined {
11
+ return runtimes.get(query);
12
+ }
13
+
8
14
  export function retainQuery<A, E>(runtime: Atom.AtomRuntime<unknown, unknown>, atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) {
9
15
  const snapshot = Atom.make<Option.Option<AsyncResult.Success<A, E>>>(Option.none()).pipe(Atom.setIdleTTL(0));
10
16
  const signals = querySignals(atom);
@@ -32,5 +38,6 @@ export function retainQuery<A, E>(runtime: Atom.AtomRuntime<unknown, unknown>, a
32
38
  return display(atom.read(context));
33
39
  }).pipe(Atom.setIdleTTL(0));
34
40
  shareQuerySignals(retained, atom);
41
+ runtimes.set(retained, runtime);
35
42
  return retained;
36
43
  }
@@ -0,0 +1,96 @@
1
+ import type { Effect, Schema } from "effect";
2
+ import type { InfrastructureFailure } from "@shivaedev/errors/infrastructure.ts";
3
+ import type { InternalServerError, ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
4
+ import type { QueryReadDenied } from "#readPolicyErrors.ts";
5
+ import type { TaggedRejection } from "#rejection.ts";
6
+ import type { Identical, SuccessProblem } from "#successProof.ts";
7
+
8
+ export type RunBody<TPayload, TYielded, A> = (payload: TPayload) => Generator<TYielded, A, never>;
9
+
10
+ export type ErrorOf<TYielded> = [TYielded] extends [never] ? never : [TYielded] extends [Effect.Effect<unknown, infer E, unknown>] ? E : never;
11
+ export type ServicesOf<TYielded> = [TYielded] extends [never] ? never : [TYielded] extends [Effect.Effect<unknown, unknown, infer R>] ? R : never;
12
+ export type RunEffect<TYielded, A> = [A] extends [unknown] ? Effect.Effect<A, ErrorOf<TYielded>, ServicesOf<TYielded>> : never;
13
+
14
+ export interface ClassRejections {
15
+ readonly [tag: string]: TaggedRejection;
16
+ }
17
+
18
+ export interface Automatic {
19
+ readonly InternalServerError: typeof InternalServerError;
20
+ readonly ServiceUnavailable: typeof ServiceUnavailable;
21
+ }
22
+
23
+ export type Raised<E> = Exclude<E, InfrastructureFailure | QueryReadDenied | InternalServerError | ServiceUnavailable>;
24
+
25
+ export interface RunFailsOutsideRejections<TOperation extends string, TTags> {
26
+ readonly missingRejections: TTags;
27
+ readonly operation: TOperation;
28
+ }
29
+
30
+ export interface RejectionsRunNeverRaises<TOperation extends string, TTags> {
31
+ readonly neverRaised: TTags;
32
+ readonly operation: TOperation;
33
+ }
34
+
35
+ export interface RejectionAutomatic<TOperation extends string, TTags> {
36
+ readonly automatic: TTags;
37
+ readonly operation: TOperation;
38
+ }
39
+
40
+ export interface RejectionClassDiffers<TOperation extends string, TTags> {
41
+ readonly operation: TOperation;
42
+ readonly raisedClassDiffers: TTags;
43
+ }
44
+
45
+ export interface RunReturnsAny<TOperation extends string, TFix extends string> {
46
+ readonly fix: TFix;
47
+ readonly operation: TOperation;
48
+ }
49
+
50
+ type Tags<E> = E extends { readonly _tag: infer TTag extends string } ? TTag : never;
51
+ type IsAny<T> = 0 extends 1 & T ? true : false;
52
+ type Declared<TSpecs> = TSpecs extends ClassRejections ? keyof TSpecs & string : never;
53
+ type AutomaticTags = keyof Automatic;
54
+
55
+ type DifferentClasses<TSpecs, E> = {
56
+ readonly [TTag in Declared<TSpecs>]: TSpecs extends { readonly [TKey in TTag]: new (...args: never) => infer TDeclared }
57
+ ? Identical<TDeclared, Extract<Raised<E>, { readonly _tag: TTag }>> extends true
58
+ ? never
59
+ : TTag
60
+ : never;
61
+ }[Declared<TSpecs>];
62
+
63
+ export type RejectionProblem<TName extends string, TSpecs, E> = TSpecs extends undefined
64
+ ? never
65
+ : [Extract<Declared<TSpecs>, AutomaticTags>] extends [never]
66
+ ? [Exclude<Tags<Raised<E>>, Declared<TSpecs>>] extends [never]
67
+ ? [Exclude<Declared<TSpecs>, Tags<Raised<E>>>] extends [never]
68
+ ? [DifferentClasses<TSpecs, E>] extends [never]
69
+ ? never
70
+ : RejectionClassDiffers<TName, DifferentClasses<TSpecs, E>>
71
+ : RejectionsRunNeverRaises<TName, Exclude<Declared<TSpecs>, Tags<Raised<E>>>>
72
+ : RunFailsOutsideRejections<TName, Exclude<Tags<Raised<E>>, Declared<TSpecs>>>
73
+ : RejectionAutomatic<TName, Extract<Declared<TSpecs>, AutomaticTags>>;
74
+
75
+ type Problems<TName extends string, TSuccess, TSpecs, TReturn, E> = SuccessProblem<TName, TSuccess, TReturn> | RejectionProblem<TName, TSpecs, E>;
76
+
77
+ export type SuccessSchema<TSuccess> = TSuccess extends Schema.Top ? TSuccess : Schema.Void;
78
+ // A mapped type, unlike the Automatic interface, satisfies the index signature of RejectionSpecs.
79
+ type Flat<T> = { readonly [TKey in keyof T]: T[TKey] };
80
+ export type SpecsOf<TSpecs> = TSpecs extends ClassRejections ? Flat<TSpecs & Automatic> : Flat<Automatic>;
81
+
82
+ // TypeScript checks the declaration once with run skipped, before it infers run's types; Pending is the default it sees then.
83
+ export interface Pending {
84
+ readonly pendingInference: unique symbol;
85
+ }
86
+
87
+ type IsPending<TReturn> = [TReturn] extends [never] ? false : [TReturn] extends [Pending] ? true : false;
88
+
89
+ export type RunCheck<TName extends string, TSuccess, TSpecs, TReturn, E> =
90
+ IsAny<TReturn> extends true
91
+ ? { readonly operationProblem: RunReturnsAny<TName, "decode the value with a schema, or give run's return a type"> }
92
+ : IsPending<TReturn> extends true
93
+ ? unknown
94
+ : [Problems<TName, TSuccess, TSpecs, TReturn, E>] extends [never]
95
+ ? unknown
96
+ : { readonly operationProblem: Problems<TName, TSuccess, TSpecs, TReturn, E> };
@@ -0,0 +1,145 @@
1
+ import { Effect, type Option, type Schema } from "effect";
2
+ import type { Key } from "@shivaedev/changes/keys.ts";
3
+ import { InternalServerError, ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
4
+ import type { Operation, PayloadSchema } from "#operation.ts";
5
+ import type { Loose } from "#operationDeclaration.ts";
6
+ import type { PermissionReadPolicy } from "#permissionReadPolicy.ts";
7
+ import type { QueryServerReads } from "#QueryServerReads.ts";
8
+ import type { QueryReadPolicy, Viewer } from "#readPolicy.ts";
9
+ import type { MatchingTags, RejectionSpecs } from "#rejection.ts";
10
+ import type { ErrorOf, RunBody, RunCheck, RunEffect, ServicesOf, SpecsOf, SuccessSchema } from "#runProof.ts";
11
+
12
+ export interface ServedQuery<
13
+ TName extends string,
14
+ TPayload extends Schema.Top,
15
+ TSuccess extends Schema.Top,
16
+ TSpecs extends RejectionSpecs,
17
+ TPolicyError,
18
+ TPolicyServices,
19
+ TRun extends Effect.Effect<unknown, unknown, unknown>,
20
+ > extends Operation<TName, TPayload, TSuccess, TSpecs> {
21
+ readonly kind: "query";
22
+ readonly readPolicy: QueryReadPolicy<TPayload["Type"], TPolicyError, TPolicyServices>;
23
+ reads: (payload: TPayload["Type"], viewer: Option.Option<Viewer>) => readonly Key[];
24
+ readonly readsCollections?: readonly { readonly name: string }[] | undefined;
25
+ readonly run: (payload: TPayload["Type"]) => TRun;
26
+ readonly serverReads?: QueryServerReads<TPayload["Type"], TPolicyError, TPolicyServices>;
27
+ }
28
+
29
+ export interface ServedCommand<
30
+ TName extends string,
31
+ TPayload extends Schema.Top,
32
+ TSuccess extends Schema.Top,
33
+ TSpecs extends RejectionSpecs,
34
+ TRun extends Effect.Effect<unknown, unknown, unknown>,
35
+ > extends Operation<TName, TPayload, TSuccess, TSpecs> {
36
+ invalidates: (payload: TPayload["Type"], result: Effect.Success<TRun>, viewer?: Option.Option<Viewer>) => readonly Key[];
37
+ readonly kind: "command";
38
+ readonly run: (payload: TPayload["Type"]) => TRun;
39
+ }
40
+
41
+ interface RunFields<TPayload extends Schema.Top | Schema.Struct.Fields, TYielded, TReturn, TSuccess, TSpecs> {
42
+ readonly payload?: TPayload;
43
+ readonly rejections?: TSpecs & MatchingTags<NonNullable<TSpecs>>;
44
+ readonly run?: RunBody<PayloadSchema<TPayload>["Type"], TYielded, TReturn>;
45
+ readonly success?: TSuccess;
46
+ }
47
+
48
+ // A run required where its types are inferred makes TypeScript report a declaration without run against default type
49
+ // arguments, hiding the declaration's own mistakes; requiring it apart keeps those errors.
50
+ export type RunDeclaration<TPayload extends Schema.Top | Schema.Struct.Fields, TYielded, TReturn, TSuccess, TSpecs> = RunFields<
51
+ TPayload,
52
+ TYielded,
53
+ TReturn,
54
+ TSuccess,
55
+ TSpecs
56
+ > &
57
+ NoInfer<{ readonly run: RunBody<never, unknown, unknown> }>;
58
+
59
+ export type CollectionReadPolicy<TCollections, TPayload, E, R> = TCollections extends undefined
60
+ ? unknown
61
+ : { readonly readPolicy: PermissionReadPolicy<TPayload, E, R> };
62
+
63
+ export type RunQueryDeclaration<
64
+ TName extends string,
65
+ TPayload extends Schema.Top | Schema.Struct.Fields,
66
+ TYielded,
67
+ TReturn,
68
+ TSuccess,
69
+ TSpecs,
70
+ TPolicyError,
71
+ TPolicyServices,
72
+ TReads,
73
+ TCollections,
74
+ > = RunDeclaration<TPayload, TYielded, TReturn, TSuccess, TSpecs> &
75
+ CollectionReadPolicy<TCollections, PayloadSchema<TPayload>["Type"], TPolicyError, TPolicyServices> & {
76
+ readonly readPolicy?: QueryReadPolicy<PayloadSchema<TPayload>["Type"], TPolicyError, TPolicyServices>;
77
+ readonly reads?: (payload: PayloadSchema<TPayload>["Type"], viewer: Option.Option<Viewer>) => readonly Key[];
78
+ readonly readsCollections?: TCollections;
79
+ readonly serverReads?: (payload: PayloadSchema<TPayload>["Type"], viewer: Option.Option<Viewer>) => TReads;
80
+ } & NoInfer<RunCheck<TName, TSuccess, TSpecs, TReturn, ErrorOf<TYielded> | TPolicyError | ErrorOf<TReads>>>;
81
+
82
+ export type ServedQueryOf<
83
+ TName extends string,
84
+ TPayload extends Schema.Top | Schema.Struct.Fields,
85
+ TYielded,
86
+ TReturn,
87
+ TSuccess,
88
+ TSpecs,
89
+ TPolicyError,
90
+ TPolicyServices,
91
+ TReads,
92
+ > = [TName] extends [string]
93
+ ? ServedQuery<
94
+ TName,
95
+ PayloadSchema<TPayload>,
96
+ SuccessSchema<TSuccess>,
97
+ SpecsOf<TSpecs>,
98
+ TPolicyError | ErrorOf<TReads>,
99
+ TPolicyServices | ServicesOf<TReads>,
100
+ RunEffect<TYielded, TReturn>
101
+ >
102
+ : never;
103
+
104
+ // Object keys are sorted, so invalidates is checked before run and cannot see run's inferred result; a declared success types it.
105
+ export interface ResultNeedsDeclaredSuccess {
106
+ readonly declareSuccess: unique symbol;
107
+ }
108
+
109
+ type ResultOf<TSuccess> = TSuccess extends Schema.Top ? TSuccess["Type"] : ResultNeedsDeclaredSuccess;
110
+
111
+ export type RunCommandDeclaration<
112
+ TName extends string,
113
+ TPayload extends Schema.Top | Schema.Struct.Fields,
114
+ TYielded,
115
+ TReturn,
116
+ TSuccess,
117
+ TSpecs,
118
+ > = RunDeclaration<TPayload, TYielded, TReturn, TSuccess, TSpecs> & {
119
+ readonly invalidates?: (payload: PayloadSchema<TPayload>["Type"], result: ResultOf<TSuccess>, viewer?: Option.Option<Viewer>) => readonly Key[];
120
+ } & NoInfer<RunCheck<TName, TSuccess, TSpecs, TReturn, ErrorOf<TYielded>>>;
121
+
122
+ interface LooseRun extends Loose {
123
+ readonly run?: (payload: never) => Generator<Effect.Effect<unknown, unknown, unknown>, unknown, never>;
124
+ }
125
+
126
+ export interface LooseQuery extends LooseRun {
127
+ readonly readPolicy?: QueryReadPolicy<unknown, unknown, unknown>;
128
+ readonly reads?: (payload: unknown, viewer: Option.Option<Viewer>) => readonly Key[];
129
+ readonly readsCollections?: readonly { readonly name: string }[];
130
+ readonly serverReads?: QueryServerReads<unknown, unknown, unknown>;
131
+ }
132
+
133
+ export interface LooseCommand extends LooseRun {
134
+ readonly invalidates?: (payload: unknown, result: unknown, viewer?: Option.Option<Viewer>) => readonly Key[];
135
+ }
136
+
137
+ export function withAutomatic(declaration: LooseRun): Loose {
138
+ return declaration.run === undefined
139
+ ? declaration
140
+ : { ...declaration, rejections: { ...declaration.rejections, InternalServerError, ServiceUnavailable } };
141
+ }
142
+
143
+ export function runOf({ run }: LooseRun) {
144
+ return run === undefined ? {} : { run: Effect.fnUntraced(run) };
145
+ }
@@ -0,0 +1,19 @@
1
+ import { Context, Effect, Option } from "effect";
2
+ import type { Rpc } from "effect/rpc";
3
+ import type { QueryReadPolicy } from "#readPolicy.ts";
4
+
5
+ export class ServedReadPolicy extends Context.Service<ServedReadPolicy, { readonly check: QueryReadPolicy<unknown, unknown, unknown> }>()(
6
+ "@shivaedev/contract/ServedReadPolicy",
7
+ ) {}
8
+
9
+ // Only a handler built by moduleHandlers carries the policy, so a hand-written handler keeps the guard's check. A call's
10
+ // middleware runs in its handler's context; a live rerun finds the query's handler by its RPC.
11
+ export function servedReadPolicy(rpc: Rpc.Any) {
12
+ return Effect.map(Effect.context<never>(), (request) =>
13
+ Option.orElse(Context.getOption(request, ServedReadPolicy), () =>
14
+ Option.flatMap(Context.getOption(request, Context.Service<Rpc.Handler<string>>(rpc.key)), (handler) =>
15
+ Context.getOption(handler.context, ServedReadPolicy),
16
+ ),
17
+ ).pipe(Option.map(({ check }) => check)),
18
+ );
19
+ }