@buildcanada/charts 0.1.0

package/src/utils/persistable/Persistable.ts

@@ -0,0 +1,82 @@
+import { toJS } from "mobx"
+import * as _ from "lodash-es"
+
+// Any classes that the user can edit, save, and then rehydrate should implement this interface
+export interface Persistable {
+    toObject(): any // This should dehydrate any runtime instances to a plain object ready to be JSON stringified
+    updateFromObject(obj: any): any // This should parse an incoming object, extend the current instance, and create new instances for any non native class types
+}
+
+// Todo: see if there's a better way to do this with Mobx
+export function objectWithPersistablesToObject<T>(
+    objWithPersistables: T,
+    keysToSerialize: string[] = []
+): T {
+    const obj = toJS(objWithPersistables) as any
+    const keysSet = new Set(keysToSerialize)
+    Object.keys(obj).forEach((key) => {
+        const val = (objWithPersistables as any)[key]
+        const valIsPersistable = val && val.toObject
+
+        // Delete any keys we don't want to serialize, if a keep list is provided
+        if (keysToSerialize.length && !keysSet.has(key)) {
+            delete obj[key]
+            return
+        }
+
+        // Val is persistable, call toObject
+        if (valIsPersistable) obj[key] = val.toObject()
+        else if (Array.isArray(val))
+            // Scan array for persistables and seriazile.
+            obj[key] = val.map((item) =>
+                item?.toObject ? item.toObject() : item
+            )
+        else obj[key] = val
+    })
+    return obj as T
+}
+
+// Basically does an Object.assign, except if the target is a Persistable, will call updateFromObject on
+// that Persistable. It does not recurse. Will only update top level Persistables.
+export function updatePersistables(
+    target: Record<string, any>,
+    obj?: Record<string, any>
+): void {
+    if (obj === undefined) return
+    for (const key in target) {
+        if (key in obj) {
+            const currentVal = target[key]
+            const currentValIsPersistableObject = currentVal?.updateFromObject
+            const newVal = obj[key]
+            if (currentValIsPersistableObject)
+                currentVal.updateFromObject(newVal)
+            else target[key] = newVal
+        }
+    }
+}
+
+// Don't persist properties that haven't changed from the defaults, and don't
+// keep properties not on the comparable class
+export function deleteRuntimeAndUnchangedProps<T>(
+    changedObj: T,
+    defaultObject: T
+): T {
+    const obj = toJS(changedObj) as Record<string, unknown>
+    const defaultObj = defaultObject as Record<string, unknown>
+    const defaultKeys = new Set(Object.keys(defaultObj))
+    Object.keys(obj).forEach((key) => {
+        if (!defaultKeys.has(key)) {
+            // Don't persist any runtime props not in the persistable instance
+            delete obj[key]
+            return
+        }
+
+        const currentValue = obj[key]
+        const defaultValue = defaultObj[key]
+        if (_.isEqual(currentValue, defaultValue)) {
+            // Don't persist any values that weren't changed from the default
+            delete obj[key]
+        }
+    })
+    return obj as T
+}

package/src/utils/persistable/readme.md

@@ -0,0 +1,50 @@
+# Persistable
+
+This Persistable interface should be used on all classes that we want to save and rehydrate.
+
+The pattern that has emerged (but can probably be improved upon) is:
+
+1.  An `Interface` for all the properties to be serialized/deserialized.
+2.  An `DefaultsClass` implementing `Interface` with all the properties and defaults. This is only necessary in order to identify the runtime vs persistable properties, and for comparing defaults. This should have no methods.
+3.  A class extending the `DefaultsClass` and implementing interface `Persistable`. This is your main class.
+
+1 & 2 can be combined, and you can just generate an interface from the `DefaultsClass`.
+
+## Rationale
+
+The Grapher admin let's authors create and edit instances of Grapher at runtime, and we save those to disk for later playback.
+
+So Graphers, and a number of properties on Grapher, are persisted. Although relatively simple, because serializing and deserializing are
+such a core bit of our code, and because we often make slight adjustments in both places, it helps to have a standard way of
+doing that throughout the Grapher codebase. Our use of Mobx also makes our needs a little different than others. Previously we had bugs where we would write something
+to the DB that should have only been a runtime property, or vice versa.
+
+The specific needs we have are listed below.
+
+Serializing:
+
+- should serialize only persistable properties
+- should have the option to serialize only values changed from their defaults
+- should be able to serialize/deserialize arbitrary "special values" that don't interchange well with JSON, such as Infinity
+- should be able to follow these rules recursively
+
+Deserializing:
+
+- should instantiate the proper non-primitive classes
+- should be able to parse "special values" to the proper in-memory structure
+- should optionally be able to validate
+- should be able to follow these rules recursively
+
+## How to Use
+
+See the interface definition.
+
+## Alternatives Considered
+
+No reason to keep this code, if we come up with a better pattern or library. One potential one is this: https://github.com/mobxjs/serializr
+
+But our needs are pretty small so it may make sense to just have our own tiny implementation.
+
+## Todo
+
+Note that the `update` method is not ideal and is not RAII. We should probably do all initialization in the constructor instead of in the updates.