varstor 0.6.61 → 0.6.63

package/README.md

@@ -18,126 +18,223 @@ import Varstor from 'varstor/webextension'
 ```
 in your script file.
 
-## Usage
+## Contents
+1. [Usage](#overview)  
+[1.1 Creation ```.add()```/```.addPersistent()```](#creation)  
+[1.2 Dynamic reevaluation (```ReactiveFunction```)](#reactivefunction)  
+[1.3 Accessing ```.get()```](#accessing)  
+[1.4 Mutating ```.set()```/```.reset()```](#mutating)  
+[1.5 Listening ```.onChange()```/```.removeListener()```](#listening)  
+[1.6 Data encapsulation ```.actions()```](#actions)  
+[1.7 Namespacing ```.get(Namespace)```](#namespacing)  
+[1.8 Method chaining](#chaining)  
+2. [Shortcuts](#shortcuts)  
+3. [Example](#example)  
+
+## Usage <a name="overview"></a>
 The library object features the following methods:
 ```js
 .add ()
 .addPersistent ()
 .get ()
 .set ()
-.resetAll ()
+.reset ()
 .onChange ()
 .removeListener ()
+.actions ()
 ```
 
-Values are added to the store with ```add``` or ```addPersistent``` methods. They perform the same functionality, except ```addPersistent``` allows state to be saved in storage and reused between browser sessions.
-Signature of those methods is:
+## Creation ```.add()```/```.addPersistent()``` <a name="creation"></a>
+Values are added to the store with add or addPersistent methods. They perform the same functionality, except addPersistent saves state to the storage and lets you reuse it between browser sessions.
+
 ```js
 async Varstor.add(
   KeysValues {
     key1: value1,
     key2: value2,
-    key3: ComputeFunction(...dependencies) => computedValue
-    ...
-  }
-) =>
-  StateAccessors {
-    key: StateAccessor
+    key3: ReactiveFunction(...valueNames[]) => computedValue
     ...
   }
+) => Varstor
 ```
 Where:  
-```KeysValues``` - a standard object with keys and values, where ```key``` is used to identify a piece of state, and ```value``` to give it a default value or ```ComputeFunction```  
-```ComputeFunction``` - reevalutes and updates its value automatically each time ```dependencies``` parameters change. ```dependencies``` parameters are any state values defined before the ```ComputeFunction```. ```computedValue```s are not saved in storage.   
-```StateAccessors``` - a map linking state ```key```s to special ```StateAccessor``` objects which will perform data manipulations and listener management.  
+```KeysValues {}``` - a standard object with keys and values, where ```key``` is a name of piece of state, and ```value``` is a default value or ```ReactiveFunction```  
+```ReactiveFunction``` - re-evalutes and updates its value automatically each time arguments in ```valueNames``` list change. ```valueNames``` are any state values defined before the ```ReactiveFunction```. ```computedValue```s are not saved in storage.   
 
 **Important: ```add``` and ```addPersistent``` are asynchronous operations; you must `await` or use ```Promise.then``` to ensure all the data is ready to work with!**  
   
-  
+## Dynamic reevaluation (```ReactiveFunction```) <a name="reactivefunction"></a>
+Values can change automatically with the help of ```ReactiveFunction```s when one or more of the other values in the namespace change.  
 
-Values can be accessed with:  
 ```js
-Varstor.get () => StateValues
+ReactiveFunction (...valueNames[]) => computedValue
+```
+Put the names of dependencies in the  ```valueNames``` arguments list of the ```ReactiveFunction```, and describe the calculation in the body of the function.  
+```js
+Varstor.add({
+  a: 1
+  b: 2,
+  c: (a, b) => a + b // 3
+})
 ```
-Where:  
-```StateValues``` - an object representing all the values in the store in the current namespace at the current moment  
   
 
-or
+## Accessing ```.get()``` <a name="accessing"></a>
+Values are accessed with:  
 ```js
-Varstor.get (AccessorsCallback (StateAccessors {}, Varstor) => value) => value
+Varstor.get() => NamespaceValues {}
 ```
 Where:  
-```AccessorsCallback``` - a function that takes all ```StateAccessors``` and a ```Varstor``` instance from the current namespace, manipulates them, and can return any ```value```, which in turn will be returned from the whole ```get(Callback)``` call.
-
+```NamespaceValues {}``` - an object representing all the values in the current namespace at the current moment  
 
-Values can be mutated with:
+  
+  
+## Mutating ```.set()```/```.reset()``` <a name="mutating"></a>
+Values are mutated with:
 ```js
-async Varstor.set (
+async Varstor.set(
   KeysValues {
     key: value
     ...
   }
 ) => Varstor
 ```
-**Important: values are updated asynchronously; don't assume the script will recognize the change immediately. Instead, make use of ```onChange``` listeners!**  
+**Important: values are updated asynchronously; don't assume the script will recognize the change immediately on the next line. Instead, ```await``` or make use of ```onChange``` listeners!**  
 
-To reset all stored values back to defaults:
+To reset values back to defaults:
 ```js
-async Varstor.resetAll () => Varstor
+async Varstor.reset(Keys []) => Varstor
 ```
+Where:  
+```Keys[]``` (optional) - array of keys to return to default values. If omitted all values will be returned to defaults.  
+
+
+## Listening ```.onChange()```/```.removeListener()``` <a name="listening"></a>
 
 To listen and react to state changes:
 ```js
-Varstor.onChange (Keys[], ChangeCallback(newValue, allValues, previousValue) => void) => Varstor
+Varstor.onChange(
+  Keys[],
+  ChangeCallback(ChangedKeys [], allValues {}, PreviousValues {}) => void
+) => Varstor
 ```
 Where:  
-```Keys``` - array of keys of the state in the current namespace that you want to listen to  
+```Keys[]``` (optional) - array of keys of the state in the current namespace that you want to listen to. If omitted, ```ChangeCallback``` will run on any value change in the namespace.  
 ```ChangeCallback``` - function to run when a change happens
 
 To remove the listener:
 ```js
-Varstor.removeListener(Keys, ChangeCallback) => Varstor
+Varstor.removeListener(
+  Keys[],
+  ChangeCallback(ChangedKeys [], allValues {}, PreviousValues {}) => void
+) => Varstor
 ```
 the same parameter usage. 
-  
-  
-  
 
 
-Methods ```.set()```, ```.resetAll()```, ```onChange```, and ```removeListener``` all return a new instance of ```Varstor``` with the same namespace, so command chaining is possible.  
-Method ```.get(() => {})``` may return a new ```Varstor``` instance.
 
-## Namespacing
+## Data encapsulation ```.actions()``` <a name="actions"></a>
+Hide away all public data access and mutation into dedicated functions with the help of ```IStateAction```s.  
+```js
+Varstor.actions({
+  KeysActions {
+    key1: IStateAction1 (Varstor, ...arguments[]) => void
+    key2: IStateAction2 (Varstor, ...arguments[]) => void
+    ...
+  }
+})
+```
+```IStateAction``` function type binds ```Varstor``` instance as the first argument, followed by all other ```arguments``` provided by the user at the time of the call.  
+These actions reside in the same scope as regular variables. So you can access them by the ```key```s defined in ```KeysActions``` object through the ```.get()``` method.
+```js
+Varstor.add({ x: 1 });
+
+Varstor.actions({
+  changeX: (varstor, newX) => varstor.set({ x: newX }), 
+}),
+
+Varstor.get().changeX(10);
+```
+  
+## Namespacing ```.get(Namespace)``` <a name="namespacing"></a>
 To avoid name collisions, put keys with the same name in different namespaces. You can create a new or get an existing namespace with
 ```js
-Varstor.get(String Namespace) => Varstor
+Varstor.get(Namespace string) => Varstor
 ```
-which will return a new instance of ```Varstor``` with the specified ```Namespace```.
+which will return a new instance of ```Varstor``` with the specified ```Namespace```.  
+  
+
+## Method chaining <a name="chaining"></a>
+Methods ```.add```, ```.addPersistent```, ```.set()```, ```.reset()```, ```onChange```, and ```removeListener``` all return a new instance of ```Varstor``` with the same namespace, so method chaining is possible.  
 
-## Shortcuts
-The library object itself can be called with different types of arguments, which will mirror almost all of its API.
+
+## Shortcuts <a name="shortcuts"></a>
+The library/namespace object itself can be called with different types of arguments, which will mirror almost all of its API.
 ```js
 Varstor() -> Varstor.get()
 Varstor(String namespace) -> Varstor.get(namespace)
-Varstor(() => {}) -> Varstor.get(() => {})
 Varstor({ key: value }) -> Varstor.set({ key: value })
-Varstor({}) -> Varstor.resetAll()
 Varstor([], () => {}) -> Varstor.onChange([], () => {})
 ```
 
-## StateAccessor
-```StateAccessor``` is a way to manipulate each piece of state individually. It's a function that can be called itself, but also an object with a set of methods:    
+## Example <a name="example"></a>
 ```js
-.()
-.set(value)
-.reset()
-.onChange(Callback)
-.removeListener(Callback)
-```
-Where:  
-```()``` (call the object itself) - returns the value  
-```.set(value)``` - sets the value  
-```.reset()``` - resets the value  
-```.onChange(Callback)``` - adds the listener  
-```.removeListener(Callback)``` - removes the listener  
+function onChange(changes, values, data) {
+  console.log("onChange", changes, values, data);
+}
+
+await Varstor.add({
+  a: 10,
+  b: 20,
+  c: (a, b) => a + b,
+});
+
+await Varstor.addPersistent({
+  d: 40,
+});
+
+console.log(Varstor.get()); // {a: 10, b: 20, c: 30, d: 40}
+
+Varstor.onChange(["a", "b", "c", "d"], onChange);
+Varstor.onChange(onChange);
+
+await Varstor.set({ a: 20, b: 88, d: 60 });
+console.log(Varstor.get()); // {a: 20, b: 88, c: 108, d: 60}
+
+await Varstor.reset(["b"]);
+console.log(Varstor.get()); // {a: 20, b: 20, c: 40, d: 60}
+
+await Varstor.reset();
+console.log(Varstor.get()); // {a: 10, b: 20, c: 30, d: 40}
+
+Varstor.removeListener(["a", "b", "c", "d"], onChange);
+Varstor.removeListener(onChange);
+
+const newNamespace = Varstor("new namespace");
+
+await newNamespace.add({
+  x: 1,
+  y: 2,
+  z: 3,
+});
+
+newNamespace.actions({
+  logValues: ({ get }) => {
+    const { x, y, z } = get();
+    console.log(`x: ${x}, y: ${y}, z: ${z}`);
+  },
+  multiplyX: ({ get, set }, num) => set({ x: get().x * num }),
+  incrementY: ({ get, set }) => set({ y: get().y + 1 }),
+})
+
+const { logValues, multiplyX, incrementY } = newNamespace.get();
+
+logValues(); // x: 1, y: 2, z: 3
+multiplyX(10)
+incrementY();
+logValues(); // x: 10, y: 3, z: 3
+
+await newNamespace({ z: 110 });
+
+console.log(Varstor("new namespace").get()); // {x: 10, y: 3, z: 110, logValues: ƒ, multiplyX: ƒ, …}
+```