@jbrowse/mobx-state-tree
v6.10.1
Published
Fork of mobx-state-tree starting from v5.4.2 for use in jbrowse 2
Readme
@jbrowse/mobx-state-tree
Fork of mobx-state-tree v5.4.2 for JBrowse 2.
- In: any upstream MST code. Every upstream type and API is still here.
- Out: the same trees, with the additions and fixes below.
- Each bullet links to the page, ADR or commit that has the detail.
- CHANGELOG.md lists every release.
Highlights
- Lazy loading and plugins:
types.union({ members: () => [...] })re-reads its members on every operation, so a plugin can register a type after the tree exists.extendInstanceadds views and actions to a live node.types.resilientkeeps the tree alive when a plugin is missing. - Smaller snapshots:
types.stripDefaultdrops a key from the snapshot while it holds the default value. - Faster at scale: array replacement,
applySnapshot,onSnapshotand type construction are 2x to 35x faster in the cases measured (Performance). - Safer writes: a refused write leaves the tree untouched.
Added APIs
Details in docs/added-apis.md.
types.resilient(type, fallback, createFallbackSnapshot): an unrecognized snapshot builds the fallback instead of crashing the tree.types.stripDefault(type, default): likeoptional, but the key leaves the snapshot when the value equals the default.types.union({ members: () => [...] }): membership re-read on every operation, for lazily loaded types.extendInstance(instance, fn): attach views, actions and volatile state to a live instance.getChildType,getUnionSubtypes,getDefaultInstanceOrSnapshot: reflection for editors and inspectors.getWrappedType,unwrapType,asArrayType,asMapType,asModelType: exact-type helpers.types.composetakes 11 parts, up from 9.
Error messages
Details in docs/error-messages.md.
- Conversion errors are depth-bound, length-capped and limited to 10 entries.
- A discriminated union reports only the member whose literal
typematched.
Behavior changes
Details in docs/behavior-changes.md.
- A refused write leaves the tree as it found it.
- A never-read node still runs
beforeDestroyand its disposers. - Detaching an ancestor of a reference's target invalidates the reference.
- A throwing preprocessor counts as a refusal during union dispatch.
- A flow that yields a non-promise rejects.
- Action-tracking middleware keeps per-instance state and settles after its last flow.
Performance
Details in docs/performance.md.
- Keyed array reconcile is linear: 10x at n=1000.
- Type construction is ~2.4x faster, and no-options unions are interned: −34% heap.
onSnapshotandgetSnapshotreads are ~2x faster, and theonSnapshotreaction dies with its last listener.- The validation-result cache is gone.
Upgrading from upstream
Code that worked on upstream can break in these places:
- The peer dependency is
mobx ^7.0.0; upstream accepts^6.3.0. - Node
>=22is required. isArrayType,isMapTypeandisModelTypeno longer narrow. Type errors move toasArrayType,asMapTypeandasModelType(ADR 0006).NonEmptyObjectis removed, so code that imported it must stop.- A property or action named
toString,valueOf,constructoror anotherObject.prototypemember throws at definition. - In production,
union(A, 5)throwsInvalid value used as weak map key; upstream built a broken union. union(A, B) === union(A, B), so a write to one union's type object shows up in every caller's (ADR 0005).
Types and build
- Phantom
unique symbolproperties became string-keyed brand interfaces, which fixes tsgo TS4058/TS4023. setDevMode()toggles dev mode at runtime.NODE_ENVis read once at load.- Dual CJS/ESM build, Vitest instead of Jest, eslint instead of tslint.
Design records
agent-docs/architecture-decision-records holds the decisions where the obvious change is wrong for a measured reason. Read the matching ADR before touching array reconciliation, union dispatch, type construction or the isXType guards.
Footnote
Written with extensive use of Claude Code.
