@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.
Files changed (375) hide show
  1. package/README.md +548 -35
  2. package/assets/installers/examples/github.config.ts +17 -19
  3. package/assets/installers/examples/goreleaser.config.ts +16 -18
  4. package/assets/installers/examples/raw.config.ts +13 -15
  5. package/bin/clients.js +88 -68
  6. package/bin/installgen.js +18 -13
  7. package/dist/cli.d.ts +4 -4
  8. package/dist/cli.js +20 -12
  9. package/dist/emit/cli/channels.d.ts +2 -2
  10. package/dist/emit/cli/channels.js +18 -13
  11. package/dist/emit/cli/commands.d.ts +1 -1
  12. package/dist/emit/cli/commands.js +14 -8
  13. package/dist/emit/cli/discovery.d.ts +0 -6
  14. package/dist/emit/cli/discovery.js +9 -7
  15. package/dist/emit/cli/flags.d.ts +1 -3
  16. package/dist/emit/cli/flags.js +11 -5
  17. package/dist/emit/cli/install.d.ts +0 -8
  18. package/dist/emit/cli/install.js +3 -3
  19. package/dist/emit/cli/layout.d.ts +1 -1
  20. package/dist/emit/cli/layout.js +13 -10
  21. package/dist/emit/cli/module.d.ts +6 -6
  22. package/dist/emit/cli/module.js +10 -10
  23. package/dist/emit/cli/release.d.ts +0 -11
  24. package/dist/emit/cli/release.js +4 -4
  25. package/dist/emit/cli/skills.js +3 -3
  26. package/dist/emit/csharp/errors.js +4 -4
  27. package/dist/emit/csharp/json.js +8 -8
  28. package/dist/emit/csharp/realtime.js +3 -3
  29. package/dist/emit/csharp/sdk-answer.js +4 -4
  30. package/dist/emit/csharp/sdk-body.js +8 -6
  31. package/dist/emit/csharp/sdk-client.d.ts +3 -3
  32. package/dist/emit/csharp/sdk-client.js +2 -2
  33. package/dist/emit/csharp/sdk-csproj.d.ts +7 -9
  34. package/dist/emit/csharp/sdk-csproj.js +10 -10
  35. package/dist/emit/csharp/sdk-doc.js +1 -1
  36. package/dist/emit/csharp/sdk-method.d.ts +18 -2
  37. package/dist/emit/csharp/sdk-method.js +24 -9
  38. package/dist/emit/csharp/sdk-plan.js +0 -1
  39. package/dist/emit/csharp/sdk.js +7 -4
  40. package/dist/emit/csharp/sse.d.ts +0 -2
  41. package/dist/emit/csharp/sse.js +7 -7
  42. package/dist/emit/csharp/transport.js +7 -7
  43. package/dist/emit/csharp/types-enum.js +3 -1
  44. package/dist/emit/csharp/types-messages.js +3 -3
  45. package/dist/emit/csharp/types-names.js +10 -12
  46. package/dist/emit/csharp/types-record.js +3 -3
  47. package/dist/emit/csharp/types-union.d.ts +1 -1
  48. package/dist/emit/csharp/types.d.ts +0 -1
  49. package/dist/emit/csharp/types.js +3 -3
  50. package/dist/emit/csharp/ws.js +2 -2
  51. package/dist/emit/go/errors.js +1 -1
  52. package/dist/emit/go/http.js +2 -2
  53. package/dist/emit/go/module-path.js +2 -2
  54. package/dist/emit/go/sdk-answer.js +1 -1
  55. package/dist/emit/go/sdk-body.js +11 -7
  56. package/dist/emit/go/sdk-client.js +1 -1
  57. package/dist/emit/go/sdk-method.d.ts +9 -0
  58. package/dist/emit/go/sdk-method.js +12 -3
  59. package/dist/emit/go/sdk-mirror.js +2 -2
  60. package/dist/emit/go/sdk-opts.d.ts +0 -2
  61. package/dist/emit/go/sdk-opts.js +3 -3
  62. package/dist/emit/go/sdk.d.ts +1 -1
  63. package/dist/emit/go/sdk.js +12 -11
  64. package/dist/emit/go/sse.js +1 -1
  65. package/dist/emit/go/types-names.js +5 -0
  66. package/dist/emit/go/types-struct.d.ts +2 -1
  67. package/dist/emit/go/types-struct.js +1 -1
  68. package/dist/emit/go/types.js +9 -9
  69. package/dist/emit/go/ws.js +6 -6
  70. package/dist/emit/java/gradle.d.ts +7 -9
  71. package/dist/emit/java/gradle.js +8 -8
  72. package/dist/emit/java/json.js +1 -1
  73. package/dist/emit/java/layout-ast.js +1 -1
  74. package/dist/emit/java/layout-decl.js +5 -4
  75. package/dist/emit/java/layout-doc.js +13 -7
  76. package/dist/emit/java/layout-dot.js +1 -1
  77. package/dist/emit/java/layout-strings.js +4 -5
  78. package/dist/emit/java/layout-types.js +7 -5
  79. package/dist/emit/java/layout-visitor.js +4 -3
  80. package/dist/emit/java/layout.js +5 -4
  81. package/dist/emit/java/models-names.js +5 -4
  82. package/dist/emit/java/models-record.d.ts +0 -1
  83. package/dist/emit/java/models-record.js +3 -3
  84. package/dist/emit/java/models-union.d.ts +1 -1
  85. package/dist/emit/java/models-union.js +1 -1
  86. package/dist/emit/java/models.d.ts +1 -2
  87. package/dist/emit/java/models.js +25 -16
  88. package/dist/emit/java/realtime.d.ts +5 -17
  89. package/dist/emit/java/realtime.js +1 -1
  90. package/dist/emit/java/sdk-client.d.ts +6 -6
  91. package/dist/emit/java/sdk-client.js +2 -1
  92. package/dist/emit/java/sdk-decl.js +2 -2
  93. package/dist/emit/java/sdk-errors.js +1 -1
  94. package/dist/emit/java/sdk-headers.js +2 -2
  95. package/dist/emit/java/sdk-mirror.js +2 -2
  96. package/dist/emit/java/sdk-models.d.ts +1 -1
  97. package/dist/emit/java/sdk-models.js +7 -7
  98. package/dist/emit/java/sdk-op.d.ts +7 -11
  99. package/dist/emit/java/sdk-op.js +22 -10
  100. package/dist/emit/java/sdk-params.d.ts +5 -5
  101. package/dist/emit/java/sdk-params.js +3 -2
  102. package/dist/emit/java/sdk-plan.js +0 -1
  103. package/dist/emit/java/sdk.d.ts +1 -1
  104. package/dist/emit/java/sdk.js +21 -14
  105. package/dist/emit/java/sse.d.ts +2 -4
  106. package/dist/emit/java/sse.js +6 -6
  107. package/dist/emit/java/ws.d.ts +2 -2
  108. package/dist/emit/java/ws.js +3 -4
  109. package/dist/emit/mcp/annotations.js +8 -4
  110. package/dist/emit/mcp/files.js +9 -9
  111. package/dist/emit/mcp/mounted.js +2 -2
  112. package/dist/emit/mcp/output-schema.js +3 -3
  113. package/dist/emit/mcp/registry.d.ts +0 -2
  114. package/dist/emit/mcp/registry.js +5 -4
  115. package/dist/emit/mcp/runtime.js +2 -2
  116. package/dist/emit/mcp/schema.js +22 -11
  117. package/dist/emit/mcp/server.d.ts +7 -7
  118. package/dist/emit/mcp/server.js +7 -6
  119. package/dist/emit/mcp/tools.js +7 -6
  120. package/dist/emit/python/errors.js +3 -3
  121. package/dist/emit/python/realtime.js +2 -2
  122. package/dist/emit/python/sdk-answer.d.ts +3 -7
  123. package/dist/emit/python/sdk-answer.js +2 -2
  124. package/dist/emit/python/sdk-body.js +4 -5
  125. package/dist/emit/python/sdk-client.js +5 -5
  126. package/dist/emit/python/sdk-doc.js +2 -2
  127. package/dist/emit/python/sdk-method.d.ts +11 -0
  128. package/dist/emit/python/sdk-method.js +20 -5
  129. package/dist/emit/python/sdk-plan.js +0 -1
  130. package/dist/emit/python/sdk-pyproject.d.ts +0 -2
  131. package/dist/emit/python/sdk-pyproject.js +8 -8
  132. package/dist/emit/python/sdk.d.ts +1 -1
  133. package/dist/emit/python/sdk.js +12 -8
  134. package/dist/emit/python/sse.d.ts +0 -2
  135. package/dist/emit/python/sse.js +2 -2
  136. package/dist/emit/python/transport.js +4 -4
  137. package/dist/emit/python/types-dict.d.ts +2 -2
  138. package/dist/emit/python/types-dict.js +1 -1
  139. package/dist/emit/python/types-names.js +2 -2
  140. package/dist/emit/python/types-union.js +1 -1
  141. package/dist/emit/python/types.js +3 -3
  142. package/dist/emit/python/ws.d.ts +2 -5
  143. package/dist/emit/python/ws.js +4 -4
  144. package/dist/emit/rust/errors.js +3 -3
  145. package/dist/emit/rust/http.js +4 -4
  146. package/dist/emit/rust/realtime.js +2 -2
  147. package/dist/emit/rust/sdk-body.js +8 -5
  148. package/dist/emit/rust/sdk-cargo.d.ts +16 -18
  149. package/dist/emit/rust/sdk-cargo.js +12 -12
  150. package/dist/emit/rust/sdk-client.d.ts +1 -1
  151. package/dist/emit/rust/sdk-client.js +3 -3
  152. package/dist/emit/rust/sdk-method.d.ts +12 -1
  153. package/dist/emit/rust/sdk-method.js +12 -4
  154. package/dist/emit/rust/sdk-opts.d.ts +2 -1
  155. package/dist/emit/rust/sdk-opts.js +2 -2
  156. package/dist/emit/rust/sdk-plan.js +0 -1
  157. package/dist/emit/rust/sdk.d.ts +1 -1
  158. package/dist/emit/rust/sdk.js +9 -6
  159. package/dist/emit/rust/sse.d.ts +0 -5
  160. package/dist/emit/rust/sse.js +2 -2
  161. package/dist/emit/rust/types-names.js +3 -3
  162. package/dist/emit/rust/types-struct.js +1 -1
  163. package/dist/emit/rust/types-union.d.ts +1 -1
  164. package/dist/emit/rust/types.js +7 -5
  165. package/dist/emit/rust/ws.d.ts +0 -11
  166. package/dist/emit/rust/ws.js +5 -5
  167. package/dist/emit/shared/escape.js +17 -17
  168. package/dist/emit/shared/format.js +1 -1
  169. package/dist/emit/shared/gofmt.js +1 -1
  170. package/dist/emit/shared/lang.js +10 -10
  171. package/dist/emit/shared/literals.d.ts +5 -0
  172. package/dist/emit/shared/literals.js +8 -0
  173. package/dist/emit/shared/metadata.d.ts +0 -6
  174. package/dist/emit/shared/metadata.js +8 -7
  175. package/dist/emit/shared/ruff.js +1 -1
  176. package/dist/emit/shared/rustfmt.js +1 -1
  177. package/dist/emit/shared/type-emitter.js +37 -20
  178. package/dist/emit/shared/unknown-type.constants.d.ts +2 -0
  179. package/dist/emit/shared/unknown-type.constants.js +2 -0
  180. package/dist/emit/ts/http.d.ts +8 -2
  181. package/dist/emit/ts/http.js +51 -6
  182. package/dist/emit/ts/package.d.ts +14 -12
  183. package/dist/emit/ts/package.js +10 -8
  184. package/dist/emit/ts/route-tree.js +2 -2
  185. package/dist/emit/ts/sdk-types-preamble.d.ts +1 -1
  186. package/dist/emit/ts/sdk-types-preamble.js +12 -4
  187. package/dist/emit/ts/sdk-types.d.ts +0 -5
  188. package/dist/emit/ts/sdk-types.js +63 -19
  189. package/dist/emit/ts/sdk.d.ts +3 -1
  190. package/dist/emit/ts/sdk.js +44 -12
  191. package/dist/emit/ts/service-map.d.ts +7 -1
  192. package/dist/emit/ts/service-map.js +10 -1
  193. package/dist/emit/ts/single-flight-text.d.ts +3 -0
  194. package/dist/emit/ts/single-flight-text.js +38 -0
  195. package/dist/emit/ts/tanstack-query.d.ts +3 -2
  196. package/dist/emit/ts/tanstack-query.js +60 -35
  197. package/dist/emit/ts/type-gen.js +31 -18
  198. package/dist/emit/ts/webhooks.d.ts +0 -2
  199. package/dist/emit/ts/webhooks.js +3 -3
  200. package/dist/extract/chain.js +5 -4
  201. package/dist/extract/extract.js +5 -5
  202. package/dist/extract/serialize.d.ts +0 -2
  203. package/dist/extract/serialize.js +14 -15
  204. package/dist/extract/walk.js +15 -12
  205. package/dist/gen/args.js +9 -5
  206. package/dist/gen/formatters.js +5 -3
  207. package/dist/gen/process.js +2 -1
  208. package/dist/gen/shipped.js +2 -2
  209. package/dist/gen/switch-on.constants.d.ts +2 -0
  210. package/dist/gen/switch-on.constants.js +2 -0
  211. package/dist/gen/targets.d.ts +6 -7
  212. package/dist/gen/targets.js +11 -6
  213. package/dist/gen/write.js +4 -2
  214. package/dist/index.js +2 -2
  215. package/dist/installers/cli.d.ts +4 -4
  216. package/dist/installers/cli.js +24 -24
  217. package/dist/installers/commands/build.d.ts +4 -4
  218. package/dist/installers/commands/build.js +2 -3
  219. package/dist/installers/commands/check.d.ts +2 -2
  220. package/dist/installers/commands/check.js +11 -10
  221. package/dist/installers/commands/init.d.ts +2 -2
  222. package/dist/installers/commands/init.js +1 -2
  223. package/dist/installers/config/define-config.d.ts +16 -16
  224. package/dist/installers/config/define-config.js +1 -1
  225. package/dist/installers/config/hooks/bun.d.ts +6 -6
  226. package/dist/installers/config/hooks/node.js +1 -1
  227. package/dist/installers/config/load.d.ts +6 -8
  228. package/dist/installers/config/load.js +7 -8
  229. package/dist/installers/config/resolve.d.ts +1 -2
  230. package/dist/installers/config/resolve.js +28 -33
  231. package/dist/installers/config/types.d.ts +6 -6
  232. package/dist/installers/config/types.js +0 -1
  233. package/dist/installers/render/quote.js +3 -5
  234. package/dist/installers/render/render.d.ts +6 -6
  235. package/dist/installers/render/render.js +26 -26
  236. package/dist/installers/ui.d.ts +4 -4
  237. package/dist/installers/ui.js +3 -3
  238. package/dist/ir/build.d.ts +3 -3
  239. package/dist/ir/build.js +8 -5
  240. package/dist/ir/invalidate-reads.d.ts +17 -0
  241. package/dist/ir/invalidate-reads.js +104 -0
  242. package/dist/ir/load.d.ts +10 -0
  243. package/dist/ir/load.js +65 -18
  244. package/dist/ir/model.d.ts +2 -1
  245. package/dist/ir/model.js +0 -1
  246. package/dist/ir/read-method.constants.d.ts +2 -0
  247. package/dist/ir/read-method.constants.js +2 -0
  248. package/dist/ir/resolve-refs.js +2 -2
  249. package/dist/ir/resource-tree.js +2 -1
  250. package/dist/ir/route-tree-intern.js +1 -1
  251. package/dist/ir/schema.js +3 -3
  252. package/dist/ir/sdk-model.js +3 -3
  253. package/dist/ir/slots.js +13 -8
  254. package/dist/ir/streams.js +1 -1
  255. package/dist/release/bootstrap.d.ts +3 -3
  256. package/dist/release/bootstrap.js +7 -7
  257. package/dist/release/bump-args.js +4 -4
  258. package/dist/release/bump-command.d.ts +1 -1
  259. package/dist/release/bump-command.js +9 -10
  260. package/dist/release/bump.d.ts +5 -4
  261. package/dist/release/bump.js +2 -2
  262. package/dist/release/cli.d.ts +4 -4
  263. package/dist/release/cli.js +4 -4
  264. package/dist/release/codegen.js +1 -1
  265. package/dist/release/digest.js +5 -7
  266. package/dist/release/git.js +5 -8
  267. package/dist/release/load.js +4 -4
  268. package/dist/release/manifest.js +9 -10
  269. package/dist/release/oasdiff.d.ts +10 -15
  270. package/dist/release/oasdiff.js +5 -6
  271. package/dist/release/registries.d.ts +0 -11
  272. package/dist/release/registries.js +17 -17
  273. package/dist/release/release-state.d.ts +16 -13
  274. package/dist/release/release-workflow.js +5 -7
  275. package/dist/release/repo-settings.d.ts +2 -1
  276. package/dist/release/spec-gate.d.ts +0 -2
  277. package/dist/release/spec-gate.js +6 -10
  278. package/dist/release/sync-command.d.ts +2 -2
  279. package/dist/release/sync-command.js +1 -1
  280. package/dist/release/sync-tree.js +9 -13
  281. package/dist/release/sync.d.ts +6 -6
  282. package/dist/release/sync.js +12 -13
  283. package/dist/release/types.d.ts +22 -22
  284. package/dist/release/types.js +0 -1
  285. package/dist/release/version-files.d.ts +3 -4
  286. package/dist/release/version-files.js +4 -5
  287. package/dist/runtime/.oxfmtrc.jsonc +8 -0
  288. package/dist/runtime/csharp/Config.cs +9 -1
  289. package/dist/runtime/csharp/Exchange.cs +56 -4
  290. package/dist/runtime/csharp/Hooks.cs +9 -0
  291. package/dist/runtime/csharp/Operation.cs +6 -1
  292. package/dist/runtime/csharp/WsDial.cs +3 -1
  293. package/dist/runtime/go/config.go +5 -0
  294. package/dist/runtime/go/hooks.go +70 -0
  295. package/dist/runtime/go/request.go +6 -2
  296. package/dist/runtime/go/stream.go +4 -1
  297. package/dist/runtime/go/ws.go +3 -1
  298. package/dist/runtime/java/ClientConfig.java +11 -0
  299. package/dist/runtime/java/Flight.java +2 -12
  300. package/dist/runtime/java/Hooks.java +45 -0
  301. package/dist/runtime/java/InvalidateEvent.java +10 -0
  302. package/dist/runtime/java/InvalidateHook.java +12 -0
  303. package/dist/runtime/java/InvalidateTarget.java +7 -0
  304. package/dist/runtime/java/Operation.java +23 -3
  305. package/dist/runtime/java/Realtime.java +3 -1
  306. package/dist/runtime/java/WsDial.java +3 -0
  307. package/dist/runtime/mcp/files.ts +1 -1
  308. package/dist/runtime/mcp/http.ts +6 -2
  309. package/dist/runtime/mcp/listen.ts +1 -1
  310. package/dist/runtime/mcp/mount.ts +2 -2
  311. package/dist/runtime/mcp/protocol.ts +1 -1
  312. package/dist/runtime/python/config.py +8 -2
  313. package/dist/runtime/python/exchange.py +3 -1
  314. package/dist/runtime/python/hooks.py +110 -5
  315. package/dist/runtime/python/operation.py +2 -0
  316. package/dist/runtime/python/send_async.py +14 -2
  317. package/dist/runtime/python/send_sync.py +4 -2
  318. package/dist/runtime/python/ws.py +5 -1
  319. package/dist/runtime/rust/config.rs +6 -1
  320. package/dist/runtime/rust/exchange.rs +15 -3
  321. package/dist/runtime/rust/hooks.rs +127 -2
  322. package/dist/runtime/rust/log.rs +11 -3
  323. package/dist/runtime/rust/request.rs +17 -0
  324. package/dist/runtime/rust/ws.rs +9 -1
  325. package/dist/runtime/ts/config.ts +69 -0
  326. package/dist/runtime/ts/http.ts +12 -10
  327. package/dist/runtime/ts/request.ts +2 -0
  328. package/dist/runtime/ts/response.ts +7 -0
  329. package/dist/runtime/ts/sdk-invalidate.ts +82 -0
  330. package/dist/runtime/ts/sdk-single-flight.constants.ts +25 -0
  331. package/dist/runtime/ts/sdk-single-flight.ts +203 -0
  332. package/dist/runtime/ts/sdk-sse.ts +5 -1
  333. package/dist/runtime/ts/sdk-ws.ts +9 -3
  334. package/dist/runtime/ts/sdk.ts +55 -31
  335. package/dist/runtime/ts/single-flight-batch.ts +184 -0
  336. package/dist/runtime/ts/single-flight-body.ts +59 -0
  337. package/dist/runtime/ts/single-flight-run.ts +160 -0
  338. package/dist/runtime/ts/single-flight.constants.ts +31 -0
  339. package/dist/runtime/ts/single-flight.ts +158 -0
  340. package/dist/runtime/ts-tanstack-query/invalidate.ts +96 -92
  341. package/dist/runtime/ts-tanstack-query/query.ts +140 -170
  342. package/package.json +12 -17
  343. package/references/INDEX.md +31 -0
  344. package/references/cli.md +33 -0
  345. package/references/configuring.md +29 -0
  346. package/references/documentation.md +15 -0
  347. package/references/errors.md +23 -0
  348. package/references/flags.md +104 -0
  349. package/references/gates.md +46 -0
  350. package/references/generate.md +29 -0
  351. package/references/install-scripts.md +28 -0
  352. package/references/install.md +38 -0
  353. package/references/license.md +8 -0
  354. package/references/mcp.md +76 -0
  355. package/references/output.md +45 -0
  356. package/references/overview.md +14 -0
  357. package/references/release-tooling.md +34 -0
  358. package/references/release.md +305 -0
  359. package/references/sdks.md +393 -0
  360. package/references/start.md +22 -0
  361. package/references/tdd.md +16 -0
  362. package/dist/emit/cli/index.d.ts +0 -1
  363. package/dist/emit/cli/index.js +0 -1
  364. package/dist/emit/csharp/index.d.ts +0 -1
  365. package/dist/emit/csharp/index.js +0 -1
  366. package/dist/emit/go/index.d.ts +0 -1
  367. package/dist/emit/go/index.js +0 -1
  368. package/dist/emit/java/index.d.ts +0 -2
  369. package/dist/emit/java/index.js +0 -2
  370. package/dist/emit/mcp/index.d.ts +0 -3
  371. package/dist/emit/mcp/index.js +0 -3
  372. package/dist/emit/python/index.d.ts +0 -1
  373. package/dist/emit/python/index.js +0 -1
  374. package/dist/emit/rust/index.d.ts +0 -1
  375. 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
- * `@tanstack/query-core` is imported for types only: an emitted SDK is loaded from the consumer's own tree
13
- * (and, in this repository's tests, from outside it), so a value import would have to resolve at run time.
14
- * That is also why a read's options carry `initialData: undefined` — solid-query reads
15
- * `initialData?: Data | undefined` as the seeded overload, and the consumer that drives this is Solid.
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
- MutationObserverOptions,
23
- QueryClient,
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
- type Req<M> = M extends (req: infer R, ...rest: never[]) => unknown ? R : never
53
- type Init<M> = M extends (req: never, init: infer I, ...rest: never[]) => unknown ? I : never
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
- /** `{ req }` is optional only when the request itself has no required field. */
57
- type ReqOptions<M> = {} extends Req<M> ? { init?: Init<M>; req?: Req<M> } : { init?: Init<M>; req: Req<M> }
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
- type ReadOptions<M> =
60
- {} extends Req<M>
61
- ? { queryProps?: Omit<QueryObserverOptions<Data<M>>, "queryFn" | "queryKey">; reqOptions?: ReqOptions<M> }
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 options, keyed and seeded: `queryKey` is tagged so a cache read infers the answer. */
65
- export type QueryFactory<M> = (
66
- ...args: {} extends Req<M> ? [options?: ReadOptions<M>] : [options: ReadOptions<M>]
67
- ) => QueryObserverOptions<Data<M>, DefaultError, Data<M>, Data<M>, QueryKey> & {
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
- /** A write's options; `mutate` takes the SDK's own input, so a call site reads like the SDK call. */
73
- export type MutationFactory<M> = (options?: {
74
- mutationProps?: Omit<MutationObserverOptions<Data<M>, DefaultError, Req<M>>, "mutationFn" | "mutationKey">
75
- }) => MutationObserverOptions<Data<M>, DefaultError, Req<M>> & {
76
- mutationFn: (input: Req<M>) => Promise<Data<M>>
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
- /** A paged read: the caller says how a page param becomes a request and where the next one comes from. */
81
- export type InfiniteFactory<M> = <TPageParam = number>(options: {
82
- buildReqOptions: (pageParam: TPageParam) => { init?: Init<M>; req: Req<M> }
83
- getNextPageParam: (
84
- lastPage: Data<M>,
85
- allPages: Data<M>[],
86
- lastPageParam: TPageParam,
87
- allPageParams: TPageParam[],
88
- ) => TPageParam | null | undefined
89
- getPreviousPageParam?: (
90
- firstPage: Data<M>,
91
- allPages: Data<M>[],
92
- firstPageParam: TPageParam,
93
- allPageParams: TPageParam[],
94
- ) => TPageParam | null | undefined
95
- infiniteQueryProps?: Omit<
96
- InfiniteQueryObserverOptions<Data<M>, DefaultError, InfiniteData<Data<M>>, QueryKey, TPageParam>,
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 builder: the request in, the key the matching factory would use out. */
103
- export type KeyFactory<M> = (req?: Req<M>) => QueryKey
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, so which
108
- * names exist and what each one takes is not knowable at this layer. The emitted
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
- function readSdk<T>(source: SdkSource<T>): T {
119
- return typeof source === "function" ? (source as () => T)() : source
120
- }
92
+ type Kind = "infiniteQuery" | "mutation" | "query" | "queryKey" | "mutationKey"
121
93
 
122
- /** The member path's method on the SDK, read when the call is made so a thunk stays per-call. */
123
- function methodAt(sdk: unknown, member: readonly string[]): AnyMethod {
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
- type Kind = "infiniteQuery" | "mutation" | "query" | "queryKey" | "mutationKey"
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
- getQueryClient?: (() => QueryClient) | undefined
140
- map: ServiceMap
141
- reads: Map<string, Read>
142
- sdk: SdkSource<unknown>
143
- sdkName: string
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
- function queryOptionsAt(ctx: Context, member: string[]) {
147
- return (options?: { queryProps?: object; reqOptions?: { init?: unknown; req?: unknown } }) => {
148
- const { init, req } = options?.reqOptions ?? {}
149
- const args = init === undefined ? [req] : [req, init]
150
- return {
151
- queryFn: () => methodAt(readSdk(ctx.sdk), member)(...args),
152
- queryKey: readKey(ctx.sdkName, member, req),
153
- ...options?.queryProps,
154
- /* after the spread: a caller's queryProps cannot un-seed the Solid overload */
155
- initialData: undefined,
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 mutationOptionsAt(ctx: Context, member: string[], entry: ServiceEntry) {
161
- return (options?: { mutationProps?: object }) => ({
162
- mutationFn: async (input: unknown) => {
163
- const data = await methodAt(readSdk(ctx.sdk), member)(input)
164
- const client = ctx.getQueryClient?.()
165
- if (client !== undefined) {
166
- const keys = invalidatedBy(ctx.reads, ctx.sdkName, entry, input)
167
- await Promise.all(keys.map((queryKey) => client.invalidateQueries({ queryKey })))
168
- }
169
- return data
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 (options: {
178
- buildReqOptions: (pageParam: unknown) => { init?: unknown; req: unknown }
179
- infiniteQueryProps?: object
180
- initialPageParam: unknown
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 keyFactoryAt(ctx: Context, member: string[]) {
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[], entry: ServiceEntry): unknown {
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, entry)
188
+ if (surface === "mutation") return mutationOptionsAt(ctx, member)
204
189
  if (surface === "infiniteQuery") return infiniteOptionsAt(ctx, member)
205
- return keyFactoryAt(ctx, member)
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, member: string[]): unknown {
214
- return new Proxy(Object.create(null) as object, {
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 at = [...member, key]
220
- if (!isEntry(child)) return surfaceProxy(ctx, surface, child as ServiceMap, at)
221
- return surfaceOf(child, surface) ? factoryFor(ctx, surface, at, child) : undefined
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 for `sdk` over `map`. `sdkName` heads every key, so two SDKs in one cache never collide.
231
- * The emitted wrapper passes its own map and name and types each surface from the document, the way the
232
- * generated client passes its map to `SDKClient`.
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<TSDK>(
235
- sdk: SdkSource<TSDK>,
236
- map: ServiceMap,
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: of("infiniteQuery"),
256
- mutation: of("mutation"),
257
- mutationKey: of("mutationKey"),
258
- query: of("query"),
259
- queryKey: of("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.29",
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).