feat: add webshellStrictMode prop to raise errors on inconsistencies

jsamr · jsamr · commit 81273be0cd51 · 2020-10-01T14:49:33.000-03:00
By default, warning messages will be logged when `webshellDebug` is set
to `true`, which defaults to `__DEV__`. From now on, errors will be
raised if `webshellStrictMode` is set to `true`. Defaults to `false`.
diff --git a/packages/core/etc/webshell.api.md b/packages/core/etc/webshell.api.md
@@ -393,6 +393,7 @@ export interface WebshellInvariantProps {
     onWebFeatureError?: (featureIdentifier: string, error: string) => void;
     webHandle?: Ref<WebHandle>;
     webshellDebug?: boolean;
+    webshellStrictMode?: boolean;
 }
 
 // @public
diff --git a/packages/core/src/Reporter.ts b/packages/core/src/Reporter.ts
@@ -0,0 +1,91 @@
+export type ErrorCode =
+  | 'WEBSH_MISSING_SHELL_HANDLER'
+  | 'WEBSH_SCRIPT_ERROR'
+  | 'WEBSH_WEBVIEW_MISSING_MEMBER'
+  | 'WEBSH_FEAT_MISSING_WEB_HANDLER'
+  | 'WEBSH_FEAT_MISSING_IN_SHELL';
+
+function describe(template: TemplateStringsArray, ...args: any[]) {
+  return (
+    '[Webshell]: ' +
+    template
+      .reduce((buffer, currentSnippet, index) => {
+        buffer.push(currentSnippet, args[index] || '');
+        return buffer;
+      }, [] as string[])
+      .join('')
+  );
+}
+
+interface ErrorDefinition<E extends ErrorCode> {
+  code: E;
+  verbose: (...args: any[]) => string;
+}
+
+const ErrorCodes: Record<ErrorCode, ErrorDefinition<ErrorCode>> = {
+  WEBSH_MISSING_SHELL_HANDLER: {
+    code: 'WEBSH_MISSING_SHELL_HANDLER',
+    verbose: function (identifier, handlerId) {
+      return describe`Web script from feature "${identifier}" sent an event for "${handlerId}" shell handler, but there is no shell handler registered for this feature. Use FeatureBuilder.withShellHandler to register that handler, or make sure its name is not misspell in the DOM script.`;
+    }
+  },
+  WEBSH_FEAT_MISSING_WEB_HANDLER: {
+    code: 'WEBSH_FEAT_MISSING_WEB_HANDLER',
+    verbose: function (identifier, handlerId) {
+      return describe`Feature "${identifier}" has no Web handler with ID "${handlerId}".`;
+    }
+  },
+  WEBSH_FEAT_MISSING_IN_SHELL: {
+    code: 'WEBSH_FEAT_MISSING_IN_SHELL',
+    verbose: function (identifier) {
+      return describe`Feature ${identifier} has not be instantiated in this shell.`;
+    }
+  },
+  WEBSH_SCRIPT_ERROR: {
+    code: 'WEBSH_SCRIPT_ERROR',
+    verbose: function (identifier, body = 'empty error') {
+      return describe`Web script from feature "${identifier}" raised an error: ${body}`;
+    }
+  },
+  WEBSH_WEBVIEW_MISSING_MEMBER: {
+    code: 'WEBSH_WEBVIEW_MISSING_MEMBER',
+    verbose: function () {
+      return describe`The WebView element you passed is missing "injectJavaScript" method.`;
+    }
+  }
+};
+
+export class Reporter {
+  private readonly webshellDebug: boolean;
+  private readonly strict: boolean;
+  constructor(webshellDebug: boolean, strict: boolean) {
+    this.webshellDebug = webshellDebug;
+    this.strict = strict;
+  }
+  dispatchError(code: ErrorCode, ...args: any[]) {
+    if (!this.webshellDebug) {
+      return;
+    }
+    const message = ErrorCodes[code].verbose(...args);
+    if (this.strict) {
+      throw new Error(message);
+    } else {
+      console.warn(message);
+    }
+  }
+
+  dispatchWebLog(
+    severity: 'warn' | 'info',
+    identifier: string,
+    message: string
+  ) {
+    if (!this.webshellDebug) {
+      return;
+    }
+    if (severity === 'warn') {
+      console.warn(`[Webshell(${identifier})]: ${message}`);
+    } else if (severity === 'info') {
+      console.info(`[Webshell(${identifier})]: ${message}`);
+    }
+  }
+}
diff --git a/packages/core/src/__tests__/make-webshell.test.tsx b/packages/core/src/__tests__/make-webshell.test.tsx
@@ -10,11 +10,20 @@ import dummyHandleridScript from './feat/DummyHandlerid.webjs';
 import dummyReceiverScript from './feat/DummyReceiver.webjs';
 import { makeWebshell } from '../make-webshell';
 import { FeatureBuilder } from '../FeatureBuilder';
-import { MinimalWebViewProps, WebHandle } from '../types';
+import {
+  MinimalWebViewProps,
+  WebHandle,
+  WebshellInvariantProps
+} from '../types';
 import { act } from 'react-test-renderer';
 
 const { waitForErsatz } = makeErsatzTesting(Ersatz);
 
+const defaultWebshellProps: WebshellInvariantProps = {
+  webshellDebug: true,
+  webshellStrictMode: true
+};
+
 const DummyWebView = React.forwardRef(({}: MinimalWebViewProps, ref) => {
   React.useImperativeHandle(ref, () => ({
     injectJavaScript() {}
@@ -66,7 +75,7 @@ const ReceiverFeature = new FeatureBuilder({
 describe('Webshell component', () => {
   it('sould mount without error', () => {
     const Webshell = makeWebshell(DummyWebView, new HelloFeature());
-    const { UNSAFE_getByType } = render(<Webshell />);
+    const { UNSAFE_getByType } = render(<Webshell {...defaultWebshellProps} />);
     const webshell = UNSAFE_getByType(Webshell);
     expect(webshell).toBeTruthy();
   });
@@ -80,18 +89,11 @@ describe('Webshell component', () => {
     );
     expect(onDOMDummyHello).toHaveBeenCalledWith('Hello world!');
   });
-  it('should handle feature failures', async () => {
-    const onDOMDummyFailure = jest.fn();
+  it('should handle feature failures with onWebFeatureError', async () => {
     const onFailure = jest.fn();
     const Webshell = makeWebshell(Ersatz, new FailingFeature());
     await waitForErsatz(
-      render(
-        <Webshell
-          webshellDebug={false}
-          onDOMDummyFailure={onDOMDummyFailure}
-          onWebFeatureError={onFailure}
-        />
-      )
+      render(<Webshell webshellDebug={false} onWebFeatureError={onFailure} />)
     );
     expect(onFailure).toHaveBeenCalledWith(
       FailingFeature.identifier,
@@ -103,7 +105,10 @@ describe('Webshell component', () => {
     const Webshell = makeWebshell(Ersatz, new OptionFeature({ foo: 'bar' }));
     await waitForErsatz(
       render(
-        <Webshell webshellDebug={false} onDOMDummyOption={onDOMDummyOption} />
+        <Webshell
+          {...defaultWebshellProps}
+          onDOMDummyOption={onDOMDummyOption}
+        />
       )
     );
     expect(onDOMDummyOption).toHaveBeenCalledWith({ foo: 'bar' });
@@ -114,7 +119,7 @@ describe('Webshell component', () => {
     await waitForErsatz(
       render(
         <Webshell
-          webshellDebug={false}
+          {...defaultWebshellProps}
           onDOMDummyOption={onHandlerIdDummyOption}
         />
       )
@@ -130,8 +135,8 @@ describe('Webshell component', () => {
       render(
         <Webshell
           webHandle={webHandle}
-          webshellDebug={false}
           onWebFeedback={onWebFeedback}
+          {...defaultWebshellProps}
         />
       )
     );
diff --git a/packages/core/src/make-webshell.tsx b/packages/core/src/make-webshell.tsx
@@ -17,6 +17,7 @@ import type {
 import { FeatureRegistry } from './FeatureRegistry';
 import { BufferedWebRMIHandle } from './web/BufferedWebRMIHandle';
 import { WebFeaturesLoader } from './web/WebFeaturesLoader';
+import { Reporter } from './Reporter';
 
 interface WebViewMessage {
   data: string;
@@ -49,6 +50,7 @@ function isPostMessageObject(o: unknown): o is PostMessage {
 
 function useWebMessageBus(
   registry: FeatureRegistry<any>,
+  reporter: Reporter,
   {
     webshellDebug,
     onWebFeatureError,
@@ -74,47 +76,26 @@ function useWebMessageBus(
         if (type === 'feature') {
           const propDef = registry.getPropDefFromId(identifier, handlerId);
           if (!propDef) {
-            console.warn(
-              `[Webshell]: script from feature "${identifier}" sent an event towards ${handlerId} handler, but there is ` +
-                'no handler registered for this feature. ' +
-                'Use FeatureBuilder.withShellHandler to register that handler, or make ' +
-                'sure its name is not misspell in the DOM script.'
+            reporter.dispatchError(
+              'WEBSH_MISSING_SHELL_HANDLER',
+              identifier,
+              handlerId
             );
             return;
           }
           const handlerName = propDef.name;
           const handler =
             typeof handlerId === 'string' ? domHandlers[handlerName] : null;
-          if (registry.getPropDefFromHandlerName(handlerName)) {
-            if (typeof handler === 'function') {
-              handler(body);
-            } else {
-              webshellDebug &&
-                console.info(
-                  `[Webshell]: script from feature "${identifier}" sent an event towards ${handlerId} handler, but there ` +
-                    `is no handler prop named "${handlerName}" attached to the shell.`
-                );
-            }
-          } else {
-            console.warn(
-              `[Webshell]: script from feature "${identifier}" sent an event towards ${handlerId} handler, but there is ` +
-                `no handler named "${handlerName}" defined with this handler ID. ` +
-                'Use FeatureBuilder.withShellHandler to register that handler, or make ' +
-                'sure its name is not misspell in the DOM script.'
-            );
+          if (typeof handler === 'function') {
+            handler(body);
           }
         } else if (type === 'error') {
           // Handle as an error message
           typeof onWebFeatureError === 'function' &&
             onWebFeatureError(identifier, body);
-          webshellDebug &&
-            console.warn(
-              `[Webshell]: script from feature "${identifier}" raised an error: ${body}`
-            );
-          return;
+          reporter.dispatchError('WEBSH_SCRIPT_ERROR', identifier, body);
         } else if (type === 'log') {
-          webshellDebug && severity === 'warn' && console.warn(body);
-          webshellDebug && severity === 'info' && console.info(body);
+          reporter.dispatchWebLog(severity, identifier, body);
         }
       } else {
         typeof onMessage === 'function' && onMessage(nativeEvent);
@@ -131,11 +112,13 @@ function useWebMessageBus(
 
 function useWebHandle(
   webViewRef: React.RefObject<any>,
-  registry: FeatureRegistry<any>
+  registry: FeatureRegistry<any>,
+  reporter: Reporter
 ) {
   return React.useMemo(
-    (): BufferedWebRMIHandle => new BufferedWebRMIHandle(webViewRef, registry),
-    [webViewRef, registry]
+    (): BufferedWebRMIHandle =>
+      new BufferedWebRMIHandle(webViewRef, registry, reporter),
+    [webViewRef, registry, reporter]
   );
 }
 
@@ -200,14 +183,20 @@ export function makeWebshell<
       webViewRef,
       injectedJavaScript: userInjectedJavaScript,
       webshellDebug,
+      webshellStrictMode,
       ...webViewProps
     } = props;
+    const reporter = React.useMemo(
+      () => new Reporter(webshellDebug, webshellStrictMode),
+      [webshellDebug, webshellStrictMode]
+    );
     const { handleOnWebMessage, isLoaded } = useWebMessageBus(
       registry,
+      reporter,
       otherProps
     );
     const injectedJavaScript = useJavaScript(loader, userInjectedJavaScript);
-    const webHandle = useWebHandle(webViewRef, registry);
+    const webHandle = useWebHandle(webViewRef, registry, reporter);
 
     React.useImperativeHandle(webHandleRef, () => webHandle);
     React.useEffect(() => {
@@ -229,7 +218,8 @@ export function makeWebshell<
     );
   };
   Webshell.defaultProps = {
-    webshellDebug: __DEV__
+    webshellDebug: __DEV__,
+    webshellStrict: false
   };
   return React.forwardRef<
     ElementRef<C>,
diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts
@@ -214,9 +214,16 @@ export interface WebshellInvariantProps {
   /**
    * Report Web error messages from features in the console.
    *
-   * @defaultvalue `__DEV__`
+   * @defaultvalue `__DEV__` (`true` in development, `false` otherwise)
    */
   webshellDebug?: boolean;
+  /**
+   * If this prop is `true` and `webshellDebug` is `true`, errors will be
+   * thrown when inconsistencies are identified.
+   *
+   * @defaultvalue false
+   */
+  webshellStrictMode?: boolean;
   /**
    * Pass a reference to send messages to the Web environment.
    */
diff --git a/packages/core/src/web/BufferedWebRMIHandle.ts b/packages/core/src/web/BufferedWebRMIHandle.ts
@@ -1,5 +1,6 @@
 import React from 'react';
 import { FeatureRegistry } from '../FeatureRegistry';
+import { Reporter } from '../Reporter';
 import { WebHandle } from '../types';
 import { WebRMIHandle } from './WebRMIHandle';
 
@@ -17,9 +18,10 @@ export class BufferedWebRMIHandle implements WebHandle {
 
   constructor(
     webViewRef: React.RefObject<any>,
-    registry: FeatureRegistry<any>
+    registry: FeatureRegistry<any>,
+    webshellDebug: Reporter
   ) {
-    this.handle = new WebRMIHandle(webViewRef, registry);
+    this.handle = new WebRMIHandle(webViewRef, registry, webshellDebug);
     this.postMessageToWeb = this.proxify('postMessageToWeb');
     this.setDebug = this.proxify('setDebug');
   }
diff --git a/packages/core/src/web/WebRMIController.ts b/packages/core/src/web/WebRMIController.ts
@@ -1,4 +1,5 @@
 import { RefObject } from 'react';
+import { Reporter } from '../Reporter';
 
 function javaScript(snippets: TemplateStringsArray, ...args: any[]) {
   return snippets
@@ -13,15 +14,15 @@ export class WebRMIController {
   private webViewRef: RefObject<{
     injectJavaScript: (js: string) => void;
   }>;
-  constructor(webViewRef: RefObject<any>) {
+  protected reporter: Reporter;
+  constructor(webViewRef: RefObject<any>, reporter: Reporter) {
     this.webViewRef = webViewRef;
+    this.reporter = reporter;
   }
 
   protected injectJavaScript(snippets: TemplateStringsArray, ...args: any[]) {
     if (this.webViewRef.current && !this.webViewRef.current.injectJavaScript) {
-      console.warn(
-        '[Webshell]: The WebView element you passed is missing injectJavaScript method.'
-      );
+      this.reporter.dispatchError('WEBSH_WEBVIEW_MISSING_MEMBER');
       return;
     }
     this.webViewRef.current?.injectJavaScript(javaScript(snippets, ...args));
diff --git a/packages/core/src/web/WebRMIHandle.ts b/packages/core/src/web/WebRMIHandle.ts
diff --git a/packages/core/src/web/web-features-loader.webjs b/packages/core/src/web/web-features-loader.webjs

Original file line number	Diff line number	Diff line change
`@@ -393,6 +393,7 @@ export interface WebshellInvariantProps {`
`393`	`393`	`onWebFeatureError?: (featureIdentifier: string, error: string) => void;`
`394`	`394`	`webHandle?: Ref<WebHandle>;`
`395`	`395`	`webshellDebug?: boolean;`
	`396`	`+ webshellStrictMode?: boolean;`
`396`	`397`	`}`
`397`	`398`
`398`	`399`	`// @public`