@jbrowse/mobx-state-tree 5.11.1 → 5.12.0

package/README.md

@@ -16,6 +16,79 @@ documents only the additions and changes made in this fork.
   exported string-keyed brand interfaces (`$EmptyObjectBrand`, `$__mstStateTreeNodeType__`),
   fixing tsgo TS4058/TS4023 errors when MST types appear in exported function return types
 
+## Error message changes
+
+Validation and conversion errors have been reworked to stay readable on large state
+trees. Upstream MST could throw error messages hundreds of kilobytes long because it
+expanded every union member's full structure and stringified entire snapshots unbounded.
+This fork keeps the errors short while making them more diagnosable.
+
+### Bounded conversion errors
+
+`typecheck()` / instantiation errors no longer dump unbounded output:
+
+- Stringified snapshots are depth-bound (nested objects past 3 levels collapse to `…`)
+- Each printed value is capped in length
+- At most 10 individual errors are reported, with a `(… and N more errors)` suffix
+
+### Scoped discriminated-union errors
+
+Take a union of view types discriminated by a literal `type` property:
+
+```ts
+const LinearGenomeView = types.model("LinearGenomeView", {
+  type: types.literal("LinearGenomeView"),
+  height: types.number,
+  assembly: types.string
+})
+const DotplotView = types.model("DotplotView", {
+  type: types.literal("DotplotView"),
+  height: types.number
+})
+const AnyView = types.union(LinearGenomeView, DotplotView)
+```
+
+Upstream MST listed every member's full structure on any failure. A single mistyped field
+produced output like this — each member's entire schema expanded inline, repeated for every
+member, often hundreds of kilobytes on a real config union:
+
+```
+No matching type for union(LinearGenomeView | DotplotView)
+(snapshot `{"type":"LinearGenomeView","height":"tall","assembly":"hg38"}` is not assignable
+to type: `({ type: ("LinearGenomeView" | snapshot like `"LinearGenomeView"`); height: number;
+assembly: string } | { type: ("DotplotView" | snapshot like `"DotplotView"`); height: number })`,
+expected an instance of `LinearGenomeView` or a snapshot like `{ type: ("LinearGenomeView" |
+snapshot like `"LinearGenomeView"`); height: number; assembly: string }` instead. … )
+```
+
+Now the error is scoped to the single member whose literal `type` matches the snapshot's
+discriminator, and reports only the property-level reasons it failed.
+
+`AnyView.create({ type: "LinearGenomeView", height: "tall", assembly: "hg38" })` throws:
+
+```
+[mobx-state-tree] Error while converting `{"type":"LinearGenomeView","height":"tall","assembly":"hg38"}` to `(LinearGenomeView | DotplotView)`:
+
+    at path "/height" value `"tall"` is not assignable to type: `number` (Value is not a number).
+```
+
+And in production builds (where full type-checking is skipped) a missing required field on a
+recognized member still names the discriminator and the offending path —
+`AnyView.create({ type: "LinearGenomeView", height: 100 })` throws:
+
+```
+[mobx-state-tree] No matching type for union (LinearGenomeView | DotplotView) for snapshot with type "LinearGenomeView":
+    at path "/assembly" value `undefined` is not assignable to type: `string` (Value is not a string).
+```
+
+Instead of a wall of text covering every union member, you get the discriminator that was
+seen plus the property-level reasons that one intended member rejected the snapshot (wrong
+field type, missing required field, etc.). The scoping drills through wrapped members
+(`optional`, `refinement`, `snapshotProcessor`, `late`) to find the underlying model, so
+real-world members like an `optional(model)` config schema are still matched correctly.
+When two members declare the same `type` literal (ambiguous), it falls back to the short
+message rather than guessing.
+
 ## Added APIs
 
 ### `types.resilient`
@@ -28,12 +101,12 @@ crashing the entire state tree.
 const PluginWidget = types.resilient(
   KnownWidget,
   UnknownWidget,
-  (error, originalSnapshot) => ({ kind: "unknown", raw: originalSnapshot }),
+  (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),
+  widgets: types.array(PluginWidget)
 })
 ```
 
@@ -66,11 +139,11 @@ creating a model:
 
 ```ts
 const Settings = types.model({
-  theme: types.optional(types.string, "light"),
+  theme: types.optional(types.string, "light")
 })
 
-const s = Settings.create()   // theme is "light"
-getSnapshot(s)                // { theme: "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
@@ -84,17 +157,17 @@ equals the default:
 
 ```ts
 const Settings = types.model({
-  theme: types.stripDefault(types.string, "light"),
+  theme: types.stripDefault(types.string, "light")
 })
 
 const s = Settings.create()
-getSnapshot(s)                // {}  ← key omitted because value equals default
+getSnapshot(s) // {}  ← key omitted because value equals default
 
 s.theme = "dark"
-getSnapshot(s)                // { theme: "dark" }
+getSnapshot(s) // { theme: "dark" }
 
 s.theme = "light"
-getSnapshot(s)                // {}  ← omitted again
+getSnapshot(s) // {}  ← omitted again
 ```
 
 #### Why this matters
@@ -132,7 +205,7 @@ ignored (all children share one element type).
 const Box = types.model({ x: types.number, y: types.number })
 const box = Box.create({ x: 1, y: 2 })
 
-getChildType(box, "x").name  // "number"
+getChildType(box, "x").name // "number"
 ```
 
 **`getUnionSubtypes(type)`** — given a `types.union` type, returns the array of its member
@@ -141,7 +214,7 @@ 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]
+getUnionSubtypes(Shape) // [Circle, Square, Triangle]
 ```
 
 **`getDefaultInstanceOrSnapshot(optionalType)`** — returns the default value (or snapshot)
@@ -151,5 +224,5 @@ default without having to create a model instance.
 ```ts
 const t = types.optional(types.string, "hello")
 
-t.getDefaultInstanceOrSnapshot()  // "hello"
+t.getDefaultInstanceOrSnapshot() // "hello"
 ```

package/dist/index.d.ts

@@ -347,7 +347,7 @@ declare function getRelativePath(base: IAnyStateTreeNode, target: IAnyStateTreeN
  * @param keepEnvironment indicates whether the clone should inherit the same environment (`true`, the default), or not have an environment (`false`). If an object is passed in as second argument, that will act as the environment for the cloned tree.
  * @returns
  */
-declare function clone<T extends IAnyStateTreeNode>(source: T, keepEnvironment?: boolean | any): T;
+declare function clone<T extends IAnyStateTreeNode>(source: T, keepEnvironment?: boolean | object): T;
 /**
  * Removes a model element from the state tree, and let it live on as a new state tree
  */
@@ -1284,52 +1284,6 @@ interface IAnyStateTreeNode extends STNValue<any, IAnyType> {
  */
 declare function isStateTreeNode<IT extends IAnyComplexType = IAnyComplexType>(value: any): value is STNValue<Instance<IT>, IT>;
 
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<R>(generator: () => IterableIterator<any>): () => Promise<R>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1>(generator: (a1: A1) => IterableIterator<any>): (a1: A1) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2>(generator: (a1: A1, a2: A2) => IterableIterator<any>): (a1: A1, a2: A2) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3>(generator: (a1: A1, a2: A2, a3: A3) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3, A4>(generator: (a1: A1, a2: A2, a3: A3, a4: A4) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3, a4: A4) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3, A4, A5>(generator: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3, A4, A5, A6>(generator: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3, A4, A5, A6, A7>(generator: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7) => Promise<any>;
-/**
- * @deprecated has been renamed to `flow()`.
- * @hidden
- */
-declare function process<A1, A2, A3, A4, A5, A6, A7, A8>(generator: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8) => IterableIterator<any>): (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8) => Promise<any>;
-
 /**
  * @hidden
  */
@@ -2185,5 +2139,5 @@ declare const types: {
     resilient: typeof resilient;
 };
 
-export { addDisposer, addMiddleware, applyAction, applyPatch, applySnapshot, cast, castFlowReturn, castToReferenceSnapshot, castToSnapshot, clone, createActionTrackingMiddleware, createActionTrackingMiddleware2, decorate, destroy, detach, escapeJsonPath, flow, getChildType, getEnv, getIdentifier, getLivelinessChecking, getMembers, getNodeId, getParent, getParentOfType, getPath, getPathParts, getPropertyMembers, getRelativePath, getRoot, getRunningActionContext, getSnapshot, getType, getUnionSubtypes, hasParent, hasParentOfType, isActionContextChildOf, isActionContextThisOrChildOf, isAlive, isArrayType, isFrozenType, isIdentifierType, isLateType, isLiteralType, isMapType, isModelType, isOptionalType, isPrimitiveType, isProtected, isReferenceType, isRefinementType, isRoot, isStateTreeNode, isType, isUnionType, isValidReference, joinJsonPath, onAction, onPatch, onSnapshot, process, protect, recordActions, recordPatches, resolveIdentifier, resolvePath, setDevMode, setLivelinessChecking, setLivelynessChecking, setTypeChecking, splitJsonPath, types as t, toGenerator, toGeneratorFunction, tryReference, tryResolve, typecheck, types, unescapeJsonPath, unprotect, walk };
+export { addDisposer, addMiddleware, applyAction, applyPatch, applySnapshot, cast, castFlowReturn, castToReferenceSnapshot, castToSnapshot, clone, createActionTrackingMiddleware, createActionTrackingMiddleware2, decorate, destroy, detach, escapeJsonPath, flow, getChildType, getEnv, getIdentifier, getLivelinessChecking, getMembers, getNodeId, getParent, getParentOfType, getPath, getPathParts, getPropertyMembers, getRelativePath, getRoot, getRunningActionContext, getSnapshot, getType, getUnionSubtypes, hasParent, hasParentOfType, isActionContextChildOf, isActionContextThisOrChildOf, isAlive, isArrayType, isFrozenType, isIdentifierType, isLateType, isLiteralType, isMapType, isModelType, isOptionalType, isPrimitiveType, isProtected, isReferenceType, isRefinementType, isRoot, isStateTreeNode, isType, isUnionType, isValidReference, joinJsonPath, onAction, onPatch, onSnapshot, protect, recordActions, recordPatches, resolveIdentifier, resolvePath, setDevMode, setLivelinessChecking, setLivelynessChecking, setTypeChecking, splitJsonPath, types as t, toGenerator, toGeneratorFunction, tryReference, tryResolve, typecheck, types, unescapeJsonPath, unprotect, walk };
 export type { $EmptyObjectBrand, CustomTypeOptions, IActionContext, IActionRecorder, IActionTrackingMiddleware2Call, IActionTrackingMiddleware2Hooks, IActionTrackingMiddlewareHooks, IAnyComplexType, IAnyModelType, IAnyStateTreeNode, IAnyType, IArrayType, IComplexType, IDisposer, IJsonPatch, IMSTArray, IMSTMap, IMapType, IMaybe, IMaybeIType, IMaybeNull, IMiddlewareEvent, IMiddlewareEventType, IMiddlewareHandler, IModelReflectionData, IModelReflectionPropertiesData, IModelType, IOptionalIType, IPatchRecorder, IReferenceType, IReversibleJsonPatch, ISerializedActionCall, ISimpleType, ISnapshotProcessor, ISnapshotProcessors, IStateTreeNode, IType, ITypeUnion, Instance, LivelinessMode, LivelynessMode, ModelActions, ModelCreationType, ModelCreationType2, ModelInstanceType, ModelInstanceTypeProps, ModelPrimitive, ModelProperties, ModelPropertiesDeclaration, ModelPropertiesDeclarationToProperties, ModelSnapshotType, ModelSnapshotType2, OnReferenceInvalidated, OnReferenceInvalidatedEvent, OptionalDefaultValueOrFunction, ReferenceIdentifier, ReferenceOptions, ReferenceOptionsGetSet, ReferenceOptionsOnInvalidated, SnapshotIn, SnapshotOrInstance, SnapshotOut, TypeOfValue, TypeOrStateTreeNodeToStateTreeNode, UnionOptions, UnionStringArray, ValidOptionalValue, ValidOptionalValues, _CustomCSProcessor, _CustomJoin, _CustomOrOther, _NotCustomized };