Registry / storage / versioned-storage

versioned-storage

library4.0.15jsnpmunverified

A lightweight browser library for type-safe, versioned JSON storage via localStorage. v4.0.15 (last release 2024) targets Node ≥20 and is ESM-only with bundled TypeScript and Flow typings. Key differentiator: automatic purging on schema version bumps, with optional migration support. Minimal API: one class (Storage) with read/write/reset. Dependencies: none.

storage

npm install versioned-storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VERSIONED-STORAGE

versioned-storage

storagejavascriptv4.0.15

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Storage

✓ import { Storage } from 'versioned-storage'

✗ const Storage = require('versioned-storage')

Package is ESM-only; require() will throw. TypeScript types are included.

default import

✓ import { Storage } from 'versioned-storage'

✗ import Storage from 'versioned-storage'

There is no default export; only named export Storage is available.

Deno import

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

✗ import { Storage } from 'versioned-storage'

In Deno (via JSR), use the scoped package name @catchen/versioned-storage.

Shows creation of versioned storages, writing/reading data, automatic purge on version change, TypeScript generics, and global reset.

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' } // version bump purges old data const settingsStorage = new Storage('settings', 2); settingsStorage.write({ theme: 'dark' }); // example with TypeScript generics type User = { id: number; name: string }; const tsStorage = new Storage<User>('ts', 1); tsStorage.write({ id: 1, name: 'Alice' }); // reset all storages Storage.reset();

Debug

Known issues

breakingSince v4.0.0, package is ESM-only. Legacy CommonJS (require()) no longer works.

fix

Replace require('versioned-storage') with import { Storage } from 'versioned-storage'.

affects: >=4.0.0

breakingSince v4.0.0, Node.js version must be >=20.

fix

Upgrade Node.js to version 20 or later.

affects: >=4.0.0

deprecatedThe static method 'reset()' was added in v2.0.0. No deprecations exist in current version.

fix

Upgrade to latest version to ensure all APIs are available.

affects: <2.0.0

gotchaIf you omit the version number in the constructor, the storage will inherit the existing version if it exists; otherwise it defaults to 0. Use with care during migration.

fix

Always provide a version number to avoid unexpected data retention.

affects: >=1.0.0

gotchaData is stored as JSON in localStorage. Values must be JSON-serializable; functions, symbols, or undefined will be lost or throw.

fix

Ensure all stored values are JSON-compatible (strings, numbers, booleans, objects, arrays, null).

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/node_modules/versioned-storage/build/index.js from /path/app.js not supported. Instead change the require of index.js in /path/app.js to a dynamic import() which is available in all CommonJS modules.

Using require() with an ESM-only package.

fix

Change require('versioned-storage') to import { Storage } from 'versioned-storage'.

TypeError: The 'super' argument must be an object or null.

Using default import (Storage) instead of named import { Storage } from 'versioned-storage'.

fix

Use named import: import { Storage } from 'versioned-storage'.

Uncaught TypeError: userStorage.read is not a function

Storage instance was not created correctly; possibly using default import or the library failed to load.

fix

Ensure you have imported Storage correctly and created an instance: const userStorage = new Storage('user', 1);

Upgrade

Version history

4.0.15latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/CatChen/versioned-storage ↗

packageversioned-storage ↗

homepagehttps://github.com/CatChen/versioned-storage#readme ↗