@mustafaaksoy41/react-native-offline-queue 0.1.2

package/lib/typescript/core/OfflineManager.d.ts

@@ -0,0 +1,53 @@
+import type { StorageAdapter, RecordStorageAdapter } from './StorageAdapter';
+import type { OfflineAction, SyncProgress } from './types';
+import type { RealmAdapterOptions } from '../adapters';
+export interface OfflineManagerConfig {
+    storage?: StorageAdapter | RecordStorageAdapter;
+    storageType?: 'mmkv' | 'async-storage' | 'memory' | 'realm';
+    storageKey?: string;
+    syncMode?: 'auto' | 'manual';
+    realmOptions?: RealmAdapterOptions;
+    onSyncAction?: (action: OfflineAction) => Promise<void>;
+    onOnlineRestore?: (params: {
+        pendingCount: number;
+        syncNow: () => Promise<void>;
+        discardQueue: () => Promise<void>;
+    }) => void;
+}
+declare class OfflineManagerClass {
+    private queue;
+    private storage;
+    private storageKey;
+    private useRecordAdapter;
+    private queueListeners;
+    private progressListeners;
+    private actionHandlers;
+    isInitialized: boolean;
+    syncMode: 'auto' | 'manual';
+    onSyncAction?: (action: OfflineAction) => Promise<void>;
+    onOnlineRestore?: OfflineManagerConfig['onOnlineRestore'];
+    isSyncing: boolean;
+    private _syncProgress;
+    get syncProgress(): SyncProgress;
+    configure(config: OfflineManagerConfig): Promise<void>;
+    private loadQueue;
+    private saveQueue;
+    subscribeQueue: (listener: () => void) => (() => void);
+    subscribe: (listener: () => void) => (() => void);
+    private notifyQueueListeners;
+    subscribeProgress: (listener: () => void) => (() => void);
+    private updateProgress;
+    private updateProgressItem;
+    push<T>(actionName: string, payload: T): Promise<OfflineAction<T>>;
+    remove(id: string): Promise<void>;
+    clear(): Promise<void>;
+    getQueue(): OfflineAction[];
+    registerHandler(actionName: string, handler: (payload: any) => Promise<void>): void;
+    unregisterHandler(actionName: string): void;
+    getHandler(actionName: string): ((payload: any) => Promise<void>) | undefined;
+    flushQueue(): Promise<void>;
+    handleOnlineRestore(): void;
+}
+export declare const OfflineManager: OfflineManagerClass;
+export {};
+//# sourceMappingURL=OfflineManager.d.ts.map

package/lib/typescript/core/OfflineManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OfflineManager.d.ts","sourceRoot":"","sources":["../../../src/core/OfflineManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE7E,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAoB,MAAM,SAAS,CAAC;AAG7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAWvD,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,cAAc,GAAG,oBAAoB,CAAC;IAChD,WAAW,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IAG7B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAGnC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAGxD,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE;QACzB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KACnC,KAAK,IAAI,CAAC;CACZ;AAED,cAAM,mBAAmB;IACvB,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,OAAO,CAAqE;IACpF,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,gBAAgB,CAAkB;IAG1C,OAAO,CAAC,cAAc,CAA8B;IAGpD,OAAO,CAAC,iBAAiB,CAA8B;IAGvD,OAAO,CAAC,cAAc,CAA2D;IAE1E,aAAa,UAAS;IACtB,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAY;IACvC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,eAAe,CAAC,EAAE,oBAAoB,CAAC,iBAAiB,CAAC,CAAC;IAC1D,SAAS,UAAS;IAGzB,OAAO,CAAC,aAAa,CAA8C;IAEnE,IAAW,YAAY,IAAI,YAAY,CAEtC;IAGY,SAAS,CAAC,MAAM,EAAE,oBAAoB;YAsCrC,SAAS;YAkBT,SAAS;IAahB,cAAc,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG1D;IAGK,SAAS,aANmB,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAMrB;IAEvC,OAAO,CAAC,oBAAoB;IAKrB,iBAAiB,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG7D;IAEF,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,kBAAkB;IAWb,IAAI,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAoBlE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAa5B,QAAQ,IAAI,aAAa,EAAE;IAK3B,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC;IAI5E,iBAAiB,CAAC,UAAU,EAAE,MAAM;IAIpC,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS;IAKvE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA0FjC,mBAAmB;CAc3B;AAED,eAAO,MAAM,cAAc,qBAA4B,CAAC"}

package/lib/typescript/core/StorageAdapter.d.ts

@@ -0,0 +1,21 @@
+import type { OfflineAction } from './types';
+export interface StorageAdapter {
+    getItem: (key: string) => Promise<string | null> | string | null;
+    setItem: (key: string, value: string) => Promise<void> | void;
+    removeItem: (key: string) => Promise<void> | void;
+}
+export interface RecordStorageAdapter {
+    insert: (action: OfflineAction) => Promise<void> | void;
+    remove: (id: string) => Promise<void> | void;
+    getAll: () => Promise<OfflineAction[]> | OfflineAction[];
+    clear: () => Promise<void> | void;
+    update: (id: string, partial: Partial<OfflineAction>) => Promise<void> | void;
+}
+export declare function isRecordAdapter(adapter: StorageAdapter | RecordStorageAdapter): adapter is RecordStorageAdapter;
+export declare class MemoryStorageAdapter implements StorageAdapter {
+    private store;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+//# sourceMappingURL=StorageAdapter.d.ts.map

package/lib/typescript/core/StorageAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageAdapter.d.ts","sourceRoot":"","sources":["../../../src/core/StorageAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACjE,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC9D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACnD;AAID,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxD,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC7C,MAAM,EAAE,MAAM,OAAO,CAAC,aAAa,EAAE,CAAC,GAAG,aAAa,EAAE,CAAC;IACzD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,aAAa,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC/E;AAGD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,cAAc,GAAG,oBAAoB,GAC7C,OAAO,IAAI,oBAAoB,CAEjC;AAED,qBAAa,oBAAqB,YAAW,cAAc;IACzD,OAAO,CAAC,KAAK,CAA8B;IAE3C,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAInC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIzC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG9B"}

package/lib/typescript/core/types.d.ts

@@ -0,0 +1,23 @@
+export interface OfflineAction<TPayload = any> {
+    id: string;
+    actionName: string;
+    payload: TPayload;
+    createdAt: number;
+    retryCount: number;
+}
+export type SyncItemStatus = 'pending' | 'syncing' | 'success' | 'failed';
+export interface SyncProgressItem {
+    action: OfflineAction;
+    status: SyncItemStatus;
+    error?: string;
+}
+export interface SyncProgress {
+    isActive: boolean;
+    totalCount: number;
+    completedCount: number;
+    failedCount: number;
+    currentAction: OfflineAction | null;
+    items: SyncProgressItem[];
+}
+export declare const INITIAL_SYNC_PROGRESS: SyncProgress;
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,GAAG;IAC3C,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,QAAQ,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,aAAa,GAAG,IAAI,CAAC;IACpC,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B;AAED,eAAO,MAAM,qBAAqB,EAAE,YAOnC,CAAC"}

package/lib/typescript/hooks/useOfflineMutation.d.ts

@@ -0,0 +1,8 @@
+export declare function useOfflineMutation<TPayload>(actionName: string, options?: {
+    handler?: (payload: TPayload) => Promise<void>;
+    onOptimisticSuccess?: (payload: TPayload) => void;
+    onError?: (error: Error, payload: TPayload) => void;
+}): {
+    mutateOffline: (payload: TPayload) => Promise<void>;
+};
+//# sourceMappingURL=useOfflineMutation.d.ts.map

package/lib/typescript/hooks/useOfflineMutation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOfflineMutation.d.ts","sourceRoot":"","sources":["../../../src/hooks/useOfflineMutation.ts"],"names":[],"mappings":"AAIA,wBAAgB,kBAAkB,CAAC,QAAQ,EACzC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE;IACR,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;CACrD;6BAeqC,QAAQ;EAqC/C"}

package/lib/typescript/hooks/useOfflineQueue.d.ts

@@ -0,0 +1,8 @@
+export declare function useOfflineQueue(): {
+    queue: import("..").OfflineAction<any>[];
+    pendingCount: number;
+    isSyncing: boolean;
+    syncNow: () => Promise<void>;
+    clearQueue: () => Promise<void>;
+};
+//# sourceMappingURL=useOfflineQueue.d.ts.map

package/lib/typescript/hooks/useOfflineQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOfflineQueue.d.ts","sourceRoot":"","sources":["../../../src/hooks/useOfflineQueue.ts"],"names":[],"mappings":"AAMA,wBAAgB,eAAe;;;;;;EAU9B"}

package/lib/typescript/hooks/useOfflineSyncInterceptor.d.ts

@@ -0,0 +1,9 @@
+export interface InterceptorOptions {
+    onPromptNeeded: (params: {
+        pendingCount: number;
+        syncNow: () => Promise<void>;
+        discardQueue: () => Promise<void>;
+    }) => void;
+}
+export declare function useOfflineSyncInterceptor({ onPromptNeeded }: InterceptorOptions): void;
+//# sourceMappingURL=useOfflineSyncInterceptor.d.ts.map

package/lib/typescript/hooks/useOfflineSyncInterceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useOfflineSyncInterceptor.d.ts","sourceRoot":"","sources":["../../../src/hooks/useOfflineSyncInterceptor.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,CAAC,MAAM,EAAE;QACvB,YAAY,EAAE,MAAM,CAAC;QACrB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,YAAY,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;KACnC,KAAK,IAAI,CAAC;CACZ;AAED,wBAAgB,yBAAyB,CAAC,EAAE,cAAc,EAAE,EAAE,kBAAkB,QA0B/E"}

package/lib/typescript/hooks/useSyncProgress.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Live sync progress tracker.
+ * Use this inside a BottomSheet, Modal, or any UI to show per-item sync status.
+ *
+ * Returns:
+ * - isActive: whether a sync session is currently running
+ * - totalCount: total items in this sync batch
+ * - completedCount: successfully synced so far
+ * - failedCount: items that failed
+ * - currentAction: the action currently being synced
+ * - items: full list with per-item status (pending | syncing | success | failed)
+ * - percentage: 0-100 completion percentage
+ */
+export declare function useSyncProgress(): {
+    percentage: number;
+    isActive: boolean;
+    totalCount: number;
+    completedCount: number;
+    failedCount: number;
+    currentAction: import("..").OfflineAction | null;
+    items: import("..").SyncProgressItem[];
+};
+//# sourceMappingURL=useSyncProgress.d.ts.map

package/lib/typescript/hooks/useSyncProgress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSyncProgress.d.ts","sourceRoot":"","sources":["../../../src/hooks/useSyncProgress.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe;;;;;;;;EAY9B"}

package/lib/typescript/index.d.ts

@@ -0,0 +1,11 @@
+export * from './core/types';
+export * from './core/StorageAdapter';
+export { OfflineManager, type OfflineManagerConfig } from './core/OfflineManager';
+export { getMMKVAdapter, getAsyncStorageAdapter, getRealmAdapter, type RealmAdapterOptions } from './adapters';
+export * from './components/OfflineProvider';
+export * from './components/OfflineSyncPrompt';
+export * from './hooks/useOfflineQueue';
+export * from './hooks/useOfflineMutation';
+export * from './hooks/useOfflineSyncInterceptor';
+export * from './hooks/useSyncProgress';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAGlF,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAG/G,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAG/C,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,mCAAmC,CAAC;AAClD,cAAc,yBAAyB,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@mustafaaksoy41/react-native-offline-queue",
+  "version": "0.1.2",
+  "description": "A flexible, high-performance offline queue and synchronizer for React Native.",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__"
+  ],
+  "scripts": {
+    "build": "bob build",
+    "postinstall": "echo '\\n📦 @mustafaaksoy41/react-native-offline-queue installed!\\n⚠️  Required peer: npm install @react-native-community/netinfo\\n💡 Optional peers: react-native-mmkv | @react-native-async-storage/async-storage | realm\\n'"
+  },
+  "keywords": [
+    "react-native",
+    "offline",
+    "queue",
+    "sync",
+    "hook"
+  ],
+  "author": "Mustafa Aksoy",
+  "license": "MIT",
+  "peerDependencies": {
+    "@react-native-async-storage/async-storage": "*",
+    "@react-native-community/netinfo": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-mmkv": "*",
+    "realm": "*"
+  },
+  "peerDependenciesMeta": {
+    "react-native-mmkv": {
+      "optional": true
+    },
+    "@react-native-async-storage/async-storage": {
+      "optional": true
+    },
+    "realm": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@react-native-community/netinfo": "^11.0.0",
+    "@types/react": "^18.2.6",
+    "react": "18.2.0",
+    "react-native": "0.73.4",
+    "react-native-builder-bob": "^0.30.0",
+    "typescript": "^5.0.2",
+    "vitepress": "^1.6.4",
+    "vue": "^3.5.29"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,141 @@
+import type { StorageAdapter } from '../core/StorageAdapter';
+import type { RecordStorageAdapter } from '../core/StorageAdapter';
+import type { OfflineAction } from '../core/types';
+
+// Dynamic require approach so Metro doesn't crash if the user hasn't installed the optional library
+
+export const getMMKVAdapter = (): StorageAdapter => {
+  try {
+    const { MMKV } = require('react-native-mmkv');
+    const storage = new MMKV();
+    return {
+      getItem: (key) => storage.getString(key) || null,
+      setItem: (key, value) => storage.set(key, value),
+      removeItem: (key) => storage.delete(key),
+    };
+  } catch (error) {
+    throw new Error(
+      "[OfflineQueue] You selected 'mmkv' storage but react-native-mmkv is not installed. Run 'npm install react-native-mmkv' and 'pod install'."
+    );
+  }
+};
+
+export const getAsyncStorageAdapter = (): StorageAdapter => {
+  try {
+    const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+    return {
+      getItem: async (key) => await AsyncStorage.getItem(key),
+      setItem: async (key, value) => await AsyncStorage.setItem(key, value),
+      removeItem: async (key) => await AsyncStorage.removeItem(key),
+    };
+  } catch (error) {
+    throw new Error(
+      "[OfflineQueue] You selected 'async-storage' but @react-native-async-storage/async-storage is not installed. Run 'npm install @react-native-async-storage/async-storage' and 'pod install'."
+    );
+  }
+};
+
+// Default Realm schema for the offline queue
+const OFFLINE_QUEUE_SCHEMA_NAME = 'OfflineQueueItem';
+
+const OfflineQueueItemSchema = {
+  name: OFFLINE_QUEUE_SCHEMA_NAME,
+  primaryKey: 'id',
+  properties: {
+    id: 'string',
+    actionName: 'string',
+    payload: 'string',     // JSON-stringified payload
+    createdAt: 'int',
+    retryCount: { type: 'int', default: 0 },
+  },
+};
+
+export interface RealmAdapterOptions {
+  /** Pass your existing Realm instance to share it with your app */
+  realmInstance?: any;
+  /** Custom schema name (default: 'OfflineQueueItem') */
+  schemaName?: string;
+}
+
+export const getRealmAdapter = (options?: RealmAdapterOptions): RecordStorageAdapter => {
+  try {
+    const Realm = require('realm');
+    const schemaName = options?.schemaName || OFFLINE_QUEUE_SCHEMA_NAME;
+
+    let realm: any;
+
+    if (options?.realmInstance) {
+      realm = options.realmInstance;
+    } else {
+      // Open a dedicated Realm with our default schema
+      realm = new Realm({
+        schema: [
+          schemaName === OFFLINE_QUEUE_SCHEMA_NAME
+            ? OfflineQueueItemSchema
+            : { ...OfflineQueueItemSchema, name: schemaName },
+        ],
+        path: 'offline-queue.realm',
+        schemaVersion: 1,
+      });
+    }
+
+    return {
+      insert: (action: OfflineAction) => {
+        realm.write(() => {
+          realm.create(schemaName, {
+            id: action.id,
+            actionName: action.actionName,
+            payload: JSON.stringify(action.payload),
+            createdAt: action.createdAt,
+            retryCount: action.retryCount,
+          });
+        });
+        return Promise.resolve();
+      },
+
+      remove: (id: string) => {
+        realm.write(() => {
+          const record = realm.objectForPrimaryKey(schemaName, id);
+          if (record) realm.delete(record);
+        });
+        return Promise.resolve();
+      },
+
+      getAll: (): OfflineAction[] => {
+        const records = realm.objects(schemaName).sorted('createdAt');
+        return Array.from(records).map((r: any) => ({
+          id: r.id,
+          actionName: r.actionName,
+          payload: JSON.parse(r.payload),
+          createdAt: r.createdAt,
+          retryCount: r.retryCount,
+        }));
+      },
+
+      clear: () => {
+        realm.write(() => {
+          const all = realm.objects(schemaName);
+          realm.delete(all);
+        });
+        return Promise.resolve();
+      },
+
+      update: (id: string, partial: Partial<OfflineAction>) => {
+        realm.write(() => {
+          const record = realm.objectForPrimaryKey(schemaName, id);
+          if (record) {
+            if (partial.retryCount !== undefined) record.retryCount = partial.retryCount;
+            if (partial.payload !== undefined) record.payload = JSON.stringify(partial.payload);
+            if (partial.actionName !== undefined) record.actionName = partial.actionName;
+          }
+        });
+        return Promise.resolve();
+      },
+    };
+  } catch (error) {
+    throw new Error(
+      "[OfflineQueue] You selected 'realm' storage but realm is not installed. Run 'npm install realm' and 'pod install'."
+    );
+  }
+};
+

package/src/components/OfflineProvider.tsx

@@ -0,0 +1,52 @@
+import React, { createContext, useContext, useEffect, useRef, useState } from 'react';
+import NetInfo from '@react-native-community/netinfo';
+import { OfflineManager, type OfflineManagerConfig } from '../core/OfflineManager';
+
+interface OfflineContextValue {
+    isOnline: boolean | null;
+}
+
+const OfflineContext = createContext<OfflineContextValue>({ isOnline: true });
+
+export const useNetworkStatus = () => useContext(OfflineContext);
+
+export interface OfflineProviderProps {
+    children: React.ReactNode;
+    config: OfflineManagerConfig;
+}
+
+export const OfflineProvider: React.FC<OfflineProviderProps> = ({ children, config }) => {
+    const [isOnline, setIsOnline] = useState<boolean | null>(null);
+    const wasOfflineRef = useRef(false);
+
+    useEffect(() => {
+        OfflineManager.configure(config);
+    }, [config]);
+
+    useEffect(() => {
+        const unsubscribe = NetInfo.addEventListener((state) => {
+            const connected = !!state.isConnected;
+            if (__DEV__) console.log('[OfflineQueue] Network:', connected ? 'online' : 'offline', '| type:', state.type);
+
+            setIsOnline(connected);
+
+            if (!connected) {
+                wasOfflineRef.current = true;
+            }
+
+            if (connected && wasOfflineRef.current) {
+                wasOfflineRef.current = false;
+                if (__DEV__) console.log('[OfflineQueue] Network restored, triggering sync handler');
+                OfflineManager.handleOnlineRestore();
+            }
+        });
+
+        return () => unsubscribe();
+    }, []);
+
+    return (
+        <OfflineContext.Provider value={{ isOnline }}>
+            {children}
+        </OfflineContext.Provider>
+    );
+};

package/src/components/OfflineSyncPrompt.tsx

@@ -0,0 +1,32 @@
+import React from 'react';
+import { useNetworkStatus } from './OfflineProvider';
+import { useOfflineQueue } from '../hooks/useOfflineQueue';
+
+export interface OfflineSyncPromptProps {
+    children: (props: {
+        pendingCount: number;
+        isSyncing: boolean;
+        syncNow: () => Promise<void>;
+        cancel: () => Promise<void>;
+    }) => React.ReactNode;
+}
+
+export const OfflineSyncPrompt: React.FC<OfflineSyncPromptProps> = ({ children }) => {
+    const { isOnline } = useNetworkStatus();
+    const { pendingCount, isSyncing, syncNow, clearQueue } = useOfflineQueue();
+
+    if (isOnline && pendingCount > 0) {
+        return (
+            <>
+                {children({
+                    pendingCount,
+                    isSyncing,
+                    syncNow,
+                    cancel: clearQueue,
+                })}
+            </>
+        );
+    }
+
+    return null;
+};