Add class and factory component type definitions. Add JSDoc comments to types.

mithril.d.ts

@@ -5,28 +5,40 @@
 declare namespace Mithril {
 
 	interface Lifecycle<A,S> {
+		/** The oninit hook is called before a vnode is touched by the virtual DOM engine. */
 		oninit?: (this: S, vnode: Vnode<A,S>) => void;
+		/** The oncreate hook is called after a DOM element is created and attached to the document. */
 		oncreate?: (this: S, vnode: VnodeDOM<A,S>) => void;
-		onbeforeremove?: (this: S, vnode: VnodeDOM<A,S>) => Promise<any> | void;
-		onremove?: (this: S, vnode: VnodeDOM<A,S>) => void;
+		/** The onbeforeupdate hook is called before a vnode is diffed in a update. */
 		onbeforeupdate?: (this: S, vnode: Vnode<A,S>, old: Vnode<A,S>) => boolean;
+		/** The onupdate hook is called after a DOM element is updated, while attached to the document. */
 		onupdate?: (this: S, vnode: VnodeDOM<A,S>) => void;
+		/** The onbeforeremove hook is called before a DOM element is detached from the document. If a Promise is returned, Mithril only detaches the DOM element after the promise completes. */
+		onbeforeremove?: (this: S, vnode: VnodeDOM<A,S>) => Promise<any> | void;
+		/** The onremove hook is called before a DOM element is removed from the document. */
+		onremove?: (this: S, vnode: VnodeDOM<A,S>) => void;
 	}
 
 	interface Hyperscript {
+		/** Creates a virtual element (Vnode). */
 		(selector: string, ...children: any[]): Vnode<any,any>;
-		<A,S>(component: Component<A,S>, a?: (A & Lifecycle<A,S>) | Children, ...children: Children[]): Vnode<A,S>;
+		/** Creates a virtual element (Vnode). */
+		<A,S>(component: Component<A,S> | {new(vnode: CVnode<A>): ClassComponent<A>} | FactoryComponent<A,S>, a?: (A & Lifecycle<A,S>) | Children, ...children: Children[]): Vnode<A,S>;
+		/** Creates a fragment virtual element (Vnode). */
 		fragment(attrs: any, children: Children[]): Vnode<any,any>;
+		/** Turns an HTML string into a virtual element (Vnode). Do not use trust on unsanitized user input. */
 		trust(html: string): Vnode<any,any>;
 	}
 
 	interface RouteResolver {
+		/** The onmatch hook is called when the router needs to find a component to render. */
+		onmatch?: (args: any, requestedPath: string) => Mithril.Component<any,any> | {new(vnode: CVnode<any>): ClassComponent<any>} | FactoryComponent<any,any> | Promise<Mithril.Component<any,any> | {new(): Component<any,any>} | FactoryComponent<any,any>> | void;
+		/** The render method is called on every redraw for a matching route. */
 		render?: (vnode: Mithril.Vnode<any,any>) => Children;
-		onmatch?: (args: any, requestedPath: string) => Mithril.Component<any,any> | Promise<Mithril.Component<any,any>> | void;
 	}
 
 	interface RouteDefs {
-		[url: string]: Component<any,any> | RouteResolver;
+		[url: string]: Component<any,any> | {new(vnode: CVnode<any>): ClassComponent<any>} | FactoryComponent<any,any> | RouteResolver;
 	}
 
 	interface RouteOptions {
@@ -36,28 +48,37 @@ declare namespace Mithril {
 	}
 
 	interface Route {
+		/** Creates application routes and mounts Components and/or RouteResolvers to a DOM element. */
 		(element: HTMLElement, defaultRoute: string, routes: RouteDefs): void;
+		/** Returns the last fully resolved routing path, without the prefix. */
 		get(): string;
+		/** Redirects to a matching route or to the default route if no matching routes can be found. */
 		set(route: string, data?: any, options?: RouteOptions): void;
+		/** Defines a router prefix which is a fragment of the URL that dictates the underlying strategy used by the router. */
 		prefix(urlFragment: string): void;
+		/** This method is meant to be used in conjunction with an <a> Vnode's oncreate hook. */
 		link(vnode: Vnode<any,any>): (e: Event) => void;
+		/** Returns the named parameter value from the current route. */
 		param(name?: string): any;
 	}
 
 	interface Mount {
-		(element: Element, component: Component<any,any> | null): void;
+		/** Mounts a component to a DOM element, enabling it to autoredraw on user events. */
+		(element: Element, component: Component<any,any> | {new(vnode: CVnode<any>): ClassComponent<any>} | FactoryComponent<any,any> | null): void;
 	}
 
 	interface WithAttr {
-		<T>(name: string, stream: Stream<T>, thisArg?: any): (e: {currentTarget: any, [p: string]: any}) => boolean;
+		/** Creates an event handler which takes the value of the specified DOM element property and calls a function with it as the argument. */
 		(name: string, callback: (value: any) => void, thisArg?: any): (e: {currentTarget: any, [p: string]: any}) => boolean;
 	}
 
 	interface ParseQueryString {
+		/** Returns an object with key/value pairs parsed from a string of the form: ?a=1&b=2 */
 		(queryString: string): any;
 	}
 
 	interface BuildQueryString {
+		/** Turns the key/value pairs of an object into a string of the form: a=1&b=2 */
 		(values: {[p: string]: any}): string;
 	}
 
@@ -83,7 +104,9 @@ declare namespace Mithril {
 	}
 
 	interface Request {
+		/** Makes an XHR request and returns a promise. */
 		<T>(options: RequestOptionsAll<T>): Promise<T>;
+		/** Makes an XHR request and returns a promise. */
 		<T>(url: string, options?: RequestOptions<T>): Promise<T>;
 	}
 
@@ -100,7 +123,9 @@ declare namespace Mithril {
 	}
 
 	interface Jsonp {
+		/** Makes a JSON-P request and returns a promise. */
 		<T>(options: JsonpOptionsAll): Promise<T>;
+		/** Makes a JSON-P request and returns a promise. */
 		<T>(url: string, options?: JsonpOptions): Promise<T>;
 	}
 
@@ -110,6 +135,7 @@ declare namespace Mithril {
 	}
 
 	interface Render {
+		/** Renders a vnode structure into a DOM element. */
 		(el: Element, vnodes: Children): void;
 	}
 
@@ -118,6 +144,7 @@ declare namespace Mithril {
 	}
 
 	interface Redraw {
+		/** Manually triggers a redraw of mounted components. */
 		(): void;
 	}
 
@@ -160,10 +187,21 @@ declare namespace Mithril {
 		domSize?: number;
 	}
 
+	interface CVnode<A> extends Vnode<A, ClassComponent<A>> {}
+
+	interface CVnodeDOM<A> extends VnodeDOM<A, ClassComponent<A>> {}
+
 	interface Component<A, S extends Lifecycle<A,S>> extends Lifecycle<A,S> {
-		view: (this: S, vnode: Vnode<A,S>) => Vnode<any,any> | null | void | (Vnode<any,any> | null | void)[];
+		view (this: S, vnode: Vnode<A,S>): Vnode<any,any> | null | void | (Vnode<any,any> | null | void)[];
 	}
 
+	interface ClassComponent<A> extends Lifecycle<A,ClassComponent<A>> {
+		view (this: ClassComponent<A>, vnode: CVnode<A>): Vnode<any,any> | null | void | (Vnode<any,any> | null | void)[];
+	}
+
+	// Factory component
+	type FactoryComponent<A,S> = (vnode: Vnode<A,S>) => Component<A,S>
+
 	type Unary<T,U> = (input: T) => U;
 
 	interface Functor<T> {
@@ -172,21 +210,32 @@ declare namespace Mithril {
 	}
 
 	interface Stream<T> {
+		/** Returns the value of the stream. */
 		(): T;
+		/** Sets the value of the stream. */
 		(value: T): this;
+		/** Creates a dependent stream whose value is set to the result of the callback function. */
 		map(f: (current: T) => Stream<T> | T | void): Stream<T>;
+		/** Creates a dependent stream whose value is set to the result of the callback function. */
 		map<U>(f: (current: T) => Stream<U> | U): Stream<U>;
+		/** This method is functionally identical to stream. It exists to conform to Fantasy Land's Applicative specification. */
 		of(val?: T): Stream<T>;
+		/** Apply. */
 		ap<U>(f: Stream<(value: T) => U>): Stream<U>;
+		/** A co-dependent stream that unregisters dependent streams when set to true. */
 		end: Stream<boolean>;
 	}
 
 	type StreamCombiner<T> = (...streams: any[]) => T
 
 	interface StreamFactory {
+		/** Creates a stream. */
 		<T>(val?: T): Stream<T>;
+		/** Creates a computed stream that reactively updates if any of its upstreams are updated. */
 		combine<T>(combiner: StreamCombiner<T>, streams: Stream<any>[]): Stream<T>;
+		/** Creates a stream whose value is the array of values from an array of streams. */
 		merge(streams: Stream<any>[]): Stream<any[]>;
+		/** A special value that can be returned to stream callbacks to halt execution of downstreams. */
 		HALT: any;
 	}
 }