@aspectly/core 0.1.0

package/src/BridgeBase.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { BridgeBase } from './BridgeBase';
+import { BridgeInternal } from './BridgeInternal';
+
+describe('BridgeBase', () => {
+  let mockBridge: BridgeInternal;
+  let bridgeBase: BridgeBase;
+
+  beforeEach(() => {
+    mockBridge = {
+      supports: vi.fn().mockReturnValue(true),
+      isAvailable: vi.fn().mockReturnValue(true),
+      send: vi.fn().mockResolvedValue({ result: 'value' }),
+      subscribe: vi.fn().mockReturnValue(1),
+      unsubscribe: vi.fn(),
+      init: vi.fn().mockResolvedValue(true),
+    } as unknown as BridgeInternal;
+
+    bridgeBase = new BridgeBase(mockBridge);
+  });
+
+  describe('supports', () => {
+    it('should delegate to internal bridge', () => {
+      bridgeBase.supports('testMethod');
+
+      expect(mockBridge.supports).toHaveBeenCalledWith('testMethod');
+    });
+
+    it('should return the result from internal bridge', () => {
+      (mockBridge.supports as ReturnType<typeof vi.fn>).mockReturnValue(false);
+
+      expect(bridgeBase.supports('unknown')).toBe(false);
+    });
+  });
+
+  describe('isAvailable', () => {
+    it('should delegate to internal bridge', () => {
+      bridgeBase.isAvailable();
+
+      expect(mockBridge.isAvailable).toHaveBeenCalled();
+    });
+
+    it('should return the result from internal bridge', () => {
+      (mockBridge.isAvailable as ReturnType<typeof vi.fn>).mockReturnValue(false);
+
+      expect(bridgeBase.isAvailable()).toBe(false);
+    });
+  });
+
+  describe('send', () => {
+    it('should delegate to internal bridge with method and params', async () => {
+      await bridgeBase.send('testMethod', { foo: 'bar' });
+
+      expect(mockBridge.send).toHaveBeenCalledWith('testMethod', { foo: 'bar' });
+    });
+
+    it('should use empty object as default params', async () => {
+      await bridgeBase.send('testMethod');
+
+      expect(mockBridge.send).toHaveBeenCalledWith('testMethod', {});
+    });
+
+    it('should return the result from internal bridge', async () => {
+      (mockBridge.send as ReturnType<typeof vi.fn>).mockResolvedValue({
+        message: 'Hello',
+      });
+
+      const result = await bridgeBase.send<{ message: string }>('greet');
+
+      expect(result).toEqual({ message: 'Hello' });
+    });
+
+    it('should propagate errors from internal bridge', async () => {
+      const error = { error_type: 'REJECTED', error_message: 'Failed' };
+      (mockBridge.send as ReturnType<typeof vi.fn>).mockRejectedValue(error);
+
+      await expect(bridgeBase.send('failing')).rejects.toEqual(error);
+    });
+  });
+
+  describe('subscribe', () => {
+    it('should delegate to internal bridge', () => {
+      const listener = vi.fn();
+      bridgeBase.subscribe(listener);
+
+      expect(mockBridge.subscribe).toHaveBeenCalledWith(listener);
+    });
+
+    it('should return subscription index', () => {
+      (mockBridge.subscribe as ReturnType<typeof vi.fn>).mockReturnValue(5);
+
+      const result = bridgeBase.subscribe(vi.fn());
+
+      expect(result).toBe(5);
+    });
+  });
+
+  describe('unsubscribe', () => {
+    it('should delegate to internal bridge', () => {
+      const listener = vi.fn();
+      bridgeBase.unsubscribe(listener);
+
+      expect(mockBridge.unsubscribe).toHaveBeenCalledWith(listener);
+    });
+  });
+
+  describe('init', () => {
+    it('should delegate to internal bridge with handlers', async () => {
+      const handlers = {
+        greet: async () => ({ message: 'hello' }),
+      };
+
+      await bridgeBase.init(handlers);
+
+      expect(mockBridge.init).toHaveBeenCalledWith(handlers);
+    });
+
+    it('should work without handlers', async () => {
+      await bridgeBase.init();
+
+      expect(mockBridge.init).toHaveBeenCalledWith(undefined);
+    });
+
+    it('should return the result from internal bridge', async () => {
+      (mockBridge.init as ReturnType<typeof vi.fn>).mockResolvedValue(false);
+
+      const result = await bridgeBase.init();
+
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/BridgeBase.ts

@@ -0,0 +1,63 @@
+import type { BridgeHandlers, BridgeListener } from './types';
+import type { BridgeInternal } from './BridgeInternal';
+
+/**
+ * BridgeBase provides the public API for bridge communication.
+ * It wraps BridgeInternal and exposes a clean interface for consumers.
+ */
+export class BridgeBase {
+  protected bridge: BridgeInternal;
+
+  constructor(bridge: BridgeInternal) {
+    this.bridge = bridge;
+  }
+
+  /**
+   * Check if a method is supported by the other side
+   * @param method Method name to check
+   */
+  public supports = (method: string): boolean => this.bridge.supports(method);
+
+  /**
+   * Check if the bridge is available (initialized)
+   */
+  public isAvailable = (): boolean => this.bridge.isAvailable();
+
+  /**
+   * Send a request to invoke a method on the other side
+   * @param method Method name to invoke
+   * @param params Parameters to pass
+   * @returns Promise resolving with the result
+   */
+  public send = <TResult = unknown>(
+    method: string,
+    params: object = {}
+  ): Promise<TResult> => {
+    return this.bridge.send<TResult>(method, params);
+  };
+
+  /**
+   * Subscribe to all result events
+   * @param listener Callback for result events
+   * @returns Subscription index
+   */
+  public subscribe = (listener: BridgeListener): number => {
+    return this.bridge.subscribe(listener);
+  };
+
+  /**
+   * Unsubscribe from result events
+   * @param listener The listener to remove
+   */
+  public unsubscribe = (listener: BridgeListener): void => {
+    return this.bridge.unsubscribe(listener);
+  };
+
+  /**
+   * Initialize the bridge with handlers
+   * @param handlers Map of method names to handler functions
+   * @returns Promise resolving when initialization is complete
+   */
+  public init = (handlers?: BridgeHandlers): Promise<boolean> =>
+    this.bridge.init(handlers);
+}

package/src/BridgeCore.test.ts

@@ -0,0 +1,254 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { BridgeCore } from './BridgeCore';
+
+describe('BridgeCore', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('wrapBridgeEvent', () => {
+    it('should wrap an event in the bridge protocol format', () => {
+      const event = { method: 'test', params: { foo: 'bar' } };
+      const wrapped = BridgeCore.wrapBridgeEvent(event);
+
+      expect(typeof wrapped).toBe('string');
+      const parsed = JSON.parse(wrapped);
+      expect(parsed.type).toBe('BridgeEvent');
+      expect(parsed.event).toEqual(event);
+    });
+
+    it('should handle complex nested objects', () => {
+      const event = {
+        method: 'test',
+        params: {
+          nested: { deep: { value: 123 } },
+          array: [1, 2, 3],
+        },
+      };
+      const wrapped = BridgeCore.wrapBridgeEvent(event);
+      const parsed = JSON.parse(wrapped);
+      expect(parsed.event).toEqual(event);
+    });
+  });
+
+  describe('wrapListener', () => {
+    it('should parse valid bridge events', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+      const event = { method: 'test' };
+      const data = JSON.stringify({ type: 'BridgeEvent', event });
+
+      wrappedListener(data);
+
+      expect(listener).toHaveBeenCalledWith(event);
+    });
+
+    it('should ignore non-string data', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+
+      wrappedListener(undefined);
+      wrappedListener(123 as unknown as string);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should ignore empty strings', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+
+      wrappedListener('');
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should handle iOS wrapped JSON (with single quotes)', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+      const event = { method: 'test' };
+      const data = `'${JSON.stringify({ type: 'BridgeEvent', event })}'`;
+
+      wrappedListener(data);
+
+      expect(listener).toHaveBeenCalledWith(event);
+    });
+
+    it('should ignore non-JSON data', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+
+      wrappedListener('not json');
+      wrappedListener('[1, 2, 3]');
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should ignore events with wrong type', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+      const data = JSON.stringify({ type: 'WrongType', event: {} });
+
+      wrappedListener(data);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it('should handle invalid JSON gracefully', () => {
+      const listener = vi.fn();
+      const wrappedListener = BridgeCore.wrapListener(listener);
+
+      wrappedListener('{invalid json}');
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('browserListener', () => {
+    it('should extract data from MessageEvent', () => {
+      const listener = vi.fn();
+      const browserListener = BridgeCore.browserListener(listener);
+      const event = { method: 'test' };
+      const messageEvent = {
+        data: JSON.stringify({ type: 'BridgeEvent', event }),
+      } as MessageEvent;
+
+      browserListener(messageEvent);
+
+      expect(listener).toHaveBeenCalledWith(event);
+    });
+
+    it('should ignore events without data', () => {
+      const listener = vi.fn();
+      const browserListener = BridgeCore.browserListener(listener);
+
+      browserListener({ data: undefined } as MessageEvent);
+      browserListener({} as MessageEvent);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('webViewListener', () => {
+    it('should extract data from WebView nativeEvent', () => {
+      const listener = vi.fn();
+      const webViewListener = BridgeCore.webViewListener(listener);
+      const event = { method: 'test' };
+      const webViewMessage = {
+        nativeEvent: {
+          data: JSON.stringify({ type: 'BridgeEvent', event }),
+        },
+      };
+
+      webViewListener(webViewMessage);
+
+      expect(listener).toHaveBeenCalledWith(event);
+    });
+
+    it('should ignore messages without nativeEvent', () => {
+      const listener = vi.fn();
+      const webViewListener = BridgeCore.webViewListener(listener);
+
+      webViewListener({});
+      webViewListener({ nativeEvent: {} });
+      webViewListener({ nativeEvent: { data: undefined } });
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('sendEvent', () => {
+    let originalParent: Window;
+    let originalRNW: typeof window.ReactNativeWebView;
+
+    beforeEach(() => {
+      originalParent = window.parent;
+      originalRNW = window.ReactNativeWebView;
+    });
+
+    afterEach(() => {
+      Object.defineProperty(window, 'parent', {
+        value: originalParent,
+        writable: true,
+        configurable: true,
+      });
+      (window as any).ReactNativeWebView = originalRNW;
+    });
+
+    it('should send to iframe parent when available', () => {
+      (window as any).ReactNativeWebView = undefined;
+      const mockParent = {
+        postMessage: vi.fn(),
+      };
+      Object.defineProperty(window, 'parent', {
+        value: mockParent,
+        writable: true,
+        configurable: true,
+      });
+
+      const event = { method: 'test' };
+      BridgeCore.sendEvent(event);
+
+      expect(mockParent.postMessage).toHaveBeenCalledWith(
+        expect.any(String),
+        '*'
+      );
+    });
+
+    it('should send to ReactNativeWebView when available', () => {
+      const mockRNW = {
+        postMessage: vi.fn(),
+      };
+      (window as any).ReactNativeWebView = mockRNW;
+
+      const event = { method: 'test' };
+      BridgeCore.sendEvent(event);
+
+      expect(mockRNW.postMessage).toHaveBeenCalledWith(expect.any(String));
+    });
+
+    it('should not send when window.parent === window (top level)', () => {
+      (window as any).ReactNativeWebView = undefined;
+      Object.defineProperty(window, 'parent', {
+        value: window,
+        writable: true,
+        configurable: true,
+      });
+
+      const event = { method: 'test' };
+      // This should not throw
+      expect(() => BridgeCore.sendEvent(event)).not.toThrow();
+    });
+  });
+
+  describe('subscribe', () => {
+    it('should subscribe to message events', () => {
+      const listener = vi.fn();
+      const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
+
+      const unsubscribe = BridgeCore.subscribe(listener);
+
+      expect(addEventListenerSpy).toHaveBeenCalledWith(
+        'message',
+        expect.any(Function)
+      );
+      expect(typeof unsubscribe).toBe('function');
+
+      addEventListenerSpy.mockRestore();
+    });
+
+    it('should return cleanup function that removes listener', () => {
+      const listener = vi.fn();
+      const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+
+      const unsubscribe = BridgeCore.subscribe(listener);
+      unsubscribe();
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith(
+        'message',
+        expect.any(Function)
+      );
+
+      removeEventListenerSpy.mockRestore();
+    });
+  });
+});

package/src/BridgeCore.ts

@@ -0,0 +1,138 @@
+/**
+ * Low-level bridge core handling platform-specific message passing
+ */
+
+export type Event = unknown;
+
+interface BridgeCoreEvent {
+  type: string;
+  event: Event;
+}
+
+interface WebViewMessage {
+  nativeEvent?: {
+    data?: string;
+  };
+}
+
+export type BridgeCoreListener = (event: Event) => void;
+
+declare global {
+  interface Window {
+    ReactNativeWebView?: {
+      postMessage: (message: string) => void;
+    };
+  }
+}
+
+/**
+ * BridgeCore handles the low-level platform detection and message serialization.
+ * It provides static methods for wrapping events, creating listeners, and sending messages.
+ */
+export class BridgeCore {
+  private static BRIDGE_EVENT_TYPE = 'BridgeEvent';
+
+  private static isJSONObject = (str: string): boolean => {
+    return str.startsWith('{') && str.endsWith('}');
+  };
+
+  /**
+   * Wraps an event in the bridge protocol format
+   */
+  public static wrapBridgeEvent = (event: Event): string => {
+    return JSON.stringify({
+      event,
+      type: BridgeCore.BRIDGE_EVENT_TYPE,
+    });
+  };
+
+  /**
+   * Creates a listener wrapper that parses incoming messages
+   */
+  static wrapListener =
+    (listener: BridgeCoreListener) =>
+    (data?: string): void => {
+      if (typeof data !== 'string') {
+        return;
+      }
+      if (!data) {
+        return;
+      }
+      let processedData = data;
+      // iOS wraps JSON with additional quotes
+      if (processedData.startsWith("'") && processedData.endsWith("'")) {
+        processedData = processedData.substring(1, processedData.length - 1);
+      }
+      if (!BridgeCore.isJSONObject(processedData)) {
+        return;
+      }
+      try {
+        const eventData: BridgeCoreEvent = JSON.parse(processedData);
+        if (!eventData || eventData.type !== BridgeCore.BRIDGE_EVENT_TYPE) {
+          return;
+        }
+        listener(eventData.event);
+      } catch {
+        // Ignore parse errors
+      }
+    };
+
+  /**
+   * Creates a browser-specific message event listener
+   */
+  static browserListener = (listener: BridgeCoreListener) => {
+    const triggerEvent = BridgeCore.wrapListener(listener);
+    return (originalEvent: MessageEvent): void => {
+      if (!originalEvent?.data) {
+        return;
+      }
+      triggerEvent(originalEvent.data);
+    };
+  };
+
+  /**
+   * Creates a React Native WebView message listener
+   */
+  static webViewListener = (listener: BridgeCoreListener) => {
+    const triggerEvent = BridgeCore.wrapListener(listener);
+    return (originalEvent: WebViewMessage): void => {
+      if (!originalEvent?.nativeEvent?.data) {
+        return;
+      }
+      triggerEvent(originalEvent.nativeEvent.data);
+    };
+  };
+
+  /**
+   * Sends an event to the parent context (WebView or iframe parent)
+   */
+  static sendEvent = (event: Event): void => {
+    const bridgeEvent = BridgeCore.wrapBridgeEvent(event);
+    if (typeof window === 'undefined') {
+      console.warn('Window is undefined');
+      return;
+    }
+    const RNW = window.ReactNativeWebView;
+    if (typeof RNW?.postMessage === 'function') {
+      RNW.postMessage(`'${bridgeEvent}'`);
+      return;
+    }
+    if (window.parent === window) {
+      return;
+    }
+    window.parent.postMessage(bridgeEvent, '*');
+  };
+
+  /**
+   * Subscribes to window message events
+   * @returns Cleanup function to unsubscribe
+   */
+  static subscribe = (listener: BridgeCoreListener): VoidFunction => {
+    const browserListener = BridgeCore.browserListener(listener);
+    if (typeof window === 'undefined' || !window.addEventListener) {
+      return () => {};
+    }
+    window.addEventListener('message', browserListener);
+    return () => window.removeEventListener('message', browserListener);
+  };
+}