GridSheet 3.x.x

Version 3.x.x

The latest major version of GridSheet introducing comprehensive async/await support and enhanced filtering capabilities.

3.1.0 - Eager Resolution

🚀 Opt-in Eager Resolution

• options.eager / Sheet.eager: Opt into resolving every async formula cell regardless of the visible range. Because GridSheet is virtualized, off-screen async cells normally do not fire until scrolled into view; eager resolution fires them after each update so off-screen rows fill in automatically. Off by default to preserve virtualization, and scoped per sheet (one shared book can drive both eager and lazy sheets).
• Sheet.resolveAll(): number: New public method to fire all off-screen async cells on demand (e.g. right before saving) and return the number of async cells visited. Pair with waitForPending() to await settlement, after which serialization (toValueMatrix, etc.) returns resolved values for off-screen rows too.
• Targets only async cells: Sync formulas resolve on read and are skipped; already-resolved cells are not re-fired, so repeated resolution converges and stays cheap. Async cells are tracked via an incremental index, so cost scales with the number of async cells, not the total cell count.

🔧 Technical Improvements

• BaseFunction.isAsync (static): A static async marker readable from the function class without instantiating it, used to detect which formulas need eager resolution.

This release is fully backward compatible: all new behavior is opt-in and off by default.

3.0.0 - Major Release

🚀 Async Function Support

• Async Formula Execution: Full support for async/await patterns in custom formulas, enabling integration with external APIs and async operations
• Automatic Promise Resolution: The framework automatically handles Promise-based results from async formulas
• Enhanced Type System: Updated type definitions to accommodate async function declarations with full TypeScript support

🎯 Filtering & Sorting Improvements

• Async-Aware Filtering: Filtering operations now wait for all async computations to complete before applying filters
• Async-Aware Sorting: Sorting operations now properly handle data containing async formulas
• Filter Reflection on Operations: Fixed filter functionality to properly reflect in sheet operations including delete, copy, move, and paste (addresses issue #117)

🎨 UI/UX Enhancements

• Context Menu Support: Added handlers to open context menus on row headers and the top-left corner area of the spreadsheet
• Improved User Interaction: Enhanced menu accessibility for better spreadsheet navigation and operations

🔧 Technical Improvements

• Performance Optimizations: Optimized async computation handling for responsive UI during long-running operations
• Comprehensive Testing: Added extensive test coverage for async formula scenarios, including error handling and timeout cases
• Example Implementation: Added case11 demonstrating async formula usage and patterns

Breaking Changes

⚠️ Important: This version introduces breaking changes:

Sheet Public Methods

Several public methods on the sheet instance have been refactored to support async operations. Method signatures and return types may have been updated. Review the API documentation for updated specifications.

System Metadata Changes

System metadata (cell.system or cell._sys) is no longer available directly on the CellType object.

• Removed: changedAt property
• Added: changedTime property

System metadata must now be accessed via sheet.__raw__.getSystem(point). Update your code to use changedTime instead of changedAt when reading this metadata.

How to Create an Async Formula

Creating async formulas is straightforward. Extend BaseFunctionAsync instead of BaseFunction:

class MyAsyncFunction extends BaseFunctionAsync {
  example = 'MY_FUNC("arg1")';
  description = 'Fetches data asynchronously.';
  defs = [{ name: 'key', description: 'The key to fetch.' }];

  // Make main() async — the framework handles the rest
  async main(key: string) {
    const res = await fetch(`https://api.example.com/${key}`);
    const data = await res.json();
    return data.value;
  }
}

The async function will automatically be awaited during formula evaluation.