Merge pull request #51 from bcdev/forman-43-derived_host_state

Introduced derived host state

Author: forman

chartlets.js/CHANGES.md

@@ -1,4 +1,11 @@
-## Version 0.0.23 (in development)
+## Version 0.0.24 (from 2024/11/23)
+
+* Exporting required `HostStore` type.
+
+## Version 0.0.23 (from 2024/11/23)
+
+* Introduced new interface `HostState` that applications may implement
+  to provide computed properties, i.e., a derived state. (#43)
 
 * Replacing entire components if a related component `StateChange` 
   has an empty `property`. (#38)

chartlets.js/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "chartlets",
-  "version": "0.0.22",
+  "version": "0.0.24",
   "description": "An experimental library for integrating interactive charts into existing JavaScript applications.",
   "type": "module",
   "files": [

chartlets.js/package.json

@@ -7,9 +7,18 @@ import ControlBar from "@/demo/components/ControlBar";
 import PanelsControl from "./components/PanelsControl";
 import PanelsRow from "./components/PanelsRow";
 import { appStore } from "@/demo/store";
+import { getValue, setValue } from "@/lib/utils/objPath";
 
 initializeContributions({
-  hostStore: appStore,
+  hostStore: {
+    // Let Chartlets listen to changes in application state.
+    subscribe: (listener: () => void) => appStore.subscribe(listener),
+    // Compute a property value and return it. We simply use getValue() here.
+    get: (property: string): unknown => getValue(appStore.getState(), property),
+    // Set a property value in the application state.
+    set: (property: string, value: unknown) =>
+      void appStore.setState(setValue(appStore.getState(), property, value)),
+  },
   logging: { enabled: true },
 });
 

chartlets.js/src/demo/App.tsx

@@ -1,18 +1,16 @@
 import { store } from "@/lib/store";
-import type { FrameworkOptions } from "@/lib/types/state/store";
+import type { FrameworkOptions } from "@/lib/types/state/options";
 import { configureLogging } from "@/lib/actions/helpers/configureLogging";
 import { handleHostStoreChange } from "./handleHostStoreChange";
 
-export function configureFramework<S extends object = object>(
-  options: FrameworkOptions<S>,
-) {
+export function configureFramework(options: FrameworkOptions) {
   if (options.logging) {
     configureLogging(options.logging);
   }
   if (options.hostStore) {
     options.hostStore.subscribe(handleHostStoreChange);
   }
   store.setState({
-    configuration: { ...options } as FrameworkOptions<object>,
+    configuration: { ...options } as FrameworkOptions,
   });
 }

chartlets.js/src/lib/actions/configureFramework.ts

@@ -36,7 +36,9 @@ export function handleComponentChange(
     contribIndex,
     changeEvent,
   );
-  invokeCallbacks(callbackRequests);
+  if (callbackRequests && callbackRequests.length > 0) {
+    invokeCallbacks(callbackRequests);
+  }
 }
 
 /**
@@ -53,8 +55,7 @@ function getCallbackRequests(
   changeEvent: ComponentChangeEvent,
 ): CallbackRequest[] {
   const { configuration, contributionsRecord } = store.getState();
-  const { hostStore, getDerivedHostState } = configuration;
-  const hostState = hostStore?.getState();
+  const { hostStore } = configuration;
   const contributions = contributionsRecord[contribPoint];
   const contribution = contributions[contribIndex];
   const callbackRequests: CallbackRequest[] = [];
@@ -75,12 +76,7 @@ function getCallbackRequests(
           contribIndex,
           callbackIndex,
           inputIndex,
-          inputValues: getInputValues(
-            inputs,
-            contribution,
-            hostState,
-            getDerivedHostState,
-          ),
+          inputValues: getInputValues(inputs, contribution, hostStore),
         });
       }
     }

chartlets.js/src/lib/actions/handleComponentChange.ts

@@ -7,73 +7,65 @@ import type {
 } from "@/lib/types/model/callback";
 import type { Input } from "@/lib/types/model/channel";
 import { getInputValues } from "@/lib/actions/helpers/getInputValues";
-import {
-  getValue,
-  type ObjPath,
-  normalizeObjPath,
-  formatObjPath,
-} from "@/lib/utils/objPath";
+import { formatObjPath } from "@/lib/utils/objPath";
 import { invokeCallbacks } from "@/lib/actions/helpers/invokeCallbacks";
 import type { ContributionState } from "@/lib/types/state/contribution";
-import type { GetDerivedState } from "@/lib/types/state/store";
+import type { HostStore } from "@/lib/types/state/options";
 
 /**
  * A reference to a property of an input of a callback of a contribution.
  */
 export interface PropertyRef extends ContribRef, CallbackRef, InputRef {
-  /** The property name as path. */
-  propertyPath: ObjPath;
+  /** The property. */
+  property: string;
 }
 
-export function handleHostStoreChange<S extends object = object>(
-  currState: S,
-  prevState: S,
-) {
-  if (store.getState().extensions.length === 0) {
-    // Exit immediately if there are no extensions (yet)
+export function handleHostStoreChange() {
+  const { extensions, configuration, contributionsRecord } = store.getState();
+  const { hostStore } = configuration;
+  if (!hostStore || extensions.length === 0) {
+    // Exit if no host store configured or
+    // there are no extensions (yet)
+    return;
+  }
+  const propertyRefs = getHostStorePropertyRefs();
+  if (!propertyRefs || propertyRefs.length === 0) {
+    // Exit if there are is nothing to be changed
     return;
   }
-  const { configuration, contributionsRecord } = store.getState();
-  const { getDerivedHostState } = configuration;
   const callbackRequests = getCallbackRequests(
+    propertyRefs,
     contributionsRecord,
-    currState,
-    prevState,
-    getDerivedHostState,
+    hostStore,
   );
-  invokeCallbacks(callbackRequests);
+  if (callbackRequests && callbackRequests.length > 0) {
+    invokeCallbacks(callbackRequests);
+  }
 }
 
-function getCallbackRequests<S extends object = object>(
+function getCallbackRequests(
+  propertyRefs: PropertyRef[],
   contributionsRecord: Record<string, ContributionState[]>,
-  hostState: S,
-  prevHostState: S,
-  getDerivedHostState: GetDerivedState<S> | undefined,
+  hostStore: HostStore,
 ): CallbackRequest[] {
-  return getHostStorePropertyRefs()
-    .filter((propertyRef) =>
-      hasPropertyChanged(
-        propertyRef.propertyPath,
-        hostState,
-        prevHostState,
-        getDerivedHostState,
-      ),
-    )
-    .map((propertyRef) => {
-      const contributions = contributionsRecord[propertyRef.contribPoint];
-      const contribution = contributions[propertyRef.contribIndex];
-      const callback = contribution.callbacks![propertyRef.callbackIndex];
-      const inputValues = getInputValues(
-        callback.inputs!,
-        contribution,
-        hostState,
-        getDerivedHostState as GetDerivedState,
-      );
-      return { ...propertyRef, inputValues };
-    });
+  return propertyRefs.map((propertyRef) => {
+    const contributions = contributionsRecord[propertyRef.contribPoint];
+    const contribution = contributions[propertyRef.contribIndex];
+    const callback = contribution.callbacks![propertyRef.callbackIndex];
+    const inputValues = getInputValues(
+      callback.inputs!,
+      contribution,
+      hostStore,
+    );
+    return { ...propertyRef, inputValues };
+  });
 }
 
-// const getHostStorePropertyRefs = memoizeOne(_getHostStorePropertyRefs);
+// TODO: use a memoized selector to get hostStorePropertyRefs
+// Note that this will only be effective and once we split the
+// static contribution infos and dynamic contribution states.
+// The hostStorePropertyRefs only depend on the static
+// contribution infos.
 
 /**
  * Get the static list of host state property references for all contributions.
@@ -87,13 +79,13 @@ function getHostStorePropertyRefs(): PropertyRef[] {
       (contribution.callbacks || []).forEach(
         (callback, callbackIndex) =>
           (callback.inputs || []).forEach((input, inputIndex) => {
-            if (!input.noTrigger && input.link === "app") {
+            if (!input.noTrigger && input.link === "app" && input.property) {
               propertyRefs.push({
                 contribPoint,
                 contribIndex,
                 callbackIndex,
                 inputIndex,
-                propertyPath: normalizeObjPath(input.property!),
+                property: formatObjPath(input.property),
               });
             }
           }),
@@ -103,25 +95,3 @@ function getHostStorePropertyRefs(): PropertyRef[] {
   });
   return propertyRefs;
 }
-
-function hasPropertyChanged<S extends object = object>(
-  propertyPath: ObjPath,
-  currState: S,
-  prevState: S,
-  getDerivedHostState: GetDerivedState<S> | undefined,
-): boolean {
-  const currValue = getValue(currState, propertyPath);
-  const prevValue = getValue(prevState, propertyPath);
-  if (
-    currValue === undefined &&
-    prevValue === undefined &&
-    getDerivedHostState !== undefined
-  ) {
-    const propertyName = formatObjPath(propertyPath);
-    return !Object.is(
-      getDerivedHostState(currState, propertyName),
-      getDerivedHostState(prevState, propertyName),
-    );
-  }
-  return !Object.is(currValue, prevValue);
-}

chartlets.js/src/lib/actions/handleHostStoreChange.ts

@@ -12,12 +12,21 @@ import {
 import type { ContribPoint } from "@/lib/types/model/extension";
 import type { ContributionState } from "@/lib";
 import { updateArray } from "@/lib/utils/updateArray";
-import { getValue, normalizeObjPath, setValue } from "@/lib/utils/objPath";
+import {
+  formatObjPath,
+  getValue,
+  normalizeObjPath,
+  setValue,
+} from "@/lib/utils/objPath";
+import {
+  isMutableHostStore,
+  type MutableHostStore,
+} from "@/lib/types/state/options";
 
 export function applyStateChangeRequests(
   stateChangeRequests: StateChangeRequest[],
 ) {
-  const { contributionsRecord } = store.getState();
+  const { configuration, contributionsRecord } = store.getState();
   const contributionsRecordNew = applyContributionChangeRequests(
     contributionsRecord,
     stateChangeRequests,
@@ -27,7 +36,10 @@ export function applyStateChangeRequests(
       contributionsRecord: contributionsRecordNew,
     });
   }
-  applyHostStateChanges(stateChangeRequests);
+  const { hostStore } = configuration;
+  if (isMutableHostStore(hostStore)) {
+    applyHostStateChanges(stateChangeRequests, hostStore);
+  }
 }
 
 // we export for testing only
@@ -130,24 +142,17 @@ export function applyComponentStateChange(
   return component;
 }
 
-function applyHostStateChanges(stateChangeRequests: StateChangeRequest[]) {
-  const { configuration } = store.getState();
-  const { hostStore } = configuration;
-  if (hostStore) {
-    const hostStateOld = hostStore.getState();
-    let hostState: object | undefined = hostStateOld;
-    stateChangeRequests.forEach((stateChangeRequest) => {
-      hostState = applyStateChanges(
-        hostState,
-        stateChangeRequest.stateChanges.filter(
-          (stateChange) => stateChange.link === "app",
-        ),
-      );
+function applyHostStateChanges(
+  stateChangeRequests: StateChangeRequest[],
+  hostStore: MutableHostStore,
+) {
+  stateChangeRequests.forEach((stateChangeRequest) => {
+    stateChangeRequest.stateChanges.forEach((stateChange) => {
+      if (stateChange.link === "app") {
+        hostStore.set(formatObjPath(stateChange.property), stateChange.value);
+      }
     });
-    if (hostState !== hostStateOld) {
-      hostStore.setState(hostState);
-    }
-  }
+  });
 }
 
 // we export for testing only

chartlets.js/src/lib/actions/helpers/applyStateChangeRequests.ts

@@ -115,22 +115,4 @@ describe("Test that getInputValueFromState()", () => {
       getInputValueFromState({ link: "container", property: "x.y.2" }, state),
     ).toEqual(6);
   });
-
-  it("works with derived state", () => {
-    const state = { x: { y: [4, 5, 6] } };
-    const getDerivedState = (
-      _state: object,
-      name: string,
-    ): number | undefined =>
-      name === "x.ySum"
-        ? state.x.y[0] + state.x.y[1] + state.x.y[2]
-        : undefined;
-    expect(
-      getInputValueFromState(
-        { link: "container", property: "x.ySum" },
-        state,
-        getDerivedState,
-      ),
-    ).toEqual(4 + 5 + 6);
-  });
 });