added basic useProxy docs

Author: bennobuilder

docs/Interfaces.md

@@ -1118,3 +1118,156 @@ MY_COMPUTED.deps; // // Returns '[Observer(MY_LOCATION)]'
 | Type                     | Default   | Required |
 |--------------------------|-----------|----------|
 | `boolean`                | true      | No       |
+
+
+
+<br/>
+
+---
+
+<br/>
+
+
+
+## `AgileHookConfigInterface`
+
+The `AgileHookConfigInterface` is used as configuration object in functions like [`useAgile()`](./packages/react/features/Hooks.md#useagile).
+Here is a Typescript Interface for quick reference. However,
+each property is explained in more detail below.
+```ts
+interface AgileHookConfigInterface {
+  key?: SubscriptionContainerKeyType;
+  agileInstance?: Agile;
+  proxyBased?: boolean;
+}
+```
+
+<br/>
+
+#### `key`
+
+The `key/name` of the [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) that is created and added to the Observers.
+```ts
+useAgile(MY_STATE, {key: 'jeff'});
+```
+Such key can be very useful during debug sessions
+in order to analyse when which SubscriptionContainer triggered a rerender on the Component.
+```ts
+// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
+// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]
+// Agile Debug: Unregistered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
+```
+
+| Type                     | Default   | Required |
+|--------------------------|-----------|----------|
+| `string \| number`       | undefined | No       |
+
+<br/>
+
+#### `agileInstance`
+
+The [Agile Instance](./packages/core/features/agile-instance/Introduction.md) the created [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) belongs to.
+However, since each Observer has an instance to the Agile Instance, `useAgile()` can automatically derive the Agile Instance from that.
+
+| Type                                                                            | Default   | Required |
+|---------------------------------------------------------------------------------|-----------|----------|
+| [Agile Instance](./packages/core/features/agile-instance/Introduction.md)       | undefined | No       |
+
+<br/>
+
+#### `proxyBased`
+
+If the `useAgile()` hook should wrap a [Proxy()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) around its return value/s.
+Through this Proxy, AgileTs is able to track accessed properties in the returned object/s
+and can construct a path to these. 
+The paths allow AgileTs to rerender the Component more efficiently,
+by only causing a rerender when an actual accessed property value mutates.
+Normally, the Component is always rerendered on a State change,
+regardless of whether the property value is accessed in the Component.
+This is totally fine if the value is primitive, or the whole object is displayed.
+However, as soon as we display only a small part of the bound State value object,
+the proxy feature might improve the performance.
+```ts
+const MY_STATE = App.createState({name: 'frank', age: 10})
+
+// -- MyComponent.js ----------------------------------------
+
+// Bind State to 'MyComponent.js'
+const myState = useAgile(MY_STATE, {proxyBased: true});
+
+return <p>{myState.name}</p>
+
+// -- core.js  ----------------------------------------------
+
+// Cause rerender on 'MyComponent.js', 
+// since the .name property got accessed
+MY_STATE.patch({name: 'jeff'});
+
+// Doesn't cause rerender on 'MyComponent.js', 
+// since the .age property didn't got accessed
+MY_STATE.patch({age: 20});
+```
+To avoid having to set the `proxyBased` configuration to `true` every time we use the proxy functionality,
+we can use the [`useProxy()`](./packages/react/features/Hooks.md#useproxy) hook which does that part for us.
+```ts
+useProxy(MY_STATE);
+// equal to
+useAgile(MY_STATE, {proxyBased: true});
+```
+
+| Type                     | Default   | Required |
+|--------------------------|-----------|----------|
+| `string \| number`       | undefined | No       |
+
+
+
+<br/>
+
+---
+
+<br/>
+
+
+
+## `ProxyHookConfigInterface`
+
+The `ProxyHookConfigInterface` is used as configuration object in functions like [`useProxy()`](./packages/react/features/Hooks.md#useproxy).
+Here is a Typescript Interface for quick reference. However,
+each property is explained in more detail below.
+```ts
+interface ProxyHookConfigInterface {
+  key?: SubscriptionContainerKeyType;
+  agileInstance?: Agile;
+}
+```
+
+<br/>
+
+#### `key`
+
+The `key/name` of the [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) that is created and added to the Observers.
+```ts
+useProxy(MY_STATE, {key: 'jeff'});
+```
+Such key can be very useful during debug sessions
+in order to analyse when which SubscriptionContainer triggered a rerender on the Component.
+```ts
+// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
+// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]
+// Agile Debug: Unregistered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
+```
+
+| Type                     | Default   | Required |
+|--------------------------|-----------|----------|
+| `string \| number`       | undefined | No       |
+
+<br/>
+
+#### `agileInstance`
+
+The [Agile Instance](./packages/core/features/agile-instance/Introduction.md) the created [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) belongs to.
+However, since each Observer has an instance to the Agile Instance, `useProxy()` can automatically derive the Agile Instance from that.
+
+| Type                                                                            | Default   | Required |
+|---------------------------------------------------------------------------------|-----------|----------|
+| [Agile Instance](./packages/core/features/agile-instance/Introduction.md)       | undefined | No       |

docs/examples/react/Introduction.md

@@ -15,6 +15,7 @@ slug: /examples/react
 
 ## 👾 Performance
 - [Large State](./react/large-state)
+- [Frequent Updates](./react/frequent-updates)
 
 You can get an overview of all performance examples in [this](https://github.com/agile-ts/performance-compare) repo.
 

docs/examples/react/examples/FrequentUpdates.mdx

@@ -0,0 +1,12 @@
+---
+id: frequent-updates
+title: Frequent Updates
+sidebar_label: Frequent Updates
+slug: /examples/react/frequent-updates
+---
+
+import {CodeSandBoxEmbed} from "../../../../src/components/docs/CodeSandBoxEmbed";
+
+<CodeSandBoxEmbed uri={'agilets-frequent-updates-5tprm'} />
+
+

docs/main/Introduction.md

@@ -90,7 +90,7 @@ const App = new Agile();
 const MY_FIRST_STATE = App.createState("Hello Friend!");
 
 
-// -- myComponent.whatever ------------------------------------------
+// -- MyComponent.js ------------------------------------------
 
 // 3️⃣ Bind initialized State to desired UI-Component
 // And wolla, it's reactive. Everytime the State mutates the Component rerenders

docs/packages/react/Introduction.md

@@ -36,7 +36,7 @@ Therefore, we have created alternatives for Class Components in order to offer t
 In Functional Components we recommend using AgileTs Hooks like [`useAgile()`](./features/Hooks.md#useagile).
 The `useAgile()` Hook binds [Agile Sub Instances](../../main/Introduction.md#agile-sub-instance) (like States or Collections) to React Components.
 ```ts
-// -- myComponent.jsx ------------------------------------------
+// -- MyComponent.jsx ------------------------------------------
 
 // Binds MY_FIRST_STATE to myComponent
 const myFirstState = useAgile(MY_FIRST_STATE);
@@ -50,7 +50,7 @@ For Class Components, we provide the `AgileHOC`.
 The `AgileHOC` is a Higher Order Component that is wrapped around a React Component.
 It takes care of binding [Agile Sub Instances](../../main/Introduction.md#agile-sub-instance) (like States or Collections) to the wrapped React Component.
 ```ts
-// -- myComponent.jsx ------------------------------------------
+// -- MyComponent.jsx ------------------------------------------
 
 // Binds MY_FIRST_STATE to myComponent
 export default AgileHOC(myComponent, [MY_FIRST_STATE]);
@@ -63,4 +63,4 @@ checkout the [AgileHOC documentation](./features/AgileHoc.md).
 - [React Hook](./features/Hooks.md)
   - [useAgile](./features/Hooks.md#useagile)
   - [useWatcher](./features/Hooks.md#usewatcher)
-- [AgileHOC](./features/AgileHoc.md)
+- [AgileHOC](./features/AgileHoc.md)

docs/packages/react/features/Hooks.md

@@ -25,7 +25,7 @@ and not the State Instance itself.
 ```ts {5}
 const MY_STATE = App.createState('jeff');
 
-// myComponent.jsx
+// MyComponent.jsx
 
 const myState = useAgile(MY_STATE);
 console.log(myState); // Returns 'jeff'
@@ -41,7 +41,7 @@ In which case it returns an array of State `values` that can be destructured.
 const MY_STATE = App.createState('jeff');
 const MY_STATE_2 = App.createState('frank');
 
-// myComponent.jsx
+// MyComponent.jsx
 
 const [myState, myState2] = useAgile([MY_STATE, MY_STATE_2]);
 console.log(myState); // Returns 'jeff'
@@ -66,7 +66,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
   ```ts {5}
   const MY_STATE = App.createState('jeff');
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const myState = useAgile(MY_STATE);
   console.log(myState); // Returns 'jeff'
@@ -75,7 +75,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
   ```ts {5}
   const MY_COMPUTED = App.createComputed(() => 'hello there');
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const myComputed = useAgile(MY_COMPUTED);
   console.log(myComputed); // Returns 'hello there'
@@ -90,7 +90,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
      initialData: [{id: 1, name: 'a'}, {id: 2, name: 'b'}, {id: 3, name: 'c'}]  
   });
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const myCollection = useAgile(MY_COLLECTION);
   console.log(myCollection); // Returns (see below)
@@ -103,7 +103,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
   });
   const MY_GROUP = MY_COLLECTION.createGroup('myGroup', [3, 1]);
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const myGroup = useAgile(MY_GROUP);
   console.log(myGroup); // Returns '[{id: 3, name: 'c'}, {id: 1, name: 'a'}]'
@@ -115,7 +115,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
   });
   const MY_SELECTOR = MY_COLLECTION.select(2);
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const mySelector = useAgile(MY_SELECTOR);
   console.log(mySelector); // Returns '{id: 2, name: 'b'}'
@@ -127,7 +127,7 @@ Instances that can be bound to a React Component via the `useAgile()` Hook:
   });
   const MY_ITEM = MY_COLLECTION.getItem(3);
 
-  // myComponent.jsx
+  // MyComponent.jsx
 
   const myItem = useAgile(MY_ITEM);
   console.log(myItem); // Returns '{id: 3, name: 'c'}'
@@ -186,7 +186,7 @@ type SubscribableAgileInstancesType = State | Collection | Observer | undefined;
 ```ts {5}
 const MY_STATE = App.createState('jeff');
 
-// myComponent.jsx
+// MyComponent.jsx
 
 const myState = useAgile(MY_STATE);
 console.log(myState); // Returns 'jeff'
@@ -196,7 +196,7 @@ When passing multiple Agile Sub Instances, an array of `outputs` matching the pa
 const MY_STATE = App.createState('jeff');
 const MY_STATE_2 = App.createState('frank');
 
-// myComponent.jsx
+// MyComponent.jsx
 
 const [myState, myState2] = useAgile([MY_STATE, MY_STATE_2]);
 console.log(myState); // Returns 'jeff'
@@ -215,15 +215,45 @@ console.log(myState2); // Returns 'frank'
 
 ## `useProxy()`
 
-Basically `useProxy()` does the same as [`useAgile()`](#useagile)
-but it differs in one key area.
-It wraps a proxy around its return value, 
-which has no limitation for the end user, but it allows AgileTs to track the used properties.
-With this information it is possible to only rerender the Component,
-when a used property mutates. In `useAgile()` it rerenders the Component
-whenever anything in the State changes, no matter it is displayed or not.
-Be aware that this is only useful if you pass an array or object State
-because it wouldn't make sense to track any primitive value.
+Basically `useProxy()` does the same as [`useAgile()`](#useagile),
+however it differs in one key area.
+It wraps a [Proxy()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) around its return value/s.
+Through this Proxy, AgileTs is able to track accessed properties in the returned object/s
+and can construct a path to these.
+The paths allow AgileTs to rerender the Component more efficiently,
+by only causing a rerender when an actual accessed property value mutates.
+With `useAgile()`, the Component is always rerendered on a State change,
+regardless of whether the property value is accessed in the Component.
+This is totally fine if the value is primitive, or the whole object is displayed.
+However, as soon as we display only a small part of the bound State value object,
+the `useProxy()` hook might improve the performance.
+
+### 🗂 Array
+`useProxy()` also supports **arrays** of State Instances.
+```ts
+const [myCoolState1, myCoolState2] = useAgile([MY_COOL_STATE1, MY_COOL_STATE2]);
+```
+In which case it returns an array of State `values` that can be destructured.
+```ts {6}
+const MY_STATE = App.createState({name: 'jeff', age: 10});
+const MY_STATE_2 = App.createState({size: 100, weight: 200});
+
+// MyComponent.jsx
+
+const [myState, myState2] = useProxy([MY_STATE, MY_STATE_2]);
+console.log(myState); // Returns '{name: 'jeff', age: 10}'
+console.log(myState2); // Returns '{size: 100, weight: 200}'
+```
+
+### 🏷 Subscribable Instances
+We are not limited to States.
+We can bind any [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance) that owns
+an `Observer` to React Components.
+```ts
+  const [myCollection, myGroup, myState] = useProxy([MY_COLLECTION, MY_GROUP, MY_STATE]);
+```
+However, the [Proxy()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) will only be wrapped
+around objects and arrays. The other instances are treated as in [useAgile()](#useagile).
 
 ### 🔴 Example
 
@@ -268,6 +298,41 @@ render(<RandomComponent/>);
 
 The `useProxy()` Hook is almost 100% typesafe.
 
+### 📭 Props
+
+| Prop              | Type                                                                         | Description                                                                                                  | Required    | 
+| ----------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------|
+| `deps`            | Array<SubscribableAgileInstancesType\> \| SubscribableAgileInstancesType     | Agile Sub Instances that are bound to the Component in which the useAgile Hook is located                    | Yes         | 
+| `config`          | [ProxyHookConfigInterface](../../../Interfaces.md#proxyhookconfiginterface)  | Configuration                                                                                                | No          |
+
+#### SubscribableAgileInstancesType
+```ts
+type SubscribableAgileInstancesType = State | Collection | Observer | undefined;
+```
+
+### 📄 Return
+
+`useProxy()` returns the current `output` of the passed [Agile Sub Instance](../../../main/Introduction.md#agile-sub-instance).
+```ts {5}
+const MY_STATE = App.createState({name: 'jeff', age: 10});
+  
+// MyComponent.jsx
+
+const myState = useAgile(MY_STATE);
+console.log(myState); // Returns '{name: 'jeff', age: 10}'
+```
+When passing multiple Agile Sub Instances, an array of `outputs` matching the passed Instances is returned.
+```ts {6}
+const MY_STATE = App.createState({name: 'jeff', age: 10});
+const MY_STATE_2 = App.createState('frank');
+
+// MyComponent.jsx
+
+const [myState, myState2] = useAgile([MY_STATE, MY_STATE_2]);
+console.log(myState); // Returns '{name: 'jeff', age: 10}'
+console.log(myState2); // Returns 'frank'
+```
+
 
 
 <br />