@jscutlery/operators 1.0.2 → 1.1.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
 
+## [1.1.1](https://github.com/jscutlery/devkit/compare/operators-1.1.0...operators-1.1.1) (2023-04-18)
+
+
+
+# [1.1.0](https://github.com/jscutlery/devkit/compare/operators-1.0.2...operators-1.1.0) (2023-04-18)
+
+
+### Features
+
+* **operators:** add suspensify's strict mode ([f9dd789](https://github.com/jscutlery/devkit/commit/f9dd789d82cdff2fffb2241e8b0aab9bd76cb363)), closes [#237](https://github.com/jscutlery/devkit/issues/237)
+
+
+
 ## [1.0.2](https://github.com/jscutlery/devkit/compare/operators-1.0.1...operators-1.0.2) (2023-04-18)
 
 

package/README.md

@@ -7,7 +7,8 @@ This package regroups a couple of RxJS operators meant to simplify some common p
 - [`suspensify`](#suspensify)
   - [Goals](#goals)
   - [Usage](#usage)
-    - [Basic](#basic)
+    - [Strict mode (will become default in 3.0.0)](#strict-mode-will-become-default-in-300)
+    - [Lax mode (default)](#lax-mode-default)
     - [With Angular](#with-angular)
     - [With `@rx-angular/state`](#with-rx-angularstate)
   - [Alternatives](#alternatives)
@@ -32,7 +33,7 @@ When dealing with an asynchronous source of data in a web application, it is a c
 - **pending**: the data is being fetched
 - **error**: an error occurred while fetching the data
 - **success**: some data has been fetched
-- **finalized**: there is no more data to fetch or an error happened
+- **finalized**: there is no more data to fetch or an error happened _(it is called `finalized` and not `completed` to avoid confusion with RxJS `complete` event which only happens if there is no error)_.
 
 The most common ways of implementing this are error-prone as they are either based on a complex combination of native RxJS operators or side effects that break the reactivity chain.
 
@@ -47,7 +48,52 @@ The `suspensify` operator is meant to provide a simple and efficient way of deal
 
 ## Usage
 
-### Basic
+### Strict mode (will become default in 3.0.0)
+
+Thanks to strict mode the emitted suspense can be narrowed down.
+
+```ts
+interval(1000)
+  .pipe(take(2), suspensify({strict: true}))
+  .subscribe((suspense) => {
+    suspense.value; // 💥
+    suspense.error; // 💥
+    if (suspense.hasValue) {
+      suspense.value; // ✅
+      suspense.error; // 💥
+    }
+    if (suspense.hasError) {
+      suspense.value; // 💥
+      suspense.error; // ✅
+    }
+  });
+```
+
+```ts
+{
+  finalized: false,
+  hasError: false,
+  hasValue: false,
+  pending: true,
+}
+{
+  finalized: false,
+  hasError: false,
+  hasValue: false,
+  pending: false,
+  value: 0,
+}
+...
+{
+  finalized: true,
+  hasError: false,
+  hasValue: true,
+  pending: false,
+  value: 1,
+}
+```
+
+### Lax mode (default)
 
 ```ts
 interval(1000)
@@ -57,23 +103,29 @@ interval(1000)
 
 ```ts
 {
+  finalized: false,
+  hasError: false,
+  hasValue: false,
+  pending: true,
   value: undefined,
   error: undefined,
-  pending: true,
-  finalized: false,
 }
 {
+  finalized: false,
+  hasError: false,
+  hasValue: false,
+  pending: false,
   value: 0,
   error: undefined,
-  pending: false,
-  finalized: false,
 }
 ...
 {
+  finalized: true,
+  hasError: false,
+  hasValue: true,
+  pending: false,
   value: 1,
   error: undefined,
-  pending: false,
-  finalized: true,
 }
 ```
 
@@ -86,9 +138,15 @@ interval(1000)
 
       <my-spinner *ngIf="suspense.pending"></my-spinner>
 
-      <div *ngIf="suspense.error">{{ suspense.error }}</div>
+      <div *ngIf="suspense.hasError">
+        {{ suspense.error }} // ✅
+        {{ suspense.value }} // 💥 will not compile in strict mode
+      </div>
 
-      <div *ngIf="suspense.value">{{ suspense.value }}</div>
+      <div *ngIf="suspense.hasValue">
+        {{ suspense.error }} // 💥 will not compile in strict mode
+        {{ suspense.value }} // ✅
+      </div>
 
     </ng-container>
   `,

package/index.cjs

@@ -1076,13 +1076,20 @@ $({ target: 'Object', stat: true, arity: 2, forced: Object.assign !== assign },
   assign: assign
 });
 
-function suspensify(
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-options) {
+function suspensify({
+  strict = false
+} = {}) {
   return source$ => {
-    return source$.pipe(_suspensify(), _coalesceFirstEmittedValue());
+    const strictSuspense$ = source$.pipe(_suspensify(), _coalesceFirstEmittedValue());
+    return strict ? strictSuspense$ : strictSuspense$.pipe(operators.map(strictSuspense => Object.assign({
+      error: undefined,
+      value: undefined
+    }, strictSuspense))
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    );
   };
 }
+
 function _coalesceFirstEmittedValue() {
   return source$ => {
     return new rxjs.Observable(observer => {
@@ -1096,31 +1103,44 @@ function _coalesceFirstEmittedValue() {
     });
   };
 }
+/* Use values as types for better type checking. */
+const TRUE = true;
+const FALSE = false;
 function _suspensify() {
   return source$ => {
     const initialState = {
-      value: undefined,
-      error: undefined,
       finalized: false,
+      hasError: false,
+      hasValue: false,
       pending: true
     };
     return source$.pipe(operators.materialize(), operators.scan((state = initialState, notification) => {
-      /* On complete, merge `finalized: true & pending: false`
-       * with the current state. */
-      if (notification.kind === 'C') {
-        return Object.assign({}, state, {
-          finalized: true,
-          pending: false
-        });
+      switch (notification.kind) {
+        /* Value. */
+        case 'N':
+          return {
+            finalized: FALSE,
+            hasError: FALSE,
+            hasValue: TRUE,
+            value: notification.value,
+            pending: FALSE
+          };
+        /* Error. */
+        case 'E':
+          return {
+            finalized: TRUE,
+            hasError: TRUE,
+            hasValue: FALSE,
+            pending: FALSE,
+            error: notification.error
+          };
+        /* Complete. */
+        case 'C':
+          return Object.assign({}, state, {
+            finalized: TRUE,
+            pending: FALSE
+          });
       }
-      /* Mark as finalized on error as complete is only triggered on success. */
-      const finalized = notification.kind === 'E';
-      return {
-        value: notification.value,
-        error: notification.error,
-        finalized,
-        pending: false
-      };
     }, initialState), operators.startWith(initialState));
   };
 }

package/index.js

@@ -1,5 +1,5 @@
 import { Observable, ReplaySubject } from 'rxjs';
-import { debounce, materialize, scan, startWith } from 'rxjs/operators';
+import { map, debounce, materialize, scan, startWith } from 'rxjs/operators';
 
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
 
@@ -1072,13 +1072,20 @@ $({ target: 'Object', stat: true, arity: 2, forced: Object.assign !== assign },
   assign: assign
 });
 
-function suspensify(
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-options) {
+function suspensify({
+  strict = false
+} = {}) {
   return source$ => {
-    return source$.pipe(_suspensify(), _coalesceFirstEmittedValue());
+    const strictSuspense$ = source$.pipe(_suspensify(), _coalesceFirstEmittedValue());
+    return strict ? strictSuspense$ : strictSuspense$.pipe(map(strictSuspense => Object.assign({
+      error: undefined,
+      value: undefined
+    }, strictSuspense))
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    );
   };
 }
+
 function _coalesceFirstEmittedValue() {
   return source$ => {
     return new Observable(observer => {
@@ -1092,31 +1099,44 @@ function _coalesceFirstEmittedValue() {
     });
   };
 }
+/* Use values as types for better type checking. */
+const TRUE = true;
+const FALSE = false;
 function _suspensify() {
   return source$ => {
     const initialState = {
-      value: undefined,
-      error: undefined,
       finalized: false,
+      hasError: false,
+      hasValue: false,
       pending: true
     };
     return source$.pipe(materialize(), scan((state = initialState, notification) => {
-      /* On complete, merge `finalized: true & pending: false`
-       * with the current state. */
-      if (notification.kind === 'C') {
-        return Object.assign({}, state, {
-          finalized: true,
-          pending: false
-        });
+      switch (notification.kind) {
+        /* Value. */
+        case 'N':
+          return {
+            finalized: FALSE,
+            hasError: FALSE,
+            hasValue: TRUE,
+            value: notification.value,
+            pending: FALSE
+          };
+        /* Error. */
+        case 'E':
+          return {
+            finalized: TRUE,
+            hasError: TRUE,
+            hasValue: FALSE,
+            pending: FALSE,
+            error: notification.error
+          };
+        /* Complete. */
+        case 'C':
+          return Object.assign({}, state, {
+            finalized: TRUE,
+            pending: FALSE
+          });
       }
-      /* Mark as finalized on error as complete is only triggered on success. */
-      const finalized = notification.kind === 'E';
-      return {
-        value: notification.value,
-        error: notification.error,
-        finalized,
-        pending: false
-      };
     }, initialState), startWith(initialState));
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jscutlery/operators",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "repository": {
     "url": "https://github.com/jscutlery/devkit"
   },

package/src/lib/suspensify.d.ts

@@ -1,9 +1,11 @@
 import { OperatorFunction } from 'rxjs';
 export interface SuspenseLax<T> {
-    value: undefined | T;
-    error: undefined | any;
     finalized: boolean;
+    hasError: boolean;
+    hasValue: boolean;
     pending: boolean;
+    error: undefined | any;
+    value: undefined | T;
 }
 export interface SuspensePending {
     finalized: false;
@@ -25,15 +27,18 @@ export interface SuspenseWithError {
     pending: false;
     error: unknown;
 }
-export declare type SuspenseStrict<T> = SuspensePending | SuspenseWithValue<T> | SuspenseWithError;
+export interface SuspenseEmpty {
+    finalized: true;
+    hasError: false;
+    hasValue: false;
+    pending: false;
+}
+export declare type SuspenseStrict<T> = SuspensePending | SuspenseWithValue<T> | SuspenseWithError | SuspenseEmpty;
 /**
  * @todo 3.0.0: Make `Suspense` an alias for `SuspenseStrict`.
  */
 export declare type Suspense<T> = SuspenseLax<T>;
 export interface SuspensifyOptions {
-    /**
-     * @deprecated 🚧 Work in progress.
-     */
     strict?: boolean;
 }
 /**