In modern web development, asynchronous programming and event listening are core technologies for building responsive, high-performance applications. Browser extensions, as specialized applications running in the browser environment, require efficient handling of asynchronous operations and event interactions. This tutorial will deeply explore asynchronous programming patterns and event listening mechanisms, with source-code-level analysis tailored to practical scenarios in browser extensions.
Asynchronous Programming Patterns
Promises and Asynchronous Flow Control
Promises are the foundational building blocks of JavaScript asynchronous programming, representing the eventual completion or failure of an asynchronous operation. Mastering advanced Promise usage can effectively manage complex asynchronous flows.
Optimized Promise Chaining
// Basic Promise chain example
function fetchUserData(userId) {
return fetch(`https://api.example.com/users/${userId}`)
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.json();
})
.then(userData => {
return fetch(`https://api.example.com/users/${userId}/preferences`);
})
.then(response => response.json())
.catch(error => {
console.error('Error in fetchUserData:', error);
throw error; // Rethrow error for external handling
});
}
// Optimized Promise chain: Adding intermediate processing steps
function enhancedFetchUserData(userId) {
let userRequest;
return fetch(`https://api.example.com/users/${userId}`)
.then(response => {
if (!response.ok) throw new Error('User fetch failed');
userRequest = response; // Save request reference
return response.json();
})
.then(userData => {
// Add validation step after fetching user data
if (!userData.isActive) {
throw new Error('Inactive user');
}
// Initiate multiple related requests in parallel
const preferencesPromise = fetch(`https://api.example.com/users/${userId}/preferences`)
.then(res => res.json());
const historyPromise = fetch(`https://api.example.com/users/${userId}/history`)
.then(res => res.json());
return Promise.all([preferencesPromise, historyPromise])
.then(([preferences, history]) => ({
...userData,
preferences,
history
}));
})
.catch(error => {
// Enhanced error handling: Add contextual information
if (error.message === 'Inactive user') {
console.warn('Attempted to fetch data for inactive user');
} else if (userRequest && userRequest.status === 404) {
console.error('User not found:', userId);
}
throw error;
});
}Advanced Promise Pattern: Timeout Control
// Implement Promise timeout mechanism
function withTimeout(promise, timeoutMs, timeoutMessage = 'Operation timed out') {
let timeoutId;
const timeoutPromise = new Promise((_, reject) => {
timeoutId = setTimeout(() => {
reject(new Error(timeoutMessage));
}, timeoutMs);
});
return Promise.race([promise, timeoutPromise])
.finally(() => clearTimeout(timeoutId));
}
// Usage example: Add timeout to API requests
async function fetchWithTimeout(url, options = {}, timeout = 5000) {
try {
const response = await withTimeout(
fetch(url, options),
timeout,
`Request to ${url} timed out after ${timeout}ms`
);
if (!response.ok) {
throw new Error(`HTTP error ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('Fetch error:', error.message);
throw error; // Rethrow for caller handling
}
}
// Practical application in extension
async function getExtensionData() {
try {
const [userPrefs, systemStatus] = await Promise.all([
fetchWithTimeout('https://api.example.com/user/prefs', {}, 3000),
fetchWithTimeout('https://api.example.com/system/status', {}, 2000)
]);
return { userPrefs, systemStatus };
} catch (error) {
// Unified error handling
if (error.message.includes('timed out')) {
showUserNotification('Request timed out, please check network connection');
} else {
showUserNotification('Failed to fetch data, please try again later');
}
return null;
}
}Async/Await and Error Handling
Async/Await syntax sugar makes asynchronous code resemble synchronous code, but special attention must be paid to error handling patterns.
Structured Error Handling Pattern
// Basic async/await error handling
async function loadExtensionSettings() {
try {
const response = await fetch('https://api.example.com/settings');
if (!response.ok) {
throw new Error(`HTTP error ${response.status}`);
}
const settings = await response.json();
return settings;
} catch (error) {
console.error('Failed to load settings:', error);
return getDefaultSettings(); // Fallback handling
}
}
// Advanced pattern: Async function with retry mechanism
async function fetchWithRetry(url, options = {}, maxRetries = 3, delayMs = 1000) {
let lastError;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const response = await fetch(url, options);
if (!response.ok) {
throw new Error(`HTTP error ${response.status}`);
}
return await response.json();
} catch (error) {
lastError = error;
if (attempt < maxRetries) {
console.warn(`Attempt ${attempt} failed, retrying in ${delayMs}ms...`);
await new Promise(resolve => setTimeout(resolve, delayMs));
delayMs *= 2; // Exponential backoff
}
}
}
throw lastError; // Throw the last error after all retries fail
}
// Practical application in extension
async function initializeExtension() {
try {
// Initialize multiple components in parallel
const [settings, userData, systemInfo] = await Promise.all([
fetchWithRetry('https://api.example.com/settings'),
loadExtensionSettings(),
fetchSystemInfo()
]);
// Execute main logic after initialization
startMainApplication(settings, userData, systemInfo);
} catch (error) {
console.error('Extension initialization failed:', error);
showFatalErrorUI(error);
}
}
// Async function with resource cleanup
async function processFile(file) {
let fileHandle;
try {
// Open file
fileHandle = await file.open();
// Process file content
const content = await fileHandle.read();
const processed = await transformContent(content);
// Save result
await saveResult(processed);
return { success: true };
} catch (error) {
console.error('File processing failed:', error);
return { success: false, error };
} finally {
// Ensure resource release
if (fileHandle) {
await fileHandle.close().catch(closeError => {
console.error('Failed to close file handle:', closeError);
});
}
}
}Asynchronous Generators and Stream Processing
Asynchronous generators provide an elegant solution for handling data streams, particularly suitable for large datasets or real-time data streams.
// Basic asynchronous generator example
async function* asyncNumberGenerator(start, end, delayMs) {
for (let i = start; i <= end; i++) {
await new Promise(resolve => setTimeout(resolve, delayMs));
yield i;
}
}
// Usage example
(async () => {
for await (const num of asyncNumberGenerator(1, 5, 1000)) {
console.log(num); // Output one number per second
}
})();
// Practical application in extension: Paginated data fetching
async function* paginatedFetcher(apiUrl, pageSize = 10) {
let page = 1;
let hasMore = true;
while (hasMore) {
try {
const response = await fetch(`${apiUrl}?page=${page}&size=${pageSize}`);
if (!response.ok) {
throw new Error(`HTTP error ${response.status}`);
}
const data = await response.json();
yield data.items; // Yield current page data
hasMore = data.hasMore;
page++;
} catch (error) {
console.error('Fetch error:', error);
yield []; // Return empty array on error
break; // Or implement retry logic based on needs
}
}
}
// Process large dataset using paginated fetcher
async function processLargeDataset() {
const dataProcessor = createDataProcessor(); // Hypothetical data processing function
for await (const items of paginatedFetcher('https://api.example.com/data')) {
if (items.length === 0) break;
// Process current page data
await dataProcessor.process(items);
// Optional: Add progress updates
updateProgress(dataProcessor.getProcessedCount());
}
console.log('Data processing complete');
}
// More complex asynchronous generator: Real-time event stream processing
async function* eventStreamProcessor(eventSource) {
let buffer = '';
for await (const chunk of eventSource) {
buffer += chunk;
// Process possible multiple messages
let messageEnd;
while ((messageEnd = buffer.indexOf('\n\n')) >= 0) {
const message = buffer.substring(0, messageEnd);
buffer = buffer.substring(messageEnd + 2);
try {
const eventData = JSON.parse(message);
yield eventData; // Yield parsed event
} catch (error) {
console.error('Failed to parse event:', error);
}
}
}
}
// Use event stream processor
async function monitorExtensionEvents() {
const eventSource = new EventSource('https://api.example.com/events');
for await (const event of eventStreamProcessor(eventSource)) {
handleExtensionEvent(event);
}
console.log('Event stream ended');
}Event Listening Mechanisms
Deep Dive into Browser Event System
The browser provides a rich event system, and understanding its workings is crucial for building responsive extensions.
Event Propagation and Capture Mechanisms
// Demonstration of event propagation phases
document.addEventListener('click', (event) => {
console.log('Document capture phase:', event.eventPhase); // 1: CAPTURING_PHASE
}, true);
document.getElementById('target').addEventListener('click', (event) => {
console.log('Target element target phase:', event.eventPhase); // 2: AT_TARGET
});
document.addEventListener('click', (event) => {
console.log('Document bubbling phase:', event.eventPhase); // 3: BUBBLING_PHASE
}, false);
// Example of stopping event propagation
document.getElementById('child').addEventListener('click', (event) => {
console.log('Child element event handling');
event.stopPropagation(); // Prevent further event propagation
});
document.getElementById('parent').addEventListener('click', () => {
console.log('Parent element event handling (won’t execute if child calls stopPropagation)');
});Custom Event System
// Create and dispatch custom events
class ExtensionEventSystem {
constructor() {
this.eventListeners = new Map();
}
// Add event listener
addEventListener(eventName, callback, options = {}) {
if (!this.eventListeners.has(eventName)) {
this.eventListeners.set(eventName, new Set());
}
this.eventListeners.get(eventName).add(callback);
// Return function to remove listener
return () => {
this.removeEventListener(eventName, callback);
};
}
// Remove event listener
removeEventListener(eventName, callback) {
if (this.eventListeners.has(eventName)) {
const listeners = this.eventListeners.get(eventName);
listeners.delete(callback);
if (listeners.size === 0) {
this.eventListeners.delete(eventName);
}
}
}
// Dispatch event
dispatchEvent(eventName, detail = {}) {
if (this.eventListeners.has(eventName)) {
const event = new CustomEvent(eventName, {
bubbles: false,
cancelable: true,
detail
});
const listeners = this.eventListeners.get(eventName);
const promises = [];
listeners.forEach(callback => {
try {
const result = callback(event);
if (result instanceof Promise) {
promises.push(result);
}
} catch (error) {
console.error(`Error in ${eventName} event handler:`, error);
}
});
// Return Promise.all if there are async listeners
if (promises.length > 0) {
return Promise.all(promises);
}
}
return Promise.resolve();
}
}
// Practical application in extension
const eventSystem = new ExtensionEventSystem();
// Register event listener
const removeClickListener = eventSystem.addEventListener('tabClicked', (event) => {
console.log('Tab clicked:', event.detail.tabId);
updateTabHighlight(event.detail.tabId);
});
// Dispatch event
async function handleTabActivation(tabId) {
// Perform synchronous operations...
highlightTab(tabId);
// Dispatch custom event
await eventSystem.dispatchEvent('tabClicked', { tabId });
// Continue with other operations...
}
// Remove event listener
// removeClickListener();
// More complex event system: With event queue and throttling
class AdvancedEventSystem extends ExtensionEventSystem {
constructor() {
super();
this.eventQueue = new Map();
this.throttleTimers = new Map();
}
// Dispatch throttled event
dispatchThrottledEvent(eventName, detail = {}, throttleMs = 100) {
if (!this.throttleTimers.has(eventName)) {
this.throttleTimers.set(eventName, null);
}
if (this.throttleTimers.get(eventName)) {
// If a timer is already running, add event to queue
if (!this.eventQueue.has(eventName)) {
this.eventQueue.set(eventName, []);
}
this.eventQueue.get(eventName).push(detail);
return;
}
// Set throttle timer
this.throttleTimers.set(eventName, setTimeout(async () => {
// Clear timer
this.throttleTimers.set(eventName, null);
// Process queued events
if (this.eventQueue.has(eventName)) {
const queuedDetails = this.eventQueue.get(eventName);
this.eventQueue.delete(eventName);
// Merge all queued event details
const mergedDetail = queuedDetails.reduce((acc, curr) => {
return { ...acc, ...curr };
}, {});
// Dispatch merged event
await super.dispatchEvent(eventName, mergedDetail);
}
}, throttleMs));
// Dispatch current event immediately (if not throttled)
if (!this.throttleTimers.get(eventName)) {
super.dispatchEvent(eventName, detail);
}
}
}
// Use advanced event system
const advancedEventSystem = new AdvancedEventSystem();
// High-frequency event example (e.g., scroll events)
window.addEventListener('scroll', () => {
advancedEventSystem.dispatchThrottledEvent('viewportScrolled', {
scrollY: window.scrollY,
timestamp: Date.now()
}, 200); // Dispatch event at most once every 200ms
});
// Listen to throttled event
advancedEventSystem.addEventListener('viewportScrolled', (event) => {
console.log('Viewport scrolled (throttled):', event.detail.scrollY);
updateLazyLoadedContent(event.detail.scrollY);
});Extension-Specific Event Listening Patterns
Browser extension APIs provide unique event systems that require special handling.
Long-Running Event Listeners
// Manage long-running event listeners
class ExtensionEventListenerManager {
constructor() {
this.listeners = new Map();
this.runtimePort = null;
}
// Initialize communication with the background script
initRuntimeCommunication() {
this.runtimePort = chrome.runtime.connect({ name: 'eventListenerManager' });
this.runtimePort.onMessage.addListener((message) => {
if (message.type === 'EVENT_UPDATE') {
this.dispatchEventToClients(message.eventName, message.data);
}
});
}
// Add tab event listener
addTabListener(eventName, callback) {
const listenerId = `tab_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
const wrappedCallback = (tabId, changeInfo, tab) => {
try {
callback({ tabId, changeInfo, tab });
} catch (error) {
console.error(`Error in ${eventName} listener:`, error);
}
};
chrome.tabs.onUpdated.addListener(wrappedCallback);
this.listeners.set(listenerId, {
type: 'tabs.onUpdated',
callback: wrappedCallback,
originalCallback: callback
});
return listenerId;
}
// Add storage event listener
addStorageListener(callback) {
const listenerId = `storage_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
const wrappedCallback = (changes, areaName) => {
try {
callback({ changes, areaName });
// Notify background script
if (this.runtimePort) {
this.runtimePort.postMessage({
type: 'STORAGE_EVENT',
areaName,
changes
});
}
} catch (error) {
console.error('Error in storage listener:', error);
}
};
chrome.storage.onChanged.addListener(wrappedCallback);
this.listeners.set(listenerId, {
type: 'storage.onChanged',
callback: wrappedCallback,
originalCallback: callback
});
return listenerId;
}
// Remove event listener
removeListener(listenerId) {
if (this.listeners.has(listenerId)) {
const { type, callback } = this.listeners.get(listenerId);
if (type === 'tabs.onUpdated') {
chrome.tabs.onUpdated.removeListener(callback);
} else if (type === 'storage.onChanged') {
chrome.storage.onChanged.removeListener(callback);
}
this.listeners.delete(listenerId);
}
}
// Dispatch event to clients (simplified example)
dispatchEventToClients(eventName, data) {
console.log(`Dispatching event to clients: ${eventName}`, data);
// Actual implementation might use messaging system
}
}
// Practical application in extension
const eventManager = new ExtensionEventListenerManager();
eventManager.initRuntimeCommunication();
// Add multiple event listeners
const tabUpdateListenerId = eventManager.addTabListener('tabUpdated', (eventData) => {
console.log('Tab updated:', eventData.tabId);
if (eventData.changeInfo.status === 'complete') {
updateTabContent(eventData.tabId);
}
});
const storageListenerId = eventManager.addStorageListener((eventData) => {
console.log('Storage changed:', eventData.areaName, eventData.changes);
if (eventData.areaName === 'local' && eventData.changes.userPrefs) {
applyUserPreferences(eventData.changes.userPrefs.newValue);
}
});
// Remove listeners when appropriate (e.g., during extension unload)
// eventManager.removeListener(tabUpdateListenerId);
// eventManager.removeListener(storageListenerId);Cross-Extension Communication Event Patterns
// Implement cross-extension communication event system
class CrossExtensionEventSystem {
constructor() {
this.messageListeners = new Map();
this.portConnections = new Map();
this.initMessageListeners();
}
// Initialize chrome.runtime.onMessage listener
initMessageListeners() {
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === 'EVENT' && this.messageListeners.has(message.eventName)) {
const callbacks = this.messageListeners.get(message.eventName);
const promises = [];
callbacks.forEach(callback => {
try {
const result = callback(message.data, sender);
if (result instanceof Promise) {
promises.push(result);
}
} catch (error) {
console.error(`Error in cross-extension event handler for ${message.eventName}:`, error);
}
});
if (promises.length > 0) {
Promise.all(promises).then(() => sendResponse({ status: 'success' }));
return true; // Keep message channel open for async response
} else {
sendResponse({ status: 'success' });
}
}
return false; // Do not keep message channel open
});
}
// Add cross-extension event listener
addCrossExtensionListener(eventName, callback) {
if (!this.messageListeners.has(eventName)) {
this.messageListeners.set(eventName, new Set());
}
this.messageListeners.get(eventName).add(callback);
// Return function to remove listener
return () => {
this.removeCrossExtensionListener(eventName, callback);
};
}
// Remove cross-extension event listener
removeCrossExtensionListener(eventName, callback) {
if (this.messageListeners.has(eventName)) {
const listeners = this.messageListeners.get(eventName);
listeners.delete(callback);
if (listeners.size === 0) {
this.messageListeners.delete(eventName);
}
}
}
// Send cross-extension event
sendCrossExtensionEvent(eventName, data, targetExtensionId = null) {
return new Promise((resolve, reject) => {
const message = {
type: 'EVENT',
eventName,
data,
timestamp: Date.now()
};
if (targetExtensionId) {
// Send to specific extension
chrome.runtime.sendMessage(targetExtensionId, message, (response) => {
if (chrome.runtime.lastError) {
reject(chrome.runtime.lastError);
} else {
resolve(response);
}
});
} else {
// Broadcast to all extensions listening to this event
// Note: Chrome extension API does not directly support broadcasting
// Simplified to send to self (actual implementation may need shared storage or message relay)
chrome.runtime.sendMessage(message, (response) => {
if (chrome.runtime.lastError) {
reject(chrome.runtime.lastError);
} else {
resolve(response);
}
});
}
});
}
// Establish persistent connection with content script
connectToContentScript(tabId) {
const port = chrome.tabs.connect(tabId, { name: 'eventSystem' });
port.onMessage.addListener((message) => {
if (message.type === 'EVENT' && this.messageListeners.has(message.eventName)) {
const callbacks = this.messageListeners.get(message.eventName);
const promises = [];
callbacks.forEach(callback => {
try {
const result = callback(message.data, { tabId });
if (result instanceof Promise) {
promises.push(result);
}
} catch (error) {
console.error(`Error in content script event handler for ${message.eventName}:`, error);
}
});
if (promises.length > 0) {
Promise.all(promises).catch(error => {
console.error('Error in Promise.all for content script events:', error);
});
}
}
});
port.onDisconnect.addListener(() => {
// Clean up related resources
console.log('Content script connection disconnected:', tabId);
});
this.portConnections.set(tabId, port);
return port;
}
// Send event to content script
sendEventToContentScript(tabId, eventName, data) {
if (this.portConnections.has(tabId)) {
const port = this.portConnections.get(tabId);
port.postMessage({
type: 'EVENT',
eventName,
data
});
return Promise.resolve();
} else {
return Promise.reject(new Error(`No connection to tab ${tabId}`));
}
}
}
// Practical application in extension
const crossEventSystem = new CrossExtensionEventSystem();
// Add cross-extension event listener
const analyticsListener = crossEventSystem.addCrossExtensionListener('analyticsEvent', (data, sender) => {
console.log('Received analytics event:', data, 'from:', sender);
trackEvent(data.eventName, data.properties);
});
// Send cross-extension event
async function reportUserAction(eventName, properties) {
try {
await crossEventSystem.sendCrossExtensionEvent('userAction', {
eventName,
properties,
timestamp: Date.now()
});
console.log('User action event sent');
} catch (error) {
console.error('Failed to send user action event:', error);
}
}
// Connect to content script and listen for events
chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
if (changeInfo.status === 'complete' && tab.url.startsWith('https://example.com')) {
const port = crossEventSystem.connectToContentScript(tabId);
// Listen for events from content script
port.onMessage.addListener((message) => {
if (message.type === 'EVENT' && message.eventName === 'contentScriptReady') {
console.log('Content script ready:', tabId);
sendInitialData(tabId);
}
});
}
});
// More complex cross-extension communication pattern: Request-response
class RequestResponseEventSystem extends CrossExtensionEventSystem {
constructor() {
super();
this.pendingRequests = new Map();
this.requestIdCounter = 0;
}
// Send request and wait for response
sendRequest(eventName, data, targetExtensionId = null, timeoutMs = 5000) {
return new Promise((resolve, reject) => {
const requestId = `req_${++this.requestIdCounter}`;
const timeoutId = setTimeout(() => {
this.pendingRequests.delete(requestId);
reject(new Error(`Request timed out: ${eventName}`));
}, timeoutMs);
this.pendingRequests.set(requestId, { resolve, reject, timeoutId });
const message = {
type: 'REQUEST',
requestId,
eventName,
data,
timestamp: Date.now()
};
if (targetExtensionId) {
chrome.runtime.sendMessage(targetExtensionId, message, (response) => {
// This callback only triggers on send failure
if (chrome.runtime.lastError) {
this.handleRequestTimeout(requestId);
reject(chrome.runtime.lastError);
}
});
} else {
// Broadcast request (simplified implementation)
chrome.runtime.sendMessage(message, (response) => {
if (chrome.runtime.lastError) {
this.handleRequestTimeout(requestId);
reject(chrome.runtime.lastError);
}
});
}
});
}
// Handle incoming request
handleIncomingRequest(requestId, eventName, data, sender) {
// This method should be called by specific event handlers
// Example framework only
console.log('Received request:', requestId, eventName, 'from:', sender);
// Simulate async processing
setTimeout(() => {
const response = {
requestId,
status: 'success',
data: { result: 'Processing complete' }
};
// Send response
chrome.runtime.sendMessage(sender.id, {
type: 'RESPONSE',
requestId,
response
});
}, 1000);
}
// Handle incoming response
handleIncomingResponse(requestId, response) {
if (this.pendingRequests.has(requestId)) {
const { resolve, reject, timeoutId } = this.pendingRequests.get(requestId);
clearTimeout(timeoutId);
this.pendingRequests.delete(requestId);
if (response.status === 'success') {
resolve(response.data);
} else {
reject(new Error(response.error || 'Unknown error'));
}
}
}
// Handle request timeout
handleRequestTimeout(requestId) {
if (this.pendingRequests.has(requestId)) {
const { reject, timeoutId } = this.pendingRequests.get(requestId);
clearTimeout(timeoutId);
this.pendingRequests.delete(requestId);
reject(new Error('Request timed out'));
}
}
}
// Use request-response event system
const requestEventSystem = new RequestResponseEventSystem();
// Send request example
async function fetchRemoteData(dataType, params) {
try {
const response = await requestEventSystem.sendRequest('fetchData', {
dataType,
params
}, 'other-extension-id', 10000);
console.log('Received remote data:', response);
return response;
} catch (error) {
console.error('Failed to fetch remote data:', error);
return null;
}
}
// Handle incoming requests (needs to be called in extension’s message listener)
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
if (message.type === 'REQUEST') {
requestEventSystem.handleIncomingRequest(
message.requestId,
message.eventName,
message.data,
sender
);
// Note: Do not call sendResponse directly, as response will be sent via event system
return true; // Keep message channel open (though response won’t happen here)
} else if (message.type === 'RESPONSE') {
requestEventSystem.handleIncomingResponse(message.requestId, message.response);
}
});



