feat(forms-manager): add support for session storage

Adds ability to use session storage for persistence, configurable through NgFormsManagerConfig

Author: Nick Linnenbrügger

README.md

@@ -246,7 +246,7 @@ formsManager.destroy();
 formsManager.controlChanges('login').pipe(takeUntil(controlDestroyed('login')));
 ```
 
-## Persist to Local Storage
+## Persist to Local Storage or Session Storage
 
 In the `upsert` method, pass the `persistState` flag:
 
@@ -256,6 +256,8 @@ formsManager.upsert(formName, abstractContorl, {
 });
 ```
 
+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).
+
 ## Validators
 
 The library exposes two helpers method for adding cross component validation:
@@ -335,7 +337,7 @@ interface AppForms {
     name: string;
     age: number;
     city: string;
-  }
+  };
 }
 ```
 
@@ -426,6 +428,7 @@ 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,40 +1,47 @@
 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: Partial<Config>,
-  providerConfig: Partial<Config> = {},
-  inlineConfig: Partial<Config>
-) {
+  defaults: Config,
+  providerConfig: DeepPartial<Config> = {},
+  inlineConfig: DeepPartial<Config>
+): Config {
   return {
     ...defaults,
+    ...providerConfig,
+    ...inlineConfig,
     storage: {
       ...defaults.storage,
       ...providerConfig.storage,
       ...inlineConfig.storage,
     },
-    ...providerConfig,
-    ...inlineConfig,
-  } as Config;
+  };
 }
 
 export class NgFormsManagerConfig {
-  constructor(private config: Partial<Config> = {}) {}
+  constructor(private config: DeepPartial<Config> = {}) {}
 
-  merge(inline: Partial<Config> = {}): Config {
+  merge(inline: DeepPartial<Config> = {}): Config {
     return mergeConfig(defaults, this.config, inline);
   }
 }

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

@@ -1,7 +1,8 @@
-import { fakeAsync, tick } from '@angular/core/testing';
+import { fakeAsync, TestBed, tick } from '@angular/core/testing';
 import { FormArray, FormControl, FormGroup, Validators } from '@angular/forms';
 import { NgFormsManager } from './forms-manager';
-import { NgFormsManagerConfig } from './config';
+import { NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from './config';
+import { LOCAL_STORAGE_TOKEN, SESSION_STORAGE_TOKEN } from './injection-tokens';
 
 // get forms snapshot
 function getSnapshot(formsManager) {
@@ -1445,4 +1446,66 @@ describe('FormsManager', () => {
       formsManager = null;
     });
   });
+
+  describe('Storage', () => {
+    let formsManager: NgFormsManager;
+    let localStorageMock: jasmine.SpyObj<Storage>;
+    let sessionStorageMock: jasmine.SpyObj<Storage>;
+
+    function configureTestingModule(ngFormsManagerConfig: NgFormsManagerConfig) {
+      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']),
+          },
+        ],
+      });
+      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 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();
+    });
+
+    afterEach(() => {
+      formsManager.unsubscribe();
+      formsManager = null;
+    });
+  });
 });

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

@@ -3,24 +3,33 @@ 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, NgFormsManagerConfig, NG_FORMS_MANAGER_CONFIG } from './config';
+import { Config, NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } 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';
 
 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) {
+  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
+  ) {
     this.store = new FormsStore({} as FormsState);
+    this.browserStorage =
+      this.config.merge().storage.type === 'LocalStorage' ? this.localStorage : this.sessionStorage;
   }
 
   /**
@@ -490,7 +499,7 @@ export class NgFormsManager<FormsState = any> {
    *
    * @example
    *
-   * Removes the control from the store and from LocalStorage
+   * Removes the control from the store and from LocalStorage/SessionStorage
    *
    * manager.clear('login');
    *
@@ -593,19 +602,22 @@ export class NgFormsManager<FormsState = any> {
   }
 
   private removeFromStorage() {
-    localStorage.setItem(this.config.merge().storage.key, JSON.stringify(this.store.getValue()));
+    this.browserStorage?.setItem(
+      this.config.merge().storage.key,
+      JSON.stringify(this.store.getValue())
+    );
   }
 
   private updateStorage(name: keyof FormsState, value: any, config) {
     if (isBrowser() && config.persistState) {
       const storageValue = this.getFromStorage(config.storage.key);
       storageValue[name] = filterControlKeys(value);
-      localStorage.setItem(config.storage.key, JSON.stringify(storageValue));
+      this.browserStorage?.setItem(config.storage.key, JSON.stringify(storageValue));
     }
   }
 
   private getFromStorage(key: string) {
-    return JSON.parse(localStorage.getItem(key) || '{}');
+    return JSON.parse(this.browserStorage?.getItem(key) || '{}');
   }
 
   private deleteControl(name: FormKeys<FormsState>) {

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

@@ -0,0 +1,62 @@
+import { TestBed } from '@angular/core/testing';
+import { PLATFORM_ID } from '@angular/core';
+import { LOCAL_STORAGE_TOKEN, SESSION_STORAGE_TOKEN } from './injection-tokens';
+
+const PLATFORM_BROWSER_ID: string = 'browser';
+const PLATFORM_SERVER_ID: string = 'server';
+const PLATFORM_WORKER_APP_ID: string = 'browserWorkerApp';
+const PLATFORM_WORKER_UI_ID: string = 'browserWorkerUi';
+
+describe('SESSION_STORAGE_TOKEN', () => {
+  it('should contain the sessionStorage object on platform browser', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_BROWSER_ID }],
+    });
+    expect(TestBed.inject(SESSION_STORAGE_TOKEN)).toBe(sessionStorage);
+  });
+  it('should contain undefined on platform server', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_SERVER_ID }],
+    });
+    expect(TestBed.inject(SESSION_STORAGE_TOKEN)).toBeUndefined();
+  });
+  it('should contain undefined on platform worker app', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_WORKER_APP_ID }],
+    });
+    expect(TestBed.inject(SESSION_STORAGE_TOKEN)).toBeUndefined();
+  });
+  it('should contain undefined on platform worker ui', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_WORKER_UI_ID }],
+    });
+    expect(TestBed.inject(SESSION_STORAGE_TOKEN)).toBeUndefined();
+  });
+});
+
+describe('LOCAL_STORAGE_TOKEN', () => {
+  it('should contain the localStorage object on platform browser', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_BROWSER_ID }],
+    });
+    expect(TestBed.inject(LOCAL_STORAGE_TOKEN)).toBe(localStorage);
+  });
+  it('should contain undefined on platform server', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_SERVER_ID }],
+    });
+    expect(TestBed.inject(LOCAL_STORAGE_TOKEN)).toBeUndefined();
+  });
+  it('should contain undefined on platform worker app', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_WORKER_APP_ID }],
+    });
+    expect(TestBed.inject(LOCAL_STORAGE_TOKEN)).toBeUndefined();
+  });
+  it('should contain undefined on platform worker ui', () => {
+    TestBed.configureTestingModule({
+      providers: [{ provide: PLATFORM_ID, useValue: PLATFORM_WORKER_UI_ID }],
+    });
+    expect(TestBed.inject(LOCAL_STORAGE_TOKEN)).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,22 @@
+import { isPlatformBrowser } from '@angular/common';
+import { InjectionToken, PLATFORM_ID, inject } from '@angular/core';
+
+/**
+ * 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
+>('SESSION_STORAGE_TOKEN', {
+  providedIn: 'root',
+  factory: () => (isPlatformBrowser(inject(PLATFORM_ID)) ? sessionStorage : undefined),
+});
+
+/**
+ * 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),
+});