Skip to content
This repository was archived by the owner on Feb 15, 2025. It is now read-only.

Commit 1505f93

Browse files
bennobuilderbennobuilder
authored
Merge pull request #87 from agile-ts/develop
Added Proxy docs
2 parents d35c83d + cea26e9 commit 1505f93

30 files changed

+1824
-2089
lines changed

‎docs/Interfaces.md

Lines changed: 169 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ slug: /interfaces
1010
**This Section might be useless to you without any context.**
1111
As the name suggests, it's all about typescript interfaces of AgileTs.
1212
These interfaces are outsourced for a better overview, maintainability, and reusability.
13-
You might get redirected to parts of the Interface Section from other documentations to learn more about specific Interfaces.
13+
You might get redirected to parts of the Interface Section from other documentation to learn more about specific Interfaces.
1414

1515
:::
1616

@@ -297,6 +297,7 @@ export interface RuntimeJobConfigInterface {
297297
background?: boolean;
298298
sideEffects?: SideEffectConfigInterface;
299299
force?: boolean;
300+
numberOfTriesToUpdate?: number | null;
300301
}
301302
```
302303

@@ -358,6 +359,19 @@ MY_STATE.set('myValue', { force: true });
358359
|--------------------------|-----------|----------|
359360
| `boolean` | false | No |
360361

362+
#### `numberOfTriesToUpdate`
363+
364+
How often the runtime should try to update not ready SubscriptionContainers of the Job.
365+
If the update tries count exceeds the `numberOfTriesToUpdate` count,
366+
the Job will be entirely removed from the runtime.
367+
This has the advantage that an overflow of the runtime is avoided.
368+
If `numberOfTriesToUpdate` is `null` the runtime tries to update the not ready Job subscriptionContainers
369+
until they are ready.
370+
371+
| Type | Default | Required |
372+
|--------------------------|-----------|----------|
373+
| `number \| null` | 3 | No |
374+
361375

362376

363377
<br/>
@@ -1103,4 +1117,157 @@ MY_COMPUTED.deps; // // Returns '[Observer(MY_LOCATION)]'
11031117

11041118
| Type | Default | Required |
11051119
|--------------------------|-----------|----------|
1106-
| `boolean` | true | No |
1120+
| `boolean` | true | No |
1121+
1122+
1123+
1124+
<br/>
1125+
1126+
---
1127+
1128+
<br/>
1129+
1130+
1131+
1132+
## `AgileHookConfigInterface`
1133+
1134+
The `AgileHookConfigInterface` is used as configuration object in functions like [`useAgile()`](./packages/react/features/Hooks.md#useagile).
1135+
Here is a Typescript Interface for quick reference. However,
1136+
each property is explained in more detail below.
1137+
```ts
1138+
interface AgileHookConfigInterface {
1139+
key?: SubscriptionContainerKeyType;
1140+
agileInstance?: Agile;
1141+
proxyBased?: boolean;
1142+
}
1143+
```
1144+
1145+
<br/>
1146+
1147+
#### `key`
1148+
1149+
The `key/name` of the [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) that is created and added to the Observers.
1150+
```ts
1151+
useAgile(MY_STATE, {key: 'jeff'});
1152+
```
1153+
Such key can be very useful during debug sessions
1154+
in order to analyse when which SubscriptionContainer triggered a rerender on a Component.
1155+
```ts
1156+
// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
1157+
// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]
1158+
// Agile Debug: Unregistered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
1159+
```
1160+
1161+
| Type | Default | Required |
1162+
|--------------------------|-----------|----------|
1163+
| `string \| number` | undefined | No |
1164+
1165+
<br/>
1166+
1167+
#### `agileInstance`
1168+
1169+
The [Agile Instance](./packages/core/features/agile-instance/Introduction.md) to which the created [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) belongs to.
1170+
However, since each Observer has an instance to the Agile Instance, `useAgile()` can automatically derive the Agile Instance from that.
1171+
1172+
| Type | Default | Required |
1173+
|---------------------------------------------------------------------------------|-----------|----------|
1174+
| [Agile Instance](./packages/core/features/agile-instance/Introduction.md) | undefined | No |
1175+
1176+
<br/>
1177+
1178+
#### `proxyBased`
1179+
1180+
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.
1181+
Through this Proxy, AgileTs is able to track accessed properties of the returned object/s
1182+
and can construct a path to these.
1183+
The paths allow AgileTs to rerender the Component more efficiently
1184+
by only causing a rerender when an actual accessed property value mutates.
1185+
Normally, the Component is always rerendered on a State change,
1186+
regardless of whether the changed property value is accessed in the Component.
1187+
This is totally fine if the value is primitive or the whole object is displayed.
1188+
However, as soon as we display only a tiny part of the bound State value object,
1189+
the proxy feature can reduce the rerender count.
1190+
```ts
1191+
const MY_STATE = App.createState({name: 'frank', age: 10})
1192+
1193+
// -- MyComponent.js ----------------------------------------
1194+
1195+
// Bind State to 'MyComponent.js'
1196+
const myState = useAgile(MY_STATE, {proxyBased: true});
1197+
1198+
return <p>{myState.name}</p>
1199+
1200+
// -- core.js ----------------------------------------------
1201+
1202+
// Causes rerender on 'MyComponent.js',
1203+
// since the '.name' property got accessed
1204+
MY_STATE.patch({name: 'jeff'});
1205+
1206+
// Doesn't cause rerender on 'MyComponent.js',
1207+
// since the '.age' property didn't got accessed
1208+
MY_STATE.patch({age: 20});
1209+
```
1210+
To avoid having to set the `proxyBased` configuration to `true` every time we use the proxy functionality,
1211+
we can use the [`useProxy()`](./packages/react/features/Hooks.md#useproxy) hook which does that part for us.
1212+
```ts
1213+
useProxy(MY_STATE);
1214+
// equal to
1215+
useAgile(MY_STATE, {proxyBased: true});
1216+
```
1217+
1218+
| Type | Default | Required |
1219+
|--------------------------|-----------|----------|
1220+
| `string \| number` | undefined | No |
1221+
1222+
1223+
1224+
<br/>
1225+
1226+
---
1227+
1228+
<br/>
1229+
1230+
1231+
1232+
## `ProxyHookConfigInterface`
1233+
1234+
The `ProxyHookConfigInterface` is used as configuration object in functions like [`useProxy()`](./packages/react/features/Hooks.md#useproxy).
1235+
Here is a Typescript Interface for quick reference. However,
1236+
each property is explained in more detail below.
1237+
```ts
1238+
interface ProxyHookConfigInterface {
1239+
key?: SubscriptionContainerKeyType;
1240+
agileInstance?: Agile;
1241+
}
1242+
```
1243+
1244+
<br/>
1245+
1246+
#### `key`
1247+
1248+
The `key/name` of the [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) that is created and added to the Observers.
1249+
```ts
1250+
useProxy(MY_STATE, {key: 'jeff'});
1251+
```
1252+
Such key can be very useful during debug sessions
1253+
in order to analyse when which SubscriptionContainer triggered a rerender on a Component.
1254+
```ts
1255+
// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
1256+
// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]
1257+
// Agile Debug: Unregistered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
1258+
```
1259+
1260+
| Type | Default | Required |
1261+
|--------------------------|-----------|----------|
1262+
| `string \| number` | undefined | No |
1263+
1264+
<br/>
1265+
1266+
#### `agileInstance`
1267+
1268+
The [Agile Instance](./packages/core/features/agile-instance/Introduction.md) to which the created [SubscriptionContainer](./packages/core/features/integration/Introduction.md#-subscriptions) belongs to.
1269+
However, since each Observer has an instance to the Agile Instance, `useProxy()` can automatically derive the Agile Instance from that.
1270+
1271+
| Type | Default | Required |
1272+
|---------------------------------------------------------------------------------|-----------|----------|
1273+
| [Agile Instance](./packages/core/features/agile-instance/Introduction.md) | undefined | No |

‎docs/examples/Indroduction.md renamed to ‎docs/examples/Introduction.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,5 +10,5 @@ That's why we've put together a few examples for you.
1010
If that's not enough, you can find even more examples in the [AgileTs repository](https://github.com/agile-ts/agile/tree/master/examples).
1111

1212
## 🚀 Quick Links
13-
- [React](./react/All.mdx)
14-
- [React-Native](./react-native/All.mdx)
13+
- [React](./react/Introduction.md)
14+
- [React-Native](./react-native/Introduction.md)

‎docs/examples/react-native/Introduction.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
id: introduction
3+
title: React-Native Examples
4+
sidebar_label: React-Native
5+
slug: /examples/react-native
6+
---
7+
8+
## 🤠 Get Started
9+
- [First State](./react-native/first-state)

‎docs/examples/react-native/examples/FirstState.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: first-state
3+
title: First State
4+
sidebar_label: First State
5+
slug: /examples/react-native/first-state
6+
---
7+
8+
import {ExpoSandBoxEmbed} from "../../../../src/components/docs/ExpoSandBoxEmbed";
9+
10+
<ExpoSandBoxEmbed uri={'@bennodev/agilets-first-state'} />

‎docs/examples/react/All.mdx

Lines changed: 0 additions & 51 deletions
This file was deleted.

‎docs/examples/react/Introduction.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
id: introduction
3+
title: React Examples
4+
sidebar_label: React
5+
slug: /examples/react
6+
---
7+
8+
## 🤠 Get Started
9+
- [First State](./react/first-state)
10+
- [First State [Class Component]](./react/class/first-state)
11+
- [First Collection](./react/first-collection)
12+
- [First Computed](./react/first-computed)
13+
- [Multieditor](./react/multieditor)
14+
- [useProxy](./react/simple-useproxy)
15+
16+
## 👾 Performance
17+
- [Large State](./react/large-state)
18+
- [Frequent Updates](./react/frequent-updates)
19+
20+
You can get an overview of all performance examples in [this](https://github.com/agile-ts/performance-compare) repository.
21+
22+
## 😎 Medium
23+
- [Simple Todo List](./react/simple-todo-list)
24+
25+
## 🤓 Enterprise
26+
- coming soon

‎docs/examples/react/examples/FirstCollection.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: first-collection
3+
title: First Collection
4+
sidebar_label: First Collection
5+
slug: /examples/react/first-collection
6+
---
7+
8+
import {CodeSandBoxEmbed} from "../../../../src/components/docs/CodeSandBoxEmbed";
9+
10+
<CodeSandBoxEmbed uri={'agilets-first-collection-uyi9g'} />

‎docs/examples/react/examples/FirstComputed.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: first-computed
3+
title: First Computed
4+
sidebar_label: First Computed
5+
slug: /examples/react/first-computed
6+
---
7+
8+
import {CodeSandBoxEmbed} from "../../../../src/components/docs/CodeSandBoxEmbed";
9+
10+
<CodeSandBoxEmbed uri={'agilets-first-collection-uyi9g'} />

‎docs/examples/react/examples/FirstState.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: first-state
3+
title: First State
4+
sidebar_label: First State
5+
slug: /examples/react/first-state
6+
---
7+
8+
import {CodeSandBoxEmbed} from "../../../../src/components/docs/CodeSandBoxEmbed";
9+
10+
<CodeSandBoxEmbed uri={'agilets-first-state-f12cz'} />

‎docs/examples/react/examples/FirstState_Class.mdx

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
id: first-state-class
3+
title: First State
4+
sidebar_label: First State
5+
slug: /examples/react/class/first-state
6+
---
7+
8+
import {CodeSandBoxEmbed} from "../../../../src/components/docs/CodeSandBoxEmbed";
9+
10+
<CodeSandBoxEmbed uri={'agilets-first-state-with-hoc-1qdew'} />

0 commit comments

Comments
 (0)