ty-fetch 0.1.0 → 0.1.2

package/README.md

@@ -7,8 +7,9 @@
 [![npm version](https://img.shields.io/npm/v/ty-fetch.svg)](https://www.npmjs.com/package/ty-fetch)
 [![license](https://img.shields.io/npm/l/ty-fetch.svg)](https://github.com/alnorris/ty-fetch/blob/main/LICENSE)
 [![CI](https://github.com/alnorris/ty-fetch/actions/workflows/ci.yml/badge.svg)](https://github.com/alnorris/ty-fetch/actions/workflows/ci.yml)
+[![Try it](https://img.shields.io/badge/try%20it-playground-blue)](https://codespaces.new/alnorris/ty-fetch?quickstart=1)
 
-**A tiny, zero-dependency HTTP client that auto-discovers your OpenAPI specs and types your API calls on-the-fly. No codegen, no build step — types generated by a TS plugin.**
+**A tiny, zero-dependency HTTP client that auto-discovers your OpenAPI specs and types your API calls on-the-fly. No codegen, no build step — types generated by a TS plugin.** [Try it in your browser →](https://codespaces.new/alnorris/ty-fetch?quickstart=1)
 
 ```bash
 npm install ty-fetch
@@ -64,16 +65,16 @@ Types appear in your editor instantly. When the spec changes, types update autom
 
 ### Compared to other tools
 
-| | ty-fetch | [openapi-typescript](https://github.com/openapi-ts/openapi-typescript) | [openapi-fetch](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) | [orval](https://github.com/orval-labs/orval) |
-|---|---|---|---|---|
-| **Codegen step** | None | `npx openapi-typescript ...` | Needs openapi-typescript first | `npx orval` |
-| **Build step** | None | Required | Required | Required |
-| **Generated files** | None | `.d.ts` files | `.d.ts` files | Full client |
-| **Spec changes** | Auto-updates | Re-run codegen | Re-run codegen | Re-run codegen |
-| **Auto-discovery** | Probes well-known paths | Manual | Manual | Manual |
-| **Editor integration** | TS plugin (autocomplete, hover, diagnostics) | Types only | Types only | Types only |
-| **Path validation** | Typo detection with suggestions | None | None | None |
-| **Runtime** | Thin fetch wrapper (~100 LOC) | None (types only) | Fetch wrapper | Axios/fetch client |
+| | ty-fetch | [openapi-fetch](https://github.com/openapi-ts/openapi-typescript/tree/main/packages/openapi-fetch) | [orval](https://github.com/orval-labs/orval) |
+|---|---|---|---|
+| **Codegen step** | None | `npx openapi-typescript` first | `npx orval` |
+| **Generated files** | None | `.d.ts` type files | Full client code |
+| **Spec changes** | Auto-updates | Re-run codegen | Re-run codegen |
+| **Auto-discovery** | Probes well-known paths | Manual | Manual |
+| **Editor integration** | TS plugin (autocomplete, hover, path validation) | Types only | Types only |
+| **Path validation** | Typo detection with "did you mean?" | None | None |
+| **Streaming** | SSE, NDJSON built-in | `parseAs: "stream"` | Depends on client |
+| **Runtime** | ~100 LOC, zero deps | ~6 KB | Axios/fetch client |
 
 ---
 
@@ -108,7 +109,7 @@ That's it. ✨
 
 > **VS Code users:** Make sure you're using the workspace TypeScript version, not the built-in one. Command Palette → **TypeScript: Select TypeScript Version** → **Use Workspace Version**
 
-Want to try it without setting up a project? Check out the [playground](./playground/).
+Want to try it without setting up a project? [Open in GitHub Codespaces →](https://codespaces.new/alnorris/ty-fetch?quickstart=1) — types work instantly, no local setup needed.
 
 ---
 

package/base.d.ts

@@ -3,9 +3,9 @@ export class HTTPError extends Error {
 }
 
 export interface Options<
-  TBody = never,
-  TPathParams = never,
-  TQueryParams = never,
+  TBody = unknown,
+  TPathParams = Record<string, string>,
+  TQueryParams = Record<string, string | number | boolean>,
   THeaders extends Record<string, string> = Record<string, string>,
 > extends Omit<RequestInit, 'body' | 'headers'> {
   body?: TBody;
@@ -31,19 +31,19 @@ export interface StreamResult<T = unknown> extends AsyncIterable<T> {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type BaseOptions = Options<any, Record<string, any>, Record<string, any>>;
+type Untyped = any;
 
 export interface TyFetch {
-  (url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  get(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  post(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  put(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  patch(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  delete(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  head(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  stream(url: string, options?: BaseOptions): StreamResult;
-  create(defaults?: BaseOptions): TyFetch;
-  extend(defaults?: BaseOptions): TyFetch;
+  <T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  get<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  post<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  put<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  patch<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  delete<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  head<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  stream<T = Untyped>(url: string, options?: Options): StreamResult<T>;
+  create(defaults?: Options): TyFetch;
+  extend(defaults?: Options): TyFetch;
   use(middleware: Middleware): TyFetch;
   HTTPError: typeof HTTPError;
 }

package/dist/core/path-validator.d.ts

@@ -1,5 +1,9 @@
 import type { OpenAPISpec } from "./types";
+/** Check if an actual URL path matches an OpenAPI path template with {param} segments. */
 export declare function matchesPathTemplate(actualPath: string, templatePath: string): boolean;
+/** Return true if the given path exists in the spec, either exactly or via template matching. */
 export declare function pathExistsInSpec(path: string, spec: OpenAPISpec): boolean;
+/** Find the matching spec path key for a given API path, returning null if not found. */
 export declare function findSpecPath(apiPath: string, spec: OpenAPISpec): string | null;
+/** Find the closest path to the target using Levenshtein distance, for typo suggestions. */
 export declare function findClosestPath(target: string, paths: string[]): string | null;

package/dist/core/path-validator.js

@@ -4,6 +4,7 @@ exports.matchesPathTemplate = matchesPathTemplate;
 exports.pathExistsInSpec = pathExistsInSpec;
 exports.findSpecPath = findSpecPath;
 exports.findClosestPath = findClosestPath;
+/** Check if an actual URL path matches an OpenAPI path template with {param} segments. */
 function matchesPathTemplate(actualPath, templatePath) {
     const actualParts = actualPath.split("/");
     const templateParts = templatePath.split("/");
@@ -11,16 +12,19 @@ function matchesPathTemplate(actualPath, templatePath) {
         return false;
     return templateParts.every((tp, i) => tp.startsWith("{") || tp === actualParts[i]);
 }
+/** Return true if the given path exists in the spec, either exactly or via template matching. */
 function pathExistsInSpec(path, spec) {
     if (spec.paths[path])
         return true;
     return Object.keys(spec.paths).some((tp) => matchesPathTemplate(path, tp));
 }
+/** Find the matching spec path key for a given API path, returning null if not found. */
 function findSpecPath(apiPath, spec) {
     if (spec.paths[apiPath])
         return apiPath;
     return Object.keys(spec.paths).find((tp) => matchesPathTemplate(apiPath, tp)) ?? null;
 }
+/** Find the closest path to the target using Levenshtein distance, for typo suggestions. */
 function findClosestPath(target, paths) {
     let best = null;
     let bestDist = Infinity;

package/dist/core/schema-utils.d.ts

@@ -1,5 +1,9 @@
 import type { OpenAPISpec } from "./types";
+/** Resolve a $ref pointer to its target schema, or return the schema as-is if not a ref. */
 export declare function resolveSchemaRef(schema: any, spec: OpenAPISpec): any;
+/** Extract the JSON or form-encoded request body schema from an operation. */
 export declare function getRequestBodySchema(operation: any): any | null;
+/** Extract the JSON response schema from a 200 or 201 response. */
 export declare function getResponseSchema(operation: any): any | null;
+/** Return true if the operation's request body is marked as required. */
 export declare function isRequestBodyRequired(operation: any): boolean;

package/dist/core/schema-utils.js

@@ -4,6 +4,7 @@ exports.resolveSchemaRef = resolveSchemaRef;
 exports.getRequestBodySchema = getRequestBodySchema;
 exports.getResponseSchema = getResponseSchema;
 exports.isRequestBodyRequired = isRequestBodyRequired;
+/** Resolve a $ref pointer to its target schema, or return the schema as-is if not a ref. */
 function resolveSchemaRef(schema, spec) {
     if (!schema)
         return null;
@@ -15,15 +16,18 @@ function resolveSchemaRef(schema, spec) {
     }
     return schema;
 }
+/** Extract the JSON or form-encoded request body schema from an operation. */
 function getRequestBodySchema(operation) {
     return (operation?.requestBody?.content?.["application/json"]?.schema ??
         operation?.requestBody?.content?.["application/x-www-form-urlencoded"]?.schema ??
         null);
 }
+/** Extract the JSON response schema from a 200 or 201 response. */
 function getResponseSchema(operation) {
     const resp = operation?.responses?.["200"] ?? operation?.responses?.["201"];
     return resp?.content?.["application/json"]?.schema ?? null;
 }
+/** Return true if the operation's request body is marked as required. */
 function isRequestBodyRequired(operation) {
     return !!operation?.requestBody?.required;
 }

package/dist/core/spec-cache.d.ts

@@ -1,10 +1,10 @@
 import type { OpenAPISpec, SpecEntry } from "./types";
-export declare const KNOWN_SPECS: Record<string, string>;
+export declare const configuredSpecs: Record<string, string>;
 export declare const specCache: Map<string, SpecEntry>;
 /**
  * Register user-provided spec mappings (from tsconfig plugin config).
  * Values can be URLs (https://...) or file paths (resolved relative to basePath).
- * These override built-in KNOWN_SPECS for the same domain.
+ * These override built-in configuredSpecs for the same domain.
  */
 export declare function registerSpecs(specs: Record<string, string>, basePath: string): void;
 /**
@@ -16,5 +16,7 @@ export declare function ensureSpec(domain: string, log: (msg: string) => void, o
 /**
  * Synchronous version — fetches and blocks. Used by CLI.
  */
+/** Return a cached spec entry if available, without triggering a new fetch. */
 export declare function ensureSpecSync(domain: string, _log: (msg: string) => void): Promise<SpecEntry>;
+/** Fetch and cache the OpenAPI spec for a domain, awaiting the result. */
 export declare function fetchSpecForDomain(domain: string, log: (msg: string) => void): Promise<SpecEntry>;

package/dist/core/spec-cache.js

@@ -36,28 +36,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.specCache = exports.KNOWN_SPECS = void 0;
+exports.specCache = exports.configuredSpecs = void 0;
 exports.registerSpecs = registerSpecs;
 exports.ensureSpec = ensureSpec;
 exports.ensureSpecSync = ensureSpecSync;
 exports.fetchSpecForDomain = fetchSpecForDomain;
 const js_yaml_1 = __importDefault(require("js-yaml"));
-exports.KNOWN_SPECS = {};
+exports.configuredSpecs = {};
 exports.specCache = new Map();
 /**
  * Register user-provided spec mappings (from tsconfig plugin config).
  * Values can be URLs (https://...) or file paths (resolved relative to basePath).
- * These override built-in KNOWN_SPECS for the same domain.
+ * These override built-in configuredSpecs for the same domain.
  */
 function registerSpecs(specs, basePath) {
     const pathMod = require("node:path");
     for (const [domain, value] of Object.entries(specs)) {
         if (value.startsWith("http://") || value.startsWith("https://")) {
-            exports.KNOWN_SPECS[domain] = value;
+            exports.configuredSpecs[domain] = value;
         }
         else {
             // Resolve relative file paths against basePath
-            exports.KNOWN_SPECS[domain] = pathMod.resolve(basePath, value);
+            exports.configuredSpecs[domain] = pathMod.resolve(basePath, value);
         }
         // Clear any cached entry so the new source is used
         exports.specCache.delete(domain);
@@ -72,7 +72,7 @@ function ensureSpec(domain, log, onLoaded) {
     const existing = exports.specCache.get(domain);
     if (existing)
         return existing;
-    const specUrl = exports.KNOWN_SPECS[domain];
+    const specUrl = exports.configuredSpecs[domain];
     const entry = { status: "loading", spec: null, fetchedAt: Date.now() };
     exports.specCache.set(domain, entry);
     if (specUrl) {
@@ -115,6 +115,7 @@ function ensureSpec(domain, log, onLoaded) {
 /**
  * Synchronous version — fetches and blocks. Used by CLI.
  */
+/** Return a cached spec entry if available, without triggering a new fetch. */
 async function ensureSpecSync(domain, _log) {
     const existing = exports.specCache.get(domain);
     if (existing?.status !== "loading")
@@ -122,11 +123,12 @@ async function ensureSpecSync(domain, _log) {
     // Already loading — wait for it (shouldn't happen in CLI flow)
     return existing;
 }
+/** Fetch and cache the OpenAPI spec for a domain, awaiting the result. */
 async function fetchSpecForDomain(domain, log) {
     const existing = exports.specCache.get(domain);
     if (existing && existing.status === "loaded")
         return existing;
-    const specUrl = exports.KNOWN_SPECS[domain];
+    const specUrl = exports.configuredSpecs[domain];
     if (specUrl) {
         log(`Fetching spec for ${domain} from ${specUrl}`);
         try {
@@ -171,6 +173,9 @@ const WELL_KNOWN_PATHS = [
     "/docs/openapi.yaml",
     "/swagger.json",
     "/api-docs/openapi.json",
+    "/api/v1/openapi.json",
+    "/api/v2/openapi.json",
+    "/api/v3/openapi.json",
 ];
 async function probeWellKnownSpecs(domain, log) {
     // Try HTTPS first, then HTTP for local/dev servers

package/dist/core/url-parser.d.ts

@@ -1,4 +1,7 @@
 import type { OpenAPISpec, ParsedUrl } from "./types";
+/** Parse an HTTP(S) URL string into its domain and path components. */
 export declare function parseFetchUrl(text: string): ParsedUrl | null;
+/** Extract the base path prefix from an OpenAPI spec (Swagger 2.0 basePath or OpenAPI 3.x servers). */
 export declare function getBasePath(spec: OpenAPISpec): string;
+/** Remove the spec's base path prefix from a URL path to get the API-relative path. */
 export declare function stripBasePath(urlPath: string, spec: OpenAPISpec): string;

package/dist/core/url-parser.js

@@ -3,12 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseFetchUrl = parseFetchUrl;
 exports.getBasePath = getBasePath;
 exports.stripBasePath = stripBasePath;
+/** Parse an HTTP(S) URL string into its domain and path components. */
 function parseFetchUrl(text) {
     const match = text.match(/^https?:\/\/([^/]+)(\/[^?#]*)?/);
     if (!match)
         return null;
     return { domain: match[1], path: match[2] || "/" };
 }
+/** Extract the base path prefix from an OpenAPI spec (Swagger 2.0 basePath or OpenAPI 3.x servers). */
 function getBasePath(spec) {
     // Swagger 2.0: basePath is a top-level field
     if (spec.basePath) {
@@ -29,6 +31,7 @@ function getBasePath(spec) {
         return "";
     }
 }
+/** Remove the spec's base path prefix from a URL path to get the API-relative path. */
 function stripBasePath(urlPath, spec) {
     const base = getBasePath(spec);
     if (base && urlPath.startsWith(base)) {

package/dist/generate-types.d.ts

@@ -65,17 +65,11 @@ export interface DomainSpec {
     basePath: string;
     spec: FullOpenAPISpec;
 }
-/**
- * Generate one .d.ts per domain — keeps each file under TS overload limits.
- * Returns a map of filename → content.
- */
-/**
- * Filter spec paths to only those matching URLs seen in the codebase.
- * usedUrls is a Set of parsed { domain, path } objects.
- */
+/** Generate one .d.ts per domain, filtered to only paths matching URLs seen in the codebase. */
 export declare function generatePerDomain(domainSpecs: DomainSpec[], usedUrls: Array<{
     domain: string;
     path: string;
 }>): Map<string, string>;
+/** Generate the full .d.ts file content with typed overloads for the given domain specs. */
 export declare function generateDtsContent(domainSpecs: DomainSpec[]): string;
 export {};

package/dist/generate-types.js

@@ -6,14 +6,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generatePerDomain = generatePerDomain;
 exports.generateDtsContent = generateDtsContent;
-/**
- * Generate one .d.ts per domain — keeps each file under TS overload limits.
- * Returns a map of filename → content.
- */
-/**
- * Filter spec paths to only those matching URLs seen in the codebase.
- * usedUrls is a Set of parsed { domain, path } objects.
- */
+/** Generate one .d.ts per domain, filtered to only paths matching URLs seen in the codebase. */
 function generatePerDomain(domainSpecs, usedUrls) {
     const result = new Map();
     // Group used paths by domain
@@ -54,6 +47,7 @@ function generatePerDomain(domainSpecs, usedUrls) {
     }
     return result;
 }
+/** Generate the full .d.ts file content with typed overloads for the given domain specs. */
 function generateDtsContent(domainSpecs) {
     const lines = [
         "// Auto-generated by ty-fetch plugin. Do not edit.",

package/index.d.ts

@@ -3,9 +3,9 @@ export class HTTPError extends Error {
 }
 
 export interface Options<
-  TBody = never,
-  TPathParams = never,
-  TQueryParams = never,
+  TBody = unknown,
+  TPathParams = Record<string, string>,
+  TQueryParams = Record<string, string | number | boolean>,
   THeaders extends Record<string, string> = Record<string, string>,
 > extends Omit<RequestInit, 'body' | 'headers'> {
   body?: TBody;
@@ -31,19 +31,19 @@ export interface StreamResult<T = unknown> extends AsyncIterable<T> {
 }
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-type BaseOptions = Options<any, Record<string, any>, Record<string, any>>;
+type Untyped = any;
 
 export interface TyFetch {
-  (url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  get(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  post(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  put(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  patch(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  delete(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  head(url: string, options?: BaseOptions): Promise<FetchResult<any>>;
-  stream(url: string, options?: BaseOptions): StreamResult;
-  create(defaults?: BaseOptions): TyFetch;
-  extend(defaults?: BaseOptions): TyFetch;
+  <T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  get<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  post<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  put<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  patch<T = Untyped>(url: string, options?: Options): Promise<FetchResult<T>>;
+  delete<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  head<T = Untyped>(url: string, options?: Options<never>): Promise<FetchResult<T>>;
+  stream<T = Untyped>(url: string, options?: Options): StreamResult<T>;
+  create(defaults?: Options): TyFetch;
+  extend(defaults?: Options): TyFetch;
   use(middleware: Middleware): TyFetch;
   HTTPError: typeof HTTPError;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ty-fetch",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Automatic TypeScript types for any REST API. No codegen, no manual types — just fetch.",
   "license": "MIT",
   "keywords": [
@@ -50,14 +50,12 @@
     "build": "tsc -p tsconfig.build.json",
     "watch": "tsc -p tsconfig.build.json --watch",
     "lint": "eslint src/ test/",
-    "check": "biome check src/ test/ && eslint src/ test/",
-    "format": "biome check --fix src/ test/",
+    "check": "eslint src/ test/",
     "prepare": "npm run build",
     "prepublishOnly": "cp base.d.ts index.d.ts && npm run build",
     "release": "np"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.10",
     "@eslint/js": "^10.0.1",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.2",