From 0ac38215f7ad16184b2eff566da0b405e1a26a5d Mon Sep 17 00:00:00 2001 From: KAMRONBEK Date: Fri, 17 Jul 2026 21:29:06 +0500 Subject: [PATCH 1/3] docs: document lazy-loaded (injected) reducers --- packages/docs-website/astro.config.mjs | 1 + .../docs/usage/lazy-loaded-reducers.md | 62 +++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md diff --git a/packages/docs-website/astro.config.mjs b/packages/docs-website/astro.config.mjs index 20a5822..fb376ea 100644 --- a/packages/docs-website/astro.config.mjs +++ b/packages/docs-website/astro.config.mjs @@ -30,6 +30,7 @@ export default defineConfig({ { label: 'Migrations with Redux Remigrate', slug: 'usage/migrations' }, { label: 'Custom Storage Driver', slug: 'usage/custom-storage-driver' }, { label: 'Using in Reducers', slug: 'usage/using-in-reducers' }, + { label: 'Lazy-loaded Reducers', slug: 'usage/lazy-loaded-reducers' }, { label: 'Rehydration Gate', slug: 'usage/rehydration-gate' }, { label: 'Error Handling', slug: 'usage/error-handling' }, { diff --git a/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md new file mode 100644 index 0000000..2ca6bb9 --- /dev/null +++ b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md @@ -0,0 +1,62 @@ +--- +title: Lazy-loaded (injected) reducers +--- + +Redux Remember doesn't add lazy-loaded / injected reducers as a first-class feature. Injecting a reducer that is *also* persisted introduces an ordering (race) condition between when the reducer becomes available and when Redux Remember reads storage, so it's left as an opt-in pattern rather than something built in. This page covers the two cases that come up and how each behaves. + +## Non-persisted injected slices + +If an injected slice is not persisted (its key isn't in `rememberedKeys`), there's nothing special to do. Pass a dynamic root reducer — for example Redux Toolkit's [`combineSlices`](https://redux-toolkit.js.org/api/combineSlices) — to `rememberReducer`, and inject whenever you like: + +```ts +import { configureStore, combineSlices } from '@reduxjs/toolkit'; +import { rememberReducer, rememberEnhancer } from 'redux-remember'; + +const rootReducer = combineSlices(baseSlice); + +const store = configureStore({ + reducer: rememberReducer(rootReducer), + enhancers: (getDefaultEnhancers) => getDefaultEnhancers().concat( + // the lazy slice's key is deliberately NOT listed here + rememberEnhancer(window.localStorage, ['base']) + ), +}); + +// later, on demand: +rootReducer.inject(lazySlice); +``` + +Redux Remember only ever touches the keys listed in `rememberedKeys`, so an injected slice that isn't listed is invisible to it — no rehydrate, no persist, no race. + +## Persisted injected slices + +If you want an injected slice to be persisted, ordering matters. Redux Remember reads storage and dispatches [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) once, when it initializes. A reducer injected *after* that point has already missed its rehydration, so its stored value is dropped and it starts from its initial state instead. + +The `initActionType` option lines the two up. When it's set, Redux Remember holds off on initializing (reading storage and starting to persist) until you dispatch that action. So inject the reducer first, then dispatch the init action: + +```ts +const rootReducer = combineSlices(baseSlice); + +const store = configureStore({ + reducer: rememberReducer(rootReducer), + enhancers: (getDefaultEnhancers) => getDefaultEnhancers().concat( + rememberEnhancer(window.localStorage, ['base', 'lazyPersisted'], { + initActionType: 'REMEMBER_INIT', + }) + ), +}); + +// 1. inject the reducer so it exists in the state tree... +rootReducer.inject(lazyPersistedSlice); + +// 2. ...then let Redux Remember read storage, with the slice already present +store.dispatch({ type: 'REMEMBER_INIT' }); +``` + +Storage is now read after `lazyPersisted` is in the tree, so it rehydrates like any statically-defined key. Without `initActionType`, Redux Remember auto-initializes as soon as the store is created — before a later `inject()` runs — which is exactly the race that drops the stored value. + +## See Also + +- [`rememberEnhancer`](../api/remember-enhancer.md) — the `initActionType` and `rememberedKeys` options +- [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) +- [Using in Reducers](./using-in-reducers.md) From e3f5a79d7db1e09b879a4384d41dc4c60146ea93 Mon Sep 17 00:00:00 2001 From: KAMRONBEK Date: Fri, 17 Jul 2026 21:50:49 +0500 Subject: [PATCH 2/3] feat: rehydrate lazy-loaded reducers on demand via store.rehydrate() Adds store.rehydrate(keys?) so an injected/persisted reducer can be loaded from storage after the store is created. Without it, a reducer injected after init misses its one-time rehydration and its stored value is dropped. - index.ts: attach store.rehydrate; it reads the given keys, dispatches REMEMBER_REHYDRATED, and adds them to the remembered set so they persist. - types.ts: RehydrateFunction + RememberEnhancerStoreExt (default enhancer Ext), so store.rehydrate is typed without extra generics. - tests: 3 new cases; full suite 7812 pass, index.ts 100% covered. - docs: usage/lazy-loaded-reducers documents the API for both cases. --- .../docs/usage/lazy-loaded-reducers.md | 24 ++++---- .../src/__tests__/index.test.ts | 58 ++++++++++++++++++- packages/redux-remember/src/index.ts | 25 +++++++- packages/redux-remember/src/types.ts | 6 ++ 4 files changed, 95 insertions(+), 18 deletions(-) diff --git a/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md index 2ca6bb9..64fe0f8 100644 --- a/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md +++ b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md @@ -2,7 +2,7 @@ title: Lazy-loaded (injected) reducers --- -Redux Remember doesn't add lazy-loaded / injected reducers as a first-class feature. Injecting a reducer that is *also* persisted introduces an ordering (race) condition between when the reducer becomes available and when Redux Remember reads storage, so it's left as an opt-in pattern rather than something built in. This page covers the two cases that come up and how each behaves. +Redux Remember supports lazy-loaded / injected reducers — reducers you add to the store after it's been created, for example a code-split slice that loads when the user navigates to a route. There are two cases, depending on whether the injected slice is persisted. ## Non-persisted injected slices @@ -26,13 +26,13 @@ const store = configureStore({ rootReducer.inject(lazySlice); ``` -Redux Remember only ever touches the keys listed in `rememberedKeys`, so an injected slice that isn't listed is invisible to it — no rehydrate, no persist, no race. +Redux Remember only ever touches the keys listed in `rememberedKeys`, so an injected slice that isn't listed is invisible to it — no rehydrate, no persist. ## Persisted injected slices -If you want an injected slice to be persisted, ordering matters. Redux Remember reads storage and dispatches [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) once, when it initializes. A reducer injected *after* that point has already missed its rehydration, so its stored value is dropped and it starts from its initial state instead. +For a slice you *do* want persisted, timing matters. Redux Remember reads storage and dispatches [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) once, when it initializes. A reducer injected after that point has already missed its rehydration, so its stored value would be dropped and it would start from its initial state. -The `initActionType` option lines the two up. When it's set, Redux Remember holds off on initializing (reading storage and starting to persist) until you dispatch that action. So inject the reducer first, then dispatch the init action: +Call [`store.rehydrate(keys)`](../api/remember-enhancer.md) after injecting the reducer. It reads those keys from storage, rehydrates them into the store, and adds them to the remembered set so they're persisted from then on: ```ts const rootReducer = combineSlices(baseSlice); @@ -40,23 +40,19 @@ const rootReducer = combineSlices(baseSlice); const store = configureStore({ reducer: rememberReducer(rootReducer), enhancers: (getDefaultEnhancers) => getDefaultEnhancers().concat( - rememberEnhancer(window.localStorage, ['base', 'lazyPersisted'], { - initActionType: 'REMEMBER_INIT', - }) + rememberEnhancer(window.localStorage, ['base']) ), }); -// 1. inject the reducer so it exists in the state tree... -rootReducer.inject(lazyPersistedSlice); - -// 2. ...then let Redux Remember read storage, with the slice already present -store.dispatch({ type: 'REMEMBER_INIT' }); +// when the lazy slice loads: +rootReducer.inject(lazyPersistedSlice); // 1. add the reducer to the tree +await store.rehydrate(['lazyPersisted']); // 2. load its persisted state ``` -Storage is now read after `lazyPersisted` is in the tree, so it rehydrates like any statically-defined key. Without `initActionType`, Redux Remember auto-initializes as soon as the store is created — before a later `inject()` runs — which is exactly the race that drops the stored value. +After this, `lazyPersisted` holds its stored value and is persisted on every change like any statically-defined key. Called with no arguments, `store.rehydrate()` re-reads every currently remembered key. ## See Also -- [`rememberEnhancer`](../api/remember-enhancer.md) — the `initActionType` and `rememberedKeys` options +- [`rememberEnhancer`](../api/remember-enhancer.md) — the `rememberedKeys` option and the `store.rehydrate` method - [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) - [Using in Reducers](./using-in-reducers.md) diff --git a/packages/redux-remember/src/__tests__/index.test.ts b/packages/redux-remember/src/__tests__/index.test.ts index 9a61190..fbf27a2 100644 --- a/packages/redux-remember/src/__tests__/index.test.ts +++ b/packages/redux-remember/src/__tests__/index.test.ts @@ -6,6 +6,7 @@ import type { Options } from '../types.ts'; describe('index.ts', () => { const mockRehydrate = { + rehydrate: vi.fn(), rehydrateReducer: vi.fn(() => 'REHYDRATE_REDUCER') }; @@ -14,6 +15,7 @@ describe('index.ts', () => { let index: typeof indexModule; beforeEach(async () => { + mockRehydrate.rehydrate = vi.fn(); mockRehydrate.rehydrateReducer = vi.fn(() => 'REHYDRATE_REDUCER'); mockInit = vi.fn(() => {}); mockCombineReducers = vi.fn(() => {}); @@ -127,7 +129,7 @@ describe('index.ts', () => { }; let mockCreateStore: StoreCreator; - const mockStore = 'my-mocked-store'; + const mockStore: any = { name: 'my-mocked-store' }; const rememberedKeys = ['zz', 'bb', 'kk']; const rootReducer = (state = {}) => state; let rootReducerWrapper: Reducer; @@ -258,5 +260,59 @@ describe('index.ts', () => { vi.clearAllTimers(); vi.useRealTimers(); }); + + it('exposes store.rehydrate() and rehydrates the requested keys', async () => { + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, [...rememberedKeys] + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + expect(typeof store.rehydrate).toBe('function'); + + await store.rehydrate(['newKey']); + + expect(mockRehydrate.rehydrate).toHaveBeenCalledWith( + mockStore, + ['newKey'], + expect.objectContaining({ + driver: mockDriver, + prefix: '@@remember-' + }) + ); + }); + + it('store.rehydrate() starts remembering newly requested keys', async () => { + const keys = ['aa', 'bb']; + + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, keys + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + await store.rehydrate(['aa', 'cc']); + + // already-remembered keys are not duplicated, new ones are appended + expect(keys).toEqual(['aa', 'bb', 'cc']); + }); + + it('store.rehydrate() with no arguments rehydrates every remembered key', async () => { + const keys = ['aa', 'bb']; + + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, keys + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + await store.rehydrate(); + + expect(mockRehydrate.rehydrate).toHaveBeenCalledWith( + mockStore, + keys, + expect.objectContaining({ driver: mockDriver }) + ); + }); }); }); diff --git a/packages/redux-remember/src/index.ts b/packages/redux-remember/src/index.ts index 8508b1e..682b99a 100644 --- a/packages/redux-remember/src/index.ts +++ b/packages/redux-remember/src/index.ts @@ -1,6 +1,7 @@ import init from './init.ts'; +import { rehydrate } from './rehydrate.ts'; import { REMEMBER_REHYDRATED, REMEMBER_PERSISTED } from './action-types.ts'; -import type { Driver, Options } from './types.ts'; +import type { Driver, Options, RememberEnhancerStoreExt } from './types.ts'; import type { Action, StoreEnhancer, @@ -60,7 +61,7 @@ const rememberReducer = ( +const rememberEnhancer = ( driver: Driver, rememberedKeys: string[], { @@ -113,12 +114,30 @@ const rememberEnhancer = ( enhancer ); + // Rehydrate (and start remembering) additional keys on demand. This is what + // makes lazy-loaded / injected reducers work: inject the reducer, then call + // store.rehydrate([key]) to load its persisted value and keep persisting it. + // Called with no arguments it re-reads every currently remembered key. + const rehydrateStore = async (keys: string[] = rememberedKeys): Promise => { + keys.forEach((key) => { + if (!rememberedKeys.includes(key)) { + rememberedKeys.push(key); + } + }); + + await rehydrate( + store, + keys, + { prefix, driver, unserialize, migrate, persistWholeStore, errorHandler } + ); + }; + if (!initActionType) { isInitialized = true; void initialize(store); } - return store; + return Object.assign(store, { rehydrate: rehydrateStore }); }; return storeCreator; diff --git a/packages/redux-remember/src/types.ts b/packages/redux-remember/src/types.ts index 9ed28cd..068f4b2 100644 --- a/packages/redux-remember/src/types.ts +++ b/packages/redux-remember/src/types.ts @@ -24,3 +24,9 @@ export type Options = { export type ExtendedOptions = Options & { driver: Driver }; + +export type RehydrateFunction = (keys?: string[]) => Promise; + +export type RememberEnhancerStoreExt = { + rehydrate: RehydrateFunction +}; From ffbb48785cb1d661eaa9834b703a5082adfefc33 Mon Sep 17 00:00:00 2001 From: KAMRONBEK Date: Fri, 18 Sep 2026 16:14:30 +0500 Subject: [PATCH 3/3] fix: close the on-demand rehydrate races, rename to store.unsafeRehydrate() Addresses review feedback that this introduced an unsafe API without marking it as such. Renames store.rehydrate() to store.unsafeRehydrate(), and fixes four timing defects that made the old implementation genuinely unsafe rather than merely unconventional: - Read the state after the storage read, in the same tick as the dispatch. It was captured before the await, so REMEMBER_REHYDRATED re-broadcast a stale snapshot and silently reverted anything dispatched while storage was being read. This also made concurrent calls revert each other. - Only add keys to the remembered set once their stored value has been loaded. Adding them up front let the persist subscriber write the slice's initial state over good stored data mid-read - and the in-flight read then returned that clobbered value, losing it for good. - Do not add keys, or dispatch, when the read fails. A transient storage error otherwise started persisting the slice's initial state. - Do not re-apply migrate(). It is a whole-state, run-once function; re-running it over already-migrated state is unsound. Also stops mutating the rememberedKeys array the caller passed in: the store keeps its own copy, shared with init() so newly remembered keys are still persisted. Adds an end-to-end suite covering these guarantees against a real store and a real async driver - they are all timing properties that a mocked driver cannot express. --- .../src/content/docs/api/actions.md | 2 +- .../src/content/docs/api/remember-enhancer.md | 22 ++ .../docs/usage/lazy-loaded-reducers.md | 29 ++- .../src/__tests__/index.test.ts | 135 ++++++++-- .../src/__tests__/rehydrate.test.ts | 78 +++++- .../src/__tests__/unsafe-rehydrate.test.ts | 243 ++++++++++++++++++ packages/redux-remember/src/index.ts | 100 ++++--- packages/redux-remember/src/rehydrate.ts | 35 +++ packages/redux-remember/src/types.ts | 4 +- 9 files changed, 587 insertions(+), 61 deletions(-) create mode 100644 packages/redux-remember/src/__tests__/unsafe-rehydrate.test.ts diff --git a/packages/docs-website/src/content/docs/api/actions.md b/packages/docs-website/src/content/docs/api/actions.md index 0ab93db..9f62e38 100644 --- a/packages/docs-website/src/content/docs/api/actions.md +++ b/packages/docs-website/src/content/docs/api/actions.md @@ -9,7 +9,7 @@ Redux Remember dispatches these actions that you can listen to in your reducers. - **Type:** `'@@REMEMBER_REHYDRATED'` - **Description:** Dispatched when state has been loaded from storage - **Payload:** The complete rehydrated root state -- **Timing:** Dispatched once when the application loads +- **Timing:** Dispatched once when the application loads — and again on every [`store.unsafeRehydrate()`](./remember-enhancer.md#storeunsaferehydrate) call, if you use it ## REMEMBER_PERSISTED diff --git a/packages/docs-website/src/content/docs/api/remember-enhancer.md b/packages/docs-website/src/content/docs/api/remember-enhancer.md index 5b20b1f..225147f 100644 --- a/packages/docs-website/src/content/docs/api/remember-enhancer.md +++ b/packages/docs-website/src/content/docs/api/remember-enhancer.md @@ -193,6 +193,28 @@ rememberEnhancer(window.localStorage, rememberedKeys, { - Type: `StoreEnhancer` - Description: A Redux enhancer to be used with your store +## Store Methods + +### store.unsafeRehydrate + +- **Type:** `(keys?: string[]) => Promise` +- **Description:** Reads the given keys from storage, rehydrates them into the store, and adds them to the remembered set so they are persisted from then on. Called with no arguments, it re-reads every currently remembered key. +- **Use Case:** Rehydrating a [lazy-loaded (injected) reducer](../usage/lazy-loaded-reducers.md) whose key was not known when the store was created +- **Why "unsafe":** It dispatches [`REMEMBER_REHYDRATED`](./actions.md#remember_rehydrated) again, which the rest of the documentation describes as happening exactly once, and it overlays whatever is in storage on top of live state. Both are fine when you call it deliberately, right after injecting a reducer; neither is safe on a timer or in response to arbitrary events. +- **Notes:** + - [`migrate`](#migrate) is **not** applied. It is a whole-state, run-once function, and re-running it over already-migrated state would corrupt it. If the lazy slice's stored data needs migrating, migrate it inside its own `unserialize`. + - If the read fails, the error goes to [`errorHandler`](#errorhandler), no action is dispatched, and the keys are **not** added to the remembered set — so a transient storage failure cannot cause the slice's initial state to be written over good stored data. + - The returned promise resolves once the state has been rehydrated, so you can `await` it before rendering the lazy route. + - With [`initActionType`](#initactiontype) set, call it only after that action has been dispatched. Before then Redux Remember is disabled, and the initial rehydration would later overwrite what you loaded. + +**Example:** +```ts +rootReducer.inject(lazyPersistedSlice); +await store.unsafeRehydrate(['lazyPersisted']); +``` + +See [Lazy-loaded Reducers](../usage/lazy-loaded-reducers.md) for the full walkthrough. + ## See Also - [rememberReducer](./remember-reducer.md) - Wrap your reducers diff --git a/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md index 64fe0f8..59c8382 100644 --- a/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md +++ b/packages/docs-website/src/content/docs/usage/lazy-loaded-reducers.md @@ -32,7 +32,7 @@ Redux Remember only ever touches the keys listed in `rememberedKeys`, so an inje For a slice you *do* want persisted, timing matters. Redux Remember reads storage and dispatches [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) once, when it initializes. A reducer injected after that point has already missed its rehydration, so its stored value would be dropped and it would start from its initial state. -Call [`store.rehydrate(keys)`](../api/remember-enhancer.md) after injecting the reducer. It reads those keys from storage, rehydrates them into the store, and adds them to the remembered set so they're persisted from then on: +Call [`store.unsafeRehydrate(keys)`](../api/remember-enhancer.md#storeunsaferehydrate) after injecting the reducer. It reads those keys from storage, rehydrates them into the store, and adds them to the remembered set so they're persisted from then on: ```ts const rootReducer = combineSlices(baseSlice); @@ -45,14 +45,33 @@ const store = configureStore({ }); // when the lazy slice loads: -rootReducer.inject(lazyPersistedSlice); // 1. add the reducer to the tree -await store.rehydrate(['lazyPersisted']); // 2. load its persisted state +rootReducer.inject(lazyPersistedSlice); // 1. add the reducer to the tree +await store.unsafeRehydrate(['lazyPersisted']); // 2. load its persisted state ``` -After this, `lazyPersisted` holds its stored value and is persisted on every change like any statically-defined key. Called with no arguments, `store.rehydrate()` re-reads every currently remembered key. +After this, `lazyPersisted` holds its stored value and is persisted on every change like any statically-defined key. Called with no arguments, `store.unsafeRehydrate()` re-reads every currently remembered key. + +## Why "unsafe"? + +The method is named `unsafeRehydrate` because it does two things the rest of Redux Remember does not: + +- It dispatches [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) again, which is otherwise documented as happening exactly once per store. Reducers that flip a one-way flag (such as a [Rehydration Gate](./rehydration-gate.md)) will see it a second time. +- It overlays whatever is in storage on top of live state. That is exactly what you want immediately after injecting a reducer, and it is not what you want in response to arbitrary events. + +Within those bounds it is safe by construction: + +- Actions dispatched while storage is being read are **not** rolled back — the state is re-read after the load, immediately before dispatching. +- Concurrent calls do not revert each other, so you can inject several lazy slices at once. +- A key only starts being persisted **after** its stored value has been loaded, so a slow driver or a failed read can never cause the slice's initial state to overwrite good stored data. +- [`migrate`](../api/remember-enhancer.md#migrate) is not re-run. It is a whole-state, run-once function; if a lazy slice's stored data needs migrating, do it in that slice's `unserialize`. + +Two things to keep in mind: + +- Await the returned promise before rendering the lazy route, otherwise it renders with initial state and then jumps to the stored value. +- If you use [`initActionType`](../api/remember-enhancer.md#initactiontype), call `unsafeRehydrate` only after that action has been dispatched — before then Redux Remember is disabled, and the initial rehydration would later overwrite what you loaded. ## See Also -- [`rememberEnhancer`](../api/remember-enhancer.md) — the `rememberedKeys` option and the `store.rehydrate` method +- [`rememberEnhancer`](../api/remember-enhancer.md) — the `rememberedKeys` option and the [`store.unsafeRehydrate`](../api/remember-enhancer.md#storeunsaferehydrate) method - [`REMEMBER_REHYDRATED`](../api/actions.md#remember_rehydrated) - [Using in Reducers](./using-in-reducers.md) diff --git a/packages/redux-remember/src/__tests__/index.test.ts b/packages/redux-remember/src/__tests__/index.test.ts index fbf27a2..4acc602 100644 --- a/packages/redux-remember/src/__tests__/index.test.ts +++ b/packages/redux-remember/src/__tests__/index.test.ts @@ -6,7 +6,7 @@ import type { Options } from '../types.ts'; describe('index.ts', () => { const mockRehydrate = { - rehydrate: vi.fn(), + loadKeys: vi.fn(), rehydrateReducer: vi.fn(() => 'REHYDRATE_REDUCER') }; @@ -15,7 +15,7 @@ describe('index.ts', () => { let index: typeof indexModule; beforeEach(async () => { - mockRehydrate.rehydrate = vi.fn(); + mockRehydrate.loadKeys = vi.fn(async () => ({})); mockRehydrate.rehydrateReducer = vi.fn(() => 'REHYDRATE_REDUCER'); mockInit = vi.fn(() => {}); mockCombineReducers = vi.fn(() => {}); @@ -129,7 +129,7 @@ describe('index.ts', () => { }; let mockCreateStore: StoreCreator; - const mockStore: any = { name: 'my-mocked-store' }; + let mockStore: any; const rememberedKeys = ['zz', 'bb', 'kk']; const rootReducer = (state = {}) => state; let rootReducerWrapper: Reducer; @@ -137,6 +137,12 @@ describe('index.ts', () => { const enhancer: any = 'dummy enhancer'; beforeEach(() => { + mockStore = { + name: 'my-mocked-store', + getState: vi.fn(() => ({})), + dispatch: vi.fn() + }; + mockCreateStore = vi.fn((wrapper) => { rootReducerWrapper = wrapper; return mockStore; @@ -261,19 +267,18 @@ describe('index.ts', () => { vi.useRealTimers(); }); - it('exposes store.rehydrate() and rehydrates the requested keys', async () => { + it('exposes store.unsafeRehydrate() and reads the requested keys', async () => { const storeMaker: StoreCreator = index.rememberEnhancer( mockDriver, [...rememberedKeys] )((() => mockStore) as StoreCreator); const store: any = storeMaker(rootReducer, initialState, enhancer); - expect(typeof store.rehydrate).toBe('function'); + expect(typeof store.unsafeRehydrate).toBe('function'); - await store.rehydrate(['newKey']); + await store.unsafeRehydrate(['newKey']); - expect(mockRehydrate.rehydrate).toHaveBeenCalledWith( - mockStore, + expect(mockRehydrate.loadKeys).toHaveBeenCalledWith( ['newKey'], expect.objectContaining({ driver: mockDriver, @@ -282,35 +287,123 @@ describe('index.ts', () => { ); }); - it('store.rehydrate() starts remembering newly requested keys', async () => { - const keys = ['aa', 'bb']; + it('store.unsafeRehydrate() does not apply migrate()', async () => { + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, [...rememberedKeys], { migrate: (state) => state } + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + await store.unsafeRehydrate(['newKey']); + + // migrate() is a whole-state, run-once function - re-running it over + // already-migrated state would be unsound + const [, loadOptions] = mockRehydrate.loadKeys.mock.calls[0]; + expect(loadOptions).not.toHaveProperty('migrate'); + }); + + it('store.unsafeRehydrate() remembers new keys without mutating the caller array', async () => { + const callerKeys = ['aa', 'bb']; + + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, callerKeys + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + await store.unsafeRehydrate(['aa', 'cc']); + + // the array the caller passed in is left alone + expect(callerKeys).toEqual(['aa', 'bb']); + // the store's own copy - shared with init() - gained 'cc' and did not + // duplicate 'aa', so 'cc' is persisted from now on + const [, storeKeys] = mockInit.mock.calls[0]; + expect(storeKeys).toEqual(['aa', 'bb', 'cc']); + }); + + it('store.unsafeRehydrate() with no arguments re-reads every remembered key', async () => { const storeMaker: StoreCreator = index.rememberEnhancer( - mockDriver, keys + mockDriver, ['aa', 'bb'] )((() => mockStore) as StoreCreator); const store: any = storeMaker(rootReducer, initialState, enhancer); - await store.rehydrate(['aa', 'cc']); + await store.unsafeRehydrate(); - // already-remembered keys are not duplicated, new ones are appended - expect(keys).toEqual(['aa', 'bb', 'cc']); + expect(mockRehydrate.loadKeys).toHaveBeenCalledWith( + ['aa', 'bb'], + expect.objectContaining({ driver: mockDriver }) + ); }); - it('store.rehydrate() with no arguments rehydrates every remembered key', async () => { - const keys = ['aa', 'bb']; + it('store.unsafeRehydrate() dispatches the state as of after the read', async () => { + mockStore.getState = vi.fn(() => ({ counter: 1 })); + + // state moves on while storage is being read + mockRehydrate.loadKeys = vi.fn(async () => { + mockStore.getState = vi.fn(() => ({ counter: 2 })); + return { lazy: 'loaded' }; + }); const storeMaker: StoreCreator = index.rememberEnhancer( - mockDriver, keys + mockDriver, ['counter'] )((() => mockStore) as StoreCreator); const store: any = storeMaker(rootReducer, initialState, enhancer); - await store.rehydrate(); + await store.unsafeRehydrate(['lazy']); - expect(mockRehydrate.rehydrate).toHaveBeenCalledWith( - mockStore, - keys, + // the payload must carry the post-read state, otherwise anything + // dispatched during the read is rolled back + expect(mockStore.dispatch).toHaveBeenCalledWith({ + type: actionTypes.REMEMBER_REHYDRATED, + payload: { counter: 2, lazy: 'loaded' } + }); + }); + + it('store.unsafeRehydrate() does nothing when the read fails', async () => { + mockRehydrate.loadKeys = vi.fn(async () => undefined); + + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, ['aa'] + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + await store.unsafeRehydrate(['bb']); + + expect(mockStore.dispatch).not.toHaveBeenCalled(); + + // 'bb' must not start being persisted - the next persist would write the + // slice's initial state over whatever is already in storage + const [, storeKeys] = mockInit.mock.calls[0]; + expect(storeKeys).toEqual(['aa']); + }); + + it('store.unsafeRehydrate() waits for the initial rehydration', async () => { + let finishInit = () => {}; + mockInit.mockImplementationOnce(() => new Promise((resolve) => { + finishInit = resolve; + })); + + const storeMaker: StoreCreator = index.rememberEnhancer( + mockDriver, ['aa'] + )((() => mockStore) as StoreCreator); + + const store: any = storeMaker(rootReducer, initialState, enhancer); + + const pending = store.unsafeRehydrate(['bb']); + await Promise.resolve(); + + // init() is still loading - reading now would let its dispatch roll us back + expect(mockRehydrate.loadKeys).not.toHaveBeenCalled(); + + finishInit(); + await pending; + + expect(mockRehydrate.loadKeys).toHaveBeenCalledWith( + ['bb'], expect.objectContaining({ driver: mockDriver }) ); }); diff --git a/packages/redux-remember/src/__tests__/rehydrate.test.ts b/packages/redux-remember/src/__tests__/rehydrate.test.ts index dcef969..d42a72b 100644 --- a/packages/redux-remember/src/__tests__/rehydrate.test.ts +++ b/packages/redux-remember/src/__tests__/rehydrate.test.ts @@ -1,4 +1,4 @@ -import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { describe, it, expect, beforeEach, afterEach, vi, type Mock } from 'vitest'; import type * as rehydrateModule from '../rehydrate.ts'; import { REMEMBER_REHYDRATED } from '../action-types.ts'; import type { Driver } from '../types.ts'; @@ -180,6 +180,82 @@ describe('rehydrate.ts', () => { }); }); + describe('loadKeys()', () => { + let mockPrefix: string; + let mockDriver: Driver; + let mockErrorHandler: Mock; + + const exec = (keys: string[], opts = {}) => mod.loadKeys( + keys, + { + prefix: mockPrefix, + driver: mockDriver, + unserialize: (data) => JSON.parse(data), + persistWholeStore: false, + errorHandler: mockErrorHandler, + ...opts + } + ); + + beforeEach(() => { + mockDriver = { + getItem: vi.fn((key) => JSON.stringify(`data-${key}`)), + setItem() {} + }; + + mockErrorHandler = vi.fn(); + mockPrefix = 'pref2.'; + }); + + it('reads the given keys one by one', async () => { + const res = await exec(['aa', 'bb']); + + expect(mockDriver.getItem).toHaveBeenCalledWith('pref2.aa'); + expect(mockDriver.getItem).toHaveBeenCalledWith('pref2.bb'); + + expect(res).toEqual({ + aa: 'data-pref2.aa', + bb: 'data-pref2.bb' + }); + }); + + it('reads the given keys out of the whole store', async () => { + mockDriver.getItem = vi.fn(() => JSON.stringify({ + aa: 'val-aa', + bb: 'val-bb', + cc: 'val-cc' + })); + + const res = await exec(['aa', 'cc'], { persistWholeStore: true }); + + expect(mockDriver.getItem).toHaveBeenCalledWith('pref2.rootState'); + + expect(res).toEqual({ + aa: 'val-aa', + cc: 'val-cc' + }); + }); + + it('returns an empty object when nothing is stored', async () => { + mockDriver.getItem = vi.fn(() => null); + + expect(await exec(['aa'])).toEqual({}); + }); + + it('returns undefined and reports the error when the read fails', async () => { + mockDriver.getItem = vi.fn(() => { + throw new Error('nope'); + }); + + expect(await exec(['aa'])).toBeUndefined(); + + expect(mockErrorHandler).toHaveBeenCalledWith( + expect.objectContaining({ name: 'RehydrateError' }) + ); + }); + + }); + describe('rehydrate()', () => { let mockState = {}; const mockStore = { diff --git a/packages/redux-remember/src/__tests__/unsafe-rehydrate.test.ts b/packages/redux-remember/src/__tests__/unsafe-rehydrate.test.ts new file mode 100644 index 0000000..61759c7 --- /dev/null +++ b/packages/redux-remember/src/__tests__/unsafe-rehydrate.test.ts @@ -0,0 +1,243 @@ +// End-to-end tests for store.unsafeRehydrate() against a real redux store and +// a real asynchronous driver. The guarantees below are all about *timing* +// between the storage read, the persist subscriber and unrelated dispatches, so +// they cannot be expressed with a mocked driver. +import { describe, it, expect, vi } from 'vitest'; +import { legacy_createStore as createStore, combineReducers } from 'redux'; +import type { Reducer } from 'redux'; +import { rememberReducer, rememberEnhancer } from '../index.ts'; + +const delay = (msecs: number) => new Promise((resolve) => setTimeout(resolve, msecs)); + +type TestDriver = { + data: Record, + delayMsecs: number, + failingKeys: string[], + getItem: (key: string) => Promise, + setItem: (key: string, value: string) => Promise +}; + +const createDriver = (data: Record = {}): TestDriver => { + const driver: TestDriver = { + data, + delayMsecs: 0, + failingKeys: [], + + getItem: async (key) => { + await delay(driver.delayMsecs); + + if (driver.failingKeys.some((failing) => key.endsWith(failing))) { + throw new Error(`cannot read ${key}`); + } + + return driver.data[key] ?? null; + }, + + setItem: async (key, value) => { + await delay(0); + driver.data[key] = value; + } + }; + + return driver; +}; + +const counter: Reducer = (state = 0, action: any) => ( + action.type === 'increment' ? state + 1 : state +); + +// stand-ins for lazily injected slices +const lazy: Reducer<{ value: string }> = (state = { value: 'initial' }) => state; +const otherLazy: Reducer<{ value: string }> = (state = { value: 'otherInitial' }) => state; + +const rootReducer = combineReducers({ counter, lazy, otherLazy }); + +const createTestStore = ( + driver: TestDriver, + rememberedKeys: string[], + options: Record = {} +) => createStore( + rememberReducer(rootReducer) as Reducer, + undefined, + rememberEnhancer(driver, rememberedKeys, { + errorHandler: vi.fn(), + persistThrottle: 10, + ...options + }) +) as any; + +// the initial rehydration plus one throttle window +const settle = () => delay(30); + +describe('store.unsafeRehydrate()', () => { + it('loads the persisted value of a key that was not remembered at startup', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }) + }); + + const store = createTestStore(driver, ['counter']); + await settle(); + + expect(store.getState().lazy).toEqual({ value: 'initial' }); + + await store.unsafeRehydrate(['lazy']); + + expect(store.getState().lazy).toEqual({ value: 'persisted' }); + }); + + it('persists the newly remembered key from then on', async () => { + const driver = createDriver(); + + const store = createTestStore(driver, ['counter']); + await settle(); + + await store.unsafeRehydrate(['lazy']); + + store.dispatch({ type: 'increment' }); + await delay(40); + + expect(driver.data['@@remember-lazy']).toBe( + JSON.stringify({ value: 'initial' }) + ); + }); + + it('keeps actions dispatched while storage is being read', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }) + }); + + const store = createTestStore(driver, ['counter']); + await settle(); + + driver.delayMsecs = 50; + const pending = store.unsafeRehydrate(['lazy']); + + await delay(10); + store.dispatch({ type: 'increment' }); + + await pending; + + // the rehydration must not roll the store back to a pre-read snapshot + expect(store.getState().counter).toBe(1); + expect(store.getState().lazy).toEqual({ value: 'persisted' }); + }); + + it('does not overwrite stored data while the read is still in flight', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }) + }); + + const store = createTestStore(driver, ['counter']); + await settle(); + + driver.delayMsecs = 50; + const pending = store.unsafeRehydrate(['lazy']); + + // an unrelated action runs the persist subscriber mid-read; the key must not + // be persisted before its stored value has been loaded, or the slice's + // initial state would be written over it + await delay(10); + store.dispatch({ type: 'increment' }); + await delay(25); + + expect(driver.data['@@remember-lazy']).toBe( + JSON.stringify({ value: 'persisted' }) + ); + + await pending; + + expect(store.getState().lazy).toEqual({ value: 'persisted' }); + }); + + it('handles concurrent calls without reverting each other', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }), + '@@remember-otherLazy': JSON.stringify({ value: 'otherPersisted' }) + }); + + const store = createTestStore(driver, ['counter']); + await settle(); + + driver.delayMsecs = 50; + const first = store.unsafeRehydrate(['lazy']); + await delay(10); + const second = store.unsafeRehydrate(['otherLazy']); + + await Promise.all([first, second]); + + expect(store.getState().lazy).toEqual({ value: 'persisted' }); + expect(store.getState().otherLazy).toEqual({ value: 'otherPersisted' }); + }); + + it('does not re-run migrate()', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }) + }); + + const migrate = vi.fn((state) => state); + const store = createTestStore(driver, ['counter'], { migrate }); + await settle(); + + expect(migrate).toHaveBeenCalledTimes(1); + + await store.unsafeRehydrate(['lazy']); + + // migrate() is a whole-state, run-once function + expect(migrate).toHaveBeenCalledTimes(1); + }); + + it('leaves the callers rememberedKeys array untouched', async () => { + const driver = createDriver(); + const rememberedKeys = ['counter']; + + const store = createTestStore(driver, rememberedKeys); + await settle(); + + await store.unsafeRehydrate(['lazy']); + + expect(rememberedKeys).toEqual(['counter']); + }); + + it('does not start persisting a key whose read failed', async () => { + const driver = createDriver({ + '@@remember-lazy': JSON.stringify({ value: 'persisted' }) + }); + + const errorHandler = vi.fn(); + const store = createTestStore(driver, ['counter'], { errorHandler }); + await settle(); + + driver.failingKeys = ['lazy']; + await store.unsafeRehydrate(['lazy']); + + expect(errorHandler).toHaveBeenCalledWith( + expect.objectContaining({ name: 'RehydrateError' }) + ); + + driver.failingKeys = []; + store.dispatch({ type: 'increment' }); + await delay(40); + + // stored data must survive a failed rehydration + expect(driver.data['@@remember-lazy']).toBe( + JSON.stringify({ value: 'persisted' }) + ); + }); + + it('re-reads every remembered key when called with no arguments', async () => { + const driver = createDriver({ + '@@remember-counter': JSON.stringify(7) + }); + + const store = createTestStore(driver, ['counter']); + await settle(); + + expect(store.getState().counter).toBe(7); + + // simulates another tab writing to storage + driver.data['@@remember-counter'] = JSON.stringify(42); + await store.unsafeRehydrate(); + + expect(store.getState().counter).toBe(42); + }); +}); diff --git a/packages/redux-remember/src/index.ts b/packages/redux-remember/src/index.ts index 682b99a..2a37d12 100644 --- a/packages/redux-remember/src/index.ts +++ b/packages/redux-remember/src/index.ts @@ -1,5 +1,5 @@ import init from './init.ts'; -import { rehydrate } from './rehydrate.ts'; +import { loadKeys } from './rehydrate.ts'; import { REMEMBER_REHYDRATED, REMEMBER_PERSISTED } from './action-types.ts'; import type { Driver, Options, RememberEnhancerStoreExt } from './types.ts'; import type { @@ -81,24 +81,35 @@ const rememberEnhancer = { + // Owned by this store. store.unsafeRehydrate() appends to it and init() + // holds the same reference, so keys added later start being persisted. + // The caller's own array is never mutated. + const keys = [...rememberedKeys]; + let isInitialized = false; - const initialize = (store: Store) => init( - store, - rememberedKeys, - { - driver, - prefix, - serialize, - unserialize, - migrate, - persistThrottle, - persistDebounce, - persistWholeStore, - errorHandler - } - ); + let initialized: Promise | undefined; + + const initialize = (store: Store) => { + initialized = init( + store, + keys, + { + driver, + prefix, + serialize, + unserialize, + migrate, + persistThrottle, + persistDebounce, + persistWholeStore, + errorHandler + } + ); + + return initialized; + }; - const store = createStore( + const store: Store = createStore( (state, action) => { if (!isInitialized && initActionType @@ -114,22 +125,49 @@ const rememberEnhancer = => { - keys.forEach((key) => { - if (!rememberedKeys.includes(key)) { - rememberedKeys.push(key); + // Rehydrate (and start remembering) additional keys after the store exists. + // This is what makes lazy-loaded / injected reducers work: inject the + // reducer, then `await store.unsafeRehydrate([key])` to load its persisted + // value and keep persisting it from then on. With no arguments it re-reads + // every currently remembered key. + // + // Deliberately named "unsafe": it re-dispatches REMEMBER_REHYDRATED, which + // consumers are otherwise documented to see exactly once, and it overlays + // stored data on top of live state. See the docs for the full caveats. + const unsafeRehydrate = async (keysToLoad: string[] = [...keys]): Promise => { + // Never race the initial rehydration - its payload would roll this back. + await initialized; + + const loaded = await loadKeys( + keysToLoad, + { prefix, driver, unserialize, persistWholeStore, errorHandler } + ); + + // A failed read must not add the keys to the remembered set: the next + // persist would write the slice's initial state over good stored data. + if (!loaded) { + return; + } + + keysToLoad.forEach((key) => { + if (!keys.includes(key)) { + keys.push(key); } }); - await rehydrate( - store, - keys, - { prefix, driver, unserialize, migrate, persistWholeStore, errorHandler } - ); + // getState() is read here - after the await, in the same tick as the + // dispatch - so anything dispatched while storage was being read is kept + // rather than rolled back to a pre-read snapshot. + // + // `migrate` is intentionally not applied: it is a whole-state, run-once + // function, and re-running it over already-migrated state is unsound. + store.dispatch({ + type: REMEMBER_REHYDRATED, + payload: { + ...store.getState(), + ...loaded + } + }); }; if (!initActionType) { @@ -137,7 +175,7 @@ const rememberEnhancer = ; + +// Reads the given keys from storage without touching the store. Returns +// undefined when the read itself failed, so callers can tell that apart from a +// successful read that simply found nothing stored (an empty object). +export const loadKeys = async ( + keys: string[], + { + driver, + prefix, + unserialize, + persistWholeStore, + errorHandler + }: LoadKeysOptions +): Promise | undefined> => { + try { + const load = persistWholeStore + ? loadAll + : loadAllKeyed; + + return await load({ + rememberedKeys: keys, + driver, + prefix, + unserialize + }); + } catch (err) { + errorHandler(new RehydrateError(err)); + return undefined; + } +}; + export const rehydrate = async ( store: Store, rememberedKeys: string[], diff --git a/packages/redux-remember/src/types.ts b/packages/redux-remember/src/types.ts index 068f4b2..a73dac9 100644 --- a/packages/redux-remember/src/types.ts +++ b/packages/redux-remember/src/types.ts @@ -25,8 +25,8 @@ export type ExtendedOptions = Options & { driver: Driver }; -export type RehydrateFunction = (keys?: string[]) => Promise; +export type UnsafeRehydrateFunction = (keys?: string[]) => Promise; export type RememberEnhancerStoreExt = { - rehydrate: RehydrateFunction + unsafeRehydrate: UnsafeRehydrateFunction };