jsonStorage

Wrapper around localStorage that stores and reads values as JSON objects. Supports merge-by-default for objects, push-by-default for arrays, and a force flag for clean replacement.

import jsonStorage from '@pim.sk/utils/jsonStorage.mjs'

Usage

getItem( name ) | getItem( name ).key

Reads a stored JSON entry from localStorage. Returns the full object, or access a specific key directly. Returns {} if the entry does not exist.

jsonStorage.getItem( "bdt" )
// → { limit: 15, ord: 2 }

jsonStorage.getItem( "bdt" ).ord
// → 2

jsonStorage.getItem( "missing" )
// → {}

In the example, use .setItem to save to localStorage, then refresh the page and see .getItem.

jsonStorage.getItem( "bdt" )        // → { limit: 15, ord: 2 }
jsonStorage.getItem( "bdt" ).ord    // → 2
jsonStorage.getItem( "missing" )    // → {}

setItem( name, values ) — merge

Stores values as JSON under the given localStorage key. Calling setItem multiple times merges the objects — existing keys are preserved, new keys are added.

jsonStorage.setItem( "bdt", { limit: 15, ord: 2 } )
// localStorage: { limit: 15, ord: 2 }

jsonStorage.setItem( "bdt", { ord: 3 } )
// localStorage: { limit: 15, ord: 3 }   ← ord updated, limit kept

jsonStorage.setItem( "bdt", { limit: 15, ord: 2 } )
// → { limit: 15, ord: 2 }

jsonStorage.setItem( "bdt", { ord: 3 } )
// → { limit: 15, ord: 3 }   ← merged

setItem( name, values, force ) — replace

force: false (default) — merges into existing object. force: true — removes the entry first, then stores the new values. Use when you need a clean replace.

jsonStorage.setItem( "bdt", { a: 1, b: 2 } )
jsonStorage.setItem( "bdt", { c: 3 } )
// merge → { a: 1, b: 2, c: 3 }

jsonStorage.setItem( "bdt", { a: 1, b: 2 } )
jsonStorage.setItem( "bdt", { c: 3 }, true )  // force
// replace → { c: 3 }

jsonStorage.setItem( "bdt", { a: 1, b: 2 } )
jsonStorage.setItem( "bdt", { c: 3 } )        // → { a:1, b:2, c:3 }

jsonStorage.setItem( "bdt", { a: 1, b: 2 } )
jsonStorage.setItem( "bdt", { c: 3 }, true )  // → { c:3 }

setItem — array values

When value is an array, items are pushed into the existing stored array. Each call appends — it does not replace.

jsonStorage.setItem( "list", [1, 2, 3] )
// → [1, 2, 3]

jsonStorage.setItem( "list", [4, 5] )
// → [1, 2, 3, 4, 5]   ← pushed, not replaced

jsonStorage.setItem( "list", [4, 5], true )  // force
// → [4, 5]

jsonStorage.setItem( "list", [1, 2, 3] )  // → [1, 2, 3]
jsonStorage.setItem( "list", [4, 5] )     // → [1, 2, 3, 4, 5]
jsonStorage.setItem( "list", [4, 5], true ) // → [4, 5]

deleteItem( name, key )

Removes a single key from the stored object. The entry remains in localStorage — only the specified key is deleted.

jsonStorage.setItem( "bdt", { limit: 15, ord: 2, page: 1 } )
// → { limit: 15, ord: 2, page: 1 }

jsonStorage.deleteItem( "bdt", "ord" )
// → { limit: 15, page: 1 }

jsonStorage.deleteItem( "bdt", "limit" )
// → { page: 1 }

jsonStorage.setItem( "bdt", { limit: 15, ord: 2, page: 1 } )

jsonStorage.deleteItem( "bdt", "ord" )
// → { limit: 15, page: 1 }

removeItem( name )

Removes the entire localStorage entry. getItem() then returns {} (empty object).

jsonStorage.setItem( "bdt", { limit: 15 } )
jsonStorage.getItem( "bdt" )   // → { limit: 15 }

jsonStorage.removeItem( "bdt" )
jsonStorage.getItem( "bdt" )   // → {}

jsonStorage.setItem( "bdt", { limit: 15 } )
jsonStorage.removeItem( "bdt" )
jsonStorage.getItem( "bdt" )    // → {}

Utils (@pim.sk/utils)