wallet-core/extension/lib/mithril.d.ts

// Mithril type definitions for Typescript

/**
 * This is the module containing all the types/declarations/etc. for Mithril
 */
declare interface MithrilStatic {
  /**
   * Creates a virtual element for use with m.render, m.mount, etc.
   *
   * @param selector A simple CSS selector. May include SVG tags. Nested
   * selectors are not supported.
   * @param attributes Attributes to add. Any DOM attribute may be used
   * as an attribute, although innerHTML and the like may be overwritten
   * silently.
   * @param children Child elements, components, and text to add.
   * @return A virtual element.
   *
   * @see m.render
   * @see m.mount
   * @see m.component
   */
  <T extends MithrilController>(selector: string,
                                attributes: MithrilAttributes,
                                ...children: Array<string |
                                  MithrilVirtualElement<T> |
                                  MithrilComponent<T>>): MithrilVirtualElement<T>;

  /**
   * Initializes a component for use with m.render, m.mount, etc.
   *
   * @param component A component.
   * @param args Arguments to optionally pass to the component.
   * @return A component.
   *
   * @see m.render
   * @see m.mount
   * @see m
   */
  <T extends MithrilController>(component: MithrilComponent<T>,
                                ...args: any[]): MithrilComponent<T>;

  /**
   * Creates a virtual element for use with m.render, m.mount, etc.
   *
   * @param selector A simple CSS selector. Nested selectors are not
   * supported.
   * @param children Child elements, components, and text to add.
   * @return A virtual element.
   *
   * @see m.render
   * @see m.mount
   * @see m.component
   */
  <T extends MithrilController>(selector: string,
                                ...children: Array<string |
                                  MithrilVirtualElement<T> |
                                  MithrilComponent<T>>): MithrilVirtualElement<T>;

  /**
   * Initializes a component for use with m.render, m.mount, etc.
   * Shorthand for m.component.
   *
   * @param selector A component.
   * @param args Arguments to optionally pass to the component.
   * @return A component.
   *
   * @see m.render
   * @see m.mount
   * @see m.component
   */
  <T extends MithrilController>(component: MithrilComponent<T>,
                                ...args: any[]): MithrilComponent<T>;

  /**
   * Creates a getter-setter function that wraps a Mithril promise. Useful
   * for uniform data access, m.withAttr, etc.
   *
   * @param promise A thennable to initialize the property with. It may
   * optionally be a Mithril promise.
   * @return A getter-setter function wrapping the promise.
   *
   * @see m.withAttr
   */
  prop<T>(promise: Thennable<T>) : MithrilPromiseProperty<T>;

  /**
   * Creates a getter-setter function that wraps a simple value. Useful
   * for uniform data access, m.withAttr, etc.
   *
   * @param value A value to initialize the property with
   * @return A getter-setter function wrapping the value.
   *
   * @see m.withAttr
   */
  prop<T>(value: T): MithrilBasicProperty<T>;

  /**
   * Creates a getter-setter function that wraps a simple value. Useful
   * for uniform data access, m.withAttr, etc.
   *
   * @return A getter-setter function wrapping the value.
   *
   * @see m.withAttr
   */
  prop<T>(): MithrilBasicProperty<T>;

  /**
   * Returns a event handler that can be bound to an element, firing with
   * the specified property.
   *
   * @param property The property to get from the event.
   * @param callback The handler to use the value from the event.
   * @return A function suitable for listening to an event.
   */
  withAttr(property: string,
           callback: (value: any) => void,
           callbackThis: any): (e: Event) => any;

  /**
   * @deprecated Use m.mount instead
   */
  module<T extends MithrilController>(rootElement: Node,
                                      component: MithrilComponent<T>): T;

  /**
   * Mounts a component to a base DOM node.
   *
   * @param rootElement The base node.
   * @param component The component to mount.
   * @return An instance of the top-level component's controller
   */
  mount<T extends MithrilController>(rootElement: Node,
                                     component: MithrilComponent<T>): T;

  /**
   * Initializes a component for use with m.render, m.mount, etc.
   *
   * @param selector A component.
   * @param args Arguments to optionally pass to the component.
   * @return A component.
   *
   * @see m.render
   * @see m.mount
   * @see m
   */
  component<T extends MithrilController>(component: MithrilComponent<T>,
                                         ...args: any[]): MithrilComponent<T>;

  /**
   * Trust this string of HTML.
   *
   * @param html The HTML to trust
   * @return A String object instance with an added internal flag to mark
   * it as trusted.
   */
  trust(html: string): MithrilTrustedString;

  /**
   * Render a virtual DOM tree.
   *
   * @param rootElement The base element/node to render the tree from.
   * @param children One or more child nodes to add to the tree.
   * @param forceRecreation If true, overwrite the entire tree without
   * diffing against it.
   */
  render<T extends MithrilController>(rootElement: Element,
                                      children: MithrilVirtualElement<T>|MithrilVirtualElement<T>[],
                                      forceRecreation?: boolean): void;

  redraw: {
    /**
     * Force a redraw the active component. It redraws asynchronously by
     * default to allow for simultaneous events to run before redrawing,
     * such as the event combination keypress + input frequently used for
     * input.
     *
     * @param force If true, redraw synchronously.
     */
    (force?: boolean): void;

    strategy: {
      /**
       * Gets the current redraw strategy, which returns one of the
       * following:
       *
       * "all" - recreates the DOM tree from scratch
       * "diff" - recreates the DOM tree from scratch
       * "none" - leaves the DOM tree intact
       *
       * This is useful for event handlers, which may want to cancel
       * the next redraw if the event doesn't update the UI.
       *
       * @return The current strategy
       */
      (): string;

      /**
       * Sets the current redraw strategy. The parameter must be one of
       * the following values:
       *
       * "all" - recreates the DOM tree from scratch
       * "diff" - recreates the DOM tree from scratch
       * "none" - leaves the DOM tree intact
       *
       * This is useful for event handlers, which may want to cancel
       * the next redraw if the event doesn't update the UI.
       *
       * @param value The value to set
       * @return The new strategy
       */
      (value: string): string;

      /**
       * @private
       * Implementation detail - it's a MithrilBasicProperty instance
       */
      toJSON(): string;
    }
  }

  route: {
    /**
     * Enable routing, mounting a controller based on the route. It
     * automatically mounts the components for you, starting with the one
     * specified by the default route.
     *
     * @param rootElement The element to mount the active controller to.
     * @param defaultRoute The route to start with.
     * @param routes A key-value mapping of pathname to controller.
     */
    <T extends MithrilController>(rootElement: Element,
                                  defaultRoute: string,
                                  routes: MithrilRoutes): void;

    /**
     * This allows m.route to be used as the `config` attribute for a
     * virtual element, particularly useful for cases like this:
     *
     * ```ts
     * // Note that the '#' is not required in `href`, thanks to the
     * `config` setting.
     * m("a[href='/dashboard/alicesmith']", {config: m.route});
     * ```
     */
    <T extends MithrilController>(element: Element,
                                  isInitialized: boolean,
                                  context?: MithrilContext,
                                  vdom?: MithrilVirtualElement<T>): void;

    /**
     * Programmatically redirect to another route.
     *
     * @param path The route to go to.
     * @param params Parameters to pass as a query string.
     * @param shouldReplaceHistory Whether to replace the current history
     * instead of adding a new one.
     */
    (path: string, params?: any, shouldReplaceHistory?: boolean): void;

    /**
     * Gets the current route.
     *
     * @return The current route.
     */
    (): string;

    /**
     * Gets a route parameter.
     *
     * @param key The key to get.
     * @return The value associated with the parameter key.
     */
    param(key: string): string;

    /**
     * The current routing mode. This may be changed before calling
     * m.route to change the part of the URL used to perform the routing.
     *
     * The value can be set to one of the following, defaulting to
     * "hash":
     *
     * "search" - Uses the query string. This allows for named anchors to
     * work on the page, but changes cause IE8 and lower to refresh the
     * page.
     *
     * "hash" - Uses the hash. This is the only routing mode that does
     * not cause page refreshes on any browser, but it does not support
     * named anchors.
     *
     * "pathname" - Uses the URL pathname. This requires server-side
     * setup to support bookmarking and page refreshes. It always causes
     * page refreshes on IE8 and lower. Note that this requires that the
     * application to be run from the root of the URL.
     */
    mode: string;

    /**
     * Serialize an object into a query string.
     *
     * @param data The data to serialize.
     * @return The serialized string.
     */
    buildQueryString(data: Object): String

    /**
     * Parse a query string into an object.
     *
     * @param data The data to parse.
     * @return The parsed object data.
     */
    parseQueryString(data: String): Object
  }

  /**
   * Send a request to a server to server. Note that the `url` option is
   * required.
   *
   * @param options The options to use
   * @return A promise to the returned data for "GET" requests, or a void
   * promise for any other request type.
   *
   * @see MithrilXHROptions for the available options.
   */
  request<T>(options: MithrilXHROptions<T>): MithrilPromise<T>;

  deferred: {
    /**
     * Create a Mithril deferred object. It behaves synchronously if
     * possible, an intentional deviation from Promises/A+. Note that
     * deferreds are completely separate from the redrawing system, and
     * never trigger a redraw on their own.
     *
     * @return A new Mithril deferred instance.
     *
     * @see m.deferred.onerror for the error callback called for Error
     * subclasses
     */
    <T>(): MithrilDeferred<T>;

    /**
     * A callback for all uncaught native Error subclasses in deferreds.
     * This defaults to synchronously rethrowing all errors, a deviation
     * from Promises/A+, but the behavior is configurable. To restore
     * Promises/A+-compatible behavior. simply set this to a no-op.
     */
    onerror(e: Error): void;
  }

  /**
   * Takes a list of promises or thennables and returns a Mithril promise
   * that resolves once all in the list are resolved, or rejects if any of
   * them reject.
   *
   * @param promises A list of promises to try to resolve.
   * @return A promise that resolves to all the promises if all resolve, or
   * rejects with the error contained in the first rejection.
   */
  sync<T>(promises: Thennable<T>[]): MithrilPromise<T[]>;

  /**
   * Use this and endComputation if your views aren't redrawing after
   * calls to third-party libraries. For integrating asynchronous code,
   * this should be called before any asynchronous work is done. For
   * synchronous code, this should be called at the beginning of the
   * problematic segment. Note that these calls must be balanced, much like
   * braces and parentheses. This is mostly used internally. Prefer
   * m.redraw where possible, especially when making repeated calls.
   *
   * @see endComputation
   * @see m.render
   */
  startComputation(): void;

  /**
   * Use startComputation and this if your views aren't redrawing after
   * calls to third-party libraries. For integrating asynchronous code,
   * this should be called after all asynchronous work completes. For
   * synchronous code, this should be called at the end of the problematic
   * segment. Note that these calls must be balanced, much like braces and
   * parentheses. This is mostly used internally. Prefer m.redraw where
   * possible, especially when making repeated calls.
   *
   * @see startComputation
   * @see m.render
   */
  endComputation(): void;

  /**
   * This overwrites the internal version of window used by Mithril.
   * It's mostly useful for testing, and is also used internally by
   * Mithril to test itself. By default Mithril uses `window` for the
   * dependency.
   *
   * @param mockWindow The mock to use for the window.
   * @return The mock that was passed in.
   */
  deps(mockWindow: Window): Window;
}

interface MithrilTrustedString extends String {
  /** @private Implementation detail. Don't depend on it. */
  $trusted: boolean;
}

/**
 * The interface for a virtual element. It's best to consider this immutable
 * for most use cases.
 *
 * @see m
 */
interface MithrilVirtualElement<T extends MithrilController> {
  /**
   * A key to optionally associate with this element.
   */
  key?: number;

  /**
   * The tag name of this element.
   */
  tag?: string;

  /**
   * The attributes of this element.
   */
  attrs?: MithrilAttributes;

  /**
   * The children of this element.
   */
  children?: Array<string|MithrilVirtualElement<T>|MithrilComponent<T>>;
}

/**
 * An event passed by Mithril to unload event handlers.
 */
interface MithrilEvent {
  /**
   * Prevent the default behavior of scrolling the page and updating the
   * URL on next route change.
   */
  preventDefault(): void;
}

/**
 * A context object for configuration functions.
 *
 * @see MithrilElementConfig
 */
interface MithrilContext {
  /**
   * A function to call when the node is unloaded. Useful for cleanup.
   */
  onunload?(): any;

  /**
   * Set true if the backing DOM node needs to be retained between route
   * changes if possible. Set false if this node needs to be recreated
   * every single time, regardless of how "different" it is.
   */
  retain?: boolean;
}

/**
 * This represents a callback function for a virtual element's config
 * attribute. It's a low-level function useful for extra cleanup after
 * removal from the tree, storing instances of third-party classes that
 * need to be associated with the DOM, etc.
 *
 * @see MithrilAttributes
 * @see MithrilContext
 */
interface MithrilElementConfig {
  /**
   * A callback function for a virtual element's config attribute.
   *
   * @param element The associated DOM element.
   * @param isInitialized Whether this is the first call for the virtual
   * element or not.
   * @param context The associated context for this element.
   * @param vdom The associated virtual element.
   */
  <T extends MithrilController>(element: Element,
                                isInitialized: boolean,
                                context: MithrilContext,
                                vdom: MithrilVirtualElement<T>): void;
}

/**
 * This represents the attributes available for configuring virtual elements,
 * beyond the applicable DOM attributes.
 *
 * @see m
 */
interface MithrilAttributes {
  /**
   * The class name(s) for this virtual element, as a space-separated list.
   */
  className?: string;

  /**
   * The class name(s) for this virtual element, as a space-separated list.
   */
    class?: string;

  /**
   * A custom, low-level configuration in case this element needs special
   * cleanup after removal from the tree.
   *
   * @see MithrilElementConfig
   */
  config?: MithrilElementConfig;

  /**
   * Any other virtual element properties including attributes and
   * event handlers
   */
  [property: string]: any;
}

/**
 * The basis of a Mithril controller instance.
 */
interface MithrilController {
  /**
   * An optional handler to call when the associated virtual element is
   * destroyed.
   *
   * @param evt An associated event.
   */
  onunload?(evt: MithrilEvent): any;
}

/**
 * This represents a controller function.
 *
 * @see MithrilControllerConstructor
 */
interface MithrilControllerFunction<T extends MithrilController> {
  (): T;
}

/**
 * This represents a controller constructor.
 *
 * @see MithrilControllerFunction
 */
interface MithrilControllerConstructor<T extends MithrilController> {
  new(): T;
}

/**
 * This represents a view factory.
 */
interface MithrilView<T extends MithrilController> {
  /**
   * Creates a view out of virtual elements.
   */
  (ctrl: T): MithrilVirtualElement<T>;
}

/**
 * This represents a Mithril component.
 *
 * @see m
 * @see m.component
 */
interface MithrilComponent<T extends MithrilController> {
  /**
   * The component's controller.
   *
   * @see m.component
   */
  controller?: MithrilControllerFunction<T> |
    MithrilControllerConstructor<T>;

  /**
   * Creates a view out of virtual elements.
   *
   * @see m.component
   */
  view(ctrl: T): MithrilVirtualElement<T>;
}

/**
 * This is the base interface for property getter-setters
 *
 * @see m.prop
 */
interface MithrilProperty<T> {
  /**
   * Gets the contained value.
   *
   * @return The contained value.
   */
  (): T;

  /**
   * Sets the contained value.
   *
   * @param value The new value to set.
   * @return The newly set value.
   */
  (value: T): T;
}

/**
 * This represents a non-promise getter-setter functions.
 *
 * @see m.prop which returns objects that implement this interface.
 */
interface MithrilBasicProperty<T> extends MithrilProperty<T> {
  /**
   * Makes this serializable to JSON.
   */
  toJSON(): T;
}

/**
 * This represents a promise getter-setter function.
 *
 * @see m.prop which returns objects that implement this interface.
 */
interface MithrilPromiseProperty<T> extends MithrilPromise<T>,
  MithrilProperty<MithrilPromise<T>> {
  /**
   * Gets the contained promise.
   *
   * @return The contained value.
   */
  (): MithrilPromise<T>;

  /**
   * Sets the contained promise.
   *
   * @param value The new value to set.
   * @return The newly set value.
   */
  (value: MithrilPromise<T>): MithrilPromise<T>;

  /**
   * Sets the contained wrapped value.
   *
   * @param value The new value to set.
   * @return The newly set value.
   */
  (value: T): MithrilPromise<T>;
}

/**
 * This represents a key-value mapping linking routes to components.
 */
interface MithrilRoutes {
  /**
   * The key represents the route. The value represents the corresponding
   * component.
   */
  [key: string]: MithrilComponent<MithrilController>;
}

/**
 * This represents a Mithril deferred object.
 */
interface MithrilDeferred<T> {
  /**
   * Resolve this deferred's promise with a value.
   *
   * @param value The value to resolve the promise with.
   */
  resolve(value?: T): void;

  /**
   * Reject this deferred with an error.
   *
   * @param value The reason for rejecting the promise.
   */
  reject(reason?: any): void;

  /**
   * The backing promise.
   *
   * @see MithrilPromise
   */
  promise: MithrilPromise<T>;
}

/**
 * This represents a thennable success callback.
 */
interface MithrilSuccessCallback<T, U> {
  (value: T): U | Thennable<U>;
}

/**
 * This represents a thennable error callback.
 */
interface MithrilErrorCallback<T> {
  (value: Error): T | Thennable<T>;
}

/**
 * This represents a thennable.
 */
interface Thennable<T> {
  then<U>(success: (value: T) => U): Thennable<U>;
  then<U,V>(success: (value: T) => U,
            error: (value: Error) => V): Thennable<U>|Thennable<V>;
  catch?: <U>(error: (value: Error) => U) => Thennable<U>;
}

/**
 * This represents a Mithril promise object.
 */
interface MithrilPromise<T> extends Thennable<T>, MithrilProperty<MithrilPromise<T>> {
  /**
   * Chain this promise with a simple success callback, propogating
   * rejections.
   *
   * @param success The callback to call when the promise is resolved.
   * @return The chained promise.
   */
  then<U>(success: MithrilSuccessCallback<T,U>): MithrilPromise<U>;

  /**
   * Chain this promise with a success callback and error callback, without
   * propogating rejections.
   *
   * @param success The callback to call when the promise is resolved.
   * @param error The callback to call when the promise is rejected.
   * @return The chained promise.
   */
  then<U, V>(success: MithrilSuccessCallback<T, U>,
             error: MithrilErrorCallback<V>): MithrilPromise<U> | MithrilPromise<V>;

  /**
   * Chain this promise with a single error callback, without propogating
   * rejections.
   *
   * @param error The callback to call when the promise is rejected.
   * @return The chained promise.
   */
  catch<U>(error: MithrilErrorCallback<U>): MithrilPromise<T> |
    MithrilPromise<U>;
}

/**
 * This represents the available options for configuring m.request.
 *
 * @see m.request
 */
interface MithrilXHROptions<T> {
  /**
   * This represents the HTTP method used, one of the following:
   *
   * - "GET" (default)
   * - "POST"
   * - "PUT"
   * - "DELETE"
   * - "HEAD"
   * - "OPTIONS"
   */
  method?: string;

  /**
   * The URL to send the request to.
   */
  url: string;

  /**
   * The username for HTTP authentication.
   */
  user?: string;

  /**
   * The password for HTTP authentication.
   */
  password?: string;

  /**
   * The data to be sent. It's automatically serialized in the right format
   * depending on the method (with exception of HTML5 FormData), and put in
   * the appropriate section of the request.
   */
  data?: any;

  /**
   * Whether to run it in the background, i.e. true if it doesn't affect
   * template rendering.
   */
  background?: boolean;

  /**
   * Set an initial value while the request is working, to populate the
   * promise getter-setter.
   */
  initialValue?: T;

  /**
   * An optional preprocessor function to unwrap a successful response, in
   * case the response contains metadata wrapping the data.
   *
   * @param data The data to unwrap.
   * @return The unwrapped result.
   */
  unwrapSuccess?(data: any): T;

  /**
   * An optional preprocessor function to unwrap an unsuccessful response,
   * in case the response contains metadata wrapping the data.
   *
   * @param data The data to unwrap.
   * @return The unwrapped result.
   */
  unwrapError?(data: any): T;

  /**
   * An optional function to serialize the data. This defaults to
   * `JSON.stringify`.
   *
   * @param dataToSerialize The data to serialize.
   * @return The serialized form as a string.
   */
  serialize?(dataToSerialize: any): string;

  /**
   * An optional function to deserialize the data. This defaults to
   * `JSON.parse`.
   *
   * @param dataToSerialize The data to parse.
   * @return The parsed form.
   */
  deserialize?(dataToDeserialize: string): any;

  /**
   * An optional function to extract the data from a raw XMLHttpRequest,
   * useful if the relevant data is in a response header or the status
   * field.
   *
   * @param xhr The associated XMLHttpRequest.
   * @param options The options passed to this request.
   * @return string The serialized format.
   */
  extract?(xhr: XMLHttpRequest, options: MithrilXHROptions<T>): string;

  /**
   * The parsed data, or its children if it's an array, will be passed to
   * this class constructor if it's given, to parse it into classes.
   *
   * @param data The data to parse.
   * @return The new instance for the list.
   */
    type?: new (data: Object) => any;

  /**
   * An optional function to run between `open` and `send`, useful for
   * adding request headers or using XHR2 features such as the `upload`
   * property. It is even possible to override the XHR altogether with a
   * similar object, such as an XDomainRequest instance.
   *
   * @param xhr The associated XMLHttpRequest.
   * @param options The options passed to this request.
   * @return The new XMLHttpRequest, or nothing if the same one is kept.
   */
  config?(xhr: XMLHttpRequest, options: MithrilXHROptions<T>): any;

  /**
   * For JSONP requests, this must be the string "jsonp". Otherwise, it's
   * ignored.
   */
  dataType?: string;

  /**
   * For JSONP requests, this is the query string key for the JSONP
   * request. This is useful for APIs that don't use common conventions,
   * such as `www.example.com/?jsonpCallback=doSomething`. It defaults to
   * `callback` for JSONP requests, and is ignored for any other kind of
   * request.
   */
  callbackKey?: string;
}