feat: add IndexedDB cache migrations and quota recovery

[whitezaddy]

Fix: Add IndexedDB cache migrations and quota recovery

Closes #207

Problem

Previously, IndexedDBCache would unconditionally delete both the announcements and meta stores whenever the schema version changed. This meant that a browser upgrade or schema bump could wipe out the entire scan cache, leading to data loss and degraded performance while forcing clients to rebuild from scratch. Additionally, it did not distinguish QuotaExceededError from other write errors, lacking the ability to dynamically adapt when the browser's storage limits were hit.

Solution

This PR resolves these issues by introducing safe versioned migrations and bounded quota recovery for IndexedDB:

• Versioned Migrations: Modified the onupgradeneeded handler in IndexedDBCache to check oldVersion and only create stores/indices if they don't already exist. It no longer aggressively drops stores when version bumps occur.
• Bounded Eviction & Quota Recovery: IndexedDBCache.put now natively catches QuotaExceededError. If the quota is exceeded, the cache falls back to aggressive bounded eviction (halving its capacity limits to make room) and retries the operation.
• Typed Quota Errors: If the quota limits still persist after an aggressive eviction sweep, it throws a new exported CacheQuotaError, providing a typed error for callers to handle.
• Cursor Preservation: Bounded eviction logic only removes items from the announcements store. The meta store remains untouched during eviction sweeps, ensuring that the lastSeen cursor safely survives quota panics.

Testing

Added comprehensive unit tests inside cache.idb.test.ts:

• Added a non-destructive schema migration test to simulate and ensure stores aren't dropped on bumps.
• Added tests utilizing a mocked IDBObjectStore to throw QuotaExceededError intentionally.
• Verified that bounded eviction triggers properly, retries the operation, and gracefully recovers without disrupting lastSeen.
• Verified that a persistent QuotaExceededError throws the explicit CacheQuotaError.

[drips-wave]

@whitezaddy Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[truthixify]

The migration test never changes the database version, and CACHE_VERSION remains 1, so it only reopens the same schema. Please add a real version step and prove records and the last-seen cursor survive a v1 to v2 upgrade.

[whitezaddy]

The migration test never changes the database version, and CACHE_VERSION remains 1, so it only reopens the same schema. Please add a real version step and prove records and the last-seen cursor survive a v1 to v2 upgrade.

Working on it

[whitezaddy]

The migration test never changes the database version, and CACHE_VERSION remains 1, so it only reopens the same schema. Please add a real version step and prove records and the last-seen cursor survive a v1 to v2 upgrade.

Kindly review again

[truthixify]

The migration and quota tests now cover the requested paths. One blocker remains: CacheQuotaError is only exported from cache.ts, while the Stellar public barrel exports IndexedDBCache without the error. Please export CacheQuotaError from src/chains/stellar/index.ts so callers can handle the typed failure.

[whitezaddy]

The migration and quota tests now cover the requested paths. One blocker remains: CacheQuotaError is only exported from cache.ts, while the Stellar public barrel exports IndexedDBCache without the error. Please export CacheQuotaError from src/chains/stellar/index.ts so callers can handle the typed failure.

I have updated src/chains/stellar/index.ts to export CacheQuotaError so callers can now properly handle the typed error!
kindly review again

[truthixify]

Merged. The migration coverage and typed quota recovery now meet the issue requirements. Thanks for addressing the review carefully.