@shivaedev/contract 0.49.0 → 0.51.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 (66) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +160 -123
  3. package/dist/bind.d.ts +7 -0
  4. package/dist/bind.d.ts.map +1 -1
  5. package/dist/bind.js +2 -1
  6. package/dist/bind.js.map +1 -1
  7. package/dist/clientOperations.d.ts +5 -1
  8. package/dist/clientOperations.d.ts.map +1 -1
  9. package/dist/clientOperations.js +4 -0
  10. package/dist/clientOperations.js.map +1 -1
  11. package/dist/commandSignal.d.ts.map +1 -1
  12. package/dist/commandSignal.js +17 -13
  13. package/dist/commandSignal.js.map +1 -1
  14. package/dist/connectionReadiness.js +1 -1
  15. package/dist/connectionReadiness.js.map +1 -1
  16. package/dist/defineModule.d.ts +5 -7
  17. package/dist/defineModule.d.ts.map +1 -1
  18. package/dist/defineModule.js.map +1 -1
  19. package/dist/failureKind.d.ts +10 -0
  20. package/dist/failureKind.d.ts.map +1 -0
  21. package/dist/failureKind.js +20 -0
  22. package/dist/failureKind.js.map +1 -0
  23. package/dist/live.d.ts.map +1 -1
  24. package/dist/live.js +16 -6
  25. package/dist/live.js.map +1 -1
  26. package/dist/liveHintQueue.d.ts.map +1 -1
  27. package/dist/liveHintQueue.js +19 -14
  28. package/dist/liveHintQueue.js.map +1 -1
  29. package/dist/moduleHandlers.d.ts +3 -3
  30. package/dist/moduleHandlers.d.ts.map +1 -1
  31. package/dist/moduleHandlers.js.map +1 -1
  32. package/dist/moduleProof.d.ts +10 -12
  33. package/dist/moduleProof.d.ts.map +1 -1
  34. package/dist/querySubscription.js +5 -1
  35. package/dist/querySubscription.js.map +1 -1
  36. package/dist/reflection.d.ts.map +1 -1
  37. package/dist/reflection.js +3 -3
  38. package/dist/reflection.js.map +1 -1
  39. package/dist/runProof.d.ts +2 -1
  40. package/dist/runProof.d.ts.map +1 -1
  41. package/dist/servedOperation.d.ts.map +1 -1
  42. package/dist/servedOperation.js +2 -1
  43. package/dist/servedOperation.js.map +1 -1
  44. package/dist/socketProtocol.js +1 -1
  45. package/dist/socketProtocol.js.map +1 -1
  46. package/dist/staleWrite.d.ts +10 -0
  47. package/dist/staleWrite.d.ts.map +1 -0
  48. package/dist/staleWrite.js +14 -0
  49. package/dist/staleWrite.js.map +1 -0
  50. package/package.json +9 -9
  51. package/src/bind.ts +9 -9
  52. package/src/clientOperations.ts +4 -0
  53. package/src/commandSignal.ts +16 -12
  54. package/src/connectionReadiness.ts +1 -1
  55. package/src/defineModule.ts +13 -10
  56. package/src/failureKind.ts +33 -0
  57. package/src/live.ts +19 -6
  58. package/src/liveHintQueue.ts +20 -14
  59. package/src/moduleHandlers.ts +3 -3
  60. package/src/moduleProof.ts +15 -23
  61. package/src/querySubscription.ts +7 -1
  62. package/src/reflection.ts +88 -86
  63. package/src/runProof.ts +3 -1
  64. package/src/servedOperation.ts +2 -1
  65. package/src/socketProtocol.ts +1 -1
  66. package/src/staleWrite.ts +23 -0
@@ -1,6 +1,5 @@
1
1
  import type { Effect, Schema, Scope } from "effect";
2
2
  import type { RpcMiddleware } from "effect/rpc";
3
- import type { RequirementRecord, RequirementsOf } from "@shivaedev/service/ServiceRequirements.ts";
4
3
  import type { Duplicated } from "#declarationError.ts";
5
4
  import type { OperationShape } from "#operation.ts";
6
5
  import type { Raised } from "#runProof.ts";
@@ -8,12 +7,6 @@ import type { SubjectDeclaration, SubjectProvides } from "#subject.ts";
8
7
  import type { WireEntry, WireEntryOf } from "#wire.ts";
9
8
  import type { RejectionsDiffer, SuccessDiffers } from "#wireProof.ts";
10
9
 
11
- export interface OperationNeedsUndeclaredServices<TOperation extends string, TMissing> {
12
- readonly missingServices: TMissing;
13
- readonly operation: TOperation;
14
- readonly problem: "run or readPolicy uses services that the module's requires and middleware do not provide";
15
- }
16
-
17
10
  type Regenerate = "the generated file is stale; run pnpm generate";
18
11
 
19
12
  export interface WireSuccessStale<TOperation extends string, TFix extends Regenerate, TRun, TWire> {
@@ -51,8 +44,6 @@ type Returns<TOperation> = TOperation extends { readonly run: infer TRun extends
51
44
  type Tags<E> = E extends { readonly _tag: infer TTag } ? TTag : E;
52
45
  type NameOf<TOperation> = TOperation extends { readonly name: infer TName extends string } ? TName : string;
53
46
 
54
- type Missing<TOperation, TAllowed> = Exclude<Effect.Services<Parts<TOperation>>, TAllowed | Scope.Scope>;
55
-
56
47
  type WireProblem<TOperation, TEntry extends WireEntry> = [SuccessDiffers<TEntry["success"], Returns<TOperation>>] extends [never]
57
48
  ? [RejectionsDiffer<TEntry["rejections"], Effect.Error<Parts<TOperation>>>] extends [never]
58
49
  ? never
@@ -65,28 +56,29 @@ type EntryProblem<TOperation> = [SuccessDiffers<Schema.Void, Returns<TOperation>
65
56
  ? never
66
57
  : OperationMissingFromWire<NameOf<TOperation>, Regenerate>;
67
58
 
68
- type OperationProblem<TOperation, TWire, TAllowed> = [Missing<TOperation, TAllowed>] extends [never]
69
- ? WireEntryOf<TWire, NameOf<TOperation>> extends infer TEntry extends WireEntry
70
- ? WireProblem<TOperation, TEntry>
71
- : EntryProblem<TOperation>
72
- : OperationNeedsUndeclaredServices<NameOf<TOperation>, Missing<TOperation, TAllowed>>;
59
+ type OperationProblem<TOperation, TWire> =
60
+ WireEntryOf<TWire, NameOf<TOperation>> extends infer TEntry extends WireEntry ? WireProblem<TOperation, TEntry> : EntryProblem<TOperation>;
73
61
 
74
62
  type SubjectServices<TSubject> = TSubject extends SubjectDeclaration ? SubjectProvides<TSubject> : never;
75
63
 
76
- export type Allowed<TRequirements extends RequirementRecord, TMiddleware extends RpcMiddleware.AnyService, TSubject> =
77
- | RequirementsOf<TRequirements>
78
- | RpcMiddleware.Provides<TMiddleware["Identifier"]>
79
- | SubjectServices<TSubject>;
64
+ export type ModuleServices = { readonly [TOperation in string]: unknown };
65
+
66
+ export type ModuleRequirements<TOperations extends readonly OperationShape[], TMiddleware extends RpcMiddleware.AnyService, TSubject> = {
67
+ readonly [TOperation in TOperations[number] as NameOf<TOperation>]: Exclude<
68
+ Effect.Services<Parts<TOperation>>,
69
+ RpcMiddleware.Provides<TMiddleware["Identifier"]> | SubjectServices<TSubject> | Scope.Scope
70
+ >;
71
+ };
80
72
 
81
- type Problems<TOperations extends readonly OperationShape[], TWire, TAllowed> =
82
- | { readonly [TIndex in keyof TOperations]: OperationProblem<TOperations[TIndex], TWire, TAllowed> }[number]
73
+ type Problems<TOperations extends readonly OperationShape[], TWire> =
74
+ | { readonly [TIndex in keyof TOperations]: OperationProblem<TOperations[TIndex], TWire> }[number]
83
75
  | (Duplicated<TOperations> extends infer TName extends string ? (TName extends string ? OperationNameRepeated<TName> : never) : never);
84
76
 
85
77
  // The proof sits on the module's name, so the first line of the compiler's message names the operation and its problem.
86
78
  // A definition without a wire leaves TWire at its constraint, whose index signature has every name; proving nothing then
87
79
  // lets the compiler's own error say that wire is missing.
88
- export type NameProof<TOperations extends readonly OperationShape[], TWire, TAllowed> = string extends keyof TWire
80
+ export type NameProof<TOperations extends readonly OperationShape[], TWire> = string extends keyof TWire
89
81
  ? unknown
90
- : [Problems<TOperations, TWire, TAllowed>] extends [never]
82
+ : [Problems<TOperations, TWire>] extends [never]
91
83
  ? unknown
92
- : Problems<TOperations, TWire, TAllowed>;
84
+ : Problems<TOperations, TWire>;
@@ -31,7 +31,13 @@ export function querySubscription<TRpc extends Rpc.Any>(
31
31
  >;
32
32
  export function querySubscription(rpc: Rpc.Any, references: readonly QueryReference[], viewer: Option.Option<Viewer>) {
33
33
  return Effect.fnUntraced(function* () {
34
- const queries = yield* Context.getUnsafe(rpc.annotations, ChangesQueries).resolve(references);
34
+ const changes = Context.getOption(rpc.annotations, ChangesQueries);
35
+ if (Option.isNone(changes)) {
36
+ return yield* Effect.die(
37
+ new Error(`${rpc._tag} carries no changes queries.\nhelp: Subscribe through the $changes RPC that changesRpc declares.`),
38
+ );
39
+ }
40
+ const queries = yield* changes.value.resolve(references);
35
41
  const prefix = rpc._tag.slice(0, -"$changes".length);
36
42
  const policies = yield* Effect.forEach(
37
43
  queries,
package/src/reflection.ts CHANGED
@@ -14,96 +14,98 @@ interface Wait {
14
14
  }
15
15
 
16
16
  // One per connection: every command and live stream that shares it folds into the same tokens.
17
- export const makeReflection = Effect.gen(function* () {
18
- const catchUps = yield* Queue.sliding<void>(1);
19
- const client = clientId();
20
- let issued = 0;
21
- const streams = new Set<FollowedStream>();
22
- const flights = new Map<number, Set<FollowedStream>>();
23
- const waits = new Set<Wait>();
17
+ // The record is mutable state that commands and streams drive synchronously, so building it is a side effect.
18
+ export const makeReflection = Effect.flatMap(Queue.sliding<void>(1), (catchUps) =>
19
+ Effect.sync(() => {
20
+ const client = clientId();
21
+ let issued = 0;
22
+ const streams = new Set<FollowedStream>();
23
+ const flights = new Map<number, Set<FollowedStream>>();
24
+ const waits = new Set<Wait>();
24
25
 
25
- // A stream armed after the command's token was issued may have registered behind it, so only a later token proves it caught up.
26
- function uncertain(wait: Wait, stream: FollowedStream) {
27
- return stream.armedAt !== undefined && (wait.own === undefined || stream.armedAt >= wait.own);
28
- }
29
- function release(covers: (wait: Wait, stream: FollowedStream) => boolean, stream?: FollowedStream) {
30
- for (const wait of [...waits]) {
31
- const covered = [...wait.streams].filter((waited) => (stream === undefined || waited === stream) && covers(wait, waited));
32
- for (const waited of covered) {
33
- wait.streams.delete(waited);
34
- }
35
- if (wait.streams.size === 0 && waits.delete(wait)) {
36
- wait.reflected();
37
- }
26
+ // A stream armed after the command's token was issued may have registered behind it, so only a later token proves it caught up.
27
+ function uncertain(wait: Wait, stream: FollowedStream) {
28
+ return stream.armedAt !== undefined && (wait.own === undefined || stream.armedAt >= wait.own);
38
29
  }
39
- }
40
- function token() {
41
- issued += 1;
42
- return issued;
43
- }
44
- function flight() {
45
- const own = token();
46
- flights.set(own, new Set());
47
- return own;
48
- }
49
- return {
50
- abandon: () => release(uncertain),
51
- accepted: (own: number | undefined, reflected: () => void) => {
52
- const confirmed = own === undefined ? undefined : flights.get(own);
53
- if (own !== undefined) {
54
- flights.delete(own);
55
- }
56
- const waited = [...streams].filter((stream) => stream.supported !== false && confirmed?.has(stream) !== true);
57
- if (waited.length === 0) {
58
- reflected();
59
- return;
60
- }
61
- const wait: Wait = { after: issued, own, reflected, streams: new Set(waited) };
62
- waits.add(wait);
63
- if (waited.some((stream) => uncertain(wait, stream))) {
64
- Queue.offerUnsafe(catchUps, undefined);
65
- }
66
- },
67
- armed: (stream: FollowedStream) => {
68
- stream.supported = true;
69
- stream.armedAt = issued;
70
- if ([...waits].some((wait) => wait.streams.has(stream))) {
71
- Queue.offerUnsafe(catchUps, undefined);
72
- }
73
- },
74
- catchUps,
75
- client,
76
- confirmed: (stream: FollowedStream, ids: readonly number[]) => {
77
- for (const id of ids) {
78
- flights.get(id)?.add(stream);
30
+ function release(covers: (wait: Wait, stream: FollowedStream) => boolean, stream?: FollowedStream) {
31
+ for (const wait of [...waits]) {
32
+ const covered = [...wait.streams].filter((waited) => (stream === undefined || waited === stream) && covers(wait, waited));
33
+ for (const waited of covered) {
34
+ wait.streams.delete(waited);
35
+ }
36
+ if (wait.streams.size === 0 && waits.delete(wait)) {
37
+ wait.reflected();
38
+ }
79
39
  }
80
- release((wait) => ids.some((id) => id === wait.own || id > wait.after), stream);
81
- },
82
- data: (stream: FollowedStream) => {
83
- if (stream.supported === undefined) {
84
- stream.supported = false;
40
+ }
41
+ function token() {
42
+ issued += 1;
43
+ return issued;
44
+ }
45
+ function flight() {
46
+ const own = token();
47
+ flights.set(own, new Set());
48
+ return own;
49
+ }
50
+ return {
51
+ abandon: () => release(uncertain),
52
+ accepted: (own: number | undefined, reflected: () => void) => {
53
+ const confirmed = own === undefined ? undefined : flights.get(own);
54
+ if (own !== undefined) {
55
+ flights.delete(own);
56
+ }
57
+ const waited = [...streams].filter((stream) => stream.supported !== false && confirmed?.has(stream) !== true);
58
+ if (waited.length === 0) {
59
+ reflected();
60
+ return;
61
+ }
62
+ const wait: Wait = { after: issued, own, reflected, streams: new Set(waited) };
63
+ waits.add(wait);
64
+ if (waited.some((stream) => uncertain(wait, stream))) {
65
+ Queue.offerUnsafe(catchUps, undefined);
66
+ }
67
+ },
68
+ armed: (stream: FollowedStream) => {
69
+ stream.supported = true;
70
+ stream.armedAt = issued;
71
+ if ([...waits].some((wait) => wait.streams.has(stream))) {
72
+ Queue.offerUnsafe(catchUps, undefined);
73
+ }
74
+ },
75
+ catchUps,
76
+ client,
77
+ confirmed: (stream: FollowedStream, ids: readonly number[]) => {
78
+ for (const id of ids) {
79
+ flights.get(id)?.add(stream);
80
+ }
81
+ release((wait) => ids.some((id) => id === wait.own || id > wait.after), stream);
82
+ },
83
+ data: (stream: FollowedStream) => {
84
+ if (stream.supported === undefined) {
85
+ stream.supported = false;
86
+ release(() => true, stream);
87
+ }
88
+ },
89
+ detach: (stream: FollowedStream) => {
90
+ streams.delete(stream);
85
91
  release(() => true, stream);
86
- }
87
- },
88
- detach: (stream: FollowedStream) => {
89
- streams.delete(stream);
90
- release(() => true, stream);
91
- },
92
- failed: (own: number | undefined) => {
93
- if (own !== undefined) {
94
- flights.delete(own);
95
- }
96
- },
97
- flight,
98
- opening: (stream: FollowedStream) => {
99
- stream.armedAt = undefined;
100
- stream.supported = undefined;
101
- streams.add(stream);
102
- },
103
- send: (piggyback: boolean) => (piggyback && [...streams].some((stream) => stream.supported !== false) ? flight() : undefined),
104
- token,
105
- };
106
- });
92
+ },
93
+ failed: (own: number | undefined) => {
94
+ if (own !== undefined) {
95
+ flights.delete(own);
96
+ }
97
+ },
98
+ flight,
99
+ opening: (stream: FollowedStream) => {
100
+ stream.armedAt = undefined;
101
+ stream.supported = undefined;
102
+ streams.add(stream);
103
+ },
104
+ send: (piggyback: boolean) => (piggyback && [...streams].some((stream) => stream.supported !== false) ? flight() : undefined),
105
+ token,
106
+ };
107
+ }),
108
+ );
107
109
 
108
110
  export type Reflection = Effect.Success<typeof makeReflection>;
109
111
 
package/src/runProof.ts CHANGED
@@ -3,12 +3,14 @@ import type { InfrastructureFailure } from "@shivaedev/errors/infrastructure.ts"
3
3
  import type { InternalServerError, ServiceUnavailable } from "@shivaedev/errors/taxonomy.ts";
4
4
  import type { QueryReadDenied } from "#readPolicyErrors.ts";
5
5
  import type { TaggedRejection } from "#rejection.ts";
6
+ import type { Answered } from "#staleWrite.ts";
6
7
 
7
8
  export type RunBody<TPayload, TYielded, A> = (payload: TPayload) => Generator<TYielded, A, never>;
8
9
 
9
10
  export type ErrorOf<TYielded> = [TYielded] extends [never] ? never : [TYielded] extends [Effect.Effect<unknown, infer E, unknown>] ? E : never;
10
11
  export type ServicesOf<TYielded> = [TYielded] extends [never] ? never : [TYielded] extends [Effect.Effect<unknown, unknown, infer R>] ? R : never;
11
- export type RunEffect<TYielded, A> = [A] extends [unknown] ? Effect.Effect<A, ErrorOf<TYielded>, ServicesOf<TYielded>> : never;
12
+ // Run answers a stale versioned write with Conflict, so its callers and its wire see that rejection.
13
+ export type RunEffect<TYielded, A> = [A] extends [unknown] ? Effect.Effect<A, Answered<ErrorOf<TYielded>>, ServicesOf<TYielded>> : never;
12
14
 
13
15
  export interface ClassRejections {
14
16
  readonly [tag: string]: TaggedRejection;
@@ -8,6 +8,7 @@ import type { QueryServerReads } from "#QueryServerReads.ts";
8
8
  import type { QueryReadPolicy, Viewer } from "#readPolicy.ts";
9
9
  import type { RejectionSpecs } from "#rejection.ts";
10
10
  import type { ErrorOf, RunBody, RunCheck, RunEffect, ServicesOf, SpecsOf } from "#runProof.ts";
11
+ import { answerStaleWrite } from "#staleWrite.ts";
11
12
 
12
13
  export interface ServedQuery<
13
14
  TName extends string,
@@ -141,5 +142,5 @@ export function invalidatesOf(declaration: LooseCommand): Invalidates {
141
142
  }
142
143
 
143
144
  export function runOf({ run }: { readonly run?: RunGenerator | undefined }) {
144
- return run === undefined ? {} : { run: Effect.fnUntraced(run) };
145
+ return run === undefined ? {} : { run: Effect.fnUntraced(run, answerStaleWrite) };
145
146
  }
@@ -62,7 +62,7 @@ const protocols = Atom.family(
62
62
  const clock = yield* SocketClock;
63
63
  let memo = socketMemoMaps.get(clock);
64
64
  if (memo === undefined) {
65
- memo = Layer.makeMemoMapUnsafe();
65
+ memo = yield* Layer.makeMemoMap;
66
66
  socketMemoMaps.set(clock, memo);
67
67
  }
68
68
  const protocol = managed.pipe(Layer.provide(Layer.succeed(Clock.Clock, clock)));
@@ -0,0 +1,23 @@
1
+ import { Effect, Predicate } from "effect";
2
+ import { Conflict } from "@shivaedev/errors/taxonomy.ts";
3
+
4
+ // The OptimisticConcurrencyError of @shivaedev/sql repositories, known by its tag as catchTag knows it, since this
5
+ // browser-safe package reaches no server package.
6
+ const STALE_WRITE = "OptimisticConcurrencyError";
7
+
8
+ export interface StaleWrite {
9
+ readonly _tag: typeof STALE_WRITE;
10
+ }
11
+
12
+ // A versioned write that lost its race means the caller acted on an old read, which the shared Conflict tells every client.
13
+ export type Answered<E> = E extends StaleWrite ? Conflict : E;
14
+
15
+ function staleConflict(cause: unknown) {
16
+ const rejection = new Conflict({ message: "This was changed or deleted since you loaded it. Refresh and try again." });
17
+ Object.defineProperty(rejection, "cause", { configurable: true, enumerable: false, value: cause });
18
+ return Effect.fail(rejection);
19
+ }
20
+
21
+ export function answerStaleWrite(effect: Effect.Effect<unknown, unknown, unknown>) {
22
+ return Effect.catchIf(effect, (error) => Predicate.isTagged(error, STALE_WRITE), staleConflict);
23
+ }