feat(storage): add deleteSourceObjects option to combine/compose method

[thiyaguk09]

Description

This PR implements a client-side workaround for the deleteSourceObjects parameter in the GCS Compose API (combine method).

Key Changes

• API Signature & Types: Added deleteSourceObjects?: boolean to CombineOptions and documented it in the combine method JSDocs.
• Request Body Integration: Added deleteSourceObjects to the JSON request body of the /compose request (omitted if undefined to ensure backward compatibility and clean requests).
• Execution Logic:
  • Executes the standard compose operation first.
  • If deleteSourceObjects is set to true and the compose operation is successful, programmatically deletes all source files.
  • If the compose operation fails, aborts immediately without deleting any source files.
• Error Handling (ComposeCleanupError):
  • Added a new ComposeCleanupError class.
  • If the compose succeeds but any source file deletion fails, a ComposeCleanupError is thrown/returned.
  • The error lists all individual deletion failures (errors) and attaches the newly composed file (newFile) and raw apiResponse so they are still accessible to the caller.
• Tests: Added comprehensive unit tests in test/bucket.ts verifying all success, failure, and partial cleanup error conditions.

Thank you for opening a Pull Request! Before submitting your PR, there are a few things you can do to make sure it goes smoothly:

• Make sure to open an issue as a bug/issue before writing your code! That way we can discuss the change, evaluate designs, and agree on the general idea
• Ensure the tests and linter pass
• Code coverage does not decrease (if any source code was changed)
• Appropriate docs were updated (if necessary)

Fixes #<issue_number_goes_here> 🦕

[gemini-code-assist]

Code Review

This pull request introduces a new deleteSourceObjects option for the combine operation in the Bucket class, allowing for the automatic deletion of source objects after a successful compose operation. It also adds a ComposeCleanupError class to handle partial failures during this cleanup process. The review feedback highlights critical safety and robustness concerns regarding potential data loss and concurrent deletion issues, suggesting the use of ifGenerationMatch and ignoreNotFound: true in the delete calls, along with corresponding updates to the test suite.

[v-pratap]

Why do we only check source.metadata.generation when building the Compose payload, but check both source.generation ?? source.metadata?.generation during the delete phase?

[thiyaguk09]

I updated Compose payload generation checks to match delete cleanup logic for consistency.