Initial commit

Author: RPGillespie6

.gitignore

@@ -0,0 +1 @@
+node_modules/

README.md

@@ -0,0 +1,68 @@
+# typed-fetch
+
+typed-fetch is intended to be a drop-in replacement for [openapi-typescript/openapi-fetch](https://github.com/openapi-ts/openapi-typescript) but with a much simpler TypeScript implementation that I believe results in fewer issues and enhanced readability.
+
+## Quickstart
+
+```bash
+# Generate TypeScript types from OpenAPI document
+typed-fetch --openapi examples/petstore-openapi.yaml --output petstore-openapi.ts
+```
+
+```ts
+// Use the generated library in your .ts files
+import { createClient } from "./petstore-openapi";
+
+const client = createClient({ baseUrl: "https://petstore.swagger.io/v2" });
+
+const { data, error } = await client.POST("/store/order", {
+    body: {
+        id: 10,
+        petId: 198772,
+        quantity: 7,
+        shipDate: "2021-07-07T00:00:00.000Z",
+        status: "approved",
+        complete: true
+    }
+});
+```
+
+## Installation
+
+You can download pre-built binaries from [Releases](https://github.com/RPGillespie6/typed-fetch/releases).
+
+If you have Go installed, you can download and install the latest version directly with:
+
+```bash
+go install github.com/RPGillespie6/typed-fetch@latest
+```
+
+Currently this utility is not being published to npm, but it's a future possibility.
+
+# Overview
+
+Type-checked [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch) calls using OpenAPI + TypeScript.
+
+Mostly API-compatible with [openapi-fetch](https://github.com/openapi-ts/openapi-typescript).
+
+Why create this library, if it's nearly identical to [openapi-fetch](https://github.com/openapi-ts/openapi-typescript)? It's because openapi-fetch uses a complex generics/constraints-based TypeScript implementation for type checking, which in my opinion makes it *very* difficult to understand, test, and maintain. The goal of typed-fetch, on the other hand, is to generate simple, straightforward types given an OpenAPI document so that any generalist programmer could inspect the generated TypeScript and easiy understand it -- [see for yourself, no PhD in TypeScript required](examples/petstore-openapi.ts). 
+
+TypeScript generated with this utility is composed almost entirely of type definitions which are stripped out at compile time, resulting in an extremely lightweight fetch wrapper. As a result, typed-fetch should have the same size and performance characteristics as openapi-fetch.
+
+Features:
+- Generated TypeScript definitions are at least an order of magnitude simpler and more straightforward than openapi-fetch, which means you can easily jump to and inspect type definitions in your favorite IDE without fear
+- Arbitrary combinations of required and optional parameters in request bodies are correctly type-checked (broken in openapi-fetch as of July 2024)
+- View your OpenAPI documentation in VSCode when you hover on functions and property names
+- Like esbuild, typed-fetch is written in golang, so it's lightning fast
+
+Limitations:
+- Only OpenAPI 3.1+ specifications officially supported (see [migration guide](https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0)), though most OpenAPI 3.0 documents will also work.
+- Some OpenAPI 3 features not currently implemented, especially if it's unclear how it would map to a TypeScript API.
+
+Missing functionality?
+
+Please open an issue with the following 2 things:
+- Snippet of valid OpenAPI 3 yaml
+- Expected TypeScript to be generated
+
+Also, I'm open to the idea of migrating this utility/approach *into* openapi-fetch if the maintainer(s) there are on-board; I'd rather there be one great tool everyone uses than further fragment the space.

examples/petstore-openapi.ts

@@ -0,0 +1,292 @@
+// Code generated by typed-fetch. DO NOT EDIT.
+// https://github.com/RPGillespie6/typed-fetch
+
+// URL types
+type UrlDeletePetPetId = '/pet/{petId}';
+type UrlDeleteStoreOrderOrderId = '/store/order/{orderId}';
+type UrlDeleteUserUsername = '/user/{username}';
+type UrlValidDelete = UrlDeletePetPetId | UrlDeleteStoreOrderOrderId | UrlDeleteUserUsername;
+
+type UrlGetPetFindByStatus = '/pet/findByStatus';
+type UrlGetPetFindByTags = '/pet/findByTags';
+type UrlGetPetPetId = '/pet/{petId}';
+type UrlGetStoreInventory = '/store/inventory';
+type UrlGetStoreOrderOrderId = '/store/order/{orderId}';
+type UrlGetUserLogin = '/user/login';
+type UrlGetUserLogout = '/user/logout';
+type UrlGetUserUsername = '/user/{username}';
+type UrlValidGet = UrlGetPetFindByStatus | UrlGetPetFindByTags | UrlGetPetPetId | UrlGetStoreInventory | UrlGetStoreOrderOrderId | UrlGetUserLogin | UrlGetUserLogout | UrlGetUserUsername;
+
+type UrlPostPet = '/pet';
+type UrlPostPetPetId = '/pet/{petId}';
+type UrlPostPetPetIdUploadImage = '/pet/{petId}/uploadImage';
+type UrlPostStoreOrder = '/store/order';
+type UrlPostUser = '/user';
+type UrlPostUserCreateWithList = '/user/createWithList';
+type UrlValidPost = UrlPostPet | UrlPostPetPetId | UrlPostPetPetIdUploadImage | UrlPostStoreOrder | UrlPostUser | UrlPostUserCreateWithList;
+
+type UrlPutPet = '/pet';
+type UrlPutUserUsername = '/user/{username}';
+type UrlValidPut = UrlPutPet | UrlPutUserUsername;
+
+// Component types
+
+type ComponentSchemaAddress = {
+    /** Example: Palo Alto */
+    city?: string;
+    /** Example: CA */
+    state?: string;
+    /** Example: 437 Lytton */
+    street?: string;
+    /** Example: 94301 */
+    zip?: string;
+}
+
+type ComponentSchemaApiResponse = {
+    code?: number;
+    message?: string;
+    type?: string;
+}
+
+type ComponentSchemaCategory = {
+    id?: number;
+    /** Example: Dogs */
+    name?: string;
+}
+
+type ComponentSchemaCustomer = {
+    address?: ComponentSchemaAddress[];
+    id?: number;
+    /** Example: fehguy */
+    username?: string;
+}
+
+type ComponentSchemaOrder = {
+    complete?: boolean;
+    id?: number;
+    petId?: number;
+    quantity?: number;
+    shipDate?: string;
+    /** Order Status; Example: approved */
+    status?: 'placed' | 'approved' | 'delivered';
+}
+
+type ComponentSchemaPet = {
+    category?: ComponentSchemaCategory;
+    id?: number;
+    /** Example: doggie */
+    name: string;
+    photoUrls: string[];
+    /** pet status in the store */
+    status?: 'available' | 'pending' | 'sold';
+    tags?: ComponentSchemaTag[];
+}
+
+type ComponentSchemaTag = {
+    id?: number;
+    name?: string;
+}
+
+type ComponentSchemaUser = {
+    /** Example: [email protected] */
+    email?: string;
+    /** Example: John */
+    firstName?: string;
+    id?: number;
+    /** Example: James */
+    lastName?: string;
+    /** Example: 12345 */
+    password?: string;
+    /** Example: 12345 */
+    phone?: string;
+    /** User Status */
+    userStatus?: number;
+    /** Example: theUser */
+    username?: string;
+}
+
+// Request types
+
+// PUT /pet
+type BodyPutPet = ComponentSchemaPet;
+type RequestPutPet = Omit<RequestInit, 'body'> & {  body: BodyPutPet; };
+
+// POST /pet
+type BodyPostPet = ComponentSchemaPet;
+type RequestPostPet = Omit<RequestInit, 'body'> & {  body: BodyPostPet; };
+
+// GET /pet/findByStatus
+type ParamGetPetFindByStatus = {
+    query?: {
+        status?: 'available' | 'pending' | 'sold';
+    };
+}
+type RequestGetPetFindByStatus = RequestInit & { params?: ParamGetPetFindByStatus;  };
+
+// GET /pet/findByTags
+type ParamGetPetFindByTags = {
+    query?: {
+        tags?: string[];
+    };
+}
+type RequestGetPetFindByTags = RequestInit & { params?: ParamGetPetFindByTags;  };
+
+// GET /pet/{petId}
+type ParamGetPetPetId = {
+    path: {
+        petId: number;
+    };
+}
+type RequestGetPetPetId = RequestInit & { params: ParamGetPetPetId;  };
+
+// POST /pet/{petId}
+type ParamPostPetPetId = {
+    path: {
+        petId: number;
+    };
+    query?: {
+        name?: string;
+        status?: string;
+    };
+}
+type RequestPostPetPetId = RequestInit & { params: ParamPostPetPetId;  };
+
+// DELETE /pet/{petId}
+type ParamDeletePetPetId = {
+    header?: {
+        api_key?: string;
+    };
+    path: {
+        petId: number;
+    };
+}
+type RequestDeletePetPetId = RequestInit & { params: ParamDeletePetPetId;  };
+
+// POST /pet/{petId}/uploadImage
+type ParamPostPetPetIdUploadImage = {
+    path: {
+        petId: number;
+    };
+    query?: {
+        additionalMetadata?: string;
+    };
+}
+type BodyPostPetPetIdUploadImage = string;
+type RequestPostPetPetIdUploadImage = Omit<RequestInit, 'body'> & { params: ParamPostPetPetIdUploadImage; body?: BodyPostPetPetIdUploadImage; };
+
+// GET /store/inventory
+type RequestGetStoreInventory = RequestInit;
+
+// POST /store/order
+type BodyPostStoreOrder = ComponentSchemaOrder;
+type RequestPostStoreOrder = Omit<RequestInit, 'body'> & {  body?: BodyPostStoreOrder; };
+
+// GET /store/order/{orderId}
+type ParamGetStoreOrderOrderId = {
+    path: {
+        orderId: number;
+    };
+}
+type RequestGetStoreOrderOrderId = RequestInit & { params: ParamGetStoreOrderOrderId;  };
+
+// DELETE /store/order/{orderId}
+type ParamDeleteStoreOrderOrderId = {
+    path: {
+        orderId: number;
+    };
+}
+type RequestDeleteStoreOrderOrderId = RequestInit & { params: ParamDeleteStoreOrderOrderId;  };
+
+// POST /user
+type BodyPostUser = ComponentSchemaUser;
+type RequestPostUser = Omit<RequestInit, 'body'> & {  body?: BodyPostUser; };
+
+// POST /user/createWithList
+type BodyPostUserCreateWithList = ComponentSchemaUser[];
+type RequestPostUserCreateWithList = Omit<RequestInit, 'body'> & {  body?: BodyPostUserCreateWithList; };
+
+// GET /user/login
+type ParamGetUserLogin = {
+    query?: {
+        username?: string;
+        password?: string;
+    };
+}
+type RequestGetUserLogin = RequestInit & { params?: ParamGetUserLogin;  };
+
+// GET /user/logout
+type RequestGetUserLogout = RequestInit;
+
+// GET /user/{username}
+type ParamGetUserUsername = {
+    path: {
+        username: string;
+    };
+}
+type RequestGetUserUsername = RequestInit & { params: ParamGetUserUsername;  };
+
+// PUT /user/{username}
+type ParamPutUserUsername = {
+    path: {
+        username: string;
+    };
+}
+type BodyPutUserUsername = ComponentSchemaUser;
+type RequestPutUserUsername = Omit<RequestInit, 'body'> & { params: ParamPutUserUsername; body?: BodyPutUserUsername; };
+
+// DELETE /user/{username}
+type ParamDeleteUserUsername = {
+    path: {
+        username: string;
+    };
+}
+type RequestDeleteUserUsername = RequestInit & { params: ParamDeleteUserUsername;  };
+
+type DataResponse<D> = { data: D; response: Response; };
+type ErrorResponse<E> = { error: E; response: Response; };
+type FetchResponse<D, E> = DataResponse<D> | ErrorResponse<E>;
+
+interface ClientOptions extends RequestInit {
+    baseUrl?: string;
+    
+	// Override fetch function (useful for testing)
+	fetch?: (input: Request) => Promise<Response>;
+	
+	// global body serializer -- allows you to customize how the body is serialized before sending
+	// normally not needed unless you are using something like XML instead of JSON
+    bodySerializer?: (body: any) => BodyInit | null; 
+    
+	// global query serializer -- allows you to customize how the query is serialized before sending
+	// normally not needed unless you are using some custom array serialization like {foo: [1,2,3,4]} => ?foo=1;2;3;4
+	querySerializer?: (query: any) => string;
+}
+
+interface Client {
+    // GET(url: string, init?: RequestInit): Promise<FetchResponse<Foo, Err>>;
+	// POST(url: string, init?: BarRequestInit): Promise<FetchResponse<Bar, Err>>;
+}
+
+// Client Implementation
+
+// If not specified, default to application/json
+// Used to deduce body serializer and to set content-type header
+const contentTypeMap: Record<string, string> = {
+	// "/some/binary/url": "application/octet-stream",
+}
+
+class ClientImpl {
+    options: ClientOptions;
+
+    constructor(options: ClientOptions) {
+        options.baseUrl = options.baseUrl || ""; // Make sure baseUrl is always a string
+        this.options = options;
+    }
+
+    #fetch(input: Request): Promise<Response> {
+        return (this.options.fetch || fetch)(input);
+    }
+}
+
+export function createClient(options: ClientOptions): Client {
+    return new ClientImpl(options);
+}