Browse documentation

OfflineQueue

Stores operations, processes them when the network is available and exposes pending and failed counts plus syncing state.

Table of contents

Category

Value

Import

js
import { OfflineQueue } from "valyrian.js/offline";

Public signature

ts
new OfflineQueue(options: OfflineQueueOptions): OfflineQueue

API form

OfflineQueue is a class. Construct it with a queue identifier, a NetworkManager and the asynchronous handler that delivers each stored operation.

Options and defaults

ts
type OfflineQueueOptions = {
  id: string;
  network: NetworkManager;
  handler: (operation: OfflineOperation) => Promise<unknown>;
  storage?: "local" | "session"; // "local"
  isRetryable?: (error: unknown) => boolean; // retries every error
  backoff?: {
    strategy?: "exponential" | "linear"; // "exponential"
    baseMs?: number; // 1000
    maxMs?: number; // 30000
  };
  maxRetries?: number; // 5
};

State and operations

ts
type OfflineOperation = {
  id: string;
  type: string;
  payload?: unknown;
  retries: number;
  createdAt: number;
  lastError?: string;
};

type QueueState = {
  pending: number;
  failed: number;
  syncing: boolean;
  lastSyncAt: number | null;
  lastError: string | null;
};

state(): Readonly<QueueState>
pending(): OfflineOperation[]
failed(): OfflineOperation[]
enqueue(operation: Omit<OfflineOperation, "id" | "createdAt" | "retries">): void
sync(): Promise<void>
retryOne(id: string): void
retryAll(): void
discardFailed(): void
on("change", callback: (state: Readonly<QueueState>) => void): () => void
on("sync:success", callback: (operation: OfflineOperation) => void): () => void
on("sync:error", callback: (payload: { operation: OfflineOperation; error: unknown }) => void): () => void
off(event, callback): void
destroy(): void

Sync outcomes

enqueue() generates id, createdAt and retries. sync() stops when offline or already active, processes operations in order and stops the current pass after a retryable failure. NetworkEvent.ONLINE starts sync automatically. destroy() removes queue and network subscriptions.

Errors

Throws TypeError when options.network is missing.