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

Commit eda6561

Browse files
bennobuilderbennobuilder
authored
Merge pull request #16 from agile-ts/develop
Develop
2 parents b7f2516 + 51fac46 commit eda6561

File tree

9 files changed

+484
-94
lines changed

9 files changed

+484
-94
lines changed

‎docs/Interfaces.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
---
2+
id: interfaces
3+
title: Interfaces
4+
sidebar_label: Interfaces
5+
slug: /interfaces
6+
---
7+
8+
:::info
9+
10+
Here are all documented Interfaces of AgileTs listed!
11+
12+
:::
13+
14+
15+
### `CreateLoggerConfig`
16+
17+
```ts
18+
export interface CreateLoggerConfigInterface {
19+
prefix?: string;
20+
allowedTags?: string[];
21+
canUseCustomStyles?: boolean;
22+
active?: boolean;
23+
level?: number;
24+
timestamp?: boolean;
25+
}
26+
```
27+
28+
| Prop | Type | Default | Description | Required |
29+
|----------------------|----------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|----------|
30+
| `level` | number | 20 (Logger.level.WARN) | On which 'level' the logger should log. For instance if it only should log Errors. | No |
31+
| `active` | boolean | true | If the Logger is active. | No |
32+
| `timestamp` | boolean | false | If a Timestamp gets applied for each Log Message. | No |
33+
| `allowedTags` | string[] | ['runtime', 'storage', 'subscription', 'multieditor'] | Sometimes logs are marked with Tags. If this is the case, the log gets only logged if the Tag is included. | No |
34+
| `canUseCustomStyles` | boolean | true | If the Logger is allowed to apply css styles to the Logs. For instance Agile Logs are by default purple. | No |
35+
36+
37+
<br/>
38+
39+
---
40+
41+
<br/>
42+
43+
44+
### `StorageMethods`
45+
46+
```ts
47+
export interface StorageMethodsInterface {
48+
get: (key: string) => any;
49+
set: (key: string, value: any) => void;
50+
remove: (key: string) => void;
51+
}
52+
```
53+
54+
| Prop | Type | Default | Description | Required |
55+
|----------|----------------------------------------|-----------|--------------------------------------------------------|----------|
56+
| `get` | (key: string) => any | undefined | Get Method of Storage (gets Items from Storage) | Yes |
57+
| `set` | (key: string, value: any) => void | undefined | Set Method of Storage (saves/updates Items in Storage) | Yes |
58+
| `remove` | (key: string) => void | undefined | Remove Method of Storage (removes Items from Storage) | Yes |
59+
60+
61+
<br/>
62+
63+
---
64+
65+
<br/>
66+
67+
68+
### `StateConfig`
69+
70+
```ts
71+
export interface StateConfigInterface {
72+
key?: StateKey;
73+
dependents?: Array<Observer>;
74+
isPlaceholder?: boolean;
75+
}
76+
```
77+
78+
| Prop | Type | Default | Description | Required |
79+
|-----------------|--------------------|-----------|-----------------------------------------------------------------------------------------------------------|----------|
80+
| `key` | `string \| number` | undefined | Key/Name of State | No |
81+
| `dependents` | Observer[] | [] | Initial dependents of the State -> if State mutates, the dependents will be ingested into the Runtime too | No |
82+
| `isPlaceholder` | boolean | false | If State is a placeholder, to hold a reference (used internal) | No |
83+
84+
85+
<br/>
86+
87+
---
88+
89+
<br/>
90+
91+
92+
### `CollectionConfig`
93+
94+
```ts
95+
export type CollectionConfig<DataType = DefaultItem> =
96+
| CreateCollectionConfigInterface<DataType>
97+
| ((
98+
collection: Collection<DataType>
99+
) => CreateCollectionConfigInterface<DataType>);
100+
```
101+
*[CreateCollectionConfigInterface](#createcollectionconfig)
102+
103+
**There are two ways configuring the Collection:**
104+
105+
1. The _Object_ way, where we can configure everything, but we are limited in the creation of Groups and Selectors,
106+
because here the Collection creates them for us, and for instance we can't pass initial Items to them.
107+
```ts
108+
const Collection = App.createCollection({
109+
key: 'dummyCollection',
110+
group: ["dummyGroup"]
111+
})
112+
```
113+
114+
2. The _Function_ way, where we can configure everything too, but here we are able to create the Groups and Selectors from scratch,
115+
and have more control over them.
116+
```ts
117+
const Collection = App.createCollection((collection) => ({
118+
key: 'dummyCollection',
119+
group: {
120+
dummyGroup: collection.Group(["item1", "item2"])
121+
}
122+
}))
123+
```
124+
125+
126+
<br/>
127+
128+
---
129+
130+
<br/>
131+
132+
133+
### `CreateCollectionConfig`
134+
135+
```ts
136+
export interface CreateCollectionConfigInterface<DataType = DefaultItem> {
137+
groups?: { [key: string]: Group<any> } | string[];
138+
selectors?: { [key: string]: Selector<any> } | string[];
139+
key?: CollectionKey;
140+
primaryKey?: string;
141+
defaultGroupKey?: GroupKey;
142+
initialData?: Array<DataType>;
143+
}
144+
145+
```
146+
| Prop | Type | Default | Description | Required |
147+
|-------------------|-------------------------------------------------|-----------|--------------------------------------------------------------------------------------------------------|----------|
148+
| `groups` | { [ key : string]: Group<any\> } \| string[] | [] | Initial Groups of Collection. Groups are used to represent multiple representations of the Collection. | No |
149+
| `selectors` | { [ key : string]: Selector<any\> } \| string[] | [] | Initial Selectors of Collection. Selectors are used to select one specific Item of the Collection. | No |
150+
| `key` | string \| number | undefined | Key/Name of Collection | No |
151+
| `primaryKey` | string | 'id' | Primary Key property of Item, used to identify Items in Collection. | No |
152+
| `defaultGroupKey` | GroupKey | 'default' | How the default Group, which represents the main representation of the Collection, is called. | No |
153+
| `initialData` | Array< DataType > | [] | Initial Data of Collection | No |
154+
155+
156+
<br/>
157+
158+
---
159+
160+
<br/>
161+
162+
163+
### `CreateEventConfig`
164+
165+
```ts
166+
export interface CreateEventConfigInterface {
167+
key?: EventKey;
168+
enabled?: boolean;
169+
maxUses?: number;
170+
delay?: number;
171+
overlap?: boolean;
172+
rerender?: boolean;
173+
dependents?: Array<Observer>;
174+
}
175+
```
176+
177+
| Prop | Type | Default | Description | Required |
178+
|--------------|------------------|-----------|-----------------------------------------------------------------------------------------------------------|----------|
179+
| `key` | string \| number | undefined | Key/Name of Event | No |
180+
| `enabled` | boolean | true | If Event is enabled and can be triggered | No |
181+
| `maxUses` | number | undefined | How often the Event can be triggered, by default infinite | No |
182+
| `delay` | number (in ms) | undefined | If the Event should have an trigger delay | No |
183+
| `overlap` | boolean | false | If a triggered Event can overlap another triggered Event from same Event Class | No |
184+
| `rerender` | boolean | false | If a Event trigger can rerender a Component (useEvent) | No |
185+
| `dependents` | Observer[] | [] | Initial dependents of the State -> if State mutates, the dependents will be ingested into the Runtime too | No |

‎docs/packages/core/Introduction.md

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -19,14 +19,19 @@ slug: /core
1919
<img src="https://img.shields.io/npm/dt/@agile-ts/core.svg?label=downloads&style=flat&colorA=293140&colorB=4a4872" alt="npm total downloads"/></a>
2020

2121

22-
## ❓ What does the `core` package?
22+
## ❓ `core`
2323

24-
You can think of the `core` package as the brain of AgileTs.
25-
It includes the [Agile Class](./features/agile-instance/Introduction.md) which is the main Instance of AgileTs.
24+
The `core` package is the brain of AgileTs and handles nearly everything related to AgileTs.
25+
- Manages your Agile Sub Instances ([State](./features/state/Introduction.md), ..)
26+
- Ingest changes into the Runtime
27+
- Triggers rerender on Integrations like [React](../react/Introduction.md)
28+
29+
Each mentioned feature is related to the [`Agile Class`](./features/agile-instance/Introduction.md) which
30+
is located in the `core`
2631
```ts
2732
const App = new Agile();
2833
```
29-
Each Agile Sub Instance like
34+
Agile Sub Instance like
3035

3136
- [State](./features/state/Introduction.md)
3237
```ts
@@ -45,8 +50,8 @@ Each Agile Sub Instance like
4550
const MY_EVENT = App.createEvent();
4651
```
4752

48-
has it originates from such main Agile Instance.
49-
It doesn't matter where we instantiate our main Agile Instance, but for sure
50-
each Application using AgileTs needs such an Instance.
51-
But be aware that it isn't recommend having multiple Agile Instances in one single Application.
53+
has it originates from the `Agile Class`.
54+
Each Application using AgileTs must instantiate such an Agile Instance.
55+
It doesn't matter where we instantiate our main Agile Instance,
56+
but be aware that it isn't recommend having multiple Agile Instances in one single Application.
5257
You might check out the [style guides](../../main/StyleGuide.md) to get some inspiration how to structure an Application having AgileTs as state manager.

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

Lines changed: 33 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,11 @@ sidebar_label: Introduction
55
slug: /core/agile-instance
66
---
77

8-
The Agile Instance is created with `new Agile()`and should be unique to your application.
9-
Multiple Agile Instances in one Application might cause trouble.
8+
The _Agile Instance_ is created with `new Agile()`and should be unique to our application.
109
```ts
1110
const App = new Agile();
1211
```
13-
With an instantiated Agile Instance, we are able to create any Agile Sub Instances like
12+
With an instantiated _Agile Instance_, we are able to create any Agile Sub Instances like
1413
- [State](../state/Introduction.md)
1514
```ts
1615
const MY_STATE = App.createState("Hello there");
@@ -28,19 +27,19 @@ With an instantiated Agile Instance, we are able to create any Agile Sub Instanc
2827
const MY_EVENT = App.createEvent();
2928
```
3029

31-
These Sub Instances we create using the main Instance are automatically added to it.
32-
Trough that the Agile Instance can also be seen as a Store, that offers many
33-
possibilities to mutate the stored Instances.
30+
These Sub Instances created with the help of the `Agile Class` are automatically bound to it.
31+
Because of the storing behaviour, the `Agile Class` can also be seen as a Store,
32+
that offers many features to mutate and work with the stored Instances.
3433

35-
## Configuration Options
34+
## 📭 Props
3635

3736
`Agile` takes an optional configuration object as its only parameter.
3837
```ts
3938
const App = new Agile({
40-
logConfig: {
41-
level: Logger.level.DEBUG,
39+
logConfig: {
4240
active: true,
4341
},
42+
localStorage: false
4443
});
4544
```
4645
Here is a Typescript Interface for quick reference, however
@@ -57,48 +56,46 @@ export interface CreateAgileConfigInterface {
5756

5857
The logConfig is thought to configure the Logger of AgileTs.
5958
For instance, we can configure if we want to log all messages or
60-
only warning.
59+
only warnings. [Here](../../../../Interfaces.md#createloggerconfig) you can find all configuration options.
6160
```ts
62-
export interface CreateLoggerConfigInterface {
63-
prefix?: string;
64-
allowedTags?: string[];
65-
canUseCustomStyles?: boolean;
66-
active?: boolean;
67-
level?: number;
68-
timestamp?: boolean;
69-
}
61+
const App = new Agile({
62+
logConfig: {
63+
level: Logger.level.ERROR, // print only errors
64+
active: true,
65+
},
66+
});
7067
```
7168

72-
| Prop | Type | Default | Description | Required |
73-
|----------------------|----------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|----------|
74-
| `level` | number | 20 (Logger.level.WARN) | On which 'level' the logger should log. For instance if it only should log Errors. | No |
75-
| `active` | boolean | true | If the Logger is active. | No |
76-
| `timestamp` | boolean | false | If a Timestamp gets applied for each Log Message. | No |
77-
| `allowedTags` | string[] | ['runtime', 'storage', 'subscription', 'multieditor'] | Sometimes logs are marked with Tags. If this is the case, the log gets only logged if the Tag is included. | No |
78-
| `canUseCustomStyles` | boolean | true | If the Logger is allowed to apply css styles to the Logs. For instance Agile Logs are by default purple. | No |
79-
80-
8169

8270
### `localStorage`
8371

8472
Defines whether we want to use the Local Storage as default Storage or not.
8573
If we use the Local Storage each Agile Sub Instance we persist, gets stored in the Local Storage by default.
8674
We aren't limited to the Local Storage, we can configure our own [Storage](../storage/Introduction.md).
87-
This is necessary in a Mobile Environment, because there the Local Storage doesn't exist.
88-
With `App.registerStorage` we can register our wished [Storage](../storage/Introduction.md).
89-
````ts
90-
localStorage: false // default true
91-
````
75+
This is in a Mobile Environment necessary, because there the Local Storage doesn't exist.
76+
With `App.registerStorage()` we can register our wished [Storage](../storage/Introduction.md).
77+
```ts
78+
const App = new Agile({
79+
localStorage: false // default true
80+
});
81+
```
9282

9383
### `waitForMount`
9484

9585
With `waitForMount` we define if AgileTs should wait
9686
with causing rerender on an unmounted Component until it got mounted.
97-
````ts
98-
waitForMount: false // default true
99-
````
87+
```ts
88+
const App = new Agile({
89+
waitForMount: false // default true
90+
});
91+
```
92+
93+
94+
## 🟦 Typescript
95+
96+
`Agile Class` is almost 100% typesafe.
10097

101-
## Where to instantiate?
98+
## 🗺 Where to instantiate?
10299

103100
You can instantiate the Agile Instance where ever you want.
104101
Directly in your Component, in an extra File or on Paper.

0 commit comments

Comments
 (0)