@cratestack/adapter-tanstack-query 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stephane Segning
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @cratestack/adapter-tanstack-query
+
+Generic [TanStack Query](https://tanstack.com/query) option builders over CrateStack's generated
+TypeScript RPC client (`transport rpc` schemas), for hand-written query/mutation hooks that don't
+go through the fully-generated `use{Model}Query`/`use{Model}Mutation` hooks
+(`cratestack generate-typescript`'s own `rpc-react-query.ts.j2` output) — e.g. calling a
+`procedure` the generated hooks don't cover yet, or using vue-query/solid-query/svelte-query
+instead of `@tanstack/react-query`.
+
+Framework-agnostic: everything here is typed against `@tanstack/query-core`, which every TanStack
+Query framework binding builds on.
+
+## Usage
+
+```ts
+import { rpcQueryOptions, rpcMutationOptions, isRpcErrorCode } from "@cratestack/adapter-tanstack-query";
+import { useQuery, useMutation } from "@tanstack/react-query";
+import { client } from "./generated/client"; // your project's generated client instance
+
+function useWidget(id: number) {
+  return useQuery({
+    ...rpcQueryOptions(client.runtime, "model.Widget.get", { id }),
+    retry: (failureCount, error) => !isRpcErrorCode(error, "not_found") && failureCount < 3,
+  });
+}
+
+function useCreateOrder() {
+  return useMutation(rpcMutationOptions(client.runtime, "model.Order.create"));
+}
+```
+
+`rpcQueryOptions`/`rpcMutationOptions` take an `RpcCaller` — any object with a
+`call<I, O>(opId, input, options?)` method, which is exactly the shape of a generated client's
+public `.runtime` field (`CratestackRpcRuntime`). Requests issued this way go through the same
+`links` chain (`@cratestack/link-batch`, `@cratestack/link-logger`, etc.) as every other call on
+that runtime.

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import type { RpcCaller } from "@cratestack/ts-types";
+import type { QueryKey } from "@tanstack/query-core";
+export type { RpcCaller } from "@cratestack/ts-types";
+/** The `[opId, input]` tuple every helper below keys its query/mutation
+ *  on — exported so callers can `queryClient.invalidateQueries({ queryKey: rpcQueryKey(opId, input) })`
+ *  without re-deriving the same shape by hand. */
+export declare function rpcQueryKey(opId: string, input?: unknown): QueryKey;
+/** Builds a `{ queryKey, queryFn }` pair for `useQuery` (or its
+ *  vue-query/solid-query/svelte-query equivalents — all built on
+ *  `@tanstack/query-core`) from a single unary RPC call. Framework-
+ *  agnostic: pass the result straight through, or spread it alongside
+ *  your own `staleTime`/`enabled`/etc. */
+export declare function rpcQueryOptions<I, O>(client: RpcCaller, opId: string, input: I): {
+    queryKey: QueryKey;
+    queryFn: (context: {
+        signal: AbortSignal;
+    }) => Promise<O>;
+};
+/** Builds a `{ mutationKey, mutationFn }` pair for `useMutation`. The
+ *  input is supplied at call time (`mutate(input)`), not here — mirrors
+ *  the generated `useCreateXMutation`/`useUpdateXMutation` hooks'
+ *  shape. */
+export declare function rpcMutationOptions<I, O>(client: RpcCaller, opId: string): {
+    mutationKey: QueryKey;
+    mutationFn: (input: I) => Promise<O>;
+};
+/** True when `error` is a `CratestackRpcError`-shaped value (or a
+ *  decoded `RpcErrorBody`) whose `code` matches — structural, not an
+ *  `instanceof` check, since `CratestackRpcError` is a per-project
+ *  generated class with no shared import path. Useful in
+ *  `retry`/`throwOnError` callbacks, e.g. never retrying a
+ *  `"not_found"`. */
+export declare function isRpcErrorCode(error: unknown, code: string): boolean;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,YAAY,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;kDAEkD;AAClD,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,CAEnE;AAED;;;;0CAI0C;AAC1C,wBAAgB,eAAe,CAAC,CAAC,EAAE,CAAC,EAClC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,CAAC,GACP;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAKnF;AAED;;;aAGa;AACb,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,CAAC,EACrC,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,MAAM,GACX;IAAE,WAAW,EAAE,QAAQ,CAAC;IAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAKjE;AAED;;;;;qBAKqB;AACrB,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpE"}

package/dist/index.js

@@ -0,0 +1,40 @@
+/** The `[opId, input]` tuple every helper below keys its query/mutation
+ *  on — exported so callers can `queryClient.invalidateQueries({ queryKey: rpcQueryKey(opId, input) })`
+ *  without re-deriving the same shape by hand. */
+export function rpcQueryKey(opId, input) {
+    return input === undefined ? [opId] : [opId, input];
+}
+/** Builds a `{ queryKey, queryFn }` pair for `useQuery` (or its
+ *  vue-query/solid-query/svelte-query equivalents — all built on
+ *  `@tanstack/query-core`) from a single unary RPC call. Framework-
+ *  agnostic: pass the result straight through, or spread it alongside
+ *  your own `staleTime`/`enabled`/etc. */
+export function rpcQueryOptions(client, opId, input) {
+    return {
+        queryKey: rpcQueryKey(opId, input),
+        queryFn: ({ signal }) => client.call(opId, input, { signal }),
+    };
+}
+/** Builds a `{ mutationKey, mutationFn }` pair for `useMutation`. The
+ *  input is supplied at call time (`mutate(input)`), not here — mirrors
+ *  the generated `useCreateXMutation`/`useUpdateXMutation` hooks'
+ *  shape. */
+export function rpcMutationOptions(client, opId) {
+    return {
+        mutationKey: [opId],
+        mutationFn: (input) => client.call(opId, input),
+    };
+}
+/** True when `error` is a `CratestackRpcError`-shaped value (or a
+ *  decoded `RpcErrorBody`) whose `code` matches — structural, not an
+ *  `instanceof` check, since `CratestackRpcError` is a per-project
+ *  generated class with no shared import path. Useful in
+ *  `retry`/`throwOnError` callbacks, e.g. never retrying a
+ *  `"not_found"`. */
+export function isRpcErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA;;kDAEkD;AAClD,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,KAAe;IACvD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC;AAED;;;;0CAI0C;AAC1C,MAAM,UAAU,eAAe,CAC7B,MAAiB,EACjB,IAAY,EACZ,KAAQ;IAER,OAAO;QACL,QAAQ,EAAE,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC;QAClC,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAO,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,CAAC;KACpE,CAAC;AACJ,CAAC;AAED;;;aAGa;AACb,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,IAAY;IAEZ,OAAO;QACL,WAAW,EAAE,CAAC,IAAI,CAAC;QACnB,UAAU,EAAE,CAAC,KAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAO,IAAI,EAAE,KAAK,CAAC;KACzD,CAAC;AACJ,CAAC;AAED;;;;;qBAKqB;AACrB,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAY;IACzD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,MAAM,IAAI,KAAK;QACd,KAA2B,CAAC,IAAI,KAAK,IAAI,CAC3C,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@cratestack/adapter-tanstack-query",
+  "version": "0.5.2",
+  "description": "Generic TanStack Query option builders (query/mutation) over CrateStack's generated TypeScript RPC client.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cratestack/cratestack.git",
+    "directory": "packages/cratestack-adapter-tanstack-query"
+  },
+  "homepage": "https://cratestack.dev",
+  "bugs": "https://github.com/cratestack/cratestack/issues",
+  "keywords": ["cratestack", "cstack", "rpc", "tanstack-query", "react-query"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "biome check ."
+  },
+  "dependencies": {
+    "@cratestack/ts-types": "0.5.2"
+  },
+  "peerDependencies": {
+    "@tanstack/query-core": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/query-core": { "optional": true }
+  },
+  "devDependencies": {
+    "@tanstack/query-core": "^5.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}