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

Commit 8614245

Browse files
bennobuilderbennobuilder
committed
persist docs changes
1 parent a3607cc commit 8614245

File tree

14 files changed

+106
-76
lines changed

14 files changed

+106
-76
lines changed

‎docs/Interfaces.md

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -303,8 +303,11 @@ Here is a Typescript Interface for quick reference. However,
303303
each property is explained in more detail below.
304304
```ts
305305
export interface StatePersistentConfigInterface {
306+
key?: string | number;
306307
loadValue?: boolean;
307308
storageKeys?: StorageKey[];
309+
onMigrate?: (value: any) => ValueType;
310+
onSave?: (value: ValueType) => any;
308311
}
309312
```
310313

@@ -317,12 +320,12 @@ Or, if the State isn't persisted yet, it stores the State value in the correspon
317320
Be aware that if we don't allow the `Persistent` to load/store the value, we have to do it ourselves.
318321
```ts {2}
319322
myState.persist({
320-
instantiate: false,
323+
loadValue: false,
321324
});
322325

323326
if (myState.persistent?.ready) {
324327
await myState.persistent?.initialLoading();
325-
myState.isPersisted = true;
328+
myState.isPersisted = true;
326329
}
327330
```
328331
Loading the value manually has one advantage.

‎docs/main/Contributing.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
id: contributing
3-
title: Contributing
4-
sidebar_label: Contributing to AgileTs
3+
title: Contributing to AgileTs
4+
sidebar_label: Contributing
55
slug: /contributing
66
description: Contributions to AgileTs are not hard and very welcome.
77
image: img/meta.png

‎docs/main/Introduction.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,18 +2,18 @@
22
id: introduction
33
title: Introducing AgileTs
44
sidebar_label: Introduction
5-
slug: /introduction/
6-
description: A global State and Logic Library implemented in Typescript, offering a reimagined API that focuses on developer experience. The AgileTs state management functionality can be used in various frameworks like React, Vue and plain Javascript.
5+
slug: /introduction
6+
description: An atom based global State and Logic Library implemented in Typescript, offering a reimagined API that focuses on developer experience. The AgileTs state management functionality can be used in various frameworks like React, Vue and plain Javascript.
77
image: img/meta.png
88
---
99

1010
## 👋 Introduction {#introduction}
1111

12-
AgileTs is a global State and Logic Library implemented in Typescript.
12+
AgileTs is an atom based global State and Logic Library implemented in Typescript.
1313
It offers a reimagined API that focuses on **developer experience**
1414
and allows you to **easily** and **flexible** manage your application States.
1515
Besides [States](../packages/core/api/state/Introduction.md),
16-
AgileTs offers some other powerful and tree shakable APIs that make your life easier,
16+
AgileTs offers some other powerful APIs that make your life easier,
1717
such as [Collections](../packages/core/api/collection/Introduction.md)
1818
and [Computed States](../packages/core/api/computed/Introduction.md).
1919
The philosophy behind AgileTs is simple:
@@ -35,7 +35,7 @@ MY_STATE.undo();
3535
MY_STATE.reset();
3636

3737
// Permanently store the State value in an external Storage
38-
MY_STATE.persist("storage-key");
38+
MY_STATE.persist({key: "storage-key"});
3939
```
4040

4141
### 🤸‍ Flexible {#flexible}

‎docs/main/StyleGuides.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -382,13 +382,13 @@ and mutate its entities as wished without further thinking.
382382
For example when we want to add a Todo-Item to the TODO Collection
383383
we simply call `core.todo.addTodo(/* new todo */);`.
384384
```ts title="index.ts"
385-
import todo from "./controllers/todo";
386-
import user from "./controllers/user";
385+
import todo from "./entities/todo";
386+
import user from "./entities/user";
387387
import {globalBind} from "@agile-ts/core";
388388

389389
const core = {
390-
todo: todo,
391-
user: user,
390+
todo,
391+
user,
392392
};
393393

394394
// For better debugging we bind the core globally

‎docs/packages/core/api/state/Methods.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -495,7 +495,7 @@ Returns the [State](./Introduction.md) it was called on.
495495

496496
Preserves the State `value` in the appropriate local Storage for the current environment.
497497
```ts
498-
MY_STATE.perist("myStorageKey");
498+
MY_STATE.perist({key: "myStorageKey"});
499499
```
500500

501501
### 🤓 Learn more
@@ -507,7 +507,6 @@ checkout the [Persisting Data](../storage/PersistingData.md) Section.
507507

508508
| Prop | Type | Default | Description | Required |
509509
|----------------------|----------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------|----------|
510-
| `key` | string \| number | undefined | Key/Name of created Persistent (Note: Key is required if State has no set Key!) | No |
511510
| `config` | [StatePersistentConfig](../../../../Interfaces.md#statepersistentconfig) | {} | Configuration | No |
512511

513512
### 📄 Return

‎docs/packages/core/api/storage/Introduction.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,10 +202,10 @@ The prefix will be added before each `Storage Key`
202202
and is intended to highlight the items stored by AgileTs.
203203
A `Storage Key` identifies the stored value in the corresponding Storage.
204204
```ts
205-
MY_STATE.persist('myState');
205+
MY_STATE.persist({key: 'myState'});
206206
// Storage Key: '_prefix_myState'
207207
208-
MY_COLLECTION.persist('myCollection');
208+
MY_COLLECTION.persist({key: 'myCollection'});
209209
// Storage Keys:
210210
// Collection Indicator: '_prefix_myCollection'
211211
// Default Group: '_prefix__myCollection_group_default'

‎docs/packages/core/api/storage/PersistingData.md

Lines changed: 33 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,20 +8,20 @@ slug: /core/persisting-data
88
It's common for applications to store data on the client browser.
99
AgileTs makes it pretty easy to achieve such goal.
1010
```ts
11-
MY_STATE.persist('storage-key-here');
11+
MY_STATE.persist({key: 'storage-key-here'});
1212
```
1313
Besides [States](../state/Introduction.md), we can persist nearly any [Agile Sub Instance](../../../../main/Introduction.md#agile-sub-instance).
1414
- [Collections](../collection/Introduction.md)
1515
```ts
16-
MY_COLLECTION.persist('storage-key-here');
16+
MY_COLLECTION.persist({key: 'storage-key-here'});
1717
```
1818
- [Selectors](../collection/selector/Introduction.md)
1919
```ts
20-
MY_SELECTOR.persist('storage-key-here');
20+
MY_SELECTOR.persist({key: 'storage-key-here'});
2121
```
2222
- [Groups](../collection/group/Introduction.md)
2323
```ts
24-
MY_GROUP.persist('storage-key-here');
24+
MY_GROUP.persist({key: 'storage-key-here'});
2525
```
2626

2727
Since many [Agile Sub Instance](../../../../main/Introduction.md#agile-sub-instance) can be persisted,
@@ -70,7 +70,7 @@ There are several ways to provide such required `storageKey` to the `persist()`
7070
```
7171
- **2.** Pass the `storageKey` directly into the `persist()` method.
7272
```ts {1}
73-
MY_INSTANCE.persist("myCoolPassedKey"); // Success (storageKey = 'myCoolPassedKey')
73+
MY_INSTANCE.persist({key: "myCoolPassedKey"}); // Success (storageKey = 'myCoolPassedKey')
7474
```
7575

7676
If AgileTs couldn't find any fitting `storageKey`,
@@ -103,3 +103,31 @@ By default, the AgilePersistInstance will be stored in the [default Storage](#-d
103103
```ts
104104
storageManager.config.defaultStorageKey; // Returns key of current default Storage
105105
```
106+
107+
## 🌈 Migration
108+
109+
In rare cases it is necessary to format the State value
110+
before it is persisted in an external Storage and migrated back later.
111+
When working with the `Date` class such formatting is required,
112+
since a javascript class can't be persisted.
113+
```ts
114+
const MY_STATE = createState(
115+
{
116+
// ..
117+
birthday: new Date('08.10.202')
118+
}
119+
).persist(
120+
{
121+
key: 'jeff',
122+
onSave: (value) => {
123+
value.date = value.date.getTime()
124+
return value;
125+
},
126+
onMigrate: (value) => {
127+
value.date = new Date(value.date);
128+
return value
129+
}
130+
}
131+
);
132+
```
133+

‎docusaurus.config.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,12 @@ const domain = 'https://agile-ts.org';
2121
const npmOrgUrl = 'https://www.npmjs.com/package/@agile-ts';
2222

2323
const customFields = {
24-
copyright: `Made with 💜 in Germany | Copyright © 2020-${new Date().getFullYear()} <a target="_blank" rel="noopener noreferrer" href="https://twitter.com/DevBenno">BennoDev</a>`,
24+
copyright: `Made with 💜 by <a target="_blank" rel="noopener noreferrer" href="https://twitter.com/DevBenno">BennoDev</a> and <a target="_blank" rel="noopener noreferrer" href="https://github.com/agile-ts/agile/graphs/contributors">these awesome people</a>`,
2525
meta: {
2626
title: 'An atom based state manager for JavaScript apps.',
2727
image: '/img/meta.png',
2828
description:
29-
'A global State and Logic Library implemented in Typescript, ' +
29+
'An atom based global State and Logic Library implemented in Typescript, ' +
3030
'offering a reimagined API that focuses on developer experience. ' +
3131
'AgileTs is a more straightforward alternative to Redux ' +
3232
'and allows you to easily manage your application States in React, Vue and plain Javascript.',
@@ -183,7 +183,7 @@ const config = {
183183
{
184184
label: 'Documentation',
185185
position: 'left',
186-
to: 'docs/introduction/',
186+
to: 'docs/introduction',
187187
},
188188
],
189189
},

‎package.json

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -19,13 +19,13 @@
1919
"install:prod:agile": "yarn add @agile-ts/core @agile-ts/react @agile-ts/api @agile-ts/event @agile-ts/proxytree @agile-ts/logger @agile-ts/utils & yarn install"
2020
},
2121
"dependencies": {
22-
"@agile-ts/api": "^0.0.24",
23-
"@agile-ts/core": "^0.2.6",
24-
"@agile-ts/event": "^0.0.13",
25-
"@agile-ts/logger": "^0.0.10",
26-
"@agile-ts/proxytree": "^0.0.8",
27-
"@agile-ts/react": "^0.2.2",
28-
"@agile-ts/utils": "^0.0.10",
22+
"@agile-ts/api": "^0.0.25",
23+
"@agile-ts/core": "^0.2.7",
24+
"@agile-ts/event": "^0.0.14",
25+
"@agile-ts/logger": "^0.0.11",
26+
"@agile-ts/proxytree": "^0.0.9",
27+
"@agile-ts/react": "^0.2.3",
28+
"@agile-ts/utils": "^0.0.11",
2929
"@docusaurus/core": "2.0.0-beta.6",
3030
"@docusaurus/module-type-aliases": "2.0.0-beta.6",
3131
"@docusaurus/preset-classic": "2.0.0-beta.6",

‎src/core/app.ts

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

0 commit comments

Comments
 (0)