feat(forms-manager): add support for configurable browser storage

Adds ability to use sessionStorage or other custom storage solution for persistence.

Author: nickhh76

README.md

@@ -246,17 +246,64 @@ formsManager.destroy();
 formsManager.controlChanges('login').pipe(takeUntil(controlDestroyed('login')));
 ```
 
-## Persist to Local Storage or Session Storage
+## Persist to browser storage (localStorage, sessionStorage or custom storage solution)
 
 In the `upsert` method, pass the `persistState` flag:
 
 ```ts
 formsManager.upsert(formName, abstractContorl, {
-  persistState: true;
+  persistState: true,
 });
 ```
 
-By default, the state is persisted to Local Storage. Session Storage can be used instead by passing the `NG_FORMS_MANAGER_CONFIG` provider (see below).
+By default, the state is persisted to `localStorage` ([Link](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage)).
+
+For storage to `sessionStorage` ([Link](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)), add `FORMS_MANAGER_SESSION_STORAGE_PROVIDER` to the providers array in `app.module.ts`:
+
+```ts
+import { FORMS_MANAGER_SESSION_STORAGE_PROVIDER } from '@ngneat/forms-manager';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [ ... ],
+  providers: [
+    ...
+    FORMS_MANAGER_SESSION_STORAGE_PROVIDER,
+    ...
+  ],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
+
+Furthermore, a **custom storage provider**, which must implement the `Storage` interface ([Link](https://developer.mozilla.org/en-US/docs/Web/API/Storage)) can be provided through the `FORMS_MANAGER_STORAGE` token:
+
+```ts
+import { FORMS_MANAGER_STORAGE } from '@ngneat/forms-manager';
+
+class MyStorage implements Storage {
+  public clear() { ... }
+  public key(index: number): string | null { ... }
+  public getItem(key: string): string | null { ... }
+  public removeItem(key: string) { ... }
+  public setItem(key: string, value: string) { ... }
+}
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [ ... ],
+  providers: [
+    ...
+    {
+      provide: FORMS_MANAGER_STORAGE,
+      useValue: MyStorage,
+    },
+    ...
+  ],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+```
 
 ## Validators
 
@@ -428,7 +475,6 @@ import { NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from '@ngneat/forms-man
       useValue: new NgFormsManagerConfig({
         debounceTime: 1000, // defaults to 300
         storage: {
-          type: 'SessionStorage',
           key: 'NgFormManager',
         },
       }),

projects/ngneat/forms-manager/src/lib/config.ts

@@ -1,30 +1,23 @@
 import { InjectionToken } from '@angular/core';
 
-type DeepPartial<T> = {
-  [P in keyof T]?: DeepPartial<T[P]>;
-};
-
-export type StorageOption = 'LocalStorage' | 'SessionStorage';
 export type Config = {
   storage: {
-    type: StorageOption;
     key: string;
   };
   debounceTime: number;
 };
 
 const defaults: Config = {
   storage: {
-    type: 'LocalStorage',
     key: 'ngFormsManager',
   },
   debounceTime: 300,
 };
 
 export function mergeConfig(
   defaults: Config,
-  providerConfig: DeepPartial<Config> = {},
-  inlineConfig: DeepPartial<Config>
+  providerConfig: Partial<Config> = {},
+  inlineConfig: Partial<Config>
 ): Config {
   return {
     ...defaults,
@@ -39,9 +32,9 @@ export function mergeConfig(
 }
 
 export class NgFormsManagerConfig {
-  constructor(private config: DeepPartial<Config> = {}) {}
+  constructor(private config: Partial<Config> = {}) {}
 
-  merge(inline: DeepPartial<Config> = {}): Config {
+  merge(inline: Partial<Config> = {}): Config {
     return mergeConfig(defaults, this.config, inline);
   }
 }

projects/ngneat/forms-manager/src/lib/forms-manager.spec.ts

@@ -1,8 +1,9 @@
 import { fakeAsync, TestBed, tick } from '@angular/core/testing';
 import { FormArray, FormControl, FormGroup, Validators } from '@angular/forms';
 import { NgFormsManager } from './forms-manager';
-import { NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from './config';
-import { LOCAL_STORAGE_TOKEN, SESSION_STORAGE_TOKEN } from './injection-tokens';
+import { NgFormsManagerConfig } from './config';
+import { FORMS_MANAGER_STORAGE, LOCAL_STORAGE_TOKEN } from './injection-tokens';
+import { Provider } from '@angular/core';
 
 // get forms snapshot
 function getSnapshot(formsManager) {
@@ -1449,58 +1450,48 @@ describe('FormsManager', () => {
 
   describe('Storage', () => {
     let formsManager: NgFormsManager;
-    let localStorageMock: jasmine.SpyObj<Storage>;
-    let sessionStorageMock: jasmine.SpyObj<Storage>;
-
-    function configureTestingModule(ngFormsManagerConfig: NgFormsManagerConfig) {
+    let localStorageMock: jasmine.SpyObj<Storage> = jasmine.createSpyObj('localStorage', [
+      'setItem',
+      'getItem',
+    ]);
+    let customStorageMock: jasmine.SpyObj<Storage> = jasmine.createSpyObj('customStorage', [
+      'setItem',
+      'getItem',
+    ]);
+
+    function configureTestingModule(providers: Array<Provider>) {
       TestBed.configureTestingModule({
-        providers: [
-          NgFormsManager,
-          {
-            provide: NG_FORMS_MANAGER_CONFIG,
-            useValue: ngFormsManagerConfig,
-          },
-          {
-            provide: LOCAL_STORAGE_TOKEN,
-            useValue: jasmine.createSpyObj('localStorage', ['setItem', 'getItem']),
-          },
-          {
-            provide: SESSION_STORAGE_TOKEN,
-            useValue: jasmine.createSpyObj('sessionStorage', ['setItem', 'getItem']),
-          },
-        ],
+        providers: [NgFormsManager, ...providers],
       });
       formsManager = TestBed.inject(NgFormsManager);
-      localStorageMock = TestBed.inject(LOCAL_STORAGE_TOKEN) as jasmine.SpyObj<Storage>;
-      sessionStorageMock = TestBed.inject(SESSION_STORAGE_TOKEN) as jasmine.SpyObj<Storage>;
 
       formsManager.upsert('user', new FormGroup({ control: new FormControl('control') }), {
         persistState: true,
       });
     }
 
-    it('should store to localStorage when storage parameter omitted in NG_FORMS_MANAGER_CONFIG', () => {
-      configureTestingModule(new NgFormsManagerConfig());
-      expect(localStorageMock.getItem).toHaveBeenCalled();
-      expect(localStorageMock.setItem).toHaveBeenCalled();
-      expect(sessionStorageMock.getItem).not.toHaveBeenCalled();
-      expect(sessionStorageMock.setItem).not.toHaveBeenCalled();
-    });
+    it('should store to localStorage (by default) when FORMS_MANAGER_STORAGE not provided', () => {
+      configureTestingModule([
+        {
+          provide: LOCAL_STORAGE_TOKEN,
+          useValue: localStorageMock,
+        },
+      ]);
 
-    it('should store to localStorage when configured as such in NG_FORMS_MANAGER_CONFIG', () => {
-      configureTestingModule(new NgFormsManagerConfig({ storage: { type: 'LocalStorage' } }));
       expect(localStorageMock.getItem).toHaveBeenCalled();
       expect(localStorageMock.setItem).toHaveBeenCalled();
-      expect(sessionStorageMock.getItem).not.toHaveBeenCalled();
-      expect(sessionStorageMock.setItem).not.toHaveBeenCalled();
     });
 
-    it('should store to sessionStorage when configured as such in NG_FORMS_MANAGER_CONFIG', () => {
-      configureTestingModule(new NgFormsManagerConfig({ storage: { type: 'SessionStorage' } }));
-      expect(sessionStorageMock.getItem).toHaveBeenCalled();
-      expect(sessionStorageMock.setItem).toHaveBeenCalled();
-      expect(localStorageMock.getItem).not.toHaveBeenCalled();
-      expect(localStorageMock.setItem).not.toHaveBeenCalled();
+    it('should store to custom storage, provided through FORMS_MANAGER_STORAGE', () => {
+      configureTestingModule([
+        {
+          provide: FORMS_MANAGER_STORAGE,
+          useValue: customStorageMock,
+        },
+      ]);
+
+      expect(customStorageMock.getItem).toHaveBeenCalled();
+      expect(customStorageMock.setItem).toHaveBeenCalled();
     });
 
     afterEach(() => {

projects/ngneat/forms-manager/src/lib/forms-manager.ts

@@ -3,33 +3,29 @@ import { AbstractControl, FormArray, FormGroup } from '@angular/forms';
 import { EMPTY, merge, Observable, Subject, Subscription, timer } from 'rxjs';
 import { debounce, distinctUntilChanged, filter, map, mapTo } from 'rxjs/operators';
 import { deleteControl, findControl, handleFormArray, toStore } from './builders';
-import { Config, NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from './config';
+import { Config, NgFormsManagerConfig, NG_FORMS_MANAGER_CONFIG } from './config';
 import { FormsStore } from './forms-manager.store';
 import { isEqual } from './isEqual';
 import { Control, ControlFactory, FormKeys, HashMap, UpsertConfig } from './types';
 import { coerceArray, filterControlKeys, filterNil, isBrowser, mergeDeep } from './utils';
-import { LOCAL_STORAGE_TOKEN, SESSION_STORAGE_TOKEN } from './injection-tokens';
+import { FORMS_MANAGER_STORAGE } from './injection-tokens';
 
 const NO_DEBOUNCE = Symbol('NO_DEBOUNCE');
 
 // @dynamic; see https://angular.io/guide/angular-compiler-options#strictmetadataemit
 @Injectable({ providedIn: 'root' })
 export class NgFormsManager<FormsState = any> {
   private readonly store: FormsStore<FormsState>;
-  private readonly browserStorage?: Storage;
   private valueChanges$$: Map<keyof FormsState, Subscription> = new Map();
   private instances$$: Map<keyof FormsState, AbstractControl> = new Map();
   private initialValues$$: Map<keyof FormsState, any> = new Map();
   private destroy$$ = new Subject();
 
   constructor(
     @Optional() @Inject(NG_FORMS_MANAGER_CONFIG) private config: NgFormsManagerConfig,
-    @Optional() @Inject(LOCAL_STORAGE_TOKEN) private readonly localStorage?: Storage,
-    @Optional() @Inject(SESSION_STORAGE_TOKEN) private readonly sessionStorage?: Storage
+    @Optional() @Inject(FORMS_MANAGER_STORAGE) private readonly browserStorage?: Storage
   ) {
     this.store = new FormsStore({} as FormsState);
-    this.browserStorage =
-      this.config.merge().storage.type === 'LocalStorage' ? this.localStorage : this.sessionStorage;
   }
 
   /**
@@ -499,7 +495,7 @@ export class NgFormsManager<FormsState = any> {
    *
    * @example
    *
-   * Removes the control from the store and from LocalStorage/SessionStorage
+   * Removes the control from the store and from browser storage
    *
    * manager.clear('login');
    *

projects/ngneat/forms-manager/src/lib/injection-tokens.spec.ts

@@ -1,6 +1,11 @@
 import { TestBed } from '@angular/core/testing';
 import { PLATFORM_ID } from '@angular/core';
-import { LOCAL_STORAGE_TOKEN, SESSION_STORAGE_TOKEN } from './injection-tokens';
+import {
+  FORMS_MANAGER_SESSION_STORAGE_PROVIDER,
+  FORMS_MANAGER_STORAGE,
+  LOCAL_STORAGE_TOKEN,
+  SESSION_STORAGE_TOKEN,
+} from './injection-tokens';
 
 const PLATFORM_BROWSER_ID: string = 'browser';
 const PLATFORM_SERVER_ID: string = 'server';
@@ -60,3 +65,17 @@ describe('LOCAL_STORAGE_TOKEN', () => {
     expect(TestBed.inject(LOCAL_STORAGE_TOKEN)).toBeUndefined();
   });
 });
+
+describe('FORMS_MANAGER_STORAGE', () => {
+  it('should contain the LOCAL_STORAGE_TOKEN by default', () => {
+    TestBed.configureTestingModule({});
+    expect(TestBed.inject(FORMS_MANAGER_STORAGE)).toBe(TestBed.inject(LOCAL_STORAGE_TOKEN));
+  });
+});
+
+describe('FORMS_MANAGER_SESSION_STORAGE_PROVIDER', () => {
+  it('should provide SESSION_STORAGE_TOKEN', () => {
+    TestBed.configureTestingModule({ providers: [FORMS_MANAGER_SESSION_STORAGE_PROVIDER] });
+    expect(TestBed.inject(FORMS_MANAGER_STORAGE)).toBe(TestBed.inject(SESSION_STORAGE_TOKEN));
+  });
+});

projects/ngneat/forms-manager/src/lib/injection-tokens.ts

@@ -1,8 +1,9 @@
 import { isPlatformBrowser } from '@angular/common';
-import { InjectionToken, PLATFORM_ID, inject } from '@angular/core';
+import { inject, InjectionToken, PLATFORM_ID, Provider } from '@angular/core';
 
 /**
- * Injection Token to safely inject {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage} to Angular DI
+ * Injection Token to safely inject
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage} to Angular DI
  */
 export const SESSION_STORAGE_TOKEN: InjectionToken<Storage | undefined> = new InjectionToken<
   Storage | undefined
@@ -12,11 +13,34 @@ export const SESSION_STORAGE_TOKEN: InjectionToken<Storage | undefined> = new In
 });
 
 /**
- * Injection Token to safely inject {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage} to Angular DI
+ * Injection Token to safely inject
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage} to Angular DI
  */
 export const LOCAL_STORAGE_TOKEN: InjectionToken<Storage | undefined> = new InjectionToken<
   Storage | undefined
 >('LOCAL_STORAGE_TOKEN', {
   providedIn: 'root',
   factory: () => (isPlatformBrowser(inject(PLATFORM_ID)) ? localStorage : undefined),
 });
+
+/**
+ * Injection Token to inject custom storage approach for persistence; must implement
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Storage} interface
+ */
+export const FORMS_MANAGER_STORAGE = new InjectionToken<Storage | undefined>(
+  'FORMS_MANAGER_STORAGE',
+  {
+    providedIn: 'root',
+    factory: () =>
+      isPlatformBrowser(inject(PLATFORM_ID)) ? inject(LOCAL_STORAGE_TOKEN) : undefined,
+  }
+);
+
+/**
+ * Value provider that injects usage of
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage} for persistence
+ */
+export const FORMS_MANAGER_SESSION_STORAGE_PROVIDER: Provider = {
+  provide: FORMS_MANAGER_STORAGE,
+  useExisting: SESSION_STORAGE_TOKEN,
+};

projects/ngneat/forms-manager/src/public_api.ts

@@ -1,3 +1,7 @@
 export { NgFormsManager } from './lib/forms-manager';
 export { setAsyncValidators, setValidators } from './lib/validators';
 export { NgFormsManagerConfig, NG_FORMS_MANAGER_CONFIG } from './lib/config';
+export {
+  FORMS_MANAGER_STORAGE,
+  FORMS_MANAGER_SESSION_STORAGE_PROVIDER,
+} from './lib/injection-tokens';