Storage

A unified, namespaced storage API that wraps localStorage, sessionStorage, and cookies behind a single consistent interface. All keys are automatically prefixed, values are JSON-serialized, and local/session entries support optional TTL-based expiration.

Quick Start

Access storage through Aura.storage, which exposes three sub-objects: .local, .session, and .cookie.

js
import aura from 'aura.js';

// Store a value in localStorage (persists across sessions)
aura.storage.local.set('user', { name: 'Alex', role: 'admin' });

// Retrieve it later
const user = aura.storage.local.get('user');
console.log(user.name); // "Alex"

// Store with a 5-minute TTL (auto-expires)
aura.storage.local.set('token', 'abc123', 5 * 60 * 1000);

// Session storage (cleared when tab closes)
aura.storage.session.set('step', 3);

// Cookies
aura.storage.cookie.set('theme', 'dark');

Sub-stores

Aura.storage is an instance of AuraStorage that creates three sub-stores during construction. Each uses the same key prefix (default aura_) to avoid collisions with other libraries.

Property	Type	Description
local	NSStore	Wraps `window.localStorage`. Data persists until explicitly removed.
session	NSStore	Wraps `window.sessionStorage`. Data is cleared when the tab closes.
cookie	CookieStore	Wraps `document.cookie`. Sent to the server with every request.

local and session share the same full API. cookie supports set(), get(), has(), and remove().

set()

Store a value under the given key. Values are automatically JSON-serialized. An optional TTL (in milliseconds) causes the entry to self-expire.

set(key: string, value: unknown, ttlMs?: number): void

Param	Type	Description
key	string	The storage key (auto-prefixed).
value	unknown	Any JSON-serializable value.
ttlMs	number?	Optional time-to-live in milliseconds. Omit for permanent storage.

js
// Permanent storage
aura.storage.local.set('prefs', { theme: 'dark', lang: 'en' });

// Expires in 1 hour
aura.storage.local.set('cache', largePayload, 3600000);

// Cookie with 7-day expiry
aura.storage.cookie.set('consent', true, 7 * 24 * 60 * 60 * 1000);

get()

Retrieve a stored value. Returns null if the key does not exist, the data is corrupted, or a TTL has expired (the expired entry is automatically cleaned up). Supports an optional generic type parameter for TypeScript users.

get<T = unknown>(key: string): T | null

Param	Type	Description
key	string	The storage key to look up.

Returns: The deserialized value, or null.

ts
// Plain JS
const prefs = aura.storage.local.get('prefs');

// TypeScript with type parameter
interface Prefs { theme: string; lang: string; }
const prefs = aura.storage.local.get<Prefs>('prefs');

// Returns null for missing or expired keys
const gone = aura.storage.local.get('nonexistent'); // null

has()

Check whether a key exists in the store. For local and session, this checks for the raw entry (even if expired). For cookie, it attempts to parse the value and returns false if the cookie is missing.

has(key: string): boolean

Param	Type	Description
key	string	The storage key to check.

Returns: true if the key exists, false otherwise.

js
if (aura.storage.local.has('user')) {
  console.log('User data found');
}

remove()

Delete a single entry by key.

remove(key: string): void

Param	Type	Description
key	string	The key to remove.

js
aura.storage.local.remove('token');
aura.storage.cookie.remove('consent');

keys()

List all keys belonging to this namespace. Only returns keys that match the current prefix, with the prefix stripped from the result. Available on local and session only.

keys(): string[]

Returns: An array of unprefixed key names.

js
const allKeys = aura.storage.local.keys();
console.log(allKeys); // ["user", "prefs", "cache"]

size()

Returns the number of entries in the namespaced store. A convenience wrapper around keys().length. Available on local and session only.

size(): number

Returns: The number of stored entries.

js
console.log(aura.storage.local.size()); // 3

clear()

Remove all entries in this namespace. Only deletes keys that match the current prefix, leaving other localStorage / sessionStorage entries untouched. Available on local and session only.

clear(): void

js
// Wipe all Aura localStorage entries
aura.storage.local.clear();

// Wipe all Aura session entries
aura.storage.session.clear();

console.log(aura.storage.local.size()); // 0

The cookie sub-store provides a simplified interface over document.cookie. Cookies are set with path=/ and SameSite=Lax by default. Values are JSON-serialized and URI-encoded.

Available methods: set(), get(), has(), remove(). The keys(), size(), and clear() methods are not available on the cookie store.

js
// Set a cookie (session cookie, no expiry)
aura.storage.cookie.set('theme', 'dark');

// Set a cookie that expires in 30 days
aura.storage.cookie.set('lang', 'en', 30 * 24 * 60 * 60 * 1000);

// Read it back
const theme = aura.storage.cookie.get('theme'); // "dark"

// Delete a cookie
aura.storage.cookie.remove('theme');

Custom Prefix

By default, all keys are prefixed with aura_. You can customize this when initializing Aura to avoid collisions with other Aura instances or libraries.

js
// During Aura init
aura.init({ storagePrefix: 'myapp_' });

// Now keys are prefixed with "myapp_"
aura.storage.local.set('user', 'Alex');
// Actual localStorage key: "myapp_user"

// Or create a standalone instance
import { AuraStorage } from 'aura.js/storage';
const store = new AuraStorage('v2_');