feat: export public types only

[jrandolf]

This PR does a few things:

• All exported artifacts are labeled with an accessor tag (@internal, @public, etc).
• The types.ts file (originally called api-docs-entry.ts) is auto-generated using utils/export-all.js.
• api-extractor only extracts non-@internal types.
• Several proxy properties of Puppeteer are deprecated and encourage importing them directly from 'puppeteer'.
• Some comments are fixed.
• Some internal symbols have been renamed.

[stevenwdv]

Does this mean that it's not possible to access the RemoteObject of a JSHandle anymore? (Or at least not without unsound casts.)
Because in that case, you could consider creating a way to somehow still access (parts of) it. It can actually be pretty useful for stuff like this:

A function that recursively unwraps handles unless they are handles to things that do not make sense unwrapped (functions, Nodes), which it leaves as JSHandles/ElementHandles.

For example, it transforms JSHandle<{elem: Element, score: number}[]> to {elem: ElementHandle<Element>, score: number}[].

async function unwrapHandle<T>(handle: JSHandle<T>): Promise<UnwrappedHandle<T>> {
	return await unwrapHandleEx(handle, () => true) as UnwrappedHandle<T>;
}

async function unwrapHandleEx<T>(handle: JSHandle<T>, shouldUnwrap: (className: string) => boolean = className => ['Object', 'Proxy'].includes(className)):
	  Promise<UnwrappedHandleEx<T>> {
	//XXX Replace _remoteObject with stable version if ever available

	// Leave functions & symbols wrapped
	if (['function', 'symbol'].includes(handle._remoteObject.type))
		return handle as UnwrappedHandleEx<T>;

	if (handle._remoteObject.type === 'object') {
		if ([undefined, 'proxy'].includes(handle._remoteObject.subtype)) {
			if (shouldUnwrap(handle._remoteObject.className!))
				return Object.fromEntries(await Promise.all([...await handle.getProperties()]
					  .map(async ([k, v]) => [k, await unwrapHandleEx(v, shouldUnwrap)]))) as UnwrappedHandleEx<T>;
		} else {
			if (handle._remoteObject.subtype === 'null')
				return null as UnwrappedHandleEx<T>;
			if (handle._remoteObject.subtype === 'array')
				return await Promise.all([...await handle.getProperties()]
					  .map(async ([, v]) => await unwrapHandleEx(v, shouldUnwrap))) as UnwrappedHandleEx<T>;
		}
		return handle as UnwrappedHandleEx<T>;

	} else  // Return other types such as numbers, booleans, bigints, etc. unwrapped
		return (handle._remoteObject.type === 'undefined'
			  ? undefined
			  : handle._remoteObject.value
			  ?? (handle._remoteObject.unserializableValue
					? eval(handle._remoteObject.unserializableValue)  // You may want to use a map here instead
					: await handle.jsonValue())) as UnwrappedHandleEx<T>;

(UnwrappedHandle* types excluded for brevity, but you can have them if you want)

[niieani]

Another problem this created is that because Protocol is not exported, the consumer needs to keep devtools-protocol version in sync with the one used by puppeteer, at least if they don't want to reach into a transitive dependency (i.e. undeclared in package.json).

Example where this is an issue: https://github.com/niieani/puppeteer-intercept-and-modify-requests/pull/4/files

[OrKoN]

@jrandolf could you please take a look? I think it makes sense to export Protocol too and create a documented way to access the remote object.

[jrandolf]

@niieani @stevenwdv Could you please file an issue for what you are requesting?