usePersistentStore

constructor

Nested in: Class Mutex

Initializes a new instance of the Mutex class. Sets up the initial lock state as a resolved promise, ensuring that the mutex is initially available for locking.

runExclusive (async)

Nested in: Class Mutex

Run a callback function exclusively, ensuring that only one call to this method can be active at any given time. This is useful for ensuring that operations that must be mutually exclusive are properly synchronized.

Parameters:

• callback: - The function to be run exclusively

Returns:

• result of the callback

getQueueInstance

Returns an instance of localForage with a store name that is unique to the provided storeKey. This instance is used to store the sync queue for the store associated with the storeKey.

Parameters:

• storeKey: - The key identifying the store for which the sync queue should be created.

Returns:

• instance of localForage with a unique store name associated with the provided storeKey.

safeForStorage

Safely clones a given value for storage purposes. Attempts to use structuredClone for deep cloning, and falls back to JSON serialization/deserialization if an error occurs (e.g., for unsupported types).

Parameters:

• value: - The value to be cloned for storage.

Returns:

• deep clone of the provided value.

readSyncQueue (async)

Reads the sync queue for the specified store key. Retrieves the list of tasks from the queue associated with the given store key from the local storage.

Parameters:

• storeKey: - The key identifying the specific store queue.

Returns:

• promise that resolves to an array of tasks in the sync queue. Returns an empty array if the queue is not found.

createPersistentStore

Creates a persistent store with the given storeKey and stateKeys. The store will use localForage to store and retrieve data. The store will also create a sync queue with the given storeKey and will use mutexes to ensure that only one task can be processed at a time.

Parameters:

• options: - An object with the following properties: storeKey {String} - The key to use for the store. stateKeys {Array<String>} - An array of state keys to store.

Returns:

• An object with the following methods: loadStateFromStorage(store) - Loads the state from storage into the given store. persistState(store) - Persists the state of the given store. enqueueSync(task) - Enqueues a task to be processed when the app is online. processSyncQueue(syncHandler) - Processes the sync queue with the given syncHandler. removeTaskFromQueue(task) - Removes a task from the sync queue. clearSyncQueue() - Clears the sync queue. persistTaskUpdate(task) - Persists a single task in the sync queue.

loadStateFromStorage (async)

Nested in: createPersistentStore

Loads the state from local storage into the provided store. Retrieves data associated with the storeKey and updates the store with the values corresponding to the specified stateKeys.

Parameters:

• store: - The store object to load the state into.

Returns:

persistState (async)

Nested in: createPersistentStore

Persists the state of the given store to local storage. Iterates over the specified stateKeys and persists the corresponding values of the store.

Parameters:

• store: - The store object to persist the state of.

Returns:

enqueueSync (async)

Nested in: createPersistentStore

Enqueues a task to the sync queue, assigning it a unique taskId and ensuring mutual exclusion for the queue update operation. The task is added to the queue associated with the specific storeKey and is persisted in local storage. Once the task is enqueued, it sets the pending sync task flag to indicate tasks are waiting to be processed.

Parameters:

• task: - The task to be added to the sync queue. The task object is augmented with a unique taskId for identification.

Returns:

• promise that resolves when the task is successfully enqueued and the pending task status is updated.

processSyncQueue (async)

Nested in: createPersistentStore

Process the sync queue associated with the storeKey by calling the syncHandler function on each task in the queue. The syncHandler should handle the task by sending it to the backend server. If the syncHandler succeeds for a task, the task is removed from the queue. If the syncHandler fails for a task, the task is left in the queue for re-processing. The function is mutually exclusive with other calls to processSyncQueue for the same storeKey, ensuring that tasks are processed sequentially.

Parameters:

• syncHandler: - The function to call on each task in the sync queue. The function should take a single argument, the task object, and return a promise that resolves when the task is successfully processed or rejects when the task fails.

Returns:

• promise that resolves when all tasks in the queue have been processed.

removeTaskFromQueue (async)

Nested in: createPersistentStore

Removes a specified task from the sync queue associated with the storeKey. This operation is performed with mutual exclusion to prevent concurrent modifications to the queue. The function filters out the task with the given taskId from the queue and persists the updated queue back to storage.

Parameters:

• task: - The task object to be removed from the queue. The task should contain a unique taskId for identification.

Returns:

• promise that resolves when the task has been successfully removed and the queue updated.

clearSyncQueue (async)

Nested in: createPersistentStore

Clears the sync queue associated with the storeKey by removing the task queue from local storage. This operation is mutually exclusive with other calls to clearSyncQueue for the same storeKey to prevent concurrent modifications to the queue.

Returns:

• promise that resolves when the queue has been cleared.

persistTaskUpdate (async)

Nested in: createPersistentStore

Persists an update to a specific task in the sync queue associated with the storeKey. The task is identified by its taskId, and the update is performed within a mutex to ensure exclusive access to the sync queue. The task is deep-cloned for storage, and the updated task is saved back to the queue, replacing the existing task with the same taskId.

Parameters:

• task: - The task object containing the updated information. The task should include a unique taskId to identify the task in the queue.

Returns:

• promise that resolves when the task update has been successfully persisted.