Serve files from any storage backend over HTTP with correct range requests, conditional caching, safe downloads and integrity digests. Zero runtime dependencies.
npm install partial-content
import { serveObject } from "partial-content/web";
import { s3Store } from "partial-content/s3";
import { S3Client } from "@aws-sdk/client-s3";
const store = s3Store({ client: new S3Client({ region: "eu-central-1" }), bucket: "documents" });
const handler = serveObject(store, { disposition: "inline" });
// Next.js App Router (route-handler params arrive as a Promise)
export async function GET(req: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
return handler(req, { key: id, mime: "application/pdf" });
}
export const HEAD = GET;The handler answers 200, 206, 304, 412, 416 and HEAD. Video seeking, PDF progressive loading and browser caching work against your origin without further code. Authorization stays yours: check access before calling the handler.
A store reads bytes from a backend; an adapter connects the handler to a server framework. Pick one of each.
| Import | Kind | Backend or framework |
|---|---|---|
partial-content/s3 |
store | AWS S3 and S3-compatible (R2, Hetzner, MinIO, Wasabi) |
partial-content/r2 |
store | Cloudflare R2 native bindings |
partial-content/gcs |
store | Google Cloud Storage |
partial-content/azure |
store | Azure Blob Storage |
partial-content/fs |
store | Local filesystem |
partial-content/http |
store | Any range-capable HTTP origin |
partial-content/memory |
store | In-memory, for tests and embedded assets |
partial-content/web |
adapter | Fetch API (Next.js, SvelteKit, Remix, Workers, Bun, Deno) |
partial-content/node |
adapter | Node http, Express, Fastify, Koa |
partial-content/hono |
adapter | Hono |
Also: partial-content (the kernel, for bringing your own I/O), partial-content/mime (MIME lookup) and partial-content/conformance (a check that a custom store meets the read contract). Cloud SDKs (@aws-sdk/client-s3, @google-cloud/storage, @azure/storage-blob) and hono are optional peer dependencies; install only what you use.
- Range requests (206, 416), including
multipart/byterangeswith coalescing and an amplification cap (RFC 9110 Section 14) - Conditional requests (304, 412) and
If-Range, evaluated in the order RFC 9110 Section 13 prescribes, with strong and weak comparison where the RFC requires each Repr-DigestandContent-DigestwithWant-*negotiation (RFC 9530)Content-Dispositionwith non-ASCII filenames, header-injection and path-traversal defense (RFC 6266, RFC 8187)- ETags from storage metadata, typed
Cache-Control, precompressed.br/.zst/.gzvariants, optional signed-URL offload - HEAD-to-GET consistency: reads are pinned to the validated representation, and a store failure maps to its truthful status (404, 503 with
Retry-After, 502) - Audit and metering hooks (
onServe,onTransfer,onError) that can report an opaque id instead of the storage key - ESM only; Node.js 24+, Bun, Deno and Cloudflare Workers
Looking for the 5.x upload API? See docs/UPGRADING.md for presigned direct-to-storage writes.
- docs/API.md: full reference, every option
- docs/EXAMPLES.md: recipes (Express, Hono, Workers, authorized proxy, digests, precompressed variants)
- docs/UPGRADING.md: moving between major versions
- docs/DESIGN.md: design notes, RFC deviations, response header matrix
- docs/BENCHMARKS.md: measurements and methodology
- SECURITY.md: threat model, standards mapping, reporting
Apache-2.0 from 5.0.0 onward, see LICENSE and NOTICE. Versions up to and including 4.0.0, as published, remain under the MIT License.