tessl/npm-webrtc-adapter

A shim to insulate apps from WebRTC spec changes and browser prefix differences

Overall
score

98%

Overview

Eval results

Files

Factory and Configuration

Name: tessl/npm-webrtc-adapter
Author: tessl

The adapter factory provides fine-grained control over which browser shims are applied, allowing developers to create customized adapter instances for specific use cases or performance optimization.

Capabilities

Adapter Factory Function

Creates adapter instances with configurable shim options.

/**
 * Creates an adapter instance with configurable shim options
 * @param window - Object containing window reference (optional)
 * @param options - Configuration options for enabling/disabling shims
 * @returns Configured adapter instance
 */
function adapterFactory(
  {window}?: {window?: Window}, 
  options?: {
    shimChrome?: boolean;
    shimFirefox?: boolean; 
    shimSafari?: boolean;
  }
): IAdapter;

Default Options:

{
  shimChrome: true,
  shimFirefox: true,
  shimSafari: true
}

Usage Examples:

import { adapterFactory } from 'webrtc-adapter/src/js/adapter_factory.js';

// Default configuration (all shims enabled)
const adapter = adapterFactory({window});

// Disable Safari shims for performance
const chromeFirefoxAdapter = adapterFactory({window}, {
  shimChrome: true,
  shimFirefox: true,
  shimSafari: false
});

// Chrome-only adapter
const chromeOnlyAdapter = adapterFactory({window}, {
  shimChrome: true,
  shimFirefox: false,
  shimSafari: false
});

// Custom window object (useful for Node.js or testing environments)
const serverAdapter = adapterFactory({window: undefined}, {
  shimChrome: false,
  shimFirefox: false,
  shimSafari: false
});

// Testing with mock window
const mockWindow = { RTCPeerConnection: MockRTCPeerConnection };
const testAdapter = adapterFactory({window: mockWindow});

Adapter Interface

The complete interface returned by the factory function.

interface IAdapter {
  /** Browser detection information */
  browserDetails: IBrowserDetails;
  /** Common shims applied to all browsers */
  commonShim: ICommonShim;
  /** Browser-specific shims (only populated for detected browser) */
  browserShim: IChromeShim | IFirefoxShim | ISafariShim | undefined;
  /** Version extraction utility function */
  extractVersion: (uastring: string, expr: string, pos: number) => number;
  /** Logging control function */
  disableLog: (disable: boolean) => string | Error;
  /** Deprecation warning control function */
  disableWarnings: (disable: boolean) => string | Error;
  /** SDP utilities from sdp package dependency */
  sdp: typeof SDPUtils;
}

Configuration Behavior

The factory applies shims based on browser detection and configuration:

When shimChrome: true and Chrome detected:

Applies all Chrome-specific shims
Sets adapter.browserShim to Chrome shim interface
Logs "adapter.js shimming chrome."

When shimFirefox: true and Firefox detected:

Applies all Firefox-specific shims
Sets adapter.browserShim to Firefox shim interface
Logs "adapter.js shimming firefox."

When shimSafari: true and Safari detected:

Applies all Safari-specific shims
Sets adapter.browserShim to Safari shim interface
Logs "adapter.js shimming safari."

When shims are disabled:

Logs appropriate warning message
Returns minimal adapter with only browser detection
adapter.browserShim remains undefined

Advanced Configuration Patterns

Conditional Shim Loading

import { adapterFactory } from 'webrtc-adapter/src/js/adapter_factory.js';

// Load shims based on environment
const isInstrumented = process.env.NODE_ENV === 'development';
const adapter = adapterFactory({window}, {
  shimChrome: !isInstrumented, // Disable for debugging
  shimFirefox: true,
  shimSafari: true
});

Library Integration

// Create adapter for specific library requirements
function createWebRTCAdapter(targetBrowser) {
  const options = {
    shimChrome: targetBrowser === 'chrome' || targetBrowser === 'all',
    shimFirefox: targetBrowser === 'firefox' || targetBrowser === 'all',
    shimSafari: targetBrowser === 'safari' || targetBrowser === 'all'
  };
  
  return adapterFactory({window}, options);
}

const adapter = createWebRTCAdapter('chrome'); // Chrome-only shims

Server-Side Usage

// Node.js environment without window object
const serverAdapter = adapterFactory({window: undefined}, {
  shimChrome: false,
  shimFirefox: false,
  shimSafari: false
});

// Access utilities without browser shims
const version = serverAdapter.extractVersion(userAgentString, pattern, position);

Performance Considerations

Selective Shimming: Disabling unused browser shims reduces bundle size and initialization time
Memory Usage: Each adapter instance maintains separate shim state
Browser Detection: Performed once during adapter creation
Lazy Loading: Shims are only applied when the corresponding browser is detected

Install with Tessl CLI

npx tessl i tessl/npm-webrtc-adapter