@dxos/plugin-sheet 0.7.4 → 0.7.5-main.937ce75

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

@@ -1,90 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import type { FunctionPluginDefinition } from 'hyperformula';
-import type { ConfigParams } from 'hyperformula/typings/ConfigParams';
-import type { FunctionTranslationsPackage } from 'hyperformula/typings/interpreter';
-import defaultsDeep from 'lodash.defaultsdeep';
-
-import { type SpaceId, type Space } from '@dxos/client/echo';
-import { Resource } from '@dxos/context';
-import { invariant } from '@dxos/invariant';
-import { log } from '@dxos/log';
-
-import { HyperFormula } from '#hyperformula';
-import { ComputeGraph } from './compute-graph';
-import { EdgeFunctionPlugin, EdgeFunctionPluginTranslations, type FunctionContextOptions } from './functions';
-
-export type ComputeGraphPlugin = {
-  plugin: FunctionPluginDefinition;
-  translations: FunctionTranslationsPackage;
-};
-
-export type ComputeGraphOptions = {
-  plugins?: ComputeGraphPlugin[];
-} & Partial<FunctionContextOptions> &
-  Partial<ConfigParams>;
-
-export const defaultOptions: ComputeGraphOptions = {
-  licenseKey: 'gpl-v3',
-};
-
-export const defaultPlugins: ComputeGraphPlugin[] = [
-  {
-    plugin: EdgeFunctionPlugin,
-    translations: EdgeFunctionPluginTranslations,
-  },
-];
-
-/**
- * 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.
- * NOTE: The package.json file defines the packaged #hyperformula module.
- */
-// 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);
-  }
-
-  getOrCreateGraph(space: Space): ComputeGraph {
-    let graph = this._graphs.get(space.id);
-    if (!graph) {
-      log('create graph', { space: space.id });
-      graph = this.createGraph(space);
-    }
-
-    return graph;
-  }
-
-  createGraph(space: Space): 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);
-    return graph;
-  }
-
-  protected override async _close() {
-    for (const graph of this._graphs.values()) {
-      await graph.close();
-    }
-    this._graphs.clear();
-  }
-}

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

@@ -1,87 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type CellValue } from 'hyperformula';
-import { afterEach, beforeEach, describe, expect, test } from 'vitest';
-
-import { Trigger } from '@dxos/async';
-import { create, fullyQualifiedId } from '@dxos/client/echo';
-import { FunctionType } from '@dxos/plugin-script/types';
-
-import { DetailedCellError } from '#hyperformula';
-import { TestBuilder } from './testing';
-
-describe('ComputeGraph', () => {
-  let testBuilder: TestBuilder;
-  beforeEach(async () => {
-    testBuilder = new TestBuilder({ types: [FunctionType] });
-    await testBuilder.open();
-  });
-  afterEach(async () => {
-    await testBuilder.close();
-  });
-
-  test('map functions', async () => {
-    const space = await testBuilder.client.spaces.create();
-    const graph = testBuilder.registry.createGraph(space);
-    await graph.open();
-
-    // Create script.
-    const trigger = new Trigger();
-    graph.update.once(() => trigger.wake());
-    const functionObject = space.db.add(create(FunctionType, { name: 'test', version: '0.0.1', binding: 'TEST' }));
-    await trigger.wait();
-    const functions = graph.getFunctions({ echo: true });
-    expect(functions).to.toHaveLength(1);
-
-    const id = graph.mapFunctionBindingToId('TEST()');
-    expect(id).to.eq(`${fullyQualifiedId(functionObject)}()`);
-  });
-
-  test('cross-node references', async () => {
-    const space = await testBuilder.client.spaces.create();
-    const graph = testBuilder.registry.createGraph(space);
-
-    // Create nodes.
-    const node1 = await graph.getOrCreateNode('node-1').open();
-    const node2 = await graph.getOrCreateNode('node-2').open();
-    expect(graph.hf.getSheetNames()).to.toHaveLength(2);
-
-    {
-      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);
-    }
-  });
-
-  // TODO(burdon): Dynamically load node/model based on dependencies.
-  //  - Create dependency then close model.
-  test('dynamic loading', async () => {
-    const space = await testBuilder.client.spaces.create();
-    const graph = testBuilder.registry.createGraph(space);
-
-    const node1 = await graph.getOrCreateNode('node-1').open();
-    node1.graph.hf.setCellContents({ sheet: node1.sheetId, row: 0, col: 0 }, "='node-2'!A1");
-    const value1 = node1.graph.hf.getCellValue({ sheet: node1.sheetId, col: 0, row: 0 });
-    expect(value1).to.be.instanceof(DetailedCellError);
-    expect((value1 as DetailedCellError).type).to.eq('REF');
-  });
-});

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

@@ -1,260 +0,0 @@
-//
-// Copyright 2024 DXOS.org
-//
-
-import { type Listeners } from 'hyperformula/typings/Emitter';
-
-import { Event } from '@dxos/async';
-import { type Space, Filter, fullyQualifiedId } from '@dxos/client/echo';
-import { FQ_ID_LENGTH } 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, type HyperFormula } from '#hyperformula';
-import { ComputeNode } from './compute-node';
-import {
-  defaultFunctions,
-  FunctionContext,
-  type FunctionContextOptions,
-  type FunctionDefinition,
-  EDGE_FUNCTION_NAME,
-} from './functions';
-
-// TODO(burdon): Factor out compute-graph.
-
-const UNKNOWN_BINDING = '__UNKNOWN__';
-
-// TODO(burdon): Factory.
-// export type ComputeNodeGenerator = <T>(obj: T) => ComputeNode;
-
-type ObjectRef = { type: string; id: string };
-
-/**
- * Marker for sheets that are managed by an ECHO object.
- * Sheet ID: `dxos.org/type/SheetType@1234`
- */
-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' | 'valuesUpdated';
-
-/**
- * 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.
- */
-export class ComputeGraph extends Resource {
-  public readonly id = `graph-${PublicKey.random().truncate()}`;
-
-  // Map of nodes indexed by sheet number.
-  private readonly _nodes = new Map<number, ComputeNode>();
-
-  // Cached function objects.
-  private _remoteFunctions: FunctionType[] = [];
-
-  public readonly update = new Event<{ type: ComputeGraphEvent }>();
-
-  // The context is passed to all functions.
-  public readonly context: FunctionContext;
-
-  constructor(
-    private readonly _hf: HyperFormula,
-    private readonly _space?: Space,
-    private readonly _options?: Partial<FunctionContextOptions>,
-  ) {
-    super();
-
-    const contextOptions = {
-      ...this._options,
-      onUpdate: (update) => {
-        this._options?.onUpdate?.(update);
-        this.update.emit({ type: 'valuesUpdated' });
-      },
-    } satisfies Partial<FunctionContextOptions>;
-    this.context = new FunctionContext(this._hf, this._space, contextOptions);
-    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));
-  }
-
-  get hf() {
-    return this._hf;
-  }
-
-  getFunctions(
-    { standard, echo }: { standard?: boolean; echo?: boolean } = { standard: true, echo: true },
-  ): FunctionDefinition[] {
-    return [
-      ...(standard
-        ? this._hf
-            .getRegisteredFunctionNames()
-            .map((name) => defaultFunctions.find((fn) => fn.name === name) ?? { name })
-        : []),
-      ...(echo ? this._remoteFunctions.map((fn) => ({ name: fn.binding! })) : []),
-    ];
-  }
-
-  /**
-   * Get or create cell representing a sheet.
-   */
-  // TODO(burdon): Async (open node).
-  //  The graph should be an extensible factory that plugins extend with model constructors.
-  //  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 {
-    invariant(name.length);
-    if (!this._hf.doesSheetExist(name)) {
-      log('created node', { space: this._space?.id, sheet: name });
-      this._hf.addSheet(name);
-    }
-
-    const sheetId = this._hf.getSheetId(name);
-    invariant(sheetId !== undefined);
-
-    const node = new ComputeNode(this, sheetId);
-    this._nodes.set(sheetId, node);
-    return node;
-  }
-
-  /**
-   * Map bound value to custom function invocation.
-   * E.g., "HELLO(...args)" => "DX("HELLO", ...args)".
-   */
-  mapFormulaToNative(formula: string): string {
-    return (
-      formula
-        //
-        // 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): Cache map.
-            const objects = this._hf
-              .getSheetNames()
-              .map((name) => {
-                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) {
-                const type = getTypename(obj)!;
-                // NOTE: Names must be single quoted.
-                return `'${createSheetName({ type, id: obj.id })}'!`;
-              }
-            }
-          }
-
-          return `${name}!`;
-        })
-
-        //
-        // Map remote function references (i.e., to remote DX function invocation).
-        //
-        .replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
-          const fn = this._remoteFunctions.find((fn) => fn.binding === binding);
-          if (!fn) {
-            return match;
-          }
-
-          if (args.trim() === '') {
-            return `${EDGE_FUNCTION_NAME}("${binding}")`;
-          } else {
-            return `${EDGE_FUNCTION_NAME}("${binding}", ${args})`;
-          }
-        })
-    );
-  }
-
-  /**
-   * Map from binding to fully qualified ECHO ID (to store).
-   * E.g., HELLO() => spaceId:objectId()
-   */
-  mapFunctionBindingToId(formula: string) {
-    return formula.replace(/(\w+)\((.*)\)/g, (match, binding, args) => {
-      if (binding === EDGE_FUNCTION_NAME || defaultFunctions.find((fn) => fn.name === binding)) {
-        return match;
-      }
-
-      const fn = this._remoteFunctions.find((fn) => fn.binding === binding);
-      if (fn) {
-        const id = fullyQualifiedId(fn);
-        return `${id}(${args})`;
-      } else {
-        return match;
-      }
-    });
-  }
-
-  /**
-   * Map from fully qualified ECHO ID to binding (from store).
-   * E.g., spaceId:objectId() => HELLO()
-   */
-  mapFunctionBindingFromId(formula: string) {
-    const binding = formula.replace(/(\w+):([a-zA-Z0-9]+)\((.*)\)/g, (match, spaceId, objectId, args) => {
-      const id = `${spaceId}:${objectId}`;
-      if (id.length !== FQ_ID_LENGTH) {
-        return match;
-      }
-
-      const fn = this._remoteFunctions.find((fn) => fullyQualifiedId(fn) === id);
-      if (fn?.binding) {
-        return `${fn.binding}(${args})`;
-      } else {
-        return UNKNOWN_BINDING;
-      }
-    });
-
-    if (binding.startsWith(`=${UNKNOWN_BINDING}`)) {
-      return undefined;
-    } else {
-      return binding;
-    }
-  }
-
-  protected override async _open() {
-    if (this._space) {
-      // Subscribe to remote function definitions.
-      const query = this._space.db.query(Filter.schema(FunctionType));
-      const unsubscribe = query.subscribe(({ objects }) => {
-        this._remoteFunctions = objects.filter(({ binding }) => binding);
-        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/compute-graph/compute-node.ts

@@ -1,62 +0,0 @@
-//
-// 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';
-
-import { DetailedCellError } from '#hyperformula';
-import { type ComputeGraph } from './compute-graph';
-import { type CellAddress, isFormula } 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 {
-  public readonly update = new Event<ComputeNodeEvent>();
-
-  constructor(
-    private readonly _graph: ComputeGraph,
-    public readonly sheetId: number,
-  ) {
-    super();
-  }
-
-  get graph() {
-    return this._graph;
-  }
-
-  clear() {
-    this._graph.hf.clearSheet(this.sheetId);
-  }
-
-  getValue(cell: CellAddress): CellScalarValue {
-    const value = this._graph.hf.getCellValue({ sheet: this.sheetId, row: cell.row, col: cell.col });
-    if (value instanceof DetailedCellError) {
-      return null;
-    }
-
-    return value;
-  }
-
-  setValue(cell: CellAddress, value: CellScalarValue) {
-    const mappedValue = isFormula(value) ? this._graph.mapFormulaToNative(value) : value;
-    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/compute-graph/functions/async-function.ts

@@ -1,179 +0,0 @@
-//
-// 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';
-import defaultsDeep from 'lodash.defaultsdeep';
-
-import { debounce, type UnsubscribeCallback } from '@dxos/async';
-import { type Space } from '@dxos/client/echo';
-import { log } from '@dxos/log';
-
-import { CellError, ErrorType, EmptyValue, FunctionPlugin, type HyperFormula } from '#hyperformula';
-
-// 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
-
-export type AsyncFunction = (...args: any) => Promise<InterpreterValue>;
-
-export type FunctionUpdateEvent = {
-  name: string;
-  cell: SimpleCellAddress;
-};
-
-export type FunctionOptions = {
-  ttl?: number;
-};
-
-export type FunctionContextOptions = {
-  defaultTtl: number;
-  debounceDelay: number;
-  remoteFunctionUrl: string;
-  onUpdate?: (update: FunctionUpdateEvent) => void;
-};
-
-export const defaultFunctionContextOptions: FunctionContextOptions = {
-  defaultTtl: 5_000,
-  debounceDelay: 200,
-  remoteFunctionUrl: 'https://edge.dxos.workers.dev/functions', // TODO(burdon): Config.
-};
-
-/**
- * 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 });
-  }
-
-  // TODO(wittjosiah): Persist cached values.
-  // Cached values for cell.
-  private readonly _cache = new Map<string, { value: InterpreterValue; ts: number }>();
-
-  // Active requests.
-  private readonly _pending = new Map<string, number>();
-
-  // Query subscriptions.
-  private readonly _subscriptions = new Map<string, UnsubscribeCallback>();
-
-  // Invocation count.
-  private _invocations: Record<string, number> = {};
-
-  private readonly _options: FunctionContextOptions;
-
-  // Debounced update handler.
-  private readonly _onUpdate: (update: FunctionUpdateEvent) => void;
-
-  constructor(
-    private readonly _hf: HyperFormula,
-    private readonly _space: Space | undefined,
-    _options?: Partial<FunctionContextOptions>,
-  ) {
-    this._options = defaultsDeep(_options ?? {}, defaultFunctionContextOptions);
-    this._onUpdate = debounce((update) => {
-      log('update', update);
-      // TODO(burdon): Better way to trigger recalculation? (NOTE: rebuildAndRecalculate resets the undo history.)
-      this._hf.resumeEvaluation();
-      this._options.onUpdate?.(update);
-    }, this._options.debounceDelay);
-  }
-
-  get space() {
-    return this._space;
-  }
-
-  get remoteFunctionUrl() {
-    return this._options.remoteFunctionUrl;
-  }
-
-  get info() {
-    return { cache: this._cache.size, invocations: this._invocations };
-  }
-
-  flush() {
-    this._cache.clear();
-    this._invocations = {};
-    this._subscriptions.forEach((unsubscribe) => unsubscribe());
-    this._subscriptions.clear();
-  }
-
-  createSubscription(name: string, unsubscribe: UnsubscribeCallback) {
-    this._subscriptions.get(name)?.();
-    this._subscriptions.set(name, unsubscribe);
-  }
-
-  /**
-   * 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({ name, cell });
-        } 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 AsyncFunctionPlugin extends FunctionPlugin {
-  get context() {
-    return this.config.context as FunctionContext;
-  }
-
-  /**
-   * 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) => {
-      return this.context.invokeFunction(procedureName, state, args, cb, options) ?? EmptyValue;
-    });
-  }
-}