From b3615aa607097cfcf70bc4ffe1afcd3807159df7 Mon Sep 17 00:00:00 2001 From: spacejack Date: Sat, 18 Feb 2017 08:44:01 -0500 Subject: [PATCH] Add class and factory component type definitions. Add JSDoc comments to types. --- mithril.d.ts | 65 +++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 57 insertions(+), 8 deletions(-) diff --git a/mithril.d.ts b/mithril.d.ts index b5a74cf2..37179e16 100644 --- a/mithril.d.ts +++ b/mithril.d.ts @@ -5,28 +5,40 @@ declare namespace Mithril { interface Lifecycle { + /** The oninit hook is called before a vnode is touched by the virtual DOM engine. */ oninit?: (this: S, vnode: Vnode) => void; + /** The oncreate hook is called after a DOM element is created and attached to the document. */ oncreate?: (this: S, vnode: VnodeDOM) => void; - onbeforeremove?: (this: S, vnode: VnodeDOM) => Promise | void; - onremove?: (this: S, vnode: VnodeDOM) => void; + /** The onbeforeupdate hook is called before a vnode is diffed in a update. */ onbeforeupdate?: (this: S, vnode: Vnode, old: Vnode) => boolean; + /** The onupdate hook is called after a DOM element is updated, while attached to the document. */ onupdate?: (this: S, vnode: VnodeDOM) => 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) => Promise | void; + /** The onremove hook is called before a DOM element is removed from the document. */ + onremove?: (this: S, vnode: VnodeDOM) => void; } interface Hyperscript { + /** Creates a virtual element (Vnode). */ (selector: string, ...children: any[]): Vnode; - (component: Component, a?: (A & Lifecycle) | Children, ...children: Children[]): Vnode; + /** Creates a virtual element (Vnode). */ + (component: Component | {new(vnode: CVnode): ClassComponent} | FactoryComponent, a?: (A & Lifecycle) | Children, ...children: Children[]): Vnode; + /** Creates a fragment virtual element (Vnode). */ fragment(attrs: any, children: Children[]): Vnode; + /** Turns an HTML string into a virtual element (Vnode). Do not use trust on unsanitized user input. */ trust(html: string): Vnode; } interface RouteResolver { + /** The onmatch hook is called when the router needs to find a component to render. */ + onmatch?: (args: any, requestedPath: string) => Mithril.Component | {new(vnode: CVnode): ClassComponent} | FactoryComponent | Promise | {new(): Component} | FactoryComponent> | void; + /** The render method is called on every redraw for a matching route. */ render?: (vnode: Mithril.Vnode) => Children; - onmatch?: (args: any, requestedPath: string) => Mithril.Component | Promise> | void; } interface RouteDefs { - [url: string]: Component | RouteResolver; + [url: string]: Component | {new(vnode: CVnode): ClassComponent} | FactoryComponent | 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 Vnode's oncreate hook. */ link(vnode: Vnode): (e: Event) => void; + /** Returns the named parameter value from the current route. */ param(name?: string): any; } interface Mount { - (element: Element, component: Component | null): void; + /** Mounts a component to a DOM element, enabling it to autoredraw on user events. */ + (element: Element, component: Component | {new(vnode: CVnode): ClassComponent} | FactoryComponent | null): void; } interface WithAttr { - (name: string, stream: Stream, 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. */ (options: RequestOptionsAll): Promise; + /** Makes an XHR request and returns a promise. */ (url: string, options?: RequestOptions): Promise; } @@ -100,7 +123,9 @@ declare namespace Mithril { } interface Jsonp { + /** Makes a JSON-P request and returns a promise. */ (options: JsonpOptionsAll): Promise; + /** Makes a JSON-P request and returns a promise. */ (url: string, options?: JsonpOptions): Promise; } @@ -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 extends Vnode> {} + + interface CVnodeDOM extends VnodeDOM> {} + interface Component> extends Lifecycle { - view: (this: S, vnode: Vnode) => Vnode | null | void | (Vnode | null | void)[]; + view (this: S, vnode: Vnode): Vnode | null | void | (Vnode | null | void)[]; } + interface ClassComponent extends Lifecycle> { + view (this: ClassComponent, vnode: CVnode): Vnode | null | void | (Vnode | null | void)[]; + } + + // Factory component + type FactoryComponent = (vnode: Vnode) => Component + type Unary = (input: T) => U; interface Functor { @@ -172,21 +210,32 @@ declare namespace Mithril { } interface Stream { + /** 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 | void): Stream; + /** Creates a dependent stream whose value is set to the result of the callback function. */ map(f: (current: T) => Stream | U): Stream; + /** This method is functionally identical to stream. It exists to conform to Fantasy Land's Applicative specification. */ of(val?: T): Stream; + /** Apply. */ ap(f: Stream<(value: T) => U>): Stream; + /** A co-dependent stream that unregisters dependent streams when set to true. */ end: Stream; } type StreamCombiner = (...streams: any[]) => T interface StreamFactory { + /** Creates a stream. */ (val?: T): Stream; + /** Creates a computed stream that reactively updates if any of its upstreams are updated. */ combine(combiner: StreamCombiner, streams: Stream[]): Stream; + /** Creates a stream whose value is the array of values from an array of streams. */ merge(streams: Stream[]): Stream; + /** A special value that can be returned to stream callbacks to halt execution of downstreams. */ HALT: any; } }