@jbrowse/mobx-state-tree 5.10.8 → 5.11.1

package/README.md

@@ -1,27 +1,155 @@
 # @jbrowse/mobx-state-tree
 
-Fork of mobx-state-tree v5.4.2 for use in jbrowse
-
-## Current list of changes
-
-- updated typescript
-- updated to import actual filepaths instead of node module resolution
-- reduced rollup config
-- removed process.env.NODE_ENV from code, instead exporting a setDevMode function
-- converted tests to vitest
-- remove unused dependencies
-- updated tslint to eslint and typescript-eslint
-- dual CJS/ESM build using main and module fields (pure ESM causes trouble when both are imported in vite)
-- added `types.resilient` - wraps a type so that instantiation errors are caught
-  and a fallback type is used instead of crashing the entire state tree. This is
-  useful for arrays or maps that may contain unknown or invalid entries (e.g.
-  plugin types that are not installed). It takes a primary type, a fallback type,
-  and a `createFallbackSnapshot` callback that receives the error and original
-  snapshot. Note: `isValidSnapshot` always returns success for resilient types,
-  meaning any value is considered a valid snapshot. Validation is deferred to
-  instantiation time, where failures are caught and routed to the fallback
-- removed NonEmptyObject annotation (also at upstream in post v5 versions)
-- replaced `unique symbol` phantom properties (`$emptyObject`, `$stateTreeNodeType`) with
+Fork of [mobx-state-tree](https://mobx-state-tree.js.org) v5.4.2 maintained for use in
+[JBrowse 2](https://jbrowse.org). All upstream types and APIs are available — this page
+documents only the additions and changes made in this fork.
+
+## Infrastructure changes
+
+- Updated TypeScript and import paths to use explicit file extensions
+- Replaced `process.env.NODE_ENV` with an exported `setDevMode()` function
+- Converted tests from Jest to Vitest
+- Replaced tslint with eslint + typescript-eslint
+- Dual CJS/ESM build (avoids issues when both are imported in the same Vite build)
+- Removed unused dependencies and the `NonEmptyObject` annotation
+- Replaced `unique symbol` phantom properties (`$emptyObject`, `$stateTreeNodeType`) with
   exported string-keyed brand interfaces (`$EmptyObjectBrand`, `$__mstStateTreeNodeType__`),
-  fixing tsgo TS4058/TS4023 errors when MST types propagate into exported function return types
-- add reflection api getChildType and getUnionSubtypes and getDefaultInstanceOrSnapshot
+  fixing tsgo TS4058/TS4023 errors when MST types appear in exported function return types
+
+## Added APIs
+
+### `types.resilient`
+
+Wraps a type so that if instantiation fails (e.g. because the snapshot is from an unknown
+plugin that is not installed), the error is caught and a fallback type is used instead of
+crashing the entire state tree.
+
+```ts
+const PluginWidget = types.resilient(
+  KnownWidget,
+  UnknownWidget,
+  (error, originalSnapshot) => ({ kind: "unknown", raw: originalSnapshot }),
+)
+
+// Arrays of plugins stay alive even if one entry is unrecognized
+const Store = types.model({
+  widgets: types.array(PluginWidget),
+})
+```
+
+`types.resilient` takes three arguments:
+
+- `type` — the primary type to try first
+- `fallbackType` — the type to use when the primary fails
+- `createFallbackSnapshot(error, originalSnapshot)` — a callback that receives the caught
+  error and the original snapshot, and returns a valid snapshot for the fallback type
+
+**Important caveat:** `isValidSnapshot` always returns success for a resilient type. Any
+value is considered a valid snapshot — validation is deferred to instantiation time, where
+failures are caught and routed to the fallback.
+
+---
+
+### `types.stripDefault`
+
+Like `types.optional`, but omits the property key from the parent model's snapshot entirely
+when the value equals the default.
+
+#### Background: snapshots and `types.optional`
+
+In MST, a **snapshot** is the plain JSON representation of your model — what you'd get from
+`getSnapshot(model)` and what you'd pass to `Model.create(...)`. Snapshots are used for
+serialization, persistence, and undo/redo.
+
+`types.optional` lets you define a property with a default value so it can be omitted when
+creating a model:
+
+```ts
+const Settings = types.model({
+  theme: types.optional(types.string, "light"),
+})
+
+const s = Settings.create()   // theme is "light"
+getSnapshot(s)                // { theme: "light" }
+```
+
+Even though `"light"` is just the default, it always appears in the snapshot. If you store
+or diff these snapshots, every instance carries that redundant data.
+
+#### What `types.stripDefault` does
+
+`types.stripDefault` works exactly like `types.optional` at runtime — the property gets its
+default when missing — but the key is **left out of the snapshot entirely** when the value
+equals the default:
+
+```ts
+const Settings = types.model({
+  theme: types.stripDefault(types.string, "light"),
+})
+
+const s = Settings.create()
+getSnapshot(s)                // {}  ← key omitted because value equals default
+
+s.theme = "dark"
+getSnapshot(s)                // { theme: "dark" }
+
+s.theme = "light"
+getSnapshot(s)                // {}  ← omitted again
+```
+
+#### Why this matters
+
+Without `stripDefault`, keeping defaults out of snapshots requires a manual
+`postProcessSnapshot` on every model. `stripDefault` handles this automatically per-property.
+
+This is especially useful when:
+
+- Snapshots are stored or synced and you want to minimize their size
+- You diff snapshots (e.g. for undo/redo or change detection) and want default values to
+  appear as "no change" rather than an explicit write
+- You have many optional fields and don't want boilerplate `postProcessSnapshot`
+
+#### How the default comparison works
+
+The comparison is done against the **normalized** default snapshot, not the raw value you
+passed in. MST instantiates the subtype with the default once, reads back its snapshot
+(which applies any nested model defaults and post-processing), and caches that as the
+reference. This means a complex nested default that gains extra fields at instantiation time
+will still compare correctly.
+
+---
+
+### Reflection API additions
+
+These utilities expose type metadata that is useful for building generic tooling (e.g.
+editors, inspectors, plugin systems) that need to introspect an MST type at runtime.
+
+**`getChildType(node, propertyName?)`** — returns the declared MST type of a child
+property on a model, array, or map instance. For arrays and maps the property name is
+ignored (all children share one element type).
+
+```ts
+const Box = types.model({ x: types.number, y: types.number })
+const box = Box.create({ x: 1, y: 2 })
+
+getChildType(box, "x").name  // "number"
+```
+
+**`getUnionSubtypes(type)`** — given a `types.union` type, returns the array of its member
+types. Useful when you need to enumerate what a union can hold.
+
+```ts
+const Shape = types.union(Circle, Square, Triangle)
+
+getUnionSubtypes(Shape)  // [Circle, Square, Triangle]
+```
+
+**`getDefaultInstanceOrSnapshot(optionalType)`** — returns the default value (or snapshot)
+declared on a `types.optional` or `types.stripDefault` type. Lets generic tooling read the
+default without having to create a model instance.
+
+```ts
+const t = types.optional(types.string, "hello")
+
+t.getDefaultInstanceOrSnapshot()  // "hello"
+```

package/dist/index.d.ts

@@ -1921,6 +1921,17 @@ declare function optional<IT extends IAnyType, OptionalVals extends ValidOptiona
  * @returns
  */
 declare function isOptionalType<IT extends IAnyType>(type: IT): type is IT;
+/**
+ * `types.stripDefault` - Like `types.optional`, but the property is omitted from
+ * a parent model's snapshot entirely when its value equals the default (instead
+ * of being serialized with the default value). Lets a model produce minimal
+ * snapshots without a bespoke `postProcessSnapshot`.
+ *
+ * @param type
+ * @param defaultValueOrFunction
+ * @returns
+ */
+declare function stripDefault<IT extends IAnyType>(type: IT, defaultValueOrFunction: OptionalDefaultValueOrFunction<IT>): IOptionalIType<IT, [undefined]>;
 
 /** @hidden */
 interface IMaybeIType<IT extends IAnyType, C, O> extends IType<IT["CreationType"] | C, IT["SnapshotType"] | O, IT["TypeWithoutSTN"] | O> {
@@ -2149,6 +2160,7 @@ declare const types: {
     safeReference: typeof safeReference;
     union: typeof union;
     optional: typeof optional;
+    stripDefault: typeof stripDefault;
     literal: typeof literal;
     maybe: typeof maybe;
     maybeNull: typeof maybeNull;

package/dist/mobx-state-tree.cjs

@@ -4905,7 +4905,7 @@ class ModelType extends ComplexType {
     }
     getSnapshot(node, applyPostProcess = true) {
         const res = {};
-        this.forAllProps((name, _type) => {
+        this.forAllProps((name, type) => {
             try {
                 // TODO: FIXME, make sure the observable ref is used!
                 const atom = mobx.getAtom(node.storedValue, name);
@@ -4914,7 +4914,11 @@ class ModelType extends ComplexType {
             catch (_e) {
                 throw fail(`${name} property is declared twice`);
             }
-            res[name] = this.getChildNode(node, name).snapshot;
+            const snapshot = this.getChildNode(node, name).snapshot;
+            // strip-default optionals omit their key when equal to the default
+            if (!shouldStripChildFromSnapshot(type, snapshot)) {
+                res[name] = snapshot;
+            }
         });
         if (applyPostProcess) {
             return this.applySnapshotPostProcessor(res);
@@ -4924,7 +4928,13 @@ class ModelType extends ComplexType {
     processInitialSnapshot(childNodes) {
         const processed = {};
         Object.keys(childNodes).forEach(key => {
-            processed[key] = childNodes[key].getSnapshot();
+            const snapshot = childNodes[key].getSnapshot();
+            // strip-default optionals omit their key when equal to the default; this
+            // mirrors getSnapshot for nodes serialized before they become observable
+            // instances (e.g. array/map children that were never accessed)
+            if (!shouldStripChildFromSnapshot(this.properties[key], snapshot)) {
+                processed[key] = snapshot;
+            }
         });
         return this.applySnapshotPostProcessor(processed);
     }
@@ -5878,6 +5888,84 @@ const undefinedAsOptionalValues = [undefined];
 function isOptionalType(type) {
     return isType(type) && (type.flags & TypeFlags.Optional) > 0;
 }
+/**
+ * Compare a child snapshot to a stripped-default's reference snapshot. Mirrors
+ * the legacy hand-rolled comparison: identity for primitives, structural for
+ * objects/arrays.
+ */
+function defaultSnapshotEquals(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (typeof a === "object" &&
+        a !== null &&
+        typeof b === "object" &&
+        b !== null) {
+        // Cheap structural short-circuit before the full stringify compare: a
+        // value of a different size can't equal the default, so the common strip
+        // case (non-empty value vs an empty `[]`/`{}` default) avoids stringifying
+        // a potentially large snapshot on every getSnapshot.
+        if (Array.isArray(a) !== Array.isArray(b)) {
+            return false;
+        }
+        const aSize = Array.isArray(a) ? a.length : Object.keys(a).length;
+        const bSize = Array.isArray(b) ? b.length : Object.keys(b).length;
+        if (aSize !== bSize) {
+            return false;
+        }
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+}
+/**
+ * An optional type that additionally omits its key from a parent model's
+ * snapshot when the value equals the (snapshotted) default. The comparison is
+ * against the default *snapshot* — i.e. the subtype is instantiated with the
+ * default once and its post-processed snapshot is cached — so a default whose
+ * normalized form gains fields (e.g. a fileLocation gaining `locationType`)
+ * still strips correctly.
+ *
+ * @hidden
+ * @internal
+ */
+class StripDefaultValue extends OptionalValue {
+    _defaultSnapshot;
+    shouldStripFromSnapshot(snapshot) {
+        if (!this._defaultSnapshot) {
+            // instantiate the subtype detached with the default and read the node's
+            // snapshot, which normalizes (fills model defaults, applies the subtype's
+            // own postProcess). Cached on the (singleton) type after first use.
+            const node = this.getSubTypes().instantiate(null, "", undefined, this.getDefaultInstanceOrSnapshot());
+            this._defaultSnapshot = { value: node.snapshot };
+        }
+        return defaultSnapshotEquals(snapshot, this._defaultSnapshot.value);
+    }
+}
+/**
+ * Whether `type` is a strip-default optional whose current child `snapshot`
+ * equals its default and should therefore be omitted from the parent model's
+ * snapshot. Used by `ModelType.getSnapshot`.
+ *
+ * @hidden
+ * @internal
+ */
+function shouldStripChildFromSnapshot(type, snapshot) {
+    return (type instanceof StripDefaultValue && type.shouldStripFromSnapshot(snapshot));
+}
+/**
+ * `types.stripDefault` - Like `types.optional`, but the property is omitted from
+ * a parent model's snapshot entirely when its value equals the default (instead
+ * of being serialized with the default value). Lets a model produce minimal
+ * snapshots without a bespoke `postProcessSnapshot`.
+ *
+ * @param type
+ * @param defaultValueOrFunction
+ * @returns
+ */
+function stripDefault(type, defaultValueOrFunction) {
+    checkOptionalPreconditions(type, defaultValueOrFunction);
+    return new StripDefaultValue(type, defaultValueOrFunction, undefinedAsOptionalValues);
+}
 
 const optionalUndefinedType = optional(undefinedType, undefined);
 const optionalNullType = optional(nullType, null);
@@ -6895,6 +6983,7 @@ const types = {
     safeReference,
     union,
     optional,
+    stripDefault,
     literal,
     maybe,
     maybeNull,