@cratestack/runtime-axios 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,22 @@
+# @cratestack/runtime-axios
+
+A `typeof fetch`-compatible transport for CrateStack's generated TypeScript RPC client
+(`transport rpc` schemas), backed by [axios](https://axios-http.com/) instead of the global
+`fetch` — useful for environments where axios is already the house HTTP client (interceptors,
+proxy/agent config, request/response transforms you don't want to reimplement).
+
+## Usage
+
+```ts
+import { createAxiosRuntime } from "@cratestack/runtime-axios";
+import { CratestackRpcRuntime } from "./generated/runtime"; // your project's generated client
+import myAxiosInstance from "./my-axios-instance";
+
+const runtime = new CratestackRpcRuntime("https://api.example.com", {
+  fetch: createAxiosRuntime({ instance: myAxiosInstance }), // defaults to the `axios` singleton
+});
+```
+
+Every request is issued with `validateStatus: () => true` — a non-2xx response comes back as a
+normal `Response` (so `CratestackRpcRuntime`/`RpcLink`s can inspect `response.status` and decode
+the server's `RpcErrorBody` themselves) rather than axios throwing an `AxiosError`.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { type AxiosInstance } from "axios";
+/** Options for {@link createAxiosRuntime}. */
+export interface AxiosRuntimeOptions {
+    /** Axios instance to issue requests through — e.g. one preconfigured
+     *  with interceptors, a base URL, or a custom `httpsAgent`. Defaults
+     *  to the top-level `axios` singleton. */
+    instance?: AxiosInstance;
+}
+/** Adapts an axios instance to the `typeof fetch` signature so it can be
+ *  passed as `CratestackRpcClientOptions.fetch` (the generated runtime's
+ *  constructor option) or as an `RpcLink`'s `request.fetchFn` override —
+ *  axios becomes the actual transport while every link and the
+ *  generated runtime keep speaking the Fetch API's `Request`/`Response`
+ *  shape, unaware anything changed underneath. */
+export declare function createAxiosRuntime(options?: AxiosRuntimeOptions): typeof fetch;
+//# 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,OAAc,EAAE,KAAK,aAAa,EAAwC,MAAM,OAAO,CAAC;AASxF,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IAClC;;8CAE0C;IAC1C,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAED;;;;;kDAKkD;AAClD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,KAAK,CAqClF"}

package/dist/index.js

@@ -0,0 +1,101 @@
+import axios from "axios";
+// The Fetch API's `Response` constructor throws if given a non-null body
+// alongside one of these statuses (https://fetch.spec.whatwg.org/#null-body-status)
+// — even an empty `ArrayBuffer` counts as "non-null". axios always hands
+// back a `data` buffer regardless of status, so it has to be dropped
+// explicitly here rather than passed through.
+const NULL_BODY_STATUSES = new Set([204, 205, 304]);
+/** Adapts an axios instance to the `typeof fetch` signature so it can be
+ *  passed as `CratestackRpcClientOptions.fetch` (the generated runtime's
+ *  constructor option) or as an `RpcLink`'s `request.fetchFn` override —
+ *  axios becomes the actual transport while every link and the
+ *  generated runtime keep speaking the Fetch API's `Request`/`Response`
+ *  shape, unaware anything changed underneath. */
+export function createAxiosRuntime(options = {}) {
+    const instance = options.instance ?? axios;
+    return (async (input, init) => {
+        const resolved = await resolveRequest(input, init);
+        const config = {
+            url: resolved.url,
+            method: resolved.method,
+            headers: headersToObject(resolved.headers),
+            data: resolved.body,
+            // Built via conditional spread, not `signal: resolved.signal ??
+            // undefined` — with `exactOptionalPropertyTypes: true`, explicitly
+            // assigning `undefined` to `signal` isn't the same as omitting the
+            // key, and axios's `GenericAbortSignal` type (unlike `data`, which
+            // is `any`) rejects it.
+            ...(resolved.signal ? { signal: resolved.signal } : {}),
+            responseType: "arraybuffer",
+            // The generated runtime and every `RpcLink` decide success/failure
+            // from `response.status`/`response.ok` themselves (see
+            // `CratestackRpcRuntime.readUnaryResponse`) — axios's default of
+            // throwing on a non-2xx status would short-circuit that and turn
+            // every server-side `RpcErrorBody` into a thrown `AxiosError`
+            // instead of a normal `Response` the caller can inspect.
+            validateStatus: () => true,
+        };
+        const response = await instance.request(config);
+        return new Response(NULL_BODY_STATUSES.has(response.status) ? null : response.data, {
+            status: response.status,
+            statusText: response.statusText,
+            headers: axiosHeadersToFetchHeaders(response.headers),
+        });
+    });
+}
+/** The generated runtime only ever calls `fetchFn(url, init)` with a
+ *  string URL and a populated `init` — this function's `Request`
+ *  handling exists purely for `typeof fetch` compatibility with callers
+ *  that pass a pre-built `Request` (e.g. from another link/middleware).
+ *  `init`'s fields, when present, override the `Request`'s own — same
+ *  precedence the real Fetch API gives `fetch(request, init)`. */
+async function resolveRequest(input, init) {
+    if (typeof input === "string" || input instanceof URL) {
+        return {
+            url: input.toString(),
+            method: init?.method ?? "GET",
+            headers: init?.headers,
+            body: init?.body ?? undefined,
+            signal: init?.signal ?? undefined,
+        };
+    }
+    return {
+        url: input.url,
+        method: init?.method ?? input.method,
+        headers: init?.headers ?? input.headers,
+        body: init?.body !== undefined
+            ? init.body
+            : input.body !== null
+                ? await input.clone().arrayBuffer()
+                : undefined,
+        signal: init?.signal ?? input.signal,
+    };
+}
+function headersToObject(headers) {
+    const result = {};
+    if (!headers) {
+        return result;
+    }
+    // `.forEach()` (rather than `.entries()`/`for...of`) is the one
+    // iteration style declared on `Headers` consistently across both the
+    // DOM lib type and the Node/undici one that `axios`'s own type
+    // dependencies can pull into scope — the other two aren't.
+    new Headers(headers).forEach((value, key) => {
+        result[key] = value;
+    });
+    return result;
+}
+function axiosHeadersToFetchHeaders(headers) {
+    const result = new Headers();
+    if (typeof headers !== "object" || headers === null) {
+        return result;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (value === undefined) {
+            continue;
+        }
+        result.set(key, Array.isArray(value) ? value.join(", ") : String(value));
+    }
+    return result;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cratestack/runtime-axios",
+  "version": "0.5.2",
+  "description": "A typeof-fetch-compatible transport for CrateStack's generated TypeScript RPC client, backed by axios.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cratestack/cratestack.git",
+    "directory": "packages/cratestack-runtime-axios"
+  },
+  "homepage": "https://cratestack.dev",
+  "bugs": "https://github.com/cratestack/cratestack/issues",
+  "keywords": ["cratestack", "cstack", "rpc", "axios", "runtime"],
+  "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 ."
+  },
+  "peerDependencies": {
+    "axios": "^1.7.0"
+  },
+  "peerDependenciesMeta": {
+    "axios": { "optional": true }
+  },
+  "devDependencies": {
+    "axios": "^1.7.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}