atom.storage

library0.5.5jsnpmunverified

A reactive Storage implementation for Atoms that persists non-critical data like user selections across sessions. v0.5.5 stable, low release cadence. Key differentiator: designed for the calmm-js Atom ecosystem (bacon.atom or kefir.atom), provides sharing of atoms with the same key, schema validation, expiry, and debounced writes — not a general-purpose storage wrapper.

storage

npm install atom.storage

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · ATOM.STORAGE

atom.storage

storagejavascriptv0.5.5

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.

Stored

✓ import Stored from 'atom.storage'

✗ const Stored = require('atom.storage')

ESM-only; no named exports.

Stored

✓ import Stored from 'atom.storage'

✗ import { Stored } from 'atom.storage'

It's a default export, not named.

Atom

✓ import Atom from 'bacon.atom'

✗ import Atom from 'atom.storage'

Atom must be provided separately; not part of this package.

Creates a Stored atom backed by localStorage using bacon.atom, reads initial value, and modifies it to trigger persistence.

import Stored from 'atom.storage'; import Atom from 'bacon.atom'; const defaultValue = { count: 0 }; const stored = Stored({ key: 'my-app:counter', value: defaultValue, Atom, storage: localStorage }); console.log(stored.get()); // defaultValue or restored value stored.modify(val => ({ count: val.count + 1 })); // persists to localStorage after modification

Debug

Known issues

gotchaDefault value is NOT stored initially; only stored after a modify that results in a new value.

fix

Call modify() after creation if immediate persistence is needed.

affects: >=0.0.0

gotchaSharing: two Stored calls with same key and storage return the exact same object (===).

fix

Be aware that atoms are shared; avoid creating separate instances expecting different identities.

affects: >=0.0.0

gotchaThe value is JSON.stringify'd; non-serializable values (e.g. undefined, functions) may cause errors.

fix

Ensure values are JSON-serializable.

affects: >=0.0.0

gotchaIf no Atom library is provided, the package does not work. No default dependency included.

fix

Install and import either 'bacon.atom' or 'kefir.atom'.

affects: >=0.0.0

gotchaThe 'time' option for expiry does not automatically clean up expired values on read? It uses stored timestamp.

fix

Understand expiry logic: checks timestamps on creation, may still read stale if not re-created.

affects: >=0.0.0

Errors

Common errors & fixes

TypeError: Cannot destructure property 'get' of 'undefined' or 'null'

Forgot to pass an Atom implementation

fix

Ensure you import and pass Atom in the options object.

SyntaxError: JSON.parse: unexpected character at line 1 column 1 of the JSON data

Stored value in localStorage is corrupted or not JSON

fix

Clear the storage key manually: localStorage.removeItem('your-key')

atom.storage: Attempted to set value with non-serializable content.

Trying to store a value containing functions or undefined

fix

Ensure the value is a plain JSON-serializable object or primitive.

Upgrade

Version history

0.5.5latest on npm

Audit

Dependencies

bacon.atomoptionalAtom implementation required (or kefir.atom)

kefir.atomoptionalAlternative Atom implementation

Agent activity

46 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/calmm-js/atom.storage ↗

packageatom.storage ↗

homepagehttps://github.com/calmm-js/atom.storage#readme ↗