versioned-storage

Use named, versioned and typed (TypeScript and Flow) JSON storage through localStorage!

Examples

Create a named and versioned storage by creating a Storage object. Use Storage.prototype.write and Storage.prototype.read to operate.

import { Storage } from 'versioned-storage';

const userStorage = new Storage('user', 1);
userStorage.write({
  id: 42,
  name: 'Cat',
});
console.log(userStorage.read()); // { id: 42, name: 'Cat' }

Add typing information with TypeScript to make each storage type safe.

import { Storage } from 'versioned-storage';

type User = {
  id: number;
  name: string;
}

const userStorage = new Storage<User>('user', 1);

userStorage.write({ id: 42 });
// TypeScript error because userStorage.write is typed as (value: User) => void.

const user = userStorage.read();
// TypeScript infers user being User because userStorage.read is typed as () => User.

Use package name with scope when used in Deno with JSR.

import { Storage } from '@catchen/versioned-storage';

Features

1. Read and write values as JSON instead of string.
2. TypeScript and Flow typing support for JSON structure being read and written.

API

The API is very simple. There are only 4 functions you need to know.

Storage class

Create a storage by calling Storage class constructor with a name and a version.

const settingsStorage = new Storage('settings', 1);

When a storage's schema is changed and no longer compatible, bump the version number and old data will be purged automatically.

const settingsStorage = new Storage('settings', 2); // Erase all data from version 1

Migrate data from previous storage schema before purging if necessary.

let settingsStorage;
try {
  settingsStorage = new Storage('settings'); // Get the storage of existing version
  switch (settingsStorage.version) {
    case 1:
      // Read v1 settings, migrate it to v3 schema and store it
      break;
    case 2:
      // Read v2 settings, migrate it to v3 schema and store it
      break;
    default:
      throw new Error('Incompatible legacy storage schema');
  }
} catch (_error) {
  settingsStorage = new Storage('settings', 3); // Start from scratch if not migratable
}

Storage.prototype.write method

Write data to a named storage by calling write method on its instance.

settingsStorage.write({
  brightness: 80,
  volume: 100,
});

Storage.prototype.read method

Read data from a named storage by calling read method on its instance.

const {
  brightness,
  volume,
} = settingsStorage.read();

Storage.reset static method

Clear all data across all named storages by calling the static method reset.

Storage.reset();