Stores reference #453

rorticus · 2019-07-19T15:39:35Z

This is a copy of #341 but that has been updated to address the requested feedback.

If this is merged, we can close #341.

agubler

A few bits are missing or outdated:

Widgets should be converted to the new function-based API
The stores middleware is not mentioned at all (for use with function-based widgets)

agubler · 2019-07-24T10:31:21Z

docs/en/stores/basic-usage.md

+
+Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.
+
+Stores provide a clean interface for storing, modifying, and retrieving data from a global object using a unidirectional data flow. Common patterns such as asynchronous retrieval, middleware, and undo patterns are built in. This allows widgets to remain focused on their primary roles of providing a visual representation of themselves and listening for user interactions.


I'm not sure about the wording of "asynchronous retrieval"

agubler · 2019-07-24T10:35:11Z

docs/en/stores/basic-usage.md

+
+Adds a value to an object or inserts it into an array.
+
+> `add` example


I think this formatting is used to indicate the filename not a title, perhaps @sbinge can confirm?

agubler · 2019-07-24T10:37:37Z

docs/en/stores/basic-usage.md

+	];
+});
+
+export const login = createProcess('login', [ fetchUser, loadUserData ]);


Should we explain this string "id" now as it is part of the example?

agubler · 2019-07-24T10:37:59Z

docs/en/stores/basic-usage.md

+export const login = createProcess('login', [ fetchUser, loadUserData ]);
+```
+
+#### Middleware


Do you think middleware is basic usage? I'm not sure...

agubler · 2019-07-24T10:38:34Z

docs/en/stores/basic-usage.md

+
+## Widgets and Stores
+
+There are two state containers available for widgets: `Container` and `StoreProvider`. These containers connect the application store with a widget.


I think it's StoreContainer rather than Container

agubler · 2019-07-24T10:39:59Z

docs/en/stores/basic-usage.md

+> widget/User.container.ts
+
+```ts
+import { createStoreContainer } from '@dojo/framework/stores/StoreInjector';


This should be imported from StoreContainer

agubler · 2019-07-24T10:41:00Z

docs/en/stores/basic-usage.md

+
+In this example `UserContainer` wraps `User` to display the current user's name. `createStoreContainer` is wrapper that is used to ensure the proper typing of `getProperties`. `getProperties` is responsible for getting to data from the store and creating properties for the widget.
+
+The most important thing to note about a `Container` is its properties are a 1:1 mapping to the widget it wraps. In other words, all properties that appear on the widget should be provided by the `Container`.


The widget properties become the properties of the container, but they are all optional..

agubler · 2019-07-24T10:42:45Z

docs/en/stores/supplemental.md

+
+## Pre-typing
+
+A pre-typed container can be created by extending the standard `StoreProvider` and passing the `State` type as a generic.


I don't think we should really recommend doing this? Soon these will be converted to functional widgets and it won't be possible - at that point we'd be able to provide a util function that can be used to create a "typed" provider.

agubler · 2019-07-24T10:44:54Z

docs/en/stores/supplemental.md

+
+### ImmutableState
+
+Dojo Stores provide an implementation of the MutableState interface that leverages [Immutable](). This implementation may provide better performance if there are frequent, deep updates to the store's state. Performance should be tested and verified before fully committing to this implementation.


needs a link to immutable?

agubler · 2019-07-24T10:45:59Z

docs/en/stores/supplemental.md

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


Should we mention JSON patch?

I'm not sure this whole section is required? What do other people think?

I think JSON Patch is cool, so to me it's worth mentioning. :)

I would say though, although it's based on JSON patch it's not implemented to exact spec - also it's something that we could change i.e. an implementation detail

I don't think we should mention JSON patch at all. It is 100% an implementation detail and we do not let the user write/pass JSON patch anywhere. As @agubler said also we do not fulfil the entire spec (nor do we intend to).

dylans

I still need to review the supplemental content and later, but wanted to provide what I've reviewed thus far.

dylans · 2019-07-24T11:40:03Z

docs/en/stores/basic-usage.md

@@ -0,0 +1,454 @@
+# Basic Usage
+
+Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.


Suggested change

Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.

Dojo provides a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.

dylans · 2019-07-24T11:42:37Z

docs/en/stores/basic-usage.md

+
+Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.
+
+Stores provide a clean interface for storing, modifying, and retrieving data from a global object using a unidirectional data flow. Common patterns such as asynchronous retrieval, middleware, and undo patterns are built in. This allows widgets to remain focused on their primary roles of providing a visual representation of themselves and listening for user interactions.


Suggested change

Stores provide a clean interface for storing, modifying, and retrieving data from a global object using a unidirectional data flow. Common patterns such as asynchronous retrieval, middleware, and undo patterns are built in. This allows widgets to remain focused on their primary roles of providing a visual representation of themselves and listening for user interactions.

Stores provide a clean interface for storing, modifying, and retrieving data from a global object through unidirectional data flow. Stores include support for common patterns such as asynchronous data retrieval, middleware, and undo. Stores and their patterns allow widgets to focus on their primary role of providing a visual representation of information and listening for user interactions.

dylans · 2019-07-24T11:43:27Z

docs/en/stores/basic-usage.md

+
+## The Store
+
+The store holds the global, atomic state for the entire application. It is created when the application is created and defined in the `Registry` with an injector.


Suggested change

The store holds the global, atomic state for the entire application. It is created when the application is created and defined in the `Registry` with an injector.

The store holds the global, atomic state for the entire application. The store gets created when the application gets created and defined in the `Registry` with an injector.

dylans · 2019-07-24T11:44:20Z

docs/en/stores/basic-usage.md

+const registry = registerStoreInjector(store);
+```
+
+`State` defines the shape of the global store using an interface. It is important that everything inside `State` is serializable, as this improves performance and makes it easier for Dojo to determine when changes to the data occur.


We've used the term global a lot, and in general in JS, global means global variable, rather than global to the application, so we may want to be more precise about that term throughout.

I'm not sure the term shape will make a lot of sense to a new user at this point?

Similarly, will someone know at this point what it means to make something serializable?

dylans · 2019-07-24T11:46:57Z

docs/en/stores/basic-usage.md

+const registry = registerStoreInjector(store);
+```
+
+`State` defines the shape of the global store using an interface. It is important that everything inside `State` is serializable, as this improves performance and makes it easier for Dojo to determine when changes to the data occur.


Suggested change

`State` defines the shape of the global store using an interface. It is important that everything inside `State` is serializable, as this improves performance and makes it easier for Dojo to determine when changes to the data occur.

`State` defines the shape of the global store using an interface. Everything inside `State` should be serializable, as this improves performance by making it easier for the Dojo virtual DOM system to determine when changes to the data occur.

I don't know this suggestion is accurate, but something like this (plus address my other comments please)

dylans · 2019-07-24T12:15:28Z

docs/en/stores/basic-usage.md

+
+### Excuting a Process
+
+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. Both the `Container` and `StoreProvider` widgets will provide you with access to the store.


Suggested change

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. Both the `Container` and `StoreProvider` widgets will provide you with access to the store.

A process simply defines an execution flow for a set of data. To execute a process, the process needs access to the store to create an executor. Both the `Container` and `StoreProvider` widgets provide access to the store.

dylans · 2019-07-24T12:16:01Z

docs/en/stores/introduction.md

@@ -0,0 +1,15 @@
+# Introduction
+
+Dojo stores is a predictable, consistent state container with built-in support for common patterns.


Suggested change

Dojo stores is a predictable, consistent state container with built-in support for common patterns.

Dojo stores provide a predictable, consistent state container with built-in support for common state management patterns.

dylans · 2019-07-24T12:17:00Z

docs/en/stores/introduction.md

+
+Dojo stores is a predictable, consistent state container with built-in support for common patterns.
+
+This package provides a centralized store designed to be the single source of truth for an application. It operates using uni-directional data flow. This means all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.


Suggested change

This package provides a centralized store designed to be the single source of truth for an application. It operates using uni-directional data flow. This means all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.

This Dojo stores package provides a centralized store designed to be the single source of truth for an application. Dojo applications operate using uni-directional data flow. As a result, all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.

dylans · 2019-07-24T12:17:43Z

docs/en/stores/introduction.md

+
+| Feature                   | Description                                                          |
+| ------------------------- | -------------------------------------------------------------------- |
+| global data store         | application state is stored globally in a single source of truth     |


Suggested change

| global data store | application state is stored globally in a single source of truth |

| global data store | application state gets stored globally in a single source of truth |

again I would somehow look to make it clear that this is global to the app and not a JS global without adding a bunch of words

dylans · 2019-07-24T12:17:58Z

docs/en/stores/introduction.md

+| ------------------------- | -------------------------------------------------------------------- |
+| global data store         | application state is stored globally in a single source of truth     |
+| uni-directional data flow | predictable and global application state management                  |
+| type safe                 | access and modification of state is protected by interfaces          |


dylans

And some more suggestions.

dylans · 2019-07-24T13:31:34Z

docs/en/stores/supplemental.md

@@ -0,0 +1,425 @@
+# State
+
+In modern browsers a `state` object is passed as part of the CommandRequest. Any modification to this object is translated to the appropriate patch operations and applied against the store.


Suggested change

In modern browsers a `state` object is passed as part of the CommandRequest. Any modification to this object is translated to the appropriate patch operations and applied against the store.

In modern browsers a `state` object is passed as part of the `CommandRequest`. Any modification to this `state` object gets translated to the appropriate patch operations and applied against the store.

dylans · 2019-07-24T13:31:54Z

docs/en/stores/supplemental.md

+});
+```
+
+Note that attempting to access state is not supported in IE and will immediately throw an error.


Suggested change

Note that attempting to access state is not supported in IE and will immediately throw an error.

Note that attempting to access state is not supported in IE11 and will immediately throw an error.

dylans · 2019-07-24T13:32:20Z

docs/en/stores/supplemental.md

+
+The StoreProvider accepts three properties
+
+-   `renderer`: A render function that has the store injected in order to access state and pass processes to child widgets.


Suggested change

- `renderer`: A render function that has the store injected in order to access state and pass processes to child widgets.

- `renderer`: A render function that has the store injected to access state and pass processes to child widgets.

dylans · 2019-07-24T13:33:11Z

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 by passing the `paths` property to the provider to ensure invalidation will only occur when state you are interested in changes.


Suggested change

1. The recommended approach is to register `path`s by passing the `paths` property to the provider to ensure invalidation will only occur when state you are interested in changes.

1. The recommended approach is to register `path`s by passing the `paths` property to the provider to ensure invalidation only occurs when relevant state changes.

dylans · 2019-07-24T13:34:44Z

docs/en/stores/supplemental.md

+/>
+```
+
+If you are **not** using `tsx`, in order for TypeScript to infer this correctly when using w(), the generic will need to be explicitly passed.


Suggested change

If you are **not** using `tsx`, in order for TypeScript to infer this correctly when using w(), the generic will need to be explicitly passed.

If you are **not** using `tsx`, in order for TypeScript to infer this correctly when using `w()`, the generic needs to get passed explicitly.

dylans · 2019-07-24T14:22:50Z

docs/en/stores/supplemental.md

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


Suggested change

# JSON Patch and Store operations

# JSON Patch and Store Operations

dylans · 2019-07-24T14:23:36Z

docs/en/stores/supplemental.md

+
+> Result
+
+```json


Most of our other guide examples use spaces for indentation, so we may want to change this for consistency?

dylans · 2019-07-24T14:24:17Z

docs/en/stores/supplemental.md

+
+Even though state has not been initialized, Dojo is able to create the underlying hierarchy based on the provided path. This operation is safe because of the type safety that TypeScript and Dojo Stores provide. This allows for users to work naturally with the `State` interface used by the store instead of needing to be concerned with the data explicitly held by the store.
+
+When an explicit state is required that information can asserted by using a `test` operation or by getting the underlying data and validating it programmatically.


Suggested change

When an explicit state is required that information can asserted by using a `test` operation or by getting the underlying data and validating it programmatically.

When an explicit state is required, that information can get asserted by using a `test` operation or by getting the underlying data and validating it programmatically.

dylans · 2019-07-24T14:24:38Z

docs/en/stores/supplemental.md

+]);
+```
+
+This example ensures that `user` is always added to the end of the list as the last element.


Suggested change

This example ensures that `user` is always added to the end of the list as the last element.

This example ensures that `user` always gets added to the end of the list as the last element.

dylans · 2019-07-24T14:25:43Z

docs/en/stores/supplemental.md

+]);
+```
+
+Access to state root is not permitted and will throw an error, for example, `get(path('/'))`. This applies to Operations also, it is not possible to create an operation that will update the state root. Best practices with @dojo/framework/stores mean touching the smallest part of the store as is necessary.


Suggested change

Access to state root is not permitted and will throw an error, for example, `get(path('/'))`. This applies to Operations also, it is not possible to create an operation that will update the state root. Best practices with @dojo/framework/stores mean touching the smallest part of the store as is necessary.

Access to state root is not permitted and will throw an error, for example, `get(path('/'))`. This restriction also applies to Operations; it is not possible to create an operation that will update the state root. Best practices with `@dojo/framework/stores` encourage accessing the smallest necessary part of the store.

rorticus · 2019-07-26T13:35:24Z

@agubler @dylans I believe all of the feedback has been addressed!

maier49 · 2019-07-26T16:10:09Z

docs/en/stores/basic-usage.md

+
+## The Store
+
+The store holds the global, atomic state for the entire application. The store gets created when the application gets created and defined in the `Registry` with an injector.


Maybe say "The store should be created..." instead of "The store gets created...". I feel like the latter makes it sound like this will happen automatically.

maier49 · 2019-07-26T16:22:01Z

docs/en/stores/basic-usage.md

+
+### Commands & Operations
+
+To modify a store, when executing a process, an operation function gets invoked. The operation function gets returned from a command. Each command is passed a `CommandRequest` which provides `path` and `at` functions to generate `Path`s in a type-safe way, a `get` function for access to the store's state, a `payload` object for the argument that the process executor was called with.


Should this sentence say "command function" instead of "operation function"? And in the next sentence, "The operation function gets returned from a command", is that right? Commands return an array of operations (or a promise or nothing), not a function.

maier49 · 2019-07-26T16:28:35Z

docs/en/stores/basic-usage.md

+
+In this example `UserContainer` wraps `User` to display the current user's name. `createStoreContainer` is a wrapper that gets used to ensure the proper typing of `getProperties`. `getProperties` is responsible for accessing data from the store and creating properties for the widget.
+
+A `StoreContainer`'s properties are a 1:1 mapping to the widget it wraps. The widget become the properties of the `StoreContainer`, but they are all optional.


"The widget become the properties" I am assuming this means something like The widget is passed the properties or The widget receives the properties? If this isn't a mistake maybe some more clarification is in order?

rorticus · 2019-07-29T11:08:10Z

@maier49 I believe your feedback has been addressed!

sbinge

We can get this in as-is with any further changes raised later as follow-up PRs, if needed.

devpaul and others added 8 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

WIP supplemental

0980cb5

supplemental draft

f56ccb2

introduction draft

267d9e5

Updating based on review feedback

583d62e

rorticus requested review from agubler, matt-gadd and sbinge July 19, 2019 15:39

agubler requested changes Jul 24, 2019

View reviewed changes

dylans requested changes Jul 24, 2019

View reviewed changes

Review feedback

ed7d444

Adding blurb about process IDs

62d7ca2

maier49 reviewed Jul 26, 2019

View reviewed changes

More review feedback

37fb80e

sbinge added the reference guide documentation label Jul 30, 2019

sbinge approved these changes Jul 30, 2019

View reviewed changes

sbinge merged commit 3015e46 into dojo:master Jul 30, 2019

agubler mentioned this pull request Jan 29, 2020

Reference guide: Dojo Stores #324

Closed


		Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.

		Stores provide a clean interface for storing, modifying, and retrieving data from a global object using a unidirectional data flow. Common patterns such as asynchronous retrieval, middleware, and undo patterns are built in. This allows widgets to remain focused on their primary roles of providing a visual representation of themselves and listening for user interactions.


		Adds a value to an object or inserts it into an array.

		> `add` example


		## Widgets and Stores

		There are two state containers available for widgets: `Container` and `StoreProvider`. These containers connect the application store with a widget.


		In this example `UserContainer` wraps `User` to display the current user's name. `createStoreContainer` is wrapper that is used to ensure the proper typing of `getProperties`. `getProperties` is responsible for getting to data from the store and creating properties for the widget.

		The most important thing to note about a `Container` is its properties are a 1:1 mapping to the widget it wraps. In other words, all properties that appear on the widget should be provided by the `Container`.


		## Pre-typing

		A pre-typed container can be created by extending the standard `StoreProvider` and passing the `State` type as a generic.


		### ImmutableState

		Dojo Stores provide an implementation of the MutableState interface that leverages [Immutable](). This implementation may provide better performance if there are frequent, deep updates to the store's state. Performance should be tested and verified before fully committing to this implementation.

		@@ -0,0 +1,454 @@
		# Basic Usage

		Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.

	Dojo is a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.
	Dojo provides a reactive architecture concerned with constantly modifying and rendering the current state of an application. In simple systems this can happen at a local level and widgets can maintain their own state. However, as a system becomes more complex the need to better compartmentalize and encapsulate data and create a clean separation of concerns quickly grows.


		## The Store

		The store holds the global, atomic state for the entire application. It is created when the application is created and defined in the `Registry` with an injector.

	`State` defines the shape of the global store using an interface. It is important that everything inside `State` is serializable, as this improves performance and makes it easier for Dojo to determine when changes to the data occur.
	`State` defines the shape of the global store using an interface. Everything inside `State` should be serializable, as this improves performance by making it easier for the Dojo virtual DOM system to determine when changes to the data occur.


		### Excuting a Process

		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. Both the `Container` and `StoreProvider` widgets will provide you with access to the store.

		@@ -0,0 +1,15 @@
		# Introduction

		Dojo stores is a predictable, consistent state container with built-in support for common patterns.

	Dojo stores is a predictable, consistent state container with built-in support for common patterns.
	Dojo stores provide a predictable, consistent state container with built-in support for common state management patterns.


		Dojo stores is a predictable, consistent state container with built-in support for common patterns.

		This package provides a centralized store designed to be the single source of truth for an application. It operates using uni-directional data flow. This means all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.

	This package provides a centralized store designed to be the single source of truth for an application. It operates using uni-directional data flow. This means all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.
	This Dojo stores package provides a centralized store designed to be the single source of truth for an application. Dojo applications operate using uni-directional data flow. As a result, all application data follows the same lifecycle, ensuring the application logic is predictable and easy to understand.

	\| global data store \| application state is stored globally in a single source of truth \|
	\| global data store \| application state gets stored globally in a single source of truth \|

	\| type safe \| access and modification of state is protected by interfaces \|
	\| type safe \| access and modification of state gets protected by interfaces \|

		@@ -0,0 +1,425 @@
		# State

		In modern browsers a `state` object is passed as part of the CommandRequest. Any modification to this object is translated to the appropriate patch operations and applied against the store.

	Note that attempting to access state is not supported in IE and will immediately throw an error.
	Note that attempting to access state is not supported in IE11 and will immediately throw an error.


		The StoreProvider accepts three properties

		- `renderer`: A render function that has the store injected in order to access state and pass processes to child widgets.

Stores reference #453

Stores reference #453

Uh oh!

Conversation

rorticus commented Jul 19, 2019

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!

dylans 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!

dylans 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


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

		1. The recommended approach is to register `path`s by passing the `paths` property to the provider to ensure invalidation will only occur when state you are interested in changes.

	If you are not using `tsx`, in order for TypeScript to infer this correctly when using w(), the generic will need to be explicitly passed.
	If you are not using `tsx`, in order for TypeScript to infer this correctly when using `w()`, the generic needs to get passed explicitly.

	# JSON Patch and Store operations
	# JSON Patch and Store Operations


		Even though state has not been initialized, Dojo is able to create the underlying hierarchy based on the provided path. This operation is safe because of the type safety that TypeScript and Dojo Stores provide. This allows for users to work naturally with the `State` interface used by the store instead of needing to be concerned with the data explicitly held by the store.

		When an explicit state is required that information can asserted by using a `test` operation or by getting the underlying data and validating it programmatically.

	When an explicit state is required that information can asserted by using a `test` operation or by getting the underlying data and validating it programmatically.
	When an explicit state is required, that information can get asserted by using a `test` operation or by getting the underlying data and validating it programmatically.

	This example ensures that `user` is always added to the end of the list as the last element.
	This example ensures that `user` always gets added to the end of the list as the last element.

	Access to state root is not permitted and will throw an error, for example, `get(path('/'))`. This applies to Operations also, it is not possible to create an operation that will update the state root. Best practices with @dojo/framework/stores mean touching the smallest part of the store as is necessary.
	Access to state root is not permitted and will throw an error, for example, `get(path('/'))`. This restriction also applies to Operations; it is not possible to create an operation that will update the state root. Best practices with `@dojo/framework/stores` encourage accessing the smallest necessary part of the store.


		### Commands & Operations

		To modify a store, when executing a process, an operation function gets invoked. The operation function gets returned from a command. Each command is passed a `CommandRequest` which provides `path` and `at` functions to generate `Path`s in a type-safe way, a `get` function for access to the store's state, a `payload` object for the argument that the process executor was called with.


		In this example `UserContainer` wraps `User` to display the current user's name. `createStoreContainer` is a wrapper that gets used to ensure the proper typing of `getProperties`. `getProperties` is responsible for accessing data from the store and creating properties for the widget.

		A `StoreContainer`'s properties are a 1:1 mapping to the widget it wraps. The widget become the properties of the `StoreContainer`, but they are all optional.