feat: Support asynchronous generateKey and validate the generated key

[AdrianCurtin]

Issue

Closes: #596

generateKey was called synchronously and its return value used unchecked, so a key could not be derived from anything asynchronous, and a bad return value failed late: undefined became the key <prefix>undefined, and an over-long key was rejected by S3 with an error that did not say which part was too long.

Separated out of #242, which originally carried this alongside a change to what createFile returns. The two are unrelated, and this one stands on its own.

Approach

• Awaited. The generator may be synchronous or asynchronous. A synchronous generator is unaffected, since awaiting a plain value is a no-op.
• Given more context. It now receives (filename, contentType, options) rather than just the filename, so a key can account for the content type or the upload's metadata and tags. Existing single-argument generators ignore the extra arguments.
• Validated. The result must be a non-empty string, and the key including bucketPrefix must be at most 1024 bytes of UTF-8, which is the S3 object key limit. The check counts bytes rather than characters, so a 600 character key of multibyte characters is correctly rejected at 1200 bytes.

Compatibility

Existing synchronous generators returning a sensible key behave exactly as before, which the current tests cover unchanged.

Two cases that used to be accepted now reject, both of which stored a file that could not be resolved afterwards:

• a generator returning a non-string or a blank string, previously stored as <prefix>undefined or a whitespace key
• a generator returning a key beyond the S3 limit, previously an opaque failure from S3

Validation applies only to generated keys. Filenames that pass through without a generator are untouched, keeping this change scoped to the feature.

Tests

spec/test.spec.js gains a generateKey block: a synchronous generator, an asynchronous one, the arguments handed to the generator, rejection for a non-string and for a blank string, propagation when an async generator rejects, a key exactly at the 1024 byte limit, a key past it, and a multibyte key that is short in characters but over the limit in bytes.

The README documents the async form, the arguments, and the constraints.

Full suite passes.

Related pull requests

These all touch createFile or getFileLocation in index.js. Merging them in this order leaves the fewest conflicts, verified by trial merges of all six together, which pass the suite once resolved:

#336 → #594 → #597 → #591 → #593 → #242

• fix: Prevent double-encoded presigned urls from s3 #336 presigned urls used a pre-encoded key
• fix: Bucket region is ignored, breaking access to buckets in opt-in regions #594 bucket region missing from the direct access url
• feat: Support asynchronous generateKey and validate the generated key #597 asynchronous generateKey
• fix: URL encoding of file location returned by createFile #591 percent-encoding of the Location url
• fix: File location returned by createFile omits the bucket when a custom endpoint is configured #593 Location omitted the bucket for custom endpoints
• feat: Revise createFile logic to return modified filenames and location #242 createFile reporting the stored name and url

#336 and #594 conflict with nothing. The rest collide on the createFile prologue and on the same anchor in spec/test.spec.js, where the conflict truncates each side's block, so the incoming describe has to be re-inserted whole rather than resolved line by line.

Conflict warning. The conflicting region includes const params = await this._buildCreateFileParams(...) from #597. Resolving in favor of the location work drops the await, which leaves a Promise where the params object is expected and fails every upload with TypeError: Cannot read properties of undefined (reading 'split'). Keep the await. Landing #597 first avoids the conflict entirely.

[parse-github-assistant]

🚀 Thanks for opening this pull request! We appreciate your effort in improving the project. Please let us know once your pull request is ready for review.

Tip

• Keep pull requests small. Large PRs will be rejected. Break complex features into smaller, incremental PRs.
• Use Test Driven Development. Write failing tests before implementing functionality. Ensure tests pass.
• Group code into logical blocks. Add a short comment before each block to explain its purpose.
• We offer conceptual guidance. Coding is up to you. PRs must be merge-ready for human review.
• Our review focuses on concept, not quality. PRs with code issues will be rejected. Use an AI agent.
• Human review time is precious. Avoid review ping-pong. Inspect and test your AI-generated code.

Note

Please respond to review comments from AI agents just like you would to comments from a human reviewer. Let the reviewer resolve their own comments, unless they have reviewed and accepted your commit, or agreed with your explanation for why the feedback was incorrect.

Caution

Pull requests must be written using an AI agent with human supervision. Pull requests written entirely by a human will likely be rejected, because of lower code quality, higher review effort and the higher risk of introducing bugs. Please note that AI review comments on this pull request alone do not satisfy this requirement. Our CI and AI review are safeguards, not development tools. If many issues are flagged, rethink your development approach. Invest more effort in planning and design rather than using review cycles to fix low-quality code.

[coderabbitai]

Warning

Review limit reached

@AdrianCurtin, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 46 seconds

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 63782e57-d1da-4474-96ef-460709d42146

📥 Commits

Reviewing files that changed from the base of the PR and between b9245cb and 8764c67.

📒 Files selected for processing (3)

• README.md
• index.js
• spec/test.spec.js

---

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.}