@finos/legend-data-cube 0.0.35 → 0.0.37

package/src/index.tsx

@@ -16,16 +16,27 @@
 
 export * from './stores/core/models/DataCubeQuery.js';
 export * from './stores/core/models/DataCubeSource.js';
+export { type DataCubeColumn } from './stores/core/models/DataCubeColumn.js';
 export * from './stores/core/models/DataCubeConfiguration.js';
+export * from './stores/core/models/AdhocQueryDataCubeSource.js';
 
 export * from './stores/core/DataCubeEngine.js';
 export * from './stores/core/DataCubeQueryEngine.js';
 export * from './stores/core/DataCubeLayoutManagerState.js';
 export * from './stores/core/DataCubeQueryBuilderUtils.js';
+
+export {
+  type DataCubeSetting,
+  DataCubeSettingGroup,
+  DataCubeSettingType,
+  type DataCubeSettingValues,
+} from './stores/core/DataCubeSetting.js';
 export { DataCubeState } from './stores/DataCubeState.js';
+export { useDataCube } from './components/DataCubeProvider.js';
 export * from './stores/DataCubeAPI.js';
 export * from './stores/DataCubeOptions.js';
-export { DataCubeSettingKey } from './stores/DataCubeSettings.js';
 
-export * from './components/core/DataCubeAlert.js';
 export * from './components/DataCube.js';
+export * from './components/core/DataCubeAlert.js';
+export * from './components/core/DataCubeFormUtils.js';
+export * from './components/core/DataCubeLayoutManager.js';

package/src/stores/DataCubeOptions.ts

@@ -14,23 +14,27 @@
  * limitations under the License.
  */
 
+import type {
+  DataCubeSetting,
+  DataCubeSettingValues,
+} from './core/DataCubeSetting.js';
 import type { DataCubeSource } from './core/models/DataCubeSource.js';
 import type { DataCubeState } from './DataCubeState.js';
 
 export type DataCubeOptions = {
-  enableDebugMode?: boolean | undefined;
-  gridClientRowBuffer?: number | undefined;
-  gridClientPurgeClosedRowNodes?: boolean | undefined;
-  gridClientSuppressLargeDatasetWarning?: boolean | undefined;
+  gridClientLicense?: string | undefined;
+
+  onInitialized?: ((dataCube: DataCubeState) => void) | undefined;
 
   onNameChanged?: ((name: string, source: DataCubeSource) => void) | undefined;
-  onSettingChanged?:
-    | ((
-        key: string,
-        value: string | number | boolean | object | undefined,
-      ) => void)
-    | undefined;
+
   innerHeaderComponent?:
     | ((dataCube: DataCubeState) => React.ReactNode)
     | undefined;
+
+  getSettingItems?: (() => DataCubeSetting[]) | undefined;
+  getSettingValues?: (() => DataCubeSettingValues | undefined) | undefined;
+  onSettingValuesChanged?:
+    | ((values: DataCubeSettingValues) => void)
+    | undefined;
 };

package/src/stores/DataCubeSettings.tsx

@@ -0,0 +1,421 @@
+/**
+ * Copyright (c) 2020-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { DataCubeState } from './DataCubeState.js';
+import {
+  DataCubeSettingGroup,
+  DataCubeSettingKey,
+  DataCubeSettingType,
+  type DataCubeSetting,
+  type DataCubeSettingValue,
+  type DataCubeSettingValues,
+} from './core/DataCubeSetting.js';
+import {
+  hashArray,
+  IllegalStateError,
+  isBoolean,
+  isNumber,
+  isString,
+  LogEvent,
+  UnsupportedOperationError,
+} from '@finos/legend-shared';
+import { DataCubeEvent } from '../__lib__/DataCubeEvent.js';
+import type { DataCubeOptions } from './DataCubeOptions.js';
+import {
+  action,
+  computed,
+  makeObservable,
+  observable,
+  runInAction,
+} from 'mobx';
+import type { DisplayState } from './core/DataCubeLayoutManagerState.js';
+import { DataCubeSettingsPanel } from '../components/core/DataCubeSettingsPanel.js';
+
+export class DataCubeSettings {
+  readonly dataCube: DataCubeState;
+  readonly display: DisplayState;
+  readonly configurations = new Map<string, DataCubeSetting>();
+  readonly defaultValues = new Map<string, DataCubeSettingValue>();
+  readonly defaultValuesHashCode!: string;
+  readonly values = new Map<string, DataCubeSettingValue>();
+  readonly currentValues = new Map<string, DataCubeSettingValue>();
+
+  getSettingValues?: (() => DataCubeSettingValues | undefined) | undefined;
+  onSettingValuesChanged?:
+    | ((values: DataCubeSettingValues) => void)
+    | undefined;
+  gridClientLicense?: string | undefined;
+
+  constructor(dataCube: DataCubeState, options?: DataCubeOptions | undefined) {
+    makeObservable(this, {
+      values: observable,
+      save: action,
+      valuesHashCode: computed,
+
+      currentValues: observable,
+      resetDefaultValues: action,
+      currentValuesHashCode: computed,
+    });
+
+    this.dataCube = dataCube;
+    this.getSettingValues = options?.getSettingValues;
+    this.onSettingValuesChanged = options?.onSettingValuesChanged;
+
+    this.display = this.dataCube.engine.layout.newDisplay(
+      'Settings',
+      () => <DataCubeSettingsPanel />,
+      {
+        x: -50,
+        y: 50,
+        width: 600,
+        height: 400,
+        minWidth: 300,
+        minHeight: 200,
+        center: false,
+      },
+    );
+
+    const CORE_SETTINGS: DataCubeSetting[] = [
+      {
+        key: DataCubeSettingKey.DEBUGGER__ENABLE_DEBUG_MODE,
+        title: `Debug Mode: Enabled`,
+        description: `Enables debug logging when running data queries, updating snapshots, etc.`,
+        group: DataCubeSettingGroup.DEBUG,
+        type: DataCubeSettingType.BOOLEAN,
+        defaultValue: false,
+      } satisfies DataCubeSetting<boolean>,
+      {
+        key: DataCubeSettingKey.GRID_CLIENT__SUPPRESS_LARGE_DATASET_WARNING,
+        title: `Large Dataset Warning: Disabled`,
+        description: `Suggests user to enable pagination when handling large datasets to improve performance.`,
+        group: DataCubeSettingGroup.GRID,
+        type: DataCubeSettingType.BOOLEAN,
+        defaultValue: false,
+      } satisfies DataCubeSetting<boolean>,
+      {
+        key: DataCubeSettingKey.GRID_CLIENT__ROW_BUFFER,
+        title: `Row Buffer`,
+        description: `Sets the number of rows the grid renders outside of the viewable area. e.g. if the buffer is 10 and your grid is showing 50 rows (as that's all that fits on your screen without scrolling), then the grid will actually render 70 in total (10 extra above and 10 extra below). Then when you scroll, the grid will already have 10 rows ready and waiting to show, no redraw is needed. A low small buffer will make initial draws of the grid faster; whereas a big one will reduce the redraw visible vertically scrolling.`,
+        group: DataCubeSettingGroup.GRID,
+        type: DataCubeSettingType.NUMERIC,
+        defaultValue: 50,
+        numericValueMin: 10,
+        numericValueStep: 10,
+        action: (newValue) =>
+          this.dataCube.runTaskForEachView((view) => {
+            view.grid.client.updateGridOptions({
+              rowBuffer: newValue,
+            });
+          }),
+      } satisfies DataCubeSetting<number>,
+      {
+        key: DataCubeSettingKey.GRID_CLIENT__PURGE_CLOSED_ROW_NODES,
+        title: `Refresh Group Node Data: Enabled`,
+        description: `Forces refresh data when group node is opened.`,
+        group: DataCubeSettingGroup.GRID,
+        type: DataCubeSettingType.BOOLEAN,
+        defaultValue: false,
+        action: (newValue) =>
+          this.dataCube.runTaskForEachView((view) => {
+            view.grid.client.updateGridOptions({
+              purgeClosedRowNodes: newValue,
+            });
+          }),
+      } satisfies DataCubeSetting<boolean>,
+      {
+        key: DataCubeSettingKey.GRID_CLIENT__ACTION__REFRESH_FAILED_DATA_FETCHES,
+        title: `Refresh Failed Data Fetch: Action`,
+        description: `Manually re-runs all failed data fetches in the grid.`,
+        group: DataCubeSettingGroup.GRID,
+        type: DataCubeSettingType.ACTION,
+        action: () => this.dataCube.refreshFailedDataFetches(),
+        defaultValue: undefined,
+      } satisfies DataCubeSetting,
+    ];
+
+    [...CORE_SETTINGS, ...(options?.getSettingItems?.() ?? [])].forEach(
+      (configuration) => {
+        this.configurations.set(configuration.key, configuration);
+        this.setValue(configuration.key, configuration.defaultValue, [
+          this.defaultValues,
+          this.values,
+          this.currentValues,
+        ]);
+      },
+    );
+
+    const settingValues = this.getSettingValues?.() ?? {};
+    Object.keys(settingValues).forEach((key) => {
+      const value = settingValues[key];
+      // for unknown settings (e.g. outdated settings, settings' keys changed, etc.), we ignore them
+      const configuration = this.configurations.get(key);
+      if (!configuration) {
+        return;
+      }
+      this.setValue(key, value, [this.values, this.currentValues]);
+    });
+
+    // NOTE: if we support explicity setting values from options, they should
+    // be processed here, as they should override the settings retrieved from
+    // cache.
+
+    this.defaultValuesHashCode = this.computeValuesHashCode(this.defaultValues);
+  }
+
+  private setValue(
+    key: string,
+    value: unknown,
+    valueIndexes: Map<string, unknown>[],
+  ) {
+    const configuration = this.configurations.get(key);
+    if (!configuration) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+        ),
+        `Can't set value for unregistered setting '${key}'`,
+      );
+      return false;
+    }
+    switch (configuration.type) {
+      case DataCubeSettingType.BOOLEAN: {
+        if (
+          !(
+            isBoolean(value) ||
+            (value === undefined && configuration.valueOptional)
+          )
+        ) {
+          this.dataCube.engine.logWarning(
+            LogEvent.create(
+              DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+            ),
+            `Can't set value for setting '${key}': boolean value expected`,
+          );
+          return false;
+        }
+        break;
+      }
+      case DataCubeSettingType.NUMERIC: {
+        if (
+          !(
+            isNumber(value) ||
+            (value === undefined && configuration.valueOptional)
+          )
+        ) {
+          this.dataCube.engine.logWarning(
+            LogEvent.create(
+              DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+            ),
+            `Can't set value for setting '${key}': numeric value expected`,
+          );
+          return false;
+        }
+        break;
+      }
+      case DataCubeSettingType.STRING: {
+        if (
+          !(
+            isString(value) ||
+            (value === undefined && configuration.valueOptional)
+          )
+        ) {
+          this.dataCube.engine.logWarning(
+            LogEvent.create(
+              DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+            ),
+            `Can't set value for setting '${key}': string value expected`,
+          );
+          return false;
+        }
+        break;
+      }
+      case DataCubeSettingType.ACTION: {
+        return false;
+      }
+      default:
+        throw new UnsupportedOperationError(
+          `Can't set value for unsupported setting type '${configuration.type}'`,
+        );
+    }
+    valueIndexes.forEach((valueIndex) => {
+      runInAction(() => valueIndex.set(key, value));
+    });
+    return true;
+  }
+
+  private getConfiguration(key: string) {
+    const configuration = this.configurations.get(key);
+    if (!configuration) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+        ),
+        `Can't retrieve value for unregistered setting '${key}'`,
+      );
+      throw new IllegalStateError(
+        `Can't retrieve value for unregistered setting '${key}'`,
+      );
+    }
+    return configuration;
+  }
+
+  getBooleanValue(key: string) {
+    const value = this.values.get(key);
+    const configuration = this.getConfiguration(key);
+    if (
+      configuration.type !== DataCubeSettingType.BOOLEAN ||
+      !isBoolean(value)
+    ) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__RETRIEVE_INCOMPATIBLE_VALUE,
+        ),
+        `Can't retrieve boolean value for setting '${key}'`,
+      );
+      throw new IllegalStateError(
+        `Can't retrieve boolean value for setting '${key}'`,
+      );
+    }
+    return value;
+  }
+
+  getNumericValue(key: string) {
+    const value = this.values.get(key);
+    const configuration = this.getConfiguration(key);
+    if (
+      configuration.type !== DataCubeSettingType.NUMERIC ||
+      !isNumber(value)
+    ) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__RETRIEVE_INCOMPATIBLE_VALUE,
+        ),
+        `Can't retrieve numeric value for setting '${key}'`,
+      );
+      throw new IllegalStateError(
+        `Can't retrieve numeric value for setting '${key}'`,
+      );
+    }
+    return value;
+  }
+
+  getStringValue(key: string) {
+    const value = this.values.get(key);
+    const configuration = this.getConfiguration(key);
+    if (configuration.type !== DataCubeSettingType.STRING || !isString(value)) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__RETRIEVE_INCOMPATIBLE_VALUE,
+        ),
+        `Can't retrieve string value for setting '${key}'`,
+      );
+      throw new IllegalStateError(
+        `Can't retrieve string value for setting '${key}'`,
+      );
+    }
+    return value;
+  }
+
+  updateValue(key: string, value: DataCubeSettingValue) {
+    const configuration = this.configurations.get(key);
+    if (!configuration) {
+      this.dataCube.engine.logWarning(
+        LogEvent.create(
+          DataCubeEvent.SETTINGS__FAILURE__FOUND_UNREGISTERED_SETTING,
+        ),
+        `Can't set value for unregistered setting '${key}'`,
+      );
+      return;
+    }
+
+    if (!this.setValue(key, value, [this.values, this.currentValues])) {
+      return;
+    }
+
+    // trigger hook
+    this.onSettingValuesChanged?.(this.getCurrentSettingValues());
+
+    // trigger action
+    configuration.action?.(value);
+  }
+
+  private computeValuesHashCode(values: Map<string, DataCubeSettingValue>) {
+    return hashArray(
+      Array.from(values.entries())
+        .toSorted((a, b) => a[0].localeCompare(b[0]))
+        .map(([key, value]) => `${key}:${value}`),
+    );
+  }
+
+  get valuesHashCode() {
+    return this.computeValuesHashCode(this.values);
+  }
+
+  get currentValuesHashCode() {
+    return this.computeValuesHashCode(this.currentValues);
+  }
+
+  resetDefaultValues() {
+    this.currentValues.clear();
+    this.defaultValues.forEach((value, key) =>
+      this.currentValues.set(key, value),
+    );
+  }
+
+  private getCurrentSettingValues(): DataCubeSettingValues {
+    const settingValues: DataCubeSettingValues = {};
+    this.values.forEach((value, key) => {
+      const configuration = this.configurations.get(key);
+      // skip if value is the same as default value
+      if (configuration && value !== configuration.defaultValue) {
+        settingValues[key] = value;
+      }
+    });
+    return settingValues;
+  }
+
+  save() {
+    const changedSettingKeys = new Set<string>();
+    this.values.forEach((value, key) => {
+      if (value !== this.currentValues.get(key)) {
+        changedSettingKeys.add(key);
+      }
+    });
+
+    // update values
+    this.values.clear();
+    this.currentValues.forEach((value, key) => this.values.set(key, value));
+
+    // trigger hook
+    this.onSettingValuesChanged?.(this.getCurrentSettingValues());
+
+    // trigger action
+    let requiresReload = false;
+    for (const key of changedSettingKeys) {
+      const configuration = this.configurations.get(key);
+      if (configuration?.requiresReload) {
+        requiresReload = true;
+      }
+      if (configuration?.action) {
+        configuration.action(this.values.get(key));
+      }
+    }
+
+    if (requiresReload) {
+      this.dataCube.reload();
+    }
+  }
+}

package/src/stores/DataCubeState.tsx

@@ -18,10 +18,10 @@ import { type DataCubeEngine } from './core/DataCubeEngine.js';
 import { DataCubeViewState } from './view/DataCubeViewState.js';
 import type { DisplayState } from './core/DataCubeLayoutManagerState.js';
 import { DocumentationPanel } from '../components/core/DataCubeDocumentationPanel.js';
-import { DataCubeSettingsPanel } from '../components/core/DataCubeSettingsPanel.js';
 import {
   ActionState,
   assertErrorThrown,
+  uuid,
   type DocumentationEntry,
 } from '@finos/legend-shared';
 import {
@@ -33,24 +33,20 @@ import { action, makeObservable, observable } from 'mobx';
 import { DataCubeSettings } from './DataCubeSettings.js';
 import type { DataCubeAPI } from './DataCubeAPI.js';
 import type { DataCubeOptions } from './DataCubeOptions.js';
+import type { DataCubeQuery } from './core/models/DataCubeQuery.js';
 
 export class DataCubeState implements DataCubeAPI {
+  uuid = uuid();
+
   readonly engine: DataCubeEngine;
+
+  readonly query: DataCubeQuery;
   readonly settings!: DataCubeSettings;
-  readonly initState = ActionState.create();
-  readonly settingsDisplay: DisplayState;
   readonly documentationDisplay: DisplayState;
-  // NOTE: when we support multiview, there can be multiple view states to support
-  // the first one in that list will be taken as the main view state
-  readonly view: DataCubeViewState;
+  readonly initializeState = ActionState.create();
 
+  onInitialized?: ((dataCube: DataCubeState) => void) | undefined;
   onNameChanged?: ((name: string, source: DataCubeSource) => void) | undefined;
-  onSettingChanged?:
-    | ((
-        key: string,
-        value: string | number | boolean | object | undefined,
-      ) => void)
-    | undefined;
   innerHeaderComponent?:
     | ((dataCube: DataCubeState) => React.ReactNode)
     | undefined;
@@ -58,32 +54,31 @@ export class DataCubeState implements DataCubeAPI {
   currentDocumentationEntry?: DocumentationEntry | undefined;
   currentActionAlert?: ActionAlert | undefined;
 
-  constructor(engine: DataCubeEngine, options?: DataCubeOptions | undefined) {
+  // NOTE: when we support multiview, there can be multiple view states to support
+  // the first one in that list will be taken as the main view state
+  view: DataCubeViewState;
+
+  constructor(
+    query: DataCubeQuery,
+    engine: DataCubeEngine,
+    options?: DataCubeOptions | undefined,
+  ) {
     makeObservable(this, {
       currentDocumentationEntry: observable,
       openDocumentationEntry: action,
 
       currentActionAlert: observable,
       alertAction: action,
+
+      uuid: observable,
+      reload: action,
     });
 
+    this.query = query;
     this.engine = engine;
-    this.settings = new DataCubeSettings(this);
+    this.settings = new DataCubeSettings(this, options);
     this.view = new DataCubeViewState(this);
 
-    this.settingsDisplay = this.engine.layout.newDisplay(
-      'Settings',
-      () => <DataCubeSettingsPanel />,
-      {
-        x: -50,
-        y: 50,
-        width: 600,
-        height: 400,
-        minWidth: 300,
-        minHeight: 200,
-        center: false,
-      },
-    );
     this.documentationDisplay = this.engine.layout.newDisplay(
       'Documentation',
       () => <DocumentationPanel />,
@@ -98,26 +93,14 @@ export class DataCubeState implements DataCubeAPI {
       },
     );
 
+    this.onInitialized = options?.onInitialized;
     this.onNameChanged = options?.onNameChanged;
-    this.onSettingChanged = options?.onSettingChanged;
     this.innerHeaderComponent = options?.innerHeaderComponent;
+  }
 
-    this.settings.enableDebugMode =
-      options?.enableDebugMode !== undefined
-        ? options.enableDebugMode
-        : this.settings.enableDebugMode;
-    this.settings.gridClientRowBuffer =
-      options?.gridClientRowBuffer !== undefined
-        ? options.gridClientRowBuffer
-        : this.settings.gridClientRowBuffer;
-    this.settings.gridClientPurgeClosedRowNodes =
-      options?.gridClientPurgeClosedRowNodes !== undefined
-        ? options.gridClientPurgeClosedRowNodes
-        : this.settings.gridClientPurgeClosedRowNodes;
-    this.settings.gridClientSuppressLargeDatasetWarning =
-      options?.gridClientSuppressLargeDatasetWarning !== undefined
-        ? options.gridClientSuppressLargeDatasetWarning
-        : this.settings.gridClientSuppressLargeDatasetWarning;
+  reload() {
+    this.view = new DataCubeViewState(this);
+    this.uuid = uuid();
   }
 
   getSettings() {
@@ -145,16 +128,20 @@ export class DataCubeState implements DataCubeAPI {
   }
 
   async initialize() {
-    if (!this.initState.isInInitialState) {
-      this.engine.logDebug('REPL store is re-initialized');
+    if (!this.initializeState.isInInitialState) {
+      this.engine.logDebug('DataCube state is re-initialized');
       return;
     }
-    this.initState.inProgress();
+    this.initializeState.inProgress();
 
     try {
-      await this.engine.initialize();
-      this.initState.pass();
-    } catch (error: unknown) {
+      await this.engine.initialize({
+        gridClientLicense: this.settings.gridClientLicense,
+      });
+
+      this.onInitialized?.(this);
+      this.initializeState.pass();
+    } catch (error) {
       assertErrorThrown(error);
       this.alertAction({
         message: `Initialization Failure: ${error.message}`,
@@ -162,7 +149,7 @@ export class DataCubeState implements DataCubeAPI {
         type: AlertType.ERROR,
         actions: [],
       });
-      this.initState.fail();
+      this.initializeState.fail();
     }
   }
 }