Misc. bootstrapping

- Add License
- Fixup README
- Create typed fetch implementation
- Finish metaprogramming implementation

Author: RPGillespie6

LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2024-present, Bryan Gillespie
+
+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.

README.md

@@ -1,19 +1,20 @@
 # 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.
+typed-fetch is intended to be a drop-in replacement for [openapi-fetch](https://github.com/openapi-ts/openapi-typescript) but using a simplified TypeScript implementation that I believe results in fewer issues and superior usability/readability/debuggability.
 
 ## Quickstart
 
 ```bash
 # Generate TypeScript types from OpenAPI document
-typed-fetch --openapi examples/petstore-openapi.yaml --output petstore-openapi.ts
+typed-fetch --openapi examples/petstore-openapi.yaml --output petstore-openapi.d.ts
 ```
 
 ```ts
 // Use the generated library in your .ts files
-import { createClient } from "./petstore-openapi";
+import type { Client as PetstoreClient } from "./petstore-openapi"; // petstore-openapi.d.ts
+import { createClient } from "./typed-fetch"; // typed-fetch.ts file from root of this repo
 
-const client = createClient({ baseUrl: "https://petstore.swagger.io/v2" });
+const client = createClient<PetstoreClient>({ baseUrl: "https://petstore.swagger.io/v2" });
 
 const { data, error } = await client.POST("/store/order", {
     body: {
@@ -43,26 +44,30 @@ Currently this utility is not being published to npm, but it's a future possibil
 
 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).
+Mostly API-compatible with [openapi-fetch](https://github.com/openapi-ts/openapi-typescript). Doesn't include extra bells and whistles like middleware support since native fetch doesn't support middlewares either.
 
-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). 
+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 debug because it [requires knowledge of esoteric TypeScript behavior](https://github.com/openapi-ts/openapi-typescript/issues/1778#issuecomment-2276217668). 
 
-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.
+The goal of typed-fetch, on the other hand, is to generate simple, straightforward "dumb" types given an OpenAPI document so that any generalist programmer could inspect the generated TypeScript and easily understand it -- [see for yourself, no TypeScript black belt required](examples/petstore-openapi.d.ts). Note there are 5 lines of "evil" TypeScript required to make this library play more nicely with VSCode intellisense, but they could be removed if VSCode had better intellisense for overloaded functions.
+
+Like [openapi-fetch](https://github.com/openapi-ts/openapi-typescript), TypeScript generated with this utility is composed entirely of type definitions which are stripped out at compile time, resulting in an extremely lightweight fetch wrapper. Currently weighs in at **1.4 KiB** minified (**700 bytes** if minified and compressed) which means typed-fetch should meet or exceed the size and performance characteristics of 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
+- Generated TypeScript definitions are *at least* an order of magnitude simpler and more straightforward than openapi-fetch, which means you don't have to be a TypeScript ninja to contribute to or debug issues with the type checking.
+- Arbitrary combinations of required and optional parameters in request bodies are correctly type-checked (broken in openapi-fetch as of August 2024 - check if [this issue](https://github.com/openapi-ts/openapi-typescript/issues/1769) is still open)
 - 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.
+- 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 all OpenAPI 3.0 documents I've tested so far also work.
+- Some of the more obscure OpenAPI 3 features are not currently implemented (polymorphism, links, callbacks, etc), and I don't plan to implement them unless there's both a strong use case and a clean way to map them to *both* fetch *and* TypeScript.
 
-Missing functionality?
+# Missing functionality?
 
-Please open an issue with the following 2 things:
+Please open an issue with the following 3 things:
 - Snippet of valid OpenAPI 3 yaml
-- Expected TypeScript to be generated
+- Expected behavior
+- Actual behavior
+
+# Note to openapi-fetch maintainers
 
-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.
+Feel free to copy any approach and/or techniques you see in this repo. I personally think the approach I implemented here in go could be fairly easily replicated in openapi-typescript, and would result in a more-maintainable and more-contributor-friendly openapi-fetch implementation. I'd be happy to help if you're interested which would obsolete this repo.