@aspectly/transports 0.1.0

package/src/TransportRegistry.test.ts

@@ -0,0 +1,345 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { TransportRegistry, detectTransport, registerTransport } from './TransportRegistry';
+import type { TransportDetector } from './types';
+import { NullTransport } from './transports/NullTransport';
+
+describe('TransportRegistry', () => {
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    // Reset registry to clean state before each test
+    TransportRegistry.reset();
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    TransportRegistry.reset();
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should have built-in detectors registered by default', () => {
+    const detectors = TransportRegistry.getDetectors();
+    expect(detectors.length).toBe(5);
+
+    const names = detectors.map(d => d.name);
+    expect(names).toContain('cefsharp');
+    expect(names).toContain('react-native');
+    expect(names).toContain('iframe');
+    expect(names).toContain('window');
+    expect(names).toContain('postmessage');
+  });
+
+  it('should sort detectors by priority (descending)', () => {
+    const detectors = TransportRegistry.getDetectors();
+
+    // Should be sorted: cefsharp (100), react-native (90), iframe (80), window (70), postmessage (10)
+    expect(detectors[0].name).toBe('cefsharp');
+    expect(detectors[0].priority).toBe(100);
+    expect(detectors[1].name).toBe('react-native');
+    expect(detectors[1].priority).toBe(90);
+    expect(detectors[2].name).toBe('iframe');
+    expect(detectors[2].priority).toBe(80);
+    expect(detectors[3].name).toBe('window');
+    expect(detectors[3].priority).toBe(70);
+    expect(detectors[4].name).toBe('postmessage');
+    expect(detectors[4].priority).toBe(10);
+  });
+
+  it('should register new detector and sort by priority', () => {
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 95,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(customDetector);
+    const detectors = TransportRegistry.getDetectors();
+
+    expect(detectors.length).toBe(6);
+    // Should be: cefsharp (100), custom (95), react-native (90), iframe (80), window (70), postmessage (10)
+    expect(detectors[1].name).toBe('custom');
+    expect(detectors[1].priority).toBe(95);
+  });
+
+  it('should replace existing detector with same name', () => {
+    const customDetector1: TransportDetector = {
+      name: 'custom',
+      priority: 50,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    const customDetector2: TransportDetector = {
+      name: 'custom',
+      priority: 110,
+      detect: () => true,
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(customDetector1);
+    expect(TransportRegistry.getDetectors().length).toBe(6);
+
+    TransportRegistry.register(customDetector2);
+    expect(TransportRegistry.getDetectors().length).toBe(6); // Still 6, not 7
+
+    const detectors = TransportRegistry.getDetectors();
+    const customDetector = detectors.find(d => d.name === 'custom');
+    expect(customDetector?.priority).toBe(110); // Updated priority
+  });
+
+  it('should unregister detector by name', () => {
+    TransportRegistry.unregister('iframe');
+    const detectors = TransportRegistry.getDetectors();
+
+    expect(detectors.length).toBe(4);
+    expect(detectors.map(d => d.name)).not.toContain('iframe');
+  });
+
+  it('should return readonly array from getDetectors', () => {
+    const detectors = TransportRegistry.getDetectors();
+    expect(Array.isArray(detectors)).toBe(true);
+    // TypeScript enforces readonly, but we can verify it's an array
+    expect(detectors.length).toBeGreaterThan(0);
+  });
+
+  it('should detect and return first matching transport', () => {
+    // Create a detector that always matches
+    const mockTransport = new NullTransport();
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 200, // Highest priority
+      detect: () => true,
+      createTransport: () => mockTransport,
+    };
+
+    TransportRegistry.register(customDetector);
+    const transport = TransportRegistry.detect();
+
+    expect(transport).toBe(mockTransport);
+    expect(transport.name).toBe('null'); // NullTransport
+  });
+
+  it('should cache detection result', () => {
+    const createTransportMock = vi.fn(() => new NullTransport());
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 200,
+      detect: () => true,
+      createTransport: createTransportMock,
+    };
+
+    TransportRegistry.register(customDetector);
+
+    const transport1 = TransportRegistry.detect();
+    const transport2 = TransportRegistry.detect();
+
+    expect(transport1).toBe(transport2); // Same instance
+    expect(createTransportMock).toHaveBeenCalledTimes(1); // Only called once
+  });
+
+  it('should force re-detection when forceRedetect is true', () => {
+    const createTransportMock = vi.fn(() => new NullTransport());
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 200,
+      detect: () => true,
+      createTransport: createTransportMock,
+    };
+
+    TransportRegistry.register(customDetector);
+
+    TransportRegistry.detect(); // First call
+    TransportRegistry.detect(true); // Force re-detect
+
+    expect(createTransportMock).toHaveBeenCalledTimes(2); // Called twice
+  });
+
+  it('should return NullTransport when no detector matches', () => {
+    // Unregister all built-in detectors
+    TransportRegistry.unregister('cefsharp');
+    TransportRegistry.unregister('react-native');
+    TransportRegistry.unregister('iframe');
+    TransportRegistry.unregister('postmessage');
+
+    const transport = TransportRegistry.detect();
+
+    expect(transport).toBeInstanceOf(NullTransport);
+    expect(transport.name).toBe('null');
+  });
+
+  it('should handle errors in detector gracefully', () => {
+    const faultyDetector: TransportDetector = {
+      name: 'faulty',
+      priority: 200,
+      detect: () => {
+        throw new Error('Detector error');
+      },
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(faultyDetector);
+
+    // Should not throw, should warn and continue
+    const transport = TransportRegistry.detect();
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[TransportRegistry] Detector "faulty" threw an error:',
+      expect.any(Error)
+    );
+    // Should fall back to next detector or NullTransport
+    expect(transport).toBeDefined();
+  });
+
+  it('should clear cached transport when clearCache is called', () => {
+    const createTransportMock = vi.fn(() => new NullTransport());
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 200,
+      detect: () => true,
+      createTransport: createTransportMock,
+    };
+
+    TransportRegistry.register(customDetector);
+
+    TransportRegistry.detect(); // First call, caches result
+    TransportRegistry.clearCache();
+    TransportRegistry.detect(); // Second call after clearing cache
+
+    expect(createTransportMock).toHaveBeenCalledTimes(2); // Called twice
+  });
+
+  it('should clear cache when registering new detector', () => {
+    const detector1: TransportDetector = {
+      name: 'detector1',
+      priority: 200,
+      detect: () => true,
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(detector1);
+    TransportRegistry.detect(); // Cache result
+
+    const detector2: TransportDetector = {
+      name: 'detector2',
+      priority: 150,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(detector2); // Should clear cache
+
+    // Cache should be cleared, so next detect() will re-run
+    // We can verify this indirectly by checking that detection happens again
+    expect(() => TransportRegistry.detect()).not.toThrow();
+  });
+
+  it('should clear cache when unregistering detector', () => {
+    TransportRegistry.detect(); // Cache result
+    TransportRegistry.unregister('iframe'); // Should clear cache
+
+    // Cache should be cleared
+    expect(() => TransportRegistry.detect()).not.toThrow();
+  });
+
+  it('should reset to built-in detectors only', () => {
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 200,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    TransportRegistry.register(customDetector);
+    expect(TransportRegistry.getDetectors().length).toBe(6);
+
+    TransportRegistry.reset();
+    const detectors = TransportRegistry.getDetectors();
+
+    expect(detectors.length).toBe(5);
+    expect(detectors.map(d => d.name)).toEqual(['cefsharp', 'react-native', 'iframe', 'window', 'postmessage']);
+  });
+
+  it('should clear cache when reset is called', () => {
+    TransportRegistry.detect(); // Cache result
+    TransportRegistry.reset(); // Should clear cache
+
+    expect(() => TransportRegistry.detect()).not.toThrow();
+  });
+});
+
+describe('detectTransport convenience function', () => {
+  beforeEach(() => {
+    TransportRegistry.reset();
+  });
+
+  afterEach(() => {
+    TransportRegistry.reset();
+  });
+
+  it('should call TransportRegistry.detect()', () => {
+    const detectSpy = vi.spyOn(TransportRegistry, 'detect');
+
+    detectTransport();
+
+    expect(detectSpy).toHaveBeenCalledWith(false);
+    detectSpy.mockRestore();
+  });
+
+  it('should pass forceRedetect parameter', () => {
+    const detectSpy = vi.spyOn(TransportRegistry, 'detect');
+
+    detectTransport(true);
+
+    expect(detectSpy).toHaveBeenCalledWith(true);
+    detectSpy.mockRestore();
+  });
+
+  it('should return a Transport instance', () => {
+    const transport = detectTransport();
+    expect(transport).toBeDefined();
+    expect(typeof transport.name).toBe('string');
+    expect(typeof transport.isAvailable).toBe('function');
+    expect(typeof transport.send).toBe('function');
+    expect(typeof transport.subscribe).toBe('function');
+  });
+});
+
+describe('registerTransport convenience function', () => {
+  beforeEach(() => {
+    TransportRegistry.reset();
+  });
+
+  afterEach(() => {
+    TransportRegistry.reset();
+  });
+
+  it('should call TransportRegistry.register()', () => {
+    const registerSpy = vi.spyOn(TransportRegistry, 'register');
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 100,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    registerTransport(customDetector);
+
+    expect(registerSpy).toHaveBeenCalledWith(customDetector);
+    registerSpy.mockRestore();
+  });
+
+  it('should actually register the detector', () => {
+    const customDetector: TransportDetector = {
+      name: 'custom',
+      priority: 100,
+      detect: () => false,
+      createTransport: () => new NullTransport(),
+    };
+
+    registerTransport(customDetector);
+
+    const detectors = TransportRegistry.getDetectors();
+    expect(detectors.map(d => d.name)).toContain('custom');
+  });
+});

package/src/TransportRegistry.ts

@@ -0,0 +1,120 @@
+import type { Transport, TransportDetector } from './types';
+import { cefSharpDetector } from './transports/CefSharpTransport';
+import { reactNativeDetector } from './transports/ReactNativeTransport';
+import { iframeDetector } from './transports/IframeTransport';
+import { windowDetector } from './transports/WindowTransport';
+import { postMessageDetector } from './transports/PostMessageTransport';
+import { NullTransport } from './transports/NullTransport';
+
+/**
+ * Registry for transport detectors
+ * Manages auto-detection of the current environment
+ */
+class TransportRegistryClass {
+  private detectors: TransportDetector[] = [];
+  private cachedTransport: Transport | null = null;
+
+  constructor() {
+    // Register built-in detectors
+    this.register(cefSharpDetector);
+    this.register(reactNativeDetector);
+    this.register(iframeDetector);
+    this.register(windowDetector);
+    this.register(postMessageDetector);
+  }
+
+  /**
+   * Register a custom transport detector
+   * @param detector The detector to register
+   */
+  register(detector: TransportDetector): void {
+    // Remove existing detector with same name
+    this.detectors = this.detectors.filter(d => d.name !== detector.name);
+    this.detectors.push(detector);
+    // Sort by priority (descending)
+    this.detectors.sort((a, b) => b.priority - a.priority);
+    // Clear cache when detectors change
+    this.cachedTransport = null;
+  }
+
+  /**
+   * Unregister a transport detector by name
+   * @param name Name of the detector to remove
+   */
+  unregister(name: string): void {
+    this.detectors = this.detectors.filter(d => d.name !== name);
+    this.cachedTransport = null;
+  }
+
+  /**
+   * Get all registered detectors
+   */
+  getDetectors(): readonly TransportDetector[] {
+    return this.detectors;
+  }
+
+  /**
+   * Detect and return the appropriate transport for the current environment
+   * Results are cached for performance
+   * @param forceRedetect Force re-detection (ignores cache)
+   */
+  detect(forceRedetect = false): Transport {
+    if (this.cachedTransport && !forceRedetect) {
+      return this.cachedTransport;
+    }
+
+    for (const detector of this.detectors) {
+      try {
+        if (detector.detect()) {
+          this.cachedTransport = detector.createTransport();
+          return this.cachedTransport;
+        }
+      } catch (error) {
+        console.warn(`[TransportRegistry] Detector "${detector.name}" threw an error:`, error);
+      }
+    }
+
+    // No transport detected, return NullTransport
+    this.cachedTransport = new NullTransport();
+    return this.cachedTransport;
+  }
+
+  /**
+   * Clear the cached transport (useful for testing)
+   */
+  clearCache(): void {
+    this.cachedTransport = null;
+  }
+
+  /**
+   * Reset registry to default state (built-in detectors only)
+   */
+  reset(): void {
+    this.detectors = [];
+    this.cachedTransport = null;
+    this.register(cefSharpDetector);
+    this.register(reactNativeDetector);
+    this.register(iframeDetector);
+    this.register(windowDetector);
+    this.register(postMessageDetector);
+  }
+}
+
+/**
+ * Global transport registry instance
+ */
+export const TransportRegistry = new TransportRegistryClass();
+
+/**
+ * Convenience function to detect transport
+ */
+export const detectTransport = (forceRedetect = false): Transport => {
+  return TransportRegistry.detect(forceRedetect);
+};
+
+/**
+ * Convenience function to register a custom detector
+ */
+export const registerTransport = (detector: TransportDetector): void => {
+  TransportRegistry.register(detector);
+};

package/src/cefsharp.ts

@@ -0,0 +1,3 @@
+// CefSharp transport - standalone entry point
+export { CefSharpTransport, cefSharpDetector } from './transports/CefSharpTransport';
+export type { Transport, TransportListener, TransportUnsubscribe } from './types';

package/src/iframe.ts

@@ -0,0 +1,3 @@
+// Iframe transport - standalone entry point
+export { IframeTransport, iframeDetector } from './transports/IframeTransport';
+export type { Transport, TransportListener, TransportUnsubscribe } from './types';

package/src/index.ts

@@ -0,0 +1,26 @@
+// Types
+export type {
+  Transport,
+  TransportListener,
+  TransportUnsubscribe,
+  TransportFactory,
+  TransportDetector,
+} from './types';
+
+// Base class
+export { BaseTransport } from './BaseTransport';
+
+// Transports
+export { CefSharpTransport, cefSharpDetector } from './transports/CefSharpTransport';
+export { ReactNativeTransport, reactNativeDetector } from './transports/ReactNativeTransport';
+export { IframeTransport, iframeDetector } from './transports/IframeTransport';
+export { WindowTransport, windowDetector } from './transports/WindowTransport';
+export { PostMessageTransport, postMessageDetector } from './transports/PostMessageTransport';
+export { NullTransport } from './transports/NullTransport';
+
+// Registry and auto-detection
+export {
+  TransportRegistry,
+  detectTransport,
+  registerTransport,
+} from './TransportRegistry';

package/src/react-native.ts

@@ -0,0 +1,3 @@
+// React Native transport - standalone entry point
+export { ReactNativeTransport, reactNativeDetector } from './transports/ReactNativeTransport';
+export type { Transport, TransportListener, TransportUnsubscribe } from './types';

package/src/transports/CefSharpTransport.test.ts

@@ -0,0 +1,187 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { CefSharpTransport, cefSharpDetector } from './CefSharpTransport';
+
+interface CefSharpWindow extends Window {
+  CefSharp?: {
+    PostMessage: (message: string) => void;
+    BindObjectAsync: (...args: unknown[]) => Promise<void>;
+  };
+}
+
+const testWindow = window as CefSharpWindow;
+
+describe('CefSharpTransport', () => {
+  let transport: CefSharpTransport;
+  let originalCefSharp: typeof testWindow.CefSharp;
+  let consoleWarnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    transport = new CefSharpTransport();
+    originalCefSharp = testWindow.CefSharp;
+    consoleWarnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    testWindow.CefSharp = originalCefSharp;
+    consoleWarnSpy.mockRestore();
+  });
+
+  it('should have name property equal to "cefsharp"', () => {
+    expect(transport.name).toBe('cefsharp');
+  });
+
+  it('should return false when CefSharp not present', () => {
+    testWindow.CefSharp = undefined;
+    expect(transport.isAvailable()).toBe(false);
+  });
+
+  it('should return false when CefSharp.PostMessage not a function', () => {
+    testWindow.CefSharp = {} as any;
+    expect(transport.isAvailable()).toBe(false);
+  });
+
+  it('should return true when CefSharp.PostMessage exists', () => {
+    testWindow.CefSharp = {
+      PostMessage: vi.fn(),
+      BindObjectAsync: vi.fn(),
+    };
+    expect(transport.isAvailable()).toBe(true);
+  });
+
+  it('should call CefSharp.PostMessage with message when sending', () => {
+    const mockPostMessage = vi.fn();
+    testWindow.CefSharp = {
+      PostMessage: mockPostMessage,
+      BindObjectAsync: vi.fn(),
+    };
+
+    transport.send('test message');
+
+    expect(mockPostMessage).toHaveBeenCalledWith('test message');
+    expect(mockPostMessage).toHaveBeenCalledTimes(1);
+  });
+
+  it('should warn when CefSharp not available during send', () => {
+    testWindow.CefSharp = undefined;
+
+    transport.send('test message');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[CefSharpTransport] CefSharp.PostMessage is not available'
+    );
+  });
+
+  it('should warn when CefSharp.PostMessage not available during send', () => {
+    testWindow.CefSharp = {} as any;
+
+    transport.send('test message');
+
+    expect(consoleWarnSpy).toHaveBeenCalledWith(
+      '[CefSharpTransport] CefSharp.PostMessage is not available'
+    );
+  });
+
+  it('should add message event listener when subscribing', () => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
+    const listener = vi.fn();
+
+    transport.subscribe(listener);
+
+    expect(addEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    addEventListenerSpy.mockRestore();
+  });
+
+  it('should call listener with string data from message event', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event = new MessageEvent('message', { data: 'test data' });
+    window.dispatchEvent(event);
+
+    expect(listener).toHaveBeenCalledWith('test data');
+  });
+
+  it('should not call listener with non-string data', () => {
+    const listener = vi.fn();
+    transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 123 });
+    const event2 = new MessageEvent('message', { data: { foo: 'bar' } });
+    const event3 = new MessageEvent('message', { data: null });
+
+    window.dispatchEvent(event1);
+    window.dispatchEvent(event2);
+    window.dispatchEvent(event3);
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('should remove event listener when cleanup function is called', () => {
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+    const listener = vi.fn();
+
+    const unsubscribe = transport.subscribe(listener);
+    unsubscribe();
+
+    expect(removeEventListenerSpy).toHaveBeenCalledWith('message', expect.any(Function));
+
+    removeEventListenerSpy.mockRestore();
+  });
+
+  it('should not receive messages after unsubscribing', () => {
+    const listener = vi.fn();
+    const unsubscribe = transport.subscribe(listener);
+
+    const event1 = new MessageEvent('message', { data: 'before unsubscribe' });
+    window.dispatchEvent(event1);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unsubscribe();
+
+    const event2 = new MessageEvent('message', { data: 'after unsubscribe' });
+    window.dispatchEvent(event2);
+
+    expect(listener).toHaveBeenCalledTimes(1); // Still 1, not 2
+  });
+});
+
+describe('cefSharpDetector', () => {
+  let originalCefSharp: typeof testWindow.CefSharp;
+
+  beforeEach(() => {
+    originalCefSharp = testWindow.CefSharp;
+  });
+
+  afterEach(() => {
+    testWindow.CefSharp = originalCefSharp;
+  });
+
+  it('should have name property equal to "cefsharp"', () => {
+    expect(cefSharpDetector.name).toBe('cefsharp');
+  });
+
+  it('should have priority of 100', () => {
+    expect(cefSharpDetector.priority).toBe(100);
+  });
+
+  it('should detect() return false when CefSharp not present', () => {
+    testWindow.CefSharp = undefined;
+    expect(cefSharpDetector.detect()).toBe(false);
+  });
+
+  it('should detect() return true when CefSharp.PostMessage exists', () => {
+    testWindow.CefSharp = {
+      PostMessage: vi.fn(),
+      BindObjectAsync: vi.fn(),
+    };
+    expect(cefSharpDetector.detect()).toBe(true);
+  });
+
+  it('should createTransport() return CefSharpTransport instance', () => {
+    const transport = cefSharpDetector.createTransport();
+    expect(transport).toBeInstanceOf(CefSharpTransport);
+    expect(transport.name).toBe('cefsharp');
+  });
+});