docs(node): note openAsBlob bugs with files over 2 GiB

[dinwwwh]

TmpFile is backed by Node's fs.openAsBlob, which misreports very large files. The Tmp File Upload plugin docs and the TmpFile JSDoc now warn about it, so users spooling multi-gigabyte uploads know which parts of the File API they can trust.

Verified on Node v22.23.2 with a sparse 5 GiB file: size reports the true size modulo 4 GiB (5 GiB comes back as 1 GiB, a uint32 truncation), a slice() spanning the 2 GiB boundary returns an empty blob, and stream() delivers every byte correctly. Tracked upstream at nodejs/node#52585, still open.

Docs

Whole-file streaming of huge uploads keeps working as documented. Handlers that need the size of, or random access into, such an upload are pointed at the TmpFile.path to stat or read directly.

Testing

pnpm docs:validate passes: no JSDoc backlink errors across 204 symbols and 315 orpc.dev links, and blume validate --strict reports no broken links.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview	Aug 17, 2026 4:18am

[pullfrog]

✅ No new issues found.

Reviewed changes

• Added a :::warning admonition to the Tmp File Upload plugin docs (tmp-file-upload.mdx) noting fs.openAsBlob's bugs with files over 2 GiB: size wraps modulo 4 GiB and slice() is unreliable above 2 GiB, while whole-file reads like stream() stay correct, with advice to stat/read TmpFile.path directly.
• Added a matching @remarks JSDoc block on the TmpFile class in tmp-file-upload-handler-plugin.ts, linking the same upstream issue and pointing size/random-access needs at path.

I cross-checked every technical claim against the linked upstream issue (nodejs/node#52585): a 5 GiB file reporting size as 1 GiB matches the modulo-4-GiB uint32 wrap described there, and the slice() failure around the 2 GiB boundary matches exactly. The stream()-stays-correct and stat-the-path guidance is sound. Well-written, accurate documentation with no behavioral surface.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@1879

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@1879

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@1879

@orpc/client

npm i https://pkg.pr.new/@orpc/client@1879

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@1879

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@1879

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@1879

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@1879

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@1879

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@1879

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@1879

@orpc/next

npm i https://pkg.pr.new/@orpc/next@1879

@orpc/node

npm i https://pkg.pr.new/@orpc/node@1879

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@1879

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@1879

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@1879

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@1879

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@1879

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@1879

@orpc/server

npm i https://pkg.pr.new/@orpc/server@1879

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@1879

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@1879

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@1879

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@1879

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@1879

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@1879

commit: 1ae7dd7

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing dinwwwh:claude/practical-cerf-15fd36 (1ae7dd7) with main (8f71dc3)}