@typhonjs-svelte/simple-web-storage

!@typhonjs-svelte/simple-web-storage



Provides a set of Svelte store helper functions to connect Svelte w/ the
browser web Storage API. This package is an evolution of
svelte-persistent-stores for Svelte v4+. The primary reason to
choose this package over alternatives is that it accomplishes the task in ~100 source lines of code w/ no dependencies
besides Svelte.

API documentation

Usage

Persist to localStorage

``js
import { writable, readable, derived } from '@typhonjs-svelte/simple-web-storage/local';

// The first argument is the storage key followed by any default value.
const count = writable('count', 0);

count.set(1);
`

Persist to sessionStorage

`js
import { writable, readable, derived } from '@typhonjs-svelte/simple-web-storage/session';

// The first argument is the storage key followed by any default value.
const count = writable('count', 0);

count.set(1);
`

The named exports from the main package export provides localStores / sessionStores respectively containing
derived / readable / writable properties.

`js
import { localStores, sessionStores } from '@typhonjs-svelte/simple-web-storage';

// The first argument is the storage key followed by any default value.
const localCount = localStores.writable('count', 0);
const sessionCount = sessionStores.writable('count', 0);

localCount.set(1);
sessionCount.set(1);
`

API

The stores provided have the same signature as the Svelte store helper functions except the first argument is the
string key used by localStorage and sessionStorage to store and retrieve the value. The
Storage interface specification only allows string values
therefore this library by default serializes stored values as JSON.

Advanced API / Customization

The storeGenerator function that wraps and creates Storage
connected stores is available allowing further external customization. You may provide a custom serialization strategy
that is different from JSON along with providing any Storage API compatible interface besides browser localStorage /
sessionStorage. The serialize / deserialize functions must match the partial signatures of JSON.parse /
JSON.stringify; IE the first value argument and return types.

The following is a Typescript example for generating storage API compatible stores w/ a customized serialization
strategy:
`ts
import {
storeGenerator,
StorageDerived,
StorageReadable,
StorageWritable } from '@typhonjs-svelte/simple-web-storage/generator';

// The storage option for storeGenerator must be a Storage API compatible instance.

// Provide a JSON parse / stringify signature compatible functions to modify serialization strategy.
// const deserialize = ... // (value: string, ...rest: any[]) => any
// const serialize = ... // (value: any, ...rest: any[]) => string

export const localStores = storeGenerator({ storage: globalThis?.localStorage, serialize, deserialize });

export const derived: StorageDerived = localStores.derived;
export const readable: StorageReadable = localStores.readable;
export const writable: StorageWritable = localStores.writable;
`

Beyond the derived, readable, and writable store helper functions created storeGenerator also adds the
storage, serialize, and deserialize` instance / functions to the returned object.

In the package tests the custom serialization strategy tested is compressed MessagePack to base64 data.

Other Svelte browser storage packages

For more comprehensive solutions that are a bit more heavyweight check out:
- @macfja/svelte-persistent-store
- Dexie.js (IndexedDB)