picospa.sessionStore
Low-level API for sessionStorage operations with JSON serialization and safe error handling.
writeArray()
Method signature: writeArray(sessionKey, array)
Stores an array in sessionStorage as JSON.
Parameters
sessionKey(string) - The key to store the data under in sessionStoragearray(Array) - The array to store
Description
- Serializes the array using
JSON.stringify() - Stores the result in
sessionStorageusing the provided key - Overwrites any existing data at that key
Example
picospa.sessionStore.writeArray('my-list', ['item1', 'item2', 'item3']);
// Stores: sessionStorage['my-list'] = '["item1","item2","item3"]'
Error Handling
- No explicit error handling - relies on browser's sessionStorage behavior
- May throw if sessionStorage is unavailable or quota exceeded
readArray()
Method signature: readArray(sessionKey)
Reads an array from sessionStorage with safe JSON parsing.
Parameters
sessionKey(string) - The key to read from sessionStorage
Returns
Array- The stored array, or empty array[]if not found or invalid
Description
- Retrieves string value from
sessionStorage.getItem() - Attempts to parse as JSON using
_safeJsonParse() - Returns empty array if key doesn't exist or parsing fails
- Provides safe fallback for missing or corrupted data
Example
const [hasValue, items] = picospa.sessionStore.readArray('my-list');
// Returns: [true, ['item1', 'item2', 'item3']] or [false, []] if nothing was stored
writeMap()
Method signature: writeMap(sessionKey, map)
Stores a Map object in sessionStorage as JSON.
Parameters
sessionKey(string) - The key to store the data under in sessionStoragemap(Map) - The Map object to store
Description
- Converts Map to array of entries using spread operator:
[...map] - Serializes the entries array using
JSON.stringify() - Stores the result in
sessionStorage
Example
const myMap = new Map([['key1', 'value1'], ['key2', 'value2']]);
picospa.sessionStore.writeMap('my-map', myMap);
// Stores: sessionStorage['my-map'] = '[["key1","value1"],["key2","value2"]]'
readMap()
Method signature: readMap(sessionKey)
Reads a Map object from sessionStorage with safe JSON parsing.
Parameters
sessionKey(string) - The key to read from sessionStorage
Returns
Map- The stored Map object, or empty Map if not found or invalid
Description
- Retrieves string value from
sessionStorage.getItem() - Attempts to parse as JSON using
_safeJsonParse() - Creates new Map from parsed entries array
- Returns empty Map if key doesn't exist or parsing fails
Example
const [hasValue, myMap] = picospa.sessionStore.readMap('my-map');
// Returns: Map with entries or new Map() if not found
console.log(myMap.get('key1')); // 'value1'
writeString()
Method signature: writeString(sessionKey, value)
Stores a string value directly in sessionStorage.
Parameters
sessionKey(string) - The key to store the data under in sessionStoragevalue(string) - The string value to store
Description
- Stores the string value directly using
sessionStorage.setItem() - No JSON serialization needed for plain strings
- Overwrites any existing data at that key
Example
picospa.sessionStore.writeString('theme', 'dark');
// Stores: sessionStorage['theme'] = 'dark'
readString()
Method signature: readString(sessionKey)
Reads a string value from sessionStorage.
Parameters
sessionKey(string) - The key to read from sessionStorage
Returns
string- The stored string, or empty string''if not found
Description
- Retrieves value directly using
sessionStorage.getItem() - Returns empty string if key doesn't exist (when
getItem()returnsnull) - No JSON parsing needed for plain strings
Example
const [hasValue, theme] = picospa.sessionStore.readString('theme');
// Returns: `[true, 'dark']` or `[false, '']` if not found
_safeJsonParse() (Internal)
Method signature: _safeJsonParse(value)
Internal utility function for safe JSON parsing.
Parameters
value(string) - The JSON string to parse
Returns
any- The parsed object, ornullif parsing fails
Description
- Attempts to parse JSON using
JSON.parse() - Uses try/catch to handle malformed JSON gracefully
- Returns
nullon any parsing error - Used internally by
readArray()andreadMap()
Example
// Internal usage only
const result = picospa.sessionStore._safeJsonParse('{"key": "value"}');
// Returns: {key: "value"} or null if invalid
Storage Patterns
Key Naming Convention
PicoSPA uses consistent key naming patterns:
${key} - scroll.restorefor scroll positions${key} - dialog.reopenfor details statepicospa-color-schemefor theme preference
Error Resilience
All read operations provide safe fallbacks:
- Arrays default to
[] - Maps default to
new Map() - Strings default to
'' - JSON parsing errors are caught and handled
Browser Support
- Requires
sessionStorageAPI support - Uses native JSON methods for serialization
- Compatible with modern browsers that support Map objects