Skip to main content

​
Overview

The Storage Service provides an abstract interface for storing and retrieving data across different storage backends. It supports various storage locations (disk, memory, session) and optional secure storage encryption.

​
StorageService

The base abstract class that all storage implementations must extend.

​
Interface

abstract class StorageService {
  abstract get valuesRequireDeserialization(): boolean;
  abstract get<T>(key: string, options?: StorageOptions): Promise<T>;
  abstract has(key: string, options?: StorageOptions): Promise<boolean>;
  abstract save<T>(key: string, obj: T, options?: StorageOptions): Promise<void>;
  abstract remove(key: string, options?: StorageOptions): Promise<void>;
}

​
Properties

​
valuesRequireDeserialization

abstract get valuesRequireDeserialization(): boolean;
Indicates whether values stored in this storage service require deserialization when retrieved.

​
Methods

​
get<T>()

abstract get<T>(key: string, options?: StorageOptions): Promise<T>;
Retrieves a value from storage. Parameters:
  • key (string): The storage key to retrieve
  • options (StorageOptions, optional): Configuration options for the storage operation
Returns: Promise<T> - The stored value, typed according to the generic parameter Example: 
const userData = await storageService.get<UserData>('user-settings');

​
has()

abstract has(key: string, options?: StorageOptions): Promise<boolean>;
Checks whether a key exists in storage. Parameters:
  • key (string): The storage key to check
  • options (StorageOptions, optional): Configuration options for the storage operation
Returns: Promise<boolean> - True if the key exists, false otherwise Example: 
const exists = await storageService.has('user-settings');
if (exists) {
  // Handle existing data
}

​
save<T>()

abstract save<T>(key: string, obj: T, options?: StorageOptions): Promise<void>;
Saves a value to storage. Parameters:
  • key (string): The storage key to save under
  • obj (T): The value to store
  • options (StorageOptions, optional): Configuration options for the storage operation
Returns: Promise<void> Example: 
await storageService.save('user-settings', { theme: 'dark', language: 'en' });

​
remove()

abstract remove(key: string, options?: StorageOptions): Promise<void>;
Removes a value from storage. Parameters:
  • key (string): The storage key to remove
  • options (StorageOptions, optional): Configuration options for the storage operation
Returns: Promise<void> Example: 
await storageService.remove('user-settings');

​
ObservableStorageService

An interface that extends storage services with observable update streams.

​
Interface

interface ObservableStorageService {
  get updates$(): Observable<StorageUpdate>;
}

​
Properties

​
updates$

get updates$(): Observable<StorageUpdate>;
Provides an observable stream of storage updates that have occurred in this storage service or in the underlying storage backend. Returns: Observable<StorageUpdate> - Stream of storage update events Example: 
storageService.updates$.subscribe((update) => {
  console.log(`Key ${update.key} was ${update.updateType}`);
});

​
Types

​
StorageOptions

type StorageOptions = {
  storageLocation?: StorageLocation;
  useSecureStorage?: boolean;
  userId?: string;
  htmlStorageLocation?: HtmlStorageLocation;
  keySuffix?: string;
};
Configuration options for storage operations. Properties:
  • storageLocation (StorageLocation, optional): The location where data should be stored (disk, memory, or both)
  • useSecureStorage (boolean, optional): Whether to use encrypted secure storage
  • userId (string, optional): User ID to scope the storage key to a specific user
  • htmlStorageLocation (HtmlStorageLocation, optional): HTML5 storage location (local, session, or memory)
  • keySuffix (string, optional): Suffix to append to the storage key

​
StorageUpdate

type StorageUpdate = {
  key: string;
  updateType: StorageUpdateType;
};
Represents a storage update event. Properties:
  • key (string): The storage key that was updated
  • updateType (StorageUpdateType): The type of update that occurred

​
StorageUpdateType

type StorageUpdateType = "save" | "remove";
The type of storage update operation.

​
StorageLocation

enum StorageLocationEnum {
  Both = "both",
  Disk = "disk",
  Memory = "memory",
}
Specifies where data should be persisted.
  • Both: Store in both disk and memory
  • Disk: Store on disk for persistence across sessions
  • Memory: Store in memory only (cleared on restart)

​
HtmlStorageLocation

enum HtmlStorageLocation {
  Local = "local",
  Memory = "memory",
  Session = "session",
}
Specifies HTML5 storage location for browser-based implementations.
  • Local: Use localStorage (persists across sessions)
  • Memory: Use in-memory storage (cleared on page reload)
  • Session: Use sessionStorage (persists for session only)

​
Usage Examples

​
Basic Storage Operations

// Save data
await storageService.save('user-preferences', {
  theme: 'dark',
  notifications: true
});

// Retrieve data
const prefs = await storageService.get<UserPreferences>('user-preferences');

// Check existence
if (await storageService.has('user-preferences')) {
  // Key exists
}

// Remove data
await storageService.remove('user-preferences');

​
Using Storage Options

// Save to secure storage for a specific user
await storageService.save(
  'auth-token',
  token,
  {
    useSecureStorage: true,
    userId: 'user-123',
    storageLocation: StorageLocationEnum.Disk
  }
);

// Retrieve from memory storage
const cachedData = await storageService.get(
  'cache-key',
  { storageLocation: StorageLocationEnum.Memory }
);

​
Observing Storage Updates

// Subscribe to all storage updates
storageService.updates$.subscribe((update) => {
  if (update.updateType === 'save') {
    console.log(`Data saved to ${update.key}`);
  } else if (update.updateType === 'remove') {
    console.log(`Data removed from ${update.key}`);
  }
});

// Filter updates for specific keys
storageService.updates$
  .pipe(filter(update => update.key === 'user-settings'))
  .subscribe((update) => {
    console.log('User settings changed');
  });

Build docs developers (and LLMs) love

Get started for freeTalk to us