useOfflineFirst

Reactive offline-first data binding powered by Legend-State's sync engine.

Combines remote sync with local persistence and automatic retry. Data is available immediately from local cache, then updated from the remote source. Failed remote operations are persisted locally and retried automatically.

Demo

useOfflineFirst

Loading...

Syncing...

Local cache + remote sync with automatic retry.

-1

0

+1

SyncClear Cache

Usage

Hook

import { useOfflineFirst } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

interface Settings {
  theme: string;
  language: string;
}

function Component() {
  const { data$, isLoaded$, isPersistLoaded$, refetch } = useOfflineFirst<Settings>({
    get: () => fetch("/api/settings").then((r) => r.json()),
    set: ({ value }) =>
      fetch("/api/settings", {
        method: "PUT",
        body: JSON.stringify(value),
      }),
    persistKey: "settings",
    persistPlugin: ObservablePersistLocalStorage,
    initial: { theme: "light", language: "en" },
  });

  return (
    <div>
      {isPersistLoaded$.get() ? (
        <>
          <span>{isLoaded$.get() ? "synced" : "from cache"}</span>
          <span>{data$.theme.get()}</span>
          <button onClick={() => data$.theme.set("dark")}>Dark mode</button>
          <button onClick={refetch}>Sync now</button>
        </>
      ) : (
        <div>Loading cache...</div>
      )}
    </div>
  );
}

Scope

import { createOfflineFirst, observable } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

interface Settings {
  theme: string;
  language: string;
}

function Component() {
  "use scope"
  const { data$, isLoaded$, isPersistLoaded$, refetch } = createOfflineFirst<Settings>({
    get: () => fetch("/api/settings").then((r) => r.json()),
    set: ({ value }) =>
      fetch("/api/settings", {
        method: "PUT",
        body: JSON.stringify(value),
      }),
    persistKey: "settings",
    persistPlugin: ObservablePersistLocalStorage,
    initial: { theme: "light", language: "en" },
  });

  return (
    <div>
      {isPersistLoaded$.get() ? (
        <>
          <span>{isLoaded$.get() ? "synced" : "from cache"}</span>
          <span>{data$.theme.get()}</span>
          <button onClick={() => data$.theme.set("dark")}>Dark mode</button>
          <button onClick={refetch}>Sync now</button>
        </>
      ) : (
        <div>Loading cache...</div>
      )}
    </div>
  );
}

Custom retry

Hook

import { useOfflineFirst } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

function Component() {
  const { data$, clearPersist } = useOfflineFirst<string[]>({
    get: () => fetch("/api/items").then((r) => r.json()),
    persistKey: "items",
    persistPlugin: ObservablePersistLocalStorage,
    initial: [],
    retry: {
      infinite: false,
      backoff: "constant",
      maxDelay: 5000,
    },
  });
}

Scope

import { createOfflineFirst, observable } from "@usels/web";
import { ObservablePersistLocalStorage } from "@usels/web";

function Component() {
  "use scope"
  const { data$, clearPersist } = createOfflineFirst<string[]>({
    get: () => fetch("/api/items").then((r) => r.json()),
    persistKey: "items",
    persistPlugin: ObservablePersistLocalStorage,
    initial: [],
    retry: {
      infinite: false,
      backoff: "constant",
      maxDelay: 5000,
    },
  });
}

Type

Parameters

Parameter	Type	Description
options	OfflineFirstOptions<T>	- Offline-first sync configuration.

OfflineFirstOptions

Option	Type	Default	Description
get	() => T | Promise<T>	-	Function that fetches remote data.
set	((params: { value: T; changes: object[]; }) => void | Promise<void>)	-	Function that sends changes to the remote.
initial	T	-	Initial value before data is loaded from persist or remote.
persistKey	string	-	Storage key for local persistence.
persistPlugin	ObservablePersistPlugin | ClassConstructor<ObservablePersistPlugin, any[]> | undefined	-	Legend-State persist plugin to use as the storage backend.
mode	"set" | "assign" | "merge" | "append" | "prepend"	"set"	How incoming data merges with existing state.
debounceSet	number	-	Milliseconds to debounce before sending changes to remote.
transform	{ load?: ((value: any) => T) | undefined; save?: ((value: T) => any) | undefined; }	-	Transform data on load/save.
retry	{ infinite?: boolean | undefined; backoff?: "constant" | "exponential" | undefined; maxDelay?: number | undefined; }	{ infinite: true, backoff: "exponential", maxDelay: 30000 }	Retry configuration for failed remote operations.

Returns

OfflineFirstReturn<T>

Name	Type	Description
data$	Observable<T>	The synced observable data.
isLoaded$	ReadonlyObservable<boolean>	Whether the remote data has been loaded.
isFetching$	ReadonlyObservable<boolean>	Whether a fetch (initial or refetch) is currently in progress.
isPersistLoaded$	ReadonlyObservable<boolean>	Whether locally persisted data has been loaded.
error$	ReadonlyObservable<Error | undefined>	The most recent sync error, if any.
lastSync$	ReadonlyObservable<number | undefined>	Timestamp of the last successful sync.
refetch	() => void	Trigger a manual re-fetch from remote.
clearPersist	() => void	Clear all locally persisted data.

Source

View on GitHub