@dxos/plugin-sheet 0.6.12-main.c974201 → 0.6.12-main.f9d0246

package/src/graph/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';
@@ -22,6 +23,11 @@ import { CellError, ErrorType, EmptyValue, FunctionPlugin, type HyperFormula } f
 // TODO(burdon): Create wrapper.
 export type AsyncFunction = (...args: any) => Promise<InterpreterValue>;
 
+export type FunctionUpdateEvent = {
+  name: string;
+  cell: SimpleCellAddress;
+};
+
 export type FunctionOptions = {
   ttl?: number;
 };
@@ -30,6 +36,7 @@ export type FunctionContextOptions = {
   defaultTtl: number;
   recalculationDelay: number;
   remoteFunctionUrl: string;
+  onUpdate?: (update: FunctionUpdateEvent) => void;
 };
 
 export const defaultFunctionContextOptions: FunctionContextOptions = {
@@ -66,24 +73,24 @@ 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(() => {
+    this._onUpdate = debounce((update) => {
       // TODO(burdon): Better way to trigger recalculation?
       //  NOTE: rebuildAndRecalculate resets the undo history.
       this._hf.resumeEvaluation();
-      onUpdate(this);
+      this._options.onUpdate?.(update);
     }, this._options.recalculationDelay);
   }
 
-  // TODO(burdon): Remove?
   get space() {
     return this._space;
   }
@@ -136,7 +143,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 });

package/src/graph/compute-graph.stories.tsx

@@ -13,9 +13,10 @@ import { Toolbar, Button, Input } from '@dxos/react-ui';
 import { SyntaxHighlighter } from '@dxos/react-ui-syntax-highlighter';
 import { withTheme } from '@dxos/storybook-utils';
 
+import { testPlugins } from './testing';
 import { createSheet } from '../defs';
 import { useComputeGraph, useSheetModel } from '../hooks';
-import { withGraphDecorator } from '../testing';
+import { withComputeGraphDecorator } from '../testing';
 import { SheetType } from '../types';
 
 const FUNCTION_NAME = 'TEST';
@@ -26,7 +27,7 @@ const Story = () => {
   const [sheet, setSheet] = useState<SheetType>();
   const [text, setText] = useState(`${FUNCTION_NAME}(100)`);
   const [result, setResult] = useState<any>();
-  const model = useSheetModel(space, sheet);
+  const model = useSheetModel(graph, sheet);
   useEffect(() => {
     if (space) {
       const sheet = space.db.add(createSheet());
@@ -83,7 +84,7 @@ export default {
   title: 'plugin-sheet/functions',
   decorators: [
     withClientProvider({ types: [FunctionType, SheetType], createIdentity: true, createSpace: true }),
-    withGraphDecorator,
+    withComputeGraphDecorator({ plugins: testPlugins }),
     withTheme,
   ],
   render: (args: any) => <Story {...args} />,

package/src/graph/compute-graph.test.ts

@@ -0,0 +1,127 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type CellValue } from 'hyperformula';
+import { afterEach, beforeEach, describe, expect, test } from 'vitest';
+
+import { Trigger } from '@dxos/async';
+import { Client } from '@dxos/client';
+import { create, fullyQualifiedId } from '@dxos/client/echo';
+import { Context } from '@dxos/context';
+import { type S } from '@dxos/echo-schema';
+import { FunctionType } from '@dxos/plugin-script/types';
+
+import { ComputeGraphRegistry } from './compute-graph';
+import { testPlugins } from './testing';
+import { addressFromA1Notation, createSheet } from '../defs';
+import { SheetModel } from '../model';
+import { type CellScalarValue } from '../types';
+
+/**
+ * NOTE: Browser test required for hyperformula due to raw translation files.
+ */
+describe('compute graph', () => {
+  let ctx: Context;
+  beforeEach(() => {
+    ctx = new Context();
+  });
+  afterEach(async () => {
+    await ctx.dispose();
+  });
+
+  // TODO(burdon): Replace with builder.
+  const createModel = async (types?: S.Schema<any>[]) => {
+    const client = new Client();
+    if (types) {
+      // TODO(burdon): Add to config.
+      client.addTypes(types);
+    }
+    await client.initialize();
+    await client.halo.createIdentity();
+    const space = await client.spaces.create();
+    ctx.onDispose(() => client.destroy());
+
+    const registry = new ComputeGraphRegistry({ plugins: testPlugins });
+    await registry.open();
+    ctx.onDispose(() => registry.close());
+
+    const graph = await registry.createGraph(space);
+
+    const sheet = createSheet({ rows: 5, columns: 5 });
+    const model = new SheetModel(graph, sheet);
+    await model.open();
+
+    return { space, graph, model };
+  };
+
+  test('map functions', async () => {
+    const { space, graph } = await createModel([FunctionType]);
+
+    // Create script.
+    const trigger = new Trigger();
+    graph.update.once(() => trigger.wake());
+    const fn = space.db.add(create(FunctionType, { version: 1, binding: 'TEST' }));
+    await trigger.wait();
+    expect(graph.getFunctions({ echo: true })).to.toHaveLength(1);
+
+    const id = graph.mapFunctionBindingToId('TEST()');
+    expect(id).to.eq(`${fullyQualifiedId(fn)}()`);
+  });
+
+  test('cross-node references', async () => {
+    const { graph } = await createModel();
+
+    // Create nodes.
+    const node1 = await graph.getOrCreateNode('node-1');
+    const node2 = await graph.getOrCreateNode('node-2');
+
+    {
+      expect(graph.hf.getSheetNames()).to.toHaveLength(3);
+      node1.graph.hf.setCellContents({ sheet: node1.sheetId, row: 0, col: 0 }, [[100, 200, 300, '=SUM(A1:C1)']]);
+      node2.graph.hf.setCellContents({ sheet: node2.sheetId, row: 0, col: 0 }, "='node-1'!D1");
+      const value1 = node1.graph.hf.getCellValue({ sheet: node1.sheetId, col: 3, row: 0 });
+      const value2 = node2.graph.hf.getCellValue({ sheet: node2.sheetId, col: 0, row: 0 });
+      expect(value1).to.eq(value2);
+    }
+
+    // Get updated event.
+    const trigger = new Trigger<CellValue>();
+    node2.update.on(({ change }) => {
+      const value = node2.graph.hf.getCellValue({ sheet: node2.sheetId, col: 0, row: 0 });
+      expect(value).to.eq(change?.newValue);
+      trigger.wake(value);
+    });
+
+    {
+      node1.graph.hf.setCellContents({ sheet: node1.sheetId, row: 0, col: 0 }, 400);
+      const value1 = node1.graph.hf.getCellValue({ sheet: node1.sheetId, col: 3, row: 0 });
+      const value2 = await trigger.wait();
+      expect(value1).to.eq(value2);
+    }
+  });
+
+  test('async function', async () => {
+    const { graph, model } = await createModel();
+
+    // Triggers function.
+    model.setValue(addressFromA1Notation('A1'), '=TEST()');
+    const trigger = new Trigger<CellScalarValue>();
+    model.update.once(({ type }) => {
+      if (type === 'valuesUpdated') {
+        const value = model.getValue(addressFromA1Notation('A1'));
+        trigger.wake(value);
+      }
+    });
+
+    // Get initial value (null).
+    const v1 = model.getValue(addressFromA1Notation('A1'));
+    expect(v1).to.be.null;
+    expect(graph.context.info.invocations.TEST).to.eq(undefined);
+
+    // Wait until async update triggered.
+    const v2 = await trigger.wait();
+    expect(v2).not.to.be.null;
+    expect(graph.context.info.invocations.TEST).to.eq(1);
+  });
+});

package/src/graph/compute-graph.ts

@@ -4,7 +4,9 @@
 
 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';
@@ -15,7 +17,7 @@ import { log } from '@dxos/log';
 import { FunctionType } from '@dxos/plugin-script/types';
 import { nonNullable } from '@dxos/util';
 
-import { HyperFormula } from '#hyperformula';
+import { ExportedCellChange, HyperFormula } from '#hyperformula';
 import { FunctionContext, type FunctionContextOptions } from './async-function';
 import { ComputeNode } from './compute-node';
 import { EdgeFunctionPlugin, EdgeFunctionPluginTranslations } from './edge-function';
@@ -43,14 +45,15 @@ export type ComputeGraphOptions = {
 
 export const defaultOptions: ComputeGraphOptions = {
   licenseKey: 'gpl-v3',
-  plugins: [
-    {
-      plugin: EdgeFunctionPlugin,
-      translations: EdgeFunctionPluginTranslations,
-    },
-  ],
 };
 
+export const defaultPlugins: ComputeGraphPlugin[] = [
+  {
+    plugin: EdgeFunctionPlugin,
+    translations: EdgeFunctionPluginTranslations,
+  },
+];
+
 /**
  * Marker for sheets that are managed by an ECHO object.
  */
@@ -59,34 +62,29 @@ export const createSheetName = (id: string) => `${PREFIX}${id}`;
 export const getSheetId = (name: string): string | undefined =>
   name.startsWith(PREFIX) ? name.slice(PREFIX.length) : undefined;
 
-/**
- * NOTE: Async imports to decouple hyperformula deps.
- */
-export const createComputeGraphRegistry = (options: Partial<FunctionContextOptions> = {}) => {
-  return new ComputeGraphRegistry({
-    ...defaultOptions,
-    ...options,
-  });
-};
-
 /**
  * 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 _registry = new Map<SpaceId, ComputeGraph>();
+  private readonly _graphs = new Map<SpaceId, ComputeGraph>();
 
-  constructor(private readonly _options: ComputeGraphOptions = defaultOptions) {
+  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._registry.get(spaceId);
+    return this._graphs.get(spaceId);
   }
 
   async getOrCreateGraph(space: Space): Promise<ComputeGraph> {
@@ -100,22 +98,29 @@ export class ComputeGraphRegistry extends Resource {
   }
 
   async createGraph(space: Space): Promise<ComputeGraph> {
-    invariant(!this._registry.has(space.id), `ComputeGraph already exists for space: ${space.id}`);
+    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);
-    await graph.open(this._ctx);
-    this._registry.set(space.id, graph);
+    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 type ComputeGraphEvent = 'functionsUpdated';
+
 /**
  * Per-space compute and dependency graph.
  * Consists of multiple ComputeNode (corresponding to a HyperFormula sheet).
  * Manages the set of custom functions.
  * HyperFormula manages the dependency graph.
  */
-// TODO(burdon): Tests.
 export class ComputeGraph extends Resource {
   public readonly id = `graph-${PublicKey.random().truncate()}`;
 
@@ -125,13 +130,10 @@ export class ComputeGraph extends Resource {
   // Cached function objects.
   private _functions: FunctionType[] = [];
 
-  // The context is passed to all functions.
-  public readonly context = new FunctionContext(this._hf, this._space, this.refresh.bind(this), this._options);
+  public readonly update = new Event<{ type: ComputeGraphEvent }>();
 
-  // TODO(burdon): Typed events.
-  // TODO(burdon): Tie into HyperFormula dependency graph.
-  // TODO(burdon): Event propagation.
-  public readonly update = new Event();
+  // The context is passed to all functions.
+  public readonly context = new FunctionContext(this._hf, this._space, this._options);
 
   constructor(
     private readonly _hf: HyperFormula,
@@ -139,21 +141,36 @@ export class ComputeGraph extends Resource {
     private readonly _options?: Partial<FunctionContextOptions>,
   ) {
     super();
-
     this._hf.updateConfig({ context: this.context });
+    // TODO(burdon): If debounce then aggregate changes.
+    const onValuesUpdate: Listeners['valuesUpdated'] = (changes) => {
+      for (const change of changes) {
+        if (change instanceof ExportedCellChange) {
+          const { sheet } = change;
+          const node = this._nodes.get(sheet);
+          if (node) {
+            node.update.emit({ type: 'valuesUpdated', change });
+          }
+        }
+      }
+    };
+
+    this._hf.on('valuesUpdated', onValuesUpdate);
+    this._ctx.onDispose(() => this._hf.off('valuesUpdated', onValuesUpdate));
   }
 
-  // TODO(burdon): Remove.
   get hf() {
     return this._hf;
   }
 
-  refresh() {
-    log('refresh', { id: this.id });
-    this.update.emit();
-  }
+  // refresh() {
+  //   log('refresh', { id: this.id });
+  //   this.update.emit();
+  // }
 
-  getFunctions({ standard = true, echo = true }: { standard?: boolean; echo?: boolean } = {}): FunctionDefinition[] {
+  getFunctions(
+    { standard, echo }: { standard?: boolean; echo?: boolean } = { standard: true, echo: true },
+  ): FunctionDefinition[] {
     return [
       ...(standard
         ? this._hf
@@ -172,19 +189,19 @@ 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.
-  getOrCreateNode(name: string): ComputeNode {
+  async getOrCreateNode(name: string): Promise<ComputeNode> {
     invariant(name.length);
     if (!this._hf.doesSheetExist(name)) {
       log.info('created node', { space: this._space?.id, name });
       this._hf.addSheet(name);
-      this.update.emit();
+      // this.update.emit();
     }
 
     const sheetId = this._hf.getSheetId(name);
     invariant(sheetId !== undefined);
 
-    // TODO(burdon): Chain context?
     const node = new ComputeNode(this, sheetId);
+    await node.open();
     this._nodes.set(sheetId, node);
     return node;
   }
@@ -281,10 +298,16 @@ export class ComputeGraph extends Resource {
       const query = this._space.db.query(Filter.schema(FunctionType));
       const unsubscribe = query.subscribe(({ objects }) => {
         this._functions = objects.filter(({ binding }) => binding);
-        this.update.emit();
+        this.update.emit({ type: 'functionsUpdated' });
       });
 
       this._ctx.onDispose(unsubscribe);
     }
   }
+
+  protected override async _close() {
+    for (const node of this._nodes.values()) {
+      await node.close();
+    }
+  }
 }

package/src/graph/compute-node.ts

@@ -2,6 +2,9 @@
 // Copyright 2024 DXOS.org
 //
 
+import { type Listeners } from 'hyperformula/typings/Emitter';
+import { type ExportedCellChange } from 'hyperformula/typings/Exporter';
+
 import { Event } from '@dxos/async';
 import { Resource } from '@dxos/context';
 
@@ -10,13 +13,17 @@ import { type ComputeGraph } from './compute-graph';
 import { type CellAddress } from '../defs';
 import { type CellScalarValue } from '../types';
 
+export type ComputeNodeEvent = {
+  type: keyof Listeners;
+  change?: ExportedCellChange;
+};
+
 /**
  * Individual "sheet" (typically corresponds to an ECHO object).
  */
 // TODO(burdon): Factor out common HF wrapper from from SheetModel.
 export class ComputeNode extends Resource {
-  // TODO(burdon): Chaing events.
-  public readonly update = new Event();
+  public readonly update = new Event<ComputeNodeEvent>();
 
   constructor(
     private readonly _graph: ComputeGraph,
@@ -25,13 +32,12 @@ export class ComputeNode extends Resource {
     super();
   }
 
-  // TODO(burdon): Remove?
   get graph() {
     return this._graph;
   }
 
-  get hf() {
-    return this._graph.hf;
+  clear() {
+    this._graph.hf.clearSheet(this.sheetId);
   }
 
   getValue(cell: CellAddress): CellScalarValue {
@@ -48,4 +54,9 @@ export class ComputeNode extends Resource {
       typeof value === 'string' && value.charAt(0) === '=' ? this._graph.mapFormulaToNative(value) : value;
     this._graph.hf.setCellContents({ sheet: this.sheetId, row: cell.row, col: cell.col }, [[mappedValue]]);
   }
+
+  protected override async _open() {
+    // const unsubscribe = this._graph.update.on(this.update.emit);
+    // this._ctx.onDispose(unsubscribe);
+  }
 }

package/src/graph/edge-function.ts

@@ -74,8 +74,7 @@ EdgeFunctionPlugin.implementedFunctions = {
       // 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 },

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

@@ -8,8 +8,9 @@ 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 AsyncFunction, FunctionPluginAsync } from '../async-function';
+import { type ComputeGraphPlugin } from '../compute-graph';
+import { parseNumberString } from '../util';
 
 /**
  * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
@@ -64,3 +65,10 @@ export const CustomPluginTranslations = {
     CRYPTO: 'CRYPTO',
   },
 };
+
+export const testPlugins: ComputeGraphPlugin[] = [
+  {
+    plugin: CustomPlugin,
+    translations: CustomPluginTranslations,
+  },
+];

package/src/graph/testing/index.ts

@@ -0,0 +1,5 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './custom-function';

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,6 @@ 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 () => space && registry.getOrCreateGraph(space), [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;
 };