feat(storage): add setHeader method to BaseApiClient

[dabarrell]

🔍 Description

What changed?

Added a setHeader(name, value) method to BaseApiClient in storage-js. This allows setting per-request HTTP headers on any storage operation, matching the existing pattern in postgrest-js which was added in supabase/postgrest-js#550.

The method creates a shallow copy of the headers object to avoid mutating shared state between instances (e.g. between StorageClient and StorageFileApi returned by from()).

Why was this change needed?

postgrest-js supports per-request header overrides via setHeader, but storage-js has no equivalent. Setting headers for storage requests currently requires creating a new Supabase client, setting the header using options.global.headers – not preferable when headers need to be set dynamically per request.

This PR enables use cases like:

supabase.storage.from('bucket').setHeader('x-custom', 'value').upload(...)

📸 Screenshots/Examples

// Set a single header
const { data, error } = await supabase.storage
  .from('avatars')
  .setHeader('custom-header', 'value')
  .upload('path/to/file.txt', fileBody)

// Chain multiple headers
const { data, error } = await supabase.storage
  .from('avatars')
  .setHeader('x-header-a', '1')
  .setHeader('x-header-b', '2')
  .download('path/to/file.txt')

🔄 Breaking changes

• This PR contains no breaking changes

📋 Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: <type>(<scope>): <description>
• I have run npx nx format to ensure consistent code formatting
• I have added tests for new functionality (if applicable)
• I have updated documentation (if applicable)

📝 Additional notes

storage-js currently uses an object to store headers, whereas postgrest-js transitioned from an object to the standard Headers API ~8mo ago in supabase/postgrest-js#619. I chose to keep the change minimal, but I'd be happy to migrate to Headers in this PR if you'd prefer.

Summary by CodeRabbit

• New Features

  • Added method to set custom headers on API clients with support for method chaining
  • Headers are applied immutably without affecting original configuration

• Tests

  • Added comprehensive test coverage for header-setting functionality

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

A new setHeader method is added to the BaseApiClient class, enabling immutable header management with method chaining support. Comprehensive tests validate the method's functionality across single calls, chained operations, header overrides, and isolation between client instances.

Changes

Cohort / File(s)	Summary
BaseApiClient Implementation packages/core/storage-js/src/lib/common/BaseApiClient.ts	Adds public setHeader(name: string, value: string): this method that creates a shallow copy of headers and returns the instance for method chaining.
BaseApiClient Tests packages/core/storage-js/test/common/BaseApiClient.test.ts	Adds 6 test cases covering: basic header assignment, method chaining, header accumulation, header override, header immutability, and client instance isolation when called through StorageClient.from().

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a setHeader method to BaseApiClient. It is concise, specific, and clearly conveys the primary feature being introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

Tip

🧪 Unit Test Generation v2 is now available!

We have significantly improved our unit test generation capabilities.

To enable: Add this to your .coderabbit.yaml configuration:

reviews:
  finishing_touches:
    unit_tests:
      enabled: true

Try it out by using the @coderabbitai generate unit tests command on your code files or under ✨ Finishing Touches on the walkthrough!

Have feedback? Share your thoughts on our Discord thread!

---

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 and usage tips.}

[coveralls]

coverage: 82.932% (+0.004%) from 82.928%
when pulling 4e4ab94 on dabarrell:feature/storage-set-header
into 0cc314a on supabase:master.