@fireflysemantics/slice 17.0.14 → 17.0.16

package/fesm2022/fireflysemantics-slice.mjs

@@ -256,10 +256,10 @@ class AbstractStore {
      * @param p The predicate used to query for the selection.
      * @return A snapshot array containing the entities that match the predicate.
      *
-     * @example Select all the `Todo` instance where the `title` length is greater than 100.
-  ```
-  let todos:Todo[]=store.select(todo=>todo.title.length>100);
-  ```
+     * @example Select all the Todo instances where the title length is greater than 100.
+     * ```
+     * let todos:Todo[]=store.select(todo=>todo.title.length>100);
+     * ```
      */
     select(p) {
         const selected = [];
@@ -275,10 +275,11 @@ class AbstractStore {
      * @param e1 The first entity
      * @param e2 The second entity
      * @return true if the two entities have equal GUID ids
-     * @example Compare `todo1` with `todo2` by `gid`.
-  ```
-  if (equalsByGUID(todo1, todo2)){...};
-  ```
+     *
+     * @example Compare todo1 with todo2 by gid.
+     * ```
+     * if (equalsByGUID(todo1, todo2)){...};
+     * ```
      */
     equalsByGUID(e1, e2) {
         return e1[this.GUID_KEY] == e2[this.GUID_KEY];
@@ -288,16 +289,18 @@ class AbstractStore {
      * @param e1 The first entity
      * @param e2 The second entity
      * @return true if the two entities have equal ID ids
-     * @example Compare `todo1` with `todo2` by `id`.
-  ```
-  if (equalsByID(todo1, todo2)){...};
-  ```
+     *
+     * @example Compare todo1 with todo2 by id.
+     *
+     * ```
+     * if (equalsByID(todo1, todo2)){...};
+     * ```
      */
     equalsByID(e1, e2) {
         return e1[this.ID_KEY] == e2[this.ID_KEY];
     }
     /**
-     * Calls complete on all {@link BehaviorSubject} instances.
+     * Calls complete on all {@link ReplaySubject} instances.
      *
      * Call destroy when disposing of the store.
      */
@@ -542,15 +545,15 @@ class Slice extends AbstractStore {
      * @param eStore The EStore instance containing the elements considered for slicing
      *
      * @example
-       <pre>
-       //Empty slice
-       new Slice<Todo>(Todo.COMPLETE, todo=>!todo.complete);
-  
-       //Initialized slice
-       let todos = [new Todo(false, "You complete me!"),
-                    new Todo(true, "You completed me!")];
-       new Slice<Todo>(Todo.COMPLETE, todo=>!todo.complete, todos);
-       </pre>
+     * ```
+     *  //Empty slice
+     *  new Slice<Todo>(Todo.COMPLETE, todo=>!todo.complete);
+     *
+     *  //Initialized slice
+     *  let todos = [new Todo(false, "You complete me!"),
+     *               new Todo(true, "You completed me!")];
+     *  new Slice<Todo>(Todo.COMPLETE, todo=>!todo.complete, todos);
+     *  ```
      */
     constructor(label, predicate, eStore) {
         super();
@@ -755,36 +758,43 @@ class Slice extends AbstractStore {
  * This `todoFactory` code will be used to illustrate the API examples.  The following
  * utilities are used in the tests and the API Typedoc examples contained here.
  * @example Utilities for API Examples
-```
-export const enum TodoSliceEnum {
-  COMPLETE = "Complete",
-  INCOMPLETE = "Incomplete"
-}
-
-export class Todo {
-  constructor(public complete: boolean, public title: string,public gid?:string, public id?:string) {}
-}
-
-export let todos = [new Todo(false, "You complete me!"), new Todo(true, "You completed me!")];
-
-export function todosFactory():Todo[] {
-  return [new Todo(false, "You complete me!"), new Todo(true, "You completed me!")];
-}
- ```
+ * ```
+ * export const enum TodoSliceEnum {
+ *    COMPLETE = "Complete",
+ *    INCOMPLETE = "Incomplete"
+ * }
+ * export class Todo {
+ *    constructor(
+ *         public complete: boolean,
+ *         public title: string,
+ *         public gid?:string,
+ *         public id?:string) {}
+ * }
+ *
+ * export let todos = [new Todo(false, "You complete me!"), new Todo(true, "You completed me!")];
+ *
+ * export function todosFactory():Todo[] {
+ *   return [new Todo(false, "You complete me!"), new Todo(true, "You completed me!")];
+ * }
+ * ```
  */
 class EStore extends AbstractStore {
     /**
      * Store constructor (Initialization with element is optional)
      *
      * perform initial notification to all observers,
-     * such that function like {@link combineLatest}{}
+     * such that functions like {@link combineLatest}{}
      * will execute at least once.
-     * @param entities
-     * @example Dynamic `EStore<Todo>` Creation
-  ```
-  // Initialize the Store
-  let store: EStore<Todo> = new EStore<Todo>(todosFactory());
-  ```*/
+     *
+     * @param entities The entities to initialize the store with.
+     * @param config The optional configuration instance.
+     *
+     * @example EStore<Todo> Creation
+     * ```
+     * // Initialize the Store
+     * let store: EStore<Todo> = new EStore<Todo>(todosFactory());
+     * ```
+     */
     constructor(entities = [], config) {
         super(config);
         /**
@@ -839,7 +849,7 @@ class EStore extends AbstractStore {
         this.notifyDelta.next(delta);
     }
     /**
-     * Calls complete on all {@link BehaviorSubject} instances.
+     * Calls complete on all EStore {@link ReplaySubject} instances.
      *
      * Call destroy when disposing of the store.
      */
@@ -847,7 +857,7 @@ class EStore extends AbstractStore {
         super.destroy();
         this.notifyLoading.complete();
         this.notifyActive.complete();
-        this.slices.forEach(slice => slice.destroy());
+        this.slices.forEach((slice) => slice.destroy());
     }
     /**
      * Toggles the entity:
@@ -856,16 +866,15 @@ class EStore extends AbstractStore {
      * it will be deleted.  If the store
      * does not contains the entity,
      * it is added.
-     * @param e
-     * @example Toggle the `Todo` instance
-  ```
-  estore.post(todo);
-  // Remove todo
-  estore.toggle(todo);
-  // Add it back
-  estore.toggle(todo);
-  
-  ```
+     * @param e The entity to toggle
+     * @example Toggle the Todo instance
+     * ```
+     * estore.post(todo);
+     * // Remove todo
+     * estore.toggle(todo);
+     * // Add it back
+     * estore.toggle(todo);
+     * ```
      */
     toggle(e) {
         if (this.contains(e)) {
@@ -886,11 +895,11 @@ class EStore extends AbstractStore {
      * change detection in the event that it maintains
      * a reference to the `active` state `Map` instance.
      *
-     * @example Add a `todo1` and `todo2` as active
-  ```
-  addActive(todo1);
-  addActive(todo2);
-  ```
+     * @example Add todo1 and todo2 as active
+     * ```
+     * addActive(todo1);
+     * addActive(todo2);
+     * ```
      */
     addActive(e) {
         if (this.contains(e)) {
@@ -904,18 +913,18 @@ class EStore extends AbstractStore {
         }
     }
     /**
-     * Delete an entity as active.
+     * Delete an active entity.
      *
      * Also we clone the map prior to broadcasting it with
      * `notifyActive` to make sure we will trigger Angular
      * change detection in the event that it maintains
      * a reference to the `active` state `Map` instance.
      *
-     * @example Mark a `todo` instance as active
-    ```
-  deleteActive(todo1);
-  deleteActive(todo2);
-    ```
+     * @example Remove todo1 and todo2 as active entities
+     * ```
+     * deleteActive(todo1);
+     * deleteActive(todo2);
+     * ```
      */
     deleteActive(e) {
         this.active.delete(e.gid);
@@ -929,23 +938,23 @@ class EStore extends AbstractStore {
      * change detection in the event that it maintains
      * a reference to the `active` state `Map` instance.
      *
-     * @example Mark a `todo` instance as active
-    ```
-  deleteActive(todo1);
-  deleteActive(todo2);
-    ```
+     * @example Clear active todo instances
+     * ```
+     * store.clearActive();
+     * ```
      */
     clearActive() {
         this.active.clear();
         this.notifyActive.next(new Map(this.active));
     }
     /**
-     * Observe the active entity.
+     * Observe the active entities.
+     *
      * @example
-       <pre>
-      let active$ = source.observeActive();
-      </pre>
-    */
+     * ```
+     * let active$ = store.observeActive();
+     * ```
+     */
     observeActive() {
         return this.notifyActive.asObservable();
     }
@@ -968,35 +977,91 @@ class EStore extends AbstractStore {
     }
     /**
      * @return A snapshot of the loading state.
+     * @example Create a reference to the loading state
+     * ```
+     * const loading:boolean = todoStore.loading;
+     * ```
      */
     get loading() {
         return this._loading;
     }
     /**
      * Observe loading.
+     *
+     * Note that this obverable piped through
+     * `takeWhile(v->v, true), such that it will
+     * complete after each emission.
+     *
+     * See:
+     * https://fireflysemantics.medium.com/waiting-on-estore-to-load-8dcbe161613c
+     *
+     * For more details.
+     * Also note that v=>v is the same as v=>v!=false
+     *
      * @example
-       <pre>
-      let loading$ = source.observeLoading();
-      </pre>
-  
-      Note that this obverable piped through
-      `takeWhile(v->v, true), such that it will
-      complete after each emission.
-  
-      See:
-      https://medium.com/@ole.ersoy/waiting-on-estore-to-load-8dcbe161613c
-  
-      For more details.
-    */
+     * ```
+     * const observeLoadingHandler: Observer<boolean> = {
+     *   complete: () => {
+     *     console.log(`Data Loaded and Observable Marked as Complete`);
+     *   }, // completeHandler
+     *   error: () => {
+     *     console.log(`Any Errors?`);
+     *   }, // errorHandler
+     *   next: (l) => {
+     *     console.log(`Data loaded and loading is ${l}`);
+     *   },
+     * };
+     *
+     * const observeLoadingResubscribeHandler: Observer<boolean> = {
+     *   complete: () => {
+     *     console.log(`Data Loaded and Resubscribe Observable Marked as Complete`);
+     *   }, // completeHandler
+     *   error: () => {
+     *     console.log(`Any Resubscribe Errors?`);
+     *   }, // errorHandler
+     *   next: (l) => {
+     *     console.log(`Data loaded and resusbscribe loading  value is ${l}`);
+     *   },
+     * };
+     *
+     * const todoStore: EStore<Todo> = new EStore();
+     * //============================================
+     * // Loading is true by default
+     * //============================================
+     * console.log(`The initial value of loading is ${todoStore.loading}`);
+     * //============================================
+     * // Observe Loading
+     * //============================================
+     * let loading$: Observable<boolean> = todoStore.observeLoading();
+     * loading$.subscribe((l) => console.log(`The value of loading is ${l}`));
+     *
+     * todoStore.loading = false;
+     * loading$.subscribe(observeLoadingHandler);
+     * //============================================
+     * // The subscription no longer fires
+     * //============================================
+     * todoStore.loading = true;
+     * todoStore.loading = false;
+     *
+     * //============================================
+     * // The subscription no longer fires,
+     * // so if we want to observe loading again
+     * // resusbscribe.
+     * //============================================
+     * todoStore.loading = true;
+     * loading$ = todoStore.observeLoading();
+     * loading$.subscribe(observeLoadingResubscribeHandler);
+     * todoStore.loading = false;
+     * ```
+     */
     observeLoading() {
-        return this.notifyLoading.asObservable().
-            pipe(takeWhile(v => v, true));
+        return this.notifyLoading.asObservable().pipe(takeWhile((v) => v, true));
     }
     /**
      * Notfiies when loading has completed.
      */
     observeLoadingComplete() {
-        return this.observeLoading().pipe(filter(loading => loading == false), switchMap(() => of(true)));
+        return this.observeLoading().pipe(filter((loading) => loading == false), switchMap(() => of(true)));
     }
     /**
      * Sets the current searching state and notifies observers.
@@ -1028,14 +1093,13 @@ class EStore extends AbstractStore {
       For more details.
     */
     observeSearching() {
-        return this.notifySearching.asObservable().
-            pipe(takeWhile(v => v, true));
+        return this.notifySearching.asObservable().pipe(takeWhile((v) => v, true));
     }
     /**
      * Notfiies when searching has completed.
      */
     observeSearchingComplete() {
-        return this.observeSearching().pipe(filter(searching => searching == false), switchMap(() => of(true)));
+        return this.observeSearching().pipe(filter((searching) => searching == false), switchMap(() => of(true)));
     }
     /**
      * Adds a slice to the store and keys it by the slices label.
@@ -1080,10 +1144,11 @@ class EStore extends AbstractStore {
     /**
      * Post (Add a new) element(s) to the store.
      * @param e An indiidual entity or an array of entities
-     * @example Post a `todo`.
-  ```
-  store.post(todo);
-  ```
+     * @example Post a Todo instance.
+     *
+     *```
+     * store.post(todo);
+     *```
      */
     post(e) {
         if (!Array.isArray(e)) {
@@ -1093,7 +1158,7 @@ class EStore extends AbstractStore {
             e[this.GUID_KEY] = guid;
             this.entries.set(guid, e);
             this.updateIDEntry(e);
-            Array.from(this.slices.values()).forEach(s => {
+            Array.from(this.slices.values()).forEach((s) => {
                 s.post(e);
             });
             //Create a new array reference to trigger Angular change detection.
@@ -1106,15 +1171,15 @@ class EStore extends AbstractStore {
         }
     }
     /**
-     * Post elements to the store.
+     * Post N entities to the store.
      * @param ...e
-     * @example Post two `Todo` instances.
-  ```
-  store.post(todo1, todo2);
-  ```
+     * @example Post two Todo instances.
+     * ```
+     * store.post(todo1, todo2);
+     * ```
      */
     postN(...e) {
-        e.forEach(e => {
+        e.forEach((e) => {
             const guid = e[this.GUID_KEY]
                 ? e[this.GUID_KEY]
                 : GUID();
@@ -1122,7 +1187,7 @@ class EStore extends AbstractStore {
             this.entries.set(guid, e);
             this.updateIDEntry(e);
         });
-        Array.from(this.slices.values()).forEach(s => {
+        Array.from(this.slices.values()).forEach((s) => {
             s.postA(e);
         });
         //Create a new array reference to trigger Angular change detection.
@@ -1133,21 +1198,22 @@ class EStore extends AbstractStore {
     /**
      * Post (Add) an array of elements to the store.
      * @param e
-     * @example Post a `Todo` array.
-  ```
-  store.post([todo1, todo2]);
-  ```
+     * @example Post a Todo array.
+     *
+     * ```
+     * store.post([todo1, todo2]);
+     * ```
      */
     postA(e) {
         this.postN(...e);
     }
     /**
-     * Put (Update) an element.
+     * Put (Update) an entity.
      * @param e
      * @example Put a Todo instance.
-  ```
-  store.put(todo1);
-  ```
+     * ```
+     * store.put(todo1);
+     * ```
      */
     put(e) {
         if (!Array.isArray(e)) {
@@ -1158,7 +1224,7 @@ class EStore extends AbstractStore {
             this.notify.next(v);
             const delta = { type: "Put" /* ActionTypes.PUT */, entries: [e] };
             this.notifyDelta.next(delta);
-            Array.from(this.slices.values()).forEach(s => {
+            Array.from(this.slices.values()).forEach((s) => {
                 s.put(e);
             });
         }
@@ -1169,25 +1235,26 @@ class EStore extends AbstractStore {
     /**
      * Put (Update) an element or add an element that was read from a persistence source
      * and thus already has an assigned global id`.
-     * @param e
-     * @example Put Todo instances.
-  ```
-  store.put(todo1, todo2);
-  ```
+     * @param e The enetity instances to update.
+     * @example Put N Todo instances.
+     *
+     * ```
+     * store.put(todo1, todo2);
+     * ```
      */
     putN(...e) {
         this.putA(e);
     }
     /**
-     * Put (Update) the array of elements.
-     * @param e
-     * @example Put Todo instances.
-  ```
-  store.put([todo1, todo2]);
-  ```
+     * Put (Update) the array of enntities.
+     * @param e The array of enntities to update
+     * @example Put an array of Todo instances.
+     * ```
+     * store.put([todo1, todo2]);
+     * ```
      */
     putA(e) {
-        e.forEach(e => {
+        e.forEach((e) => {
             let guid = e[this.GUID_KEY];
             this.entries.set(guid, e);
             this.updateIDEntry(e);
@@ -1197,7 +1264,7 @@ class EStore extends AbstractStore {
         this.notify.next(v);
         const delta = { type: "Put" /* ActionTypes.PUT */, entries: e };
         this.notifyDelta.next(delta);
-        Array.from(this.slices.values()).forEach(s => {
+        Array.from(this.slices.values()).forEach((s) => {
             s.putA(e);
         });
     }
@@ -1205,9 +1272,9 @@ class EStore extends AbstractStore {
      * Delete (Update) the array of elements.
      * @param e
      * @example Delete todo1.
-  ```
-  store.delete(todo1]);
-  ```
+     * ```
+     * store.delete(todo1]);
+     * ```
      */
     delete(e) {
         if (!Array.isArray(e)) {
@@ -1215,14 +1282,14 @@ class EStore extends AbstractStore {
             const guid = e[this.GUID_KEY];
             this.entries.delete(guid);
             this.deleteIDEntry(e);
-            Array.from(this.slices.values()).forEach(s => {
+            Array.from(this.slices.values()).forEach((s) => {
                 s.entries.delete(guid);
             });
             //Create a new array reference to trigger Angular change detection.
             let v = [...Array.from(this.entries.values())];
             const delta = { type: "Delete" /* ActionTypes.DELETE */, entries: [e] };
             this.notifyAll(v, delta);
-            Array.from(this.slices.values()).forEach(s => {
+            Array.from(this.slices.values()).forEach((s) => {
                 s.delete(e);
             });
         }
@@ -1233,29 +1300,29 @@ class EStore extends AbstractStore {
     /**
      * Delete N elements.
      * @param ...e
-     * @example Put Todo instances.
-  ```
-  store.delete(todo1, todo2);
-  ```
+     * @example Delete N Todo instance argument.
+     * ```
+     * store.deleteN(todo1, todo2);
+     * ```
      */
     deleteN(...e) {
         this.deleteA(e);
     }
     /**
-     * Delete N elements.
-     * @param ...e
-     * @example Put Todo instances.
-  ```
-  store.delete(todo1, todo2);
-  ```
+     * Delete an array of elements.
+     * @param e The array of instances to be deleted
+     * @example Delete the array of Todo instances.
+     * ```
+     * store.deleteA([todo1, todo2]);
+     * ```
      */
     deleteA(e) {
-        e.forEach(e => {
+        e.forEach((e) => {
             this.deleteActive(e);
             const guid = e[this.GUID_KEY];
             this.entries.delete(guid);
             this.deleteIDEntry(e);
-            Array.from(this.slices.values()).forEach(s => {
+            Array.from(this.slices.values()).forEach((s) => {
                 s.entries.delete(guid);
             });
         });
@@ -1263,21 +1330,21 @@ class EStore extends AbstractStore {
         let v = [...Array.from(this.entries.values())];
         const delta = { type: "Delete" /* ActionTypes.DELETE */, entries: e };
         this.notifyAll(v, delta);
-        Array.from(this.slices.values()).forEach(s => {
+        Array.from(this.slices.values()).forEach((s) => {
             s.deleteA(e);
         });
     }
     /**
      * Delete elements by {@link Predicate}.
      * @param p The predicate.
-     * @example Put Todo instances.
-  ```
-  store.delete(todo1, todo2);
-  ```
+     * @example Delete the Todo instances.
+     * ```
+     * store.delete(todo1, todo2);
+     * ```
      */
     deleteP(p) {
         const d = [];
-        Array.from(this.entries.values()).forEach(e => {
+        Array.from(this.entries.values()).forEach((e) => {
             if (p(e)) {
                 d.push(e);
                 const id = e[this.GUID_KEY];
@@ -1290,7 +1357,7 @@ class EStore extends AbstractStore {
         let v = [...Array.from(this.entries.values())];
         const delta = { type: "Delete" /* ActionTypes.DELETE */, entries: d };
         this.notifyAll(v, delta);
-        Array.from(this.slices.values()).forEach(s => {
+        Array.from(this.slices.values()).forEach((s) => {
             s.deleteA(d);
         });
     }
@@ -1323,18 +1390,18 @@ class EStore extends AbstractStore {
      * send their own delta notification.
      *
      * @example Reset the store.
-  ```
-  store.reset();
-  ```
+     * ```
+     * store.reset();
+     * ```
      */
     reset() {
         const delta = {
             type: "Reset" /* ActionTypes.RESET */,
-            entries: Array.from(this.entries.values())
+            entries: Array.from(this.entries.values()),
         };
         this.notifyAll([], delta);
         this.entries = new Map();
-        Array.from(this.slices.values()).forEach(s => {
+        Array.from(this.slices.values()).forEach((s) => {
             s.reset();
         });
     }