Skip to content

v0.60.0 - Global Cache Sharing for Gaskets (2026-03-31)

What Changed?

This release introduces CacheLedger, a singleton pattern for sharing cache across multiple gasket instances within a GAS execution context. The SheetGasket class now uses this global cache, eliminating redundant API calls when multiple instances access the same sheets. All cache keys are namespaced by spreadsheet ID to prevent collisions between sheets in different spreadsheets.

What's New

CacheLedger Singleton

What it does: CacheLedger is a global singleton that manages a shared JunkPocket cache across all gasket instances. This prevents multiple instances from making redundant API calls to the same resources within a single GAS execution (6-minute limit). Resources are automatically cleaned up when execution ends.

How to use it: The change is transparent to users. SheetGasket now uses CacheLedger automatically. Multiple instances will share cached sheets without any code changes needed:

TypeScript
const gasket1 = new SheetGasket({ name: "sheets1" });
const gasket2 = new SheetGasket({ name: "sheets2" });
const book = SpreadsheetApp.getActiveSpreadsheet();

// First call: API hit
const sheet1 = gasket1.getByName(book, "Sales");

// Second call: Cache hit (same object reference)
const sheet2 = gasket2.getByName(book, "Sales");
// sheet1 === sheet2

Key Design Details:

  • Cache keys use the format sheet:<spreadsheetId>:<identifier> to prevent collisions
  • Different spreadsheets maintain separate cache entries even for sheets with the same name
  • For testing, call CacheLedger.reset() in beforeEach hooks to ensure test isolation

Added

  • CacheLedger singleton class for global cache management
  • Comprehensive test suite for cache behavior and key format validation

Changed

  • SheetGasket now uses CacheLedger.getInstance() instead of instance-level cache
  • Cache key format updated from simple names to namespaced format: sheet:<bookId>:<identifier>
  • All SheetGasket methods (getByName, getById, getActive, getOrCreate, getSheets) updated to use namespaced keys

Is It Safe to Upgrade?

  • Breaking Changes: No
  • Backward Compatible: Yes

SheetGasket's public API is unchanged. The switch to global caching is transparent to users. All existing code continues to work without modification. The only visible improvement is reduced API call overhead when multiple instances access the same sheets.

Release Details

  • Date: 2026-03-31
  • Version: v0.60.0
  • gaslamp: 119
  • pilotlamp: 77
  • Files Changed: 5
  • Commits:
    • adfa9d58 feat(gears): add CacheLedger singleton for shared cache management
    • 00ff6fb7 refactor(gears): use unknown instead of any for CacheLedger generic type
    • 81697a16 feat(gaskets): integrate CacheLedger into SheetGasket for cache sharing

Known Issues

None at this time.

Next Steps

  • Extend CacheLedger integration to other gasket classes (BookGasket, future gasket implementations)
  • Consider implementing cache eviction strategies for long-running scripts
  • Monitor cache efficiency metrics in real-world GAS deployments