watch method

README.md

@@ -189,11 +189,8 @@ this.storage.get('notexisting').subscribe((data) => {
 ```
 
 Note you'll only get *one* value: the `Observable` is here for asynchrony but is not meant to
-emit again when the stored data is changed. And it's normal: if app data change, it's the role of your app
-to keep track of it, not of this lib. See [#16](https://github.com/cyrilletuzi/angular-async-local-storage/issues/16) 
-for more context and [#4](https://github.com/cyrilletuzi/angular-async-local-storage/issues/4)
-for an example. A `watch()` method may come soon
-(see [#108](https://github.com/cyrilletuzi/angular-async-local-storage/pull/108))
+emit again when the stored data is changed. If you need to watch the value,
+version 9 introduced a `watch()` method, see the [watching guide](./docs/WATCHING.md).
 
 ### Checking data
 

docs/WATCHING.md

@@ -0,0 +1,113 @@
+# Watching guide
+
+*Since version 9 of this lib*, you can now watch an item via the `StorageMap` service.
+
+Notes:
+
+- Client-side storage only makes sense for keeping data when the user *leaves* the application
+and comes back later; if you just need to track data when the user stays in the application,
+you do *not* need to watch and not even to use client-side storage: you just need a variable/property.
+
+- Unlike all other `Observable`s of this lib, this one won't auto-complete,
+as the purpose is to watch indefinitely. So **be sure to unsubscribe**.
+
+- The lib can only detect changes in storage done *with this lib* (ie. via `set()` / `.delete()` or `.clear()`).
+It *cannot* detect external changes (for examples via the native `indexedDB` API or via another lib like `localForage`).
+
+## Via manual subscription
+
+```typescript
+import { Subscription } from 'rxjs';
+import { StorageMap } from '@ngx-pwa/local-storage';
+
+@Component({
+  template: `<p>{{data}}<p>`
+})
+export class SomeComponent implements OnInit, OnDestroy {
+
+  data: string;
+  dataSubscription: Subscription;
+
+  constructor(private storageMap: StorageMap) {}
+
+  ngOnInit()  {
+    this.dataSubscription = this.storageMap.watch('somekey', { type: 'string' })
+      .subscribe((result) => {
+        this.data = result;
+      });
+  }
+
+  ngOnDestroy()  {
+    this.dataSubscription.unsubcribe();
+  }
+
+}
+```
+
+## Via the `async` pipe
+
+```typescript
+import { Observable } from 'rxjs';
+import { StorageMap } from '@ngx-pwa/local-storage';
+
+@Component({
+  template: `<p>{{data$ | async}}<p>`
+})
+export class SomeComponent implements OnInit {
+
+  data$: Observable<string>;
+
+  constructor(private storageMap: StorageMap) {}
+
+  ngOnInit()  {
+    this.data$ = this.storageMap.watch('somekey', { type: 'string' });
+  }
+
+}
+```
+
+Note as usual in Angular, do *not* use the `async` pipe twice on the same `Observable`.
+If you need the data in several places:
+
+```typescript
+import { Observable } from 'rjxs';
+import { StorageMap, JSONSchema } from '@ngx-pwa/local-storage';
+
+interface Data {
+  hello: string;
+  world: string;
+}
+
+@Component({
+  template: `
+    <div *ngIf="data$ | async as data">
+      <p>{{data.hello}}</p>
+      <p>{{data.world}}</p>
+    <div>
+  `
+})
+export class SomeComponent implements OnInit {
+
+  data$: Observable<Data>;
+
+  constructor(private storageMap: StorageMap) {}
+
+  ngOnInit()  {
+
+    const schema: JSONSchema = {
+      type: 'object',
+      properties: {
+        hello: { type: 'string' },
+        world: { type: 'string' },
+      },
+      required: ['hello', 'world'],
+    };
+
+    this.data$ = this.storageMap.watch<Data>('somekey', schema);
+
+  }
+
+}
+```
+
+[Back to general documentation](../README.md)

projects/ngx-pwa/local-storage/src/lib/storages/storage-map.service.spec.ts

@@ -506,6 +506,87 @@ function tests(description: string, localStorageServiceFactory: () => StorageMap
 
     });
 
+    describe('watch()', () => {
+
+      it('with valid schema', (done) => {
+
+        const watchedKey = 'watched1';
+        const values = [undefined, 'test1', undefined, 'test2', undefined];
+        let i = 0;
+
+        localStorageService.watch(watchedKey, { type: 'string' }).subscribe((result) => {
+
+          expect(result).toBe(values[i]);
+
+          i += 1;
+
+          if (i === 1) {
+
+            localStorageService.set(watchedKey, values[1]).pipe(
+              mergeMap(() => localStorageService.delete(watchedKey)),
+              mergeMap(() => localStorageService.set(watchedKey, values[3])),
+              mergeMap(() => localStorageService.clear()),
+            ).subscribe();
+
+          }
+
+          if (i === values.length) {
+            done();
+          }
+
+        });
+
+      });
+
+      it('with invalid schema', (done) => {
+
+        const watchedKey = 'watched2';
+
+        localStorageService.set(watchedKey, 'test').subscribe(() => {
+
+          localStorageService.watch(watchedKey, { type: 'number' }).subscribe({
+            error: () => {
+              expect().nothing();
+              done();
+            }
+          });
+
+        });
+
+      });
+
+      it('without schema', (done) => {
+
+        const watchedKey = 'watched3';
+        const values = [undefined, 'test1', undefined, 'test2', undefined];
+        let i = 0;
+
+        localStorageService.watch(watchedKey).subscribe((result) => {
+
+          expect(result).toBe(values[i]);
+
+          i += 1;
+
+          if (i === 1) {
+
+            localStorageService.set(watchedKey, values[1]).pipe(
+              mergeMap(() => localStorageService.delete(watchedKey)),
+              mergeMap(() => localStorageService.set(watchedKey, values[3])),
+              mergeMap(() => localStorageService.clear()),
+            ).subscribe();
+
+          }
+
+          if (i === values.length) {
+            done();
+          }
+
+        });
+
+      });
+
+    });
+
     /* Avoid https://github.com/cyrilletuzi/angular-async-local-storage/issues/25
     * Avoid https://github.com/cyrilletuzi/angular-async-local-storage/issues/5 */
     describe('complete', () => {

projects/ngx-pwa/local-storage/src/lib/storages/storage-map.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Inject } from '@angular/core';
-import { Observable, throwError, of, OperatorFunction } from 'rxjs';
-import { mergeMap, catchError } from 'rxjs/operators';
+import { Observable, throwError, of, OperatorFunction, ReplaySubject } from 'rxjs';
+import { mergeMap, catchError, tap } from 'rxjs/operators';
 
 import { ValidationError } from './exceptions';
 import {
@@ -15,6 +15,8 @@ import { LS_PREFIX } from '../tokens';
 })
 export class StorageMap {
 
+  protected notifiers = new Map<string, ReplaySubject<any>>();
+
   /**
    * Constructor params are provided by Angular (but can also be passed manually in tests)
    * @param database Storage to use
@@ -220,10 +222,12 @@ export class StorageMap {
       return throwError(new ValidationError());
     }
 
-    return this.database.set(key, data)
+    return this.database.set(key, data).pipe(
       /* Catch if `indexedDb` is broken */
-      .pipe(this.catchIDBBroken(() => this.database.set(key, data)));
-
+      this.catchIDBBroken(() => this.database.set(key, data)),
+      /* Notify watchers (must be last because it should only happen if the operation succeeds) */
+      tap(() => { this.notify(key, data); }),
+    );
   }
 
   /**
@@ -236,9 +240,12 @@ export class StorageMap {
    */
   delete(key: string): Observable<undefined> {
 
-    return this.database.delete(key)
+    return this.database.delete(key).pipe(
       /* Catch if `indexedDb` is broken */
-      .pipe(this.catchIDBBroken(() => this.database.delete(key)));
+      this.catchIDBBroken(() => this.database.delete(key)),
+      /* Notify watchers (must be last because it should only happen if the operation succeeds) */
+      tap(() => { this.notify(key, undefined); }),
+    );
 
   }
 
@@ -251,9 +258,16 @@ export class StorageMap {
    */
   clear(): Observable<undefined> {
 
-    return this.database.clear()
+    return this.database.clear().pipe(
       /* Catch if `indexedDb` is broken */
-      .pipe(this.catchIDBBroken(() => this.database.clear()));
+      this.catchIDBBroken(() => this.database.clear()),
+      /* Notify watchers (must be last because it should only happen if the operation succeeds) */
+      tap(() => {
+        for (const key of this.notifiers.keys()) {
+          this.notify(key, undefined);
+        }
+      }),
+    );
 
   }
 
@@ -295,6 +309,64 @@ export class StorageMap {
 
   }
 
+  /**
+   * Watch an item value in storage.
+   * **Note only changes done via this lib will be watched**, external changes in storage can't be detected.
+   * The signature has many overloads due to validation, **please refer to the documentation.**
+   * @see https://github.com/cyrilletuzi/angular-async-local-storage/blob/master/docs/VALIDATION.md
+   * @param key The item's key to watch
+   * @param schema Optional JSON schema to validate the initial value
+   * @returns An infinite `Observable` giving the current value
+   */
+  watch<T = string>(key: string, schema: JSONSchemaString): Observable<string | undefined>;
+  watch<T = number>(key: string, schema: JSONSchemaInteger | JSONSchemaNumber): Observable<number | undefined>;
+  watch<T = boolean>(key: string, schema: JSONSchemaBoolean): Observable<boolean | undefined>;
+  watch<T = string[]>(key: string, schema: JSONSchemaArrayOf<JSONSchemaString>): Observable<string[] | undefined>;
+  watch<T = number[]>(key: string, schema: JSONSchemaArrayOf<JSONSchemaInteger | JSONSchemaNumber>): Observable<number[] | undefined>;
+  watch<T = boolean[]>(key: string, schema: JSONSchemaArrayOf<JSONSchemaBoolean>): Observable<boolean[] | undefined>;
+  watch<T = any>(key: string, schema: JSONSchema): Observable<T | undefined>;
+  watch<T = unknown>(key: string, schema?: JSONSchema): Observable<unknown>;
+  watch<T = any>(key: string, schema?: JSONSchema) {
+
+    /* Check if there is already a notifier and cast according to schema */
+    let notifier = this.notifiers.get(key) as ReplaySubject<typeof schema extends JSONSchema ? (T | undefined) : unknown>;
+
+    if (!notifier) {
+
+      /* Create a notifier and cast according to schema */
+      notifier = new ReplaySubject<typeof schema extends JSONSchema ? (T | undefined) : unknown>(1);
+
+      /* Memorize the notifier */
+      this.notifiers.set(key, notifier);
+
+      /* Get the current item value */
+      this.get<T>(key, schema).subscribe({
+        next: (result) => notifier.next(result),
+        error: (error) => notifier.error(error),
+      });
+
+    }
+
+    /* Only the public API of the `Observable` should be returned */
+    return notifier.asObservable();
+
+  }
+
+  /**
+   * Notify when a value changes
+   * @param key The item's key
+   * @param data The new value
+   */
+  protected notify(key: string, value: any): void {
+
+    const notifier = this.notifiers.get(key);
+
+    if (notifier) {
+      notifier.next(value);
+    }
+
+  }
+
   /**
    * RxJS operator to catch if `indexedDB` is broken
    * @param operationCallback Callback with the operation to redo