@dxos/plugin-sheet 0.6.12-main.15a606f → 0.6.12-main.568932b

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

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type SimpleCellAddress } from 'hyperformula/typings/Cell';
 import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
 import { type InterpreterValue } from 'hyperformula/typings/interpreter/InterpreterValue';
 import { type ProcedureAst } from 'hyperformula/typings/parser';
@@ -13,28 +14,33 @@ 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 = {
+  name: string;
+  cell: SimpleCellAddress;
+};
+
 export type FunctionOptions = {
   ttl?: number;
 };
 
 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.
 };
 
@@ -66,24 +72,23 @@ export class FunctionContext {
   private _invocations: Record<string, number> = {};
 
   private readonly _options: FunctionContextOptions;
-  private readonly _onUpdate: () => void;
+
+  // Debounced update handler.
+  private readonly _onUpdate: (update: FunctionUpdateEvent) => void;
 
   constructor(
     private readonly _hf: HyperFormula,
     private readonly _space: Space | undefined,
-    onUpdate: (context: FunctionContext) => void,
     _options?: Partial<FunctionContextOptions>,
   ) {
     this._options = defaultsDeep(_options ?? {}, defaultFunctionContextOptions);
-    this._onUpdate = debounce(() => {
-      // TODO(burdon): Better way to trigger recalculation?
-      //  NOTE: rebuildAndRecalculate resets the undo history.
+    this._onUpdate = debounce((update) => {
+      // TODO(burdon): Better way to trigger recalculation? (NOTE: rebuildAndRecalculate resets the undo history.)
       this._hf.resumeEvaluation();
-      onUpdate(this);
-    }, this._options.recalculationDelay);
+      this._options.onUpdate?.(update);
+    }, this._options.debounceDelay);
   }
 
-  // TODO(burdon): Remove?
   get space() {
     return this._space;
   }
@@ -136,7 +141,7 @@ export class FunctionContext {
           const value = await cb(...args);
           this._cache.set(invocationKey, { value, ts: Date.now() });
           log('set', { cell, value });
-          this._onUpdate();
+          this._onUpdate({ name, cell });
         } catch (err) {
           // TODO(burdon): Show error to user.
           log.warn('failed', { cell, err });
@@ -155,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,19 +65,18 @@ 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 },
 
-      // Remote function arguments (currently supporting up to 9).
-      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      // Remote function arguments (currently supporting up to 8).
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
       { argumentType: FunctionArgumentType.ANY, optionalArg: true },
@@ -91,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

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+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/{custom-function.ts → testing/test-plugin.ts}

@@ -8,14 +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 { parseNumberString } from './util';
+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();
     };
@@ -23,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();
@@ -40,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,
   },
@@ -54,13 +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 testFunctionPlugins: ComputeGraphPlugin[] = [
+  {
+    plugin: TestPlugin,
+    translations: TestPluginTranslations,
+  },
+];

package/src/hooks/hooks.stories.tsx

@@ -14,14 +14,14 @@ import { withTheme } from '@dxos/storybook-utils';
 import { ComputeGraphContextProvider } from '../components';
 import { createSheet } from '../defs';
 import { useComputeGraph, useSheetModel } from '../hooks';
-import { withGraphDecorator } from '../testing';
+import { withComputeGraphDecorator } from '../testing';
 import { SheetType } from '../types';
 
 const Story = () => {
   const space = useSpace();
   const graph = useComputeGraph(space);
   const [sheet, setSheet] = useState<SheetType>();
-  const model = useSheetModel(space, sheet);
+  const model = useSheetModel(graph, sheet);
   useEffect(() => {
     if (space) {
       const sheet = space.db.add(createSheet());
@@ -41,7 +41,7 @@ export default {
   component: ComputeGraphContextProvider,
   decorators: [
     withClientProvider({ types: [SheetType], createIdentity: true, createSpace: true }),
-    withGraphDecorator,
+    withComputeGraphDecorator(),
     withTheme,
   ],
   render: (args: any) => <Story {...args} />,

package/src/hooks/useComputeGraph.ts

@@ -16,5 +16,13 @@ import { type ComputeGraph } from '../graph';
  */
 export const useComputeGraph = (space?: Space): ComputeGraph | undefined => {
   const { registry } = useContext(ComputeGraphContext) ?? raise(new Error('Missing ComputeGraphContext'));
-  return 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/hooks/useSheetModel.ts

@@ -4,9 +4,7 @@
 
 import { useEffect, useState } from 'react';
 
-import { type Space } from '@dxos/react-client/echo';
-
-import { useComputeGraph } from './useComputeGraph';
+import { type ComputeGraph } from '../graph';
 import { SheetModel } from '../model';
 import { type SheetType } from '../types';
 
@@ -15,14 +13,13 @@ export type UseSheetModelOptions = {
 };
 
 export const useSheetModel = (
-  space?: Space,
+  graph?: ComputeGraph,
   sheet?: SheetType,
   { readonly }: UseSheetModelOptions = {},
 ): SheetModel | undefined => {
-  const graph = useComputeGraph(space);
   const [model, setModel] = useState<SheetModel>();
   useEffect(() => {
-    if (!space || !graph || !sheet) {
+    if (!graph || !sheet) {
       return;
     }
 
@@ -37,7 +34,7 @@ export const useSheetModel = (
       clearTimeout(t);
       void model?.close();
     };
-  }, [space, sheet, graph, readonly]);
+  }, [graph, sheet, readonly]);
 
   return model;
 };

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

@@ -0,0 +1,57 @@
+//
+// 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 { addressFromA1Notation, createSheet } from '../defs';
+import { TestBuilder, testFunctionPlugins } from '../graph/testing';
+import { type CellScalarValue } from '../types';
+
+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);
+  });
+});