versioned-storage
Version:
Local storage with versioning.
118 lines (84 loc) • 3.38 kB
Markdown
# versioned-storage [](https://github.com/CatChen/versioned-storage/actions/workflows/node.yml) [](https://github.com/CatChen/versioned-storage/actions/workflows/deno.yml) [](https://codecov.io/gh/CatChen/versioned-storage)
Use named, versioned and typed ([TypeScript](https://www.typescriptlang.org/) and [Flow](https://flow.org/)) 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.
```JavaScript
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.
```TypeScript
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.
```TypeScript
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.
```JavaScript
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.
```JavaScript
const settingsStorage = new Storage('settings', 2); // Erase all data from version 1
```
Migrate data from previous storage schema before purging if necessary.
```JavaScript
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.
```JavaScript
settingsStorage.write({
brightness: 80,
volume: 100,
});
```
### `Storage.prototype.read` method
Read data from a named storage by calling `read` method on its instance.
```JavaScript
const {
brightness,
volume,
} = settingsStorage.read();
```
### `Storage.reset` static method
Clear all data across all named storages by calling the static method `reset`.
```JavaScript
Storage.reset();
```