index.d.ts

// Mithril type definitions for Typescript. Note that changes to this *must* be
// mirrored in the ambient file in mithril.d.ts

/**
* This is the module containing all the types/declarations/etc. for Mithril
*/

export interface ChildArray extends Array<Children> {}
export type Children = Child | ChildArray;
export type Child = string | TrustedString | VirtualElement | Component<Controller>;

export interface Static {
	/**
	* 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
	*/
	(
		selector: string,
		...children: Children[]
	): VirtualElement;

	/**
	* 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
	*/
	(
		selector: string,
		attributes: Attributes,
		...children: Children[]
	): VirtualElement;

	/**
	* 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 Controller>(
		component: Component<T>,
		...args: any[]
	): Component<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>): Promise<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): BasicProperty<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>(): BasicProperty<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) => any,
		callbackThis?: any
	): (e: Event) => void;

	/**
	* @deprecated Use m.mount instead
	*/
	module<T extends Controller>(
		rootElement: Node,
		component: Component<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 Controller>(
		rootElement: Node,
		component: Component<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 Controller>(
		component: Component<T>,
		...args: any[]
	): Component<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): TrustedString;

	/**
	* 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(
		rootElement: Element,
		children: VirtualElement|VirtualElement[],
		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;

		/**
		* Gets/sets 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
		*/
		strategy: BasicProperty<"all" | "diff" | "none">;
	}

	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.
		*/
		(
			rootElement: Element,
			defaultRoute: string,
			routes: Routes
		): 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});
		* ```
		*/
		(
			element: Element,
			isInitialized: boolean,
			context?: Context,
			vdom?: VirtualElement
		): 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: "search" | "hash" | "pathname";

		/**
		* 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 an XHR request to a server. Note that the `url` option is
	* required.
	*
	* @param options The options to use for the request.
	* @return A promise to the returned data, or void if not applicable.
	*
	* @see XHROptions for the available options.
	*/
	request(options: XHROptions): Promise<any>

	/**
	* Send a JSONP request to a server. Note that the `url` option is
	* required.
	*
	* @param options The options to use
	* @return A promise to the returned data.
	*
	* @see JSONPOptions for the available options.
	*/
	request(options: JSONPOptions): Promise<any>;

	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>(): Deferred<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>[]): Promise<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;
}

export default m: Static;

/**
* 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
*/
export function prop<T>(promise: Thennable<T>): Promise<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
*/
export function prop<T>(value: T): BasicProperty<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
*/
export function prop<T>(): BasicProperty<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.
*/
export function withAttr(
	property: string,
	callback: (value: any) => any,
	callbackThis?: any
): (e: Event) => void;

/**
* @deprecated Use m.mount instead
*/
export function module<T extends Controller>(
	rootElement: Node,
	component: Component<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
*/
export function mount<T extends Controller>(
	rootElement: Node,
	component: Component<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
*/
export function component<T extends Controller>(
	component: Component<T>,
	...args: any[]
): Component<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.
*/
export function trust(html: string): TrustedString;

/**
* 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.
*/
export function render(
	rootElement: Element,
	children: VirtualElement|VirtualElement[],
	forceRecreation?: boolean
): void;

export const 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;

	/**
	* Gets/sets 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
	*/
	strategy: BasicProperty<"all" | "diff" | "none">;
}

export const 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.
	*/
	(
		rootElement: Element,
		defaultRoute: string,
		routes: Routes
	): 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});
	* ```
	*/
	(
		element: Element,
		isInitialized: boolean,
		context?: Context,
		vdom?: VirtualElement
	): 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: "search" | "hash" | "pathname";

	/**
	* 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 an XHR request to a server. Note that the `url` option is
* required.
*
* @param options The options to use for the request.
* @return A promise to the returned data, or void if not applicable.
*
* @see XHROptions for the available options.
*/
export function request(options: XHROptions): Promise<any>

/**
* Send a JSONP request to a server. Note that the `url` option is
* required.
*
* @param options The options to use
* @return A promise to the returned data.
*
* @see JSONPOptions for the available options.
*/
export function request(options: JSONPOptions): Promise<any>;

export const 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>(): Deferred<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.
*/
export function sync<T>(promises: Thennable<T>[]): Promise<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
*/
export function 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
*/
export function 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.
*/
export function deps(mockWindow: Window): Window;

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

/**
* A virtual element. It's best to consider this immutable for most use cases.
*
* @see m
*/
export interface VirtualElement {
	/**
	* The tag name of this element.
	*/
	tag: string;

	/**
	* The attributes of this element.
	*/
	attrs: Attributes;

	/**
	* The children of this element.
	*/
	children: Children[];
}

/**
* An event passed by Mithril to unload event handlers.
*/
export interface Event {
	/**
	* 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 ElementConfig
*/
export interface Context {
	/**
	* 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 Attributes
* @see Context
*/
export interface ElementConfig {
	/**
	* 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.
	*/
	(
		element: Element,
		isInitialized: boolean,
		context: Context,
		vdom: VirtualElement
	): void;
}

/**
* This represents the attributes available for configuring virtual elements,
* beyond the applicable DOM attributes.
*
* @see m
*/
export interface Attributes {
	/**
	* 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 ElementConfig
	*/
	config?: ElementConfig;

	/**
	* A key to optionally associate with this element.
	*/
	key?: string | number;

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

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

/**
* This represents a controller function.
*
* @see ControllerConstructor
*/
export interface ControllerFunction<T extends Controller> {
	(...args: any[]): T;
}

/**
* This represents a controller constructor.
*
* @see ControllerFunction
*/
export interface ControllerConstructor<T extends Controller> {
	new (...args: any[]): T;
}

/**
* This represents a Mithril component.
*
* @see m
* @see m.component
*/
export interface Component<T extends Controller> {
	/**
	* The component's controller.
	*
	* @see m.component
	*/
	controller?: ControllerFunction<T> | ControllerConstructor<T>;

	/**
	* Creates a view out of virtual elements.
	*
	* @see m.component
	*/
	view(ctrl?: T, ...args: any[]): VirtualElement;
}

/**
* This is the base interface for property getter-setters
*
* @see m.prop
*/
export interface Property<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.
*/
export interface BasicProperty<T> extends Property<T> {
	/**
	* Makes this serializable to JSON.
	*/
	toJSON(): T;
}

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

/**
* This represents a Mithril deferred object.
*/
export interface Deferred<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 Promise
	*/
	promise: Promise<T>;
}

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

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

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

/**
* This represents a Mithril promise object.
*/
export interface Promise<T> extends Thennable<T>, Property<T | Promise<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: SuccessCallback<T, U>): Promise<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: SuccessCallback<T, U>, error: ErrorCallback<V>): Promise<U | 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: ErrorCallback<U>): Promise<T | U>;
}

/**
 * These are the common options shared across normal and JSONP requests.
 *
 * @see m.request
 */
export interface RequestOptions {
	/**
	* 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?: any;

	/**
	* 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): any;

	/**
	* 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): any;

	/**
	* 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: this): 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: any) => any;

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

/**
* This represents the available options for configuring m.request for JSONP
* requests.
*
* @see m.request
*/
export interface JSONPOptions extends RequestOptions {
	/**
	* For JSONP requests, this must be the string "jsonp". Otherwise, it's
	* ignored.
	*/
	dataType: "jsonp";

	/**
	* The querystring key for the JSONP request callback. This is useful for
	* APIs that don't use common conventions, such as
	* `www.example.com/?jsonpCallback=doSomething`. It defaults to
	* `callback`.
	*/
	callbackKey?: string;

	/**
	 * The data to send with the request. This is automatically serialized
	 * to a querystring.
	 */
	data?: Object;
}

/**
* This represents the available options for configuring m.request for
* standard AJAX requests.
*
* @see m.request
*/
export interface XHROptions extends RequestOptions {
	/**
	* This represents the HTTP method used, defaulting to "GET".
	*/
	method: "GET" | "POST" | "PUT" | "DELETE" | "HEAD" | "OPTIONS";

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

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

	/**
	* 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: this): any;

	/**
	 * The data to send with the request.
	 */
	data?: Object;
}