From 66c4b6e1f0dff4cdf4c71bb4bde49aac1be831ef Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 10:44:52 +0100 Subject: [PATCH 01/16] chore: vendor Mitt into src/common/third-party As discussed in #6203 we need to vendor our common dependencies in so that when we ship an ESM build all imports point to file paths and do not rely on Node resolution (e.g. a browser does not understand `import mitt from 'mitt'`). --- .eslintignore | 1 + .eslintrc.js | 6 + src/common/EventEmitter.ts | 6 +- src/common/third-party/mitt/README.md | 171 ++++++++++++++++++ src/common/third-party/mitt/dist/index.d.ts | 19 ++ src/common/third-party/mitt/dist/mitt.es.js | 2 + .../third-party/mitt/dist/mitt.es.js.map | 1 + src/common/third-party/mitt/dist/mitt.js | 2 + src/common/third-party/mitt/dist/mitt.js.map | 1 + .../third-party/mitt/dist/mitt.modern.js | 2 + .../third-party/mitt/dist/mitt.modern.js.map | 1 + src/common/third-party/mitt/dist/mitt.umd.js | 2 + .../third-party/mitt/dist/mitt.umd.js.map | 1 + src/common/third-party/mitt/package.json | 125 +++++++++++++ src/common/third-party/mitt/src/index.ts | 78 ++++++++ tsconfig.json | 3 + 16 files changed, 420 insertions(+), 1 deletion(-) create mode 100644 src/common/third-party/mitt/README.md create mode 100644 src/common/third-party/mitt/dist/index.d.ts create mode 100644 src/common/third-party/mitt/dist/mitt.es.js create mode 100644 src/common/third-party/mitt/dist/mitt.es.js.map create mode 100644 src/common/third-party/mitt/dist/mitt.js create mode 100644 src/common/third-party/mitt/dist/mitt.js.map create mode 100644 src/common/third-party/mitt/dist/mitt.modern.js create mode 100644 src/common/third-party/mitt/dist/mitt.modern.js.map create mode 100644 src/common/third-party/mitt/dist/mitt.umd.js create mode 100644 src/common/third-party/mitt/dist/mitt.umd.js.map create mode 100644 src/common/third-party/mitt/package.json create mode 100644 src/common/third-party/mitt/src/index.ts diff --git a/.eslintignore b/.eslintignore index 758aeb91ddbf8..ef6d583e01198 100644 --- a/.eslintignore +++ b/.eslintignore @@ -10,3 +10,4 @@ lib/ # We ignore this file because it uses ES imports which we don't yet use # in the Puppeteer src, so it trips up the ESLint-TypeScript parser. utils/doclint/generate_types/test/test.ts +src/common/third-party/ diff --git a/.eslintrc.js b/.eslintrc.js index bc63a76df3c07..bc67644f3affd 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -87,8 +87,14 @@ module.exports = { // enforce the variable in a catch block is named error "unicorn/catch-error-name": "error", + "no-restricted-imports": ["error", { patterns: ["*Events"], + paths: [{ + name: "mitt", + message: + "Import Mitt from the vendored location: src/common/third-party/mitt/src/index.js", + }], }], "import/extensions": ["error", "ignorePackages"] }, diff --git a/src/common/EventEmitter.ts b/src/common/EventEmitter.ts index 73d7787cd533c..29d434d2fe86d 100644 --- a/src/common/EventEmitter.ts +++ b/src/common/EventEmitter.ts @@ -1,4 +1,8 @@ -import mitt, { Emitter, EventType, Handler } from 'mitt'; +import mitt, { + Emitter, + EventType, + Handler, +} from './third-party/mitt/src/index.js'; /** * @internal diff --git a/src/common/third-party/mitt/README.md b/src/common/third-party/mitt/README.md new file mode 100644 index 0000000000000..b6a80225dfe32 --- /dev/null +++ b/src/common/third-party/mitt/README.md @@ -0,0 +1,171 @@ +

+ mitt +
+ npm + build status + gzip size +

+ +# Mitt + +> Tiny 200b functional event emitter / pubsub. + +- **Microscopic:** weighs less than 200 bytes gzipped +- **Useful:** a wildcard `"*"` event type listens to all events +- **Familiar:** same names & ideas as [Node's EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter) +- **Functional:** methods don't rely on `this` +- **Great Name:** somehow [mitt](https://npm.im/mitt) wasn't taken + +Mitt was made for the browser, but works in any JavaScript runtime. It has no dependencies and supports IE9+. + +## Table of Contents + +- [Install](#install) +- [Usage](#usage) +- [Examples & Demos](#examples--demos) +- [API](#api) +- [Contribute](#contribute) +- [License](#license) + +## Install + +This project uses [node](http://nodejs.org) and [npm](https://npmjs.com). Go check them out if you don't have them locally installed. + +```sh +$ npm install --save mitt +``` + +Then with a module bundler like [rollup](http://rollupjs.org/) or [webpack](https://webpack.js.org/), use as you would anything else: + +```javascript +// using ES6 modules +import mitt from 'mitt' + +// using CommonJS modules +var mitt = require('mitt') +``` + +The [UMD](https://github.com/umdjs/umd) build is also available on [unpkg](https://unpkg.com): + +```html + +``` + +You can find the library on `window.mitt`. + +## Usage + +```js +import mitt from 'mitt' + +const emitter = mitt() + +// listen to an event +emitter.on('foo', e => console.log('foo', e) ) + +// listen to all events +emitter.on('*', (type, e) => console.log(type, e) ) + +// fire an event +emitter.emit('foo', { a: 'b' }) + +// working with handler references: +function onFoo() {} +emitter.on('foo', onFoo) // listen +emitter.off('foo', onFoo) // unlisten +``` + +### Typescript + +```ts +import mitt from 'mitt'; +const emitter: mitt.Emitter = mitt(); +``` + +## Examples & Demos + + + Preact + Mitt Codepen Demo +
+ preact + mitt preview + + +* * * + +## API + + + +#### Table of Contents + +- [mitt](#mitt) +- [on](#on) + - [Parameters](#parameters) +- [off](#off) + - [Parameters](#parameters-1) +- [emit](#emit) + - [Parameters](#parameters-2) + +### mitt + +Mitt: Tiny (~200b) functional event emitter / pubsub. + +Returns **Mitt** + +### on + +Register an event handler for the given type. + +#### Parameters + +- `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to listen for, or `"*"` for all events +- `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Function to call in response to given event + +### off + +Remove an event handler for the given type. + +#### Parameters + +- `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** Type of event to unregister `handler` from, or `"*"` +- `handler` **[Function](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function)** Handler function to remove + +### emit + +Invoke all handlers for the given type. +If present, `"*"` handlers are invoked after type-matched handlers. + +Note: Manually firing "\*" handlers is not supported. + +#### Parameters + +- `type` **([string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String) \| [symbol](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Symbol))** The event type to invoke +- `evt` **Any?** Any value (object is recommended and powerful), passed to each handler + +## Contribute + +First off, thanks for taking the time to contribute! +Now, take a moment to be sure your contributions make sense to everyone else. + +### Reporting Issues + +Found a problem? Want a new feature? First of all see if your issue or idea has [already been reported](../../issues). +If don't, just open a [new clear and descriptive issue](../../issues/new). + +### Submitting pull requests + +Pull requests are the greatest contributions, so be sure they are focused in scope, and do avoid unrelated commits. + +- Fork it! +- Clone your fork: `git clone https://github.com//mitt` +- Navigate to the newly cloned directory: `cd mitt` +- Create a new branch for the new feature: `git checkout -b my-new-feature` +- Install the tools necessary for development: `npm install` +- Make your changes. +- Commit your changes: `git commit -am 'Add some feature'` +- Push to the branch: `git push origin my-new-feature` +- Submit a pull request with full remarks documenting your changes. + +## License + +[MIT License](https://opensource.org/licenses/MIT) © [Jason Miller](https://jasonformat.com/) diff --git a/src/common/third-party/mitt/dist/index.d.ts b/src/common/third-party/mitt/dist/index.d.ts new file mode 100644 index 0000000000000..b37905bcf57f9 --- /dev/null +++ b/src/common/third-party/mitt/dist/index.d.ts @@ -0,0 +1,19 @@ +export declare type EventType = string | symbol; +export declare type Handler = (event?: any) => void; +export declare type WildcardHandler = (type: EventType, event?: any) => void; +export declare type EventHandlerList = Array; +export declare type WildCardEventHandlerList = Array; +export declare type EventHandlerMap = Map; +export interface Emitter { + on(type: EventType, handler: Handler): void; + on(type: '*', handler: WildcardHandler): void; + off(type: EventType, handler: Handler): void; + off(type: '*', handler: WildcardHandler): void; + emit(type: EventType, event?: T): void; + emit(type: '*', event?: any): void; +} +/** Mitt: Tiny (~200b) functional event emitter / pubsub. + * @name mitt + * @returns {Mitt} + */ +export default function mitt(all?: EventHandlerMap): Emitter; diff --git a/src/common/third-party/mitt/dist/mitt.es.js b/src/common/third-party/mitt/dist/mitt.es.js new file mode 100644 index 0000000000000..74aaf3a2413c1 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.es.js @@ -0,0 +1,2 @@ +export default function(n){return n=n||new Map,{on:function(t,e){var i=n.get(t);i&&i.push(e)||n.set(t,[e])},off:function(t,e){var i=n.get(t);i&&i.splice(i.indexOf(e)>>>0,1)},emit:function(t,e){(n.get(t)||[]).slice().map(function(n){n(e)}),(n.get("*")||[]).slice().map(function(n){n(t,e)})}}} +//# sourceMappingURL=mitt.es.js.map diff --git a/src/common/third-party/mitt/dist/mitt.es.js.map b/src/common/third-party/mitt/dist/mitt.es.js.map new file mode 100644 index 0000000000000..0f1670de46272 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.es.js.map @@ -0,0 +1 @@ +{"version":3,"file":"mitt.es.js","sources":["../src/index.ts"],"sourcesContent":["export type EventType = string | symbol;\n\n// An event handler can take an optional event argument\n// and should not return a value\nexport type Handler = (event?: any) => void;\nexport type WildcardHandler= (type: EventType, event?: any) => void\n\n// An array of all currently registered event handlers for a type\nexport type EventHandlerList = Array;\nexport type WildCardEventHandlerList = Array;\n\n// A map of event types and their corresponding event handlers.\nexport type EventHandlerMap = Map;\n\nexport interface Emitter {\n\ton(type: EventType, handler: Handler): void;\n\ton(type: '*', handler: WildcardHandler): void;\n\n\toff(type: EventType, handler: Handler): void;\n\toff(type: '*', handler: WildcardHandler): void;\n\n\temit(type: EventType, event?: T): void;\n\temit(type: '*', event?: any): void;\n}\n\n/** Mitt: Tiny (~200b) functional event emitter / pubsub.\n * @name mitt\n * @returns {Mitt}\n */\nexport default function mitt(all?: EventHandlerMap): Emitter {\n\tall = all || new Map();\n\n\treturn {\n\n\t\t/**\n\t\t * Register an event handler for the given type.\n\t\t * @param {string|symbol} type Type of event to listen for, or `\"*\"` for all events\n\t\t * @param {Function} handler Function to call in response to given event\n\t\t * @memberOf mitt\n\t\t */\n\t\ton(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tconst added = handlers && handlers.push(handler);\n\t\t\tif (!added) {\n\t\t\t\tall.set(type, [handler]);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Remove an event handler for the given type.\n\t\t *\n\t\t * @param {string|symbol} type Type of event to unregister `handler` from, or `\"*\"`\n\t\t * @param {Function} handler Handler function to remove\n\t\t * @memberOf mitt\n\t\t */\n\t\toff(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tif (handlers) {\n\t\t\t\thandlers.splice(handlers.indexOf(handler) >>> 0, 1);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Invoke all handlers for the given type.\n\t\t * If present, `\"*\"` handlers are invoked after type-matched handlers.\n\t\t *\n\t\t * Note: Manually firing \"*\" handlers is not supported.\n\t\t *\n\t\t * @param {string|symbol} type The event type to invoke\n\t\t * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler\n\t\t * @memberOf mitt\n\t\t */\n\t\temit(type: EventType, evt: any) {\n\t\t\t((all.get(type) || []) as EventHandlerList).slice().map((handler) => { handler(evt); });\n\t\t\t((all.get('*') || []) as WildCardEventHandlerList).slice().map((handler) => { handler(type, evt); });\n\t\t}\n\t};\n}\n"],"names":["all","Map","on","type","handler","handlers","get","push","set","off","splice","indexOf","emit","evt","slice","map"],"mappings":"wBA6B6BA,GAG5B,OAFAA,EAAMA,GAAO,IAAIC,IAEV,CAQNC,YAAGC,EAAiBC,GACnB,IAAMC,EAAWL,EAAIM,IAAIH,GACXE,GAAYA,EAASE,KAAKH,IAEvCJ,EAAIQ,IAAIL,EAAM,CAACC,KAWjBK,aAAIN,EAAiBC,GACpB,IAAMC,EAAWL,EAAIM,IAAIH,GACrBE,GACHA,EAASK,OAAOL,EAASM,QAAQP,KAAa,EAAG,IAcnDQ,cAAKT,EAAiBU,IACnBb,EAAIM,IAAIH,IAAS,IAAyBW,QAAQC,IAAI,SAACX,GAAcA,EAAQS,MAC7Eb,EAAIM,IAAI,MAAQ,IAAiCQ,QAAQC,IAAI,SAACX,GAAcA,EAAQD,EAAMU"} \ No newline at end of file diff --git a/src/common/third-party/mitt/dist/mitt.js b/src/common/third-party/mitt/dist/mitt.js new file mode 100644 index 0000000000000..fdfe692346d73 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.js @@ -0,0 +1,2 @@ +module.exports=function(n){return n=n||new Map,{on:function(e,t){var i=n.get(e);i&&i.push(t)||n.set(e,[t])},off:function(e,t){var i=n.get(e);i&&i.splice(i.indexOf(t)>>>0,1)},emit:function(e,t){(n.get(e)||[]).slice().map(function(n){n(t)}),(n.get("*")||[]).slice().map(function(n){n(e,t)})}}}; +//# sourceMappingURL=mitt.js.map diff --git a/src/common/third-party/mitt/dist/mitt.js.map b/src/common/third-party/mitt/dist/mitt.js.map new file mode 100644 index 0000000000000..e5d45cedaccc2 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.js.map @@ -0,0 +1 @@ +{"version":3,"file":"mitt.js","sources":["../src/index.ts"],"sourcesContent":["export type EventType = string | symbol;\n\n// An event handler can take an optional event argument\n// and should not return a value\nexport type Handler = (event?: any) => void;\nexport type WildcardHandler= (type: EventType, event?: any) => void\n\n// An array of all currently registered event handlers for a type\nexport type EventHandlerList = Array;\nexport type WildCardEventHandlerList = Array;\n\n// A map of event types and their corresponding event handlers.\nexport type EventHandlerMap = Map;\n\nexport interface Emitter {\n\ton(type: EventType, handler: Handler): void;\n\ton(type: '*', handler: WildcardHandler): void;\n\n\toff(type: EventType, handler: Handler): void;\n\toff(type: '*', handler: WildcardHandler): void;\n\n\temit(type: EventType, event?: T): void;\n\temit(type: '*', event?: any): void;\n}\n\n/** Mitt: Tiny (~200b) functional event emitter / pubsub.\n * @name mitt\n * @returns {Mitt}\n */\nexport default function mitt(all?: EventHandlerMap): Emitter {\n\tall = all || new Map();\n\n\treturn {\n\n\t\t/**\n\t\t * Register an event handler for the given type.\n\t\t * @param {string|symbol} type Type of event to listen for, or `\"*\"` for all events\n\t\t * @param {Function} handler Function to call in response to given event\n\t\t * @memberOf mitt\n\t\t */\n\t\ton(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tconst added = handlers && handlers.push(handler);\n\t\t\tif (!added) {\n\t\t\t\tall.set(type, [handler]);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Remove an event handler for the given type.\n\t\t *\n\t\t * @param {string|symbol} type Type of event to unregister `handler` from, or `\"*\"`\n\t\t * @param {Function} handler Handler function to remove\n\t\t * @memberOf mitt\n\t\t */\n\t\toff(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tif (handlers) {\n\t\t\t\thandlers.splice(handlers.indexOf(handler) >>> 0, 1);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Invoke all handlers for the given type.\n\t\t * If present, `\"*\"` handlers are invoked after type-matched handlers.\n\t\t *\n\t\t * Note: Manually firing \"*\" handlers is not supported.\n\t\t *\n\t\t * @param {string|symbol} type The event type to invoke\n\t\t * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler\n\t\t * @memberOf mitt\n\t\t */\n\t\temit(type: EventType, evt: any) {\n\t\t\t((all.get(type) || []) as EventHandlerList).slice().map((handler) => { handler(evt); });\n\t\t\t((all.get('*') || []) as WildCardEventHandlerList).slice().map((handler) => { handler(type, evt); });\n\t\t}\n\t};\n}\n"],"names":["all","Map","on","type","handler","handlers","get","push","set","off","splice","indexOf","emit","evt","slice","map"],"mappings":"wBA6B6BA,GAG5B,OAFAA,EAAMA,GAAO,IAAIC,IAEV,CAQNC,YAAGC,EAAiBC,GACnB,IAAMC,EAAWL,EAAIM,IAAIH,GACXE,GAAYA,EAASE,KAAKH,IAEvCJ,EAAIQ,IAAIL,EAAM,CAACC,KAWjBK,aAAIN,EAAiBC,GACpB,IAAMC,EAAWL,EAAIM,IAAIH,GACrBE,GACHA,EAASK,OAAOL,EAASM,QAAQP,KAAa,EAAG,IAcnDQ,cAAKT,EAAiBU,IACnBb,EAAIM,IAAIH,IAAS,IAAyBW,QAAQC,IAAI,SAACX,GAAcA,EAAQS,MAC7Eb,EAAIM,IAAI,MAAQ,IAAiCQ,QAAQC,IAAI,SAACX,GAAcA,EAAQD,EAAMU"} \ No newline at end of file diff --git a/src/common/third-party/mitt/dist/mitt.modern.js b/src/common/third-party/mitt/dist/mitt.modern.js new file mode 100644 index 0000000000000..ccafa5a569689 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.modern.js @@ -0,0 +1,2 @@ +export default function(e){return e=e||new Map,{on(t,n){const s=e.get(t);s&&s.push(n)||e.set(t,[n])},off(t,n){const s=e.get(t);s&&s.splice(s.indexOf(n)>>>0,1)},emit(t,n){(e.get(t)||[]).slice().map(e=>{e(n)}),(e.get("*")||[]).slice().map(e=>{e(t,n)})}}} +//# sourceMappingURL=mitt.modern.js.map diff --git a/src/common/third-party/mitt/dist/mitt.modern.js.map b/src/common/third-party/mitt/dist/mitt.modern.js.map new file mode 100644 index 0000000000000..650d79e5b50a9 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.modern.js.map @@ -0,0 +1 @@ +{"version":3,"file":"mitt.modern.js","sources":["../src/index.ts"],"sourcesContent":["export type EventType = string | symbol;\n\n// An event handler can take an optional event argument\n// and should not return a value\nexport type Handler = (event?: any) => void;\nexport type WildcardHandler= (type: EventType, event?: any) => void\n\n// An array of all currently registered event handlers for a type\nexport type EventHandlerList = Array;\nexport type WildCardEventHandlerList = Array;\n\n// A map of event types and their corresponding event handlers.\nexport type EventHandlerMap = Map;\n\nexport interface Emitter {\n\ton(type: EventType, handler: Handler): void;\n\ton(type: '*', handler: WildcardHandler): void;\n\n\toff(type: EventType, handler: Handler): void;\n\toff(type: '*', handler: WildcardHandler): void;\n\n\temit(type: EventType, event?: T): void;\n\temit(type: '*', event?: any): void;\n}\n\n/** Mitt: Tiny (~200b) functional event emitter / pubsub.\n * @name mitt\n * @returns {Mitt}\n */\nexport default function mitt(all?: EventHandlerMap): Emitter {\n\tall = all || new Map();\n\n\treturn {\n\n\t\t/**\n\t\t * Register an event handler for the given type.\n\t\t * @param {string|symbol} type Type of event to listen for, or `\"*\"` for all events\n\t\t * @param {Function} handler Function to call in response to given event\n\t\t * @memberOf mitt\n\t\t */\n\t\ton(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tconst added = handlers && handlers.push(handler);\n\t\t\tif (!added) {\n\t\t\t\tall.set(type, [handler]);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Remove an event handler for the given type.\n\t\t *\n\t\t * @param {string|symbol} type Type of event to unregister `handler` from, or `\"*\"`\n\t\t * @param {Function} handler Handler function to remove\n\t\t * @memberOf mitt\n\t\t */\n\t\toff(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tif (handlers) {\n\t\t\t\thandlers.splice(handlers.indexOf(handler) >>> 0, 1);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Invoke all handlers for the given type.\n\t\t * If present, `\"*\"` handlers are invoked after type-matched handlers.\n\t\t *\n\t\t * Note: Manually firing \"*\" handlers is not supported.\n\t\t *\n\t\t * @param {string|symbol} type The event type to invoke\n\t\t * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler\n\t\t * @memberOf mitt\n\t\t */\n\t\temit(type: EventType, evt: any) {\n\t\t\t((all.get(type) || []) as EventHandlerList).slice().map((handler) => { handler(evt); });\n\t\t\t((all.get('*') || []) as WildCardEventHandlerList).slice().map((handler) => { handler(type, evt); });\n\t\t}\n\t};\n}\n"],"names":["all","Map","on","type","handler","handlers","get","push","set","off","splice","indexOf","emit","evt","slice","map"],"mappings":"wBA6B6BA,GAG5B,OAFAA,EAAMA,GAAO,IAAIC,IAEV,CAQNC,GAAGC,EAAiBC,GACnB,MAAMC,EAAWL,EAAIM,IAAIH,GACXE,GAAYA,EAASE,KAAKH,IAEvCJ,EAAIQ,IAAIL,EAAM,CAACC,KAWjBK,IAAIN,EAAiBC,GACpB,MAAMC,EAAWL,EAAIM,IAAIH,GACrBE,GACHA,EAASK,OAAOL,EAASM,QAAQP,KAAa,EAAG,IAcnDQ,KAAKT,EAAiBU,IACnBb,EAAIM,IAAIH,IAAS,IAAyBW,QAAQC,IAAKX,IAAcA,EAAQS,MAC7Eb,EAAIM,IAAI,MAAQ,IAAiCQ,QAAQC,IAAKX,IAAcA,EAAQD,EAAMU"} \ No newline at end of file diff --git a/src/common/third-party/mitt/dist/mitt.umd.js b/src/common/third-party/mitt/dist/mitt.umd.js new file mode 100644 index 0000000000000..cf39868329fd7 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.umd.js @@ -0,0 +1,2 @@ +!function(e,n){"object"==typeof exports&&"undefined"!=typeof module?module.exports=n():"function"==typeof define&&define.amd?define(n):(e=e||self).mitt=n()}(this,function(){return function(e){return e=e||new Map,{on:function(n,t){var f=e.get(n);f&&f.push(t)||e.set(n,[t])},off:function(n,t){var f=e.get(n);f&&f.splice(f.indexOf(t)>>>0,1)},emit:function(n,t){(e.get(n)||[]).slice().map(function(e){e(t)}),(e.get("*")||[]).slice().map(function(e){e(n,t)})}}}}); +//# sourceMappingURL=mitt.umd.js.map diff --git a/src/common/third-party/mitt/dist/mitt.umd.js.map b/src/common/third-party/mitt/dist/mitt.umd.js.map new file mode 100644 index 0000000000000..b5aaf64a43593 --- /dev/null +++ b/src/common/third-party/mitt/dist/mitt.umd.js.map @@ -0,0 +1 @@ +{"version":3,"file":"mitt.umd.js","sources":["../src/index.ts"],"sourcesContent":["export type EventType = string | symbol;\n\n// An event handler can take an optional event argument\n// and should not return a value\nexport type Handler = (event?: any) => void;\nexport type WildcardHandler= (type: EventType, event?: any) => void\n\n// An array of all currently registered event handlers for a type\nexport type EventHandlerList = Array;\nexport type WildCardEventHandlerList = Array;\n\n// A map of event types and their corresponding event handlers.\nexport type EventHandlerMap = Map;\n\nexport interface Emitter {\n\ton(type: EventType, handler: Handler): void;\n\ton(type: '*', handler: WildcardHandler): void;\n\n\toff(type: EventType, handler: Handler): void;\n\toff(type: '*', handler: WildcardHandler): void;\n\n\temit(type: EventType, event?: T): void;\n\temit(type: '*', event?: any): void;\n}\n\n/** Mitt: Tiny (~200b) functional event emitter / pubsub.\n * @name mitt\n * @returns {Mitt}\n */\nexport default function mitt(all?: EventHandlerMap): Emitter {\n\tall = all || new Map();\n\n\treturn {\n\n\t\t/**\n\t\t * Register an event handler for the given type.\n\t\t * @param {string|symbol} type Type of event to listen for, or `\"*\"` for all events\n\t\t * @param {Function} handler Function to call in response to given event\n\t\t * @memberOf mitt\n\t\t */\n\t\ton(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tconst added = handlers && handlers.push(handler);\n\t\t\tif (!added) {\n\t\t\t\tall.set(type, [handler]);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Remove an event handler for the given type.\n\t\t *\n\t\t * @param {string|symbol} type Type of event to unregister `handler` from, or `\"*\"`\n\t\t * @param {Function} handler Handler function to remove\n\t\t * @memberOf mitt\n\t\t */\n\t\toff(type: EventType, handler: Handler) {\n\t\t\tconst handlers = all.get(type);\n\t\t\tif (handlers) {\n\t\t\t\thandlers.splice(handlers.indexOf(handler) >>> 0, 1);\n\t\t\t}\n\t\t},\n\n\t\t/**\n\t\t * Invoke all handlers for the given type.\n\t\t * If present, `\"*\"` handlers are invoked after type-matched handlers.\n\t\t *\n\t\t * Note: Manually firing \"*\" handlers is not supported.\n\t\t *\n\t\t * @param {string|symbol} type The event type to invoke\n\t\t * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler\n\t\t * @memberOf mitt\n\t\t */\n\t\temit(type: EventType, evt: any) {\n\t\t\t((all.get(type) || []) as EventHandlerList).slice().map((handler) => { handler(evt); });\n\t\t\t((all.get('*') || []) as WildCardEventHandlerList).slice().map((handler) => { handler(type, evt); });\n\t\t}\n\t};\n}\n"],"names":["all","Map","on","type","handler","handlers","get","push","set","off","splice","indexOf","emit","evt","slice","map"],"mappings":"6LA6B6BA,GAG5B,OAFAA,EAAMA,GAAO,IAAIC,IAEV,CAQNC,YAAGC,EAAiBC,GACnB,IAAMC,EAAWL,EAAIM,IAAIH,GACXE,GAAYA,EAASE,KAAKH,IAEvCJ,EAAIQ,IAAIL,EAAM,CAACC,KAWjBK,aAAIN,EAAiBC,GACpB,IAAMC,EAAWL,EAAIM,IAAIH,GACrBE,GACHA,EAASK,OAAOL,EAASM,QAAQP,KAAa,EAAG,IAcnDQ,cAAKT,EAAiBU,IACnBb,EAAIM,IAAIH,IAAS,IAAyBW,QAAQC,IAAI,SAACX,GAAcA,EAAQS,MAC7Eb,EAAIM,IAAI,MAAQ,IAAiCQ,QAAQC,IAAI,SAACX,GAAcA,EAAQD,EAAMU"} \ No newline at end of file diff --git a/src/common/third-party/mitt/package.json b/src/common/third-party/mitt/package.json new file mode 100644 index 0000000000000..0e1e01b86f541 --- /dev/null +++ b/src/common/third-party/mitt/package.json @@ -0,0 +1,125 @@ +{ + "_from": "mitt@^2.0.1", + "_id": "mitt@2.0.1", + "_inBundle": false, + "_integrity": "sha512-FhuJY+tYHLnPcBHQhbUFzscD5512HumCPE4URXZUgPi3IvOJi4Xva5IIgy3xX56GqCmw++MAm5UURG6kDBYTdg==", + "_location": "/mitt", + "_phantomChildren": {}, + "_requested": { + "type": "range", + "registry": true, + "raw": "mitt@^2.0.1", + "name": "mitt", + "escapedName": "mitt", + "rawSpec": "^2.0.1", + "saveSpec": null, + "fetchSpec": "^2.0.1" + }, + "_requiredBy": [ + "/" + ], + "_resolved": "https://registry.npmjs.org/mitt/-/mitt-2.0.1.tgz", + "_shasum": "9e8a075b4daae82dd91aac155a0ece40ca7cb393", + "_spec": "mitt@^2.0.1", + "_where": "/Users/jacktfranklin/src/puppeteer", + "authors": [ + "Jason Miller " + ], + "bugs": { + "url": "https://github.com/developit/mitt/issues" + }, + "bundleDependencies": false, + "deprecated": false, + "description": "Tiny 200b functional Event Emitter / pubsub.", + "devDependencies": { + "@types/chai": "^4.2.11", + "@types/mocha": "^7.0.2", + "@types/sinon": "^9.0.4", + "@types/sinon-chai": "^3.2.4", + "@typescript-eslint/eslint-plugin": "^3.0.1", + "@typescript-eslint/parser": "^3.0.1", + "chai": "^4.2.0", + "documentation": "^13.0.0", + "eslint": "^7.1.0", + "eslint-config-developit": "^1.2.0", + "esm": "^3.2.25", + "microbundle": "^0.12.0", + "mocha": "^7.2.0", + "npm-run-all": "^4.1.5", + "rimraf": "^3.0.2", + "sinon": "^9.0.2", + "sinon-chai": "^3.5.0", + "ts-node": "^8.10.1", + "typescript": "^3.9.3" + }, + "eslintConfig": { + "extends": [ + "developit", + "plugin:@typescript-eslint/eslint-recommended", + "plugin:@typescript-eslint/recommended" + ], + "parser": "@typescript-eslint/parser", + "parserOptions": { + "sourceType": "module" + }, + "env": { + "browser": true, + "mocha": true, + "jest": false, + "es6": true + }, + "globals": { + "expect": true + }, + "rules": { + "semi": [ + 2, + "always" + ], + "jest/valid-expect": 0, + "@typescript-eslint/no-explicit-any": 0, + "@typescript-eslint/explicit-function-return-type": 0, + "@typescript-eslint/explicit-module-boundary-types": 0, + "@typescript-eslint/no-empty-function": 0 + } + }, + "eslintIgnore": [ + "dist" + ], + "esmodules": "dist/mitt.modern.js", + "files": [ + "src", + "dist" + ], + "homepage": "https://github.com/developit/mitt", + "jsnext:main": "dist/mitt.es.js", + "keywords": [ + "events", + "eventemitter", + "emitter", + "pubsub" + ], + "license": "MIT", + "main": "dist/mitt.js", + "module": "dist/mitt.es.js", + "name": "mitt", + "repository": { + "type": "git", + "url": "git+https://github.com/developit/mitt.git" + }, + "scripts": { + "build": "npm-run-all --silent clean -p bundle -s docs", + "bundle": "microbundle", + "clean": "rimraf dist", + "docs": "documentation readme src/index.ts --section API -q --parse-extension ts", + "lint": "eslint src test --ext ts --ext js", + "release": "npm run -s build -s && npm t && git commit -m $npm_package_version && git tag $npm_package_version && git push && git push --tags && npm publish", + "test": "npm-run-all --silent typecheck lint testonly", + "testonly": "mocha --require esm test/**/*.js", + "typecheck": "tsc **/*.ts --noEmit" + }, + "source": "src/index.ts", + "typings": "dist/index.d.ts", + "umd:main": "dist/mitt.umd.js", + "version": "2.0.1" +} diff --git a/src/common/third-party/mitt/src/index.ts b/src/common/third-party/mitt/src/index.ts new file mode 100644 index 0000000000000..cfb1cf386cdbd --- /dev/null +++ b/src/common/third-party/mitt/src/index.ts @@ -0,0 +1,78 @@ +export type EventType = string | symbol; + +// An event handler can take an optional event argument +// and should not return a value +export type Handler = (event?: any) => void; +export type WildcardHandler= (type: EventType, event?: any) => void + +// An array of all currently registered event handlers for a type +export type EventHandlerList = Array; +export type WildCardEventHandlerList = Array; + +// A map of event types and their corresponding event handlers. +export type EventHandlerMap = Map; + +export interface Emitter { + on(type: EventType, handler: Handler): void; + on(type: '*', handler: WildcardHandler): void; + + off(type: EventType, handler: Handler): void; + off(type: '*', handler: WildcardHandler): void; + + emit(type: EventType, event?: T): void; + emit(type: '*', event?: any): void; +} + +/** Mitt: Tiny (~200b) functional event emitter / pubsub. + * @name mitt + * @returns {Mitt} + */ +export default function mitt(all?: EventHandlerMap): Emitter { + all = all || new Map(); + + return { + + /** + * Register an event handler for the given type. + * @param {string|symbol} type Type of event to listen for, or `"*"` for all events + * @param {Function} handler Function to call in response to given event + * @memberOf mitt + */ + on(type: EventType, handler: Handler) { + const handlers = all.get(type); + const added = handlers && handlers.push(handler); + if (!added) { + all.set(type, [handler]); + } + }, + + /** + * Remove an event handler for the given type. + * + * @param {string|symbol} type Type of event to unregister `handler` from, or `"*"` + * @param {Function} handler Handler function to remove + * @memberOf mitt + */ + off(type: EventType, handler: Handler) { + const handlers = all.get(type); + if (handlers) { + handlers.splice(handlers.indexOf(handler) >>> 0, 1); + } + }, + + /** + * Invoke all handlers for the given type. + * If present, `"*"` handlers are invoked after type-matched handlers. + * + * Note: Manually firing "*" handlers is not supported. + * + * @param {string|symbol} type The event type to invoke + * @param {Any} [evt] Any value (object is recommended and powerful), passed to each handler + * @memberOf mitt + */ + emit(type: EventType, evt: any) { + ((all.get(type) || []) as EventHandlerList).slice().map((handler) => { handler(evt); }); + ((all.get('*') || []) as WildCardEventHandlerList).slice().map((handler) => { handler(type, evt); }); + } + }; +} diff --git a/tsconfig.json b/tsconfig.json index 5a62ace19cb13..99e824e778302 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -13,5 +13,8 @@ }, "include": [ "src" + ], + "exclude": [ + "src/common/third-party/mitt/dist" ] } From 351a5577dbd2832e8653cc81062dc728c7d19e52 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 11:25:38 +0100 Subject: [PATCH 02/16] vendor docs --- CONTRIBUTING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5cf0d56fce334..e185fa62ca178 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -153,6 +153,20 @@ For all dependencies (both installation and development): A barrier for introducing new installation dependencies is especially high: - **Do not add** installation dependency unless it's critical to project success. +### Vendoring third party dependencies + +Because we are working towards an agnostic Puppeteer that can run in any environment (see [#6125](https://github.com/puppeteer/puppeteer/issues/6125)) we cannot import common dependencies in a way that relies on Node's resolution to find them. For example, `import mitt from 'mitt'` works fine in Node, but in an ESM build running in the browser, the browser has no idea where to find `'mitt'`. + +Therefore we put all common dependencies into `src/common/third-party`. This means there are extra criteria for these dependencies; ideally they will not depend on any other modules. If they do, we should consider an alternative way of managing our dependencies. + +The process for updating a vendored dependency is: + +1. `npm install {DEP NAME HERE}` +2. `cp -r node_modules/DEP src/common/third-party/DEP` +3. Update `eslintrc.js` to forbid importing DEP directly (see the `Mitt` rule already defined in there). +4. Use the new DEP, and run `npm run tsc` to check everything compiles successfully. +5. If the dep ships as compiled JS, you may need to disable TypeScript checking the file. Add an entry to the `excludes` property of the root `tsconfig.json` (again, see the entry that's already there for Mitt as an example). + ## Running & Writing Tests - Every feature should be accompanied by a test. From 9bb806aeb4c46c1ad50e37ca77eab72cc14f0f93 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 12:08:51 +0100 Subject: [PATCH 03/16] remove mitt from package.json --- package.json | 1 - 1 file changed, 1 deletion(-) diff --git a/package.json b/package.json index f3a43990e3ede..ba9fa9f43294c 100644 --- a/package.json +++ b/package.json @@ -49,7 +49,6 @@ "extract-zip": "^2.0.0", "https-proxy-agent": "^4.0.0", "mime": "^2.0.3", - "mitt": "^2.0.1", "pkg-dir": "^4.2.0", "progress": "^2.0.1", "proxy-from-env": "^1.0.0", From 769563b40d9b3bfc34a25d432101ae76ce349359 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 12:12:00 +0100 Subject: [PATCH 04/16] fix docs --- CONTRIBUTING.md | 1 + utils/doclint/check_public_api/index.js | 16 ++++++++-------- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e185fa62ca178..2dc39d32f8031 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ * [Commit Messages](#commit-messages) * [Writing Documentation](#writing-documentation) * [Adding New Dependencies](#adding-new-dependencies) + - [Vendoring third party dependencies](#vendoring-third-party-dependencies) * [Running & Writing Tests](#running--writing-tests) * [Public API Coverage](#public-api-coverage) * [Debugging Puppeteer](#debugging-puppeteer) diff --git a/utils/doclint/check_public_api/index.js b/utils/doclint/check_public_api/index.js index 2bd41d4a28280..fa8aa5c9fd06b 100644 --- a/utils/doclint/check_public_api/index.js +++ b/utils/doclint/check_public_api/index.js @@ -674,56 +674,56 @@ function compareDocumentations(actual, expected) { 'Method EventEmitter.emit() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.listenerCount() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.off() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.on() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.once() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.removeListener() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.addListener() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ 'Method EventEmitter.removeAllListeners() event', { actualName: 'string|symbol', - expectedName: 'Object', + expectedName: 'EventType', }, ], [ From ee2d0255c06983ccf3cfe77c3fa676af181effab Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 16:03:09 +0100 Subject: [PATCH 05/16] create vendor dir --- {src/common/third-party => vendor}/mitt/README.md | 0 {src/common/third-party => vendor}/mitt/dist/index.d.ts | 0 {src/common/third-party => vendor}/mitt/dist/mitt.es.js | 0 {src/common/third-party => vendor}/mitt/dist/mitt.es.js.map | 0 {src/common/third-party => vendor}/mitt/dist/mitt.js | 0 {src/common/third-party => vendor}/mitt/dist/mitt.js.map | 0 {src/common/third-party => vendor}/mitt/dist/mitt.modern.js | 0 {src/common/third-party => vendor}/mitt/dist/mitt.modern.js.map | 0 {src/common/third-party => vendor}/mitt/dist/mitt.umd.js | 0 {src/common/third-party => vendor}/mitt/dist/mitt.umd.js.map | 0 {src/common/third-party => vendor}/mitt/package.json | 0 {src/common/third-party => vendor}/mitt/src/index.ts | 0 12 files changed, 0 insertions(+), 0 deletions(-) rename {src/common/third-party => vendor}/mitt/README.md (100%) rename {src/common/third-party => vendor}/mitt/dist/index.d.ts (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.es.js (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.es.js.map (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.js (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.js.map (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.modern.js (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.modern.js.map (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.umd.js (100%) rename {src/common/third-party => vendor}/mitt/dist/mitt.umd.js.map (100%) rename {src/common/third-party => vendor}/mitt/package.json (100%) rename {src/common/third-party => vendor}/mitt/src/index.ts (100%) diff --git a/src/common/third-party/mitt/README.md b/vendor/mitt/README.md similarity index 100% rename from src/common/third-party/mitt/README.md rename to vendor/mitt/README.md diff --git a/src/common/third-party/mitt/dist/index.d.ts b/vendor/mitt/dist/index.d.ts similarity index 100% rename from src/common/third-party/mitt/dist/index.d.ts rename to vendor/mitt/dist/index.d.ts diff --git a/src/common/third-party/mitt/dist/mitt.es.js b/vendor/mitt/dist/mitt.es.js similarity index 100% rename from src/common/third-party/mitt/dist/mitt.es.js rename to vendor/mitt/dist/mitt.es.js diff --git a/src/common/third-party/mitt/dist/mitt.es.js.map b/vendor/mitt/dist/mitt.es.js.map similarity index 100% rename from src/common/third-party/mitt/dist/mitt.es.js.map rename to vendor/mitt/dist/mitt.es.js.map diff --git a/src/common/third-party/mitt/dist/mitt.js b/vendor/mitt/dist/mitt.js similarity index 100% rename from src/common/third-party/mitt/dist/mitt.js rename to vendor/mitt/dist/mitt.js diff --git a/src/common/third-party/mitt/dist/mitt.js.map b/vendor/mitt/dist/mitt.js.map similarity index 100% rename from src/common/third-party/mitt/dist/mitt.js.map rename to vendor/mitt/dist/mitt.js.map diff --git a/src/common/third-party/mitt/dist/mitt.modern.js b/vendor/mitt/dist/mitt.modern.js similarity index 100% rename from src/common/third-party/mitt/dist/mitt.modern.js rename to vendor/mitt/dist/mitt.modern.js diff --git a/src/common/third-party/mitt/dist/mitt.modern.js.map b/vendor/mitt/dist/mitt.modern.js.map similarity index 100% rename from src/common/third-party/mitt/dist/mitt.modern.js.map rename to vendor/mitt/dist/mitt.modern.js.map diff --git a/src/common/third-party/mitt/dist/mitt.umd.js b/vendor/mitt/dist/mitt.umd.js similarity index 100% rename from src/common/third-party/mitt/dist/mitt.umd.js rename to vendor/mitt/dist/mitt.umd.js diff --git a/src/common/third-party/mitt/dist/mitt.umd.js.map b/vendor/mitt/dist/mitt.umd.js.map similarity index 100% rename from src/common/third-party/mitt/dist/mitt.umd.js.map rename to vendor/mitt/dist/mitt.umd.js.map diff --git a/src/common/third-party/mitt/package.json b/vendor/mitt/package.json similarity index 100% rename from src/common/third-party/mitt/package.json rename to vendor/mitt/package.json diff --git a/src/common/third-party/mitt/src/index.ts b/vendor/mitt/src/index.ts similarity index 100% rename from src/common/third-party/mitt/src/index.ts rename to vendor/mitt/src/index.ts From ca1e1840b60dd6c8522fe6706b3bcd539621621c Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Mon, 13 Jul 2020 16:30:34 +0100 Subject: [PATCH 06/16] get proj refs working --- src/common/EventEmitter.ts | 2 +- src/tsconfig.json | 9 +++++++++ tsconfig.base.json | 15 +++++++++++++++ tsconfig.json | 22 ++++++---------------- vendor/tsconfig.json | 9 +++++++++ 5 files changed, 40 insertions(+), 17 deletions(-) create mode 100644 src/tsconfig.json create mode 100644 tsconfig.base.json create mode 100644 vendor/tsconfig.json diff --git a/src/common/EventEmitter.ts b/src/common/EventEmitter.ts index 29d434d2fe86d..3588f1408b6e3 100644 --- a/src/common/EventEmitter.ts +++ b/src/common/EventEmitter.ts @@ -2,7 +2,7 @@ import mitt, { Emitter, EventType, Handler, -} from './third-party/mitt/src/index.js'; +} from '../../vendor/mitt/src/index.js'; /** * @internal diff --git a/src/tsconfig.json b/src/tsconfig.json new file mode 100644 index 0000000000000..d1f4ea9771827 --- /dev/null +++ b/src/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../tsconfig.base.json", + "compilerOptions": { + "outDir": "../lib/puppeteer" + }, + "references": [ + { "path": "../vendor"} + ] +} diff --git a/tsconfig.base.json b/tsconfig.base.json new file mode 100644 index 0000000000000..d08041c2fb794 --- /dev/null +++ b/tsconfig.base.json @@ -0,0 +1,15 @@ +{ + "compilerOptions": { + "esModuleInterop": true, + "allowJs": true, + "checkJs": true, + "target": "ESNext", + "moduleResolution": "node", + "outDir": "./lib", + "module": "CommonJS", + "declaration": true, + "declarationMap": true, + "resolveJsonModule": true, + "composite": true, + } +} diff --git a/tsconfig.json b/tsconfig.json index 99e824e778302..a4e368c8742ee 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,20 +1,10 @@ { + "references": [ + { "path": "./src" }, + { "path": "./vendor" }, + ], "compilerOptions": { - "allowJs": true, - "checkJs": true, - "outDir": "./lib/cjs", - "target": "ESNext", - "moduleResolution": "node", - "module": "CommonJS", - "declaration": true, - "declarationMap": true, - "esModuleInterop": true, - "resolveJsonModule": true + "esModuleInterop": true }, - "include": [ - "src" - ], - "exclude": [ - "src/common/third-party/mitt/dist" - ] + "files": [] } diff --git a/vendor/tsconfig.json b/vendor/tsconfig.json new file mode 100644 index 0000000000000..e83f32946167b --- /dev/null +++ b/vendor/tsconfig.json @@ -0,0 +1,9 @@ +{ + "extends": "../tsconfig.base.json", + "exclude": [ + "mitt/dist" + ], + "compilerOptions": { + "outDir": "../lib/vendor" + } +} From 04f0a5407d5cdb6cbb62b26496b85be467be7143 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 10:23:39 +0100 Subject: [PATCH 07/16] references --- cjs-entry.js | 2 +- package.json | 5 +- src/tsconfig.cjs.json | 11 +++++ src/tsconfig.esm.json | 11 +++++ src/tsconfig.json | 9 ---- test/EventEmitter.spec.ts | 2 +- test/coverage-utils.js | 52 ++++++++++----------- test/elementhandle.spec.ts | 2 +- test/keyboard.spec.ts | 2 +- test/launcher.spec.ts | 2 +- test/mocha-utils.ts | 11 +++-- test/mouse.spec.ts | 2 +- test/page.spec.ts | 4 +- test/target.spec.ts | 2 +- test/worker.spec.ts | 4 +- tsconfig.base.json | 5 +- tsconfig.json | 10 +--- vendor/tsconfig.cjs.json | 11 +++++ vendor/{tsconfig.json => tsconfig.esm.json} | 4 +- 19 files changed, 85 insertions(+), 66 deletions(-) create mode 100644 src/tsconfig.cjs.json create mode 100644 src/tsconfig.esm.json delete mode 100644 src/tsconfig.json create mode 100644 vendor/tsconfig.cjs.json rename vendor/{tsconfig.json => tsconfig.esm.json} (56%) diff --git a/cjs-entry.js b/cjs-entry.js index 424ffadf1a14e..1bcec7d85aff2 100644 --- a/cjs-entry.js +++ b/cjs-entry.js @@ -25,5 +25,5 @@ * This means that we can publish to CJS and ESM whilst maintaining the expected * import behaviour for CJS and ESM users. */ -const puppeteerExport = require('./lib/cjs/index'); +const puppeteerExport = require('./lib/cjs/puppeteer/index'); module.exports = puppeteerExport.default; diff --git a/package.json b/package.json index ba9fa9f43294c..114c70d6968d7 100644 --- a/package.json +++ b/package.json @@ -24,9 +24,8 @@ "doc": "node utils/doclint/cli.js", "clean-lib": "rm -rf lib", "tsc": "npm run clean-lib && tsc --version && npm run tsc-cjs && npm run tsc-esm", - "tsc-cjs": "tsc -p .", - "tsc-esm": "tsc --build tsconfig-esm.json", - "typecheck": "tsc -p . --noEmit", + "tsc-cjs": "tsc -b src/tsconfig.cjs.json", + "tsc-esm": "tsc -b src/tsconfig.esm.json", "apply-next-version": "node utils/apply_next_version.js", "test-install": "scripts/test-install.sh", "generate-docs": "npm run tsc && api-extractor run --local --verbose && api-documenter markdown -i temp -o new-docs", diff --git a/src/tsconfig.cjs.json b/src/tsconfig.cjs.json new file mode 100644 index 0000000000000..c144b956bf813 --- /dev/null +++ b/src/tsconfig.cjs.json @@ -0,0 +1,11 @@ +{ + "extends": "../tsconfig.base.json", + "compilerOptions": { + "composite": true, + "outDir": "../lib/cjs/puppeteer", + "module": "CommonJS" + }, + "references": [ + { "path": "../vendor/tsconfig.cjs.json"} + ] +} diff --git a/src/tsconfig.esm.json b/src/tsconfig.esm.json new file mode 100644 index 0000000000000..487533061f44f --- /dev/null +++ b/src/tsconfig.esm.json @@ -0,0 +1,11 @@ +{ + "extends": "../tsconfig.base.json", + "compilerOptions": { + "composite": true, + "outDir": "../lib/esm/puppeteer", + "module": "esnext" + }, + "references": [ + { "path": "../vendor/tsconfig.esm.json"} + ] +} diff --git a/src/tsconfig.json b/src/tsconfig.json deleted file mode 100644 index d1f4ea9771827..0000000000000 --- a/src/tsconfig.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "extends": "../tsconfig.base.json", - "compilerOptions": { - "outDir": "../lib/puppeteer" - }, - "references": [ - { "path": "../vendor"} - ] -} diff --git a/test/EventEmitter.spec.ts b/test/EventEmitter.spec.ts index ea0189d9e4dff..bf20e7fe8fc28 100644 --- a/test/EventEmitter.spec.ts +++ b/test/EventEmitter.spec.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { EventEmitter } from '../lib/cjs/common/EventEmitter.js'; +import { EventEmitter } from '../lib/cjs/puppeteer/common/EventEmitter.js'; import sinon from 'sinon'; import expect from 'expect'; diff --git a/test/coverage-utils.js b/test/coverage-utils.js index 27b06e7492646..add0238a0e8a2 100644 --- a/test/coverage-utils.js +++ b/test/coverage-utils.js @@ -39,32 +39,32 @@ const fs = require('fs'); * part of the TSDoc migration. */ const MODULES_TO_CHECK_FOR_COVERAGE = { - Accessibility: '../lib/cjs/common/Accessibility', - Browser: '../lib/cjs/common/Browser', - BrowserContext: '../lib/cjs/common/Browser', - BrowserFetcher: '../lib/cjs/node/BrowserFetcher', - CDPSession: '../lib/cjs/common/Connection', - ConsoleMessage: '../lib/cjs/common/ConsoleMessage', - Coverage: '../lib/cjs/common/Coverage', - Dialog: '../lib/cjs/common/Dialog', - ElementHandle: '../lib/cjs/common/JSHandle', - ExecutionContext: '../lib/cjs/common/ExecutionContext', - EventEmitter: '../lib/cjs/common/EventEmitter', - FileChooser: '../lib/cjs/common/FileChooser', - Frame: '../lib/cjs/common/FrameManager', - JSHandle: '../lib/cjs/common/JSHandle', - Keyboard: '../lib/cjs/common/Input', - Mouse: '../lib/cjs/common/Input', - Page: '../lib/cjs/common/Page', - Puppeteer: '../lib/cjs/common/Puppeteer', - HTTPRequest: '../lib/cjs/common/HTTPRequest', - HTTPResponse: '../lib/cjs/common/HTTPResponse', - SecurityDetails: '../lib/cjs/common/SecurityDetails', - Target: '../lib/cjs/common/Target', - TimeoutError: '../lib/cjs/common/Errors', - Touchscreen: '../lib/cjs/common/Input', - Tracing: '../lib/cjs/common/Tracing', - WebWorker: '../lib/cjs/common/WebWorker', + Accessibility: '../lib/cjs/puppeteer/common/Accessibility', + Browser: '../lib/cjs/puppeteer/common/Browser', + BrowserContext: '../lib/cjs/puppeteer/common/Browser', + BrowserFetcher: '../lib/cjs/puppeteer/node/BrowserFetcher', + CDPSession: '../lib/cjs/puppeteer/common/Connection', + ConsoleMessage: '../lib/cjs/puppeteer/common/ConsoleMessage', + Coverage: '../lib/cjs/puppeteer/common/Coverage', + Dialog: '../lib/cjs/puppeteer/common/Dialog', + ElementHandle: '../lib/cjs/puppeteer/common/JSHandle', + ExecutionContext: '../lib/cjs/puppeteer/common/ExecutionContext', + EventEmitter: '../lib/cjs/puppeteer/common/EventEmitter', + FileChooser: '../lib/cjs/puppeteer/common/FileChooser', + Frame: '../lib/cjs/puppeteer/common/FrameManager', + JSHandle: '../lib/cjs/puppeteer/common/JSHandle', + Keyboard: '../lib/cjs/puppeteer/common/Input', + Mouse: '../lib/cjs/puppeteer/common/Input', + Page: '../lib/cjs/puppeteer/common/Page', + Puppeteer: '../lib/cjs/puppeteer/common/Puppeteer', + HTTPRequest: '../lib/cjs/puppeteer/common/HTTPRequest', + HTTPResponse: '../lib/cjs/puppeteer/common/HTTPResponse', + SecurityDetails: '../lib/cjs/puppeteer/common/SecurityDetails', + Target: '../lib/cjs/puppeteer/common/Target', + TimeoutError: '../lib/cjs/puppeteer/common/Errors', + Touchscreen: '../lib/cjs/puppeteer/common/Input', + Tracing: '../lib/cjs/puppeteer/common/Tracing', + WebWorker: '../lib/cjs/puppeteer/common/WebWorker', }; function traceAPICoverage(apiCoverage, className, modulePath) { diff --git a/test/elementhandle.spec.ts b/test/elementhandle.spec.ts index e7d221b3b75a8..5bb74a3dbf397 100644 --- a/test/elementhandle.spec.ts +++ b/test/elementhandle.spec.ts @@ -24,7 +24,7 @@ import { } from './mocha-utils'; // eslint-disable-line import/extensions import utils from './utils.js'; -import { ElementHandle } from '../lib/cjs/common/JSHandle.js'; +import { ElementHandle } from '../lib/cjs/puppeteer/common/JSHandle.js'; describe('ElementHandle specs', function () { setupTestBrowserHooks(); diff --git a/test/keyboard.spec.ts b/test/keyboard.spec.ts index 9ad47972c7c59..889c97483a04a 100644 --- a/test/keyboard.spec.ts +++ b/test/keyboard.spec.ts @@ -23,7 +23,7 @@ import { setupTestPageAndContextHooks, itFailsFirefox, } from './mocha-utils'; // eslint-disable-line import/extensions -import { KeyInput } from '../lib/cjs/common/USKeyboardLayout.js'; +import { KeyInput } from '../lib/cjs/puppeteer/common/USKeyboardLayout.js'; describe('Keyboard', function () { setupTestBrowserHooks(); diff --git a/test/launcher.spec.ts b/test/launcher.spec.ts index 4e1d623268867..ef3cef9cb9c92 100644 --- a/test/launcher.spec.ts +++ b/test/launcher.spec.ts @@ -27,7 +27,7 @@ import { import utils from './utils.js'; import expect from 'expect'; import rimraf from 'rimraf'; -import { Page } from '../lib/cjs/common/Page.js'; +import { Page } from '../lib/cjs/puppeteer/common/Page.js'; const rmAsync = promisify(rimraf); const mkdtempAsync = promisify(fs.mkdtemp); diff --git a/test/mocha-utils.ts b/test/mocha-utils.ts index 2a26afc98bb45..ae14bbc67e9ee 100644 --- a/test/mocha-utils.ts +++ b/test/mocha-utils.ts @@ -19,10 +19,13 @@ import * as path from 'path'; import * as fs from 'fs'; import * as os from 'os'; import sinon from 'sinon'; -import puppeteer from '../lib/cjs/index.js'; -import { Browser, BrowserContext } from '../lib/cjs/common/Browser.js'; -import { Page } from '../lib/cjs/common/Page.js'; -import { Puppeteer } from '../lib/cjs/common/Puppeteer.js'; +import puppeteer from '../lib/cjs/puppeteer/index.js'; +import { + Browser, + BrowserContext, +} from '../lib/cjs/puppeteer/common/Browser.js'; +import { Page } from '../lib/cjs/puppeteer/common/Page.js'; +import { Puppeteer } from '../lib/cjs/puppeteer/common/Puppeteer.js'; import utils from './utils.js'; import rimraf from 'rimraf'; diff --git a/test/mouse.spec.ts b/test/mouse.spec.ts index 7d47b4cabc120..2670bafdfe670 100644 --- a/test/mouse.spec.ts +++ b/test/mouse.spec.ts @@ -21,7 +21,7 @@ import { setupTestPageAndContextHooks, itFailsFirefox, } from './mocha-utils'; // eslint-disable-line import/extensions -import { KeyInput } from '../lib/cjs/common/USKeyboardLayout.js'; +import { KeyInput } from '../lib/cjs/puppeteer/common/USKeyboardLayout.js'; interface Dimensions { x: number; diff --git a/test/page.spec.ts b/test/page.spec.ts index 441bc5ac6c178..eb97ceeeacc89 100644 --- a/test/page.spec.ts +++ b/test/page.spec.ts @@ -26,8 +26,8 @@ import { itFailsFirefox, describeFailsFirefox, } from './mocha-utils'; // eslint-disable-line import/extensions -import { Page, Metrics } from '../lib/cjs/common/Page.js'; -import { JSHandle } from '../lib/cjs/common/JSHandle.js'; +import { Page, Metrics } from '../lib/cjs/puppeteer/common/Page.js'; +import { JSHandle } from '../lib/cjs/puppeteer/common/JSHandle.js'; describe('Page', function () { setupTestBrowserHooks(); diff --git a/test/target.spec.ts b/test/target.spec.ts index 7459218dbb5d6..8646a60c8e49e 100644 --- a/test/target.spec.ts +++ b/test/target.spec.ts @@ -23,7 +23,7 @@ import { setupTestPageAndContextHooks, itFailsFirefox, } from './mocha-utils'; // eslint-disable-line import/extensions -import { Target } from '../lib/cjs/common/Target.js'; +import { Target } from '../lib/cjs/puppeteer/common/Target.js'; describe('Target', function () { setupTestBrowserHooks(); diff --git a/test/worker.spec.ts b/test/worker.spec.ts index a4a356bfb3713..2c5827361b52e 100644 --- a/test/worker.spec.ts +++ b/test/worker.spec.ts @@ -22,8 +22,8 @@ import { describeFailsFirefox, } from './mocha-utils'; // eslint-disable-line import/extensions import utils from './utils.js'; -import { WebWorker } from '../lib/cjs/common/WebWorker.js'; -import { ConsoleMessage } from '../lib/cjs/common/ConsoleMessage.js'; +import { WebWorker } from '../lib/cjs/puppeteer/common/WebWorker.js'; +import { ConsoleMessage } from '../lib/cjs/puppeteer/common/ConsoleMessage.js'; const { waitEvent } = utils; describeFailsFirefox('Workers', function () { diff --git a/tsconfig.base.json b/tsconfig.base.json index d08041c2fb794..31a7a463db0bc 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -5,11 +5,8 @@ "checkJs": true, "target": "ESNext", "moduleResolution": "node", - "outDir": "./lib", - "module": "CommonJS", "declaration": true, "declarationMap": true, - "resolveJsonModule": true, - "composite": true, + "resolveJsonModule": true } } diff --git a/tsconfig.json b/tsconfig.json index a4e368c8742ee..45514fcd973c5 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,10 +1,4 @@ { - "references": [ - { "path": "./src" }, - { "path": "./vendor" }, - ], - "compilerOptions": { - "esModuleInterop": true - }, - "files": [] + "extends": "./tsconfig.base.json", + "include": ["test"] } diff --git a/vendor/tsconfig.cjs.json b/vendor/tsconfig.cjs.json new file mode 100644 index 0000000000000..f73a8d57d0115 --- /dev/null +++ b/vendor/tsconfig.cjs.json @@ -0,0 +1,11 @@ +{ + "extends": "../tsconfig.base.json", + "exclude": [ + "mitt/dist" + ], + "compilerOptions": { + "composite": true, + "outDir": "../lib/cjs/vendor", + "module": "CommonJS" + } +} diff --git a/vendor/tsconfig.json b/vendor/tsconfig.esm.json similarity index 56% rename from vendor/tsconfig.json rename to vendor/tsconfig.esm.json index e83f32946167b..1f0bae8e3d2db 100644 --- a/vendor/tsconfig.json +++ b/vendor/tsconfig.esm.json @@ -4,6 +4,8 @@ "mitt/dist" ], "compilerOptions": { - "outDir": "../lib/vendor" + "composite": true, + "outDir": "../lib/esm/vendor", + "module": "esnext" } } From da889c50c3c04e20398a99231139914198ba81f4 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 10:27:47 +0100 Subject: [PATCH 08/16] docs --- CONTRIBUTING.md | 13 +------------ vendor/README.md | 13 +++++++++++++ 2 files changed, 14 insertions(+), 12 deletions(-) create mode 100644 vendor/README.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2dc39d32f8031..0c898fed58010 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,19 +154,8 @@ For all dependencies (both installation and development): A barrier for introducing new installation dependencies is especially high: - **Do not add** installation dependency unless it's critical to project success. -### Vendoring third party dependencies +There are additional considerations for dependencies that are environment agonistic. See the [`vendor/README.md`](https://github.com/puppeteer/puppeteer/blob/main/vendor/README.md) for details. -Because we are working towards an agnostic Puppeteer that can run in any environment (see [#6125](https://github.com/puppeteer/puppeteer/issues/6125)) we cannot import common dependencies in a way that relies on Node's resolution to find them. For example, `import mitt from 'mitt'` works fine in Node, but in an ESM build running in the browser, the browser has no idea where to find `'mitt'`. - -Therefore we put all common dependencies into `src/common/third-party`. This means there are extra criteria for these dependencies; ideally they will not depend on any other modules. If they do, we should consider an alternative way of managing our dependencies. - -The process for updating a vendored dependency is: - -1. `npm install {DEP NAME HERE}` -2. `cp -r node_modules/DEP src/common/third-party/DEP` -3. Update `eslintrc.js` to forbid importing DEP directly (see the `Mitt` rule already defined in there). -4. Use the new DEP, and run `npm run tsc` to check everything compiles successfully. -5. If the dep ships as compiled JS, you may need to disable TypeScript checking the file. Add an entry to the `excludes` property of the root `tsconfig.json` (again, see the entry that's already there for Mitt as an example). ## Running & Writing Tests diff --git a/vendor/README.md b/vendor/README.md new file mode 100644 index 0000000000000..cbb1b43275459 --- /dev/null +++ b/vendor/README.md @@ -0,0 +1,13 @@ +# Vendoring third party dependencies + +Because we are working towards an agnostic Puppeteer that can run in any environment (see [#6125](https://github.com/puppeteer/puppeteer/issues/6125)) we cannot import common dependencies in a way that relies on Node's resolution to find them. For example, `import mitt from 'mitt'` works fine in Node, but in an ESM build running in the browser, the browser has no idea where to find `'mitt'`. + +Therefore we put all common dependencies into this directory, `vendor`. This means there are extra criteria for these dependencies; ideally they will not depend on any other modules. If they do, we should consider an alternative way of managing our dependencies. + +The process for updating a vendored dependency is: + +1. `npm install {DEP NAME HERE}` +2. `cp -r node_modules/DEP vendor/DEP` +3. Update `eslintrc.js` to forbid importing DEP directly (see the `Mitt` rule already defined in there). +4. Use the new DEP, and run `npm run tsc` to check everything compiles successfully. +5. If the dep ships as compiled JS, you may need to disable TypeScript checking the file. Add an entry to the `excludes` property of the TSConfig files in `vendor`. (again, see the entry that's already there for Mitt as an example). Don't forget to update both the ESM and CJS config files. From aced5523ac295547b0cb725f6be0d8947c5a1702 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 12:09:28 +0100 Subject: [PATCH 09/16] restructure test files --- CONTRIBUTING.md | 32 ++++++++++++++++++++++++++++++++ test/mocha-ts-require.js | 3 +++ test/tsconfig.test.json | 3 +++ tsconfig.json | 4 ---- 4 files changed, 38 insertions(+), 4 deletions(-) create mode 100644 test/tsconfig.test.json delete mode 100644 tsconfig.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0c898fed58010..91e47d4463624 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,6 +86,38 @@ npm run tsc - Try to avoid the use of `any` when possible. Consider `unknown` as a better alternative. You are able to use `any` if needbe, but it will generate an ESLint warning. +## Project structure and TypeScript compilation + +The code in Puppeteer is split primarily into two folders: + +- `src` contains all source code +- `vendor` contains all dependencies that we've vendored into the codebase. See the [`vendor/README.md`](https://github.com/puppeteer/puppeteer/blob/main/vendor/README.md) for details. + +We structure these using TypeScript's project references, which lets us treat each folder like a standalone TypeScript project. + +### Shipping CJS and ESM bundles + +Currently Puppeteer ships two bundles; a CommonJS version for Node and an ESM bundle for the browser. Therefore we maintain two `tsconfig` files for each project; `tsconfig.esm.json` and `tsconfig.cjs.json`. At build time we compile twice, once outputting to CJS and another time to output to ESM. + +We compile into the `lib` directory which is what we publish on the npm repository and it's structured like so: + +``` +lib +- cjs + - puppeteer <== the output of compiling `src/tsconfig.cjs.json` + - vendor <== the output of compiling `vendor/tsconfig.cjs.json` +- esm + - puppeteer <== the output of compiling `src/tsconfig.esm.json` + - vendor <== the output of compiling `vendor/tsconfig.esm.json` +``` + +The main entry point for the Node module Puppeteer is `cjs-entry.js`. This imports `lib/cjs/puppeteer/index.js` and exposes it to Node users. + +### tsconfig for the tests + +We also maintain `test/tsconfig.test.json`. This is **only used to compile the unit test `*.spec.ts` files**. When the tests are run, we first compile Puppeteer as normal before running the unit tests **against the compiled output**. Doing this lets the test run against the compiled code we ship to users so it gives us more confidence in our compiled output being correct. + + ## API guidelines When authoring new API methods, consider the following: diff --git a/test/mocha-ts-require.js b/test/mocha-ts-require.js index 2bf2cc677eba1..a0ac64fa62b7a 100644 --- a/test/mocha-ts-require.js +++ b/test/mocha-ts-require.js @@ -1,3 +1,5 @@ +const path = require('path'); + require('ts-node').register({ /** * We ignore the lib/ directory because that's already been TypeScript @@ -5,4 +7,5 @@ require('ts-node').register({ * the unit tests. */ ignore: ['lib/*', 'node_modules'], + project: path.join(__dirname, 'tsconfig.test.json'), }); diff --git a/test/tsconfig.test.json b/test/tsconfig.test.json new file mode 100644 index 0000000000000..6ae022f65bf01 --- /dev/null +++ b/test/tsconfig.test.json @@ -0,0 +1,3 @@ +{ + "extends": "../tsconfig.base.json", +} diff --git a/tsconfig.json b/tsconfig.json deleted file mode 100644 index 45514fcd973c5..0000000000000 --- a/tsconfig.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "extends": "./tsconfig.base.json", - "include": ["test"] -} From 399be53797cac6e2f172c4821136bf1d630f52e0 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 12:12:59 +0100 Subject: [PATCH 10/16] misc fixes --- .eslintignore | 2 +- .eslintrc.js | 2 +- CONTRIBUTING.md | 4 +++- utils/doclint/cli.js | 8 ++++++-- 4 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.eslintignore b/.eslintignore index ef6d583e01198..7f38955118ae2 100644 --- a/.eslintignore +++ b/.eslintignore @@ -10,4 +10,4 @@ lib/ # We ignore this file because it uses ES imports which we don't yet use # in the Puppeteer src, so it trips up the ESLint-TypeScript parser. utils/doclint/generate_types/test/test.ts -src/common/third-party/ +vendor/ diff --git a/.eslintrc.js b/.eslintrc.js index bc67644f3affd..84821c4205731 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -93,7 +93,7 @@ module.exports = { paths: [{ name: "mitt", message: - "Import Mitt from the vendored location: src/common/third-party/mitt/src/index.js", + "Import Mitt from the vendored location: vendor/mitt/src/index.js", }], }], "import/extensions": ["error", "ignorePackages"] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91e47d4463624..96d528cb5214c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,11 +5,13 @@ * [Code reviews](#code-reviews) * [Code Style](#code-style) * [TypeScript guidelines](#typescript-guidelines) + * [Project structure and TypeScript compilation](#project-structure-and-typescript-compilation) + - [Shipping CJS and ESM bundles](#shipping-cjs-and-esm-bundles) + - [tsconfig for the tests](#tsconfig-for-the-tests) * [API guidelines](#api-guidelines) * [Commit Messages](#commit-messages) * [Writing Documentation](#writing-documentation) * [Adding New Dependencies](#adding-new-dependencies) - - [Vendoring third party dependencies](#vendoring-third-party-dependencies) * [Running & Writing Tests](#running--writing-tests) * [Public API Coverage](#public-api-coverage) * [Debugging Puppeteer](#debugging-puppeteer) diff --git a/utils/doclint/cli.js b/utils/doclint/cli.js index ef551ac080f84..abc3d2c84d65c 100755 --- a/utils/doclint/cli.js +++ b/utils/doclint/cli.js @@ -72,8 +72,12 @@ async function run() { const jsSources = [ ...(await Source.readdir(path.join(PROJECT_DIR, 'lib'))), ...(await Source.readdir(path.join(PROJECT_DIR, 'lib', 'cjs'))), - ...(await Source.readdir(path.join(PROJECT_DIR, 'lib', 'cjs', 'common'))), - ...(await Source.readdir(path.join(PROJECT_DIR, 'lib', 'cjs', 'node'))), + ...(await Source.readdir( + path.join(PROJECT_DIR, 'lib', 'cjs', 'puppeteer', 'common') + )), + ...(await Source.readdir( + path.join(PROJECT_DIR, 'lib', 'cjs', 'puppeteer', 'node') + )), ]; const allSrcCode = [...jsSources, ...tsSourcesNoDefinitions]; messages.push(...(await checkPublicAPI(page, mdSources, allSrcCode))); From 7468ce9a939fc224505d7eebab741eb4d5f52b06 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 12:17:14 +0100 Subject: [PATCH 11/16] fix install script --- install.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/install.js b/install.js index 402a72e0d2f60..5fe1314e4a6e8 100644 --- a/install.js +++ b/install.js @@ -29,7 +29,10 @@ const compileTypeScriptIfRequired = require('./typescript-if-required'); async function download() { await compileTypeScriptIfRequired(); // need to ensure TS is compiled before loading the installer - const { downloadBrowser, logPolitely } = require('./lib/cjs/install'); + const { + downloadBrowser, + logPolitely, + } = require('./lib/cjs/puppeteer/install'); if (process.env.PUPPETEER_SKIP_DOWNLOAD) { logPolitely( From 72505198ffcd4a416788cd8c754cf292d48b43c5 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 14:20:38 +0100 Subject: [PATCH 12/16] fix api extractor --- CONTRIBUTING.md | 4 ++++ api-extractor.json | 2 +- new-docs/puppeteer.md | 2 +- new-docs/puppeteer.protocol.css.cssmedia.md | 2 +- new-docs/puppeteer.protocol.css.cssmedia.source.md | 2 +- new-docs/puppeteer.protocol.md | 2 +- tsconfig.json | 11 +++++++++++ 7 files changed, 20 insertions(+), 5 deletions(-) create mode 100644 tsconfig.json diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 96d528cb5214c..043bf03705c67 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,6 +119,10 @@ The main entry point for the Node module Puppeteer is `cjs-entry.js`. This impor We also maintain `test/tsconfig.test.json`. This is **only used to compile the unit test `*.spec.ts` files**. When the tests are run, we first compile Puppeteer as normal before running the unit tests **against the compiled output**. Doing this lets the test run against the compiled code we ship to users so it gives us more confidence in our compiled output being correct. +### Root `tsconfig.json` + +The root `tsconfig.json` exists for the API Extractor; it has to find a `tsconfig.json` in the project's root directory. It is _not_ used for anything else. + ## API guidelines diff --git a/api-extractor.json b/api-extractor.json index b388a148a4906..3e7b9e66f625e 100644 --- a/api-extractor.json +++ b/api-extractor.json @@ -1,6 +1,6 @@ { "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json", - "mainEntryPointFilePath": "/lib/cjs/api-docs-entry.d.ts", + "mainEntryPointFilePath": "/lib/cjs/puppeteer/api-docs-entry.d.ts", "bundledPackages": [ "devtools-protocol" ], "apiReport": { diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 5e64b8e168171..ee5c2de12a696 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -85,7 +85,7 @@ | Namespace | Description | | --- | --- | -| [Protocol](./puppeteer.protocol.md) | \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Auto-generated by protocol-dts-generator.ts, do not edit manually. \* \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* | +| [Protocol](./puppeteer.protocol.md) | The Chrome DevTools protocol. | ## Variables diff --git a/new-docs/puppeteer.protocol.css.cssmedia.md b/new-docs/puppeteer.protocol.css.cssmedia.md index 3c79ef5fb021d..3efb162b165dc 100644 --- a/new-docs/puppeteer.protocol.css.cssmedia.md +++ b/new-docs/puppeteer.protocol.css.cssmedia.md @@ -18,7 +18,7 @@ export interface CSSMedia | --- | --- | --- | | [mediaList](./puppeteer.protocol.css.cssmedia.medialist.md) | [MediaQuery](./puppeteer.protocol.css.mediaquery.md)\[\] | Array of media queries. | | [range](./puppeteer.protocol.css.cssmedia.range.md) | [SourceRange](./puppeteer.protocol.css.sourcerange.md) | The associated rule (@media or @import) header range in the enclosing stylesheet (if available). | -| [source](./puppeteer.protocol.css.cssmedia.source.md) | ('mediaRule' \| 'importRule' \| 'linkedSheet' \| 'inlineSheet') | Source of the media query: "mediaRule" if specified by a rule, "importRule" if specified by an rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. | +| [source](./puppeteer.protocol.css.cssmedia.source.md) | ('mediaRule' \| 'importRule' \| 'linkedSheet' \| 'inlineSheet') | Source of the media query: "mediaRule" if specified by a @media rule, "importRule" if specified by an @import rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. | | [sourceURL](./puppeteer.protocol.css.cssmedia.sourceurl.md) | string | URL of the document containing the media query description. | | [styleSheetId](./puppeteer.protocol.css.cssmedia.stylesheetid.md) | [StyleSheetId](./puppeteer.protocol.css.stylesheetid.md) | Identifier of the stylesheet containing this object (if exists). | | [text](./puppeteer.protocol.css.cssmedia.text.md) | string | Media query text. | diff --git a/new-docs/puppeteer.protocol.css.cssmedia.source.md b/new-docs/puppeteer.protocol.css.cssmedia.source.md index ea482440c3f65..158fff3386b16 100644 --- a/new-docs/puppeteer.protocol.css.cssmedia.source.md +++ b/new-docs/puppeteer.protocol.css.cssmedia.source.md @@ -4,7 +4,7 @@ ## Protocol.CSS.CSSMedia.source property -Source of the media query: "mediaRule" if specified by a rule, "importRule" if specified by an rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. +Source of the media query: "mediaRule" if specified by a `@media` rule, "importRule" if specified by an `@import` rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. Signature: diff --git a/new-docs/puppeteer.protocol.md b/new-docs/puppeteer.protocol.md index 587ee69698bd0..ed932d4facd27 100644 --- a/new-docs/puppeteer.protocol.md +++ b/new-docs/puppeteer.protocol.md @@ -4,7 +4,7 @@ ## Protocol namespace -\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Auto-generated by protocol-dts-generator.ts, do not edit manually. \* \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* +The Chrome DevTools protocol. Signature: diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000000000..69717ed6d9b2e --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,11 @@ +/** + * This configuration only exists for the API Extractor tool. See the details in + * CONTRIBUTING.md that describes our TypeScript setup. +*/ +{ + "extends": "./tsconfig.base.json", + "compilerOptions": { + "noEmit": true + }, + "include": ["src"] +} From d7bb7e454c8205f5efffabd5f3e2ed9637c524c8 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 14:30:56 +0100 Subject: [PATCH 13/16] fix broken core --- cjs-entry-core.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cjs-entry-core.js b/cjs-entry-core.js index efcdb39027f7e..70e9b88040ff1 100644 --- a/cjs-entry-core.js +++ b/cjs-entry-core.js @@ -25,5 +25,5 @@ * This means that we can publish to CJS and ESM whilst maintaining the expected * import behaviour for CJS and ESM users. */ -const puppeteerExport = require('./lib/cjs/index-core'); +const puppeteerExport = require('./lib/cjs/puppeteer/index-core'); module.exports = puppeteerExport.default; From 89b2166d95308b91dc6d8aa7285581fe2e895828 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 15:10:09 +0100 Subject: [PATCH 14/16] fix up --- new-docs/puppeteer.md | 2 +- new-docs/puppeteer.protocol.css.cssmedia.md | 2 +- new-docs/puppeteer.protocol.css.cssmedia.source.md | 2 +- new-docs/puppeteer.protocol.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index ee5c2de12a696..5e64b8e168171 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -85,7 +85,7 @@ | Namespace | Description | | --- | --- | -| [Protocol](./puppeteer.protocol.md) | The Chrome DevTools protocol. | +| [Protocol](./puppeteer.protocol.md) | \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Auto-generated by protocol-dts-generator.ts, do not edit manually. \* \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* | ## Variables diff --git a/new-docs/puppeteer.protocol.css.cssmedia.md b/new-docs/puppeteer.protocol.css.cssmedia.md index 3efb162b165dc..3c79ef5fb021d 100644 --- a/new-docs/puppeteer.protocol.css.cssmedia.md +++ b/new-docs/puppeteer.protocol.css.cssmedia.md @@ -18,7 +18,7 @@ export interface CSSMedia | --- | --- | --- | | [mediaList](./puppeteer.protocol.css.cssmedia.medialist.md) | [MediaQuery](./puppeteer.protocol.css.mediaquery.md)\[\] | Array of media queries. | | [range](./puppeteer.protocol.css.cssmedia.range.md) | [SourceRange](./puppeteer.protocol.css.sourcerange.md) | The associated rule (@media or @import) header range in the enclosing stylesheet (if available). | -| [source](./puppeteer.protocol.css.cssmedia.source.md) | ('mediaRule' \| 'importRule' \| 'linkedSheet' \| 'inlineSheet') | Source of the media query: "mediaRule" if specified by a @media rule, "importRule" if specified by an @import rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. | +| [source](./puppeteer.protocol.css.cssmedia.source.md) | ('mediaRule' \| 'importRule' \| 'linkedSheet' \| 'inlineSheet') | Source of the media query: "mediaRule" if specified by a rule, "importRule" if specified by an rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. | | [sourceURL](./puppeteer.protocol.css.cssmedia.sourceurl.md) | string | URL of the document containing the media query description. | | [styleSheetId](./puppeteer.protocol.css.cssmedia.stylesheetid.md) | [StyleSheetId](./puppeteer.protocol.css.stylesheetid.md) | Identifier of the stylesheet containing this object (if exists). | | [text](./puppeteer.protocol.css.cssmedia.text.md) | string | Media query text. | diff --git a/new-docs/puppeteer.protocol.css.cssmedia.source.md b/new-docs/puppeteer.protocol.css.cssmedia.source.md index 158fff3386b16..ea482440c3f65 100644 --- a/new-docs/puppeteer.protocol.css.cssmedia.source.md +++ b/new-docs/puppeteer.protocol.css.cssmedia.source.md @@ -4,7 +4,7 @@ ## Protocol.CSS.CSSMedia.source property -Source of the media query: "mediaRule" if specified by a `@media` rule, "importRule" if specified by an `@import` rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. +Source of the media query: "mediaRule" if specified by a rule, "importRule" if specified by an rule, "linkedSheet" if specified by a "media" attribute in a linked stylesheet's LINK tag, "inlineSheet" if specified by a "media" attribute in an inline stylesheet's STYLE tag. Signature: diff --git a/new-docs/puppeteer.protocol.md b/new-docs/puppeteer.protocol.md index ed932d4facd27..587ee69698bd0 100644 --- a/new-docs/puppeteer.protocol.md +++ b/new-docs/puppeteer.protocol.md @@ -4,7 +4,7 @@ ## Protocol namespace -The Chrome DevTools protocol. +\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Auto-generated by protocol-dts-generator.ts, do not edit manually. \* \*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\* Signature: From 594ce45c2ee8180b904cba9954b7f692aa669999 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 16:27:58 +0100 Subject: [PATCH 15/16] doc update --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 043bf03705c67..90f9a1ac0a88a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,7 @@ * [Project structure and TypeScript compilation](#project-structure-and-typescript-compilation) - [Shipping CJS and ESM bundles](#shipping-cjs-and-esm-bundles) - [tsconfig for the tests](#tsconfig-for-the-tests) + - [Root `tsconfig.json`](#root-tsconfigjson) * [API guidelines](#api-guidelines) * [Commit Messages](#commit-messages) * [Writing Documentation](#writing-documentation) From 14f6d6d9a20477929cdc14352fca378b42311094 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Tue, 14 Jul 2020 16:29:00 +0100 Subject: [PATCH 16/16] help with debugging --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 114c70d6968d7..d71e5fcbae5ca 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,7 @@ "apply-next-version": "node utils/apply_next_version.js", "test-install": "scripts/test-install.sh", "generate-docs": "npm run tsc && api-extractor run --local --verbose && api-documenter markdown -i temp -o new-docs", - "ensure-new-docs-up-to-date": "npm run generate-docs && exit `git status --porcelain | head -255 | wc -l`", + "ensure-new-docs-up-to-date": "npm run generate-docs && git status && exit `git status --porcelain | head -255 | wc -l`", "generate-dependency-graph": "echo 'Requires graphviz installed locally!' && depcruise --exclude 'api.ts' --do-not-follow '^node_modules' --output-type dot src/index.ts | dot -T png > dependency-chart.png", "ensure-correct-devtools-protocol-revision": "ts-node scripts/ensure-correct-devtools-protocol-package" },