Storage adapters

Storage adapters control how FFDB persists auth and session-related state across runtimes. This reference covers adapter contracts, built-ins, and practical choices.

Interface

type StorageAdapter = {
  get(key: string): Promise<string | null> | string | null
  set(key: string, value: string): Promise<void> | void
  remove(key: string): Promise<void> | void
}

Built-in adapters

import { memoryStorage, browserStorage } from 'ffdb-client'

const mem = memoryStorage()
const local = browserStorage('local')
const session = browserStorage('session')
const indexeddb = browserStorage('indexeddb')

Behavior reference

Name
memoryStorage()
Description
In-memory only. Fast and simple, but resets on reload/process exit.
Name
browserStorage('local')
Description
Uses localStorage. Persists across browser restarts.
Name
browserStorage('session')
Description
Uses sessionStorage. Tab-scoped persistence.
Name
browserStorage('indexeddb')
Description
Async IndexedDB-backed storage for browser environments that prefer async storage semantics.

End-to-end usage

import { browserStorage, createClient } from 'ffdb-client'
import type { Database } from './ffdb.types'

const client = await createClient<Database>({
  config: {
    apiUrl: import.meta.env.VITE_FFDB_API_URL,
  },
  storage: browserStorage('local'),
})

const session = await client.auth.getSession()
console.log(session.data)

Custom adapter example

const customStorageAdapter = {
  async get(key: string) {
    return await myKV.get(key)
  },
  async set(key: string, value: string) {
    await myKV.set(key, value)
  },
  async remove(key: string) {
    await myKV.delete(key)
  },
}

Decision guide

Use memoryStorage for tests and ephemeral sessions.
Use browserStorage('local') for most web apps.
Use browserStorage('session') when tab isolation is a requirement.
Provide a custom adapter in React Native, Node, and desktop shells.

Storage adapters persist small client state. They are not replacements for offline table replication.