@workerstack/clients 1.0.0-rc.29 → 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 +548 -35
- package/assets/installers/examples/github.config.ts +17 -19
- package/assets/installers/examples/goreleaser.config.ts +16 -18
- package/assets/installers/examples/raw.config.ts +13 -15
- package/bin/clients.js +88 -68
- package/bin/installgen.js +18 -13
- package/dist/cli.d.ts +4 -4
- package/dist/cli.js +20 -12
- package/dist/emit/cli/channels.d.ts +2 -2
- package/dist/emit/cli/channels.js +18 -13
- package/dist/emit/cli/commands.d.ts +1 -1
- package/dist/emit/cli/commands.js +14 -8
- package/dist/emit/cli/discovery.d.ts +0 -6
- package/dist/emit/cli/discovery.js +9 -7
- package/dist/emit/cli/flags.d.ts +1 -3
- package/dist/emit/cli/flags.js +11 -5
- package/dist/emit/cli/install.d.ts +0 -8
- package/dist/emit/cli/install.js +3 -3
- package/dist/emit/cli/layout.d.ts +1 -1
- package/dist/emit/cli/layout.js +13 -10
- package/dist/emit/cli/module.d.ts +6 -6
- package/dist/emit/cli/module.js +10 -10
- package/dist/emit/cli/release.d.ts +0 -11
- package/dist/emit/cli/release.js +4 -4
- package/dist/emit/cli/skills.js +3 -3
- package/dist/emit/csharp/errors.js +4 -4
- package/dist/emit/csharp/json.js +8 -8
- package/dist/emit/csharp/realtime.js +3 -3
- package/dist/emit/csharp/sdk-answer.js +4 -4
- package/dist/emit/csharp/sdk-body.js +8 -6
- package/dist/emit/csharp/sdk-client.d.ts +3 -3
- package/dist/emit/csharp/sdk-client.js +2 -2
- package/dist/emit/csharp/sdk-csproj.d.ts +7 -9
- package/dist/emit/csharp/sdk-csproj.js +10 -10
- package/dist/emit/csharp/sdk-doc.js +1 -1
- package/dist/emit/csharp/sdk-method.d.ts +18 -2
- package/dist/emit/csharp/sdk-method.js +24 -9
- package/dist/emit/csharp/sdk-plan.js +0 -1
- package/dist/emit/csharp/sdk.js +7 -4
- package/dist/emit/csharp/sse.d.ts +0 -2
- package/dist/emit/csharp/sse.js +7 -7
- package/dist/emit/csharp/transport.js +7 -7
- package/dist/emit/csharp/types-enum.js +3 -1
- package/dist/emit/csharp/types-messages.js +3 -3
- package/dist/emit/csharp/types-names.js +10 -12
- package/dist/emit/csharp/types-record.js +3 -3
- package/dist/emit/csharp/types-union.d.ts +1 -1
- package/dist/emit/csharp/types.d.ts +0 -1
- package/dist/emit/csharp/types.js +3 -3
- package/dist/emit/csharp/ws.js +2 -2
- package/dist/emit/go/errors.js +1 -1
- package/dist/emit/go/http.js +2 -2
- package/dist/emit/go/module-path.js +2 -2
- package/dist/emit/go/sdk-answer.js +1 -1
- package/dist/emit/go/sdk-body.js +11 -7
- package/dist/emit/go/sdk-client.js +1 -1
- package/dist/emit/go/sdk-method.d.ts +9 -0
- package/dist/emit/go/sdk-method.js +12 -3
- package/dist/emit/go/sdk-mirror.js +2 -2
- package/dist/emit/go/sdk-opts.d.ts +0 -2
- package/dist/emit/go/sdk-opts.js +3 -3
- package/dist/emit/go/sdk.d.ts +1 -1
- package/dist/emit/go/sdk.js +12 -11
- package/dist/emit/go/sse.js +1 -1
- package/dist/emit/go/types-names.js +5 -0
- package/dist/emit/go/types-struct.d.ts +2 -1
- package/dist/emit/go/types-struct.js +1 -1
- package/dist/emit/go/types.js +9 -9
- package/dist/emit/go/ws.js +6 -6
- package/dist/emit/java/gradle.d.ts +7 -9
- package/dist/emit/java/gradle.js +8 -8
- package/dist/emit/java/json.js +1 -1
- package/dist/emit/java/layout-ast.js +1 -1
- package/dist/emit/java/layout-decl.js +5 -4
- package/dist/emit/java/layout-doc.js +13 -7
- package/dist/emit/java/layout-dot.js +1 -1
- package/dist/emit/java/layout-strings.js +4 -5
- package/dist/emit/java/layout-types.js +7 -5
- package/dist/emit/java/layout-visitor.js +4 -3
- package/dist/emit/java/layout.js +5 -4
- package/dist/emit/java/models-names.js +5 -4
- package/dist/emit/java/models-record.d.ts +0 -1
- package/dist/emit/java/models-record.js +3 -3
- package/dist/emit/java/models-union.d.ts +1 -1
- package/dist/emit/java/models-union.js +1 -1
- package/dist/emit/java/models.d.ts +1 -2
- package/dist/emit/java/models.js +25 -16
- package/dist/emit/java/realtime.d.ts +5 -17
- package/dist/emit/java/realtime.js +1 -1
- package/dist/emit/java/sdk-client.d.ts +6 -6
- package/dist/emit/java/sdk-client.js +2 -1
- package/dist/emit/java/sdk-decl.js +2 -2
- package/dist/emit/java/sdk-errors.js +1 -1
- package/dist/emit/java/sdk-headers.js +2 -2
- package/dist/emit/java/sdk-mirror.js +2 -2
- package/dist/emit/java/sdk-models.d.ts +1 -1
- package/dist/emit/java/sdk-models.js +7 -7
- package/dist/emit/java/sdk-op.d.ts +7 -11
- package/dist/emit/java/sdk-op.js +22 -10
- package/dist/emit/java/sdk-params.d.ts +5 -5
- package/dist/emit/java/sdk-params.js +3 -2
- package/dist/emit/java/sdk-plan.js +0 -1
- package/dist/emit/java/sdk.d.ts +1 -1
- package/dist/emit/java/sdk.js +21 -14
- package/dist/emit/java/sse.d.ts +2 -4
- package/dist/emit/java/sse.js +6 -6
- package/dist/emit/java/ws.d.ts +2 -2
- package/dist/emit/java/ws.js +3 -4
- package/dist/emit/mcp/annotations.js +8 -4
- package/dist/emit/mcp/files.js +9 -9
- package/dist/emit/mcp/mounted.js +2 -2
- package/dist/emit/mcp/output-schema.js +3 -3
- package/dist/emit/mcp/registry.d.ts +0 -2
- package/dist/emit/mcp/registry.js +5 -4
- package/dist/emit/mcp/runtime.js +2 -2
- package/dist/emit/mcp/schema.js +22 -11
- package/dist/emit/mcp/server.d.ts +7 -7
- package/dist/emit/mcp/server.js +7 -6
- package/dist/emit/mcp/tools.js +7 -6
- package/dist/emit/python/errors.js +3 -3
- package/dist/emit/python/realtime.js +2 -2
- package/dist/emit/python/sdk-answer.d.ts +3 -7
- package/dist/emit/python/sdk-answer.js +2 -2
- package/dist/emit/python/sdk-body.js +4 -5
- package/dist/emit/python/sdk-client.js +5 -5
- package/dist/emit/python/sdk-doc.js +2 -2
- package/dist/emit/python/sdk-method.d.ts +11 -0
- package/dist/emit/python/sdk-method.js +20 -5
- package/dist/emit/python/sdk-plan.js +0 -1
- package/dist/emit/python/sdk-pyproject.d.ts +0 -2
- package/dist/emit/python/sdk-pyproject.js +8 -8
- package/dist/emit/python/sdk.d.ts +1 -1
- package/dist/emit/python/sdk.js +12 -8
- package/dist/emit/python/sse.d.ts +0 -2
- package/dist/emit/python/sse.js +2 -2
- package/dist/emit/python/transport.js +4 -4
- package/dist/emit/python/types-dict.d.ts +2 -2
- package/dist/emit/python/types-dict.js +1 -1
- package/dist/emit/python/types-names.js +2 -2
- package/dist/emit/python/types-union.js +1 -1
- package/dist/emit/python/types.js +3 -3
- package/dist/emit/python/ws.d.ts +2 -5
- package/dist/emit/python/ws.js +4 -4
- package/dist/emit/rust/errors.js +3 -3
- package/dist/emit/rust/http.js +4 -4
- package/dist/emit/rust/realtime.js +2 -2
- package/dist/emit/rust/sdk-body.js +8 -5
- package/dist/emit/rust/sdk-cargo.d.ts +16 -18
- package/dist/emit/rust/sdk-cargo.js +12 -12
- package/dist/emit/rust/sdk-client.d.ts +1 -1
- package/dist/emit/rust/sdk-client.js +3 -3
- package/dist/emit/rust/sdk-method.d.ts +12 -1
- package/dist/emit/rust/sdk-method.js +12 -4
- package/dist/emit/rust/sdk-opts.d.ts +2 -1
- package/dist/emit/rust/sdk-opts.js +2 -2
- package/dist/emit/rust/sdk-plan.js +0 -1
- package/dist/emit/rust/sdk.d.ts +1 -1
- package/dist/emit/rust/sdk.js +9 -6
- package/dist/emit/rust/sse.d.ts +0 -5
- package/dist/emit/rust/sse.js +2 -2
- package/dist/emit/rust/types-names.js +3 -3
- package/dist/emit/rust/types-struct.js +1 -1
- package/dist/emit/rust/types-union.d.ts +1 -1
- package/dist/emit/rust/types.js +7 -5
- package/dist/emit/rust/ws.d.ts +0 -11
- package/dist/emit/rust/ws.js +5 -5
- package/dist/emit/shared/escape.js +17 -17
- package/dist/emit/shared/format.js +1 -1
- package/dist/emit/shared/gofmt.js +1 -1
- package/dist/emit/shared/lang.js +10 -10
- package/dist/emit/shared/literals.d.ts +5 -0
- package/dist/emit/shared/literals.js +8 -0
- package/dist/emit/shared/metadata.d.ts +0 -6
- package/dist/emit/shared/metadata.js +8 -7
- package/dist/emit/shared/ruff.js +1 -1
- package/dist/emit/shared/rustfmt.js +1 -1
- package/dist/emit/shared/type-emitter.js +37 -20
- package/dist/emit/shared/unknown-type.constants.d.ts +2 -0
- package/dist/emit/shared/unknown-type.constants.js +2 -0
- package/dist/emit/ts/http.d.ts +8 -2
- package/dist/emit/ts/http.js +51 -6
- package/dist/emit/ts/package.d.ts +14 -12
- package/dist/emit/ts/package.js +10 -8
- package/dist/emit/ts/route-tree.js +2 -2
- package/dist/emit/ts/sdk-types-preamble.d.ts +1 -1
- package/dist/emit/ts/sdk-types-preamble.js +12 -4
- package/dist/emit/ts/sdk-types.d.ts +0 -5
- package/dist/emit/ts/sdk-types.js +63 -19
- package/dist/emit/ts/sdk.d.ts +3 -1
- package/dist/emit/ts/sdk.js +44 -12
- package/dist/emit/ts/service-map.d.ts +7 -1
- 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 +60 -35
- package/dist/emit/ts/type-gen.js +31 -18
- package/dist/emit/ts/webhooks.d.ts +0 -2
- package/dist/emit/ts/webhooks.js +3 -3
- package/dist/extract/chain.js +5 -4
- package/dist/extract/extract.js +5 -5
- package/dist/extract/serialize.d.ts +0 -2
- package/dist/extract/serialize.js +14 -15
- package/dist/extract/walk.js +15 -12
- package/dist/gen/args.js +9 -5
- package/dist/gen/formatters.js +5 -3
- package/dist/gen/process.js +2 -1
- package/dist/gen/shipped.js +2 -2
- 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 +6 -7
- package/dist/gen/targets.js +11 -6
- package/dist/gen/write.js +4 -2
- package/dist/index.js +2 -2
- package/dist/installers/cli.d.ts +4 -4
- package/dist/installers/cli.js +24 -24
- package/dist/installers/commands/build.d.ts +4 -4
- package/dist/installers/commands/build.js +2 -3
- package/dist/installers/commands/check.d.ts +2 -2
- package/dist/installers/commands/check.js +11 -10
- package/dist/installers/commands/init.d.ts +2 -2
- package/dist/installers/commands/init.js +1 -2
- package/dist/installers/config/define-config.d.ts +16 -16
- package/dist/installers/config/define-config.js +1 -1
- package/dist/installers/config/hooks/bun.d.ts +6 -6
- package/dist/installers/config/hooks/node.js +1 -1
- package/dist/installers/config/load.d.ts +6 -8
- package/dist/installers/config/load.js +7 -8
- package/dist/installers/config/resolve.d.ts +1 -2
- package/dist/installers/config/resolve.js +28 -33
- package/dist/installers/config/types.d.ts +6 -6
- package/dist/installers/config/types.js +0 -1
- package/dist/installers/render/quote.js +3 -5
- package/dist/installers/render/render.d.ts +6 -6
- package/dist/installers/render/render.js +26 -26
- package/dist/installers/ui.d.ts +4 -4
- package/dist/installers/ui.js +3 -3
- package/dist/ir/build.d.ts +3 -3
- package/dist/ir/build.js +8 -5
- 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 +65 -18
- package/dist/ir/model.d.ts +2 -1
- package/dist/ir/model.js +0 -1
- package/dist/ir/read-method.constants.d.ts +2 -0
- package/dist/ir/read-method.constants.js +2 -0
- package/dist/ir/resolve-refs.js +2 -2
- package/dist/ir/resource-tree.js +2 -1
- package/dist/ir/route-tree-intern.js +1 -1
- package/dist/ir/schema.js +3 -3
- package/dist/ir/sdk-model.js +3 -3
- package/dist/ir/slots.js +13 -8
- package/dist/ir/streams.js +1 -1
- package/dist/release/bootstrap.d.ts +3 -3
- package/dist/release/bootstrap.js +7 -7
- package/dist/release/bump-args.js +4 -4
- package/dist/release/bump-command.d.ts +1 -1
- package/dist/release/bump-command.js +9 -10
- package/dist/release/bump.d.ts +5 -4
- package/dist/release/bump.js +2 -2
- package/dist/release/cli.d.ts +4 -4
- package/dist/release/cli.js +4 -4
- package/dist/release/codegen.js +1 -1
- package/dist/release/digest.js +5 -7
- package/dist/release/git.js +5 -8
- package/dist/release/load.js +4 -4
- package/dist/release/manifest.js +9 -10
- package/dist/release/oasdiff.d.ts +10 -15
- package/dist/release/oasdiff.js +5 -6
- package/dist/release/registries.d.ts +0 -11
- package/dist/release/registries.js +17 -17
- package/dist/release/release-state.d.ts +16 -13
- package/dist/release/release-workflow.js +5 -7
- package/dist/release/repo-settings.d.ts +2 -1
- package/dist/release/spec-gate.d.ts +0 -2
- package/dist/release/spec-gate.js +6 -10
- package/dist/release/sync-command.d.ts +2 -2
- package/dist/release/sync-command.js +1 -1
- package/dist/release/sync-tree.js +9 -13
- package/dist/release/sync.d.ts +6 -6
- package/dist/release/sync.js +12 -13
- package/dist/release/types.d.ts +22 -22
- package/dist/release/types.js +0 -1
- package/dist/release/version-files.d.ts +3 -4
- package/dist/release/version-files.js +4 -5
- package/dist/runtime/.oxfmtrc.jsonc +8 -0
- 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/mcp/files.ts +1 -1
- package/dist/runtime/mcp/http.ts +6 -2
- package/dist/runtime/mcp/listen.ts +1 -1
- package/dist/runtime/mcp/mount.ts +2 -2
- package/dist/runtime/mcp/protocol.ts +1 -1
- 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 -170
- package/package.json +12 -17
- 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
- package/dist/emit/cli/index.d.ts +0 -1
- package/dist/emit/cli/index.js +0 -1
- package/dist/emit/csharp/index.d.ts +0 -1
- package/dist/emit/csharp/index.js +0 -1
- package/dist/emit/go/index.d.ts +0 -1
- package/dist/emit/go/index.js +0 -1
- package/dist/emit/java/index.d.ts +0 -2
- package/dist/emit/java/index.js +0 -2
- package/dist/emit/mcp/index.d.ts +0 -3
- package/dist/emit/mcp/index.js +0 -3
- package/dist/emit/python/index.d.ts +0 -1
- package/dist/emit/python/index.js +0 -1
- package/dist/emit/rust/index.d.ts +0 -1
- package/dist/emit/rust/index.js +0 -1
|
@@ -9,124 +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
|
-
// oxlint-disable-next-line typescript/no-explicit-any
|
|
50
31
|
type AnyMethod = (...args: any[]) => any
|
|
51
32
|
|
|
52
|
-
|
|
53
|
-
type
|
|
54
|
-
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"
|
|
55
35
|
|
|
56
|
-
/**
|
|
57
|
-
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
|
|
58
41
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
: { 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>
|
|
63
45
|
|
|
64
|
-
/** A read's
|
|
65
|
-
export type QueryFactory<M> = (
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
initialData: undefined
|
|
69
|
-
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>>
|
|
70
50
|
}
|
|
71
51
|
|
|
72
|
-
/**
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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>>
|
|
77
58
|
mutationKey: QueryKey
|
|
78
59
|
}
|
|
79
60
|
|
|
80
|
-
/**
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
) =>
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
"getNextPageParam" | "getPreviousPageParam" | "initialPageParam" | "queryFn" | "queryKey"
|
|
98
|
-
>
|
|
99
|
-
initialPageParam: TPageParam
|
|
100
|
-
}) => 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>>
|
|
101
78
|
|
|
102
|
-
/** A key
|
|
103
|
-
export type
|
|
79
|
+
/** A write's key, which is its member path. */
|
|
80
|
+
export type MutationKeyFactory = () => QueryKey
|
|
104
81
|
|
|
105
82
|
/**
|
|
106
83
|
* One surface as this file can describe it: a tree of factories, indexable by name, callable at a leaf.
|
|
107
|
-
* It cannot be more precise here — the map arrives as `ServiceMap`, whose literal types are gone
|
|
108
|
-
*
|
|
109
|
-
* `<stem>.tanstack-query.gen.ts` declares the exact nested types over its own document and this shape
|
|
110
|
-
* 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.
|
|
111
86
|
*/
|
|
112
87
|
export interface Surface {
|
|
113
|
-
// oxlint-disable-next-line typescript/no-explicit-any
|
|
114
88
|
(...args: any[]): any
|
|
115
89
|
readonly [key: string]: Surface
|
|
116
90
|
}
|
|
117
91
|
|
|
118
|
-
|
|
119
|
-
return typeof source === "function" ? (source as () => T)() : source
|
|
120
|
-
}
|
|
92
|
+
type Kind = "infiniteQuery" | "mutation" | "query" | "queryKey" | "mutationKey"
|
|
121
93
|
|
|
122
|
-
/** The
|
|
123
|
-
|
|
124
|
-
let node: unknown = sdk
|
|
125
|
-
for (const key of member) node = (node as Record<string, unknown>)[key]
|
|
126
|
-
return node as AnyMethod
|
|
127
|
-
}
|
|
94
|
+
/** The five surfaces, untyped here; the emitted wrapper types each from its document. */
|
|
95
|
+
export type QueryHelpers = Readonly<{ [K in Kind]: Surface }>
|
|
128
96
|
|
|
129
|
-
|
|
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
|
+
}
|
|
130
103
|
|
|
131
104
|
/** Which surface an entry belongs to; a stream belongs to none. */
|
|
132
105
|
function surfaceOf(entry: ServiceEntry, surface: Kind): boolean {
|
|
@@ -135,74 +108,87 @@ function surfaceOf(entry: ServiceEntry, surface: Kind): boolean {
|
|
|
135
108
|
return surface === "mutation" || surface === "mutationKey" ? !read : read
|
|
136
109
|
}
|
|
137
110
|
|
|
138
|
-
type Context = {
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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 }
|
|
144
138
|
}
|
|
145
139
|
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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()
|
|
157
152
|
}
|
|
158
153
|
}
|
|
159
154
|
|
|
160
|
-
function
|
|
161
|
-
return (
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
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)
|
|
170
169
|
},
|
|
171
170
|
mutationKey: [ctx.sdkName, ...member],
|
|
172
|
-
...options?.mutationProps,
|
|
173
171
|
})
|
|
174
172
|
}
|
|
175
173
|
|
|
176
174
|
function infiniteOptionsAt(ctx: Context, member: string[]) {
|
|
177
|
-
return (
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
})
|
|
182
|
-
const { buildReqOptions, infiniteQueryProps, initialPageParam, ...rest } = options
|
|
183
|
-
return {
|
|
184
|
-
...rest,
|
|
185
|
-
initialPageParam,
|
|
186
|
-
queryFn: (context: { pageParam: unknown }) => {
|
|
187
|
-
const { init, req } = buildReqOptions(context.pageParam)
|
|
188
|
-
const args = init === undefined ? [req] : [req, init]
|
|
189
|
-
return methodAt(readSdk(ctx.sdk), member)(...args)
|
|
190
|
-
},
|
|
191
|
-
queryKey: [...readKey(ctx.sdkName, member, buildReqOptions(initialPageParam).req), INFINITE],
|
|
192
|
-
...infiniteQueryProps,
|
|
193
|
-
}
|
|
194
|
-
}
|
|
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
|
+
})
|
|
195
180
|
}
|
|
196
181
|
|
|
197
|
-
function
|
|
182
|
+
function queryKeyAt(ctx: Context, member: string[]) {
|
|
198
183
|
return (req?: unknown) => readKey(ctx.sdkName, member, req)
|
|
199
184
|
}
|
|
200
185
|
|
|
201
|
-
function factoryFor(ctx: Context, surface: Kind, member: string[]
|
|
186
|
+
function factoryFor(ctx: Context, surface: Kind, member: string[]) {
|
|
202
187
|
if (surface === "query") return queryOptionsAt(ctx, member)
|
|
203
|
-
if (surface === "mutation") return mutationOptionsAt(ctx, member
|
|
188
|
+
if (surface === "mutation") return mutationOptionsAt(ctx, member)
|
|
204
189
|
if (surface === "infiniteQuery") return infiniteOptionsAt(ctx, member)
|
|
205
|
-
return
|
|
190
|
+
if (surface === "mutationKey") return () => [ctx.sdkName, ...member]
|
|
191
|
+
return queryKeyAt(ctx, member)
|
|
206
192
|
}
|
|
207
193
|
|
|
208
194
|
/**
|
|
@@ -210,52 +196,36 @@ function factoryFor(ctx: Context, surface: Kind, member: string[], entry: Servic
|
|
|
210
196
|
* factory, and anything else — a write on `query`, a read on `mutation`, a stream on either, a name the
|
|
211
197
|
* map does not hold — gives `undefined`, so the surface never invents an operation.
|
|
212
198
|
*/
|
|
213
|
-
function surfaceProxy(ctx: Context, surface: Kind, node: ServiceMap
|
|
214
|
-
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, {
|
|
215
201
|
get(_, key) {
|
|
216
202
|
if (typeof key !== "string") return undefined
|
|
217
|
-
const child = childOf(node, key)
|
|
203
|
+
const child = childOf(node.map, key)
|
|
218
204
|
if (child === undefined) return undefined
|
|
219
|
-
const
|
|
220
|
-
|
|
221
|
-
|
|
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
|
|
222
209
|
},
|
|
223
210
|
has(_, key) {
|
|
224
|
-
return typeof key === "string" && childOf(node, key) !== undefined
|
|
211
|
+
return typeof key === "string" && childOf(node.map, key) !== undefined
|
|
225
212
|
},
|
|
226
213
|
})
|
|
227
214
|
}
|
|
228
215
|
|
|
229
216
|
/**
|
|
230
|
-
* The helper set
|
|
231
|
-
*
|
|
232
|
-
*
|
|
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.
|
|
233
220
|
*/
|
|
234
|
-
export function queryHelpers
|
|
235
|
-
|
|
236
|
-
map:
|
|
237
|
-
sdkName: string,
|
|
238
|
-
options: QueryHelperOptions = {},
|
|
239
|
-
): {
|
|
240
|
-
infiniteQuery: Surface
|
|
241
|
-
mutation: Surface
|
|
242
|
-
mutationKey: Surface
|
|
243
|
-
query: Surface
|
|
244
|
-
queryKey: Surface
|
|
245
|
-
} {
|
|
246
|
-
const ctx: Context = {
|
|
247
|
-
getQueryClient: options.getQueryClient,
|
|
248
|
-
map,
|
|
249
|
-
reads: indexReads(map),
|
|
250
|
-
sdk,
|
|
251
|
-
sdkName,
|
|
252
|
-
}
|
|
253
|
-
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: [] }
|
|
254
224
|
return {
|
|
255
|
-
infiniteQuery:
|
|
256
|
-
mutation:
|
|
257
|
-
mutationKey:
|
|
258
|
-
query:
|
|
259
|
-
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),
|
|
260
230
|
}
|
|
261
231
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workerstack/clients",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.31",
|
|
4
|
+
"private": false,
|
|
4
5
|
"description": "Generates SDKs (TypeScript, Go, Rust, Python, C#, Java), a CLI and an MCP server from any OpenAPI 3.x document.",
|
|
5
6
|
"keywords": [
|
|
6
7
|
"codegen",
|
|
@@ -26,9 +27,11 @@
|
|
|
26
27
|
"files": [
|
|
27
28
|
"assets",
|
|
28
29
|
"bin",
|
|
29
|
-
"dist"
|
|
30
|
+
"dist",
|
|
31
|
+
"references"
|
|
30
32
|
],
|
|
31
33
|
"type": "module",
|
|
34
|
+
"sideEffects": false,
|
|
32
35
|
"exports": {
|
|
33
36
|
".": {
|
|
34
37
|
"types": "./dist/index.d.ts",
|
|
@@ -46,32 +49,21 @@
|
|
|
46
49
|
"types": "./dist/release/index.d.ts",
|
|
47
50
|
"default": "./dist/release/index.js"
|
|
48
51
|
},
|
|
49
|
-
"./package.json": "./package.json"
|
|
52
|
+
"./package.json": "./package.json",
|
|
53
|
+
"./references/*": "./references/*"
|
|
50
54
|
},
|
|
51
55
|
"publishConfig": {
|
|
52
56
|
"access": "public",
|
|
53
57
|
"provenance": true
|
|
54
58
|
},
|
|
55
|
-
"scripts": {
|
|
56
|
-
"fmt": "oxfmt",
|
|
57
|
-
"fmt:check": "oxfmt --check",
|
|
58
|
-
"lint": "oxlint",
|
|
59
|
-
"lint:fix": "oxlint --fix",
|
|
60
|
-
"postinstall": "repo sync --postinstall",
|
|
61
|
-
"prepack": "bun scripts/build.ts",
|
|
62
|
-
"prepare": "lefthook install --reset-hooks-path",
|
|
63
|
-
"test": "vitest run --coverage",
|
|
64
|
-
"test:harness": "vitest run --mode harness",
|
|
65
|
-
"typecheck": "tsc --noEmit -p tsconfig.json"
|
|
66
|
-
},
|
|
67
59
|
"dependencies": {
|
|
68
|
-
"jiti": "2.7.0",
|
|
69
60
|
"oxc-transform": "0.155.0",
|
|
70
61
|
"zod": "4.3.6"
|
|
71
62
|
},
|
|
72
63
|
"peerDependencies": {
|
|
73
64
|
"oxfmt": ">=0.63.0",
|
|
74
|
-
"ts-morph": ">=28.0.0"
|
|
65
|
+
"ts-morph": ">=28.0.0",
|
|
66
|
+
"vite": ">=8.1.4"
|
|
75
67
|
},
|
|
76
68
|
"peerDependenciesMeta": {
|
|
77
69
|
"oxfmt": {
|
|
@@ -79,6 +71,9 @@
|
|
|
79
71
|
},
|
|
80
72
|
"ts-morph": {
|
|
81
73
|
"optional": true
|
|
74
|
+
},
|
|
75
|
+
"vite": {
|
|
76
|
+
"optional": true
|
|
82
77
|
}
|
|
83
78
|
},
|
|
84
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).
|