@cratestack/ts-types 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,40 @@
+# @cratestack/ts-types
+
+Shared TypeScript interfaces for CrateStack's generated TypeScript RPC client (`transport rpc`
+schemas) and for the rest of the `@cratestack/*` npm family (`link-*`, `runtime-*`, `validator-*`,
+`adapter-*`).
+
+Pinned local copies of the wire/link contract generated into every CrateStack `transport rpc`
+project by `crates/cratestack-client-typescript/templates/src/rpc-links.ts.j2` and
+`rpc-runtime.ts.j2` ([issue #182](https://github.com/cratestack/cratestack/issues/182)). Kept as
+plain interfaces/function types deliberately — a generated project's `CratestackRpcRuntime` is a
+per-project class with no shared import path, so this package can't (and doesn't need to) import
+it; TypeScript's structural typing means any object shaped like these types is assignable into a
+generated client's `links` array, regardless of which project generated it.
+
+This package has **no runtime code** — every export is an `interface` or `type`, so it compiles
+away to (essentially) nothing. Everything else in the `@cratestack/*` family depends on it for
+types only (`import type`), so pulling in `link-batch`, `validator-zod`, etc. never adds this
+package's weight to your bundle.
+
+## Exports
+
+- **`.`** — `RpcLink`, `RpcLinkRequest`, `RpcLinkResponse`, `RpcLinkNext`, `CratestackRpcCodec`,
+  `RpcRequest`, `RpcResponseFrame`, `RpcErrorBody`.
+- **`./test-harness`** — `FakeRuntime`, a minimal in-memory runtime that mirrors
+  `CratestackRpcRuntime`'s chain construction exactly, for testing `RpcLink` implementations
+  against a real chain instead of a reimplementation of one. Not part of the public API surface —
+  used by this package's own tests and by every other `@cratestack/*` package's test suite.
+
+## Usage
+
+```ts
+import type { RpcLink } from "@cratestack/ts-types";
+
+export function createMyLink(): RpcLink {
+  return async (request, next) => {
+    // ...
+    return next(request);
+  };
+}
+```

package/dist/index.d.ts

@@ -0,0 +1,65 @@
+/** One request going through the chain — mirrors the generated
+ *  `RpcLinkRequest`. */
+export interface RpcLinkRequest {
+    readonly kind: "unary" | "batch";
+    readonly opId: string;
+    readonly input: unknown;
+    readonly headers: Headers;
+    readonly signal: AbortSignal | null;
+    readonly idempotencyKey?: string;
+    readonly codec: CratestackRpcCodec;
+    readonly fetchFn: typeof fetch;
+    readonly urls: {
+        unary(opId: string): string;
+        batch(): string;
+    };
+}
+/** Mirrors the generated `RpcLinkResponse`. */
+export interface RpcLinkResponse {
+    readonly response: Response;
+}
+export type RpcLinkNext = (request: RpcLinkRequest) => Promise<RpcLinkResponse>;
+/** Mirrors the generated `RpcLink`. */
+export type RpcLink = (request: RpcLinkRequest, next: RpcLinkNext) => Promise<RpcLinkResponse>;
+/** Mirrors the generated `CratestackRpcCodec`. */
+export interface CratestackRpcCodec {
+    readonly contentType: string;
+    encode(value: unknown): BodyInit;
+    decode(bytes: Uint8Array): unknown;
+}
+/** Wire shape of a single `/rpc/batch` request frame — mirrors the
+ *  generated `RpcRequest`. */
+export interface RpcRequest<I = unknown> {
+    id: number;
+    op: string;
+    input: I;
+    idem?: string;
+}
+/** Wire shape of a single `/rpc/batch` response frame — mirrors the
+ *  generated `RpcResponseFrame`. */
+export interface RpcResponseFrame<O = unknown> {
+    id: number;
+    output?: O;
+    error?: RpcErrorBody;
+}
+/** Mirrors the generated `RpcErrorBody`. */
+export interface RpcErrorBody {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+/** Structural match for `CratestackRpcRuntime.call()` (see
+ *  `crates/cratestack-client-typescript/templates/src/rpc-runtime.ts.j2`)
+ *  — a generated client exposes this as its public `.runtime` field, so
+ *  e.g. `rpcQueryOptions(client.runtime, opId, input)`
+ *  (`@cratestack/adapter-tanstack-query`) or
+ *  `createRpcBaseQuery(client.runtime)` (`@cratestack/adapter-rtk`) work
+ *  against any generated project without either package importing its
+ *  (per-project, unshared) class. Shared here rather than duplicated
+ *  per adapter package, since both need the exact same contract. */
+export interface RpcCaller {
+    call<I, O>(opId: string, input: I, options?: {
+        signal?: AbortSignal;
+    }): Promise<O>;
+}
+//# 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":"AAUA;wBACwB;AACxB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,OAAO,KAAK,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE;QACb,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;QAC5B,KAAK,IAAI,MAAM,CAAC;KACjB,CAAC;CACH;AAED,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEhF,uCAAuC;AACvC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAE/F,kDAAkD;AAClD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;CACpC;AAED;8BAC8B;AAC9B,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;oCACoC;AACpC,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,CAAC,CAAC;IACX,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;oEAQoE;AACpE,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACpF"}

package/dist/index.js

@@ -0,0 +1,11 @@
+// Pinned local copies of the wire/link contract generated into every
+// CrateStack `transport rpc` project by
+// `crates/cratestack-client-typescript/templates/src/rpc-links.ts.j2` and
+// `rpc-runtime.ts.j2` (issue #182). Kept as plain interfaces/function
+// types deliberately — a generated project's `CratestackRpcRuntime` is a
+// per-project class with no shared import path, so this package can't
+// (and doesn't need to) import it; TypeScript's structural typing means
+// any object shaped like these types is assignable into a generated
+// client's `links` array, regardless of which project generated it.
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,wCAAwC;AACxC,0EAA0E;AAC1E,sEAAsE;AACtE,yEAAyE;AACzE,sEAAsE;AACtE,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE"}

package/dist/test-harness.d.ts

@@ -0,0 +1,25 @@
+import type { RpcLink } from "./index.js";
+export declare const jsonCodec: {
+    contentType: string;
+    encode(value: unknown): BodyInit;
+    decode(bytes: Uint8Array): unknown;
+};
+/** Mirrors `CratestackRpcRuntime`'s chain construction and `call()`/
+ *  `batch()` request-building exactly (see
+ *  `crates/cratestack-client-typescript/templates/src/rpc-runtime.ts.j2`),
+ *  so these tests exercise the real generated contract rather than a
+ *  reimplementation of it. Exported (as `@cratestack/ts-types/test-harness`,
+ *  not part of the public `.` entry point) so every other `@cratestack/*`
+ *  package's own test suite can exercise its `RpcLink` against a real
+ *  chain instead of each maintaining its own copy. */
+export declare class FakeRuntime {
+    private readonly chain;
+    private readonly fetchFn;
+    constructor(fetchFn: typeof fetch, links?: RpcLink[]);
+    call<O>(opId: string, input: unknown, opts?: {
+        signal?: AbortSignal;
+        idempotencyKey?: string;
+    }): Promise<O>;
+    batch(requests: unknown[]): Promise<unknown>;
+}
+//# sourceMappingURL=test-harness.d.ts.map

package/dist/test-harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-harness.d.ts","sourceRoot":"","sources":["../src/test-harness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAA+B,MAAM,YAAY,CAAC;AAEvE,eAAO,MAAM,SAAS;;kBAEN,OAAO,GAAG,QAAQ;kBAGlB,UAAU,GAAG,OAAO;CAMnC,CAAC;AAaF;;;;;;;sDAOsD;AACtD,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAc;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;gBAE3B,OAAO,EAAE,OAAO,KAAK,EAAE,KAAK,GAAE,OAAO,EAAO;IAQlD,IAAI,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,EACd,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAO,GAC3D,OAAO,CAAC,CAAC,CAAC;IA2BP,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC;CAkBnD"}

package/dist/test-harness.js

@@ -0,0 +1,83 @@
+export const jsonCodec = {
+    contentType: "application/json",
+    encode(value) {
+        return JSON.stringify(value ?? null);
+    },
+    decode(bytes) {
+        if (bytes.length === 0) {
+            return undefined;
+        }
+        return JSON.parse(new TextDecoder().decode(bytes));
+    },
+};
+const terminalLink = async (request) => {
+    const url = request.kind === "batch" ? request.urls.batch() : request.urls.unary(request.opId);
+    const response = await request.fetchFn(url, {
+        method: "POST",
+        headers: request.headers,
+        body: request.codec.encode(request.input),
+        signal: request.signal,
+    });
+    return { response };
+};
+/** Mirrors `CratestackRpcRuntime`'s chain construction and `call()`/
+ *  `batch()` request-building exactly (see
+ *  `crates/cratestack-client-typescript/templates/src/rpc-runtime.ts.j2`),
+ *  so these tests exercise the real generated contract rather than a
+ *  reimplementation of it. Exported (as `@cratestack/ts-types/test-harness`,
+ *  not part of the public `.` entry point) so every other `@cratestack/*`
+ *  package's own test suite can exercise its `RpcLink` against a real
+ *  chain instead of each maintaining its own copy. */
+export class FakeRuntime {
+    chain;
+    fetchFn;
+    constructor(fetchFn, links = []) {
+        this.fetchFn = fetchFn;
+        this.chain = links.reduceRight((next, link) => (request) => link(request, next), terminalLink);
+    }
+    async call(opId, input, opts = {}) {
+        const request = {
+            kind: "unary",
+            opId,
+            input: input ?? null,
+            headers: new Headers(),
+            signal: opts.signal ?? null,
+            ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+            codec: jsonCodec,
+            fetchFn: this.fetchFn,
+            urls: {
+                unary: (id) => `https://example.test/rpc/${id}`,
+                batch: () => "https://example.test/rpc/batch",
+            },
+        };
+        const { response } = await this.chain(request);
+        if (response.status === 204) {
+            return undefined;
+        }
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        if (!response.ok) {
+            const body = jsonCodec.decode(bytes);
+            throw new Error(`rpc error ${body.code}: ${body.message}`);
+        }
+        return jsonCodec.decode(bytes);
+    }
+    async batch(requests) {
+        const request = {
+            kind: "batch",
+            opId: "batch",
+            input: requests,
+            headers: new Headers(),
+            signal: null,
+            codec: jsonCodec,
+            fetchFn: this.fetchFn,
+            urls: {
+                unary: (id) => `https://example.test/rpc/${id}`,
+                batch: () => "https://example.test/rpc/batch",
+            },
+        };
+        const { response } = await this.chain(request);
+        const bytes = new Uint8Array(await response.arrayBuffer());
+        return jsonCodec.decode(bytes);
+    }
+}
+//# sourceMappingURL=test-harness.js.map

package/dist/test-harness.js.map

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cratestack/ts-types",
+  "version": "0.5.2",
+  "description": "Shared TypeScript interfaces for CrateStack's generated RPC client (RpcLink, RpcLinkRequest, wire frame shapes). Types only — compiles to near-empty JS.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cratestack/cratestack.git",
+    "directory": "packages/cratestack-ts-types"
+  },
+  "homepage": "https://cratestack.dev",
+  "bugs": "https://github.com/cratestack/cratestack/issues",
+  "keywords": ["cratestack", "cstack", "rpc", "types", "trpc-links"],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./test-harness": {
+      "types": "./dist/test-harness.d.ts",
+      "import": "./dist/test-harness.js"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "biome check ."
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}