graphql-upload-ts handles GraphQL multipart uploads with a TypeScript-first API. It keeps the upload middleware and scalar explicit, which matters because file handling is one of those "works in the demo" paths that becomes painful under real streams, validation, and cleanup.
Why uploads deserve respect#
File upload code fails in unglamorous ways: streams left open, temp files not removed, middleware mounted in the wrong order, limits applied too late, or validation that happens after the expensive part already ran. The happy path is usually easy. The production path is concurrent uploads, interrupted clients, large files, retries, and a server that still has to protect memory and disk.
This repo keeps that work visible. Middleware is middleware. The scalar is explicit. The integration points are ordinary enough that a team can reason about where bytes enter the system, where they are validated, and who is responsible for cleanup.
What it keeps sharp#
- Middleware order is documented instead of guessed.
- Streams are consumed or destroyed so temp files do not linger.
- Types are part of the integration, not an afterthought.
- Bun support stays in the normal install path, not a separate fork.
- Limits and validation happen at the upload boundary, before the expensive path gets comfortable.
- Framework adapters matter because teams rarely run the same GraphQL server forever.
Where I would look first in production#
I would test the unhappy path before celebrating the happy one: client disconnects mid-stream, file size exceeds the limit, filename metadata is hostile, resolver validation rejects the upload, and two large uploads arrive at the same time. Those are the cases that decide whether upload support is a feature or a liability.
The useful part of this repo is that those questions are visible. You can point to the middleware, the scalar, the resolver, and the cleanup path. That is how file upload code should be reviewed.
The engineering habit#
I like libraries that make unsafe paths hard to ignore. Uploads should not be a black box hidden behind a pretty mutation. They are resource management, API design, and operational safety in the same feature.
The larger principle is the one I use in product platforms too: keep the dangerous boundary explicit, give it types, give it tests, and make cleanup part of the contract instead of a note in someone else's memory.