Skip to content

Commit 7162c96

Browse files
committed
update readme
Add motivations and more examples.
1 parent 234c605 commit 7162c96

File tree

1 file changed

+76
-6
lines changed

1 file changed

+76
-6
lines changed

README.md

Lines changed: 76 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,21 +14,21 @@ A **writable** derived store for objects and arrays!
1414
### Objects are `keyed`
1515

1616
```js
17-
const name = writable({ first: 'Rich', last: 'Harris' });
18-
const firstName = keyed(name, 'first');
17+
const name = writable({ first: "Rich", last: "Harris" });
18+
const firstName = keyed(name, "first");
1919

20-
$firstName = 'Bryan';
20+
$firstName = "Bryan";
2121

2222
console.log($name); // { first: 'Bryan', last: 'Harris' };
2323
```
2424

2525
### Arrays are `indexed`
2626

2727
```js
28-
const history = writable(['one', 'two', 'three']);
28+
const history = writable(["one", "two", "three"]);
2929
const previousEdit = indexed(history, 1);
3030

31-
$previousEdit = 'four';
31+
$previousEdit = "four";
3232

3333
console.log($history); // ['one', 'four', 'three'];
3434
```
@@ -55,5 +55,75 @@ Due to Typescript limitations, if the parent store is nullable, specify the full
5555

5656
```ts
5757
const name = writable<Name | undefined>(undefined);
58-
const firstName = keyed<Name>(name, 'first');
58+
const firstName = keyed<Name>(name, "first");
59+
```
60+
61+
### Nested objects
62+
63+
`keyed` and `indexed` only derive one depth of properties or elements. To access nested objects, nest multiple `keyed` or `indexed` calls.
64+
65+
```js
66+
const email = keyed(indexed(keyed(settings, "profiles"), 0), "email");
67+
```
68+
69+
## Motivations
70+
71+
We usually read and write properties of an object store with [auto-subscriptions](https://svelte.dev/tutorial/auto-subscriptions).
72+
73+
```svelte
74+
<input bind:value={$name.first}/>
75+
```
76+
77+
However, auto-subscriptions are isolated to a Svelte component. `svelte-keyed` aims to solve several common limitations listed below.
78+
79+
### Context stores
80+
81+
Often, we want to set a property or element of a store into component context, then allow child components to read / write to the property.
82+
83+
```svelte
84+
<!-- Settings.svelte -->
85+
<script>
86+
setContext('profileSettings', keyed(settings, 'profile'));
87+
</script>
88+
89+
<GeneralSettings />
90+
<ProfileSettings />
91+
```
92+
93+
```svelte
94+
<!-- ProfileSettings.svelte -->
95+
<script>
96+
const profileSettings = getContext('profileSettings');
97+
</script>
98+
99+
<input type="text" bind:value={$profileSettings.username} />
100+
```
101+
102+
### Helper functions
103+
104+
One important method to reduce clutter on your component is to extract functionality into external helper functions. `svelte-keyed` allows you to create derived `Writable` stores that can be passed into or returned from helper functions.
105+
106+
```svelte
107+
<!-- Settings.svelte -->
108+
<script>
109+
const stats = writable({ userClicks: 0, userTaps: 0 });
110+
const clicks = keyed(stats, 'userClicks');
111+
</script>
112+
113+
<div use:trackClicks={clicks} />
114+
<input use:trackClicks={clicks} />
115+
```
116+
117+
```js
118+
export const trackClicks = (node, clicks) => {
119+
const listen = () => {
120+
clicks.update(($clicks) => $clicks + 1);
121+
};
122+
node.addEventListener("click", listen);
123+
return {
124+
destroy() {
125+
node.removeEventListener("click", listen);
126+
},
127+
};
128+
};
59129
```

0 commit comments

Comments
 (0)