Subject-like wrapper around the Broadcast Channel API

[alexanderharding]

Any interest in adding a Subject-like wrapper around the Broadcast Channel API to the project? If so, I'd like to submit a PR for the following API:

// BroadcastChannelSubject.ts - similar to WebSocketSubject.ts
import { Observable } from '../../Observable';
import { Subject } from '../../Subject';
import { Observer, SubscriptionLike } from '../../types';
import { Operator } from '../../Operator';

export interface BroadcastChannelSubjectConfig<In = void, Out = In> {
  /**
   * The name of the underlying {@linkcode BroadcastChannel}.
   */
  name: string;
  /**
   * A function that transforms the {@linkcode MessageEvent} into an {@linkcode Out|output value}.
   * @default (event) => event.data
   */
  transformer?: (event: MessageEvent<In>) => Out;
}

const DEFAULT_TRANSFORMER = (event: MessageEvent) => event.data;

export class BroadcastChannelSubject<In = void, Out = In> extends Observable<Out> implements Observer<In>, SubscriptionLike {
  private readonly _channel: BroadcastChannel;
  private readonly _transformer: (event: MessageEvent<In>) => Out;
  private _output = new Subject<Out>();
  private _closed = false;

  constructor(nameOrConfig: string | BroadcastChannelSubjectConfig<In, Out>) {
    super((subscriber) => this._output.subscribe(subscriber));

    this._transformer = typeof nameOrConfig === 'string' || !nameOrConfig.transformer ? DEFAULT_TRANSFORMER : nameOrConfig.transformer;
    this._channel = new BroadcastChannel(typeof nameOrConfig === 'string' ? nameOrConfig : nameOrConfig.name);
    this._channel.onmessage = (event) => {
      try {
        this._output.next(this._transformer(event));
      } catch (error) {
        this.error(error);
      }
    };
    this._channel.onmessageerror = (error) => this.error(error);
  }

  /**
   * The name of the underlying {@linkcode BroadcastChannel}.
   */
  get name(): string {
    return this._channel.name;
  }

  /**
   * Determines if the underlying {@linkcode BroadcastChannel} has been closed and can no longer send or receive messages.
   * When closed, this {@linkcode BroadcastChannelSubject} is also completed.
   * @see {@linkcode BroadcastChannel.close}
   * @see {@linkcode BroadcastChannelSubject.complete} which should be called to close the underlying {@linkcode BroadcastChannel}.
   */
  get closed(): boolean {
    return this._closed;
  }

  /** @deprecated Internal implementation detail, do not use directly. Will be made internal in v8. */
  lift<R>(operator: Operator<Out, R>): BroadcastChannelSubject<In, R> {
    const channel = new BroadcastChannelSubject({ name: this.name, transformer: this._transformer } as BroadcastChannelSubjectConfig<any>);
    channel.operator = operator;
    channel.source = this;
    return channel;
  }

  /**
   * Broadcasts {@linkcode value} to all _other_ open {@linkcode BroadcastChannel}'s under the
   * same channel name.
   *
   * If the {@linkcode value} is not {@linkcode structuredClone|cloneable},  subscribers of this
   * {@linkcode BroadcastChannelSubject} will receive an {@linkcode DOMException|error} notification instead.
   *
   * @see {@linkcode BroadcastChannel.postMessage}
   */
  next(value: In): void {
    try {
      this._channel.postMessage(value);
    } catch (error) {
      this.error(error);
    }
  }

  /**
   * Errors this {@linkcode BroadcastChannelSubject} but doesn't close the underlying {@linkcode BroadcastChannel} since it
   * isn't directly affected (it _could_ still send/receive messages).
   *
   * If the underlying {@linkcode BroadcastChannel} is {@linkcode BroadcastChannelSubject.closed|open}, subscribers are encouraged
   * to retry so they can continue to receive messages. They do not need to retry to continue to
   * {@linkcode BroadcastChannelSubject.next|send} messages.
   */
  error(error: any): void {
    (this.closed ? this._output : this._resetOutput()).error(error);
  }

  /**
   * Completes this {@linkcode BroadcastChannelSubject} and closes the underlying {@linkcode BroadcastChannel} so it can no
   * longer send or receive messages.
   *
   * It is encouraged to call this method when the {@linkcode BroadcastChannelSubject} is no longer needed so
   * it can be eligible for garbage collection.
   * @see {@linkcode BroadcastChannel.close}
   */
  complete(): void {
    this._channel.close();
    this._closed = true;
    this._output.complete();
  }

  /**
   * Creates a new Observable with this Subject as the source. You can do this
   * to create custom Observer-side logic of the Subject and conceal it from
   * code that uses the Observable.
   * @return Observable that this Subject casts to.
   */
  asObservable(): Observable<Out> {
    const observable = new Observable<Out>();
    observable.source = this;
    return observable;
  }

  unsubscribe(): void {
    (this.closed ? this._output : this._resetOutput()).unsubscribe();
  }

  /** @returns The previous output. */
  private _resetOutput(): Subject<Out> {
    const previous = this._output;
    this._output = new Subject();
    return previous;
  }
}

// broadcastChannel.ts - similar to webSocket
import { BroadcastChannelSubject, BroadcastChannelSubjectConfig } from './BroadcastChannelSubject';

/**
 * Wrapper around the {@linkcode BroadcastChannel} object provided by the browser.
 *
 * <span class="informal">{@link Subject} that communicates with other BroadcastChannel objects</span>
 *
 * `broadcastChannel` is a factory function that produces a `BroadcastChannelSubject`,
 * which can be used to communicate with other BroadcastChannel objects (which may be in other windows,
 * tabs, workers, or iframes) under the same origin. `broadcastChannel` accepts either a string with
 * the channel name, or a {@link BroadcastChannelSubjectConfig} object for providing additional
 * configuration, such as a transformer function to customize how messages are processed.
 *
 * When `BroadcastChannelSubject` is created, it establishes a new `BroadcastChannel` connection
 * with the specified name. Any messages posted to this channel by other BroadcastChannel objects
 * will be emitted as values in the stream. By default, the raw message data is emitted, but you
 * can provide a custom `transformer` function in the config to transform the {@link MessageEvent}
 * before emission.
 *
 * If at any point there is an error in message processing or posting, the stream will error with
 * whatever the BroadcastChannel API has thrown. Note that these errors don't close the underlying
 * channel - subscribers are encouraged to retry to continue receiving messages.
 *
 * By virtue of being a {@link Subject}, `BroadcastChannelSubject` allows for both sending and receiving
 * messages. To send a message to other BroadcastChannel objects, use the `next` method. The value passed
 * to `next` must be {@link structuredClone|cloneable} - if it's not, subscribers to the current Subject will receive an error.
 * The `complete` method closes the underlying channel so it can no longer send or receive messages.
 * The `error` method signals an error to subscribers but doesn't close the channel since it isn't
 * directly affected.
 *
 * ## Examples
 *
 * Basic usage with string name:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel('my-channel');
 *
 * // Subscribe to receive messages from other channels under the same name
 * channel.subscribe({
 *   next: msg => console.log('message received:', msg),
 *   error: err => console.log('error:', err),
 *   complete: () => console.log('channel closed')
 * });
 *
 * // Send a message to other channels under the same name
 * channel.next({ type: 'greeting', text: 'Hello!' });
 *
 * // Close the channel when done
 * channel.complete();
 * ```
 *
 * Using a custom transformer:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel({
 *   name: 'my-channel',
 *   transformer: (event) => ({
 *     data: event.data,
 *     timestamp: Date.now()
 *   })
 * });
 *
 * channel.subscribe(msg => {
 *   console.log(`Received at ${msg.timestamp}:`, msg.data);
 * });
 * ```
 *
 * @param name The channel name as a string.
 * @return A Subject which allows both sending and receiving messages via BroadcastChannel.
 */
export function broadcastChannel<T = void>(name: string): BroadcastChannelSubject<T, T>;
/**
 * Wrapper around the {@linkcode BroadcastChannel} object provided by the browser.
 *
 * <span class="informal">{@link Subject} that communicates with other BroadcastChannel objects</span>
 *
 * `broadcastChannel` is a factory function that produces a `BroadcastChannelSubject`,
 * which can be used to communicate with other BroadcastChannel objects (which may be in other windows,
 * tabs, workers, or iframes) under the same origin. `broadcastChannel` accepts either a string with
 * the channel name, or a {@link BroadcastChannelSubjectConfig} object for providing additional
 * configuration, such as a transformer function to customize how messages are processed.
 *
 * When `BroadcastChannelSubject` is created, it establishes a new `BroadcastChannel` connection
 * with the specified name. Any messages posted to this channel by other BroadcastChannel objects
 * will be emitted as values in the stream. By default, the raw message data is emitted, but you
 * can provide a custom `transformer` function in the config to transform the {@link MessageEvent}
 * before emission.
 *
 * If at any point there is an error in message processing or posting, the stream will error with
 * whatever the BroadcastChannel API has thrown. Note that these errors don't close the underlying
 * channel - subscribers are encouraged to retry to continue receiving messages.
 *
 * By virtue of being a {@link Subject}, `BroadcastChannelSubject` allows for both sending and receiving
 * messages. To send a message to other BroadcastChannel objects, use the `next` method. The value passed
 * to `next` must be {@link structuredClone|cloneable} - if it's not, subscribers to the current Subject will receive an error.
 * The `complete` method closes the underlying channel so it can no longer send or receive messages.
 * The `error` method signals an error to subscribers but doesn't close the channel since it isn't
 * directly affected.
 *
 * ## Examples
 *
 * Basic usage with string name:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel('my-channel');
 *
 * // Subscribe to receive messages from other channels under the same name
 * channel.subscribe({
 *   next: msg => console.log('message received:', msg),
 *   error: err => console.log('error:', err),
 *   complete: () => console.log('channel closed')
 * });
 *
 * // Send a message to other channels under the same name
 * channel.next({ type: 'greeting', text: 'Hello!' });
 *
 * // Close the channel when done
 * channel.complete();
 * ```
 *
 * Using a custom transformer:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel({
 *   name: 'my-channel',
 *   transformer: (event) => ({
 *     data: event.data,
 *     timestamp: Date.now()
 *   })
 * });
 *
 * channel.subscribe(msg => {
 *   console.log(`Received at ${msg.timestamp}:`, msg.data);
 * });
 * ```
 *
 * @param config A configuration object.
 * @return A Subject which allows both sending and receiving messages via BroadcastChannel.
 */
export function broadcastChannel<In = void, Out = In>(config: BroadcastChannelSubjectConfig<In, Out>): BroadcastChannelSubject<In, Out>;
/**
 * Wrapper around the {@linkcode BroadcastChannel} object provided by the browser.
 *
 * <span class="informal">{@link Subject} that communicates with other BroadcastChannel objects</span>
 *
 * `broadcastChannel` is a factory function that produces a `BroadcastChannelSubject`,
 * which can be used to communicate with other BroadcastChannel objects (which may be in other windows,
 * tabs, workers, or iframes) under the same origin. `broadcastChannel` accepts either a string with
 * the channel name, or a {@link BroadcastChannelSubjectConfig} object for providing additional
 * configuration, such as a transformer function to customize how messages are processed.
 *
 * When `BroadcastChannelSubject` is created, it establishes a new `BroadcastChannel` connection
 * with the specified name. Any messages posted to this channel by other BroadcastChannel objects
 * will be emitted as values in the stream. By default, the raw message data is emitted, but you
 * can provide a custom `transformer` function in the config to transform the {@link MessageEvent}
 * before emission.
 *
 * If at any point there is an error in message processing or posting, the stream will error with
 * whatever the BroadcastChannel API has thrown. Note that these errors don't close the underlying
 * channel - subscribers are encouraged to retry to continue receiving messages.
 *
 * By virtue of being a {@link Subject}, `BroadcastChannelSubject` allows for both sending and receiving
 * messages. To send a message to other BroadcastChannel objects, use the `next` method. The value passed
 * to `next` must be {@link structuredClone|cloneable} - if it's not, subscribers to the current Subject will receive an error.
 * The `complete` method closes the underlying channel so it can no longer send or receive messages.
 * The `error` method signals an error to subscribers but doesn't close the channel since it isn't
 * directly affected.
 *
 * ## Examples
 *
 * Basic usage with string name:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel('my-channel');
 *
 * // Subscribe to receive messages from other channels under the same name
 * channel.subscribe({
 *   next: msg => console.log('message received:', msg),
 *   error: err => console.log('error:', err),
 *   complete: () => console.log('channel closed')
 * });
 *
 * // Send a message to other channels under the same name
 * channel.next({ type: 'greeting', text: 'Hello!' });
 *
 * // Close the channel when done
 * channel.complete();
 * ```
 *
 * Using a custom transformer:
 *
 * ```ts
 * import { broadcastChannel } from 'rxjs/broadcastChannel';
 *
 * const channel = broadcastChannel({
 *   name: 'my-channel',
 *   transformer: (event) => ({
 *     data: event.data,
 *     timestamp: Date.now()
 *   })
 * });
 *
 * channel.subscribe(msg => {
 *   console.log(`Received at ${msg.timestamp}:`, msg.data);
 * });
 * ```
 *
 * @param nameOrConfig The channel name as a string or a configuration object.
 * @return A Subject which allows both sending and receiving messages via BroadcastChannel.
 */
export function broadcastChannel<In = void, Out = In>(
  nameOrConfig: string | BroadcastChannelSubjectConfig<In, Out>
): BroadcastChannelSubject<In, Out>;
export function broadcastChannel<In = void, Out = In>(
  nameOrConfig: string | BroadcastChannelSubjectConfig<In, Out>
): BroadcastChannelSubject<In, Out> {
  return new BroadcastChannelSubject(nameOrConfig);
}