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

Commit 52d4b02

Browse files
committed
added getDefaultGroup() and move() docs
1 parent 40f07ed commit 52d4b02

File tree

5 files changed

+127
-51
lines changed

5 files changed

+127
-51
lines changed

docs/Interfaces.md

Lines changed: 15 additions & 15 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

@@ -362,7 +362,7 @@ MY_STATE.set('myValue', { force: true });
362362
#### `numberOfTriesToUpdate`
363363

364364
How often the runtime should try to update not ready SubscriptionContainers of the Job.
365-
If the update tries count exceeds the `numberOfTriesToUpdate` count,
365+
If the update tries count exceeds the `numberOfTriesToUpdate` count,
366366
the Job will be entirely removed from the runtime.
367367
This has the advantage that an overflow of the runtime is avoided.
368368
If `numberOfTriesToUpdate` is `null` the runtime tries to update the not ready Job subscriptionContainers
@@ -1151,7 +1151,7 @@ The `key/name` of the [SubscriptionContainer](./packages/core/features/integrati
11511151
useAgile(MY_STATE, {key: 'jeff'});
11521152
```
11531153
Such key can be very useful during debug sessions
1154-
in order to analyse when which SubscriptionContainer triggered a rerender on the Component.
1154+
in order to analyse when which SubscriptionContainer triggered a rerender on a Component.
11551155
```ts
11561156
// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
11571157
// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]
@@ -1178,15 +1178,15 @@ However, since each Observer has an instance to the Agile Instance, `useAgile()`
11781178
#### `proxyBased`
11791179

11801180
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 in the returned object/s
1182-
and can construct a path to these.
1183-
The paths allow AgileTs to rerender the Component more efficiently,
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
11841184
by only causing a rerender when an actual accessed property value mutates.
11851185
Normally, the Component is always rerendered on a State change,
1186-
regardless of whether the 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 small part of the bound State value object,
1189-
the proxy feature might improve the performance.
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.
11901190
```ts
11911191
const MY_STATE = App.createState({name: 'frank', age: 10})
11921192

@@ -1200,11 +1200,11 @@ return <p>{myState.name}</p>
12001200
// -- core.js ----------------------------------------------
12011201

12021202
// Cause rerender on 'MyComponent.js',
1203-
// since the .name property got accessed
1203+
// since the '.name' property got accessed
12041204
MY_STATE.patch({name: 'jeff'});
12051205

12061206
// Doesn't cause rerender on 'MyComponent.js',
1207-
// since the .age property didn't got accessed
1207+
// since the '.age' property didn't got accessed
12081208
MY_STATE.patch({age: 20});
12091209
```
12101210
To avoid having to set the `proxyBased` configuration to `true` every time we use the proxy functionality,
@@ -1236,8 +1236,8 @@ Here is a Typescript Interface for quick reference. However,
12361236
each property is explained in more detail below.
12371237
```ts
12381238
interface ProxyHookConfigInterface {
1239-
key?: SubscriptionContainerKeyType;
1240-
agileInstance?: Agile;
1239+
key?: SubscriptionContainerKeyType;
1240+
agileInstance?: Agile;
12411241
}
12421242
```
12431243

@@ -1250,7 +1250,7 @@ The `key/name` of the [SubscriptionContainer](./packages/core/features/integrati
12501250
useProxy(MY_STATE, {key: 'jeff'});
12511251
```
12521252
Such key can be very useful during debug sessions
1253-
in order to analyse when which SubscriptionContainer triggered a rerender on the Component.
1253+
in order to analyse when which SubscriptionContainer triggered a rerender on a Component.
12541254
```ts
12551255
// Agile Debug: Registered Callback/Component based Subscription 'jeff', SubscriptionContainer('jeff')
12561256
// Agile Debug: Updated/Rerendered Subscriptions, [SubscriptionContainer('jeff'), ..]

docs/main/Introduction.md

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ The benefit of keeping logic separate to UI-Components is to make your code more
7171

7272
Learn the powerful tools of AgileTs in a short amount of time. An excellent place to start are
7373
our [Quick Start](./Installation.md) Guides, or if you don't like to follow any tutorials,
74-
you can jump straight into our [Example](../examples/Indroduction.md) Section.
74+
you can jump straight into our [Example](../examples/Introduction.md) Section.
7575

7676

7777
## ⏳ Quick Example
@@ -110,11 +110,11 @@ It's only one click away. Just select your preferred Framework below.
110110

111111
More examples can be found in the [Example](../examples/Indroduction.md) Section.
112112

113-
## 👨‍💻 When use AgileTs
113+
## 👨‍💻 When using AgileTs
114114

115115
AgileTs is thought to handle the States of the business logic and logic in general that isn't explicitly bound to a Component.
116116
This includes, for example, `server caching States` like the logged-in user. AgileTs wasn't built to handle UI States like `isModalOpen`.
117-
Therefore, AgileTs should be used as a friend and helper to outsource all business logic from your UI-Components.
117+
Therefore, AgileTs should be used as a friend and helper to outsource all business logic from UI-Components.
118118

119119
## 🟦 Typescript
120120

@@ -126,8 +126,8 @@ We have a variety of resources available to help you learn AgileTs. An excellent
126126
our [Quick Start](./Installation.md) Guides, where you learn the basics about how to use AgileTs in a specific
127127
Framework. After knowing the ground concept of AgileTs, we recommend checking out the [Style Guides](./StyleGuide.md).
128128
The Style Guides will help you to get some inspiration on structuring a scalable application using AgileTs. Now you
129-
are ready to use AgileTs wherever you want. In case you need some more information about some functionalities of AgileTs,
130-
use the search bar in the top right corner. In case you have any further questions, don't hesitate to join our [Community Discord](https://discord.gg/T9GzreAwPH).
129+
are ready to use AgileTs wherever you want. If you need some more information about some functionalities of AgileTs,
130+
use the search bar in the top right corner. And in case you have any further questions, don't hesitate to join our [Community Discord](https://discord.gg/T9GzreAwPH).
131131

132132
## 👮 Data Flow
133133

@@ -137,9 +137,9 @@ use the search bar in the top right corner. In case you have any further questio
137137

138138
In State-Management, the Data-Flow more or less starts and ends in the UI-Component.
139139
For example, if we click a Button, we trigger an action that resolves in a UI change.
140-
By clicking a Theme Button, we start an action that changes the color theme of the current site.
140+
So by clicking a Theme Button, we start an action that changes the color theme of the current site.
141141
In order that this color change can visibly happen, the Component has to rerender.
142-
For that, we need to subscribe/bind the State (`THEME_STATE`) to the UI-Component,
142+
For this, we need to subscribe/bind the State (`THEME_STATE`) to the UI-Component,
143143
with, for instance, the `useAgile()` hook.
144144
Such subscription is essential to rerender the Component whenever the subscribed State mutates.
145145
```ts
@@ -155,7 +155,7 @@ onClick={() => {
155155
The action, triggered by the Theme Button,
156156
then mutates the actual `THEME_STATE` and might do some side calculations.
157157
We can also omit this step and edit the State directly in the UI-Component.
158-
Everyone as he likes. However, I personally prefer separating UI-Component logic from global/business logic.
158+
Everyone as he likes. However, I prefer separating UI-Component logic from global/business logic.
159159
```ts
160160
const toggleTheme = () => {
161161
THEME_STATE.invert();
@@ -178,7 +178,7 @@ THEME_STATE.ingestValue(/* new value of THEME_STATE */);
178178
#### `4`
179179

180180
The Observer then creates a Job and passes it to the Runtime.
181-
The passed Job has a reference to the Observer to perform the actual action
181+
The created Job has a reference to the Observer itself in order to perform the actual action
182182
and rerender the correct UI-Components.
183183
```ts
184184
// ..
@@ -202,7 +202,7 @@ jobsToRerender.push(job);
202202

203203
#### `6`
204204

205-
A side effect of running a Job is the rerendering of subscribed Components.
205+
A side effect of running a Job is the rerendering of subscribed Components.
206206
Another could be the persisting into a permanent Storage or rebuilding the Group output.
207207
```ts
208208
// ..
@@ -246,8 +246,8 @@ other documentation sections. Often to learn some more about specific properties
246246
## 🤓 Glossary
247247

248248
In these docs, we will refer to our classes with a capital first letter.
249-
For example, when you see 'state' we are referring to the programming concept `state`,
250-
but when you see 'State' we are referring to our [State](../packages/core/features/state/Introduction.md) class.
249+
For example, when you see 'state', we refer to the programming concept `state`,
250+
but when you see 'State', we are referring to our [State](../packages/core/features/state/Introduction.md) class.
251251

252252
### `Agile Sub Instance`
253253
Instances that hold a reference to the [`Agile Instance`](../packages/core/features/agile-instance/Introduction.md)
@@ -281,7 +281,7 @@ In July, I came to the conclusion to contribute to PulseJs, in order to speed up
281281
But before I could do anything, I had to figure out how PulseJs works internally.
282282
After hours, I still haven't figured out how it works. This was due to the fact that I was a Typescript noob,
283283
and the codebase was not contributor friendly (No comments, variables called x, a, b, ..).
284-
In order to learn how PulseJs works and to get a deeper understanding of Typescript,
284+
To learn how PulseJs works and to get a deeper understanding of Typescript,
285285
I decided to rewrite PulseJs from scratch in a separate project, later AgileTs.
286286
After a while, I got the hang and understood how PulseJs works under the hood.
287287

@@ -290,8 +290,8 @@ My [first contribution](https://github.com/pulse-framework/pulse/commits?author=
290290
where I refactored the `PulseHOC`. Unfortunately, PulseJs was moving further and further away from my idea of an ideal State Management Framework.
291291
For instance, they introduced the `Pulse.Core`, which more or less forced me to define all States, Actions in a single object called `core`.
292292
I wouldn't say I liked that change since I switched, among other reasons, to PulseJs in order not to define all my States in a single object.
293-
Because of this relatively large design change, I would have to rebuild my entire State Management Logic of my applications.
294-
Which I didn't want to do, because I liked the old concept more.
293+
Because of this relatively significant design change, I would have to rebuild my entire State Management Logic of my applications.
294+
Which I didn't want to do because I liked the old concept more.
295295

296296
Luckily I had the refactored PulseJs version lying around, which I created to learn how PulseJs works internally and released it as an own framework called
297297
[agile-architecture](https://www.npmjs.com/package/agile-architecture).
@@ -308,7 +308,7 @@ Today AgileTs has only a similar syntax to PulseJs. Internal, it works quite dif
308308

309309
**Conclusion:** The idea of AgileTs is based on PulseJs, and I would have loved to continue working on PulseJs.
310310
But certain circumstances, such as a poor organization and different visions,
311-
have driven me to write my own State Manager based on the good ground concept of PulseJs and MVVM frameworks.
311+
have driven me to write my own State Manager based on the excellent ground concept of PulseJs and MVVM frameworks.
312312

313313
## 🎉 Credits
314314

docs/packages/core/features/agile-instance/Introduction.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,6 +117,10 @@ new Agile({
117117
bindGlobal: false // default false
118118
});
119119
```
120+
A globally bound Agile Instance has some advantages:
121+
- If methods such as `useAgile()` can't find any Agile Instance in the given Instances,
122+
they fall back on the global Agile Instance.
123+
- You can simply access it in the console for debugging purpose.
120124

121125
| Type | Default | Required |
122126
|-----------------|-------------|----------|
@@ -134,4 +138,4 @@ which might help you with such a hard decision.
134138

135139
## 🟦 Typescript
136140

137-
The `Agile Class` is almost 100% typesafe.
141+
The `Agile Class` is almost 100% typesafe.

docs/packages/core/features/collection/Methods.md

Lines changed: 62 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -492,6 +492,33 @@ Group | undefined
492492

493493

494494

495+
## `getDefaultGroup()`
496+
497+
Returns the default [Group](./group/Introduction.md) of the Collection.
498+
```ts
499+
MY_COLLECTION.getDefaultGroup();
500+
// equal to
501+
MY_COLLECTION.getGroup(MY_COLLECTION.config.defaultGroupKey);
502+
```
503+
If it can't find the default Group, it returns `undefined`.
504+
But if that is the case, something big has gone wrong.
505+
506+
### 📄 Return
507+
508+
```ts
509+
Group | undefined
510+
```
511+
512+
513+
514+
<br />
515+
516+
---
517+
518+
<br />
519+
520+
521+
495522
## `getGroupWithReference()`
496523

497524
Returns like [`getGroup()`](#getgroup) the Group at the given `groupKey`.
@@ -1137,7 +1164,7 @@ Returns the [Collection](./Introduction.md) it was called on.
11371164

11381165
## `put()`
11391166

1140-
With the `put()` method, we can quickly add specific `itemKeys` to particular Groups.
1167+
With the `put()` method, we can quickly add specific `itemKeys` to particular Group/s.
11411168
```ts
11421169
MY_COLLECTION.put('itemKey1', 'groupKey1');
11431170
```
@@ -1173,6 +1200,39 @@ Returns the [Collection](./Introduction.md) it was called on.
11731200

11741201

11751202

1203+
## `move()`
1204+
1205+
Moves `itemKey/s` from one Group to another Group.
1206+
```ts
1207+
MY_COLLECTION.move('itemKey1', /* from */ 'groupKey1', /* to */ 'groupKey2');
1208+
```
1209+
In the above example, we move the `itemKey1` from Group at `groupKey1` to Group at `groupKey2`, so to speak.
1210+
1211+
### 📭 Props
1212+
1213+
| Prop | Type | Default | Description | Required |
1214+
|----------------------|-----------------------------------------------------------------------|------------|-----------------------------------------------------------------------------------------------|----------|
1215+
| `itemKeys` | number \| string | Array<number \| string \> | [] | ItemKey/s that are moved | Yes |
1216+
| `oldGroupKey` | number \| string | undefined | GroupKey of the Group that currently keeps the Item/s at itemKey/s | Yes |
1217+
| `newGroupKey` | number \| string | undefined | GroupKey of the Group into which the Item/s at itemKey/s are moved | Yes |
1218+
| `config` | [GroupAddConfigInterface](../../../../Interfaces.md#groupaddconfig) | {} | Configuration | No |
1219+
1220+
### 📄 Return
1221+
1222+
```ts
1223+
Collection
1224+
```
1225+
Returns the [Collection](./Introduction.md) it was called on.
1226+
1227+
1228+
<br />
1229+
1230+
---
1231+
1232+
<br />
1233+
1234+
1235+
11761236
## `updateItemKey()`
11771237

11781238
:::warning
@@ -1431,4 +1491,4 @@ MY_COLLECTION.collect({id: 2, name: 'jeff'});
14311491
```ts
14321492
Collection
14331493
```
1434-
Returns the [Collection](./Introduction.md) it was called on.
1494+
Returns the [Collection](./Introduction.md) it was called on.

0 commit comments

Comments
 (0)