@dxos/compute 0.7.5-main.499c70c

package/src/functions/async-function.ts

@@ -0,0 +1,179 @@
+//
+// 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;
+    });
+  }
+}

package/src/functions/edge-function.ts

@@ -0,0 +1,100 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { effect } from '@preact/signals-core';
+import { type InterpreterState } from 'hyperformula/typings/interpreter/InterpreterState';
+import { type ProcedureAst } from 'hyperformula/typings/parser';
+
+import { Filter, getMeta } from '@dxos/client/echo';
+import { FunctionType, getUserFunctionUrlInMetadata } from '@dxos/functions';
+import { log } from '@dxos/log';
+import { nonNullable } from '@dxos/util';
+
+import { CellError, ErrorType, FunctionArgumentType } from '#hyperformula';
+import { type AsyncFunction, AsyncFunctionPlugin } from './async-function';
+
+export const EDGE_FUNCTION_NAME = 'DX';
+
+const FUNCTION_TTL = 10_000;
+
+/**
+ * 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 AsyncFunctionPlugin {
+  dx(ast: ProcedureAst, state: InterpreterState) {
+    const handler =
+      (subscribe = false): AsyncFunction =>
+      async (binding: string, ...args: any) => {
+        const space = this.context.space;
+        if (!space) {
+          return new CellError(ErrorType.REF, 'Missing space');
+        }
+
+        const {
+          objects: [fn],
+        } = await space.db.query(Filter.schema(FunctionType, { binding })).run();
+        if (!fn) {
+          log.info('Function not found', { binding });
+          return new CellError(ErrorType.REF, 'Function not found');
+        }
+
+        if (subscribe) {
+          const unsubscribe = effect(() => {
+            log('function changed', { fn });
+            const _ = fn?.version;
+
+            // 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: FUNCTION_TTL });
+          });
+
+          this.context.createSubscription(ast.procedureName, unsubscribe);
+        }
+
+        const path = getUserFunctionUrlInMetadata(getMeta(fn));
+        const response = await fetch(`${this.context.remoteFunctionUrl}${path}`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ args: args.filter(nonNullable) }),
+        });
+        const result = await response.text();
+        log('function executed', { result });
+
+        return result;
+      };
+
+    return this.runAsyncFunction(ast, state, handler(true), { ttl: FUNCTION_TTL });
+  }
+}
+
+EdgeFunctionPlugin.implementedFunctions = {
+  [EDGE_FUNCTION_NAME]: {
+    method: 'dx',
+    parameters: [
+      // Binding
+      { argumentType: FunctionArgumentType.STRING },
+
+      // Remote function arguments (currently supporting up to 8).
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+      { argumentType: FunctionArgumentType.ANY, optionalArg: true },
+    ],
+    isVolatile: true,
+  },
+};
+
+export const EdgeFunctionPluginTranslations = {
+  enGB: {
+    [EDGE_FUNCTION_NAME]: 'Remote function',
+  },
+  enUS: {
+    [EDGE_FUNCTION_NAME]: 'Remote function',
+  },
+};