Manual type declarations in openapi-fetch

[drwpow]

Changes

Splits index.ts (runtime + types) into manual index.js and index.d.ts files. Added this section to the CONTRIBUTING docs to explain why:

This project uses manual type declarations (docs) 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.

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.

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!

This is an internal change—tests still pass—but it will make some upcoming changes much, much easier.

How to Review

• Tests should pass

Checklist

• Unit tests updated
• docs/ updated (if necessary)
• pnpm run update:examples run (only applicable for openapi-typescript)

[changeset-bot]

🦋 Changeset detected

Latest commit: 3347010

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openapi-fetch	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[drwpow]

Moved into /fixtures/ folder for cleanup

[drwpow]

Fun fact: I originally wanted to add allowJs: true to TSConfig, however, that broke everything—it tries to infer types from .js files and ignores .d.ts. So fortunately no change is necessary, and TypeScript likes .d.ts just as much as the original .ts

[drwpow]

Not actually rewritten; just moved several sections out of the “Opening a Pull Request” heading and into a “Writing Code” heading

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Pages

Latest commit:	3347010
Status:	✅  Deploy successful!
Preview URL:	https://cce5cc96.openapi-ts.pages.dev
Branch Preview URL:	https://manual-types.openapi-ts.pages.dev

View logs