feat(storage): support transition + expiration + filter on lifecycle rules

[designcode]

Summary

• A lifecycle rule now accepts up to one transition (top-level storageClass + days/date), an optional expiration: { days?, date? }, and an optional filter: { prefix } on the same rule. At least one of transition or expiration must be present.
• Multiple rules per bucket are supported — each input rule is matched to an existing rule by id; unmatched existing rules are preserved unchanged. Single-rule + single-existing auto-matches without an id for back-compat.
• getBucketInfo returns the complete rule list in lifecycleRules — transitions, expirations, filtered rules, all of them. ttlConfig on the response is marked @deprecated and is no longer populated. Read the bucket-wide TTL from lifecycleRules (the rule with only expiration, no transition, no filter).
• setBucketTtl continues to work — it derives the existing TTL by scanning lifecycleRules itself.
• Existing single-rule, transition-only callers keep working without changes. BucketLifecycleExpiration is exported from the public surface.

Example

await setBucketLifecycle('my-bucket', {
  lifecycleRules: [
    {
      filter: { prefix: 'logs/' },
      storageClass: 'GLACIER',
      days: 30,
      expiration: { days: 30 },
    },
    {
      filter: { prefix: 'logs-2/' },
      storageClass: 'GLACIER_IR',
      days: 30,
      expiration: { days: 60 },
    },
  ],
});

Test plan

• npm run test --workspace=@tigrisdata/storage (134 passing)
• npm run build --workspace=@tigrisdata/storage (tsc + tsup clean)
• Smoke against a Tigris bucket: set two prefix-scoped rules each carrying transition + expiration, then getBucketInfo and confirm round-trip; toggle one rule by id via setBucketLifecycle and confirm the other is preserved.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes lifecycle rule serialization/merging and getBucketInfo normalization, which could affect how bucket retention/transition policies are applied and preserved across updates. Extensive tests reduce risk but behavior changes for existing lifecycle configurations merit caution.

Overview
Extends bucket lifecycle support to multiple rules per bucket, where each rule can include a single transition plus optional expiration and optional filter.prefix, and updates are merged into existing bucket rules primarily by id (with a constrained no-id auto-match for back-compat).

getBucketInfo now returns the full lifecycle rule list (including expirations and filters) via settings.lifecycleRules, and settings.ttlConfig is marked deprecated and is no longer populated; setBucketTtl derives the bucket-wide TTL by scanning lifecycleRules and avoids duplicating the TTL-shaped rule.

Updates include new public types (BucketLifecycleExpiration, BucketLifecycleFilter), API shape support for lifecycle rule filters, tightened validation in setBucketLifecycle/buildLifecycleRules, and a large expansion of lifecycle merging test coverage.

^{Reviewed by Cursor Bugbot for commit 076417f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

This PR extends lifecycle rules to support multiple transitions per rule (e.g. STANDARD_IA at 30 days → GLACIER at 90) and adds an optional filter.prefix to scope a rule to a key prefix, while keeping the existing single-transition shorthand fully backward-compatible.

• BucketLifecycleRule gains a transitions array and a filter field; new types BucketLifecycleTransition and BucketLifecycleFilter are exported.
• buildLifecycleRules / formatTransitionRule are refactored to resolve and merge transition arrays; getBucketInfo is updated to surface the full transitions array while back-populating the legacy storageClass/days/date fields from transitions[0].
• Validation in setBucketLifecycle is restructured to catch mixed usage of the two styles and validate each transition entry individually.

Confidence Score: 3/5

A filter-only rule with no existing lifecycle rule passes all guards and reaches the API with a body containing a filter but no transitions, which is likely invalid.

The core multi-transition and merge logic in resolveTransitions is sound and well-tested, but ruleHasTransitionContent treating filter as sufficient content creates a gap: a filter-only rule on a bucket with no existing lifecycle rule bypasses all guards and triggers an API call with a lifecycle rule body that has no transitions array, which is likely invalid and will produce an unexpected error or silently malformed state.

packages/storage/src/lib/bucket/set/lifecycle.ts — the filter-only validation gap; packages/storage/src/lib/bucket/types.ts — the inaccurate JSDoc.

Important Files Changed

Filename	Overview
packages/storage/src/lib/bucket/set/lifecycle.ts	Validation logic restructured to support multi-transition and filter fields; a filter-only rule with no existing transitions can slip past guards and produce an API body with no transitions.
packages/storage/src/lib/bucket/utils/lifecycle.ts	Core rule-building logic cleanly refactored to handle multiple transitions and filter merging; the resolveTransitions branching logic is correct for the defined cases.
packages/storage/src/lib/bucket/types.ts	New types BucketLifecycleTransition and BucketLifecycleFilter added cleanly; JSDoc on BucketLifecycleRule incorrectly states "transitions wins" when both fields are set, but runtime behaviour is actually an error.
packages/storage/src/lib/bucket/info.ts	Mapping updated to expose full transitions array and filter while populating legacy fields from transitions[0] for backward compatibility.
packages/storage/src/lib/bucket/utils/lifecycle.test.ts	10 new test cases covering multi-transition rules, filter handling, and toggle-only preservations; no coverage for the filter-only + no-existing-rule edge case.
packages/storage/src/lib/bucket/utils/api.ts	Added filter.prefix field to the API type shape; straightforward, no issues.
packages/storage/src/server.ts	New types re-exported from the public surface; no issues.
packages/storage/README.md	Documentation updated with new property tables and a multi-transition example; content is accurate and clear.

_{Reviews (1): Last reviewed commit: "feat(storage): support multiple lifecycl..." | Re-trigger Greptile}

[garrensmith]

@greptileai review and summarise

[garrensmith]

This seems like a valid error:

A filter-only rule with no existing lifecycle rule passes all guards and reaches the API with a body containing a filter but no transitions, which is likely invalid.

The core multi-transition and merge logic in resolveTransitions is sound and well-tested, but ruleHasTransitionContent treating filter as sufficient content creates a gap: a filter-only rule on a bucket with no existing lifecycle rule bypasses all guards and triggers an API call with a lifecycle rule body that has no transitions array, which is likely invalid and will produce an unexpected error or silently malformed state.

[designcode]

Agreed — fixed. setBucketLifecycle now rejects rules with no transition and no expiration unless they target an existing rule via id, so filter-only and toggle-only inputs without an id error out before the network round-trip rather than reaching buildLifecycleRules with a malformed body. Also added a final-shape check inside buildLifecycleRules that catches partial updates which fail to merge into a complete rule.

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 9968a48. Configure here.}

[github-actions]

🎉 This PR is included in version 3.4.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀