Deprecation Notice: As of 0.4.0, this library has been migrated to: @yogasoft/tidal-state
Tidal State
A framework-agnostic library that takes the complexity out of state management. Built 100% in TypeScript with an Object-Oriented design and full support for reactive programming.
Key Features
- Quickly structure state on any class or object with RxJS-enabled stateful properties.
- Safely expose and share state with flexible access rules.
- Object-Oriented design with highly re-usable components.
- Fully type-enabled classes and interfaces.
- TS strict mode verified. (pre-packaged code)
- Easily import into any JS or TS project (UI/Node) for a powerful, yet simple state management solution.
- ES5 compatibility.
Description
Tidal State is a state management library that allows your application to safely navigate the stateful tide, leveraging the power of RxJS while presenting a simpler interface for state interactions.
Class state is defined by stateful properties, which can then be exposed together as distinct state objects. There are three primary types of tidal properties, covering the general types in JavaScript: primitives, functions, and objects. Each of the three tidal properties has two versions: a read-only and a read-write version. The properties can be used independently for internal state management in a single class, but can optionally be exposed to the state pool through the TidalApplication api.
Access rules define what classes or other "state owners" in the application have access to a given state object. They can also leverage the current status of the state itself to determine access rights. Defining state access rules is optional, and by default only the state owner has access to a given state object.
The state pool - the collection of all of the application's state objects - is accessed through an instance of TidalNavigator. Each navigator is identified by a stateId - a string constant which denotes the class or "owner" of the navigator. There are two types of navigators: attached and detached. A detached navigator is not tied to any state object, and is only identified by a human-readable state id field. Whereas, an attached navigator "owns" a specific state object, and thus has special access to its properties, such as the ability to access the subject of a read-only property, or reset a read-only property.
The primary goal of Tidal State is to provide a simple, Object-Oriented approach to state management, allowing everyone from novice to expert to benefit. It easily integrates into any Typescript (or JS) application.
Releases
0.3.0 (Released)
- New TidalNavigator#getTransientState method now returns the new TransientState type. The onInit and onDestroy methods allow setting up interactions with StateObjects immediately after they're initialized in the state pool, or just before they are destroyed and removed. TransientStates can be used to setup state interactions regardless of whether the state has been initialized or not.
- Add new TidalService type for representing service calls as non-finite event streams. Includes internal ServiceCallStatus property for tracking service call state and TidalExecutor for synchronously triggering event propagation.
- Added new TidalApplication#initFreeState method, which initializes a "free" state in the application state pool, which is not owned by any caller, and whose access is therefore fully determined by the required StateAccessRule that is passed in. This can be used for semi-global states or states which have a longer lifetime than their consumers.
- Added resetAllLocalProperties(obj) util method. Resets all Local* properties contained in the passed in object.
- Add ability to chain two Tidal* or Local* property to eachother with new sync() method. This causes value updates to propagate between them.
- All destroy method calls now call Subject#unsubscribe() internally on all Tidal* properties, preventing any access to a tidal property value after it has been destroyed.
- Reworked TidalFunction* generic types so a function type is used now instead of only the function return type.
- ServiceCallStatus is now a shareable property, extending TidalPrimitive. The previous version is now called LocalServiceCallStatus, which still extends LocalPrimitive, and is therefore RW, but never is part of a shared StateObject.
- Added orElseGet method to all Tidal and Local properties. Returns passed in value if the current value of the property is null or undefined.
- Fixed TidalNavigator#resetState(stateId) method to only attempt resets on Tidal* properties as expected.
- Removal of all functionality which was deprecated in v0.2.0.
0.2.0
- Published library is now fully ES5 backwards compatible.
- Addition of Local* property types. Local properties behave exactly the same as the normal Tidal* type of properties, except that they are never pulled into the state pool (they're excluded from the StateObject), and thus are only available to the class in which they are defined. This allows fine-grained control over which properties are shareable and which are not, within a single class's state.
- Streamlined state and navigator initialization. The 'TidalApplication#initNavigator' function followed by 'TidalNavigator#initState' is now the primary way of initializing a state object. Child states can be initialized with 'TidalNavigator#initChildState'. Both 'TidalApplication#initDetachedNavigator' and 'TidalApplication#initState' are now deprecated.
- Added new 'destroy' method to TidalNavigator, which destroys the navigator, along with all of its owned states, including any child states created by the navigator.
- Added isAnyReadOnlyProperty, isAnyReadWriteProperty, and isAnyLocalProperty util functions.
- Fixed type handling on TidalObject/RW patch method. It is no longer possible to patch when the object is currently null.
- Added new Toggleable* util properties. Convenient properties that take a primary and secondary value and can be toggled with .toggle(). Including the basic ToggleableBoolean, which just takes the initial value.
- Add 'resetState' method to TidalNavigator objects, providing a simple way to reset all properties in any StateObject. Note, if any non-owner attempts to reset a state with read-only properties, then an error will be throw and none of the target StateObject's properties will be reset.
- Added ServiceCallStatus util property. Easily track the status of a service call in various phases (init, processing, failure, success).
- Added 'set' convenience method to TidalNavigator - a shorthand way for state owners to update a RO property value.
0.1.0
- Initial stable release with core features.