V2 Documentation Content Outline Brainstorming

Configuration

• Babel 6 - "plugins": ["transform-decorators-legacy"]

Background and Fundamentals

• Philosophy, terminology, key concepts, benefits, thinking in Mobservable (maximize computations, minimize state size)

• Amazing Examples - demonstrate the the advantages / differences

  • Compare and contrast with Flux approaches
  • Meteor Tracker comparison and problems solved: https://medium.com/@faceyspacey/the-evolution-of-tracker-solutions-to-its-core-problems-4b9cb90d479a#.5fd0nzli7

• How does it work - link to blog post

• State

  • Building Blocks - observable, computed, reaction (?), action
  • Types - values, arrays, maps, sets
  • Examples - how to build collections of state (POJS, ES5, Decorators, Typed)
  • Helpers - peek, untracked, autorun, autorunAsync, autorunUntil, expr

React Design Patterns

• UI and Domain Stores (from current docs)
  • Explain how most state is outside the components
  • Show how state is loaded asynchronously
• React Components
  • making them observers and explaining how to pass state to them (eg. is all state in global stores? is it better to use props / context / singletons?)

Design Patterns

• Transactions
• Expression composition
• Transformations
  • describe how they work: in which situations are they useful, how to manage lifecycles of generated objects
  • how to register dependencies (and where not to)
• Using with 'set' to implement actions
• Code Reuse
  • Mixins
  • Reusable stores
• Lifecycle Management
  • Computed state

Pitfalls and Common Solutions

• Anti pattern: update state in reaction to state updates
• Creating one-time reactions for loading, clean-up etc using when
• Watching for a value change and cascading updates - for example, the user clicks on a list item, the item's isActive property is set, and you want to update the the UI Store without creating a cycle (https://github.com/mweststrate/mobservable/issues/72)
• Asynchronous data fetching - for example, using autorun to watch for a change, fetch a value from the server, then updating an observable. Is there a way to do this with asynchronous computed values? what about if a second change occurs mid-fetch?
• Multiple transformation - I think the API currently only supports a single transformation, but maybe needs to be expanded (eg. one per transformation instance)
• How to avoid using untracked
• How to architect a reusable component that uses mobservable internally, but integrates with non-mobservable components - should store observables in component state and use an unwrap function to pass data out?
• Transactions and views - this is related to the potential issue in https://github.com/mweststrate/mobservable/issues/67. Should get be used or not? What about @computed? Currently, I'm finding that I need to cache the transformed nodes and use shallowCompare to see if they changed (which may be a bug or a problem that this pitfall advice will solve)
• Handling props that may change, but have observables. To hide implementation details, sometimes a subset of state is passed to a component rather than a full store. If the root of the subset changes, you find yourself watching the old root. Recommendation: assign a key to the component: https://github.com/mweststrate/mobservable/issues/78. The key should be an internal implementation detail (eg. transparently assigned) rather than assigned by the caller.

Tips and Tricks / Cool Stuff

• Debugging
• Using the debugging tools

Upgrading Guide to V2

Changed Behavior

• fastArray

Renaming

• autorun -> reactive (?)
• autorunUntil -> when

Deprecations

• observable (type) - show that it can be replaced with 'extend' and / or decorators
• observable (value) - show that it can be replaced with 'extend' and / or decorators
• modifiers (asFlat, asReference, asStructure) - show that they can be solved with 'extend' and non-recursive observables...hopefully!