@lwc/hmr-client 10.2.1 → 10.3.1

package/dist/client/client.d.ts

@@ -0,0 +1,38 @@
+import JSONWebSocket from '../utils/json-web-socket';
+import { TypedEventTarget } from '../utils/typed-event-target';
+import { HotModuleHandler } from './hot-module-handler';
+type HmrClientEvent = {
+    modulePath: string;
+};
+type HmrClientEvents = {
+    'hmr:update': HmrClientEvent;
+    'hmr:delete': HmrClientEvent;
+    'hmr:create': HmrClientEvent;
+    'hmr:hot-swapped': HmrClientEvent;
+    'hmr:close': void;
+};
+export declare class HMRClient {
+    moduleHandlerHooks: HotModuleHandler;
+    ws: JSONWebSocket;
+    private eventTarget;
+    constructor(ws: JSONWebSocket, moduleHandlerHooks: HotModuleHandler);
+    /**
+     * Register all modules that have been registered at this point.
+     * This function is usually called upon hmr-client initialization.
+     */
+    registerAllModules(): void;
+    /**
+     * Register any new modules that have been registered.
+     */
+    registerPendingModules(): void;
+    messageCallback(data: unknown): void;
+    /**
+     * Send a message to the dev server to send a hot module.
+     * The send and receive messages are asyncronous.
+     * @param modulePath the module to be fetched
+     */
+    fetchModule(modulePath: string): void;
+    addEventListener: TypedEventTarget<HmrClientEvents>['addEventListener'];
+    removeEventListener: TypedEventTarget<HmrClientEvents>['removeEventListener'];
+}
+export {};

package/dist/client/hot-module-handler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * This interface defines capabilities that need to be implemented by the container to handle hot module
+ * updates.
+ */
+export interface HotModuleHandler {
+    /**
+     * Fetch all dependencies that are required for a hot module before its evaluation.
+     * @param moduleSpecifiers List of dependent modules specifiers.
+     */
+    fetchDependencies(moduleSpecifiers: string[]): Promise<any>;
+    /**
+     * Evalaute a given Javascript source code.
+     * @param source Javascript in string format.
+     */
+    evaluateModule(ownerModuleId: string, hotModulePath: string, source: string): Promise<unknown>;
+}

package/dist/client/index.d.ts

@@ -0,0 +1,18 @@
+import { Auth_Challenge, Auth_Response } from '@lwc/lwc-dev-server-types';
+import { HotModuleHandler } from './hot-module-handler';
+import { HMRClient } from './client';
+type AuthConfig = {
+    authChallengeData: Auth_Challenge;
+    authResponseCallback: (response: Auth_Response) => boolean;
+};
+/**
+ * Initialize the hmr-client.
+ * @param url The lightning dev preview server to connect to. Provide the fully qualified WebSocketServer url, for example 'wss://localhost:8999'
+ * @param target The type of client being served. Currently only supports 'LEX.
+ * @param hotModuleHandler Callback hooks that the hmr-client will utilize to handle hot modules. The callbacks are implemented by the container.
+ * @param authConfig Optional authentication configuration if the hmr-client needs to establish an authenticated connection.
+ *
+ * @returns {HMRClient} the HMR Client
+ */
+export declare function initializeClient(url: string, _target: string, hotModuleHandler: HotModuleHandler, authConfig?: AuthConfig): Promise<HMRClient>;
+export {};

package/dist/client/index.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.cjs.js

@@ -5,6 +5,54 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var lwcDevServerTypes = require('@lwc/lwc-dev-server-types');
+
+/**
+ * Wrapper on WebSocket to handle JSON serialization/deserialization
+ */
+class JSONWebSocket {
+    constructor(url, protocols) {
+        this.socket = new WebSocket(url, protocols);
+    }
+    send(data) {
+        this.socket.send(JSON.stringify(data));
+    }
+    onMessage(callback) {
+        this.socket.addEventListener('message', (event) => {
+            const jsonData = JSON.parse(event.data);
+            callback(jsonData);
+        });
+    }
+    close() {
+        this.socket.close();
+    }
+    static init(url, protocols) {
+        return new Promise((resolve, reject) => {
+            try {
+                const socket = new JSONWebSocket(url, protocols);
+                socket.socket.onopen = () => resolve(socket);
+                socket.socket.onerror = (e) => reject(e);
+            }
+            catch (e) {
+                reject(e);
+            }
+        });
+    }
+}
+
+/* eslint-disable no-console */
+/**
+ * All the console methods in one module so that these can be instrumented for JEST tests and
+ * marked for eslint ignore in one place.
+ */
+const LABEL = '[lightning preview]';
+function logWarning(message) {
+    console.warn(`${LABEL} ${message}`);
+}
+
+const IGNORING_PREAUTH_RESPONSES = 'Ignoring pre-authenticated responses sent from Lightning Dev Preview server';
+const AUTH_FAILURE = 'WebSocket Authentication Failure: Failed to success fully establish an authenticated connection between Lightning Dev Preview server and client';
+
 const hotModuleCbs = new Map();
 /**
  * API call to self update.
@@ -95,239 +143,6 @@ function getActiveModules() {
     return Array.from(activeModules.values());
 }
 
-/**
- * This module is responsible for notfying the user about module updates in the server
- **/
-class NotifyModuleUpdate {
-    constructor() {
-        this.observers = new Set();
-    }
-    register(observer) {
-        if (observer) {
-            this.observers.add(observer);
-        }
-    }
-    deregister(observer) {
-        if (observer) {
-            this.observers.delete(observer);
-        }
-    }
-    notify(message) {
-        this.observers.forEach((observer) => observer.notify(message));
-    }
-}
-
-/* eslint-disable no-console */
-/**
- * All the console methods in one module so that these can be instrumented for JEST tests and
- * marked for eslint ignore in one place.
- */
-const LABEL = '[lightning preview]';
-function logWarning(message) {
-    console.warn(`${LABEL} ${message}`);
-}
-function logInfo(message) {
-    console.log(`${LABEL} ${message}`);
-}
-
-const SOCKET_OPEN = 'WebSocket: Connection to Lightning Dev Preview server open.';
-const SOCKET_CONNECTION_INITIATION = 'WebSocket: Connecting to Lightning Dev Preview server:';
-const SOCKET_SERVER_UNAVAILABLE = 'WebSocket Server Unavailable: Connection to Lightning Dev Preview server unavailable.';
-const SOCKET_SERVER_CONNECTION_ERROR = 'WebSocket Server Connection Error: Connection to Lightning Dev Preview server failed.';
-const IGNORING_PREAUTH_RESPONSES = 'Ignoring pre-authenticated responses sent from Lightning Dev Preview server';
-const AUTH_FAILURE = 'WebSocket Authentication Failure: Failed to success fully establish an authenticated connection between Lightning Dev Preview server and client';
-
-const CONNECTION_RETRY_COUNT = 5;
-const CONNECTION_RETRY_INTERVAL_MS = 500;
-async function getConnection(devServerUrl, target, clientId, authConfig, connectionOpenCallback, connectionCloseCallback) {
-    const socket = await initiateWSConnection(devServerUrl, CONNECTION_RETRY_COUNT);
-    connectionOpenCallback && connectionOpenCallback();
-    if (connectionCloseCallback) {
-        socket.addEventListener('close', connectionCloseCallback);
-    }
-    const connection = new Connection(socket);
-    const initData = {
-        type: 'init',
-        data: {
-            clientId,
-            url: window.location.href,
-            target,
-        },
-    };
-    // If authentication is needed, resolve promise after successful authentication
-    if (authConfig) {
-        return new Promise((resolve, reject) => {
-            // Create a listener to handle the auth response and remove it once the connection is authenticated
-            const listener = createAuthMessageHandler((response) => {
-                // Delegate auth response validation to invoker
-                const authResult = authConfig.authResponseCallback(response);
-                // If successful, resolve with a connection that is ready to be used
-                if (authResult) {
-                    socket.removeEventListener('message', listener);
-                    resolve(connection);
-                }
-                else {
-                    reject(new Error(AUTH_FAILURE));
-                }
-            });
-            socket.addEventListener('message', listener);
-            initData.data.auth = {
-                type: 'auth-challenge',
-                data: authConfig.authChallengeData,
-            };
-            connection.send(initData);
-        });
-    }
-    else {
-        connection.send(initData);
-        return connection;
-    }
-}
-class Connection {
-    constructor(socket) {
-        this.socket = socket;
-    }
-    send(data) {
-        if (!this.isReady()) {
-            logWarning('Ignoring to send data before connection is ready.');
-            return false;
-        }
-        this.socket.send(JSON.stringify(data));
-        return true;
-    }
-    receive(callback) {
-        if (!this.isReady()) {
-            logWarning('Connection not ready to receive data from server.');
-            return;
-        }
-        this.socket.addEventListener('message', ({ data }) => {
-            if (data) {
-                const payload = JSON.parse(data);
-                callback(payload);
-            }
-        });
-    }
-    close() {
-        this.socket.close();
-    }
-    isReady() {
-        return this.socket.readyState === this.socket.OPEN;
-    }
-}
-/**
- * A event handler to handle messages from the WebSocket.
- * This handler is meant to only be used for authentication and then detached after successful auth.
- */
-function createAuthMessageHandler(authCallback) {
-    return ({ data }) => {
-        if (data) {
-            const payload = JSON.parse(data);
-            // only accept auth-response messages from LDP Server until authenticated
-            if (payload.type !== 'auth-response') {
-                logWarning(IGNORING_PREAUTH_RESPONSES);
-                return;
-            }
-            if (payload.type === 'auth-response') {
-                const authResponse = payload;
-                authCallback(authResponse.data);
-            }
-        }
-    };
-}
-/**
- * A function to establish a WebSocket connection to the provided url
- * @param wsServerUrl The lightning dev server url to connect to
- * @param connectionRetry number of retry attempts to connect with the server
- * @returns
- */
-async function initiateWSConnection(wsServerUrl, connectionRetry) {
-    let socket;
-    let retryCount = 0;
-    while (socket === undefined && retryCount < connectionRetry) {
-        try {
-            logInfo(`${SOCKET_CONNECTION_INITIATION} ${wsServerUrl}` + retryCount
-                ? `, retry attempt: ${retryCount}`
-                : '');
-            socket = await connect(wsServerUrl);
-        }
-        catch (e) {
-            // Nothing to do, the LDP server is not available yet.
-            // Cannot tell if the server url is unavailable or invalid, regardless it will retry
-        }
-        if (socket !== undefined) {
-            break;
-        }
-        retryCount++;
-        await new Promise((resolve) => setTimeout(resolve, CONNECTION_RETRY_INTERVAL_MS));
-    }
-    if (socket === undefined) {
-        logWarning(SOCKET_SERVER_UNAVAILABLE);
-        throw new Error(SOCKET_SERVER_UNAVAILABLE);
-    }
-    return socket;
-}
-/**
- * Attempt to open a WebSockect connection
- * @param wsServerUrl WebSocketServer url to connect to
- * @returns Resolves with a successful socket connection, that is open to communication else rejects with an error message
- */
-function connect(wsServerUrl) {
-    return new Promise((resolve, reject) => {
-        try {
-            const socket = new WebSocket(wsServerUrl, 'lightning-dev-preview');
-            const errorHandler = (_e) => {
-                logWarning(`${SOCKET_SERVER_CONNECTION_ERROR}.`);
-                reject(SOCKET_SERVER_CONNECTION_ERROR);
-            };
-            socket.addEventListener('error', errorHandler);
-            // The connection is ready when the open callback is called, resolve the promise then
-            socket.addEventListener('open', () => {
-                logInfo(SOCKET_OPEN);
-                // Remove the error handler once the connection is open
-                socket.removeEventListener('error', errorHandler);
-                // The connection is ready when the open callback is called, resolve the promise then
-                resolve(socket);
-            });
-        }
-        catch (e) {
-            logWarning(`${SOCKET_SERVER_CONNECTION_ERROR}. Cause: ${JSON.stringify(e)}`);
-            reject(SOCKET_SERVER_CONNECTION_ERROR);
-        }
-    });
-}
-
-class ConsoleNotifier {
-    notify(message) {
-        switch (message.eventType) {
-            case 'create':
-                console.log(`A new module was added at ${message.modulePath}`);
-                break;
-            case 'delete':
-                console.log(`A module was deleted at ${message.modulePath}`);
-                break;
-            case 'update':
-                console.log(`A source change detected at ${message.modulePath}`);
-                break;
-            case 'hot-swapped':
-                console.log(`Received a hot module with path ${message.modulePath}, attempting to hot swap`);
-                break;
-        }
-        if (message.action) {
-            console.log(`Taking the following action on module update ${message.action.message}`);
-        }
-    }
-}
-
-function debounce(callback, delay) {
-    let timer;
-    return () => {
-        clearTimeout(timer);
-        timer = window.setTimeout(() => {
-            callback();
-        }, delay);
-    };
-}
-
 function extractDescriptorsFromSource(src) {
     const amdPattern = /^define\('([^']+)',\s*\[([^\]]*)\],/;
     const match = amdPattern.exec(src);
@@ -349,32 +164,86 @@ function adaptSourceForLex(src, hotModulePath, parentDescriptor) {
         .concat('}');
 }
 
-const MODULE_REGISTRATION_DELAY_MS = 100;
-// Create a random identifier for the client connection
-function generateRandomClientId() {
-    const uid = typeof crypto !== 'undefined' ? crypto.randomUUID() : Math.round(Math.random() * 1000);
-    return `${uid}`;
+function debounce(callback, delay) {
+    let timer;
+    return () => {
+        clearTimeout(timer);
+        timer = setTimeout(() => {
+            callback();
+        }, delay);
+    };
+}
+
+/******************************************************************************
+Copyright (c) Microsoft Corporation.
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.
+***************************************************************************** */
+/* global Reflect, Promise, SuppressedError, Symbol */
+
+
+function __classPrivateFieldGet(receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+}
+
+function __classPrivateFieldSet(receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+}
+
+typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+};
+
+var _TypedEventTarget_target;
+//TODO:  move to notify folder
+class TypedEventTarget {
+    constructor() {
+        _TypedEventTarget_target.set(this, void 0);
+        __classPrivateFieldSet(this, _TypedEventTarget_target, new EventTarget(), "f");
+    }
+    addEventListener(type, listener) {
+        __classPrivateFieldGet(this, _TypedEventTarget_target, "f").addEventListener(type, listener);
+    }
+    removeEventListener(type, listener) {
+        __classPrivateFieldGet(this, _TypedEventTarget_target, "f").removeEventListener(type, listener);
+    }
+    dispatch(type, detail) {
+        return __classPrivateFieldGet(this, _TypedEventTarget_target, "f").dispatchEvent(new CustomEvent(type, { detail }));
+    }
 }
+_TypedEventTarget_target = new WeakMap();
+
+const MODULE_REGISTRATION_DELAY_MS = 100;
 let hotModuleCounter = 0;
 class HMRClient {
-    constructor(clientId, connection, moduleHandlerHooks) {
-        this.notifyModuleUpdate = new NotifyModuleUpdate();
+    constructor(ws, moduleHandlerHooks) {
+        this.eventTarget = new TypedEventTarget();
+        this.addEventListener = (...args) => {
+            this.eventTarget.addEventListener(...args);
+        };
+        this.removeEventListener = (...args) => {
+            this.eventTarget.removeEventListener(...args);
+        };
+        if (ws.socket.readyState !== 1) {
+            throw new Error('Socket needs to be open');
+        }
         this.moduleHandlerHooks = moduleHandlerHooks;
-        this.connection = connection;
-        this.clientId = clientId;
-        // Register a console logger
-        this.notifyModuleUpdate.register(new ConsoleNotifier());
-        this.init();
-    }
-    registerObserver(observer) {
-        // Register any container specific observers
-        this.notifyModuleUpdate.register(observer);
-    }
-    /**
-     * Initialize the hmr-client.
-     */
-    init() {
-        // Register all modules upon first connection
+        this.ws = ws;
         this.registerAllModules();
         // Add a debounced callback to register any new modules with server
         const registerPendingModulesDebounced = debounce(this.registerPendingModules.bind(this), MODULE_REGISTRATION_DELAY_MS);
@@ -382,7 +251,8 @@ class HMRClient {
             modulesPendingRegistration.add(modulePath);
             registerPendingModulesDebounced();
         });
-        this.connection.receive(this.messageCallback.bind(this));
+        this.ws.onMessage(this.messageCallback.bind(this));
+        this.ws.socket.addEventListener('close', () => this.eventTarget.dispatch('hmr:close'));
     }
     /**
      * Register all modules that have been registered at this point.
@@ -393,10 +263,9 @@ class HMRClient {
             type: 'register',
             data: {
                 modules: getActiveModules(),
-                clientId: this.clientId,
             },
         };
-        this.connection.send(moduleRegistration);
+        this.ws.send(moduleRegistration);
         modulesPendingRegistration.clear();
     }
     /**
@@ -408,15 +277,16 @@ class HMRClient {
                 type: 'register',
                 data: {
                     modules: Array.from(modulesPendingRegistration).map((module) => activeModules.get(module)),
-                    clientId: this.clientId,
                 },
             };
-            this.connection.send(moduleRegistration);
+            this.ws.send(moduleRegistration);
             // We assume the registration was successful
             modulesPendingRegistration.clear();
         }
     }
     messageCallback(data) {
+        if (!lwcDevServerTypes.isHmrData(data))
+            return;
         switch (data.type) {
             // Some paths were updated
             case 'update': {
@@ -424,10 +294,7 @@ class HMRClient {
                 moduleUpdate.data.forEach(({ modulePath }) => {
                     // If there are update handlers for the modulePath, then fetch an update
                     if (hasUpdateHandlers(modulePath)) {
-                        this.notifyModuleUpdate.notify({
-                            eventType: 'update',
-                            modulePath,
-                        });
+                        this.eventTarget.dispatch('hmr:update', { modulePath });
                         this.fetchModule(modulePath);
                     }
                 });
@@ -438,10 +305,7 @@ class HMRClient {
                 const hotModules = data;
                 // Process each incoming hot module
                 hotModules.data.forEach(async ({ modulePath, src }) => {
-                    this.notifyModuleUpdate.notify({
-                        eventType: 'hot-swapped',
-                        modulePath,
-                    });
+                    this.eventTarget.dispatch('hmr:hot-swapped', { modulePath });
                     // Wrapped update handler, it will call the previous accept callbacks and remove
                     // them after they have been invoked.
                     const handler = updateHandler(modulePath);
@@ -466,10 +330,7 @@ class HMRClient {
             case 'module-delete': {
                 const deletedModule = data;
                 deletedModule.data.forEach(({ modulePath }) => {
-                    this.notifyModuleUpdate.notify({
-                        eventType: 'delete',
-                        modulePath,
-                    });
+                    this.eventTarget.dispatch('hmr:delete', { modulePath });
                 });
                 // A module was deleted
                 // reload page?
@@ -478,7 +339,7 @@ class HMRClient {
             case 'error':
                 // eslint-disable-next-line no-console
                 console.log('LWC dev server encountered an error, reloading page');
-                window.location.reload();
+                location.reload();
                 break;
         }
     }
@@ -491,26 +352,65 @@ class HMRClient {
         const fetchData = { type: 'fetch', data: { modulePath } };
         // fetch the new module from the server
         // eval it and return the new module
-        this.connection.send(fetchData);
+        this.ws.send(fetchData);
     }
 }
+
 /**
  * Initialize the hmr-client.
  * @param url The lightning dev preview server to connect to. Provide the fully qualified WebSocketServer url, for example 'wss://localhost:8999'
  * @param target The type of client being served. Currently only supports 'LEX.
  * @param hotModuleHandler Callback hooks that the hmr-client will utilize to handle hot modules. The callbacks are implemented by the container.
  * @param authConfig Optional authentication configuration if the hmr-client needs to establish an authenticated connection.
- * @param connectionOpenCallback Be notified when a connection to the server is open.
- * @param connectionCloseCallback Be notified when a connection to the server is closed.
- * @param observer Be notified of hot module updates.
+ *
+ * @returns {HMRClient} the HMR Client
  */
-async function initializeClient(url, target, hotModuleHandler, authConfig, connectionOpenCallback, connectionCloseCallback, observer) {
-    const clientId = generateRandomClientId();
-    const connection = await getConnection(url, target, clientId, authConfig, connectionOpenCallback, connectionCloseCallback);
-    const hmrClient = new HMRClient(clientId, connection, hotModuleHandler);
-    if (observer) {
-        hmrClient.notifyModuleUpdate.register(observer);
+async function initializeClient(url, _target, hotModuleHandler, authConfig) {
+    const wsUrl = new URL(url);
+    wsUrl.searchParams.set('referer', location.href);
+    if (authConfig) {
+        wsUrl.searchParams.set('sessionTokenCipher', authConfig.authChallengeData.sessionTokenCipher);
+    }
+    const ws = await JSONWebSocket.init(wsUrl.toString(), 'lightning-dev-preview');
+    if (authConfig) {
+        try {
+            await waitForAuthResponse(ws, authConfig);
+        }
+        catch (e) {
+            ws.close();
+            throw e;
+        }
     }
+    const client = new HMRClient(ws, hotModuleHandler);
+    listenOnConsole(client);
+    return client;
+}
+function waitForAuthResponse(ws, authConfig) {
+    return new Promise((resolve, reject) => {
+        const listener = ({ data }) => {
+            if (!data)
+                reject(new Error('Invalid message, missing data.')); // TODO: log the reason here.
+            const payload = JSON.parse(data);
+            if (payload.type !== 'auth-response') {
+                logWarning(IGNORING_PREAUTH_RESPONSES); // TODO: log the reason here.
+                reject(new Error('Invalid non-auth response.'));
+            }
+            if (authConfig.authResponseCallback(payload.data)) {
+                resolve();
+            }
+            else {
+                reject(new Error(AUTH_FAILURE));
+            }
+        };
+        ws.socket.addEventListener('message', listener, { once: true });
+    });
+}
+/* eslint-disable no-console */
+function listenOnConsole(hmrClient) {
+    hmrClient.addEventListener('hmr:create', (event) => console.log(`A new module was added at ${event.detail.modulePath}`));
+    hmrClient.addEventListener('hmr:update', (event) => console.log(`A source change detected at ${event.detail.modulePath}`));
+    hmrClient.addEventListener('hmr:hot-swapped', (event) => console.log(`Received a hot module with path ${event.detail.modulePath}, attempting to hot swap`));
+    hmrClient.addEventListener('hmr:delete', (event) => console.log(`A module was deleted at ${event.detail.modulePath}`));
 }
 
 exports.accept = accept;