Stores reference #341

devpaul · 2019-05-17T18:42:32Z

This is a draft of the stores reference guide.

Introduction is mostly complete. Some cleanup on the features will likely need to happen when I'm done writing and have full view of everything.
Basic usage is done. It contains everything a person needs to use state from store to widget written in a manner that progresses from operations thru StoreProvider.
Supplemental is done

Resolves #324

We added a discussion about Dojo's implementation of JSON patch in the supplemental section after writing #339 and discussing the state feature with @maier49. Dojo differs quite significantly from JSON patch in that it tries to do the right thing regarding uninitialized state and avoid throwing errors.

agubler · 2019-05-28T09:08:35Z

docs/en/stores/basic-usage.md

+});
+```
+
+`State` defines the shape of the global store using an interface. In general state should be serializable. This improves performance and makes it easier for Dojo to determine when changes to the data occur.


State should be completely serializable, this is important for features such as history.

I agree that it usually should be. How would you recommend handling state that contains TypedArrays for large data sets or BigInt?

agubler

@devpaul A few comments, but this looks like a good start!

agubler · 2019-05-28T09:10:19Z

docs/en/stores/basic-usage.md

+
+> main.ts
+
+```ts


Do you think that we should use the helper from StoreInjector, registerStoreInjector for the example:

import { registerStoreInjector } from '@dojo/framework/store/StoreInjector'; import Store from '@dojo/framework/stores/Store'; import { State } from './interfaces'; const store = new Store<State>(); const registry = registerStoreInjector(store);

Totally. I forgot about that :)

agubler · 2019-05-28T09:11:34Z

docs/en/stores/basic-usage.md

+
+### Operations
+
+Stores cannot be modified directly. Instead four operations are available for modifying state: `add`, `remove`, `replace`, and `test`. These operations are represented by simple objects based on the [JSON patch](http://jsonpatch.com/) format, but in practice helper functions will always be used.


I don't think we need to mention JSON patch here, although being inspired by JSON patch is where we started it is an implementation detail that we could change in the future.

I agree. After writing this I spoke w/ @maier49 and found that we deviate from JSON patch in a lot of small ways

agubler · 2019-05-28T09:13:57Z

docs/en/stores/basic-usage.md

+A process simply defines an execution flow for a set of data. To execute a process it needs access to the store to create an executor. Then the executor can be provided a payload to act upon.
+
+```ts
+import { login } from 'commands/login';


Should this be processes? And also prefixed with ./?

agubler · 2019-05-28T09:14:25Z

docs/en/stores/basic-usage.md

+
+Note that the documentation in this section is intended to show how widgets and state are connected. For a more detailed look see the [Widgets]() reference guide.
+
+### Container


Can we talk about the StoreProvider first please?

agubler · 2019-05-28T09:16:03Z

docs/en/stores/basic-usage.md

+const login = createProcess('login', [ fetchUser, loadUserData ], [ resetUserOnError ]);
+```
+
+#### Excuting a Process


Perhaps it's worth talking about this in the StoreProvider / Container sections as that's the main place that you will have access to the store? I'm not sure we should be suggesting people to export the store instance from main.ts.... Maybe we should have a section on creating initial store state, which would normally be done in the main.ts

You make a good point. I wanted to show the most basic usage of a process, but in doing so it could be reinforcing a bad pattern.

agubler · 2019-05-28T09:26:31Z

docs/en/stores/basic-usage.md

+
+`UserProvider` extends `WidgetBase` allowing us the opportunity to redefine the widget's properties. In this case `UserProvider` does not accept any properties. It gets all of the information it needs from the store. The `StoreProvider` occurs as part of `UserProvider`'s render and provides its own renderer just like any other widget.
+
+The `StoreProvider` is more robust than a `Container`. Since it is always wrapped by a widget it gives the opportunity to decide what properties should be provided by the outside widget and which should be provided from the store.


I don't think this is true, it's not always wrapped by a widget nor would I recommend doing that by default. I would also start with using the StoreProvider inline and then think about where to abstract when it becomes required.

Hmm maybe this part can be removed entirely. For me it was novel when the StoreProvider became available because Container didn't allow properties to be redefined it was actually a lot of work to connect a store to a widget and then change the properties. So while I was really excited about StoreProvider for this reason future Dojo users can just take this for granted 😅

agubler · 2019-05-28T09:27:19Z

docs/en/stores/supplemental.md

+
+-   `renderer`: A render function that has the store injected in order to access state and pass processes to child widgets.
+-   `stateKey`: The key of the state in the registry.
+-   `paths` (optional): A function to connect the Container to sections of the state.


"connect the provider to sections of the state"

agubler · 2019-05-28T09:28:02Z

docs/en/stores/supplemental.md

+
+The `StoreProvider` has two main ways to trigger invalidation and cause a rerender.
+
+1.  The recommended approach is to register `path`s on container creation to ensure invalidation will only occur when state you are interested in changes.


"register paths by passing the paths property to the provider...."

agubler · 2019-05-28T09:29:05Z

docs/en/stores/supplemental.md

+export class TypedStoreProvider extends StoreProvider<State> {}
+```
+
+**However** in order for TypeScript to infer this correctly when using w(), the generic will need to be explicitly passed.


Using tsx infers the renderer functions arguments correctly, do you think we should demonstrate this?

That sounds great. Why does it work for tsx and not w()?

agubler · 2019-05-28T09:30:38Z

docs/en/stores/supplemental.md

+});
+```
+
+# JSON Patch and Store operations


As before I don't think we should mention JSON path in the reference guide.

There's some advanced functionality here that I want to cover

that stores will automatically create the underlying structure

that stores will rarely throw an error

that adding and replacing past the end of an array will add to the end of an array

Maybe keep this section and remove the references to JSON Patch

agubler · 2019-05-30T19:13:29Z

@devpaul Sorry to be a pain but as #357 has been merged, could you update any references to framework/widget-core to framework/core. Thanks!

devpaul · 2019-06-01T01:05:26Z

Thanks for your feedback @agubler! Hope to have time to work on this soon

devpaul added 4 commits May 13, 2019 17:49

WIP dojo/stores skeleton

dd3baaf

WIP Mostly complete basic usage, draft introduction, some supplemental

f795c3c

editing

45df725

Store and widgets

1e200d9

devpaul requested a review from sbinge May 17, 2019 18:42

devpaul added 3 commits May 20, 2019 09:47

WIP supplemental

0980cb5

supplemental draft

f56ccb2

introduction draft

267d9e5

devpaul marked this pull request as ready for review May 21, 2019 02:31

vansimke added the reference guide documentation label May 21, 2019

agubler reviewed May 28, 2019

View reviewed changes

agubler requested changes May 28, 2019

View reviewed changes

rorticus mentioned this pull request Jul 19, 2019

Stores reference #453

Merged

sbinge closed this in #453 Jul 30, 2019


		### Operations

		Stores cannot be modified directly. Instead four operations are available for modifying state: `add`, `remove`, `replace`, and `test`. These operations are represented by simple objects based on the [JSON patch](http://jsonpatch.com/) format, but in practice helper functions will always be used.


		Note that the documentation in this section is intended to show how widgets and state are connected. For a more detailed look see the [Widgets]() reference guide.

		### Container


		`UserProvider` extends `WidgetBase` allowing us the opportunity to redefine the widget's properties. In this case `UserProvider` does not accept any properties. It gets all of the information it needs from the store. The `StoreProvider` occurs as part of `UserProvider`'s render and provides its own renderer just like any other widget.

		The `StoreProvider` is more robust than a `Container`. Since it is always wrapped by a widget it gives the opportunity to decide what properties should be provided by the outside widget and which should be provided from the store.


		The `StoreProvider` has two main ways to trigger invalidation and cause a rerender.

		1. The recommended approach is to register `path`s on container creation to ensure invalidation will only occur when state you are interested in changes.


		> main.ts

		```ts

Stores reference #341

Stores reference #341

Uh oh!

Conversation

devpaul commented May 17, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agubler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

agubler commented May 30, 2019

Uh oh!

devpaul commented Jun 1, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

devpaul commented May 17, 2019 •

edited

Loading