spectype

Generate a thin, correct, learnable TypeScript client from TypeSpec — types, zod schemas, an HTTP client, and TanStack Query helpers. Bring your own axios/ky instance; the generated code imposes no base URL, auth, or interceptors.

Install

npm install --save-dev @risemaxi/spectype

Quick start

# tspconfig.yaml
emit:
  - "@risemaxi/spectype"
options:
  "@risemaxi/spectype":
    emitter-output-dir: "{project-root}/tsp-output/client"
    validator: zod # zod | zod3 | valibot
    httpClient: axios # axios | ky
    generate:
      tanstack: react # react | off

import { setClient } from "./tsp-output/client/client.js";
import axios from "axios";

// optional — defaults to axios.create(); configure once if you need a baseURL/auth
setClient(axios.create({ baseURL: "https://api.example.com" }));

import { listItems, createItem, handleCreateItemError } from "./tsp-output/client/api/items.js";

const items = await listItems({ query: { limit: 20 } }); // JSON-deserialized, typed
try {
  await createItem({ body: { name: "Widget" } });
} catch (e) {
  handleCreateItemError(e, {
    http: { 400: (body) => console.error(body) },
    fallback: (err) => {
      throw err;
    },
  });
}

Generated layout

types.ts       interfaces, unions (incl. @discriminator), enums, scalars
schemas.ts     validation schemas (1:1 with types), non-transforming
client.ts      default instance + setClient, error handler, form-data, path/query, paging helpers
api/<group>.ts per-group operations + TanStack Query options
index.ts       barrel

Design

• Bring-your-own-client. client.ts ships a default axios.create()/ky.create() and a setClient(instance); operations read the live binding (no per-call overhead).
• JSON-deserialized, no surprises. Operations return the parsed JSON body; dates/ bytes/decimals stay strings. Schemas are non-transforming, so opt-in parse validates without changing the type or shape.
• Response payload optional ⟺ null. For response/body properties, x?: T and x: T | null unify to x?: T | null. HTTP metadata (@query/@path/@header/@cookie) stays strict. Toggle with payloadOptionalNullable (default true).
• Opt-in parsing, zero cost when off. parse: false (default) emits no schema imports and no parse? flag — consumers that never validate pay no module cost. Set parse: true to generate the capability; parseDefault (default true) sets the per-call default, overridable with { parse: false }. A failed parse throws and is routed to the error handler's validation branch (alongside http/network/timeout/fallback).
• Pick your validator. validator: zod (v4), zod3, or valibot. The schema layer is fully behind one interface, so schemas.ts and the (synchronous) parse call are the only things that differ by library — everything else is shared.
• Typed error handling that returns a result. Each op gets a handle<Op>Error that dispatches by status (http), then network/timeout/validation/fallback. Bodies are typed per status, and the call's result is inferred as the union of whatever your handlers return — so you can map an error to a value, or throw in fallback.
• Bundler-friendly layout. generate.barrel: false skips the index.ts re-export and splits schemas.ts into one module per schema (schemas/<name>.ts), so a bundler that doesn't tree-shake within a module (e.g. Metro) pulls in only the schemas an import actually reaches. api files deep-import the consts they use; types.ts stays a single file (type-only, erased). The default (barrel: true) keeps the single schemas.ts + index.ts.
• Pagination. Standard TypeSpec @list/@offset/@pageItems/… drive *InfiniteQueryOptions.

Options

| Option | Values | Default | | ------------------------------- | -------------------------------------------------------- | --------- | | validator | zod, zod3, valibot | zod | | httpClient | axios, ky | axios | | generate.types/schemas/client | boolean | true | | generate.tanstack | react, off | off | | generate.barrel | boolean | true | | parse | boolean | false | | parseDefault | boolean | true | | decimalAs | string, number | string | | unknownAs | unknown, any | unknown | | payloadOptionalNullable | boolean | true | | importExtension | js, none | js | | publishable | { packageName, version, description, author, license } | — |

Development

bun install
bun run build   # alloy build -> dist
bun test        # golden snapshots + tsc-correctness + runtime

Tests are functional: exact input→output goldens, real tsc type-checking of the generated code, and runtime behavior — across {zod4, zod3, valibot} × {axios, ky} and the option matrix.