### Install Reduxed Chrome Storage

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

This command installs the `reduxed-chrome-storage` package, making it available for use in your project.

```shell
npm install reduxed-chrome-storage
```

--------------------------------

### Initialize Reduxed Chrome Storage for common use cases

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

Demonstrates the basic setup of `reduxed-chrome-storage` using `setupReduxed` with a Redux store creator. It shows how to obtain a replacement store instance using both Promise and async/await patterns.

```typescript
import {
  setupReduxed, ReduxedSetupOptions
} from 'reduxed-chrome-storage';
import { configureStore } from '@reduxjs/toolkit';
import reducer from './reducer';

const storeCreatorContainer = (preloadedState?: any) =>
  configureStore({reducer, preloadedState});
const options: ReduxedSetupOptions = { ... };
const instantiate = setupReduxed(storeCreatorContainer, options);
// Obtain a replacement store instance
//   Option #1: Promise style
instantiate().then(store => {
  const state = store.getState();
  ...
});
//   Option #2: async/await style
async () => {
  const store = await instantiate();
  const state = store.getState();
  ...
}
```

--------------------------------

### Configure Reduxed Chrome Storage for Manifest V3 service workers with change listeners

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

Illustrates how to integrate `reduxed-chrome-storage` into a Manifest V3 service worker, emphasizing the use of `onGlobalChange` and `onLocalChange` listeners for tracking state changes without `store.subscribe()`. It includes examples of filtering state changes using `diffDeep` and `isEqual`.

```typescript
import {
  setupReduxed, diffDeep, isEqual,
  ReduxedSetupOptions, ReduxedSetupListeners, ChangeListener
} from 'reduxed-chrome-storage';
...

// In order to track state changes set onGlobalChange and(or) onLocalChange
// properties within 3rd argument of setupReduxed like below
// instead of calling store.subscribe() in each API event listener

const globalChangeListener: ChangeListener = (store, previousState) => {
  const state = store.getState();
  // Below is an example how to filter down state changes
  // by comparing current state with previous one
  const diff = diffDeep(state, previousState);
  if (diff && ['someKey', 'anotherKey'].some(key => key in diff)) {
    ...
  }
};

const localChangeListener: ChangeListener = (store, previousState) => {
  const state = store.getState();
  // Another (a simpler) example how to filter down state changes
  if (isEqual(state.someKey, previousState.someKey)) {
    ...
  }
};

const storeCreatorContainer = ...;
const options: ReduxedSetupOptions = { ... };
const listeners: ReduxedSetupListeners = {
  onGlobalChange: globalChangeListener,
  onLocalChange: localChangeListener
};
const instantiate = setupReduxed(storeCreatorContainer, options, listeners);

// General pattern
chrome.{API}.on{Event}.addListener(async () => {
  // Obtain a store instance
  const store = await instantiate();
  const state = store.getState();
  ...
});

// Specific example
chrome.runtime.onStartup.addListener(async () => {
  // Obtain a store instance
  const store = await instantiate();
  const state = store.getState();
  ...
});
...
```

--------------------------------

### API Reference for setupReduxed() function

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

The `setupReduxed()` function initializes the Reduxed Chrome Storage library, connecting a Redux store to `chrome.storage`. It should be called only once per extension component. It accepts three arguments: a store creator, options, and listeners, and returns an async function to obtain the store instance.

```APIDOC
setupReduxed(storeCreatorContainer: Function, options?: ReduxedSetupOptions, listeners?: ReduxedSetupListeners): () => Promise<Store>

- Description: Sets up Reduxed Chrome Storage, allowing to get a Redux store replacement connected to the state in `chrome.storage`.
- Parameters:
  - storeCreatorContainer: A function that creates a Redux store instance. It typically accepts an optional `preloadedState` argument, as shown in examples using `configureStore`.
  - options: (Optional) An object of type `ReduxedSetupOptions` to configure the setup. This object allows specifying various behaviors for the Reduxed Chrome Storage.
  - listeners: (Optional) An object of type `ReduxedSetupListeners` containing callback functions. These include `onGlobalChange` (for all state changes), `onLocalChange` (for specific local state changes), and `onError` (for errors during `chrome.storage` updates).
- Returns: An async function. When this returned function is called, it returns a Promise that resolves to a replacement Redux store instance. This store is connected to and synchronized with `chrome.storage`.
```

--------------------------------

### setupReduxed() Function API Reference

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

Comprehensive documentation for the `setupReduxed()` function, including its mandatory store creator container argument, optional configuration options for Chrome/Browser API integration, storage settings, and behavior flags, along with available error and state change listeners.

```APIDOC
setupReduxed(storeCreatorContainer: Function, options?: Object, listeners?: Object)

Arguments:
  1. storeCreatorContainer: Function (mandatory)
     - Description: A function that calls a store creator (e.g., Redux's createStore() or Redux Toolkit's configureStore()) and returns a Redux store. It receives one argument (preloadedState) to pass to the store creator.

  2. options: Object (optional)
     - Description: Configuration options for setupReduxed().
     - Properties:
       - namespace: string
         - Default: 'chrome'
         - Description: A string to identify the APIs namespace to be used, either 'chrome' or 'browser'. If this and the next two options are missing, the chrome namespace is used by default.
       - chromeNs: host object (ChromeNamespace)
         - Description: The chrome namespace within Manifest V2 extension. If this option is supplied, the previous one is ignored.
       - browserNs: host object (BrowserNamespace)
         - Description: The browser namespace within Firefox extension, or the chrome namespace within Manifest V3 chrome extension. You may pass the chrome namespace within Manifest V3 to make this library use Promise-based APIs under the hood. If this option is supplied, the previous two are ignored.
       - storageArea: string
         - Default: 'local'
         - Description: The name of chrome.storage area to be used, either 'sync' or 'local'. 'local' area is recommended for main state due to less strict limits.
       - storageKey: string
         - Default: 'reduxed'
         - Description: Key under which the state will be stored/tracked in chrome.storage.
       - isolated: boolean
         - Default: false
         - Description: If true, the store in this specific extension component isn't supposed to receive state changes from other extension components. Recommended for Manifest V3 service workers and all extension-related pages (e.g. options page etc.) except popup page.
       - plainActions: boolean
         - Default: false
         - Description: If true, the store is only supposed to dispatch plain object actions.
       - outdatedTimeout: number
         - Default: 1000
         - Description: Max. time (in ms) to wait for outdated (async) actions to be completed. This option is ignored if at least one of the previous two (isolated/plainActions) options is checked.

  3. listeners: Object (optional)
     - Description: Callback functions for errors and state changes.
     - Properties:
       - onError: function (ErrorListener)
         - Description: A function to be called whenever an error occurs during chrome.storage update.
         - Arguments:
           1. errorMessage: string (defined by storage API)
           2. isLimitExceeded: boolean (true if the limit for the used storage area is exceeded)
       - onGlobalChange: function (ChangeListener)
         - Description: A function to be called whenever the state changes that may be caused by any extension component (popup etc.).
         - Arguments:
           1. temporaryStore: Object (a temporary store representing the current state)
           2. previousState: Object (the previous state)
```

--------------------------------

### Reduxed Chrome Storage Store Creation Function

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

This entry describes the function returned by `setupReduxed()`, which is responsible for asynchronously creating a Redux store replacement connected to `chrome.storage`. It allows for optional state initialization and returns a Promise indicating readiness.

```APIDOC
setupReduxed().returnedFunction(initialStateValue?)
  - Description: Creates asynchronously a Redux store replacement connected to the state stored in `chrome.storage`.
  - Parameters:
    - initialStateValue (optional): Any type. A value to which the state will be reset entirely or partially upon store creation.
  - Returns: Promise<Store> - A Promise to be resolved when the created replacement store is ready.
  - Usage Note: Must only be called once per extension component, except in Manifest V3 service workers where it should be called in each API event listener.
```

--------------------------------

### Implement error tracking for Reduxed Chrome Storage updates

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

Shows how to set up an `onError` listener within `setupReduxed` to catch and handle errors that occur during `chrome.storage` updates, providing a mechanism for robust error management.

```typescript
import {
  setupReduxed, ReduxedSetupListeners, ErrorListener
} from 'reduxed-chrome-storage';
...

// errorListener will be called whenever an error occurs
// during chrome.storage update
const errorListener: ErrorListener = (message, exceeded) => {
  ...
};
const storeCreatorContainer = ...;
const listeners: ReduxedSetupListeners = {
  onError: errorListener
};
const instantiate = setupReduxed(storeCreatorContainer, { ... }, listeners);
...
```

--------------------------------

### Reduxed Chrome Storage Utility Functions

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

This section outlines three utility functions (`isEqual`, `diffDeep`, `cloneDeep`) provided by the library. These functions are optimized for working with JSON data and are useful for comparing, finding differences, and deep copying state-related data.

```APIDOC
isEqual(value1, value2)
  - Description: Checks deeply if two supplied values are equal.
  - Parameters:
    - value1: The first value to compare.
    - value2: The second value to compare.
  - Returns: boolean - True if values are deeply equal, false otherwise.

diffDeep(value1, value2)
  - Description: Finds the deep difference between two supplied values.
  - Parameters:
    - value1: The first value to compare.
    - value2: The second value to compare.
  - Returns: any - The found deep difference.

cloneDeep(value)
  - Description: Creates a deep copy of supplied value using JSON stringification.
  - Parameters:
    - value: The value to copy.
  - Returns: any - The created deep copy.
```

--------------------------------

### Reduxed Chrome Storage Change Listeners

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

This section details the `onLocalChange` and `onGlobalChange` functions, which serve as state change listeners for the Reduxed Chrome Storage library. They provide alternatives to `store.subscribe` specifically for Manifest V3 service workers, offering different update timings and scopes.

```APIDOC
onLocalChange(storeReference, previousState)
  - Type: function (ChangeListener in Typescript definition)
  - Description: A function called when a store in the specific extension component (service worker) causes a state change.
  - Parameters:
    - storeReference: Reference to the store that caused the change.
    - previousState: The state before the change.
  - Behavior: Provides immediate state updates from the local component.

onGlobalChange()
  - Description: A function that gets state updates from all extension components.
  - Behavior: Gets state updates after they've passed through the `chrome.storage` update cycle (`storage.set` then `storage.onChanged`).
  - Note: Both `onLocalChange` and `onGlobalChange` are intended for Manifest V3 service workers as replacements for `store.subscribe`.
```

--------------------------------

### Reduxed Chrome Storage State JSON Stringification Caveats

Source: https://github.com/hindmost/reduxed-chrome-storage/blob/master/README.md

This section details important considerations regarding how state is stored in `chrome.storage`. Since all data is JSON-stringified, developers must be aware that non-JSON values will be lost or altered, potentially causing unexpected side effects.

```APIDOC
State Storage Considerations
  - Description: All state data is stored in `chrome.storage` and is JSON-stringified.
  - Implications:
    - State should not contain non-JSON values (e.g., functions, `undefined` as explicit property values) as they will be lost or altered.
    - Using non-JSON values may lead to unwanted side effects.
  - Specific Example: Object properties explicitly set to `undefined` (`{key: undefined, ...}`) will be lost.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.