@dxos/plugin-sheet 0.6.8-main.046e6cf

package/src/components/CellEditor/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './CellEditor';
+export * from './extension';

package/src/components/ComputeGraph/async-function.ts

@@ -0,0 +1,148 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { CellError, ErrorType, EmptyValue, FunctionPlugin, type HyperFormula } from 'hyperformula';
+import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
+import { type InterpreterValue } from 'hyperformula/typings/interpreter/InterpreterValue';
+import { type ProcedureAst } from 'hyperformula/typings/parser';
+
+import { debounce } from '@dxos/async';
+import { type Space } from '@dxos/client/echo';
+import { log } from '@dxos/log';
+
+// TODO(burdon): 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 FunctionOptions = {
+  ttl?: number;
+};
+
+export type FunctionContextOptions = {
+  defaultTtl: number;
+  recalculationDelay: number;
+};
+
+export const defaultFunctionContextOptions: FunctionContextOptions = {
+  defaultTtl: 5_000,
+  recalculationDelay: 200,
+};
+
+/**
+ * The context singleton for the model is passed into custom functions.
+ *
+ * HyperFormula does not support async functions.
+ * - https://hyperformula.handsontable.com/guide/custom-functions.html
+ * - https://hyperformula.handsontable.com/guide/known-limitations.html#known-limitations
+ * - https://github.com/handsontable/hyperformula/issues/892
+ */
+export class FunctionContext {
+  // Mangle name with params.
+  static createInvocationKey(name: string, ...args: any) {
+    return JSON.stringify({ name, ...args });
+  }
+
+  // Cached values for cell.
+  private readonly _cache = new Map<string, { value: InterpreterValue; ts: number }>();
+
+  // Active requests.
+  private readonly _pending = new Map<string, number>();
+
+  // Invocation count.
+  private _invocations: Record<string, number> = {};
+
+  private readonly _onUpdate: () => void;
+
+  constructor(
+    private readonly _hf: HyperFormula,
+    private readonly _space: Space | undefined,
+    onUpdate: (context: FunctionContext) => void,
+    private readonly _options = defaultFunctionContextOptions,
+  ) {
+    this._onUpdate = debounce(() => {
+      // TODO(burdon): Better way to trigger recalculation?
+      //  NOTE: rebuildAndRecalculate resets the undo history.
+      this._hf.resumeEvaluation();
+      onUpdate(this);
+    }, this._options.recalculationDelay);
+  }
+
+  get space() {
+    return this._space;
+  }
+
+  get info() {
+    return { cache: this._cache.size, invocations: this._invocations };
+  }
+
+  flush() {
+    this._cache.clear();
+    this._invocations = {};
+  }
+
+  /**
+   * Exec the function if TTL has expired.
+   * Return the cached value.
+   */
+  invokeFunction(
+    name: string,
+    state: InterpreterState,
+    args: any[],
+    cb: AsyncFunction,
+    options?: FunctionOptions,
+  ): InterpreterValue | undefined {
+    const ttl = options?.ttl ?? this._options.defaultTtl;
+
+    const { formulaAddress: cell } = state;
+    const invocationKey = FunctionContext.createInvocationKey(name, ...args);
+    const { value = undefined, ts = 0 } = this._cache.get(invocationKey) ?? {};
+
+    const now = Date.now();
+    const delta = now - ts;
+    if ((!ts || delta > ttl) && !this._pending.has(invocationKey)) {
+      this._pending.set(invocationKey, now);
+      setTimeout(async () => {
+        this._invocations[name] = (this._invocations[name] ?? 0) + 1;
+        try {
+          // Exec function.
+          const value = await cb(...args);
+          this._cache.set(invocationKey, { value, ts: Date.now() });
+          log('set', { cell, value });
+          this._onUpdate();
+        } catch (err) {
+          // TODO(burdon): Show error to user.
+          log.warn('failed', { cell, err });
+          this._cache.set(invocationKey, { value: new CellError(ErrorType.ERROR, 'Function failed.'), ts: Date.now() });
+        } finally {
+          this._pending.delete(invocationKey);
+        }
+      });
+    }
+
+    log('invoke', { cell, name, args, cache: value });
+    return value;
+  }
+}
+
+/**
+ * Base class for async functions.
+ */
+export class FunctionPluginAsync extends FunctionPlugin {
+  get context() {
+    return this.config.context as FunctionContext;
+  }
+
+  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) => {
+      return this.context.invokeFunction(procedureName, state, args, cb, options) ?? EmptyValue;
+    });
+  }
+}

package/src/components/ComputeGraph/custom.ts

@@ -0,0 +1,70 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { FunctionArgumentType } from 'hyperformula';
+import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
+import { type ProcedureAst } from 'hyperformula/typings/parser';
+
+import { getDeep } from '@dxos/util';
+
+import { type AsyncFunction, FunctionPluginAsync } from './async-function';
+
+// TODO(burdon): Factor out.
+const parseNumberString = (str: string): number => {
+  return parseFloat(str.replace(/[^\d.]/g, ''));
+};
+
+/**
+ * https://hyperformula.handsontable.com/guide/custom-functions.html#add-a-simple-custom-function
+ */
+export class CustomPlugin extends FunctionPluginAsync {
+  test(ast: ProcedureAst, state: InterpreterState) {
+    const handler: AsyncFunction = async () => {
+      return Math.random();
+    };
+
+    return this.runAsyncFunction(ast, state, handler);
+  }
+
+  crypto(ast: ProcedureAst, state: InterpreterState) {
+    const handler: AsyncFunction = async (_currency) => {
+      const currency = (_currency || 'USD').toUpperCase();
+      const result = await fetch(`https://api.coindesk.com/v1/bpi/currentprice/${currency}.json`);
+      const data = await result.json();
+      const rate = getDeep<string>(data, ['bpi', currency, 'rate']);
+      if (!rate) {
+        return NaN;
+      }
+
+      return parseNumberString(rate);
+    };
+
+    return this.runAsyncFunction(ast, state, handler, { ttl: 10_000 });
+  }
+}
+
+CustomPlugin.implementedFunctions = {
+  TEST: {
+    method: 'test',
+    parameters: [],
+    isVolatile: true,
+  },
+
+  CRYPTO: {
+    method: 'crypto',
+    parameters: [{ argumentType: FunctionArgumentType.STRING, optionalArg: true }],
+    isVolatile: true,
+  },
+};
+
+export const CustomPluginTranslations = {
+  enGB: {
+    TEST: 'TEST',
+    CRYPTO: 'CRYPTO',
+  },
+  enUS: {
+    TEST: 'TEST',
+    CRYPTO: 'CRYPTO',
+  },
+};

package/src/components/ComputeGraph/edge-function.ts

@@ -0,0 +1,60 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { CellError, ErrorType, FunctionArgumentType } from 'hyperformula';
+import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
+import { type ProcedureAst } from 'hyperformula/typings/parser';
+
+import { Filter, getMeta } from '@dxos/client/echo';
+import { getUserFunctionUrlInMetadata } from '@dxos/plugin-script/edge';
+import { ScriptType } from '@dxos/plugin-script/types';
+
+import { type AsyncFunction, FunctionPluginAsync } from './async-function';
+
+/**
+ * A hyperformula function plugin for calling 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) {
+    const handler: AsyncFunction = async (binding: string) => {
+      const space = this.context.space;
+      if (!space) {
+        return new CellError(ErrorType.VALUE, 'No space');
+      }
+
+      const {
+        objects: [script],
+      } = await space.db.query(Filter.schema(ScriptType, { binding })).run();
+      if (!script) {
+        return new CellError(ErrorType.VALUE, 'No script');
+      }
+
+      const path = getUserFunctionUrlInMetadata(getMeta(script));
+      // TODO(wittjosiah): Get base url from client config.
+      const result = await fetch(`https://functions-staging.dxos.workers.dev${path}`, { method: 'POST' });
+      return await result.text();
+    };
+
+    return this.runAsyncFunction(ast, state, handler, { ttl: 10_000 });
+  }
+}
+
+EdgeFunctionPlugin.implementedFunctions = {
+  EDGE: {
+    method: 'edge',
+    parameters: [{ argumentType: FunctionArgumentType.STRING }],
+    isVolatile: true,
+  },
+};
+
+export const EdgeFunctionPluginTranslations = {
+  enGB: {
+    EDGE: 'EDGE',
+  },
+  enUS: {
+    EDGE: 'EDGE',
+  },
+};

package/src/components/ComputeGraph/graph-context.tsx

@@ -0,0 +1,37 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import React, { createContext, type PropsWithChildren, useContext, useEffect } from 'react';
+
+import { type Space } from '@dxos/react-client/echo';
+
+import { createComputeGraph, type ComputeGraph } from './graph';
+
+export type ComputeGraphContextType = {
+  graphs: Record<string, ComputeGraph>;
+  setGraph: (key: string, graph: ComputeGraph) => void;
+};
+
+export const ComputeGraphContext = createContext<ComputeGraphContextType>({ graphs: {}, setGraph: () => {} });
+
+export const ComputeGraphContextProvider = ({
+  children,
+  graphs,
+  setGraph,
+}: PropsWithChildren<ComputeGraphContextType>) => {
+  return <ComputeGraphContext.Provider value={{ graphs, setGraph }}>{children}</ComputeGraphContext.Provider>;
+};
+
+export const useComputeGraph = (space: Space): ComputeGraph => {
+  const { graphs, setGraph } = useContext(ComputeGraphContext);
+  const graph = graphs[space.id] ?? createComputeGraph(space);
+
+  useEffect(() => {
+    if (!graphs[space.id]) {
+      setGraph(space.id, graph);
+    }
+  }, [space]);
+
+  return graph;
+};

package/src/components/ComputeGraph/graph.browser.test.ts

@@ -0,0 +1,49 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { expect } from 'chai';
+import { describe, test } from 'vitest';
+
+import { Trigger } from '@dxos/async';
+
+import { createComputeGraph } from './graph';
+import { addressFromA1Notation, SheetModel } from '../../model';
+import { type CellScalarValue, createSheet } from '../../types';
+
+/**
+ * VITEST_ENV=chrome p vitest --watch
+ * NOTE: Browser test required for hyperformula due to raw translation files.
+ */
+describe('compute graph', () => {
+  const createModel = async () => {
+    const graph = createComputeGraph();
+    const sheet = createSheet();
+    const model = new SheetModel(graph, sheet, { rows: 5, columns: 5 });
+    graph.update.on(() => model.update.emit());
+    return { graph, model };
+  };
+
+  test('async function', async () => {
+    const { graph, model } = await createModel();
+
+    // Triggers function.
+    model.setValue(addressFromA1Notation('A1'), '=TEST()');
+
+    const trigger = new Trigger<CellScalarValue>();
+    model.update.on(() => {
+      const value = model.getValue(addressFromA1Notation('A1'));
+      trigger.wake(value);
+    });
+
+    // Get initial value (i.e., 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/components/ComputeGraph/graph.ts

@@ -0,0 +1,52 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { HyperFormula } from 'hyperformula';
+
+import { Event } from '@dxos/async';
+import { type Space } from '@dxos/client/echo';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { FunctionContext } from './async-function';
+import { CustomPlugin, CustomPluginTranslations } from './custom';
+import { EdgeFunctionPlugin, EdgeFunctionPluginTranslations } from './edge-function';
+
+/**
+ * Create root graph for space.
+ */
+export const createComputeGraph = (space?: Space): ComputeGraph => {
+  // TODO(burdon): Configure.
+  HyperFormula.registerFunctionPlugin(CustomPlugin, CustomPluginTranslations);
+  HyperFormula.registerFunctionPlugin(EdgeFunctionPlugin, EdgeFunctionPluginTranslations);
+
+  const hf = HyperFormula.buildEmpty({ licenseKey: 'gpl-v3' });
+  return new ComputeGraph(hf, space);
+};
+
+/**
+ * Per-space compute and dependency graph.
+ */
+// TODO(burdon): Create instance for each space.
+export class ComputeGraph {
+  public readonly id = `graph-${PublicKey.random().truncate()}`;
+  public readonly update = new Event();
+
+  // The context is passed to all functions.
+  public readonly context = new FunctionContext(this.hf, this._space, () => {
+    this.refresh();
+  });
+
+  constructor(
+    public readonly hf: HyperFormula,
+    private readonly _space?: Space,
+  ) {
+    this.hf.updateConfig({ context: this.context });
+  }
+
+  refresh() {
+    log('refresh', { id: this.id });
+    this.update.emit();
+  }
+}

package/src/components/ComputeGraph/index.ts

@@ -0,0 +1,7 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export * from './custom';
+export * from './graph';
+export * from './graph-context';