feat(api): make canonical list metadata hydration optional (#829)

[Zach Dunn (zachdunn)]

Implements issue #829 §5 ("Make expensive enrichment optional") for the canonical file listing.

What changed

• GET /v1/workspaces/:workspace/files (and its legacy /me/workspaces/:name/files alias, which forwards the query string unchanged) now accepts ?metadata=0 / ?metadata=false to skip the D1 metadata hydration pass. Default behavior is unchanged — no param, or any other value, still hydrates and returns metadata per row exactly as before. No response fields were removed or renamed.
• packages/uploads's client (list/listAll) now sends metadata=0 whenever the caller didn't pass metadata: true. Previously the client always paid for the server's hydration pass and then discarded the metadata map client-side when the caller hadn't asked for it — this closes that gap. Callers that do pass metadata: true are unaffected (client still sends metadata=1 and surfaces the map).

Param naming

files.ts's legacy bearer listing route already uses ?metadata=1/true as an opt-in (that route doesn't hydrate by default). The canonical route hydrates by default, so this reuses the same metadata param name with inverted polarity (0/false opts out) rather than introducing a second param — same spelling callers already know, consistent with how each route's default behaves.

Left out of scope

Evaluated gallery preview enrichment (workspace-galleries.ts's itemCount/references/previewUrl hydration on GET /:workspace/galleries) for the same opt-out pattern. That enrichment is structurally different — it isn't a single D1 read but a per-row storage resolve for the cover thumbnail — so making it optional is a larger change than this PR's scope. Noting it here rather than doing it as part of §5.

Tests

• apps/api/test/routes-workspace-files.test.ts: default hydration is unchanged; ?metadata=0 and ?metadata=false both skip hydration (no metadata key on returned rows).
• packages/uploads/test/client-metadata.test.ts: client still requests metadata=1 when metadata: true is passed; now asserts it sends metadata=0 when it isn't.
• pnpm test (root, full suite): all passing.
• Typecheck: apps/api (pnpm --filter @uploads/api run typecheck) and packages/uploads (pnpm run typecheck in that package) both clean.

Changeset

Added a minor changeset for @buildinternet/uploads — additive client behavior change (fewer bytes/less server work on list/listAll calls that don't request metadata).

Refs #829 §5.

[changeset-bot]

🦋 Changeset detected

Latest commit: 67c1226

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

This PR includes changesets to release 1 package

Name	Type
@buildinternet/uploads	Minor

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

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (2)

• coderabbit:review
• review

🚫 Excluded labels (none allowed) (1)

• wip

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7d4bb707-0847-4c42-84c2-5acbe035a221

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}