fs-storage

localStorage service factory with prefix namespacing.

npm install @script-development/fs-storage

What It Does

fs-storage wraps localStorage in a service that namespaces all keys under a prefix. This prevents key collisions when multiple applications or modules share the same browser storage.

Basic Usage

import {createStorageService} from '@script-development/fs-storage';

const storage = createStorageService('myapp');

// Stores as "myapp:username" in localStorage
storage.put('username', 'Alice');

// Retrieves from "myapp:username"
const name = storage.get<string>('username'); // "Alice"

// Remove a single key
storage.remove('username');

// Remove all keys with this prefix
storage.clear();

Automatic Serialization

The service handles JSON serialization automatically. You can store any value that's JSON-serializable:

// Objects and arrays are JSON-stringified on put, parsed on get
storage.put('settings', {theme: 'dark', language: 'en'});
const settings = storage.get<Settings>('settings'); // { theme: "dark", language: "en" }

// Numbers, booleans, arrays — all work
storage.put('count', 42);
storage.put('enabled', true);
storage.put('tags', ['admin', 'editor']);

Default Values

The get method accepts a default value that is returned when the key doesn't exist:

// Returns "guest" if "role" hasn't been stored
const role = storage.get('role', 'guest'); // "guest"

Smart parsing behavior

When you pass a string default value, the stored value is returned as a raw string (no JSON parsing). When you pass a non-string default or no default, the service attempts to JSON-parse the stored value. This lets you store and retrieve both plain strings and complex objects predictably.

Prefix Namespacing

The prefix is prepended to every key with a : separator:

const userStorage = createStorageService('user');
const cacheStorage = createStorageService('cache');

userStorage.put('name', 'Alice'); // localStorage key: "user:name"
cacheStorage.put('name', 'stale'); // localStorage key: "cache:name"

userStorage.get('name'); // "Alice"
cacheStorage.get('name'); // "stale"

// clear() only removes keys with the matching prefix
userStorage.clear(); // removes "user:*", leaves "cache:*" intact

This is particularly useful when:

• Multiple apps run on the same domain
• Different features store data independently
• You want to clear one feature's cache without affecting others

Used By Other Packages

fs-storage provides the storage shape that other packages accept. For example, fs-theme needs a storage contract — and fs-storage matches it naturally:

import {createStorageService} from '@script-development/fs-storage';
import {createThemeService} from '@script-development/fs-theme';

const storage = createStorageService('myapp');
const theme = createThemeService(storage);
// Theme preference is persisted under "myapp:theme"

fs-adapter-store also uses storage for offline persistence of domain state.

API Reference

createStorageService(prefix)

Parameter	Type	Description
prefix	string	Required. Prepended to all keys as prefix:key

Service Methods

Method	Returns	Description
put(key, value)	void	Store a value (JSON-stringified if not a string)
get<T>(key)	T | undefined	Retrieve a value, attempting JSON parse
get<T>(key, defaultValue)	T	Retrieve with fallback default
remove(key)	void	Remove a single key
clear()	void	Remove all keys with this prefix