javascript 49 lines · 9 steps

Versioned state migrations in localStorage

A persistence layer that upgrades old saved state through numbered migration steps before handing it to the app.

Explained by highlit
Intermediate migrations persistence versioning localstorage error-handling
1const STORAGE_KEY = "app_state";
2const CURRENT_VERSION = 3;
3 
4const migrations = {
5 1: (state) => ({ ...state, theme: state.theme ?? "light" }),
6 2: (state) => ({ ...state, filters: { query: state.search ?? "", tags: [] }, search: undefined }),
7 3: (state) => ({ ...state, sidebar: { collapsed: false, width: 240 } }),
8};
9 
10function migrate(state, fromVersion) {
11 let migrated = state;
12 for (let v = fromVersion + 1; v <= CURRENT_VERSION; v++) {
13 const step = migrations[v];
14 if (step) migrated = step(migrated);
15 }
16 return migrated;
17}
18 
19export function loadState(defaults) {
20 const raw = localStorage.getItem(STORAGE_KEY);
21 if (!raw) return { ...defaults };
22 
23 try {
24 const { version = 0, data } = JSON.parse(raw);
25 if (version === CURRENT_VERSION) return { ...defaults, ...data };
26 
27 const upgraded = migrate(data, version);
28 const state = { ...defaults, ...upgraded };
29 saveState(state);
30 return state;
31 } catch (err) {
32 console.warn("Corrupt persisted state, resetting", err);
33 localStorage.removeItem(STORAGE_KEY);
34 return { ...defaults };
35 }
36}
37 
38export function saveState(data) {
39 const payload = JSON.stringify({ version: CURRENT_VERSION, data });
40 try {
41 localStorage.setItem(STORAGE_KEY, payload);
42 } catch (err) {
43 if (err.name === "QuotaExceededError") {
44 console.error("localStorage quota exceeded, state not saved");
45 } else {
46 throw err;
47 }
48 }
49}
01 / 01
STEP 01

Walkthrough

Space play ←→ step click any line
Three takeaways
  1. 1Tagging persisted data with a version number lets you evolve its shape without breaking existing users.
  2. 2Chaining small pure migration functions keeps each schema change isolated and testable.
  3. 3Persistence code should treat stored data as untrusted and degrade gracefully to defaults on corruption.

Related explainers

go 
func RecoveryHandler(logger *zap.Logger) gin.HandlerFunc {
	return gin.CustomRecovery(func(c *gin.Context, recovered any) {
		var brokenPipe bool
		if ne, ok := recovered.(*net.OpError); ok {

A panic-recovery middleware in Gin

middleware panic-recovery structured-logging
Intermediate 6 steps
php 
<?php
 
namespace App\Http\Controllers;
 

Verifying Stripe webhooks in Laravel

webhooks signature-verification event-dispatch
Intermediate 8 steps
javascript 
const asyncHandler = (fn) => (req, res, next) => {
  Promise.resolve(fn(req, res, next)).catch(next);
};
 

Async error handling in Express routes

async-await error-handling middleware
Intermediate 7 steps
rust 
use axum::{
    extract::{Path, State},
    http::StatusCode,
    routing::get,

Building a JSON user API in Axum

routing shared-state json-serialization
Intermediate 8 steps
javascript 
async function mapWithConcurrency(items, limit, worker) {
  const results = new Array(items.length);
  let nextIndex = 0;
 

Bounded-concurrency async map in JavaScript

concurrency async-await promises
Intermediate 7 steps
rust 
use axum::{
    body::Bytes,
    extract::State,
    http::StatusCode,

Handling raw byte uploads in Axum

extractors shared-state request-limits
Intermediate 7 steps

Share this explainer

Here's the card — post it anywhere.

Versioned state migrations in localStorage — share card
Made with highlit — turn any snippet into a walkthrough like this in about a minute.
Explain your code