From 1c8707a34aff01b2d69b35a389549f082d0f0467 Mon Sep 17 00:00:00 2001
From: Brian Schiller <bgschiller@gmail.com>
Date: Fri, 25 Jan 2019 11:03:55 -0700
Subject: [PATCH] puppeteer: safer args for page.eval and friends

page.evaluate and similar functions are currently typed as if
they accept 'any' args, but they will throw exceptions unless
the args are either Serializable (with JSON.stringify) or JSHandles.

In GoogleChrome/puppeteer#3591, @SimonSchick recommended that tighter
type definitions was a preferable way to address this rather than
runtime error checking.

I've been using these updated types in my project for the last couple of
months without problem.

I suspect that some of the X1, X2 type parameters should also
be changed to reflect that they can only be SerializableOrJSHandle,
but I wasn't sure how to change the existing UnwrapElementHandle<X1>
types.
---
 types/puppeteer/index.d.ts | 41 +++++++++++++++++++++++++++-----------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/types/puppeteer/index.d.ts b/types/puppeteer/index.d.ts
index bd65a70455..66c73e1f96 100644
--- a/types/puppeteer/index.d.ts
+++ b/types/puppeteer/index.d.ts
@@ -18,6 +18,19 @@ export type WrapElementHandle<X> = X extends Element ? ElementHandle<X> : X;
 /** Unwraps a DOM element out of an ElementHandle instance */
 export type UnwrapElementHandle<X> = X extends ElementHandle<infer E> ? E : X;
 
+export type Serializable =
+  | number
+  | string
+  | boolean
+  | null
+  | JSONArray
+  | JSONObject;
+export interface JSONArray extends Array<Serializable> { }
+export interface JSONObject {
+  [key: string]: Serializable;
+}
+export type SerializableOrJSHandle = Serializable | JSHandle;
+
 /** Defines `$eval` and `$$eval` for Page, Frame and ElementHandle. */
 export interface Evalable {
   /**
@@ -106,7 +119,7 @@ export interface Evalable {
   $eval<R>(
     selector: string,
     pageFunction: (element: Element, ...args: any[]) => R | Promise<R>,
-    ...args: any[],
+    ...args: SerializableOrJSHandle[],
   ): Promise<WrapElementHandle<R>>;
 
   /**
@@ -195,7 +208,7 @@ export interface Evalable {
   $$eval<R>(
     selector: string,
     pageFunction: (elements: Element[], ...args: any[]) => R | Promise<R>,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<WrapElementHandle<R>>;
 }
 
@@ -718,7 +731,7 @@ export interface Worker {
    */
   evaluate<T>(
     pageFunction: (...args: any[]) => T | Promise<T>,
-    ...args: any[],
+    ...args: SerializableOrJSHandle[],
   ): Promise<T>;
 
   /**
@@ -727,7 +740,7 @@ export interface Worker {
    */
   evaluateHandle<T>(
     pageFunction: (...args: any[]) => T | Promise<T>,
-    ...args: any[],
+    ...args: SerializableOrJSHandle[],
   ): Promise<T>;
 
   executionContext(): Promise<ExecutionContext>;
@@ -830,11 +843,11 @@ export interface ElementHandle<E extends Element = Element> extends JSHandle, Ev
 export interface ExecutionContext {
   evaluate(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<any>;
   evaluateHandle(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<JSHandle>;
   queryObjects(prototypeHandle: JSHandle): JSHandle;
 }
@@ -1141,7 +1154,7 @@ export interface FrameBase extends Evalable {
    */
   evaluate(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<any>;
 
   /**
@@ -1154,7 +1167,7 @@ export interface FrameBase extends Evalable {
    */
   evaluateHandle(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<JSHandle>;
 
   /** This method fetches an element with selector and focuses it. */
@@ -1219,7 +1232,11 @@ export interface FrameBase extends Evalable {
   /**
    * Shortcut for waitForFunction.
    */
-  waitFor(selector: ((...args: any[]) => any) | string, options?: WaitForSelectorOptions, ...args: any[]): Promise<any>;
+  waitFor(
+    selector: ((...args: any[]) => any) | string,
+    options?: WaitForSelectorOptions,
+    ...args: SerializableOrJSHandle[]
+  ): Promise<any>;
 
   /**
    * Allows waiting for various conditions.
@@ -1227,7 +1244,7 @@ export interface FrameBase extends Evalable {
   waitForFunction(
     fn: string | ((...args: any[]) => any),
     options?: PageFnOptions,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<any>;
 
   /**
@@ -1539,7 +1556,7 @@ export interface Page extends EventEmitter, FrameBase {
    */
   evaluateHandle(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<JSHandle>;
 
   /**
@@ -1550,7 +1567,7 @@ export interface Page extends EventEmitter, FrameBase {
    */
   evaluateOnNewDocument(
     fn: EvaluateFn,
-    ...args: any[]
+    ...args: SerializableOrJSHandle[]
   ): Promise<void>;
 
   /**