mobx-sentinel

Change detection, reactive validation, and form integration for class-based MobX models — added from the outside, without contaminating the models themselves.

Get started API reference GitHub

Packages

@mobx-sentinel/core

Watcher detects changes in models, Validator validates them reactively — composable from many sources, sync or async, with smart job scheduling and cancellation for async validations — and @nested tracks models inside models.

@mobx-sentinel/form

Asynchronous submission, nested and array forms, flexible custom bindings (most in less than 50 lines), and error reporting that shows errors when users are ready for them.

@mobx-sentinel/react

Hooks that handle component lifecycle for you, and standard bindings for the most common form elements.

Why mobx-sentinel

This library originally started with the goal of creating a form-building library centered around models, and evolved into a more general-purpose library that enhances model capabilities with form management being one of its applications.

About Form Management

When dealing with complex domains, we needed a solution that works with forms while assuming business logic exists as class implementations using MobX. With models as a premise, most responsibilities should be placed on the model side.

While there are already many libraries for building forms using MobX, they are all designed from a data serialization perspective rather than modeling, and have issues either being unable to use classes or not properly separating data from form state management. Furthermore, there isn't a single one designed to allow type-safe implementation from both model and UI ends. (cf. Alternatives)
Additionally, showing error messages to users at appropriate times is important for user experience, yet many existing libraries lack proper design. (cf. Smart Error Reporting)

This library aims to solve these problems through a model-centric design that properly separates and breaks down responsibilities into layers:

Validation = Business logic layer (Model)
- Provides validity state and error management
Form-specific state management = Application logic layer (View-Model)
- Handles form submission
- Reacts to validity state changes
Input element connection (a.k.a. Binding) = Presentation layer (View)
- Handles form state and UI events to update forms, models and UI
- Gets values from the model and writes back on input changes
- Expresses error states

Design Principles

Model first
- Assumes the existence of class-based models.
- Promotes clear separation between core business logic and application logic.
- [Form] Pushes responsibilities towards the model side, minimizing form responsibilities.
- [Form] Do not manage data directly; Not intended for simple data-first form implementations.
Non-intrusive
- Minimizes required interfaces for models, maintaining purity.
- Extends model's capabilities from an "outsider" standpoint.
- [Form] No direct references between forms and models.
Transparent I/O
- No module directly mutates models — Makes control obvious and safe.
- Unidirectional data flow / dependency.
- [Form] No hidden magic between model ↔ input element interactions.
Modular implementation
- Multi-package architecture with clear separation of concerns.
- Enhances testability and extensibility.
Rigorous typing
- Maximizes use of TypeScript's type system for error detection and code completion.
- Improves development productivity.

How it compares

See how mobx-sentinel differs from other MobX form libraries in type safety, UI bindings and class-based design, and how its error reporting differs from popular form libraries.

Alternatives