/**
 * Insight APIs
 *
 * @example
 *
 * ```js
 * insight.on('event', (ev) => { ... });
 * ```
 */

/**
 * Names of events emitted by Insight APIs.
 */
type InsightEventName = "source" | string;

// Base interface for insight events.
interface InsightEventType<T> {
  name: string;
  shape: T;
}

/**
 * Structure of a `source` event emitted by the Insight API.
 */
type InsightSourceEvent = {
  /**
   * Name of the source file or snippet.
   */
  name: string;

  /**
   * Character string of the source code.
   */
  characters: string;
};

/**
 * Event type and shape for 'source' events.
 */
type InsightSourceEventType = InsightEventType<
  InsightSourceEvent & {
    name: "source";
  }
>;

/**
 * Shape of event payloads passed to event callbacks.
 */
type InsightEventShape = InsightSourceEventShape | any;

/**
 * Base callback type for events emitted by Insight APIs.
 */
type InsightEventCallback<E = InsightEventShape> = (ev: E) => void;

/**
 * Union of all event types.
 */
type InsightEvent = InsightSourceEventType;

/**
 * Insight API
 *
 * Offers APIs for instrumenting code within Elide's guest VM context.
 */
interface InsightAPI {
  /**
   * Subscribe to an event via the Insight API.
   *
   * @param name Name of the event
   * @param callback Callback to invoke when the event is emitted
   */
  on<E = InsightEventShape>(name: string, callback: InsightEventCallback<E>);
}

declare var insight: InsightAPI;