yankeeinlondon/gotcha

Gotcha is a JavaScript and TypeScript library that makes it easier and safer to talk to other services over the web. When your app needs to fetch data from an API, upload a file, or communicate with another server, it handles the request and, crucially, gives you a clear, structured way to deal with whatever comes back, whether that's a success or a failure. Instead of the traditional approach where a failed web request throws an exception that you have to catch and untangle, this library returns a result object that you check explicitly. You simply ask "did this work?" If it did, you access your data. If it did not, the error is categorized for you, telling you whether it was a timeout, a redirection, a problem on your end (like a bad request), or a problem on the server's end. It also has built-in support for setting time limits on requests, so if a server is too slow, you get a clean, categorized timeout error rather than a hung application. This is designed for developers building applications in Node.js or similar JavaScript environments who want more predictable networking code. For example, if you are building a backend service that calls several external APIs, using this approach means you can handle a 404 "not found" from one service differently than a 500 "server error" from another, all without wrapping your code in messy try-catch blocks. It is intended as a straightforward replacement for the standard "fetch" API, adding this smarter error handling and timeout management on top. The project is built in TypeScript, which means it provides "type safety." In practical terms, this gives developers helpful, automatic guidance in their code editors about what properties and data are available in different scenarios, reducing bugs. Under the hood, it is powered by "undici," a high-performance web client, so it prioritizes speed while adding a layer of safety and structure on top.