[core] feat(interpreter): allow to provide errorListeners

.changeset/famous-icons-flash.md

@@ -0,0 +1,5 @@
+---
+'xstate': minor
+---
+
+allow to provide errorListeners into interpreter

packages/core/src/interpreter.ts

@@ -160,6 +160,7 @@ export class Interpreter<
   private contextListeners: Set<ContextListener<TContext>> = new Set();
   private stopListeners: Set<Listener> = new Set();
   private doneListeners: Set<EventListener> = new Set();
+  private errorListeners: Set<EventListener> = new Set();
   private eventListeners: Set<EventListener> = new Set();
   private sendListeners: Set<EventListener> = new Set();
   private logger: (...args: any[]) => void;
@@ -313,6 +314,15 @@ export class Interpreter<
       this.stop();
     }
   }
+
+  private sendError(errorEvent: Event<TEvent> | SCXML.Event<TEvent>): void {
+    if (this.errorListeners.size) {
+      for (const listener of this.errorListeners) {
+        listener(errorEvent as EventObject);
+      }
+    }
+  }
+
   /*
    * Adds a listener that is notified whenever a state transition happens. The listener is called with
    * the next state and the event object that caused the state transition.
@@ -343,7 +353,7 @@ export class Interpreter<
     nextListenerOrObserver?:
       | ((state: State<TContext, TEvent, any, TTypestate>) => void)
       | Observer<State<TContext, TEvent, any, TTypestate>>,
-    _?: (error: any) => void, // TODO: error listener
+    errorListener?: (error: any) => void,
     completeListener?: () => void
   ): Subscription {
     if (!nextListenerOrObserver) {
@@ -352,6 +362,7 @@ export class Interpreter<
 
     let listener: (state: State<TContext, TEvent, any, TTypestate>) => void;
     let resolvedCompleteListener = completeListener;
+    let resolvedErrorListener = errorListener;
 
     if (typeof nextListenerOrObserver === 'function') {
       listener = nextListenerOrObserver;
@@ -373,11 +384,17 @@ export class Interpreter<
       this.onDone(resolvedCompleteListener);
     }
 
+    if (resolvedErrorListener) {
+      this.onError(resolvedErrorListener);
+    }
+
     return {
       unsubscribe: () => {
         listener && this.listeners.delete(listener);
         resolvedCompleteListener &&
           this.doneListeners.delete(resolvedCompleteListener);
+        resolvedErrorListener &&
+          this.errorListeners.delete(resolvedErrorListener);
       }
     };
   }
@@ -432,6 +449,16 @@ export class Interpreter<
     this.doneListeners.add(listener);
     return this;
   }
+  /**
+   * Adds a state listener that is notified when the statechart has reached an error.
+   * @param listener The state listener
+   */
+  public onError(
+    listener: EventListener<DoneEvent>
+  ): Interpreter<TContext, TStateSchema, TEvent, TTypestate> {
+    this.errorListeners.add(listener);
+    return this;
+  }
   /**
    * Removes a listener.
    * @param listener The listener to remove
@@ -444,6 +471,7 @@ export class Interpreter<
     this.sendListeners.delete(listener);
     this.stopListeners.delete(listener);
     this.doneListeners.delete(listener);
+    this.errorListeners.delete(listener);
     this.contextListeners.delete(listener);
     return this;
   }
@@ -510,6 +538,9 @@ export class Interpreter<
     for (const listener of this.doneListeners) {
       this.doneListeners.delete(listener);
     }
+    for (const listener of this.errorListeners) {
+      this.errorListeners.delete(listener);
+    }
 
     if (!this.initialized) {
       // Interpreter already stopped; do nothing
@@ -559,6 +590,14 @@ export class Interpreter<
       return this.state;
     }
 
+    if (((event as EventObject)?.type || '').includes('error')) {
+      if (this.parent) {
+        this.parent.sendError(event as any);
+      } else {
+        this.sendError(event as any);
+      }
+    }
+
     const _event = toSCXMLEvent(toEventObject(event as Event<TEvent>, payload));
 
     if (this.status === InterpreterStatus.Stopped) {
@@ -1056,10 +1095,17 @@ export class Interpreter<
             // Send "error.platform.id" to this (parent).
             this.send(toSCXMLEvent(errorEvent as any, { origin: id }));
           } catch (error) {
-            reportUnhandledExceptionOnInvocation(errorData, error, id);
+            if (this.parent) {
+              this.parent.send(errorEvent);
+            } else if (!this.errorListeners.size) {
+              reportUnhandledExceptionOnInvocation(errorData, error, id);
+            }
             if (this.devTools) {
               this.devTools.send(errorEvent, this.state);
             }
+
+            this.sendError(errorEvent);
+
             if (this.machine.strict) {
               // it would be better to always stop the state machine if unhandled
               // exception/promise rejection happens but because we don't want to

packages/core/test/interpreter.test.ts

@@ -1751,6 +1751,175 @@ Event: {\\"type\\":\\"SOME_EVENT\\"}"
       service.send('INC');
       service.send('INC');
     });
+
+    describe('when errorListener is provided', () => {
+      it('should handle errors', (done) => {
+        const failureMachine = createMachine<typeof context>(
+          {
+            id: 'interval',
+            context,
+            initial: 'active',
+            states: {
+              active: {
+                after: {
+                  10: {
+                    target: 'failure'
+                  }
+                }
+              },
+              failure: {
+                invoke: {
+                  src: 'failure'
+                }
+              }
+            }
+          },
+          {
+            services: {
+              failure: async () => {
+                throw new Error('error');
+              }
+            }
+          }
+        );
+
+        const intervalService = interpret(failureMachine).start();
+
+        intervalService.subscribe(
+          () => {},
+          (error) => {
+            expect(error.type).toBe('error.platform.failure');
+            expect(error.data).toBeInstanceOf(Error);
+            intervalService.stop();
+            done();
+          }
+        );
+      });
+
+      it('should handle child errors', (done) => {
+        const childMachine = createMachine<typeof context>(
+          {
+            id: 'child',
+            context,
+            initial: 'active',
+            states: {
+              active: {
+                after: {
+                  100: {
+                    target: 'failure'
+                  }
+                }
+              },
+              failure: {
+                invoke: {
+                  src: 'failure'
+                }
+              }
+            }
+          },
+          {
+            services: {
+              failure: async () => {
+                throw new Error('error');
+              }
+            }
+          }
+        );
+
+        const parentMachine = createMachine({
+          initial: 'foo',
+          states: {
+            foo: {
+              invoke: {
+                id: 'child',
+                src: childMachine
+              }
+            }
+          }
+        });
+
+        const intervalService = interpret(parentMachine).start();
+
+        intervalService.subscribe(
+          () => {},
+          (error) => {
+            expect(error.type).toBe('error.platform.failure');
+            expect(error.data).toBeInstanceOf(Error);
+            intervalService.stop();
+            done();
+          }
+        );
+      });
+
+      it('should handle grandchild errors', (done) => {
+        const childMachine = createMachine<typeof context>(
+          {
+            id: 'child',
+            context,
+            initial: 'active',
+            states: {
+              active: {
+                after: {
+                  100: {
+                    target: 'failure'
+                  }
+                }
+              },
+              failure: {
+                invoke: {
+                  src: 'failure'
+                }
+              }
+            }
+          },
+          {
+            services: {
+              failure: async () => {
+                throw new Error('error');
+              }
+            }
+          }
+        );
+
+        const parentMachine = createMachine({
+          id: 'parent',
+          initial: 'foo',
+          states: {
+            foo: {
+              invoke: {
+                id: 'child',
+                src: childMachine
+              }
+            }
+          }
+        });
+
+        const grandparentMachine = createMachine({
+          id: 'grandparent',
+          initial: 'bar',
+          states: {
+            bar: {
+              invoke: {
+                id: 'parent',
+                src: parentMachine
+              }
+            }
+          }
+        });
+
+        const intervalService = interpret(grandparentMachine).start();
+
+        intervalService.subscribe(
+          () => {},
+          (error) => {
+            expect(error.type).toBe('error.platform.failure');
+            expect(error.data).toBeInstanceOf(Error);
+            intervalService.stop();
+            done();
+          }
+        );
+      });
+    });
   });
 
   describe('services', () => {