@dxos/plugin-sheet 0.6.12-main.f9d0246 → 0.6.12-staging.e11e696

package/src/graph/compute-graph.ts

@@ -2,116 +2,45 @@
 // Copyright 2024 DXOS.org
 //
 
-import { type FunctionPluginDefinition } from 'hyperformula';
-import { type ConfigParams } from 'hyperformula/typings/ConfigParams';
 import { type Listeners } from 'hyperformula/typings/Emitter';
-import { type FunctionTranslationsPackage } from 'hyperformula/typings/interpreter';
-import defaultsDeep from 'lodash.defaultsdeep';
 
 import { Event } from '@dxos/async';
-import { type SpaceId, type Space, Filter, fullyQualifiedId } from '@dxos/client/echo';
+import { type Space, Filter, fullyQualifiedId } from '@dxos/client/echo';
 import { Resource } from '@dxos/context';
+import { getTypename } from '@dxos/echo-schema';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
 import { FunctionType } from '@dxos/plugin-script/types';
 import { nonNullable } from '@dxos/util';
 
-import { ExportedCellChange, HyperFormula } from '#hyperformula';
-import { FunctionContext, type FunctionContextOptions } from './async-function';
+import { ExportedCellChange, type HyperFormula } from '#hyperformula';
 import { ComputeNode } from './compute-node';
-import { EdgeFunctionPlugin, EdgeFunctionPluginTranslations } from './edge-function';
-import { defaultFunctions, type FunctionDefinition } from './function-defs';
-
-//
-// NOTE: The package.json file defines the packaged #hyperformula module.
-//
+import {
+  defaultFunctions,
+  FunctionContext,
+  type FunctionContextOptions,
+  type FunctionDefinition,
+  EDGE_FUNCTION_NAME,
+} from './functions';
 
 // TODO(wittjosiah): Factor out.
-const OBJECT_ID_LENGTH = 60; // 33 (space id) + 26 (object id) + 1 (separator).
-
-// TODO(burdon): Change to "DX".
-const CUSTOM_FUNCTION = 'ECHO';
+const OBJECT_ID_LENGTH = 60; // 33 (space id) + 1 (separator) + 26 (object id).
 
-export type ComputeGraphPlugin = {
-  plugin: FunctionPluginDefinition;
-  translations: FunctionTranslationsPackage;
-};
-
-export type ComputeGraphOptions = {
-  plugins?: ComputeGraphPlugin[];
-} & Partial<FunctionContextOptions> &
-  Partial<ConfigParams>;
-
-export const defaultOptions: ComputeGraphOptions = {
-  licenseKey: 'gpl-v3',
-};
+// TODO(burdon): Factory.
+// export type ComputeNodeGenerator = <T>(obj: T) => ComputeNode;
 
-export const defaultPlugins: ComputeGraphPlugin[] = [
-  {
-    plugin: EdgeFunctionPlugin,
-    translations: EdgeFunctionPluginTranslations,
-  },
-];
+type ObjectRef = { type: string; id: string };
 
 /**
  * Marker for sheets that are managed by an ECHO object.
+ * Sheet ID: `dxos.org/type/SheetType@1234`
  */
-const PREFIX = '__';
-export const createSheetName = (id: string) => `${PREFIX}${id}`;
-export const getSheetId = (name: string): string | undefined =>
-  name.startsWith(PREFIX) ? name.slice(PREFIX.length) : undefined;
-
-/**
- * Manages a collection of ComputeGraph instances for each space.
- *
- * [ComputePlugin] => [ComputeGraphRegistry] => [ComputeGraph(Space)] => [ComputeNode(Object)]
- *
- * NOTE: The ComputeGraphRegistry manages the hierarchy of resources via its root Context.
- */
-// TODO(burdon): Move graph into separate plugin; isolate HF deps.
-export class ComputeGraphRegistry extends Resource {
-  private readonly _graphs = new Map<SpaceId, ComputeGraph>();
-
-  private readonly _options: ComputeGraphOptions;
-
-  constructor(options: ComputeGraphOptions = { plugins: defaultPlugins }) {
-    super();
-    this._options = defaultsDeep({}, options, defaultOptions);
-    this._options.plugins?.forEach(({ plugin, translations }) => {
-      HyperFormula.registerFunctionPlugin(plugin, translations);
-    });
-  }
-
-  getGraph(spaceId: SpaceId): ComputeGraph | undefined {
-    return this._graphs.get(spaceId);
-  }
-
-  async getOrCreateGraph(space: Space): Promise<ComputeGraph> {
-    let graph = this.getGraph(space.id);
-    if (!graph) {
-      log.info('create graph', { space: space.id });
-      graph = await this.createGraph(space);
-    }
-
-    return graph;
-  }
-
-  async createGraph(space: Space): Promise<ComputeGraph> {
-    invariant(!this._graphs.has(space.id), `ComputeGraph already exists for space: ${space.id}`);
-    const hf = HyperFormula.buildEmpty(this._options);
-    const graph = new ComputeGraph(hf, space, this._options);
-    this._graphs.set(space.id, graph);
-    await graph.open();
-    return graph;
-  }
-
-  protected override async _close() {
-    for (const graph of this._graphs.values()) {
-      await graph.close();
-    }
-  }
-}
+export const createSheetName = ({ type, id }: ObjectRef) => `${type}@${id}`;
+export const parseSheetName = (name: string): Partial<ObjectRef> => {
+  const [type, id] = name.split('@');
+  return id ? { type, id } : { id: type };
+};
 
 export type ComputeGraphEvent = 'functionsUpdated';
 
@@ -128,7 +57,7 @@ export class ComputeGraph extends Resource {
   private readonly _nodes = new Map<number, ComputeNode>();
 
   // Cached function objects.
-  private _functions: FunctionType[] = [];
+  private _remoteFunctions: FunctionType[] = [];
 
   public readonly update = new Event<{ type: ComputeGraphEvent }>();
 
@@ -163,11 +92,6 @@ export class ComputeGraph extends Resource {
     return this._hf;
   }
 
-  // refresh() {
-  //   log('refresh', { id: this.id });
-  //   this.update.emit();
-  // }
-
   getFunctions(
     { standard, echo }: { standard?: boolean; echo?: boolean } = { standard: true, echo: true },
   ): FunctionDefinition[] {
@@ -177,7 +101,7 @@ export class ComputeGraph extends Resource {
             .getRegisteredFunctionNames()
             .map((name) => defaultFunctions.find((fn) => fn.name === name) ?? { name })
         : []),
-      ...(echo ? this._functions.map((fn) => ({ name: fn.binding! })) : []),
+      ...(echo ? this._remoteFunctions.map((fn) => ({ name: fn.binding! })) : []),
     ];
   }
 
@@ -189,19 +113,17 @@ export class ComputeGraph extends Resource {
   //  This would enable on-the-fly instantiation of new models when then are referenced.
   //  E.g., Cross-object reference would be stored as "ObjectId!A1"
   //  The graph would then load the object and create a ComputeNode (model) of the appropriate type.
-  async getOrCreateNode(name: string): Promise<ComputeNode> {
+  getOrCreateNode(name: string): ComputeNode {
     invariant(name.length);
     if (!this._hf.doesSheetExist(name)) {
-      log.info('created node', { space: this._space?.id, name });
+      log.info('created node', { space: this._space?.id, sheet: name });
       this._hf.addSheet(name);
-      // this.update.emit();
     }
 
     const sheetId = this._hf.getSheetId(name);
     invariant(sheetId !== undefined);
 
     const node = new ComputeNode(this, sheetId);
-    await node.open();
     this._nodes.set(sheetId, node);
     return node;
   }
@@ -213,22 +135,27 @@ export class ComputeGraph extends Resource {
   mapFormulaToNative(formula: string): string {
     return (
       formula
-        // Sheet references.
+        //
+        // Map cross-sheet references by name onto sheet stored by ECHO object/model.
+        // Example: "Test Sheet"!A0 => "dxos.org/type/SheetType@1234"!A0
         // https://hyperformula.handsontable.com/guide/cell-references.html#cell-references
+        //
         .replace(/['"]?([ \w]+)['"]?!/, (_match, name) => {
           if (name) {
-            // TODO(burdon): What if not loaded?
+            // TODO(burdon): Cache map.
             const objects = this._hf
               .getSheetNames()
               .map((name) => {
-                const id = getSheetId(name);
-                return id ? this._space?.db.getObjectById(id) : undefined;
+                const { type, id } = parseSheetName(name);
+                return type && id ? this._space?.db.getObjectById(id) : undefined;
               })
               .filter(nonNullable);
 
             for (const obj of objects) {
-              if (obj.name === name || obj.title === name) {
-                return `${createSheetName(obj.id)}!`;
+              if (obj.name === name) {
+                const type = getTypename(obj)!;
+                // NOTE: Names must be single quoted.
+                return `'${createSheetName({ type, id: obj.id })}'!`;
               }
             }
           }
@@ -236,17 +163,19 @@ export class ComputeGraph extends Resource {
           return `${name}!`;
         })
 
-        // Functions.
+        //
+        // Map remote function references (i.e., to remote DX function invocation).
+        //
         .replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
-          const fn = this._functions.find((fn) => fn.binding === binding);
+          const fn = this._remoteFunctions.find((fn) => fn.binding === binding);
           if (!fn) {
             return match;
           }
 
           if (args.trim() === '') {
-            return `${CUSTOM_FUNCTION}("${binding}")`;
+            return `${EDGE_FUNCTION_NAME}("${binding}")`;
           } else {
-            return `${CUSTOM_FUNCTION}("${binding}", ${args})`;
+            return `${EDGE_FUNCTION_NAME}("${binding}", ${args})`;
           }
         })
     );
@@ -258,11 +187,11 @@ export class ComputeGraph extends Resource {
    */
   mapFunctionBindingToId(formula: string) {
     return formula.replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
-      if (binding === CUSTOM_FUNCTION || defaultFunctions.find((fn) => fn.name === binding)) {
+      if (binding === EDGE_FUNCTION_NAME || defaultFunctions.find((fn) => fn.name === binding)) {
         return match;
       }
 
-      const fn = this._functions.find((fn) => fn.binding === binding);
+      const fn = this._remoteFunctions.find((fn) => fn.binding === binding);
       if (fn) {
         const id = fullyQualifiedId(fn);
         return `${id}(${args})`;
@@ -283,7 +212,7 @@ export class ComputeGraph extends Resource {
         return match;
       }
 
-      const fn = this._functions.find((fn) => fullyQualifiedId(fn) === id);
+      const fn = this._remoteFunctions.find((fn) => fullyQualifiedId(fn) === id);
       if (fn?.binding) {
         return `${fn.binding}(${args})`;
       } else {
@@ -297,7 +226,7 @@ export class ComputeGraph extends Resource {
       // Subscribe to remote function definitions.
       const query = this._space.db.query(Filter.schema(FunctionType));
       const unsubscribe = query.subscribe(({ objects }) => {
-        this._functions = objects.filter(({ binding }) => binding);
+        this._remoteFunctions = objects.filter(({ binding }) => binding);
         this.update.emit({ type: 'functionsUpdated' });
       });
 

package/src/graph/compute-node.ts

@@ -55,6 +55,7 @@ export class ComputeNode extends Resource {
     this._graph.hf.setCellContents({ sheet: this.sheetId, row: cell.row, col: cell.col }, [[mappedValue]]);
   }
 
+  // TODO(burdon): Load data into sheet.
   protected override async _open() {
     // const unsubscribe = this._graph.update.on(this.update.emit);
     // this._ctx.onDispose(unsubscribe);

package/src/graph/{async-function.ts → functions/async-function.ts}

@@ -14,13 +14,12 @@ import { log } from '@dxos/log';
 
 import { CellError, ErrorType, EmptyValue, FunctionPlugin, type HyperFormula } from '#hyperformula';
 
-// TODO(burdon): API gateways!
+// TODO(burdon): Create API gateways:
 //  https://publicapis.io
 //  https://api-ninjas.com/api/cryptoprice
 //  https://developers.google.com/apis-explorer
 //  https://publicapis.io/coin-desk-api
 
-// TODO(burdon): Create wrapper.
 export type AsyncFunction = (...args: any) => Promise<InterpreterValue>;
 
 export type FunctionUpdateEvent = {
@@ -34,14 +33,14 @@ export type FunctionOptions = {
 
 export type FunctionContextOptions = {
   defaultTtl: number;
-  recalculationDelay: number;
+  debounceDelay: number;
   remoteFunctionUrl: string;
   onUpdate?: (update: FunctionUpdateEvent) => void;
 };
 
 export const defaultFunctionContextOptions: FunctionContextOptions = {
   defaultTtl: 5_000,
-  recalculationDelay: 200,
+  debounceDelay: 200,
   remoteFunctionUrl: 'https://edge.dxos.workers.dev/functions', // TODO(burdon): Config.
 };
 
@@ -84,11 +83,10 @@ export class FunctionContext {
   ) {
     this._options = defaultsDeep(_options ?? {}, defaultFunctionContextOptions);
     this._onUpdate = debounce((update) => {
-      // TODO(burdon): Better way to trigger recalculation?
-      //  NOTE: rebuildAndRecalculate resets the undo history.
+      // TODO(burdon): Better way to trigger recalculation? (NOTE: rebuildAndRecalculate resets the undo history.)
       this._hf.resumeEvaluation();
       this._options.onUpdate?.(update);
-    }, this._options.recalculationDelay);
+    }, this._options.debounceDelay);
   }
 
   get space() {
@@ -162,12 +160,15 @@ export class FunctionContext {
 /**
  * Base class for async functions.
  */
-export class FunctionPluginAsync extends FunctionPlugin {
+export class AsyncFunctionPlugin extends FunctionPlugin {
   get context() {
     return this.config.context as FunctionContext;
   }
 
-  runAsyncFunction(ast: ProcedureAst, state: InterpreterState, cb: AsyncFunction, options?: FunctionOptions) {
+  /**
+   * Immediately returns cached value then runs the async function.
+   */
+  protected runAsyncFunction(ast: ProcedureAst, state: InterpreterState, cb: AsyncFunction, options?: FunctionOptions) {
     const { procedureName } = ast;
     const metadata = this.metadata(procedureName);
     return this.runFunction(ast.args, state, metadata, (...args: any) => {

package/src/graph/{edge-function.ts → functions/edge-function.ts}

@@ -13,17 +13,19 @@ import { FunctionType } from '@dxos/plugin-script/types';
 import { nonNullable } from '@dxos/util';
 
 import { CellError, ErrorType, FunctionArgumentType } from '#hyperformula';
-import { type AsyncFunction, FunctionPluginAsync } from './async-function';
+import { type AsyncFunction, AsyncFunctionPlugin } from './async-function';
 
-const EDGE_FUNCTION_TTL = 10_000;
+export const EDGE_FUNCTION_NAME = 'DX';
+
+const FUNCTION_TTL = 10_000;
 
 /**
- * A hyperformula function plugin for calling EDGE functions.
+ * A hyperformula function plugin for calling remote (EDGE) functions.
  *
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
  */
-export class EdgeFunctionPlugin extends FunctionPluginAsync {
-  edge(ast: ProcedureAst, state: InterpreterState) {
+export class EdgeFunctionPlugin extends AsyncFunctionPlugin {
+  dx(ast: ProcedureAst, state: InterpreterState) {
     const handler =
       (subscribe = false): AsyncFunction =>
       async (binding: string, ...args: any) => {
@@ -47,7 +49,7 @@ export class EdgeFunctionPlugin extends FunctionPluginAsync {
 
             // TODO(wittjosiah): `ttl` should be 0 to force a recalculation when a new version is deployed.
             //  This needs a ttl to prevent a binding change from causing the function not to be found.
-            this.runAsyncFunction(ast, state, handler(false), { ttl: EDGE_FUNCTION_TTL });
+            this.runAsyncFunction(ast, state, handler(false), { ttl: FUNCTION_TTL });
           });
 
           this.context.createSubscription(ast.procedureName, unsubscribe);
@@ -63,13 +65,13 @@ export class EdgeFunctionPlugin extends FunctionPluginAsync {
         return await result.text();
       };
 
-    return this.runAsyncFunction(ast, state, handler(true), { ttl: EDGE_FUNCTION_TTL });
+    return this.runAsyncFunction(ast, state, handler(true), { ttl: FUNCTION_TTL });
   }
 }
 
 EdgeFunctionPlugin.implementedFunctions = {
-  EDGE: {
-    method: 'edge',
+  [EDGE_FUNCTION_NAME]: {
+    method: 'dx',
     parameters: [
       // Binding
       { argumentType: FunctionArgumentType.STRING },
@@ -90,9 +92,9 @@ EdgeFunctionPlugin.implementedFunctions = {
 
 export const EdgeFunctionPluginTranslations = {
   enGB: {
-    EDGE: 'EDGE',
+    [EDGE_FUNCTION_NAME]: 'Remote function',
   },
   enUS: {
-    EDGE: 'EDGE',
+    [EDGE_FUNCTION_NAME]: 'Remote function',
   },
 };

package/src/graph/functions/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './async-function';
+export * from './edge-function';
+export * from './function-defs';

package/src/graph/hyperformula.test.ts

@@ -7,8 +7,7 @@ import { describe, test, expect } from 'vitest';
 import { HyperFormula } from '#hyperformula';
 
 describe('hyperformula', () => {
-  test('sanity', async () => {
-    // TODO(burdon): Throws "Cannot convert undefined or null to object" in vitest (without browser).
+  test('sanity test', async () => {
     const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
     expect(hf).to.exist;
   });

package/src/graph/index.ts

@@ -3,5 +3,6 @@
 //
 
 export * from './compute-graph';
+export * from './compute-graph-registry';
 export * from './compute-node';
-export * from './function-defs';
+export * from './functions';

package/src/graph/testing/index.ts

@@ -2,4 +2,5 @@
 // Copyright 2024 DXOS.org
 //
 
-export * from './custom-function';
+export * from './test-builder';
+export * from './test-plugin';

package/src/graph/testing/test-builder.ts

@@ -0,0 +1,54 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { Client, type ClientOptions } from '@dxos/client';
+import { type Context, Resource } from '@dxos/context';
+import { invariant } from '@dxos/invariant';
+
+import { type ComputeGraphOptions, ComputeGraphRegistry } from '../compute-graph-registry';
+
+export type TestBuilderOptions = ClientOptions & ComputeGraphOptions;
+
+// TODO(burdon): Reconcile with @dxos/client/testing.
+export class TestBuilder extends Resource {
+  private _client?: Client;
+  private _registry?: ComputeGraphRegistry;
+
+  constructor(private readonly _options: TestBuilderOptions = {}) {
+    super();
+  }
+
+  get ctx(): Context {
+    return this._ctx;
+  }
+
+  get client(): Client {
+    invariant(this._client);
+    return this._client;
+  }
+
+  get registry(): ComputeGraphRegistry {
+    invariant(this._registry);
+    return this._registry;
+  }
+
+  override async _open() {
+    const client = new Client(this._options);
+    await client.initialize();
+    await client.halo.createIdentity();
+    this._client = client;
+    this._ctx.onDispose(async () => {
+      await client.destroy();
+      this._client = undefined;
+    });
+
+    const registry = new ComputeGraphRegistry(this._options);
+    await registry.open();
+    this._registry = registry;
+    this._ctx.onDispose(async () => {
+      await registry.close();
+      this._registry = undefined;
+    });
+  }
+}

package/src/graph/testing/{custom-function.ts → test-plugin.ts}

@@ -8,15 +8,30 @@ import { type ProcedureAst } from 'hyperformula/typings/parser';
 import { getDeep } from '@dxos/util';
 
 import { FunctionArgumentType } from '#hyperformula';
-import { type AsyncFunction, FunctionPluginAsync } from '../async-function';
-import { type ComputeGraphPlugin } from '../compute-graph';
+import { type ComputeGraphPlugin } from '../compute-graph-registry';
+import { type AsyncFunction, AsyncFunctionPlugin } from '../functions';
 import { parseNumberString } from '../util';
 
 /**
+ * Testing functions run locally (not run via EDGE).
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
  */
-export class CustomPlugin extends FunctionPluginAsync {
+export class TestPlugin extends AsyncFunctionPlugin {
+  /**
+   * Simple local function returns input value.
+   */
   test(ast: ProcedureAst, state: InterpreterState) {
+    const handler: AsyncFunction = async (_value) => {
+      return _value;
+    };
+
+    return this.runAsyncFunction(ast, state, handler);
+  }
+
+  /**
+   * Simple local function returns random number.
+   */
+  random(ast: ProcedureAst, state: InterpreterState) {
     const handler: AsyncFunction = async () => {
       return Math.random();
     };
@@ -24,6 +39,9 @@ export class CustomPlugin extends FunctionPluginAsync {
     return this.runAsyncFunction(ast, state, handler);
   }
 
+  /**
+   * Async HTTP function.
+   */
   crypto(ast: ProcedureAst, state: InterpreterState) {
     const handler: AsyncFunction = async (_currency) => {
       const currency = (_currency || 'USD').toUpperCase();
@@ -41,9 +59,15 @@ export class CustomPlugin extends FunctionPluginAsync {
   }
 }
 
-CustomPlugin.implementedFunctions = {
+TestPlugin.implementedFunctions = {
   TEST: {
     method: 'test',
+    parameters: [{ argumentType: FunctionArgumentType.NUMBER, optionalArg: false }],
+    isVolatile: true,
+  },
+
+  RANDOM: {
+    method: 'random',
     parameters: [],
     isVolatile: true,
   },
@@ -55,20 +79,22 @@ CustomPlugin.implementedFunctions = {
   },
 };
 
-export const CustomPluginTranslations = {
+export const TestPluginTranslations = {
   enGB: {
-    TEST: 'TEST',
-    CRYPTO: 'CRYPTO',
+    TEST: 'Returns input value',
+    RANDOM: 'Random number',
+    CRYPTO: 'Crypto token value',
   },
   enUS: {
-    TEST: 'TEST',
-    CRYPTO: 'CRYPTO',
+    TEST: 'Returns input value',
+    RANDOM: 'Random number',
+    CRYPTO: 'Crypto token value',
   },
 };
 
-export const testPlugins: ComputeGraphPlugin[] = [
+export const testFunctionPlugins: ComputeGraphPlugin[] = [
   {
-    plugin: CustomPlugin,
-    translations: CustomPluginTranslations,
+    plugin: TestPlugin,
+    translations: TestPluginTranslations,
   },
 ];

package/src/hooks/useComputeGraph.ts

@@ -16,6 +16,13 @@ import { type ComputeGraph } from '../graph';
  */
 export const useComputeGraph = (space?: Space): ComputeGraph | undefined => {
   const { registry } = useContext(ComputeGraphContext) ?? raise(new Error('Missing ComputeGraphContext'));
-  const [graph] = useAsyncState(async () => space && registry.getOrCreateGraph(space), [space, registry]);
+  const [graph] = useAsyncState(async () => {
+    if (space) {
+      const graph = registry.getOrCreateGraph(space);
+      await graph.open();
+      return graph;
+    }
+  }, [space, registry]);
+
   return graph;
 };

package/src/model/sheet-model.test.ts

@@ -0,0 +1,59 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Trigger } from '@dxos/async';
+import { FunctionType } from '@dxos/plugin-script/types';
+
+import { SheetModel } from './sheet-model';
+import { createSheet, addressFromA1Notation } from '../defs';
+import { TestBuilder, testFunctionPlugins } from '../graph/testing';
+import { type CellScalarValue } from '../types';
+
+// TODO(burdon): GPT("prompt", inputs); e.g., with large text cells.
+
+describe('SheetModel', () => {
+  let testBuilder: TestBuilder;
+  beforeEach(async () => {
+    testBuilder = new TestBuilder({ types: [FunctionType], plugins: testFunctionPlugins });
+    await testBuilder.open();
+  });
+  afterEach(async () => {
+    await testBuilder.close();
+  });
+
+  test('async function', async () => {
+    const space = await testBuilder.client.spaces.create();
+    const graph = testBuilder.registry.createGraph(space);
+    await graph.open();
+
+    // TODO(burdon): Create via factory.
+    const sheet = createSheet({ rows: 5, columns: 5 });
+    const model = new SheetModel(graph, sheet);
+    await model.open();
+    testBuilder.ctx.onDispose(() => model.close());
+
+    // Trigger waits for function invocation.
+    const trigger = new Trigger<CellScalarValue>();
+    model.setValue(addressFromA1Notation('A1'), '=TEST(100)');
+    model.update.once((update) => {
+      const { type } = update;
+      if (type === 'valuesUpdated') {
+        const value = model.getValue(addressFromA1Notation('A1'));
+        trigger.wake(value);
+      }
+    });
+
+    // Initial value will be null.
+    const v1 = model.getValue(addressFromA1Notation('A1'));
+    expect(v1).to.be.null;
+    expect(graph.context.info.invocations.TEST).not.to.exist;
+
+    // Wait until async update triggered.
+    const v2 = await trigger.wait();
+    expect(v2).to.eq(100);
+    expect(graph.context.info.invocations.TEST).to.eq(1);
+  });
+});