Merge pull request #32 from nickhh76/feature/session-storage

Author: NetanelBasal

README.md

@@ -246,16 +246,65 @@ formsManager.destroy();
 formsManager.controlChanges('login').pipe(takeUntil(controlDestroyed('login')));
 ```
 
-## Persist to Local 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 `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
 
 The library exposes two helpers method for adding cross component validation:
@@ -335,7 +384,7 @@ interface AppForms {
     name: string;
     age: number;
     city: string;
-  }
+  };
 }
 ```
 

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

@@ -15,20 +15,20 @@ const defaults: Config = {
 };
 
 export function mergeConfig(
-  defaults: Partial<Config>,
+  defaults: Config,
   providerConfig: Partial<Config> = {},
   inlineConfig: Partial<Config>
-) {
+): Config {
   return {
     ...defaults,
+    ...providerConfig,
+    ...inlineConfig,
     storage: {
       ...defaults.storage,
       ...providerConfig.storage,
       ...inlineConfig.storage,
     },
-    ...providerConfig,
-    ...inlineConfig,
-  } as Config;
+  };
 }
 
 export class NgFormsManagerConfig {

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

@@ -1,7 +1,14 @@
-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 {
+  FORMS_MANAGER_SESSION_STORAGE_PROVIDER,
+  FORMS_MANAGER_STORAGE,
+  LOCAL_STORAGE_TOKEN,
+  SESSION_STORAGE_TOKEN,
+} from './injection-tokens';
+import { Provider } from '@angular/core';
 
 // get forms snapshot
 function getSnapshot(formsManager) {
@@ -1445,4 +1452,73 @@ describe('FormsManager', () => {
       formsManager = null;
     });
   });
+
+  describe('Storage', () => {
+    let formsManager: NgFormsManager;
+    let localStorageMock: jasmine.SpyObj<Storage> = jasmine.createSpyObj('localStorage', [
+      'setItem',
+      'getItem',
+    ]);
+    let sessionStorageMock: jasmine.SpyObj<Storage> = jasmine.createSpyObj('sessionStorage', [
+      'setItem',
+      'getItem',
+    ]);
+    let customStorageMock: jasmine.SpyObj<Storage> = jasmine.createSpyObj('customStorage', [
+      'setItem',
+      'getItem',
+    ]);
+
+    function configureTestingModule(providers: Array<Provider>) {
+      TestBed.configureTestingModule({
+        providers: [NgFormsManager, ...providers],
+      });
+      formsManager = TestBed.inject(NgFormsManager);
+
+      formsManager.upsert('user', new FormGroup({ control: new FormControl('control') }), {
+        persistState: true,
+      });
+    }
+
+    it('should store to localStorage (by default) when FORMS_MANAGER_STORAGE not provided', () => {
+      configureTestingModule([
+        {
+          provide: LOCAL_STORAGE_TOKEN,
+          useValue: localStorageMock,
+        },
+      ]);
+
+      expect(localStorageMock.getItem).toHaveBeenCalled();
+      expect(localStorageMock.setItem).toHaveBeenCalled();
+    });
+
+    it('should store to sessionStorage when FORMS_MANAGER_SESSION_STORAGE_PROVIDER used', () => {
+      configureTestingModule([
+        {
+          provide: SESSION_STORAGE_TOKEN,
+          useValue: sessionStorageMock,
+        },
+        FORMS_MANAGER_SESSION_STORAGE_PROVIDER,
+      ]);
+
+      expect(sessionStorageMock.getItem).toHaveBeenCalled();
+      expect(sessionStorageMock.setItem).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(() => {
+      formsManager.unsubscribe();
+      formsManager = null;
+    });
+  });
 });

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

@@ -8,9 +8,11 @@ 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 { 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>;
@@ -19,7 +21,10 @@ export class NgFormsManager<FormsState = any> {
   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,
+    @Inject(FORMS_MANAGER_STORAGE) private readonly browserStorage?: Storage
+  ) {
     this.store = new FormsStore({} as FormsState);
   }
 
@@ -490,7 +495,7 @@ export class NgFormsManager<FormsState = any> {
    *
    * @example
    *
-   * Removes the control from the store and from LocalStorage
+   * Removes the control from the store and from browser storage
    *
    * manager.clear('login');
    *
@@ -593,19 +598,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,81 @@
+import { TestBed } from '@angular/core/testing';
+import { PLATFORM_ID } from '@angular/core';
+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';
+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();
+  });
+});
+
+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

@@ -0,0 +1,46 @@
+import { isPlatformBrowser } from '@angular/common';
+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
+ */
+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),
+});
+
+/**
+ * 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';