From e1b4dc2ab0f41c098756a159aea1f6543f040d5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CScott?= Date: Sun, 19 Nov 2023 08:15:12 -0500 Subject: [PATCH] docs: :bug: Fixed all code examples (missing '), Rewrote upgrading Objects example and reordered --- README.md | 76 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 40 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 173b43e..0b7f854 100644 --- a/README.md +++ b/README.md @@ -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', @@ -43,13 +43,32 @@ 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: @@ -57,7 +76,7 @@ Persisted data is stored using `JSON.parse` and `JSON.stringify` but this can be ```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', @@ -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. @@ -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: