Manual type declarations in openapi-fetch (#1424)

* Separate TS types to be managed manually

* Update CONTRIBUTING.md

* Cleanup

.changeset/fair-carpets-beg.md

@@ -0,0 +1,5 @@
+---
+"openapi-fetch": patch
+---
+
+Separate TS types to be managed manually

packages/openapi-fetch/.eslintignore

@@ -1 +1 @@
-test/openapi-typescript-codegen.min.js
+test/fixtures

packages/openapi-fetch/CONTRIBUTING.md

@@ -10,45 +10,23 @@ Please check out the [the open issues](https://github.com/drwpow/openapi-typescr
 
 Contributing doesn’t have to be in code. Simply answering questions in open issues or providing workarounds is as important as making pull requests.
 
-## Opening a Pull Request
-
-Pull requests are **welcome** for this repo!
-
-Bugfixes will always be accepted, though in some cases some small changes may be requested.
-
-However, if adding a feature or breaking change, please **open an issue first to discuss.** This ensures no time or work is wasted writing code that won’t be accepted to the project (see [Project Goals](https://openapi-ts.pages.dev/openapi-fetch/about/#project-goals)). Undiscussed feature work may be rejected at the discretion of the maintainers.
+## Writing code
 
 ### Setup
 
 1. Install [pnpm](https://pnpm.io/)
 2. [Fork this repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) and clone your copy locally
 3. Run `pnpm i` to install dependencies
 
-### Writing code
-
-Create a new branch for your PR with `git checkout -b your-branch-name`. Add the relevant code as well as docs and tests. When you push everything up (`git push`), navigate back to your repo in GitHub and you should see a prompt to open a new PR.
-
-While best practices for commit messages are encouraged (e.g. start with an imperative verb, keep it short, use the body if needed), this repo doesn’t follow any specific guidelines. Clarity is favored over strict rules. Changelogs are generated separately from git (see [the Changelogs section](#changelogs))
-
-### Writing the PR
-
-**Please fill out the template!** It’s a very lightweight template 🙂.
-
-### Changelogs
-
-The changelog is generated via [changesets](https://github.com/changesets/changesets), and is separate from Git commit messages and pull request titles. To write a human-readable changelog for your changes, run:
-
-```
-npx changeset
-```
+### Runtime code vs static type declarations
 
-This will ask if it’s a `patch`, `minor`, or `major` change ([semver](https://semver.org/)), along with a plain description of what you did. Commit this new file along with the rest of your PR, and during the next release this will go into the official changelog!
+This project uses **manual type declarations** ([docs](https://www.typescriptlang.org/docs/handbook/2/type-declarations.html#dts-files)) that are kept separately from the runtime code. `index.d.ts` contains **type declarations**, and `index.js` contains **runtime code**. The most important code lives in `index.d.ts` because this library exists to provide correct type inference. `index.js`, is far less important, and is only doing bare-minimum work to support the API as efficiently as possible.
 
-### CI
+In most projects, **this is not recommended practice** as the two can (and will) diverge, and you’re left with types that “lie” to you about what the runtime is doing. So this project does have that liability. However, due to the unique nature of this project implementing complex type inference from user-provided schemas, the type inference itself is so complex it was interfering with readable, maintainable, runtime code. By separating the two we won’t have the more complex parts of TypeScript interfering with the optimal runtime code. This would not be tenable in a larger project, but is perfect for a small codebase like this with minimal surface area.
 
-All PRs must fix lint errors, and all tests must pass. PRs will not be merged until all CI checks are “green” (✅).
+When writing code, it’s tempting to ignore `index.d.ts` and only make runtime updates, since that is generally simpler. But **please don’t!** We write tests in `*.test.ts` files intentionally so that the type inference can be typechecked as well as the runtime. Whenever you make a change to `index.js`, you probably need to also make a chance to `index.d.ts`, too. And **testing type correctness in tests is just as important as testing the runtime!**
 
-#### Tests
+### Testing
 
 This library uses [Vitest](https://vitest.dev/) for testing. There’s a great [VS Code extension](https://marketplace.visualstudio.com/items?itemName=ZixuanChen.vitest-explorer) you can optionally use if you’d like in-editor debugging tools.
 
@@ -69,3 +47,45 @@ To start the entire test suite in watch mode:
 ```bash
 npx vitest
 ```
+
+#### TypeScript tests
+
+**Don’t neglect writing TS tests!** In the test suite, you’ll see `// @ts-expect-error` comments. These are critical tests in and of themselves—they are asserting that TypeScript throws an error when it should be throwing an error (the test suite will actually fail in places if a TS error is _not_ raised).
+
+As this is just a minimal fetch wrapper meant to provide deep type inference for API schemas, **testing TS types** is arguably more important than testing the runtime. So please make liberal use of `// @ts-expect-error`, and as a general rule of thumb, write more **unwanted** output tests than _wanted_ output tests.
+
+### Changelogs
+
+The changelog is generated via [changesets](https://github.com/changesets/changesets), and is separate from Git commit messages and pull request titles. To write a human-readable changelog for your changes, run:
+
+```
+npx changeset
+```
+
+This will ask if it’s a `patch`, `minor`, or `major` change ([semver](https://semver.org/)), along with a plain description of what you did. Commit this new file along with the rest of your PR, and during the next release this will go into the official changelog!
+
+## Opening a Pull Request
+
+Pull requests are **welcome** for this repo!
+
+Bugfixes will always be accepted, though in some cases some small changes may be requested.
+
+However, if adding a feature or breaking change, please **open an issue first to discuss.** This ensures no time or work is wasted writing code that won’t be accepted to the project (see [Project Goals](https://openapi-ts.pages.dev/openapi-fetch/about/#project-goals)). Undiscussed feature work may be rejected at the discretion of the maintainers.
+
+### Writing the commit
+
+Create a new branch for your PR with `git checkout -b your-branch-name`. Add the relevant code as well as docs and tests. When you push everything up (`git push`), navigate back to your repo in GitHub and you should see a prompt to open a new PR.
+
+While best practices for commit messages are encouraged (e.g. start with an imperative verb, keep it short, use the body if needed), this repo doesn’t follow any specific guidelines. Clarity is favored over strict rules. Changelogs are generated separately from git (see [the Changelogs section](#changelogs)).
+
+### Writing the PR notes
+
+**Please fill out the template!** It’s a very lightweight template 🙂.
+
+### Adding docs
+
+If you added a feature, or changed how something worked, please [update the docs](../../docs/)!
+
+### Passing CI
+
+All PRs must fix lint errors, and all tests must pass. PRs will not be merged until all CI checks are “green” (✅).

packages/openapi-fetch/package.json

@@ -47,29 +47,29 @@
     "svelte"
   ],
   "scripts": {
-    "build": "pnpm run build:clean && pnpm run build:ts && pnpm run build:ts-min && pnpm run build:cjs",
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:js-min && pnpm run build:cjs",
     "build:clean": "del dist",
-    "build:ts": "tsc -p tsconfig.build.json",
-    "build:ts-min": "esbuild --bundle src/index.ts --format=esm --minify --outfile=dist/index.min.js && cp dist/index.d.ts dist/index.min.d.ts",
-    "build:cjs": "esbuild --bundle src/index.ts --format=cjs --outfile=dist/cjs/index.cjs && cp dist/index.d.ts dist/cjs/index.d.cts",
+    "build:js": "mkdir -p dist && cp src/* dist",
+    "build:js-min": "esbuild --bundle src/index.js --format=esm --minify --outfile=dist/index.min.js && cp dist/index.d.ts dist/index.min.d.ts",
+    "build:cjs": "esbuild --bundle src/index.js --format=cjs --outfile=dist/cjs/index.cjs && cp dist/index.d.ts dist/cjs/index.d.cts",
     "lint": "pnpm run lint:js",
     "lint:js": "eslint \"{src,test}/**/*.{js,ts}\"",
     "lint:prettier": "prettier --check \"{src,test}/**/*\"",
     "test": "pnpm run test:ts && npm run test:js",
     "test:js": "vitest run",
     "test:ts": "tsc --noEmit",
-    "prepare": "openapi-typescript test/v1.yaml -o test/v1.d.ts",
+    "prepare": "openapi-typescript test/fixtures/api.yaml -o test/fixtures/api.d.ts",
     "prepublish": "pnpm run prepare && pnpm run build",
     "version": "pnpm run prepare && pnpm run build"
   },
   "dependencies": {
     "openapi-typescript-helpers": "^0.0.4"
   },
   "devDependencies": {
-    "axios": "^1.5.1",
+    "axios": "^1.6.0",
     "del-cli": "^5.1.0",
-    "esbuild": "^0.19.4",
-    "nanostores": "^0.9.3",
+    "esbuild": "^0.19.5",
+    "nanostores": "^0.9.4",
     "openapi-typescript": "^6.7.0",
     "openapi-typescript-codegen": "^0.25.0",
     "openapi-typescript-fetch": "^1.1.3",