Developer Documentation/SDK Reference/Storage API

Storage API

Simple key-value storage for settings and preferences.

Overview

The Storage API provides a simple key-value store scoped to your extension. It's perfect for settings, preferences, and simple data that doesn't need the complexity of a database.

Storage data is scoped to your extension and persists across sessions.

Basic Usage

Get, set, and remove values with simple async methods:

import { useHaexClient } from '@haex-space/vault-sdk/vue'

const client = useHaexClient()

// Store a value
await client.storage.set('username', 'john_doe')

// Retrieve a value
const username = await client.storage.get('username')
console.log(username) // 'john_doe'

// Remove a value
await client.storage.remove('username')

Available Methods

get() 

// get(key: string): Promise<string | null>
// Retrieves a value by key, returns null if not found

const value = await client.storage.get('theme')

if (value !== null) {
  console.log('Theme:', value)
} else {
  console.log('No theme set, using default')
}

set() 

// set(key: string, value: string): Promise<void>
// Stores a key-value pair

await client.storage.set('theme', 'dark')
await client.storage.set('sidebar_collapsed', 'true')
await client.storage.set('last_sync', Date.now().toString())

remove() 

// remove(key: string): Promise<void>
// Removes a key-value pair

await client.storage.remove('theme')
await client.storage.remove('temporary_data')

keys() 

// keys(): Promise<string[]>
// Returns all stored keys

const allKeys = await client.storage.keys()
console.log(allKeys) // ['theme', 'sidebar_collapsed', 'last_sync']

// Iterate over all stored data
for (const key of allKeys) {
  const value = await client.storage.get(key)
  console.log(`${key}: ${value}`)
}

clear() 

// clear(): Promise<void>
// Removes all stored data for this extension

await client.storage.clear()

Storing JSON Data

Storage values are strings. Serialize complex data with JSON:

// Store JSON data by serializing it
const settings = {
  theme: 'dark',
  fontSize: 14,
  notifications: true
}

await client.storage.set('settings', JSON.stringify(settings))

// Retrieve and parse JSON
const storedSettings = await client.storage.get('settings')
if (storedSettings) {
  const parsed = JSON.parse(storedSettings)
  console.log(parsed.theme) // 'dark'
}

Remember to handle JSON.parse errors for corrupted or invalid data.

Examples

Settings Manager

A reusable composable for managing application settings:

// settings.ts - A simple settings manager
import { useHaexClient } from '@haex-space/vault-sdk/vue'

interface AppSettings {
  theme: 'light' | 'dark' | 'system'
  fontSize: number
  autoSave: boolean
  language: string
}

const defaultSettings: AppSettings = {
  theme: 'system',
  fontSize: 14,
  autoSave: true,
  language: 'en'
}

export function useSettings() {
  const client = useHaexClient()
  const settings = ref<AppSettings>(defaultSettings)

  async function loadSettings() {
    const stored = await client.storage.get('app_settings')
    if (stored) {
      settings.value = { ...defaultSettings, ...JSON.parse(stored) }
    }
  }

  async function saveSettings(newSettings: Partial<AppSettings>) {
    settings.value = { ...settings.value, ...newSettings }
    await client.storage.set('app_settings', JSON.stringify(settings.value))
  }

  async function resetSettings() {
    settings.value = defaultSettings
    await client.storage.remove('app_settings')
  }

  return { settings, loadSettings, saveSettings, resetSettings }
}

Simple Cache

Cache data with expiration:

// Simple cache with expiration
const CACHE_PREFIX = 'cache_'
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

interface CacheEntry<T> {
  data: T
  expires: number
}

async function getCached<T>(key: string): Promise<T | null> {
  const stored = await client.storage.get(CACHE_PREFIX + key)
  if (!stored) return null

  const entry: CacheEntry<T> = JSON.parse(stored)
  if (Date.now() > entry.expires) {
    await client.storage.remove(CACHE_PREFIX + key)
    return null
  }

  return entry.data
}

async function setCached<T>(key: string, data: T, ttl = CACHE_TTL) {
  const entry: CacheEntry<T> = {
    data,
    expires: Date.now() + ttl
  }
  await client.storage.set(CACHE_PREFIX + key, JSON.stringify(entry))
}

// Usage
const userData = await getCached<User>('user_profile')
if (!userData) {
  const fresh = await fetchUserProfile()
  await setCached('user_profile', fresh)
}
←Database APIFilesystem API→