Skip to content

docs: 🐛 Fixed all code examples (missing '), Rewrote upgrading Ob… #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

docs: 🐛 Fixed all code examples (missing '), Rewrote upgrading Ob… #2

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
76 changes: 40 additions & 36 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Import and create a `Writable` store, just as you would with the default Svelte
```ts
import { web_storage } from 'svelte-web-storage'

export const settings = web_storage('settings, {
export const settings = web_storage('settings', {
page_size: 24,
currency: 'USD',
language: 'en-US',
Expand All @@ -43,21 +43,40 @@ To use `sessionStorage` which isn't persisted or synchronized across tabs, use a
```ts
import { web_storage } from 'svelte-web-storage'

export const settings = web_storage('settings, {
export const settings = web_storage('settings', {
page_size: 24,
currency: 'USD',
language: 'en-US',
}, { persist: false }) // <== disables persistence
```

### Upgrading Objects

If you add new properties to your settings object, the new default values of those properties will be automatically added to any persisted values. Adding a `theme` property to the previous example would set its store value to `system`, but leave any existing customized properties unchanged. No need to manually handle properties missing from the persisted state, or your settings having possibly undefined values.

```ts
import { web_storage } from 'svelte-web-storage'

export const settings = web_storage('settings', {
page_size: 24,
currency: 'USD',
language: 'en-US'
});

$settings.theme = 'system';

console.log(JSON.stringify($settings));
// { "page_size":24, "currency":"USD", "language":"en-US", "theme":"system" }
```

### Custom Serialization

Persisted data is stored using `JSON.parse` and `JSON.stringify` but this can be overridden by passing in a `serializer` as part of the 3rd options parameter. This might be because you have some legacy format that you want to use:

```ts
import { web_storage } from 'svelte-web-storage'

export const settings = web_storage('settings, {
export const settings = web_storage('settings', {
page_size: 24,
currency: 'USD',
language: 'en-US',
Expand All @@ -78,21 +97,6 @@ export const settings = web_storage('settings, {
})
```

### Upgrading Objects

If you add new properties to your settings object, the new default values of those properties will be automatically added to any persisted values. Adding a `theme` property to the previous example would set the store value to `system`, but leave any existing customized properties unchanged. No need to manually handle properties missing from the persisted state, or your settings having possibly undefined values.

```ts
import { web_storage } from 'svelte-web-storage'

export const settings = web_storage('settings, {
page_size: 24,
currency: 'USD',
language: 'en-US',
theme: 'system',
})
```

## Comparison (work in progress)

There are lots of packages that do similar things to this lib, so why might you want to use this one? I've tried to put together a comparison of all the ones I could find - I'm not claiming it's an exhaustive or a 100% accurate list, so let me know if there is something I've missed or you think is incorrect.
Expand Down Expand Up @@ -122,24 +126,24 @@ The criteria for comparing includes:
- **Handsomeness** of the author
- that's a joke, to see if anyone read this far ...

| Name | Version | Minified | GZipped | Correct | Upgrade | SSR | SK Deps | Session | Sync | Values | TS | Serialize |
| ----------------------------------- | ------- | -------: | ------: | :-----: | :-----: | :-: | :-----: | :-----: | :--: | :----: | :-: | :-------: |
| svelte-web-storage | 0.0.2 | 629B | 397B | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| svelte-persisted-store | 0.7.0 | 1.24kB | 650B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-persistent-store | 0.1.6 | 1.7kB | 837B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-backed-store | 1.1.1 | 3.5kB | 1.25kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-persistent-writable | 1.1.6 | 1.4kB | 631B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-localstorage-writable | 0.1.3 | 960B | 519B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-syncable | 1.0.4 | | | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-storable | 1.0.4 | 1kB | 509B | ✅ | ❓ | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-cached-store | | | | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @macfja/svelte-persistent-store | 2.4.1 | 19.9kB | 7.3kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @macfja/browser-storage-store | 1.0.0 | 4.2kB | 1.9kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @n0n3br/svelte-persist-store | 1.0.2 | 8.4kB | 2.9kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @babichjacob/svelte-localstorage | | | | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @typhonjs-svelte/simple-web-storage | | | | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @thegrommet/svelte-syncable | 2.0.0 | 846B | 447B | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @furudean/svelte-persistent-store | 0.8.0 | 881B | 494B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| Name | Version | Minified | GZipped | Correct | Upgrade | SSR | SK Deps | Session | Sync | Values | TS | Serialize |
| ----------------------------------- | ------- | -------: | ------: | :-----: | :-----: | :---: | :-----: | :-----: | :---: | :----: | :---: | :-------: |
| svelte-web-storage | 0.0.2 | 629B | 397B | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| svelte-persisted-store | 0.7.0 | 1.24kB | 650B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-persistent-store | 0.1.6 | 1.7kB | 837B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-backed-store | 1.1.1 | 3.5kB | 1.25kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-persistent-writable | 1.1.6 | 1.4kB | 631B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-localstorage-writable | 0.1.3 | 960B | 519B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-syncable | 1.0.4 | | | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-storable | 1.0.4 | 1kB | 509B | ✅ | ❓ | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| svelte-cached-store | | | | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @macfja/svelte-persistent-store | 2.4.1 | 19.9kB | 7.3kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @macfja/browser-storage-store | 1.0.0 | 4.2kB | 1.9kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @n0n3br/svelte-persist-store | 1.0.2 | 8.4kB | 2.9kB | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @babichjacob/svelte-localstorage | | | | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @typhonjs-svelte/simple-web-storage | | | | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @thegrommet/svelte-syncable | 2.0.0 | 846B | 447B | ❌ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |
| @furudean/svelte-persistent-store | 0.8.0 | 881B | 494B | ✅ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ | ❓ |

### Methodology:

Expand Down