Improve typescript accuracy

[connorjclark]

The intended way to use puppeteer + typescript today is by installing @types/puppeteer. However, there are some gaps in these types:

• (big) CDPSession is ignorant of the protocol commands / events and return types. https://github.com/DefinitelyTyped/DefinitelyTyped/blob/9f57df89f30bacee1d46dfbf40a08132b4b059ef/types/puppeteer/index.d.ts#L2151
• (nit) Page.emulate(emulateOptions) - types claim that both viewport and userAgent are optional, but actually both are required https://github.com/DefinitelyTyped/DefinitelyTyped/blob/9f57df89f30bacee1d46dfbf40a08132b4b059ef/types/puppeteer/index.d.ts#L519
• I use very little of the API surface, there are likely more.

These discrepancies can be avoided if the type definitions are generated from the source directly.

Approach 1: Generate declaration files from JS

This seemed like the ideal approach - generate a .d.ts for every module and publish on npm. Users could use the types like this:

const Browser = require('puppeteer/lib/Browser');

interface MyInterface {
  browser: Browser;
}

Ultimately, this didn't work, I think due to bugs within TS. Here's what would need to be done.

Upgrade to TS 3.7

3.7 added support of --declaration with --allowJs. microsoft/TypeScript#7546 (comment)

tsc errors for events

This pattern trips up TS when generated the declaration file:

const EventEmitter = require('events');

class Blah extends EventEmitter {...}

The error manifests like this:

Using const EventEmitter = require('events').EventEmitter fixes this. Yeah, that works - it was originally the only way to import EventEmitter, and has stuck around. TS doesn't error b/c @types/node references a non-exported name for the default export, but for this named export it doesn't.

But, all modules that import a puppeteer class that extends EventEmitter still get the same error:

Declaration emit for this file requires using private name 'Page' from module '"/Users/cjamcl/src/puppeteer/lib/Page"'. An explicit type annotation may unblock declaration emit.

So, this is a blocker.

Bad generated declaration files

USKeyboardLayout.js generates this .d.ts file:

declare const _exports: {
    [x: string]: KeyDefinition;
};
export = _exports;
export type KeyDefinition = {
    keyCode?: number;
    shiftKeyCode?: number;
    key?: string;
    shiftKey?: string;
    code?: string;
    text?: string;
    shiftText?: string;
    location?: number;
};

Which isn't even valid:

Another blocker.

:(

At this point, I gave up.

Approach 2: Convert to TypeScript

This would certainly make great types available for puppeteer, but would be a lot of work.

Approach 3: Just fixup @types/puppeteer

At the very least, I'd like to fix the lack of good CDP types in @types/puppeteer. Puppeteer internally defines these in lib/externals.d.ts. But it uses a protocol.d.ts that is generated based on the packaged Chromium version, so it makes sense to just import that file into @types/puppeteer:

import Protocol from 'puppeteer/lib/protocol';

...

export interface CDPSession extends EventEmitter {
  /**
   * Detaches session from target. Once detached, session won't emit any events and can't be used
   * to send messages.
   */
  detach(): Promise<void>;

  on<T extends keyof Protocol.Events>(event: T, listener: (arg: Protocol.Events[T]) => void): this;
  
  /**
   * @param method Protocol method name
   * @param parameters Protocol parameters
   */
  send<T extends keyof Protocol.CommandParameters>(method: T, parameters?: Protocol.CommandParameters[T]): Promise<Protocol.CommandReturnValues[T]>;
}

This requires publishing protocol.d.ts to npm, and tweaking the script that generates that file to export default Protocol; so it can be imported.

With these changes, the following would be well-typed:

const flattenedDocument = await session.send('DOM.getFlattenedDocument', { depth: -1 }); // errors if command name + param type do not match up

session.on('CSS.styleSheetAdded', styleSheetData => { ... }); // event data is properly typed

---

Some docs on how to use TypeScript would be good. Basically:

1. install @types/puppeteer
2. Using js and jsdoc ...

/** @typedef {import('puppeteer').Browser} Browser */
/** @typedef {import('puppeteer').CDPSession} CDPSession */
/** @typedef {import('puppeteer').Page} Page */

/**
 * @typedef MyType
 * @property {Browser} browser
 * @property {CDPSession} session
 * @property {Page} page
 */

[JoelEinbinder]

Take a look at utils/doclint/generate_types

[SimonSchick]

@connorjclark I amended the fix for the emulate types in my puppeteer v2 PR DefinitelyTyped/DefinitelyTyped#40284

[stale]

We're marking this issue as unconfirmed because it has not had recent activity and we weren't able to confirm it yet. It will be closed if no further activity occurs within the next 30 days.

[stale]

We are closing this issue. If the issue still persists in the latest version of Puppeteer, please reopen the issue and update the description. We will try our best to accomodate it!