Docs
API Reference

API Reference

Legend:

  • ? means optional

initStore

Create a standalone store instance without React.

import { initStore } from "floppy-disk";
 
const store = initStore(initialState, options);

Parameters

  • initialState : The initial state of the store, must be an object
  • options?
    • onFirstSubscribe? : Called when the first subscriber is added
    • onSubscribe? : Called every time a subscriber is added
    • onUnsubscribe? : Called every time a subscriber is removed
    • onLastUnsubscribe? : Called when the last subscriber is removed
    • onStateChange? : Called whenever state changes (does not register as a subscriber)
    • allowSetStateServerSide? : Allow setState on server (disabled by default)

Return Value

  • store : Store Instance
    • store.getState() : Get the current state
    • store.setState(value) : Update the state (accepts partial object or updater function)
    • store.subscribe(fn) : Subscribe to state changes (returns unsubscribe function)
    • store.getSubscriberCount() : Get the number of subscribers

createStore

Creates a store with built-in React bindings.

import { createStore } from "floppy-disk/react";
 
const useStore = createStore(initialState, options);

Parameters

  • initialState : The initial state of the store, must be an object
  • options?
    • onFirstSubscribe? : Called when the first subscriber is added
    • onSubscribe? : Called every time a subscriber is added
    • onUnsubscribe? : Called every time a subscriber is removed
    • onLastUnsubscribe? : Called when the last subscriber is removed
    • onStateChange? : Called whenever state changes (does not register as a subscriber)
    • allowSetStateServerSide? : Allow setState on server (disabled by default)

Return Value

  • useStore()

    • Parameters (optional)
      • initialState? : Initial state applied once on first render (also updates the store)
    • Return Value
      • state : Proxied state with automatic tracking (component re-renders only when accessed values change)

  • useStore methods

    • useStore.getState() : Get the current state
    • useStore.setState(value) : Update the state (accepts partial object or updater function)
    • useStore.subscribe(fn) : Subscribe to state changes (returns unsubscribe function)
    • useStore.getSubscriberCount() : Get the number of subscribers

createStores

Creates a factory for multiple stores identified by a key.

import { createStores } from "floppy-disk/react";
 
const getStore = createStores(initialState, options);
const useStore = getStore(key);

Parameters

  • initialState : The initial state for each store instance, must be an object
  • options?
    • onFirstSubscribe? : Called when the first subscriber is added
    • onSubscribe? : Called every time a subscriber is added
    • onUnsubscribe? : Called every time a subscriber is removed
    • onLastUnsubscribe? : Called when the last subscriber is removed
    • onStateChange? : Called whenever state changes (does not register as a subscriber)
    • allowSetStateServerSide? : Allow setState on server (disabled by default)

Return Value

  • getStore(key?)

    • Parameters
      • key? : Unique identifier for the store instance (object, will be hashed)
    • Return Value
      • useStore : A store bound to the given key (lazily created and cached)

  • useStore()

    • Parameters (optional)
      • initialState? : Initial state applied once per store instance (also updates the store once)
    • Return Value
      • state : Proxied state with automatic tracking (component re-renders only when accessed values change)

  • useStore methods

    • useStore.getState() : Get the current state
    • useStore.setState(value) : Update the state (accepts partial object or updater function)
    • useStore.subscribe(fn) : Subscribe to state changes (returns unsubscribe function)
    • useStore.getSubscriberCount() : Get the number of subscribers
    • useStore.delete() : Delete the store instance (only works when no active subscribers)

  • useStore properties

    • useStore.key : The original key object
    • useStore.keyHash : Deterministic hash of the key

Notes

  • Each unique key creates an isolated store
  • Stores are lazily created and cached
  • .delete() will reset state and remove the store from cache
  • Cannot delete a store while it still has active subscribers

createQuery

Creates a query factory for managing async state with caching and lifecycle.

import { createQuery } from "floppy-disk/react";
 
const getQuery = createQuery(queryFn, options);
const useQuery = getQuery(variable);

Parameters

  • queryFn : Async function that returns data
    • Receives (variable, currentState, variableHash)
  • options?
    • staleTime? : Time (ms) data is considered fresh (default: 2500)
    • gcTime? : Time (ms) before unused queries are garbage collected (default: 5 minutes)
    • revalidateOnFocus? : Revalidate on window focus (default: true)
    • revalidateOnReconnect? : Revalidate on network reconnect (default: true)
    • onSuccess? : Called when query succeeds
    • onError? : Called when query fails and no more retries
    • onSettled? : Called after success or final failure
    • shouldRetry? : Control retry behavior (default: retry once with 1500ms delay)
    • onFirstSubscribe? : Called when the first subscriber is added
    • onSubscribe? : Called every time a subscriber is added
    • onUnsubscribe? : Called every time a subscriber is removed
    • onLastUnsubscribe? : Called when the last subscriber is removed
    • onStateChange? : Called whenever state changes (does not register as a subscriber)
    • allowSetStateServerSide? : Allow setState on server (disabled by default)

Return Value

  • getQuery(variable?)

    • Parameters
      • variable? : Query parameter (object, used as key)
    • Return Value
      • useQuery : Query instance (lazily created and cached per variable)

  • useQuery()

    • Parameters (optional)
      • initialData? : Initial data (applied once per query instance)
      • initialDataIsStale? : Treat initial data as stale (default: false)
      • revalidateOnMount? : Auto revalidate on mount (default: true)
      • keepPreviousData? : Keep previous data during variable change
    • Return Value
      • state : Proxied query state with automatic tracking

  • useQuery methods

    • useQuery.execute(options?) : Execute query
      • execute always runs if there is no ongoing execution
      • If there is an ongoing execution:
        • overwriteOngoingExecution: true (default) → starts a new execution & ignores the previous one
        • overwriteOngoingExecution: false → reuses the existing promise (deduped)
    • useQuery.revalidate(options?) : Execute only if stale or invalidated
    • useQuery.invalidate(options?) : Mark as invalid (and execute if active)
    • useQuery.reset() : Reset to initial state
    • useQuery.delete() : Delete query (only if no subscribers)
    • useQuery.optimisticUpdate(data) : Apply optimistic data
    • useQuery.rollbackOptimisticUpdate() : Restore previous data
    • useQuery.getState() : Get current state
    • useQuery.setState(value) : Manually update state (not recommended)
    • useQuery.subscribe(fn) : Subscribe to state changes
    • useQuery.getSubscriberCount() : Get the number of subscribers

  • getQuery methods

    • getQuery.executeAll() : Execute all queries
    • getQuery.revalidateAll() : Revalidate all stale or invalidated
    • getQuery.invalidateAll() : Invalidate all
    • getQuery.resetAll() : Reset all queries

Notes

  • Queries are keyed by query variable (deterministic hash)
  • Each variable has its own isolated state
  • Invalidated queries bypass staleTime
  • Unused queries are garbage collected after gcTime

createMutation

Creates a mutation store for handling async operations that modify data.

import { createMutation } from "floppy-disk/react";
 
const useMutation = createMutation(mutationFn, options);

Parameters

  • mutationFn : Async function that performs the mutation
    • Receives (variable, stateBeforeExecute)
  • options?
    • onSuccess? : Called when mutation succeeds
    • onError? : Called when mutation fails
    • onSettled? : Called after success or error
    • onFirstSubscribe? : Called when the first subscriber is added
    • onSubscribe? : Called every time a subscriber is added
    • onUnsubscribe? : Called every time a subscriber is removed
    • onLastUnsubscribe? : Called when the last subscriber is removed
    • onStateChange? : Called whenever state changes (does not register as a subscriber)
    • allowSetStateServerSide? : Allow setState on server (disabled by default)

Return Value

  • useMutation()

    • Return Value
      • state : Proxied mutation state with automatic tracking

  • useMutation methods

    • useMutation.execute(variable?) : Execute mutation
    • useMutation.reset() : Reset state to initial
    • useMutation.getState() : Get current state
    • useMutation.setState(value) : Manually update state (not recommended)
    • useMutation.subscribe(fn) : Subscribe to state changes
    • useMutation.getSubscriberCount() : Get the number of subscribers

Notes

  • No retry mechanism
  • Promise never rejects (always resolves with { variable: TVariable; data?: TData; error?: TError })
  • If execution triggered while there is inprogress execution:
    • Only the latest execution updates state
    • Previous executions are ignored

useMutation

A hook for managing mutation state without a global store.

import { useMutation } from "floppy-disk/react";
 
const [state, actions] = useMutation(mutationFn, options);

Parameters

  • mutationFn : Async function that performs the mutation
    • Receives (variable, stateBeforeExecute)
    • Does not need to be memoized
  • options?
    • onSuccess? : Called when mutation succeeds
    • onError? : Called when mutation fails
    • onSettled? : Called after success or error

Return Value

  • [state, actions]
    • state : Current mutation state (render snapshot)
    • actions.execute(variable?) : Execute mutation
    • actions.reset() : Reset state to initial
    • actions.getLatestState() : Get latest state (not tied to render)

Notes

  • Local-only (not shared across components)
  • No retry mechanism
  • Promise never rejects (always resolves with { variable: TVariable; data?: TData; error?: TError })
  • If execution triggered while there is inprogress execution:
    • Only the latest execution updates state
    • Previous executions are ignoredOnly latest execution updates state
  • Safe against stale closures (always uses latest function & callbacks)
Query/Mutation CancellationChange Log ↗