Skip to content

[STAR-2198] Initial state management library implementation.

Fox Piacenti requested to merge fox/STAR-2198-state-management into master

This MR implements singleton management in Providence. This allows client developers to instantly instantiate redux slices with the most commonly needed mutations and actions included. Once the store is initialized, and your types are defined, you can put code like this in a component:

const controller = useSingle<TestType>('test', {endpoint: '/some/api/url/'})

...And get a controller object that can do common operations with typechecking. So, you can do this:

controller.x = {a: 'thing'}

...And in the background, Providence will commit the updated value to the redux state.

Providence ensures you get one controller per name-- in the above instance, the name is test, and the controller you receive will be the same if you request it in another component. You can do common network operations with the controller. For instance, when you need a controller to ensure that a resource is fetched if it has not been already, you can do:

controller.getOnce()

...and be certain that only one network call will be used, even if several components might be loading that controller at the same time and in uncertain order.

You can also post, patch, and delete objects using their convenience methods. Each will make a call to the endpoint URL.

In many cases, you'd want to update only a single field on an object. The canonical example would be for creating interactive form elements that will patch and update a value on an object. For this, we have the patcher, a special controller that creates debounced background patch requests as you update it, and provides properties that let you keep track of whether the value has been updated on the server (that is, whether it is dirty) and errors that have been returned from the server when attempting to update the field (such as validation messages).

These patchers are available on the special p property on the controller. For example:

const controller = useSingle<Person>('test', {endpoint: '/some/api/url/', {x: {name: 'Person', age: 26})
controller.p.name.model = 'Homer Simpson'

The above will send a patch request to /some/api/url to update the value on the server. If there is an error, the errors will be available on:

controller.p.name.errors

JIRA tickets: https://tasks.opencraft.com/browse/SE-5153

Testing instructions:

  1. Clone the repo
  2. npm install
  3. npm run test

You should be able to see the .spec files, which demonstrate how the controllers can be used.

Edited by Fox Piacenti

Merge request reports