js/store
js/store.ts
fino:store — provider-owned key/value storage with optional capabilities.
Store is the smallest shared persistence contract in Fino. Keys are
strings and values are chosen by the provider: the interface does not
require JSON serialization, cloning, persistence, or a particular wire
representation. Uint8Array is a first-class value, so stores can expose
raw binary backends without base64 conversion.
Capabilities
Plain stores provide read, write, delete, deterministic listing, and namespaces. Providers may additionally expose:
atomic, for opaque version tokens and checked multi-key commits; andexpiration, for provider-managed TTL, including TTL writes inside atomic commits.
Consumers require only the capabilities their correctness depends on.
Versions are concurrency tokens, not retained revision history. Cache policy
lives in fino:cache and delegates expiry to expiration when available.
memoryStore() retains values by reference and performs no encoding.
sqliteStore() owns its representation and defaults to a binary codec that
supports ordinary JSON-like values plus nested Uint8Array values. Callers
can replace that codec for domain-specific data.
import { memoryStore, sqliteStore } from 'fino:store';
const memory = memoryStore();
await memory.set('packet', new Uint8Array([1, 2, 3]));
const sqlite = await sqliteStore({ path: './application.db' });
await sqlite.namespace('users').set('ada', { name: 'Ada' });Interfaces
interface StoreEntry<T = unknown> {
One key/value pair returned by Store.list().
Properties
key: string
Key within the current namespace.
value: T
Value in the representation chosen by the provider.
interface VersionedStoreEntry<T = unknown> extends StoreEntry<T> {
A value paired with an opaque optimistic-concurrency token.
Properties
version: string
Token that changes whenever this key is written successfully.
interface StoreListOptions {
Options for listing records in one namespace.
Properties
prefix?: string
Return only keys beginning with this prefix. Defaults to every key.
interface StoreCheck {
One precondition for an atomic store commit.
Properties
key: string
Key whose current version is checked.
ifVersion: string | null
Required version, or null when the key must not exist.
interface StoreWrite<T = unknown> {
One value written by an atomic store commit.
Properties
key: string
Key to create or replace.
value: T
Provider-supported value to store.
ttlMs?: number
Provider-managed lifetime in milliseconds.
This option is valid only when the owning store exposes expiration.
interface StoreCommit {
One atomic group of checked writes and deletes.
Properties
checks?: StoreCheck[]
Preconditions evaluated before any mutation.
writes?: StoreWrite[]
Values created or replaced when every check matches.
deletes?: string[]
Keys removed when every check matches. Missing keys are ignored.
interface StoreCommitResult {
Result of a successful atomic commit.
Properties
writes: VersionedStoreEntry[]
Versioned entries produced by writes, in input order.
interface AtomicStoreCapability {
Optional optimistic-concurrency capability exposed by a store provider.
Methods
getEntry<T = unknown>(key: string): Promise<VersionedStoreEntry<T> | null>
Read a value with its current opaque version, or null.
commit(mutation: StoreCommit): Promise<StoreCommitResult | null>
Apply checked writes and deletes atomically, or return null on conflict.
interface StoreExpirationCapability {
Optional provider-managed expiry capability.
Methods
set<T = unknown>(key: string, value: T, ttlMs: number): Promise<void>
Atomically store value with a lifetime of ttlMs milliseconds.
Non-positive lifetimes make the value immediately unavailable.
interface Store {
Generic asynchronous key/value storage.
Providers define value identity and serialization. A memory store may return the exact object that was written, while a remote or persistent provider may decode a new value. Callers that need portable data should choose a value representation accepted by every configured provider.
Methods
get<T = unknown>(key: string): Promise<T | null>
Read key, returning null when it is absent or expired.
set<T = unknown>(key: string, value: T): Promise<void>
Store value unconditionally, clearing any previous expiry.
delete(key: string): Promise<boolean>
Delete key, returning whether it existed.
list<T = unknown>(options?: StoreListOptions): Promise<StoreEntry<T>[]>
List entries in deterministic key order.
namespace(name: string): Store
Return a view over the same provider in a child namespace.
Readonly Properties
readonly atomic?: AtomicStoreCapability
Optional checked-transaction capability.
readonly expiration?: StoreExpirationCapability
Optional native/provider-managed expiry capability.
interface AtomicStore extends Store {
Store whose provider supports checked transactions.
Readonly Properties
readonly atomic: AtomicStoreCapability
Methods
namespace(name: string): AtomicStore
interface ExpiringStore extends Store {
Store whose provider manages entry expiry.
Readonly Properties
readonly expiration: StoreExpirationCapability
Methods
namespace(name: string): ExpiringStore
interface AtomicExpiringStore extends AtomicStore, ExpiringStore {
Store supporting both checked transactions and provider-managed expiry.
Methods
namespace(name: string): AtomicExpiringStore
interface StoreClock {
Clock used by providers that implement expiry locally.
Methods
now(): number
Return the current Unix timestamp in milliseconds.
interface MemoryStoreOptions {
Options for creating an in-memory store.
Properties
namespace?: string
Initial namespace. Defaults to "default".
clock?: StoreClock
Clock used by provider-managed expiry. Defaults to Date.now().
interface StoreCodec {
Provider-specific value codec used by sqliteStore().
Methods
encode(value: unknown): Uint8Array
Encode one value for a SQLite BLOB column.
decode(bytes: Uint8Array): unknown
Decode one SQLite BLOB value.
interface SqliteStoreOptions {
Options for opening a SQLite store.
Properties
path: string
SQLite database path.
namespace?: string
Initial namespace. Defaults to "default".
fs?: FileSystem
Optional filesystem provider for the SQLite VFS.
codec?: StoreCodec
Provider-owned value codec. Defaults to the built-in binary codec.
clock?: StoreClock
Clock used by provider-managed expiry. Defaults to Date.now().
interface SqliteStore extends AtomicExpiringStore {
SQLite store handle that owns its database connection.
Methods
close(): Promise<void>
Close the underlying database connection.
Functions
function memoryStore(options: MemoryStoreOptions = {}): AtomicExpiringStore
Create an in-memory store that retains values without encoding or cloning.
function sqliteStore(options: SqliteStoreOptions): Promise<SqliteStore>
Open a SQLite store with provider-owned binary serialization and TTL.