@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.
- package/README.md +175 -21
- package/bin/clients.js +5 -6
- package/bin/installgen.js +5 -9
- package/dist/cli.js +3 -1
- package/dist/emit/csharp/sdk-method.d.ts +18 -1
- package/dist/emit/csharp/sdk-method.js +14 -3
- package/dist/emit/csharp/sdk.js +4 -1
- package/dist/emit/go/sdk-method.d.ts +9 -0
- package/dist/emit/go/sdk-method.js +10 -1
- package/dist/emit/go/sdk.js +4 -3
- package/dist/emit/java/sdk-client.js +1 -0
- package/dist/emit/java/sdk-op.d.ts +6 -1
- package/dist/emit/java/sdk-op.js +15 -3
- package/dist/emit/java/sdk.js +7 -1
- package/dist/emit/python/sdk-method.d.ts +11 -0
- package/dist/emit/python/sdk-method.js +15 -0
- package/dist/emit/python/sdk.js +5 -1
- package/dist/emit/rust/sdk-method.d.ts +12 -1
- package/dist/emit/rust/sdk-method.js +10 -2
- package/dist/emit/rust/sdk.js +4 -1
- package/dist/emit/ts/http.d.ts +8 -0
- package/dist/emit/ts/http.js +48 -3
- package/dist/emit/ts/package.js +1 -0
- package/dist/emit/ts/sdk-types-preamble.js +10 -2
- package/dist/emit/ts/sdk-types.d.ts +0 -5
- package/dist/emit/ts/sdk-types.js +52 -8
- package/dist/emit/ts/sdk.d.ts +3 -1
- package/dist/emit/ts/sdk.js +40 -8
- package/dist/emit/ts/service-map.d.ts +5 -0
- package/dist/emit/ts/service-map.js +10 -1
- package/dist/emit/ts/single-flight-text.d.ts +3 -0
- package/dist/emit/ts/single-flight-text.js +38 -0
- package/dist/emit/ts/tanstack-query.d.ts +3 -2
- package/dist/emit/ts/tanstack-query.js +54 -29
- package/dist/gen/process.js +2 -1
- package/dist/gen/switch-on.constants.d.ts +2 -0
- package/dist/gen/switch-on.constants.js +2 -0
- package/dist/gen/targets.d.ts +4 -3
- package/dist/gen/targets.js +4 -3
- package/dist/ir/invalidate-reads.d.ts +17 -0
- package/dist/ir/invalidate-reads.js +104 -0
- package/dist/ir/load.d.ts +10 -0
- package/dist/ir/load.js +62 -14
- package/dist/ir/read-method.constants.d.ts +2 -0
- package/dist/ir/read-method.constants.js +2 -0
- package/dist/release/load.js +1 -1
- package/dist/runtime/csharp/Config.cs +9 -1
- package/dist/runtime/csharp/Exchange.cs +56 -4
- package/dist/runtime/csharp/Hooks.cs +9 -0
- package/dist/runtime/csharp/Operation.cs +6 -1
- package/dist/runtime/csharp/WsDial.cs +3 -1
- package/dist/runtime/go/config.go +5 -0
- package/dist/runtime/go/hooks.go +70 -0
- package/dist/runtime/go/request.go +6 -2
- package/dist/runtime/go/stream.go +4 -1
- package/dist/runtime/go/ws.go +3 -1
- package/dist/runtime/java/ClientConfig.java +11 -0
- package/dist/runtime/java/Flight.java +2 -12
- package/dist/runtime/java/Hooks.java +45 -0
- package/dist/runtime/java/InvalidateEvent.java +10 -0
- package/dist/runtime/java/InvalidateHook.java +12 -0
- package/dist/runtime/java/InvalidateTarget.java +7 -0
- package/dist/runtime/java/Operation.java +23 -3
- package/dist/runtime/java/Realtime.java +3 -1
- package/dist/runtime/java/WsDial.java +3 -0
- package/dist/runtime/python/config.py +8 -2
- package/dist/runtime/python/exchange.py +3 -1
- package/dist/runtime/python/hooks.py +110 -5
- package/dist/runtime/python/operation.py +2 -0
- package/dist/runtime/python/send_async.py +14 -2
- package/dist/runtime/python/send_sync.py +4 -2
- package/dist/runtime/python/ws.py +5 -1
- package/dist/runtime/rust/config.rs +6 -1
- package/dist/runtime/rust/exchange.rs +15 -3
- package/dist/runtime/rust/hooks.rs +127 -2
- package/dist/runtime/rust/log.rs +11 -3
- package/dist/runtime/rust/request.rs +17 -0
- package/dist/runtime/rust/ws.rs +9 -1
- package/dist/runtime/ts/config.ts +69 -0
- package/dist/runtime/ts/http.ts +12 -10
- package/dist/runtime/ts/request.ts +2 -0
- package/dist/runtime/ts/response.ts +7 -0
- package/dist/runtime/ts/sdk-invalidate.ts +82 -0
- package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
- package/dist/runtime/ts/sdk-single-flight.ts +203 -0
- package/dist/runtime/ts/sdk-sse.ts +5 -1
- package/dist/runtime/ts/sdk-ws.ts +9 -3
- package/dist/runtime/ts/sdk.ts +55 -31
- package/dist/runtime/ts/single-flight-batch.ts +184 -0
- package/dist/runtime/ts/single-flight-body.ts +59 -0
- package/dist/runtime/ts/single-flight-run.ts +160 -0
- package/dist/runtime/ts/single-flight.constants.ts +31 -0
- package/dist/runtime/ts/single-flight.ts +158 -0
- package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
- package/dist/runtime/ts-tanstack-query/query.ts +140 -168
- package/package.json +10 -18
- package/references/INDEX.md +31 -0
- package/references/cli.md +33 -0
- package/references/configuring.md +29 -0
- package/references/documentation.md +15 -0
- package/references/errors.md +23 -0
- package/references/flags.md +104 -0
- package/references/gates.md +46 -0
- package/references/generate.md +29 -0
- package/references/install-scripts.md +28 -0
- package/references/install.md +38 -0
- package/references/license.md +8 -0
- package/references/mcp.md +76 -0
- package/references/output.md +45 -0
- package/references/overview.md +14 -0
- package/references/release-tooling.md +34 -0
- package/references/release.md +305 -0
- package/references/sdks.md +393 -0
- package/references/start.md +22 -0
- package/references/tdd.md +16 -0
|
@@ -9,122 +9,97 @@
|
|
|
9
9
|
* a websocket or a realtime connection belongs to neither — a stream is not a cache entry — and asking for
|
|
10
10
|
* one gives `undefined` rather than a factory that would key a stream as data.
|
|
11
11
|
*
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
12
|
+
* Each factory returns only what it owns — the key and the function — and the caller spreads it into
|
|
13
|
+
* TanStack's own options, so every other option is TanStack's, typed by TanStack. A write invalidates
|
|
14
|
+
* nothing here: the SDK's `onInvalidate` hook (`invalidate.ts`) does, so a raw SDK call refreshes the
|
|
15
|
+
* cache too. `@tanstack/query-core` is imported for types only: an emitted SDK is loaded from the
|
|
16
|
+
* consumer's own tree, so a value import would have to resolve at run time.
|
|
16
17
|
*/
|
|
17
18
|
import type {
|
|
18
19
|
DataTag,
|
|
19
20
|
DefaultError,
|
|
20
21
|
InfiniteData,
|
|
21
22
|
InfiniteQueryObserverOptions,
|
|
22
|
-
|
|
23
|
-
|
|
23
|
+
MutationFunctionContext,
|
|
24
|
+
QueryFunction,
|
|
24
25
|
QueryKey,
|
|
25
|
-
QueryObserverOptions,
|
|
26
26
|
} from "@tanstack/query-core"
|
|
27
27
|
import type { ServiceEntry, ServiceMap } from "../ts/sdk.ts"
|
|
28
|
-
import {
|
|
29
|
-
childOf,
|
|
30
|
-
indexReads,
|
|
31
|
-
INFINITE,
|
|
32
|
-
invalidatedBy,
|
|
33
|
-
isEntry,
|
|
34
|
-
isStream,
|
|
35
|
-
READ,
|
|
36
|
-
type Read,
|
|
37
|
-
readKey,
|
|
38
|
-
} from "./invalidate.ts"
|
|
39
|
-
|
|
40
|
-
/** The SDK, or a thunk for one: an isomorphic app builds a client per request. */
|
|
41
|
-
export type SdkSource<T> = T | (() => T)
|
|
42
|
-
|
|
43
|
-
/** What the helpers need beyond the SDK: the client whose cache a write invalidates. */
|
|
44
|
-
export type QueryHelperOptions = {
|
|
45
|
-
getQueryClient?: (() => QueryClient) | undefined
|
|
46
|
-
}
|
|
28
|
+
import { childOf, INFINITE, isEntry, isStream, READ, readKey } from "./invalidate.ts"
|
|
47
29
|
|
|
48
30
|
/* an SDK method, whatever its shape: `unknown` collapses call signatures, which is what this must not do */
|
|
49
31
|
type AnyMethod = (...args: any[]) => any
|
|
50
32
|
|
|
51
|
-
|
|
52
|
-
type
|
|
53
|
-
type Data<M> = M extends (...args: never[]) => infer R ? Awaited<R> : never
|
|
33
|
+
/** The per-call options a generated method's input carries beside the request; none of them is in a key. */
|
|
34
|
+
type CallOption = "baseURL" | "cookies" | "headers" | "idempotencyKey" | "raw" | "signal" | "singleFlight" | "timeout"
|
|
54
35
|
|
|
55
|
-
/**
|
|
56
|
-
type
|
|
36
|
+
/** A method's one input, as its value overload (the last, which `infer` reads) takes it. */
|
|
37
|
+
type Input<M> = M extends AnyMethod ? Parameters<M>[0] : never
|
|
38
|
+
type Req<M> = Omit<NonNullable<Input<M>>, CallOption>
|
|
39
|
+
type Init<M> = Pick<NonNullable<Input<M>>, Extract<keyof NonNullable<Input<M>>, Exclude<CallOption, "raw">>>
|
|
40
|
+
type Data<M> = M extends (...args: never[]) => infer R ? Awaited<R> : never
|
|
57
41
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
: { queryProps?: Omit<QueryObserverOptions<Data<M>>, "queryFn" | "queryKey">; reqOptions: ReqOptions<M> }
|
|
42
|
+
/** `req` may be left out only when the request itself has no required field. */
|
|
43
|
+
type ReqArgs<M> = {} extends Req<M> ? [req?: Req<M>] : [req: Req<M>]
|
|
44
|
+
type ReadKey<T> = DataTag<QueryKey, T, DefaultError>
|
|
62
45
|
|
|
63
|
-
/** A read's
|
|
64
|
-
export type QueryFactory<M> = (
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
initialData: undefined
|
|
68
|
-
queryKey: DataTag<QueryKey, Data<M>, DefaultError>
|
|
46
|
+
/** A read's key and function; `init` (a timeout, headers, a signal) reaches the call but not the key. */
|
|
47
|
+
export type QueryFactory<M> = (...args: [...ReqArgs<M>, init?: Init<M>]) => {
|
|
48
|
+
queryFn: QueryFunction<Data<M>, QueryKey>
|
|
49
|
+
queryKey: ReadKey<Data<M>>
|
|
69
50
|
}
|
|
70
51
|
|
|
71
|
-
/**
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
52
|
+
/**
|
|
53
|
+
* A write's key and function; `mutate` takes the SDK method's own input, so a call site reads like the call. A
|
|
54
|
+
* mutation whose `meta.singleFlight` is false sends its write direct, never in a single-flight batch.
|
|
55
|
+
*/
|
|
56
|
+
export type MutationFactory<M> = () => {
|
|
57
|
+
mutationFn: (variables: Input<M>, context?: MutationFunctionContext) => Promise<Data<M>>
|
|
76
58
|
mutationKey: QueryKey
|
|
77
59
|
}
|
|
78
60
|
|
|
79
|
-
/**
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
) =>
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
"getNextPageParam" | "getPreviousPageParam" | "initialPageParam" | "queryFn" | "queryKey"
|
|
97
|
-
>
|
|
98
|
-
initialPageParam: TPageParam
|
|
99
|
-
}) => InfiniteQueryObserverOptions<Data<M>, DefaultError, InfiniteData<Data<M>>, QueryKey, TPageParam>
|
|
61
|
+
/**
|
|
62
|
+
* A paged read: `build` turns a page param into the request. It is called once with `undefined` when the
|
|
63
|
+
* options are made, for the key, so it must accept `undefined`; every page after shares that key.
|
|
64
|
+
* `initialPageParam` and `getNextPageParam` are TanStack's, spread beside the result. The return names
|
|
65
|
+
* TanStack's whole options type, not just the two fields it holds: that is what carries `P` to the
|
|
66
|
+
* observer, which would otherwise infer the page param from `initialPageParam` alone.
|
|
67
|
+
*/
|
|
68
|
+
export type InfiniteFactory<M> = <P>(
|
|
69
|
+
build: (pageParam: P) => Req<M>,
|
|
70
|
+
init?: Init<M>,
|
|
71
|
+
) => Omit<
|
|
72
|
+
InfiniteQueryObserverOptions<Data<M>, DefaultError, InfiniteData<Data<M>, P>, QueryKey, P>,
|
|
73
|
+
"getNextPageParam" | "initialPageParam"
|
|
74
|
+
> & { queryKey: ReadKey<InfiniteData<Data<M>, P>> }
|
|
75
|
+
|
|
76
|
+
/** A read's key: the request in, the key `query` would use out, tagged so a cache read infers the answer. */
|
|
77
|
+
export type QueryKeyFactory<M> = (...args: ReqArgs<M>) => ReadKey<Data<M>>
|
|
100
78
|
|
|
101
|
-
/** A key
|
|
102
|
-
export type
|
|
79
|
+
/** A write's key, which is its member path. */
|
|
80
|
+
export type MutationKeyFactory = () => QueryKey
|
|
103
81
|
|
|
104
82
|
/**
|
|
105
83
|
* One surface as this file can describe it: a tree of factories, indexable by name, callable at a leaf.
|
|
106
|
-
* It cannot be more precise here — the map arrives as `ServiceMap`, whose literal types are gone
|
|
107
|
-
*
|
|
108
|
-
* `<stem>.tanstack-query.gen.ts` declares the exact nested types over its own document and this shape
|
|
109
|
-
* disappears behind them; a consumer never sees it.
|
|
84
|
+
* It cannot be more precise here — the map arrives as `ServiceMap`, whose literal types are gone — so the
|
|
85
|
+
* emitted `<stem>.tanstack-query.gen.ts` declares the exact nested types and this shape disappears behind them.
|
|
110
86
|
*/
|
|
111
87
|
export interface Surface {
|
|
112
88
|
(...args: any[]): any
|
|
113
89
|
readonly [key: string]: Surface
|
|
114
90
|
}
|
|
115
91
|
|
|
116
|
-
|
|
117
|
-
return typeof source === "function" ? (source as () => T)() : source
|
|
118
|
-
}
|
|
92
|
+
type Kind = "infiniteQuery" | "mutation" | "query" | "queryKey" | "mutationKey"
|
|
119
93
|
|
|
120
|
-
/** The
|
|
121
|
-
|
|
122
|
-
let node: unknown = sdk
|
|
123
|
-
for (const key of member) node = (node as Record<string, unknown>)[key]
|
|
124
|
-
return node as AnyMethod
|
|
125
|
-
}
|
|
94
|
+
/** The five surfaces, untyped here; the emitted wrapper types each from its document. */
|
|
95
|
+
export type QueryHelpers = Readonly<{ [K in Kind]: Surface }>
|
|
126
96
|
|
|
127
|
-
|
|
97
|
+
/** The member path's method on the SDK, read when the call is made so `getSdk` stays per-call. */
|
|
98
|
+
function methodAt(ctx: Context, member: readonly string[]): AnyMethod {
|
|
99
|
+
let node: unknown = ctx.getSdk()
|
|
100
|
+
for (const key of member) node = (node /* a path the map named: each step holds the next */ as Surface)[key]
|
|
101
|
+
return node /* the leaf the map names an operation is its method */ as AnyMethod
|
|
102
|
+
}
|
|
128
103
|
|
|
129
104
|
/** Which surface an entry belongs to; a stream belongs to none. */
|
|
130
105
|
function surfaceOf(entry: ServiceEntry, surface: Kind): boolean {
|
|
@@ -133,74 +108,87 @@ function surfaceOf(entry: ServiceEntry, surface: Kind): boolean {
|
|
|
133
108
|
return surface === "mutation" || surface === "mutationKey" ? !read : read
|
|
134
109
|
}
|
|
135
110
|
|
|
136
|
-
type Context = {
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
111
|
+
type Context = { getSdk: () => unknown; sdkName: string }
|
|
112
|
+
type CallInit = { signal?: AbortSignal | undefined }
|
|
113
|
+
|
|
114
|
+
/** One signal for a call, and the release of the listeners that make it. */
|
|
115
|
+
type Linked = { done: () => void; signal: AbortSignal }
|
|
116
|
+
|
|
117
|
+
function noop(): void {}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* TanStack's signal and the caller's as one, by listeners: never `AbortSignal.any`, whose combined signal,
|
|
121
|
+
* only weakly held, can be collected before it fires. TanStack's aborts on a cancel and when the last
|
|
122
|
+
* observer leaves; `done` drops the listeners once the call settles.
|
|
123
|
+
*/
|
|
124
|
+
function linked(query: AbortSignal, own: AbortSignal | undefined): Linked {
|
|
125
|
+
if (own === undefined) return { done: noop, signal: query }
|
|
126
|
+
const sources = [query, own]
|
|
127
|
+
const controller = new AbortController()
|
|
128
|
+
const fired = sources.find((signal) => signal.aborted)
|
|
129
|
+
if (fired !== undefined) controller.abort(fired.reason)
|
|
130
|
+
function abort(event: Event): void {
|
|
131
|
+
controller.abort((event.target /* a listener's target is its signal */ as AbortSignal).reason)
|
|
132
|
+
}
|
|
133
|
+
for (const signal of sources) signal.addEventListener("abort", abort, { once: true })
|
|
134
|
+
function done(): void {
|
|
135
|
+
for (const signal of sources) signal.removeEventListener("abort", abort)
|
|
136
|
+
}
|
|
137
|
+
return { done, signal: controller.signal }
|
|
142
138
|
}
|
|
143
139
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
140
|
+
/** One call of the member's method with `req` and `init`, under the query's signal and the caller's. */
|
|
141
|
+
async function call(
|
|
142
|
+
ctx: Context,
|
|
143
|
+
member: readonly string[],
|
|
144
|
+
input: { init: CallInit | undefined; req: unknown; signal: AbortSignal },
|
|
145
|
+
) {
|
|
146
|
+
const { done, signal } = linked(input.signal, input.init?.signal)
|
|
147
|
+
try {
|
|
148
|
+
const req = input.req /* a request is an object or nothing: the factories' types admit no other */ as object
|
|
149
|
+
return await methodAt(ctx, member)({ ...req, ...input.init, signal })
|
|
150
|
+
} finally {
|
|
151
|
+
done()
|
|
155
152
|
}
|
|
156
153
|
}
|
|
157
154
|
|
|
158
|
-
function
|
|
159
|
-
return (
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
155
|
+
function queryOptionsAt(ctx: Context, member: string[]) {
|
|
156
|
+
return (req?: unknown, init?: CallInit) => ({
|
|
157
|
+
queryFn: (context: { signal: AbortSignal }) => call(ctx, member, { init, req, signal: context.signal }),
|
|
158
|
+
queryKey: readKey(ctx.sdkName, member, req),
|
|
159
|
+
})
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function mutationOptionsAt(ctx: Context, member: string[]) {
|
|
163
|
+
return () => ({
|
|
164
|
+
mutationFn: (variables: unknown, context?: MutationFunctionContext) => {
|
|
165
|
+
/* a mutation's `meta.singleFlight: false` sends its write direct, never in a single-flight batch */
|
|
166
|
+
const isDirect = context?.meta?.["singleFlight"] === false
|
|
167
|
+
const direct = { ...(variables /* the SDK method's input, or none */ as object), singleFlight: false }
|
|
168
|
+
return methodAt(ctx, member)(isDirect ? direct : variables)
|
|
168
169
|
},
|
|
169
170
|
mutationKey: [ctx.sdkName, ...member],
|
|
170
|
-
...options?.mutationProps,
|
|
171
171
|
})
|
|
172
172
|
}
|
|
173
173
|
|
|
174
174
|
function infiniteOptionsAt(ctx: Context, member: string[]) {
|
|
175
|
-
return (
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
})
|
|
180
|
-
const { buildReqOptions, infiniteQueryProps, initialPageParam, ...rest } = options
|
|
181
|
-
return {
|
|
182
|
-
...rest,
|
|
183
|
-
initialPageParam,
|
|
184
|
-
queryFn: (context: { pageParam: unknown }) => {
|
|
185
|
-
const { init, req } = buildReqOptions(context.pageParam)
|
|
186
|
-
const args = init === undefined ? [req] : [req, init]
|
|
187
|
-
return methodAt(readSdk(ctx.sdk), member)(...args)
|
|
188
|
-
},
|
|
189
|
-
queryKey: [...readKey(ctx.sdkName, member, buildReqOptions(initialPageParam).req), INFINITE],
|
|
190
|
-
...infiniteQueryProps,
|
|
191
|
-
}
|
|
192
|
-
}
|
|
175
|
+
return (build: (pageParam: unknown) => unknown, init?: CallInit) => ({
|
|
176
|
+
queryFn: (context: { pageParam: unknown; signal: AbortSignal }) =>
|
|
177
|
+
call(ctx, member, { init, req: build(context.pageParam), signal: context.signal }),
|
|
178
|
+
queryKey: [...readKey(ctx.sdkName, member, build(undefined)), INFINITE],
|
|
179
|
+
})
|
|
193
180
|
}
|
|
194
181
|
|
|
195
|
-
function
|
|
182
|
+
function queryKeyAt(ctx: Context, member: string[]) {
|
|
196
183
|
return (req?: unknown) => readKey(ctx.sdkName, member, req)
|
|
197
184
|
}
|
|
198
185
|
|
|
199
|
-
function factoryFor(ctx: Context, surface: Kind, member: string[]
|
|
186
|
+
function factoryFor(ctx: Context, surface: Kind, member: string[]) {
|
|
200
187
|
if (surface === "query") return queryOptionsAt(ctx, member)
|
|
201
|
-
if (surface === "mutation") return mutationOptionsAt(ctx, member
|
|
188
|
+
if (surface === "mutation") return mutationOptionsAt(ctx, member)
|
|
202
189
|
if (surface === "infiniteQuery") return infiniteOptionsAt(ctx, member)
|
|
203
|
-
return
|
|
190
|
+
if (surface === "mutationKey") return () => [ctx.sdkName, ...member]
|
|
191
|
+
return queryKeyAt(ctx, member)
|
|
204
192
|
}
|
|
205
193
|
|
|
206
194
|
/**
|
|
@@ -208,52 +196,36 @@ function factoryFor(ctx: Context, surface: Kind, member: string[], entry: Servic
|
|
|
208
196
|
* factory, and anything else — a write on `query`, a read on `mutation`, a stream on either, a name the
|
|
209
197
|
* map does not hold — gives `undefined`, so the surface never invents an operation.
|
|
210
198
|
*/
|
|
211
|
-
function surfaceProxy(ctx: Context, surface: Kind, node: ServiceMap
|
|
212
|
-
return new Proxy(Object.create(null) as
|
|
199
|
+
function surfaceProxy(ctx: Context, surface: Kind, node: { map: ServiceMap; member: string[] }): Surface {
|
|
200
|
+
return new Proxy(Object.create(null) /* a bare target: the proxy answers every read itself */ as Surface, {
|
|
213
201
|
get(_, key) {
|
|
214
202
|
if (typeof key !== "string") return undefined
|
|
215
|
-
const child = childOf(node, key)
|
|
203
|
+
const child = childOf(node.map, key)
|
|
216
204
|
if (child === undefined) return undefined
|
|
217
|
-
const
|
|
218
|
-
|
|
219
|
-
|
|
205
|
+
const member = [...node.member, key]
|
|
206
|
+
const map = child /* a child that is not an entry is a branch of the map */ as ServiceMap
|
|
207
|
+
if (!isEntry(child)) return surfaceProxy(ctx, surface, { map, member })
|
|
208
|
+
return surfaceOf(child, surface) ? factoryFor(ctx, surface, member) : undefined
|
|
220
209
|
},
|
|
221
210
|
has(_, key) {
|
|
222
|
-
return typeof key === "string" && childOf(node, key) !== undefined
|
|
211
|
+
return typeof key === "string" && childOf(node.map, key) !== undefined
|
|
223
212
|
},
|
|
224
213
|
})
|
|
225
214
|
}
|
|
226
215
|
|
|
227
216
|
/**
|
|
228
|
-
* The helper set
|
|
229
|
-
*
|
|
230
|
-
*
|
|
217
|
+
* The helper set over `map` for the SDK `getSdk` returns, read on every call so an isomorphic app can
|
|
218
|
+
* hand each request its own client. `sdkName` heads every key, so two SDKs in one cache never collide.
|
|
219
|
+
* The emitted wrapper passes its own map and name and types each surface from the document.
|
|
231
220
|
*/
|
|
232
|
-
export function queryHelpers
|
|
233
|
-
|
|
234
|
-
map:
|
|
235
|
-
sdkName: string,
|
|
236
|
-
options: QueryHelperOptions = {},
|
|
237
|
-
): {
|
|
238
|
-
infiniteQuery: Surface
|
|
239
|
-
mutation: Surface
|
|
240
|
-
mutationKey: Surface
|
|
241
|
-
query: Surface
|
|
242
|
-
queryKey: Surface
|
|
243
|
-
} {
|
|
244
|
-
const ctx: Context = {
|
|
245
|
-
getQueryClient: options.getQueryClient,
|
|
246
|
-
map,
|
|
247
|
-
reads: indexReads(map),
|
|
248
|
-
sdk,
|
|
249
|
-
sdkName,
|
|
250
|
-
}
|
|
251
|
-
const of = (surface: Kind) => surfaceProxy(ctx, surface, map, []) as Surface
|
|
221
|
+
export function queryHelpers(getSdk: () => unknown, map: ServiceMap, sdkName: string): QueryHelpers {
|
|
222
|
+
const ctx: Context = { getSdk, sdkName }
|
|
223
|
+
const root = { map, member: [] }
|
|
252
224
|
return {
|
|
253
|
-
infiniteQuery:
|
|
254
|
-
mutation:
|
|
255
|
-
mutationKey:
|
|
256
|
-
query:
|
|
257
|
-
queryKey:
|
|
225
|
+
infiniteQuery: surfaceProxy(ctx, "infiniteQuery", root),
|
|
226
|
+
mutation: surfaceProxy(ctx, "mutation", root),
|
|
227
|
+
mutationKey: surfaceProxy(ctx, "mutationKey", root),
|
|
228
|
+
query: surfaceProxy(ctx, "query", root),
|
|
229
|
+
queryKey: surfaceProxy(ctx, "queryKey", root),
|
|
258
230
|
}
|
|
259
231
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workerstack/clients",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.31",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a CLI and an MCP server from any OpenAPI 3.x document.",
|
|
6
6
|
"keywords": [
|
|
@@ -27,7 +27,8 @@
|
|
|
27
27
|
"files": [
|
|
28
28
|
"assets",
|
|
29
29
|
"bin",
|
|
30
|
-
"dist"
|
|
30
|
+
"dist",
|
|
31
|
+
"references"
|
|
31
32
|
],
|
|
32
33
|
"type": "module",
|
|
33
34
|
"sideEffects": false,
|
|
@@ -48,33 +49,21 @@
|
|
|
48
49
|
"types": "./dist/release/index.d.ts",
|
|
49
50
|
"default": "./dist/release/index.js"
|
|
50
51
|
},
|
|
51
|
-
"./package.json": "./package.json"
|
|
52
|
+
"./package.json": "./package.json",
|
|
53
|
+
"./references/*": "./references/*"
|
|
52
54
|
},
|
|
53
55
|
"publishConfig": {
|
|
54
56
|
"access": "public",
|
|
55
57
|
"provenance": true
|
|
56
58
|
},
|
|
57
|
-
"scripts": {
|
|
58
|
-
"build:types": "tsc -p tsconfig.build.json",
|
|
59
|
-
"fmt": "repo fmt",
|
|
60
|
-
"fmt:check": "repo fmt --check",
|
|
61
|
-
"lint": "repo lint",
|
|
62
|
-
"lint:fix": "repo lint --fix",
|
|
63
|
-
"postinstall": "repo sync --postinstall",
|
|
64
|
-
"prepack": "bun scripts/build.ts",
|
|
65
|
-
"test": "vitest run --coverage",
|
|
66
|
-
"test:harness": "vitest run --mode harness",
|
|
67
|
-
"typecheck": "tsc -p tsconfig.json",
|
|
68
|
-
"typecheck:src": "tsc -p tsconfig.src.json"
|
|
69
|
-
},
|
|
70
59
|
"dependencies": {
|
|
71
|
-
"jiti": "2.7.0",
|
|
72
60
|
"oxc-transform": "0.155.0",
|
|
73
61
|
"zod": "4.3.6"
|
|
74
62
|
},
|
|
75
63
|
"peerDependencies": {
|
|
76
64
|
"oxfmt": ">=0.63.0",
|
|
77
|
-
"ts-morph": ">=28.0.0"
|
|
65
|
+
"ts-morph": ">=28.0.0",
|
|
66
|
+
"vite": ">=8.1.4"
|
|
78
67
|
},
|
|
79
68
|
"peerDependenciesMeta": {
|
|
80
69
|
"oxfmt": {
|
|
@@ -82,6 +71,9 @@
|
|
|
82
71
|
},
|
|
83
72
|
"ts-morph": {
|
|
84
73
|
"optional": true
|
|
74
|
+
},
|
|
75
|
+
"vite": {
|
|
76
|
+
"optional": true
|
|
85
77
|
}
|
|
86
78
|
},
|
|
87
79
|
"engines": {
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# References
|
|
2
|
+
|
|
3
|
+
<!-- repo:stack 67f979b7 -->
|
|
4
|
+
- [@workerstack/repo](../node_modules/@workerstack/repo/references/INDEX.md)
|
|
5
|
+
<!-- /repo:stack -->
|
|
6
|
+
|
|
7
|
+
<!-- repo:available 10ef8736 -->
|
|
8
|
+
- [@workerstack/database](https://www.npmjs.com/package/@workerstack/database): Schema, queries and migrations for SQLite, D1 and Postgres
|
|
9
|
+
- [@workerstack/testing](https://www.npmjs.com/package/@workerstack/testing): End-to-end matrix testing for APIs, web apps and Workers
|
|
10
|
+
<!-- /repo:available -->
|
|
11
|
+
|
|
12
|
+
<!-- repo:refs 2e18d615 -->
|
|
13
|
+
- `overview.md`: What it generates
|
|
14
|
+
- `install.md`: Install the package
|
|
15
|
+
- `start.md`: First generation
|
|
16
|
+
- `generate.md`: The generate command
|
|
17
|
+
- `flags.md`: Every generate flag
|
|
18
|
+
- `sdks.md`: The six SDKs
|
|
19
|
+
- `errors.md`: Errors and the safe mirror
|
|
20
|
+
- `cli.md`: The generated CLI
|
|
21
|
+
- `install-scripts.md`: Install scripts for a CLI
|
|
22
|
+
- `release-tooling.md`: Release tooling overview
|
|
23
|
+
- `mcp.md`: The generated MCP server
|
|
24
|
+
- `configuring.md`: Configuring generation
|
|
25
|
+
- `output.md`: What a run writes
|
|
26
|
+
- `documentation.md`: Further documentation
|
|
27
|
+
- `release.md`: Release public packages
|
|
28
|
+
- `gates.md`: Gates, push, CI and release
|
|
29
|
+
- `tdd.md`: Red, fix, green
|
|
30
|
+
- `license.md`: License
|
|
31
|
+
<!-- /repo:refs -->
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The generated CLI
|
|
3
|
+
order: 80
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# The command-line client
|
|
7
|
+
|
|
8
|
+
`--target cli` writes a Go command-line client for the API: one command per operation, grouped by its dotted
|
|
9
|
+
`operationId`, with `--help` everywhere, `commands` and `schema` for discovery, typed flags, table/JSON/NDJSON/YAML
|
|
10
|
+
output, streams, pagination, shell completion, and an embedded `SKILL.md` so an agent can drive it. It ships with a
|
|
11
|
+
release workflow, which can publish to Homebrew, Scoop, winget, AUR and deb/rpm/apk packages, and, with `--cli-repo`,
|
|
12
|
+
install scripts that verify what they install.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
clients generate --spec openapi.json --target cli --out ./cli --cli-repo acme/shop-cli
|
|
16
|
+
shop orders list --status open --output json
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
| Value | Default | What it does |
|
|
20
|
+
| ------------------------------------------------------------------- | --------------- | ---------------------------------------------------- |
|
|
21
|
+
| a command per operation | — | grouped by the dotted operationId resource tree |
|
|
22
|
+
| `--json` | off | one machine-readable shape on every command |
|
|
23
|
+
| `--output <json\|ndjson\|yaml\|table>` | table | human and machine formats |
|
|
24
|
+
| `--api-key` / `--base-url` / `--config` / `--timeout` / `--verbose` | from config/env | auth, target, config file, deadline, logging |
|
|
25
|
+
| `commands`, `schema` | — | a listable command index and per-call schemas |
|
|
26
|
+
| `--output <file>` | stdout | a binary response written as bytes, pipe-safe |
|
|
27
|
+
| exit codes | usage/standard | non-zero on usage error, distinct from a runtime one |
|
|
28
|
+
|
|
29
|
+
Its configuration has one precedence, everywhere: **flag, then environment, then config file.** The environment
|
|
30
|
+
variables are the `--cli-env-prefix` (or the API's name) upper-cased.
|
|
31
|
+
|
|
32
|
+
Full reference: [the generated CLI](https://github.com/workerstack/clients/blob/main/docs/cli.md) and
|
|
33
|
+
[releasing it](https://github.com/workerstack/clients/blob/main/docs/cli-release.md).
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Configuring generation
|
|
3
|
+
order: 120
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Configuring generation
|
|
7
|
+
|
|
8
|
+
In a backend project the generation is configured once, in the Vite plugin, and `clients generate --app` reads
|
|
9
|
+
the same app. `codegen.mcp` writes the handler `mcp()` mounts, and `codegen.openApi` the document the SDKs are
|
|
10
|
+
generated from:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
# the whole set, from the app module, in one run
|
|
14
|
+
npx clients generate --app src/app.ts \
|
|
15
|
+
--target ts --target go --target python --target cli --target mcp \
|
|
16
|
+
--go-module-path github.com/acme/shop/sdk --cli-repo acme/shop-cli --out generated
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
{
|
|
21
|
+
"scripts": {
|
|
22
|
+
"generate": "backend generate && clients generate --app src/app.ts --target ts --out generated"
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
What each target names its package, its client class and its environment variables is the `--<target>-<option>` set
|
|
28
|
+
above; nothing is read from a config file of ours, so one command line is the whole input and a CI run cannot drift
|
|
29
|
+
from a developer's.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Further documentation
|
|
3
|
+
order: 140
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Documentation
|
|
7
|
+
|
|
8
|
+
- [Code generation](https://github.com/workerstack/clients/blob/main/docs/codegen.md): every target and its options.
|
|
9
|
+
- [Generated clients](https://github.com/workerstack/clients/blob/main/docs/client.md) and their
|
|
10
|
+
[per-language recipes](https://github.com/workerstack/clients/blob/main/docs/sdk-recipes.md).
|
|
11
|
+
- [The generated CLI](https://github.com/workerstack/clients/blob/main/docs/cli.md),
|
|
12
|
+
[releasing it](https://github.com/workerstack/clients/blob/main/docs/cli-release.md), and
|
|
13
|
+
[the MCP server](https://github.com/workerstack/backend/blob/main/docs/mcp.md).
|
|
14
|
+
- [SDK conformance](https://github.com/workerstack/clients/blob/main/docs/conformance.md) and
|
|
15
|
+
[the framework itself](https://github.com/workerstack/backend#readme).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Errors and the safe mirror
|
|
3
|
+
order: 70
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Errors and the safe mirror
|
|
7
|
+
|
|
8
|
+
Two styles, in all six SDKs, over the same calls:
|
|
9
|
+
|
|
10
|
+
- **The normal call** answers its value and throws on any failure: an error status as its typed error
|
|
11
|
+
(`NotFoundError` and so on, each a `ClientError`), and an undecodable or over-cap 2xx as a `DecodeError`.
|
|
12
|
+
- **`client.safe`** holds the same calls, each answering a result. On `ok` it carries the data, the raw response, and
|
|
13
|
+
the declared response headers when the operation has any. Otherwise it carries the error the normal call would have
|
|
14
|
+
thrown, with the parsed body on it. A declared status narrows the error's type and body; any other status is the
|
|
15
|
+
base client error with an `unknown` body.
|
|
16
|
+
- **No answer throws in both styles.** A call never sent, a refused or dropped connection, a timeout, a cancel, and a
|
|
17
|
+
stream that drops after it opened are not answers, so there is nothing for a result to carry.
|
|
18
|
+
|
|
19
|
+
A name of yours that collides with the mirror, or with a runtime type, is renamed and reported on stderr — never
|
|
20
|
+
silently. An operation or root resource named `safe` becomes `safe_`, and a component named like one of the runtime
|
|
21
|
+
types becomes `<Name>Model`.
|
|
22
|
+
|
|
23
|
+
Full reference: [generated clients](https://github.com/workerstack/clients/blob/main/docs/client.md).
|