@workerstack/clients 1.0.0-rc.30 → 1.0.0-rc.31

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 (115) hide show
  1. package/README.md +175 -21
  2. package/bin/clients.js +5 -6
  3. package/bin/installgen.js +5 -9
  4. package/dist/cli.js +3 -1
  5. package/dist/emit/csharp/sdk-method.d.ts +18 -1
  6. package/dist/emit/csharp/sdk-method.js +14 -3
  7. package/dist/emit/csharp/sdk.js +4 -1
  8. package/dist/emit/go/sdk-method.d.ts +9 -0
  9. package/dist/emit/go/sdk-method.js +10 -1
  10. package/dist/emit/go/sdk.js +4 -3
  11. package/dist/emit/java/sdk-client.js +1 -0
  12. package/dist/emit/java/sdk-op.d.ts +6 -1
  13. package/dist/emit/java/sdk-op.js +15 -3
  14. package/dist/emit/java/sdk.js +7 -1
  15. package/dist/emit/python/sdk-method.d.ts +11 -0
  16. package/dist/emit/python/sdk-method.js +15 -0
  17. package/dist/emit/python/sdk.js +5 -1
  18. package/dist/emit/rust/sdk-method.d.ts +12 -1
  19. package/dist/emit/rust/sdk-method.js +10 -2
  20. package/dist/emit/rust/sdk.js +4 -1
  21. package/dist/emit/ts/http.d.ts +8 -0
  22. package/dist/emit/ts/http.js +48 -3
  23. package/dist/emit/ts/package.js +1 -0
  24. package/dist/emit/ts/sdk-types-preamble.js +10 -2
  25. package/dist/emit/ts/sdk-types.d.ts +0 -5
  26. package/dist/emit/ts/sdk-types.js +52 -8
  27. package/dist/emit/ts/sdk.d.ts +3 -1
  28. package/dist/emit/ts/sdk.js +40 -8
  29. package/dist/emit/ts/service-map.d.ts +5 -0
  30. package/dist/emit/ts/service-map.js +10 -1
  31. package/dist/emit/ts/single-flight-text.d.ts +3 -0
  32. package/dist/emit/ts/single-flight-text.js +38 -0
  33. package/dist/emit/ts/tanstack-query.d.ts +3 -2
  34. package/dist/emit/ts/tanstack-query.js +54 -29
  35. package/dist/gen/process.js +2 -1
  36. package/dist/gen/switch-on.constants.d.ts +2 -0
  37. package/dist/gen/switch-on.constants.js +2 -0
  38. package/dist/gen/targets.d.ts +4 -3
  39. package/dist/gen/targets.js +4 -3
  40. package/dist/ir/invalidate-reads.d.ts +17 -0
  41. package/dist/ir/invalidate-reads.js +104 -0
  42. package/dist/ir/load.d.ts +10 -0
  43. package/dist/ir/load.js +62 -14
  44. package/dist/ir/read-method.constants.d.ts +2 -0
  45. package/dist/ir/read-method.constants.js +2 -0
  46. package/dist/release/load.js +1 -1
  47. package/dist/runtime/csharp/Config.cs +9 -1
  48. package/dist/runtime/csharp/Exchange.cs +56 -4
  49. package/dist/runtime/csharp/Hooks.cs +9 -0
  50. package/dist/runtime/csharp/Operation.cs +6 -1
  51. package/dist/runtime/csharp/WsDial.cs +3 -1
  52. package/dist/runtime/go/config.go +5 -0
  53. package/dist/runtime/go/hooks.go +70 -0
  54. package/dist/runtime/go/request.go +6 -2
  55. package/dist/runtime/go/stream.go +4 -1
  56. package/dist/runtime/go/ws.go +3 -1
  57. package/dist/runtime/java/ClientConfig.java +11 -0
  58. package/dist/runtime/java/Flight.java +2 -12
  59. package/dist/runtime/java/Hooks.java +45 -0
  60. package/dist/runtime/java/InvalidateEvent.java +10 -0
  61. package/dist/runtime/java/InvalidateHook.java +12 -0
  62. package/dist/runtime/java/InvalidateTarget.java +7 -0
  63. package/dist/runtime/java/Operation.java +23 -3
  64. package/dist/runtime/java/Realtime.java +3 -1
  65. package/dist/runtime/java/WsDial.java +3 -0
  66. package/dist/runtime/python/config.py +8 -2
  67. package/dist/runtime/python/exchange.py +3 -1
  68. package/dist/runtime/python/hooks.py +110 -5
  69. package/dist/runtime/python/operation.py +2 -0
  70. package/dist/runtime/python/send_async.py +14 -2
  71. package/dist/runtime/python/send_sync.py +4 -2
  72. package/dist/runtime/python/ws.py +5 -1
  73. package/dist/runtime/rust/config.rs +6 -1
  74. package/dist/runtime/rust/exchange.rs +15 -3
  75. package/dist/runtime/rust/hooks.rs +127 -2
  76. package/dist/runtime/rust/log.rs +11 -3
  77. package/dist/runtime/rust/request.rs +17 -0
  78. package/dist/runtime/rust/ws.rs +9 -1
  79. package/dist/runtime/ts/config.ts +69 -0
  80. package/dist/runtime/ts/http.ts +12 -10
  81. package/dist/runtime/ts/request.ts +2 -0
  82. package/dist/runtime/ts/response.ts +7 -0
  83. package/dist/runtime/ts/sdk-invalidate.ts +82 -0
  84. package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
  85. package/dist/runtime/ts/sdk-single-flight.ts +203 -0
  86. package/dist/runtime/ts/sdk-sse.ts +5 -1
  87. package/dist/runtime/ts/sdk-ws.ts +9 -3
  88. package/dist/runtime/ts/sdk.ts +55 -31
  89. package/dist/runtime/ts/single-flight-batch.ts +184 -0
  90. package/dist/runtime/ts/single-flight-body.ts +59 -0
  91. package/dist/runtime/ts/single-flight-run.ts +160 -0
  92. package/dist/runtime/ts/single-flight.constants.ts +31 -0
  93. package/dist/runtime/ts/single-flight.ts +158 -0
  94. package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
  95. package/dist/runtime/ts-tanstack-query/query.ts +140 -168
  96. package/package.json +10 -18
  97. package/references/INDEX.md +31 -0
  98. package/references/cli.md +33 -0
  99. package/references/configuring.md +29 -0
  100. package/references/documentation.md +15 -0
  101. package/references/errors.md +23 -0
  102. package/references/flags.md +104 -0
  103. package/references/gates.md +46 -0
  104. package/references/generate.md +29 -0
  105. package/references/install-scripts.md +28 -0
  106. package/references/install.md +38 -0
  107. package/references/license.md +8 -0
  108. package/references/mcp.md +76 -0
  109. package/references/output.md +45 -0
  110. package/references/overview.md +14 -0
  111. package/references/release-tooling.md +34 -0
  112. package/references/release.md +305 -0
  113. package/references/sdks.md +393 -0
  114. package/references/start.md +22 -0
  115. package/references/tdd.md +16 -0
@@ -0,0 +1,203 @@
1
+ import type { FreshReads, SingleFlightBatch, SingleFlightConfig } from "./config.ts"
2
+ import { ClientError, DecodeError } from "./error.ts"
3
+ import { AUTH_TOKEN, type HTTPClient, REFRESH_AUTH } from "./http.ts"
4
+ import { isJsonMediaType, parseMediaType } from "./media-type.ts"
5
+ import { requestSignal } from "./request.ts"
6
+ import type { Sent } from "./response.ts"
7
+ import { targetsOf } from "./sdk-invalidate.ts"
8
+ import {
9
+ BATCH_VERSION,
10
+ DEFAULT_FLIGHT_PATH,
11
+ DEFAULT_MAX_READS,
12
+ MAX_WRITE_STATUS,
13
+ MIN_WRITE_STATUS,
14
+ NO_BODY_STATUSES,
15
+ REFUSED,
16
+ REFUSED_STATUS,
17
+ UNAUTHORIZED_STATUS,
18
+ WRITE_METHODS,
19
+ } from "./sdk-single-flight.constants.ts"
20
+ import type { CallInput, ServiceEntry } from "./sdk.ts"
21
+
22
+ /** The input a call keeps to itself: a write sent with any goes direct. */
23
+ const DIRECT_KEYS = ["baseURL", "body", "cookies", "form", "headers"] as const
24
+
25
+ /** One eligible write: its config and the batch it sends. */
26
+ export type Flight = { batch: SingleFlightBatch; config: SingleFlightConfig }
27
+
28
+ /** The client a write is sent by: its single-flight config, its HTTP client and its dispose signal. */
29
+ export type FlightClient = { config: SingleFlightConfig | undefined; disposal: AbortSignal; http: HTTPClient }
30
+
31
+ /** One eligible write as it is sent: the client, the batch and the call's input. */
32
+ type FlightCall = { disposal: AbortSignal; flight: Flight; http: HTTPClient; input: CallInput }
33
+
34
+ /** What a batch brought back: the write's answer, rebuilt, and the reads, by id. */
35
+ export type Flown = { fresh: FreshReads; sent: Sent }
36
+
37
+ /** Whether `entry` never goes in a batch under `config`: no REST JSON write with reads, or one it excludes. */
38
+ function isDirectEntry(config: SingleFlightConfig, entry: ServiceEntry): boolean {
39
+ if (!WRITE_METHODS.includes(entry.method) || entry.accept !== undefined || entry.call !== undefined) return true
40
+ return entry.empty === true || config.exclude?.includes(entry.id) === true || (entry.reads?.length ?? 0) === 0
41
+ }
42
+
43
+ /** Whether a call with `input` goes direct: it opts out, wants the raw answer, or sets what a batch cannot carry. */
44
+ function isDirectInput(input: CallInput): boolean {
45
+ if (input.singleFlight === false || input.raw === true) return true
46
+ return DIRECT_KEYS.some((key) => input[key] !== undefined)
47
+ }
48
+
49
+ /** The write's input as a batch carries it: only what the handler takes, an idempotent write's key included. */
50
+ function batchInput(entry: ServiceEntry, input: CallInput): SingleFlightBatch["input"] {
51
+ const out: SingleFlightBatch["input"] = {}
52
+ if (input.params !== undefined) out.params = input.params
53
+ if (input.search !== undefined) out.search = input.search
54
+ if (input.json !== undefined) out.json = input.json
55
+ if (entry.idempotent === true && input.idempotencyKey !== undefined) out.idempotencyKey = input.idempotencyKey
56
+ return out
57
+ }
58
+
59
+ /** The batch `entry` called with `input` sends under `config`, or none when it goes direct. */
60
+ function flightOf(config: SingleFlightConfig | undefined, entry: ServiceEntry, input: CallInput): Flight | undefined {
61
+ if (config === undefined || isDirectEntry(config, entry) || isDirectInput(input)) return undefined
62
+ const picked = config.select(targetsOf(entry.reads ?? [], input.params))
63
+ const reads = picked.slice(0, Math.max(config.maxReads ?? DEFAULT_MAX_READS, 0))
64
+ if (reads.length === 0) return undefined
65
+ return { batch: { input: batchInput(entry, input), op: entry.id, reads, v: BATCH_VERSION }, config }
66
+ }
67
+
68
+ /** Whether `value` is an object whose keys can be read. */
69
+ function isObject(value: unknown): value is object {
70
+ return typeof value === "object" && value !== null && !Array.isArray(value)
71
+ }
72
+
73
+ /** Whether `value` is text. */
74
+ function isString(value: unknown): value is string {
75
+ return typeof value === "string"
76
+ }
77
+
78
+ /** Whether `body` is a handler's refusal problem. */
79
+ function isRefusal(body: unknown): body is { type: typeof REFUSED } {
80
+ return isObject(body) && "type" in body && body.type === REFUSED
81
+ }
82
+
83
+ /** `promise`, or the abort of `signal` first. */
84
+ function raced<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
85
+ if (signal === undefined) return promise
86
+ return new Promise<T>((resolve, reject) => {
87
+ function onAbort(): void {
88
+ reject(signal?.reason)
89
+ }
90
+ signal.addEventListener("abort", onAbort, { once: true })
91
+ promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort))
92
+ })
93
+ }
94
+
95
+ /** What `send` resolves: what the batch got back, a stand-in Response its read errors carry. */
96
+ async function sentBy(send: NonNullable<SingleFlightConfig["send"]>, call: FlightCall) {
97
+ const { done, signal } = requestSignal([call.input.signal, call.disposal], call.input.timeout)
98
+ try {
99
+ signal?.throwIfAborted()
100
+ return { response: new Response(null), value: await raced(send(call.flight.batch), signal) }
101
+ } finally {
102
+ done()
103
+ }
104
+ }
105
+
106
+ /** What one sending of the batch got back, and its response; undefined for a refusal. */
107
+ async function sendOnce(call: FlightCall) {
108
+ const { config, batch } = call.flight
109
+ if (config.send !== undefined) return sentBy(config.send, call)
110
+ const opts = { json: batch, signal: call.input.signal, timeout: call.input.timeout }
111
+ try {
112
+ const answer = await call.http.requestOperation({ method: "POST", opts, path: config.path ?? DEFAULT_FLIGHT_PATH })
113
+ return { response: answer.response, value: answer.data }
114
+ } catch (e) {
115
+ if (e instanceof ClientError && e.status === REFUSED_STATUS && isRefusal(e.body)) return undefined
116
+ throw e
117
+ }
118
+ }
119
+
120
+ /** The write's answer of an envelope. */
121
+ type EnvelopeWrite = { body: unknown; headers: Readonly<Record<string, string>>; status: number }
122
+
123
+ /** An envelope as the client reads it: the write's answer and each read's entry, still unread. */
124
+ type Envelope = { reads: readonly unknown[]; write: EnvelopeWrite }
125
+
126
+ /** One read's entry that came back with data. */
127
+ type AnsweredRead = { data: unknown; id: string }
128
+
129
+ /** Whether `value` is the write's answer: a status 200 to 599, headers of strings, and a body. */
130
+ function isWrite(value: unknown): value is EnvelopeWrite {
131
+ if (!isObject(value) || !("body" in value) || !("headers" in value) || !("status" in value)) return false
132
+ const { headers, status } = value
133
+ if (typeof status !== "number" || !Number.isInteger(status)) return false
134
+ if (status < MIN_WRITE_STATUS || status > MAX_WRITE_STATUS) return false
135
+ return isObject(headers) && Object.values(headers).every(isString)
136
+ }
137
+
138
+ /** Whether `value` is an envelope of the one batch version. */
139
+ function isEnvelope(value: unknown): value is Envelope {
140
+ if (!isObject(value) || !("v" in value) || !("write" in value) || !("reads" in value)) return false
141
+ return value.v === BATCH_VERSION && isWrite(value.write) && Array.isArray(value.reads)
142
+ }
143
+
144
+ /** Whether `value` is a read's entry that came back with data. */
145
+ function isAnswered(value: unknown): value is AnsweredRead {
146
+ return isObject(value) && "data" in value && "id" in value && isString(value.id)
147
+ }
148
+
149
+ /** What came back as an envelope; a DecodeError, carrying `response`, when it is none. */
150
+ function envelopeOf(got: { response: Response; value: unknown }): Envelope {
151
+ if (isEnvelope(got.value)) return got.value
152
+ const { response } = got
153
+ const message = "Single-flight answer is no version 1 envelope"
154
+ throw new DecodeError({ body: null, message, response, status: response.status })
155
+ }
156
+
157
+ /** The reads `flight` asked for that `envelope` brought back by id, and those it did not. */
158
+ function freshOf(envelope: Envelope, flight: Flight): FreshReads {
159
+ const data = new Map<string, unknown>()
160
+ for (const read of envelope.reads) if (isAnswered(read)) data.set(read.id, read.data)
161
+ const failed = new Set(flight.batch.reads.map((read) => read.id).filter((id) => !data.has(id)))
162
+ return { data, failed }
163
+ }
164
+
165
+ /** The write's answer as the Response a direct call would have read. */
166
+ function responseOf(write: EnvelopeWrite): Response {
167
+ const isJson = isJsonMediaType(parseMediaType(write.headers["content-type"]))
168
+ let body: string | null = null
169
+ if (!NO_BODY_STATUSES.includes(write.status) && write.body !== null)
170
+ body = isString(write.body) && !isJson ? write.body : JSON.stringify(write.body)
171
+ return new Response(body, { headers: write.headers, status: write.status })
172
+ }
173
+
174
+ /** What a batch brought back, the write's answer as a Sent with nothing to release. */
175
+ function flownOf(envelope: Envelope, flight: Flight): Flown {
176
+ const response = responseOf(envelope.write)
177
+ const sent = {
178
+ done: () => undefined,
179
+ exemptFromTimeout: () => undefined,
180
+ failed: (cause: unknown) => cause,
181
+ response,
182
+ }
183
+ return { fresh: freshOf(envelope, flight), sent }
184
+ }
185
+
186
+ /**
187
+ * Send `entry` called with `input` in a single-flight batch when it is eligible, and read its envelope: the write's
188
+ * answer and the reads brought back. Undefined when the call goes direct, or the handler refused the batch. A write's
189
+ * 401 refreshes the token once, as a direct call's does, and sends the batch again.
190
+ */
191
+ export async function fly(client: FlightClient, entry: ServiceEntry, input: CallInput): Promise<Flown | undefined> {
192
+ const flight = flightOf(client.config, entry, input)
193
+ if (flight === undefined) return undefined
194
+ const call = { disposal: client.disposal, flight, http: client.http, input }
195
+ const token = client.http[AUTH_TOKEN]
196
+ const got = await sendOnce(call)
197
+ if (got === undefined) return undefined
198
+ const envelope = envelopeOf(got)
199
+ if (envelope.write.status !== UNAUTHORIZED_STATUS || !(await client.http[REFRESH_AUTH](token)))
200
+ return flownOf(envelope, flight)
201
+ const again = await sendOnce(call)
202
+ return again === undefined ? undefined : flownOf(envelopeOf(again), flight)
203
+ }
@@ -43,7 +43,10 @@ function mapEvents(
43
43
  }
44
44
  }
45
45
 
46
- /** An SSE op opened: its stale view for the hooks, and its `x-invalidate` targets marked once the answer is ok. */
46
+ /**
47
+ * An SSE op opened: its stale view for the hooks, and its `x-invalidate` targets marked once the answer is ok, when
48
+ * the `onInvalidate` hooks are called detached: the open is sync, so nothing waits on them.
49
+ */
47
50
  async function open(core: SdkCore, entry: ServiceEntry, input: RequestOptions): Promise<Answer> {
48
51
  const opts = optionsFor(entry, input)
49
52
  const template = templateOf(entry)
@@ -58,6 +61,7 @@ async function open(core: SdkCore, entry: ServiceEntry, input: RequestOptions):
58
61
  }
59
62
  const onOpen = () => {
60
63
  if (selector !== undefined) core.mark(entry, input.params, selector)
64
+ void core.invalidated(entry, input.params)
61
65
  }
62
66
  const { data, response } = await openStream(core.http, { meta, method: entry.method, onOpen, opts, path: template })
63
67
  return { data: eventsOf(data, entry.sse), response }
@@ -6,7 +6,10 @@ import { createTypedWebSocket, type TypedWebSocket, wsUrl } from "./ws.ts"
6
6
  /** A WebSocket call's input: the request's options, the subprotocols, and a resume token. */
7
7
  type WsInput = RequestOptions & { protocols?: string | string[]; reconnectToken?: string }
8
8
 
9
- /** A WebSocket op: one socket per call, its `x-invalidate` targets marked once it opens. */
9
+ /**
10
+ * A WebSocket op: one socket per call, its `x-invalidate` targets marked once it opens, when the `onInvalidate` hooks
11
+ * are called detached: the `open` listener is sync, so nothing waits on them.
12
+ */
10
13
  export const wsOp: OperationCall =
11
14
  (core, entry) =>
12
15
  (input: WsInput = {}): TypedWebSocket => {
@@ -14,9 +17,12 @@ export const wsOp: OperationCall =
14
17
  if (input.reconnectToken) url.searchParams.append("reconnect_token", input.reconnectToken)
15
18
  const { decode, dispatch, encode } = entry
16
19
  const socket = createTypedWebSocket(url.toString(), { decode, dispatch, encode, protocols: input.protocols })
17
- if (entry.invalidate?.length) {
20
+ if (entry.reads?.length) {
18
21
  const selector = `WS ${interpolatePath(templateOf(entry), input.params)}`
19
- socket.on("open", () => core.mark(entry, input.params, selector))
22
+ socket.on("open", () => {
23
+ core.mark(entry, input.params, selector)
24
+ void core.invalidated(entry, input.params)
25
+ })
20
26
  }
21
27
  return socket
22
28
  }
@@ -1,9 +1,11 @@
1
- import type { ClientConfig, RequestMeta } from "./config.ts"
1
+ import type { ClientConfig, FreshReads, RequestMeta, SingleFlightConfig } from "./config.ts"
2
2
  import { ClientError, DecodeError } from "./error.ts"
3
3
  import { HTTPClient } from "./http.ts"
4
4
  import { interpolatePath, PathParamError } from "./path.ts"
5
5
  import { newClientRequestId, type RequestOptions } from "./request.ts"
6
- import { type Answer, resultOf } from "./response.ts"
6
+ import { type Answer, finishRequest, resultOf } from "./response.ts"
7
+ import { runInvalidateHooks, type ServiceRead } from "./sdk-invalidate.ts"
8
+ import { fly } from "./sdk-single-flight.ts"
7
9
  import { resolveInvalidationTargets, StaleIndex } from "./stale.ts"
8
10
 
9
11
  /** One operation as the service map holds it: where it goes and how its answer is read. */
@@ -14,12 +16,16 @@ export type ServiceEntry = {
14
16
  empty?: boolean
15
17
  /** the declared response headers, lower case (A2) */
16
18
  headers?: readonly string[]
19
+ /** the operationId: what `onInvalidate` names a write by, whatever member path it is renamed to */
20
+ id: string
17
21
  idempotent?: boolean
18
22
  invalidate?: readonly string[]
19
23
  method: string
20
24
  params?: readonly string[]
21
25
  /** the OpenAPI path template, `{param}` kept */
22
26
  path: string
27
+ /** the reads a successful call makes stale, resolved from `invalidate` at generation */
28
+ reads?: readonly ServiceRead[]
23
29
  realtime?: boolean
24
30
  /** an event stream; `"json"` when its events carry JSON `data` the client parses, or the names of the events that
25
31
  do when the operation names its events (an unnamed one is `message`) */
@@ -50,7 +56,11 @@ export type InvalidationConfig = {
50
56
  staleTime: number
51
57
  }
52
58
 
53
- export type SDKConfig = ClientConfig & { invalidation?: InvalidationConfig }
59
+ export type SDKConfig = ClientConfig & {
60
+ invalidation?: InvalidationConfig
61
+ /** send eligible writes to a single-flight handler with the reads they make stale; see `SingleFlightConfig` */
62
+ singleFlight?: SingleFlightConfig
63
+ }
54
64
 
55
65
  /** What a REST call takes; a stream, WebSocket or realtime operation's own call types its input further. */
56
66
  export type CallInput = RequestOptions
@@ -75,14 +85,15 @@ export function templateOf(entry: ServiceEntry): string {
75
85
  return entry.wildcard === undefined ? entry.path : entry.path.replace(`{${entry.wildcard}}`, `*${entry.wildcard}`)
76
86
  }
77
87
 
78
- /** A call whose path params cannot form a path, as a status-0 ClientError: no request was sent. */
79
- function pathError(e: PathParamError, entry: ServiceEntry): ClientError {
80
- return new ClientError({
81
- body: null,
82
- message: `${e.message} for ${entry.method} ${entry.path}`,
83
- response: Response.error(),
84
- status: 0,
85
- })
88
+ /** `template` filled with `params`; params that cannot form a path throw a status-0 ClientError, no request sent. */
89
+ function pathOf(entry: ServiceEntry, template: string, params: CallInput["params"]): string {
90
+ try {
91
+ return interpolatePath(template, params)
92
+ } catch (e) {
93
+ if (!(e instanceof PathParamError)) throw e
94
+ const message = `${e.message} for ${entry.method} ${entry.path}`
95
+ throw new ClientError({ body: null, message, response: Response.error(), status: 0 })
96
+ }
86
97
  }
87
98
 
88
99
  /** The per-call options an entry adds: its `Accept` and an `Idempotency-Key`. */
@@ -109,13 +120,6 @@ export class SdkCore {
109
120
  this.#stale = this.#newIndex()
110
121
  }
111
122
 
112
- #newIndex(): StaleIndex | null {
113
- const invalidation = this.#config.invalidation
114
- if (!invalidation || invalidation.staleTime <= 0) return null
115
- const maxSources = Math.max(invalidation.maxSourcesPerTarget ?? 16, 1)
116
- return new StaleIndex({ maxEntries: invalidation.staleMaxEntries ?? 1000, maxSources })
117
- }
118
-
119
123
  dispose(): void {
120
124
  this.#disposal.abort(new Error("The client was disposed"))
121
125
  this.#stale = this.#newIndex()
@@ -136,33 +140,53 @@ export class SdkCore {
136
140
  for (const target of resolveInvalidationTargets(entry.invalidate, params)) this.#stale.mark(target, selector, at)
137
141
  }
138
142
 
139
- /** A REST op's answer, its `x-invalidate` targets marked and its stale mark cleared once it is a 2xx. */
140
- async request(entry: ServiceEntry, input: CallInput): Promise<Answer> {
143
+ /** Tell the `onInvalidate` hooks what the successful call `entry` with `params` made stale; it never rejects. */
144
+ invalidated(entry: ServiceEntry, params: RequestOptions["params"], fresh?: FreshReads): Promise<void> {
145
+ const operation = `${entry.method} ${entry.path}`
146
+ return runInvalidateHooks(this.#config, { by: entry.id, fresh, operation, params, reads: entry.reads })
147
+ }
148
+
149
+ /**
150
+ * A REST op's answer, its `x-invalidate` targets marked and its stale mark cleared once it is a 2xx; it resolves
151
+ * after the `onInvalidate` hooks settle. An eligible write goes in a single-flight batch, its key made first so a
152
+ * refused batch's direct resend carries the same one.
153
+ */
154
+ async request(entry: ServiceEntry, call: CallInput): Promise<Answer> {
155
+ const key = entry.idempotent === true ? { idempotencyKey: call.idempotencyKey ?? newClientRequestId() } : {}
156
+ const input = { ...call, ...key }
141
157
  const template = templateOf(entry)
142
- let path: string
143
- try {
144
- path = interpolatePath(template, input.params)
145
- } catch (e) {
146
- throw e instanceof PathParamError ? pathError(e, entry) : e
147
- }
158
+ const path = pathOf(entry, template, input.params)
148
159
  const selector = `${entry.method} ${path}`
149
160
  const meta = this.meta(selector, path, entry.method)
150
- const opts = optionsFor(entry, input)
151
- const declared = entry.empty ? null : entry.accept
161
+ const reading = { declared: entry.empty === true ? null : entry.accept, limits: this.#config, method: entry.method }
162
+ let fresh: FreshReads | undefined
152
163
  const settle = () => {
153
164
  this.mark(entry, input.params, selector)
154
165
  if (meta?.isStale) this.#stale?.clear(selector, path, entry.method, meta.seqSnapshot)
166
+ return this.invalidated(entry, input.params, fresh)
155
167
  }
156
168
  try {
157
- const answer = await this.http.requestOperation({ declared, meta, method: entry.method, opts, path: template })
158
- settle()
169
+ const client = { config: this.#config.singleFlight, disposal: this.#disposal.signal, http: this.http }
170
+ const flown = await fly(client, entry, input)
171
+ fresh = flown?.fresh
172
+ const op = { ...reading, meta, opts: optionsFor(entry, input), path: template }
173
+ const answer =
174
+ flown === undefined ? await this.http.requestOperation(op) : await finishRequest(flown.sent, reading)
175
+ await settle()
159
176
  return answer
160
177
  } catch (e) {
161
178
  /* a 2xx whose body does not decode still changed what it invalidates */
162
- if (e instanceof DecodeError) settle()
179
+ if (e instanceof DecodeError) await settle()
163
180
  throw e
164
181
  }
165
182
  }
183
+
184
+ #newIndex(): StaleIndex | null {
185
+ const invalidation = this.#config.invalidation
186
+ if (!invalidation || invalidation.staleTime <= 0) return null
187
+ const maxSources = Math.max(invalidation.maxSourcesPerTarget ?? 16, 1)
188
+ return new StaleIndex({ maxEntries: invalidation.staleMaxEntries ?? 1000, maxSources })
189
+ }
166
190
  }
167
191
 
168
192
  /** The function an entry is called through, named by its member path; a safe one's REST answer a Result. */
@@ -0,0 +1,184 @@
1
+ import type { CallInput, ServiceEntry, ServiceMap, ServiceMapNode } from "./sdk.ts"
2
+ import { BATCH_VERSION, WRITE_METHODS } from "./sdk-single-flight.constants.ts"
3
+ import { READ_METHOD } from "./single-flight.constants.ts"
4
+
5
+ /** A JSON value, as a parsed body holds it. */
6
+ export type Json = null | boolean | number | string | readonly Json[] | JsonObject
7
+
8
+ /** A JSON object, as a parsed body holds it. */
9
+ export type JsonObject = { readonly [key: string]: Json }
10
+
11
+ /** One operation of the service map: its entry, and the member path the SDK calls it by. */
12
+ export type FlightOp = { entry: ServiceEntry; path: readonly string[] }
13
+
14
+ /** One read a batch asks for: the caller's name for it, its operation and its input. */
15
+ export type FlightRead = { id: string; input: CallInput; op: FlightOp }
16
+
17
+ /** A batch the service map allows: the write and its input, then the reads. */
18
+ export type FlightBatch = { input: CallInput; reads: readonly FlightRead[]; write: FlightOp }
19
+
20
+ /** What `parseBatch` answers: the batch, or why it was refused. */
21
+ export type ParsedBatch = { batch: FlightBatch } | { refused: string }
22
+
23
+ /** The input keys a write may carry; a read carries only params and search. */
24
+ type InputKey = "idempotencyKey" | "json" | "params" | "search"
25
+ const WRITE_KEYS: readonly InputKey[] = ["idempotencyKey", "json", "params", "search"]
26
+ const READ_KEYS: readonly InputKey[] = ["params", "search"]
27
+
28
+ /** Whether `node` is an operation, not a namespace of them. */
29
+ function isEntry(node: ServiceMapNode): node is ServiceEntry {
30
+ return Object.hasOwn(node, "method") && typeof node["method"] === "string"
31
+ }
32
+
33
+ /** Every operation of `map` by its operationId. */
34
+ export function operationsOf(map: ServiceMap): ReadonlyMap<string, FlightOp> {
35
+ const out = new Map<string, FlightOp>()
36
+ function walk(node: ServiceMapNode, path: readonly string[]): void {
37
+ if (isEntry(node)) out.set(node.id, { entry: node, path })
38
+ else for (const [key, child] of Object.entries(node)) walk(child, [...path, key])
39
+ }
40
+ walk(map, [])
41
+ return out
42
+ }
43
+
44
+ /** Whether `value` is a JSON object, not an array or null. */
45
+ function isObject(value: Json | undefined): value is JsonObject {
46
+ return typeof value === "object" && value !== null && !Array.isArray(value)
47
+ }
48
+
49
+ /** Whether `value` is a string. */
50
+ function isString(value: Json | undefined): value is string {
51
+ return typeof value === "string"
52
+ }
53
+
54
+ /** Whether `value` is what a path param may be: a string, or a finite number. */
55
+ function isParam(value: Json): value is number | string {
56
+ return isString(value) || (typeof value === "number" && Number.isFinite(value))
57
+ }
58
+
59
+ /** Whether `value` is a JSON scalar: no array or object. */
60
+ function isScalar(value: Json): value is boolean | null | number | string {
61
+ return value === null || typeof value !== "object"
62
+ }
63
+
64
+ /** Whether `value` is a JSON array. */
65
+ function isList(value: Json): value is readonly Json[] {
66
+ return Array.isArray(value)
67
+ }
68
+
69
+ /** Whether `value` is what a query param may be: a scalar, or a list of them. */
70
+ function isSearchValue(value: Json): boolean {
71
+ return isList(value) ? value.every(isScalar) : isScalar(value)
72
+ }
73
+
74
+ /** Whether `entry` is a plain REST call: no event stream, socket or realtime adapter. */
75
+ function isRest(entry: ServiceEntry): boolean {
76
+ return (
77
+ entry.call === undefined &&
78
+ [entry.sse, entry.ws, entry.realtime].every((flag) => flag === undefined || flag === false)
79
+ )
80
+ }
81
+
82
+ /** Whether `key` is one of `keys`. */
83
+ function isInputKey(key: string, keys: readonly InputKey[]): key is InputKey {
84
+ return keys.some((allowed) => allowed === key)
85
+ }
86
+
87
+ /** Refuse the batch: `parseBatch` turns this into its answer. */
88
+ function refuse(why: string): never {
89
+ throw new RangeError(why)
90
+ }
91
+
92
+ /** `value`'s path params, each one `entry` declares and a string or a number. */
93
+ function paramsOf(entry: ServiceEntry, value: Json): CallInput["params"] {
94
+ if (!isObject(value)) return refuse("params is not an object")
95
+ const declared = entry.params ?? []
96
+ for (const [key, param] of Object.entries(value)) {
97
+ if (!declared.includes(key)) refuse(`${entry.id} declares no param ${key}`)
98
+ if (!isParam(param)) refuse(`param ${key} is not a string or a number`)
99
+ }
100
+ return value /* interpolatePath writes a number as its digits, as a generated number param */ as CallInput["params"]
101
+ }
102
+
103
+ /** One input key's field put on `input`, once it is what `entry` takes there. */
104
+ type Field = (input: CallInput, field: Json, entry: ServiceEntry) => void
105
+
106
+ function setIdempotencyKey(input: CallInput, field: Json, entry: ServiceEntry): void {
107
+ if (!isString(field) || entry.idempotent !== true) refuse(`${entry.id} takes no idempotencyKey`)
108
+ input.idempotencyKey = field
109
+ }
110
+
111
+ function setJson(input: CallInput, field: Json): void {
112
+ input.json = field
113
+ }
114
+
115
+ function setParams(input: CallInput, field: Json, entry: ServiceEntry): void {
116
+ input.params = paramsOf(entry, field)
117
+ }
118
+
119
+ function setSearch(input: CallInput, field: Json): void {
120
+ if (!isObject(field) || !Object.values(field).every(isSearchValue)) refuse("search is not an object of scalars")
121
+ input.search = field
122
+ }
123
+
124
+ const FIELDS = {
125
+ idempotencyKey: setIdempotencyKey,
126
+ json: setJson,
127
+ params: setParams,
128
+ search: setSearch,
129
+ } satisfies { readonly [K in InputKey]: Field }
130
+
131
+ /** `value` as the input `entry` is called with, holding only `keys`. */
132
+ function inputOf(entry: ServiceEntry, value: Json | undefined, keys: readonly InputKey[]): CallInput {
133
+ if (value === undefined) return {}
134
+ if (!isObject(value)) return refuse("input is not an object")
135
+ const input: CallInput = {}
136
+ for (const [key, field] of Object.entries(value)) {
137
+ if (!isInputKey(key, keys)) refuse(`input key ${key} is not allowed here`)
138
+ FIELDS[key](input, field, entry)
139
+ }
140
+ return input
141
+ }
142
+
143
+ /** The write `body` names: a REST operation sent with a write method. */
144
+ function writeOf(ops: ReadonlyMap<string, FlightOp>, body: JsonObject): FlightOp {
145
+ const name = body["op"]
146
+ const op = isString(name) ? ops.get(name) : undefined
147
+ if (op === undefined || !WRITE_METHODS.includes(op.entry.method) || !isRest(op.entry)) refuse("op is no write")
148
+ return op
149
+ }
150
+
151
+ /** A read's id: a non-empty string no other read of the batch has. */
152
+ function idOf(value: JsonObject, seen: Set<string>): string {
153
+ const { id } = value
154
+ if (!isString(id) || id === "" || seen.has(id)) refuse("a read has no id of its own")
155
+ seen.add(id)
156
+ return id
157
+ }
158
+
159
+ /** One read of a batch: a REST GET with a JSON answer, named by an id no other read has. */
160
+ function readOf(ops: ReadonlyMap<string, FlightOp>, value: Json, seen: Set<string>): FlightRead {
161
+ if (!isObject(value)) return refuse("a read is not an object")
162
+ const id = idOf(value, seen)
163
+ const { operationId } = value
164
+ const op = isString(operationId) ? ops.get(operationId) : undefined
165
+ if (op === undefined || op.entry.method !== READ_METHOD || !isRest(op.entry)) refuse(`${id} is no read`)
166
+ if (op.entry.accept !== undefined || op.entry.empty === true) refuse(`${id} answers no JSON`)
167
+ return { id, input: inputOf(op.entry, value["input"], READ_KEYS), op }
168
+ }
169
+
170
+ /** `body` as a batch of `ops`: a version 1 batch of one write and at most `maxReads` reads, or why it is refused. */
171
+ export function parseBatch(ops: ReadonlyMap<string, FlightOp>, body: Json, maxReads: number): ParsedBatch {
172
+ try {
173
+ if (!isObject(body) || body["v"] !== BATCH_VERSION) return refuse("the body is no version 1 batch")
174
+ const write = writeOf(ops, body)
175
+ const input = inputOf(write.entry, body["input"], WRITE_KEYS)
176
+ const reads = body["reads"] ?? []
177
+ if (!isList(reads) || reads.length > maxReads) refuse(`reads is not a list of at most ${maxReads}`)
178
+ const seen = new Set<string>()
179
+ return { batch: { input, reads: reads.map((read) => readOf(ops, read, seen)), write } }
180
+ } catch (e) {
181
+ if (e instanceof RangeError) return { refused: e.message }
182
+ throw e
183
+ }
184
+ }
@@ -0,0 +1,59 @@
1
+ /**
2
+ * A body to read whole: each chunk is offered to `take` first; the read stops once it refuses one or `signal`
3
+ * aborts.
4
+ */
5
+ export type BodySource = {
6
+ body: ReadableStream<Uint8Array> | null
7
+ signal?: AbortSignal
8
+ take: (chunk: Uint8Array) => boolean
9
+ }
10
+
11
+ /** A body being read: its reader, the chunks kept so far, and what decides whether the next is kept. */
12
+ type Drain = { chunks: Uint8Array[]; reader: ReadableStreamDefaultReader<Uint8Array>; take: BodySource["take"] }
13
+
14
+ /** A settled cancel: a body is given up on whether or not its cancel succeeds. */
15
+ function nothing(): undefined {
16
+ return undefined
17
+ }
18
+
19
+ /** `chunks` as one buffer. */
20
+ function joined(chunks: readonly Uint8Array[]): Uint8Array<ArrayBuffer> {
21
+ let size = 0
22
+ for (const chunk of chunks) size += chunk.byteLength
23
+ const out = new Uint8Array(size)
24
+ let at = 0
25
+ for (const chunk of chunks) {
26
+ out.set(chunk, at)
27
+ at += chunk.byteLength
28
+ }
29
+ return out
30
+ }
31
+
32
+ /** Read `drain` to its end: false, with the body cancelled, once `take` refuses a chunk. */
33
+ async function drained(drain: Drain): Promise<boolean> {
34
+ const next = await drain.reader.read()
35
+ if (next.done) return true
36
+ if (!drain.take(next.value)) {
37
+ /* not awaited: the refusal stands whether or not the body cancels cleanly */
38
+ void drain.reader.cancel().catch(nothing)
39
+ return false
40
+ }
41
+ drain.chunks.push(next.value)
42
+ return drained(drain)
43
+ }
44
+
45
+ /** `source`'s body read whole, or undefined once `take` refused a chunk; an abort cancels it where it stands. */
46
+ export async function bodyOf(source: BodySource): Promise<Uint8Array<ArrayBuffer> | undefined> {
47
+ if (source.body === null) return new Uint8Array(0)
48
+ const reader = source.body.getReader()
49
+ function stop(): void {
50
+ void reader.cancel().catch(nothing)
51
+ }
52
+ source.signal?.addEventListener("abort", stop, { once: true })
53
+ try {
54
+ const drain: Drain = { chunks: [], reader, take: source.take }
55
+ return (await drained(drain)) ? joined(drain.chunks) : undefined
56
+ } finally {
57
+ source.signal?.removeEventListener("abort", stop)
58
+ }
59
+ }