{"id":49653,"library":"versioned-storage","title":"versioned-storage","description":"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.","status":"active","version":"4.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/CatChen/versioned-storage","tags":["javascript","versioned","storage","typescript"],"install":[{"cmd":"npm install versioned-storage","lang":"bash","label":"npm"},{"cmd":"yarn add versioned-storage","lang":"bash","label":"yarn"},{"cmd":"pnpm add versioned-storage","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Package is ESM-only; require() will throw. TypeScript types are included.","wrong":"const Storage = require('versioned-storage')","symbol":"Storage","correct":"import { Storage } from 'versioned-storage'"},{"note":"There is no default export; only named export Storage is available.","wrong":"import Storage from 'versioned-storage'","symbol":"default import","correct":"import { Storage } from 'versioned-storage'"},{"note":"In Deno (via JSR), use the scoped package name @catchen/versioned-storage.","wrong":"import { Storage } from 'versioned-storage'","symbol":"Deno import","correct":"import { Storage } from '@catchen/versioned-storage'"}],"quickstart":{"code":"import { Storage } from 'versioned-storage';\n\nconst userStorage = new Storage('user', 1);\nuserStorage.write({ id: 42, name: 'Cat' });\nconsole.log(userStorage.read()); // { id: 42, name: 'Cat' }\n\n// version bump purges old data\nconst settingsStorage = new Storage('settings', 2);\nsettingsStorage.write({ theme: 'dark' });\n\n// example with TypeScript generics\ntype User = { id: number; name: string };\nconst tsStorage = new Storage<User>('ts', 1);\ntsStorage.write({ id: 1, name: 'Alice' });\n\n// reset all storages\nStorage.reset();","lang":"typescript","description":"Shows creation of versioned storages, writing/reading data, automatic purge on version change, TypeScript generics, and global reset."},"warnings":[{"fix":"Replace require('versioned-storage') with import { Storage } from 'versioned-storage'.","message":"Since v4.0.0, package is ESM-only. Legacy CommonJS (require()) no longer works.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade Node.js to version 20 or later.","message":"Since v4.0.0, Node.js version must be >=20.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade to latest version to ensure all APIs are available.","message":"The static method 'reset()' was added in v2.0.0. No deprecations exist in current version.","severity":"deprecated","affected_versions":"<2.0.0"},{"fix":"Always provide a version number to avoid unexpected data retention.","message":"If 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure all stored values are JSON-compatible (strings, numbers, booleans, objects, arrays, null).","message":"Data is stored as JSON in localStorage. Values must be JSON-serializable; functions, symbols, or undefined will be lost or throw.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'20':23 '2024':20 'api':48 'automat':37 'browser':6 'bump':42 'bundl':30 'class':50 'depend':54 'differenti':36 'esm':27 'esm-on':26 'flow':33 'javascript':56 'json':13 'key':35 'last':18 'librari':7 'lightweight':5 'localstorag':16 'migrat':45 'minim':47 'node':22 'none':55 'one':49 'option':44 'purg':38 'read/write/reset':53 'releas':19 'safe':11 'schema':40 'storag':3,14,51,58 'support':46 'target':21 'type':10,34 'type-saf':9 'typescript':31,59 'v4.0.15':17 'version':2,12,41,57 'versioned-storag':1 'via':15","created_at":"2026-06-07T17:02:53.873219+00:00","updated_at":"2026-06-07T17:02:53.873219+00:00","problems":[{"fix":"Change require('versioned-storage') to import { Storage } from 'versioned-storage'.","cause":"Using require() with an ESM-only package.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/node_modules/versioned-storage/build/index.js from /path/app.js not supported.\nInstead change the require of index.js in /path/app.js to a dynamic import() which is available in all CommonJS modules."},{"fix":"Use named import: import { Storage } from 'versioned-storage'.","cause":"Using default import (Storage) instead of named import { Storage } from 'versioned-storage'.","error":"TypeError: The 'super' argument must be an object or null."},{"fix":"Ensure you have imported Storage correctly and created an instance: const userStorage = new Storage('user', 1);","cause":"Storage instance was not created correctly; possibly using default import or the library failed to load.","error":"Uncaught TypeError: userStorage.read is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/CatChen/versioned-storage#readme","github":"https://github.com/CatChen/versioned-storage","docs":null,"changelog":null,"pypi":null,"npm":"versioned-storage","openapi_spec":null,"status_page":null,"smithery":null,"categories":["storage"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}