Update README files

Author: tommasoberlose

README.md

@@ -6,33 +6,41 @@
 
 The library works by wrapping standard Redux Toolkit functions, adding persistence logic without changing the way you write your reducers or actions.
 
+<br />
 
 ## ✨ Features
 
 * **Effortless Persistence**: Persist any Redux Toolkit slice or reducer with minimal configuration.
+
 * **Flexible API**: Choose between a `createPersistedSlice` utility or a `createPersistedReducer` builder syntax.
+
 * **Storage Agnostic**: Works with any storage provider that implements a simple `getItem`, `setItem`, and `removeItem` interface.
-* **Selective Persistence**: An optional filter function allows you to specify exactly which parts of a state should be persisted.
+
+* **Rehydration Lifecycle**: Use optional callbacks (`onRehydrationStart`, `onRehydrationSuccess`, `onRehydrationError`) to react to the persistence lifecycle.
+
 * **TypeScript Support**: Fully typed to ensure a great developer experience.
+
 * **Minimal Footprint**: Extremely lightweight with a production size under 10 KB.
 
+<br />
 
 ## ⚙️ Installation
 
 You can install `rtk-persist` using either `yarn` or `npm`:
 
-```bash
+```
 yarn add rtk-persist
 ```
 
 or
 
-```bash
+```
 npm install --save rtk-persist
 ```
 
 The package has a peer dependency on `@reduxjs/toolkit`.
 
+<br />
 
 ## 🚀 Quick Start
 
@@ -46,7 +54,7 @@ This approach is best if you prefer the `createSlice` API from Redux Toolkit.
 
 Replace `createSlice` with `createPersistedSlice`. The function accepts the same options.
 
-```typescript
+```
 // features/counter/counterSlice.ts
 import { createPersistedSlice } from 'rtk-persist';
 import { PayloadAction } from '@reduxjs/toolkit';
@@ -81,10 +89,10 @@ This approach is ideal if you prefer the `createReducer` builder syntax.
 
 Use `createPersistedReducer` and define your case reducers using the builder callback.
 
-```typescript
+```
 // features/counter/counterReducer.ts
 import { createPersistedReducer } from 'rtk-persist';
-import { createAction, PayloadAction, UnknownAction } from '@reduxjs/toolkit';
+import { createAction } from '@reduxjs/toolkit';
 
 const increment = createAction<number>('increment');
 const decrement = createAction<number>('decrement');
@@ -106,9 +114,9 @@ export const reducer = createPersistedReducer(
 
 ### 2. Configure the Store
 
-Whichever option you choose, you must use `configurePersistedStore` and provide a storage handler.
+Whichever option you choose, you must use `configurePersistedStore` and provide a storage handler. The store is created synchronously, and rehydration from storage happens in the background.
 
-```typescript
+```
 // app/store.ts
 import { configurePersistedStore } from 'rtk-persist';
 // Import your slice reducer (Option 1)
@@ -134,44 +142,69 @@ export const store = configurePersistedStore(
     },
   },
   'applicationId',
-  storage
+  storage,
+  {
+    onRehydrationStart: () => console.log('Rehydration started...'),
+    onRehydrationSuccess: () => console.log('Rehydration successful!'),
+    onRehydrationError: (error) => console.error('Rehydration failed:', error),
+  }
 );
 
-type Store = Awaited<typeof store>;
-export type RootState = ReturnType<Store['getState']>;
-export type AppDispatch = Store['dispatch'];
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;
 ```
 
+<br />
 
 ## 🛠️ API
 
 ### `createPersistedSlice(sliceOptions)`
 
 A wrapper around RTK's `createSlice`.
+
 * **`sliceOptions`**: The standard `CreateSliceOptions` object.
 
 ### `createPersistedReducer(name, initialState, builderCallback)`
 
 A wrapper around RTK's `createReducer`.
+
 * **`name`**: A unique string to identify this reducer in storage.
+
 * **`initialState`**: The initial state for the reducer.
+
 * **`builderCallback`**: A callback that receives a `builder` object to define case reducers.
 
-### `configurePersistedStore(storeOptions, applicationId, storageHandler)`
+### `configurePersistedStore(storeOptions, applicationId, storageHandler, persistenceOptions?)`
 
 A wrapper around RTK's `configureStore`.
+
 * **`storeOptions`**: The standard `ConfigureStoreOptions` object.
+
 * **`applicationId`**: A unique string that identifies the application.
+
 * **`storageHandler`**: A storage object that implements `getItem`, `setItem`, and `removeItem`.
 
+* **`persistenceOptions`** (optional): An object to control the persistence behavior:
+
+  * `rehydrationTimeout` (optional, `number`): The maximum time in milliseconds to wait for rehydration to complete before timing out. Defaults to `5000`.
+
+  * `onRehydrationStart` (optional, `() => void`): A callback invoked when the rehydration process begins.
+
+  * `onRehydrationSuccess` (optional, `() => void`): A callback invoked when the rehydration process completes successfully.
+
+  * `onRehydrationError` (optional, `(error: unknown) => void`): A callback invoked if an error occurs during rehydration.
+
+<br />
 
 ## ❤️ Author
 
-This library is authored and maintained by **[Fancy Pixel srl](https://www.fancypixel.it)**.
+This library is authored and maintained by [**Fancy Pixel srl**](https://www.fancypixel.it).
 
 This library was crafted from our daily experiences building modern web and mobile applications. Contributions are welcome!
 
+<br />
 
 ## 📄 License
 
 This project is licensed under the MIT License.
+        

example/README.md

@@ -10,7 +10,7 @@ Use this project to understand the library's features or as a sandbox for testin
 
 1.  **Clone the repository** (if you haven't already):
     ```bash
-    git clone https://github.com/FancyPixel/rtk-persist.git
+    git clone [https://github.com/FancyPixel/rtk-persist.git](https://github.com/FancyPixel/rtk-persist.git)
     ```
 
 2.  **Navigate to the example app directory**:
@@ -19,59 +19,40 @@ Use this project to understand the library's features or as a sandbox for testin
     ```
 
 3.  **Install dependencies**:
+    This command will also link the local `rtk-persist` library from the parent directory, as specified in `package.json`.
     ```bash
     yarn
     ```
 
 4.  **Run the application**:
     ```bash
-    yarn start
+    yarn dev
     ```
 
 ***
 
 ## 🛠️ Developing and Testing Local Library Changes
 
-If you have made changes to the `rtk-persist` library source code and want to test them in this example app without publishing to npm, follow these steps.
-
-This workflow ensures that the example app uses your latest local code from the library.
+If you have made changes to the `rtk-persist` library source code, the example app can use them directly thanks to the local file path dependency. This workflow ensures that the example app always uses your latest local code from the library.
 
 1.  **Navigate to the Library's Root Directory**:
-    Open a terminal and go to the root of the `rtk-persist` library, not the example app.
+    Open a terminal and go to the root of the `rtk-persist` library (the parent directory of `example`).
     ```bash
     # Assuming you are in the 'example' directory
     cd ..
     ```
 
 2.  **Build the Library**:
-    Compile the library's TypeScript source code into JavaScript.
+    After making any changes to the library's source code, you must rebuild it for the changes to be reflected in the example app.
     ```bash
     yarn build
     ```
 
-3.  **Package the Library**:
-    Create a local tarball (`.tgz` file) of the library. This is what you will install in the example app.
-    ```bash
-    yarn pack
-    ```
-    This command will create a file like `rtk-persist-v1.0.1.tgz` in the library's root directory. Note the exact filename.
-
-4.  **Navigate Back to the Example App Directory**:
+3.  **Run the Example App**:
+    Navigate back to the example app directory and start the development server. The app will automatically use the newly built version of the library.
     ```bash
     cd example
+    yarn dev
     ```
 
-5.  **Install the Local Library Package**:
-    Install the `.tgz` file you created in step 3. This will override the version from the npm registry.
-    ```bash
-    # Replace the filename with the one generated in step 3
-    yarn add file:../rtk-persist-v1.0.1.tgz
-    ```
-
-6.  **Run the Example App**:
-    Start the example application to see your local changes in action.
-    ```bash
-    yarn start
-    ```
-
-Now, the example app is running with your modified version of the `rtk-persist` library. Repeat this process every time you want to test new changes.
+Now, the example app is running with your modified version of the `rtk-persist` library. Simply repeat step 2 every time you want to test new changes.