walkeros-understanding-stores

Understanding walkerOS Stores

Overview

Stores provide key-value storage that other components (sources, transformers, destinations) consume via environment injection. They are the 4th component type in Flow.Json alongside sources, transformers, and destinations.

Core principle: Stores are passive infrastructure. They don't process events or participate in chains — they provide state that other components read and write.

Store interface

See packages/core/src/types/store.ts for the canonical interface.

Instance

Property	Type	Purpose	Required
type	string	Store type identifier	Required
config	Store.Config	Settings and env	Required
get	(key) => StoreValue | undefined	Read a value	Required
set	(key, value, ttl?) => void	Write a value (optional TTL)	Required
delete	(key) => void	Remove a value	Required
destroy	DestroyFn	Cleanup on shutdown	Optional

All methods can be sync or async (return Promise).

Value type and file mode

Stores hold one canonical value type: structured data (StoreValue), with binary (Uint8Array) as a first-class leaf. StoreValue is string | number | boolean | null | Uint8Array | StoreValue[] | { [key: string]: StoreValue } (undefined is reserved as the "miss" sentinel and is never a stored value). A shared core codec (serializeStoreValue / deserializeStoreValue) round-trips that value to and from each backing.

Store.Config.file?: boolean (default false) picks the mode, decided once at init:

• Structured (default): values are StoreValue data, serialized by the shared codec.
• File (file: true): a byte-native backend (fs, S3, GCS) persists raw bytes byte-exact. set() accepts a Uint8Array or string and stores it untouched; get() hands the exact bytes back. Use for serving assets such as walker.js. The Sheets store is structured-only and rejects file: true at init.