@genesislcap/foundation-store 14.117.0 → 14.118.0

package/README.md

@@ -169,14 +169,13 @@ class DefaultStore extends AbstractStoreRoot<Store, StoreEventDetailMap, Interna
    */
   onFooEvent = this.createListener('store-foo', detail => {...});
   onBarEvent = this.createListener<boolean>('store-bar', detail => this.commit.someToggle = detail); // < commit values to the store synchronously
-  onZooEvent = this.createAsyncListener<StoreZooEventDetail>('store-zoo', async (detail) => {
-    try {
-      const response = await this.someAsyncTask(detail); // < likely an injected service
-      this.emit('store-zoo-success', response); // < you could commit here if you really wanted to...
-    } catch (e) {
-      this.emit('store-zoo-error', e);
-    }
-  });
+  onZooEvent = this.createAsyncListener<StoreZooEventDetail>('store-zoo', async (detail) =>
+    this.invokeAsyncAPI(
+      async () => this.someAsyncTask(detail), // < likely an injected service,
+      'store-zoo-error',
+      'store-zoo-success'
+    )
+  );
 
   /**
    * 9: Create getters for common derived data needs, similar to selectors in the Redux sense. These however do not
@@ -197,7 +196,7 @@ class DefaultStore extends AbstractStoreRoot<Store, StoreEventDetailMap, Interna
 /**
  * 10: Register the store which defines the DI key using the interface
  */
-export const Store = registerStore(DefaultStore, 'RootStore');
+export const Store = registerStore<Store>(DefaultStore, 'RootStore');
 ```
 
 Your root store is now ready to be injected into your application. Hopefully the above gives you a good idea of general
@@ -225,7 +224,7 @@ class DefaultTradeEntryUI extends AbstractStore<TradeEntryUI, TradeEntryUIEventD
   onOpen = this.createListener<boolean>('trade-entry-ui-open', detail => this.commit.isOpen = detail);
 }
 
-export const TradeEntryUI = registerStore(DefaultTradeEntryUI, 'TradeEntryUI');
+export const TradeEntryUI = registerStore<TradeEntryUI>(DefaultTradeEntryUI, 'TradeEntryUI');
 ```
 
 ## Store events
@@ -235,36 +234,81 @@ export const TradeEntryUI = registerStore(DefaultTradeEntryUI, 'TradeEntryUI');
 In your main application class, likely `./src/main/main.ts`, you need to fire a `'store-connected'` event in-order to
 fully initialise the store.
 
-For example:
-
 ```typescript
 // ./main/main.ts
 
 type EventMap = StoreEventDetailMap & {...}; // < whatever other events you allow your custom element to emit
 
-@customElement({name, template, styles})
+/**
+ * MainApplication
+ * 
+ * @fires store-connected - Fires a custom 'store-connected' event after connection to connect the store.
+ * @fires store-ready - Fires a custom 'store-ready' event after connection to ready the store.
+ * @fires store-disconnected - Fires a custom 'store-disconnected' event after disconnection to unbind the store.
+ * 
+ * @public
+ */
+@customElement({ name, template, styles })
 export class MainApplication extends EventEmitter<EventMap>(FASTElement) {
-  @Store store!: Store; // < injected root store
-  @observable rootElement!: HTMLElement; // < rootElement provided via a 'ref' directive in the tempate
+  /**
+   * @public
+   */
+  @Store store: Store; // < injected root store
+
+  /**
+   * @public
+   */
   connectedCallback() {
     super.connectedCallback();
-    this.$emit('store-connected', this.rootElement); // < emit the strongly typed event when we're connected to the dom
+    this.addEventListeners();
+    this.readyStore();
   }
-}
-```
 
-This `'store-connected'` event handler needs to be explicitly bound as an event handler in the main template.
+  /**
+   * @public
+   */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeEventListeners();
+    this.disconnectStore();
+  }
 
-```typescript jsx
-// ./main/main.template.ts
+  /**
+   * @internal
+   */
+  protected addEventListeners() {
+    this.addEventListener('store-connected', this.store.onConnected);
+  }
 
-<template
-  ${ref('rootElement')}
-  @store-connected=${(x, c) => x.store.onConnected(customEvent(c))}
->
+  /**
+   * @internal
+   */
+  protected removeEventListeners() {
+    this.removeEventListener('store-connected', this.store.onConnected);
+  }
+
+  /**
+   * @internal
+   */
+  protected readyStore() {
+    this.$emit('store-connected', this);
+    /**
+     * Do some other work if needed.
+     */
+    this.$emit('store-ready', true);
+  }
+
+  /**
+   * @internal
+   */
+  protected disconnectStore() {
+    this.$emit('store-disconnected');
+  }
+}
 ```
 
-When the root store handles `'store-connected'`, it auto binds all the store event listeners to the rootElement.
+The `'store-connected'` event handler needs to be explicitly bound. When the root store handles `'store-connected'`,
+it auto binds all the store event listeners to the rootElement.
 
 At this point you can start emitting strongly typed store events, and they will be handled by their corresponding store.
 See [EventEmitter](src/.foundation/events/eventEmitter/README.md) for more information.
@@ -278,11 +322,26 @@ do, you can just emit this right after `'store-connected'`.
 ```typescript
 // ./main/main.ts
 
-this.$emit('store-connected', this.rootElement);
-// possible other work done in-between...
+this.$emit('store-connected', this);
+/**
+ * Do some other work if needed.
+ */
 this.$emit('store-ready', true);
 ```
 
+### `'store-disconnected'`
+
+Emitting `'store-disconnected'` will remove all the previously bound event listeners.
+
+```typescript
+// ./main/main.ts
+
+disconnectedCallback() {
+  super.disconnectedCallback();
+  this.$emit('store-disconnected');
+}
+```
+
 ## Using store fragments
 
 To use a store fragment in your custom element simply inject it using its `interface` as the DI key.
@@ -425,14 +484,13 @@ constructor(
   this.createErrorListener('trades-load-error', () => this.commit.trades = undefined);
 }
 
-onTradesLoad = this.createAsyncListener<string>('trades-load', async (positionId) => {
-  try {
-    const trades = await this.service.getTrades(positionId);
-    this.emit('trades-load-success', trades);
-  } catch (e) {
-    this.emit('trades-load-error', e);
-  }
-});
+onTradesLoad = this.createAsyncListener<string>('trades-load', async (positionId) =>
+  this.invokeAsyncAPI(
+    async () => this.service.getTrades(positionId),
+    'trades-load-error',
+    'trades-load-success'
+  )
+);
 ```
 
 ### Errors