From 7aa3a226d7e0b2d6e2978c495c3566f3f847577c Mon Sep 17 00:00:00 2001 From: Joe Skeen Date: Mon, 28 Sep 2015 16:04:43 -0600 Subject: [PATCH 1/3] Added documentation to browser-sync.d.ts --- browser-sync/browser-sync-tests.ts | 3 +- browser-sync/browser-sync.d.ts | 343 ++++++++++++++++++++++++++--- 2 files changed, 318 insertions(+), 28 deletions(-) diff --git a/browser-sync/browser-sync-tests.ts b/browser-sync/browser-sync-tests.ts index f5c02292c..4b2c0bb54 100644 --- a/browser-sync/browser-sync-tests.ts +++ b/browser-sync/browser-sync-tests.ts @@ -79,9 +79,10 @@ bs.init({ bs.reload(); -function browserSyncInit(): browserSync.BrowserSync { +function browserSyncInit(): typeof browserSync { var browser = browserSync.create(); browser.init(); return browser; } var browser = browserSyncInit(); +browser.exit(); diff --git a/browser-sync/browser-sync.d.ts b/browser-sync/browser-sync.d.ts index 70e8dc1c1..9f081f663 100644 --- a/browser-sync/browser-sync.d.ts +++ b/browser-sync/browser-sync.d.ts @@ -1,6 +1,6 @@ // Type definitions for browser-sync // Project: http://www.browsersync.io/ -// Definitions by: Asana +// Definitions by: Asana , Joe Skeen // Definitions: https://github.com/borisyankov/DefinitelyTyped /// @@ -12,55 +12,280 @@ declare module "browser-sync" { import http = require("http"); interface Options { + /** + * Browsersync includes a user-interface that is accessed via a separate port. The UI allows to controls + * all devices, push sync updates and much more. + * + * port - Default: 3001 + * weinre.port - Default: 8080 + * Note: requires at least version 2.0.0 + */ + ui?: UIOptions; + /** + * Browsersync can watch your files as you work. Changes you make will either be injected into the page (CSS + * & images) or will cause all browsers to do a full-page refresh. See anymatch for more information on glob + * patterns. + * Default: false + */ files?: string | string[]; - watchOptions?: GazeOptions; + /** + * File watching options that get passed along to Chokidar. Check their docs for available options + * Default: undefined + * Note: requires at least version 2.6.0 + */ + watchOptions?: ChokidarOptions; + /** + * Use the built-in static server for basic HTML/JS/CSS websites. + * Default: false + */ server?: ServerOptions; - proxy?: string | boolean; + /** + * Proxy an EXISTING vhost. Browsersync will wrap your vhost with a proxy URL to view your site. + * target - Default: undefined + * ws - Default: undefined + * middleware - Default: undefined + * reqHeaders - Default: undefined + * proxyRes - Default: undefined + */ + proxy?: string | boolean | ProxyOptions; + /** + * Use a specific port (instead of the one auto-detected by Browsersync) + * Default: 3000 + */ port?: number; + /** + * Add additional directories from which static files should be served. + * Should only be used in proxy or snippet mode. + * Default: [] + * Note: requires at least version 2.8.0 + */ + serveStatic?: string[]; + /** + * Enable https for localhost development. + * Note - this is not needed for proxy option as it will be inferred from your target url. + * Note: requires at least version 1.3.0 + */ https?: boolean; + /** + * Clicks, Scrolls & Form inputs on any device will be mirrored to all others. + * clicks - Default: true + * scroll - Default: true + * forms - Default: true + */ ghostMode?: GhostOptions | boolean; + /** + * Can be either "info", "debug", "warn", or "silent" + * Default: info + */ logLevel?: string; + /** + * Change the console logging prefix. Useful if you're creating your own project based on Browsersync + * Default: BS + * Note: requires at least version 1.5.1 + */ logPrefix?: string; + /** + * Whether or not to log connections + * Default: false + */ logConnections?: boolean; + /** + * Whether or not to log information about changed files + * Default: false + */ logFileChanges?: boolean; + /** + * Log the snippet to the console when you're in snippet mode (no proxy/server) + * Default: true + * Note: requires at least version 1.5.2 + */ logSnippet?: boolean; + /** + * You can control how the snippet is injected onto each page via a custom regex + function. + * You can also provide patterns for certain urls that should be ignored from the snippet injection. + * Note: requires at least version 2.0.0 + */ snippetOptions?: SnippetOptions; + /** + * Add additional HTML rewriting rules. + * Default: false + * Note: requires at least version 2.4.0 + */ rewriteRules?: boolean | RewriteRules[]; + /** + * Tunnel the Browsersync server through a random Public URL + * Default: null + */ tunnel?: string | boolean; + /** + * Some features of Browsersync (such as xip & tunnel) require an internet connection, but if you're + * working offline, you can reduce start-up time by setting this option to false + */ online?: boolean; + /** + * Default: true + * Decide which URL to open automatically when Browsersync starts. Defaults to "local" if none set. + * Can be true, local, external, ui, ui-external, tunnel or false + */ open?: string | boolean; + /** + * The browser(s) to open + * Default: default + */ browser?: string | string[]; + /** + * Requires an internet connection - useful for services such as Typekit as it allows you to configure + * domains such as *.xip.io in your kit settings + * Default: false + */ xip?: boolean; + /** + * Reload each browser when Browsersync is restarted. + * Default: false + */ + reloadOnRestart?: boolean; + /** + * The small pop-over notifications in the browser are not always needed/wanted. + * Default: true + */ notify?: boolean; - scrollProportionally?: boolean; + /** + * scrollProportionally: false // Sync viewports to TOP position + * Default: true + */ + scrollProportionally?: boolean + /** + * How often to send scroll events + * Default: 0 + */ scrollThrottle?: number; + /** + * Decide which technique should be used to restore scroll position following a reload. + * Can be window.name or cookie + * Default: 'window.name' + */ + scrollRestoreTechnique?: string; + /** + * Sync the scroll position of any element on the page. Add any amount of CSS selectors + * Default: [] + * Note: requires at least version 2.9.0 + */ + scrollElements?: string[]; + /** + * Default: [] + * Note: requires at least version 2.9.0 + * Sync the scroll position of any element on the page - where any scrolled element will cause + * all others to match scroll position. This is helpful when a breakpoint alters which element + * is actually scrolling + */ + scrollElementMapping?: string[]; + /** + * Time, in milliseconds, to wait before instructing the browser to reload/inject following a file change event + * Default: 0 + */ reloadDelay?: number; + /** + * Restrict the frequency in which browser:reload events can be emitted to connected clients + * Default: 0 + * Note: requires at least version 2.6.0 + */ reloadDebounce?: number; + /** + * User provided plugins + * Default: [] + * Note: requires at least version 2.6.0 + */ plugins?: any[]; + /** + * Whether to inject changes (rather than a page refresh) + * Default: true + */ injectChanges?: boolean; + /** + * The initial path to load + */ startPath?: string; + /** + * Whether to minify the client script + * Default: true + */ minify?: boolean; + /** + * Override host detection if you know the correct IP to use + */ host?: string; + /** + * Send file-change events to the browser + * Default: true + */ codeSync?: boolean; + /** + * Append timestamps to injected files + * Default: true + */ timestamps?: boolean; + /** + * Alter the script path for complete control over where the Browsersync Javascript is served + * from. Whatever you return from this function will be used as the script path. + * Note: requires at least version 1.5.0 + */ scriptPath?: (path: string) => string; + /** + * Configure the Socket.IO path and namespace & domain to avoid collisions. + * path - Default: "/browser-sync/socket.io" + * clientPath - Default: "/browser-sync" + * namespace - Default: "/browser-sync" + * domain - Default: undefined + * port - Default: undefined + * clients.heartbeatTimeout - Default: 5000 + * Note: requires at least version 1.6.2 + */ socket?: SocketOptions; } - interface GazeOptions { + interface Hash { + [path: string]: T; + } + + interface ChokidarOptions { interval?: number; debounceDelay?: number; mode?: string; cwd?: string; } + + interface UIOptions { + /** set the default port */ + port?: number; + /** set the default weinre port */ + weinre?: { + port?: number; + }; + } interface ServerOptions { + /** set base directory */ baseDir?: string | string[]; + /** enable directory listing */ directory?: boolean; + /** set index filename */ index?: string; - routes?: {[path: string]: string}; + /** + * key-value object hash, where the key is the url to match, + * and the value is the folder to serve (relative to your working directory) + * */ + routes?: Hash; + /** configure custom middleware */ middleware?: MiddlewareHandler[]; } + + interface ProxyOptions { + target?: string; + middleware?: MiddlewareHandler; + ws: boolean; + reqHeaders: (config) => Hash; + proxyRes: (res: http.ServerResponse, req: http.ServerRequest, next: Function) => any; + } interface MiddlewareHandler { (req: http.ServerRequest, res: http.ServerResponse, next: Function): any; @@ -81,6 +306,9 @@ declare module "browser-sync" { path?: string; clientPath?: string; namespace?: string; + domain?: string; + port?: number; + clients?: { heartbeatTimeout?: number; }; } interface RewriteRules { @@ -88,30 +316,91 @@ declare module "browser-sync" { fn: (match: string) => string; } - module browserSync { - interface BrowserSync { - init(config?: Options, callback?: (err: Error, bs: Object) => any): void; - reload(): void; - reload(file: string): void; - reload(files: string[]): void; - reload(options: {stream: boolean}): NodeJS.ReadWriteStream; - notify(message: string, timeout?: number): void; - exit(): void; - watch(patterns: string, opts?: chokidar.WatchOptions, fn?: (event: string, file: fs.Stats) => any): NodeJS.EventEmitter; - pause(): void; - resume(): void; - emitter: NodeJS.EventEmitter; - active: boolean; - paused: boolean; - } - } - - interface Exports extends browserSync.BrowserSync { - create(): browserSync.BrowserSync; + + interface BrowserSync { (config?: Options, callback?: (err: Error, bs: Object) => any): void; + /** + * Create a Browsersync instance + * @param name an identifier that can used for retrieval later + */ + create(name?: string): BrowserSync; + /** + * Get a single instance by name. This is useful if you have your build scripts in separate files + * @param name the identifier used for retrieval + */ + get(name: string): BrowserSync; + /** + * Start the Browsersync service. This will launch a server, proxy or start the snippet mode + * depending on your use-case. + */ + init(config?: Options, callback?: (err: Error, bs: Object) => any): void; + /** + * Reload the browser + * The reload method will inform all browsers about changed files and will either cause the browser + * to refresh, or inject the files where possible. + */ + reload(): void; + /** + * Reload a single file + * The reload method will inform all browsers about changed files and will either cause the browser + * to refresh, or inject the files where possible. + */ + reload(file: string): void; + /** + * Reload multiple files + * The reload method will inform all browsers about changed files and will either cause the browser + * to refresh, or inject the files where possible. + */ + reload(files: string[]): void; + /** + * The reload method will inform all browsers about changed files and will either cause the browser + * to refresh, or inject the files where possible. + */ + reload(options: {stream: boolean}): NodeJS.ReadWriteStream; + /** + * The stream method returns a transform stream and can act once or on many files. + * @param opts Configuration for the stream method + */ + stream(opts: {once: boolean}): NodeJS.ReadWriteStream; + /** + * Helper method for browser notifications + * @param message Can be a simple message such as 'Connected' or HTML + * @param timeout How long the message will remain in the browser. @since 1.3.0 + */ + notify(message: string, timeout?: number): void; + /** + * This method will close any running server, stop file watching & exit the current process. + */ + exit(): void; + /** + * Stand alone file-watcher. Use this along with Browsersync to create your own, minimal build system + */ + watch(patterns: string, opts?: chokidar.WatchOptions, fn?: (event: string, file: fs.Stats) => any) + : NodeJS.EventEmitter; + /** + * Method to pause file change events + */ + pause(): void; + /** + * Method to resume paused watchers + */ + resume(): void; + /** + * The internal Event Emitter used by the running Browsersync instance (if there is one). You can use + * this to emit your own events, such as changed files, logging etc. + */ + emitter: NodeJS.EventEmitter; + /** + * A simple true/false flag that you can use to determine if there's a currently-running Browsersync instance. + */ + active: boolean; + /** + * A simple true/false flag to determine if the current instance is paused + */ + paused: boolean; } - var browserSync: Exports; + const browserSync: BrowserSync; export = browserSync; } From 596a8af137b4129d2253003952f2840d7f7633a7 Mon Sep 17 00:00:00 2001 From: Joe Skeen Date: Mon, 28 Sep 2015 16:17:56 -0600 Subject: [PATCH 2/3] Fix implicit 'any' --- browser-sync/browser-sync.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/browser-sync/browser-sync.d.ts b/browser-sync/browser-sync.d.ts index 9f081f663..f189f4ac0 100644 --- a/browser-sync/browser-sync.d.ts +++ b/browser-sync/browser-sync.d.ts @@ -283,7 +283,7 @@ declare module "browser-sync" { target?: string; middleware?: MiddlewareHandler; ws: boolean; - reqHeaders: (config) => Hash; + reqHeaders: (config: any) => Hash; proxyRes: (res: http.ServerResponse, req: http.ServerRequest, next: Function) => any; } From de62c4326435c86ffe5ab90de8d980a7ce61f2b6 Mon Sep 17 00:00:00 2001 From: Joe Skeen Date: Wed, 30 Sep 2015 08:07:12 -0600 Subject: [PATCH 3/3] Fixed problem with using static BrowserSync functions on an instance causing a runtime error --- browser-sync/browser-sync-tests.ts | 4 +++- browser-sync/browser-sync.d.ts | 38 ++++++++++++++++++------------ 2 files changed, 26 insertions(+), 16 deletions(-) diff --git a/browser-sync/browser-sync-tests.ts b/browser-sync/browser-sync-tests.ts index 4b2c0bb54..50042410f 100644 --- a/browser-sync/browser-sync-tests.ts +++ b/browser-sync/browser-sync-tests.ts @@ -79,9 +79,11 @@ bs.init({ bs.reload(); -function browserSyncInit(): typeof browserSync { +function browserSyncInit() { var browser = browserSync.create(); browser.init(); + console.log(browser.name); + console.log(browserSync.name); return browser; } var browser = browserSyncInit(); diff --git a/browser-sync/browser-sync.d.ts b/browser-sync/browser-sync.d.ts index f189f4ac0..03b751fab 100644 --- a/browser-sync/browser-sync.d.ts +++ b/browser-sync/browser-sync.d.ts @@ -316,24 +316,32 @@ declare module "browser-sync" { fn: (match: string) => string; } - - interface BrowserSync { - (config?: Options, callback?: (err: Error, bs: Object) => any): void; - /** - * Create a Browsersync instance - * @param name an identifier that can used for retrieval later - */ - create(name?: string): BrowserSync; - /** - * Get a single instance by name. This is useful if you have your build scripts in separate files - * @param name the identifier used for retrieval - */ - get(name: string): BrowserSync; + interface BrowserSyncStatic extends BrowserSyncInstance { /** * Start the Browsersync service. This will launch a server, proxy or start the snippet mode * depending on your use-case. */ - init(config?: Options, callback?: (err: Error, bs: Object) => any): void; + (config?: Options, callback?: (err: Error, bs: Object) => any): BrowserSyncInstance; + /** + * Create a Browsersync instance + * @param name an identifier that can used for retrieval later + */ + create(name?: string): BrowserSyncInstance; + /** + * Get a single instance by name. This is useful if you have your build scripts in separate files + * @param name the identifier used for retrieval + */ + get(name: string): BrowserSyncInstance; + } + + interface BrowserSyncInstance { + /** the name of this instance of browser-sync */ + name: string; + /** + * Start the Browsersync service. This will launch a server, proxy or start the snippet mode + * depending on your use-case. + */ + init(config?: Options, callback?: (err: Error, bs: Object) => any): BrowserSyncInstance; /** * Reload the browser * The reload method will inform all browsers about changed files and will either cause the browser @@ -400,7 +408,7 @@ declare module "browser-sync" { paused: boolean; } - const browserSync: BrowserSync; + const browserSync: BrowserSyncStatic; export = browserSync; }