@delphington/persistent-buckets

persistent-buckets

Versioned localStorage buckets backed by shared Vue refs.

Usage

import { defineBucket } from '@delphington/persistent-buckets';

type Preferences = {
  theme: 'light' | 'dark';
};

export const preferences = defineBucket<Preferences>({
  key: 'example:preferences',
  version: 0,
  initial: { theme: 'light' },
  migrate(version, stored) {
    if (version !== 0) throw new Error('Unsupported preferences version');
    return stored as Preferences;
  },
});

state is a shared Vue ref. Changes must be saved explicitly:

const state = preferences.state;
state.value.theme = 'dark';
preferences.save();

Bucket modules self-register when they are imported. Import every bucket at the application's entry point so aggregate operations always use the complete set:

import './persistence/buckets/history';
import './persistence/buckets/preferences';

Vite applications can instead eagerly import a bucket directory:

import.meta.glob('./persistence/buckets/*.ts', { eager: true });

Only imported buckets are included by persistence.dump(), persistence.restore(), persistence.reset(), and persistence.prune().

Bucket data must be JSON-serializable. If localStorage is unavailable, data is kept in memory and persistence.ephemeral is true.