Core: Fill in & warn against jQuery.proxy

Fixes gh-460

Author: mgol

src/jquery/core.js

@@ -10,6 +10,7 @@ import "../disablePatches.js";
 var findProp,
 	arr = [],
 	push = arr.push,
+	slice = arr.slice,
 	sort = arr.sort,
 	splice = arr.splice,
 	class2type = {},
@@ -23,6 +24,19 @@ var findProp,
 	// to avoid O(N^2) behavior when the engine would try matching "\s+$" at each space position.
 	rtrim = /^[\s\uFEFF\xA0]+|([^\s\uFEFF\xA0])[\s\uFEFF\xA0]+$/g;
 
+function isFunction( obj ) {
+
+	// Support: Chrome <=57, Firefox <=52
+	// In some browsers, typeof returns "function" for HTML <object> elements
+	// (i.e., `typeof document.createElement( "object" ) === "function"`).
+	// We don't want to classify *any* DOM node as a function.
+	// Support: QtWeb <=3.8.5, WebKit <=534.34, wkhtmltopdf tool <=0.12.5
+	// Plus for old WebKit, typeof returns "function" for HTML collections
+	// (e.g., `typeof document.getElementsByTagName("div") === "function"`). (gh-4756)
+	return typeof obj === "function" && typeof obj.nodeType !== "number" &&
+		typeof obj.item !== "function";
+}
+
 migratePatchFunc( jQuery.fn, "init", function( arg1 ) {
 	var args = Array.prototype.slice.call( arguments );
 
@@ -180,6 +194,41 @@ if ( jQueryVersionSince( "3.3.0" ) ) {
 		}, "isWindow",
 		"jQuery.isWindow() is deprecated"
 	);
+
+	// Bind a function to a context, optionally partially applying any
+	// arguments.
+	// jQuery.proxy is deprecated to promote standards (specifically Function#bind)
+	// However, it is not slated for removal any time soon
+	migratePatchAndWarnFunc( jQuery, "proxy",
+		function( fn, context ) {
+			var tmp, args, proxy;
+
+			if ( typeof context === "string" ) {
+				tmp = fn[ context ];
+				context = fn;
+				fn = tmp;
+			}
+
+			// Quick check to determine if target is callable, in the spec
+			// this throws a TypeError, but we will just return undefined.
+			if ( !isFunction( fn ) ) {
+				return undefined;
+			}
+
+			// Simulated bind
+			args = slice.call( arguments, 2 );
+			proxy = function() {
+				return fn.apply( context || this, args.concat( slice.call( arguments ) ) );
+			};
+
+			// Set the guid of unique handler to the same of original handler, so it can be removed
+			proxy.guid = fn.guid = fn.guid || jQuery.guid++;
+
+			return proxy;
+		}, "proxy",
+		"jQuery.proxy() is deprecated"
+	);
+
 }
 
 if ( jQueryVersionSince( "4.0.0" ) ) {

test/unit/jquery/core.js

@@ -505,3 +505,59 @@ QUnit[ jQueryVersionSince( "4.0.0" ) ? "test" : "skip" ]( "jQuery.fn.splice", fu
 			"splice removed & added in-place" );
 	} );
 } );
+
+QUnit[ jQueryVersionSince( "3.3.0" ) ? "test" : "skip" ]( "jQuery.proxy", function( assert ) {
+	assert.expect( 10 );
+
+	var test2, test3, test4, fn, cb,
+		test = function() {
+			assert.equal( this, thisObject, "Make sure that scope is set properly." );
+		},
+		thisObject = { foo: "bar", method: test };
+
+	expectWarning( assert, "jQuery.proxy", 7, function() {
+
+		// Make sure normal works
+		test.call( thisObject );
+
+		// Basic scoping
+		jQuery.proxy( test, thisObject )();
+
+		// Another take on it
+		jQuery.proxy( thisObject, "method" )();
+
+		// Make sure it doesn't freak out
+		assert.equal( jQuery.proxy( null, thisObject ), undefined,
+			"Make sure no function was returned." );
+
+		// Partial application
+		test2 = function( a ) {
+			assert.equal( a, "pre-applied", "Ensure arguments can be pre-applied." );
+		};
+		jQuery.proxy( test2, null, "pre-applied" )();
+
+		// Partial application w/ normal arguments
+		test3 = function( a, b ) {
+			assert.equal( b, "normal", "Ensure arguments can be pre-applied and passed as usual." );
+		};
+		jQuery.proxy( test3, null, "pre-applied" )( "normal" );
+
+		// Test old syntax
+		test4 = {
+			"meth": function( a ) {
+				assert.equal( a, "boom", "Ensure old syntax works." );
+			}
+		};
+		jQuery.proxy( test4, "meth" )( "boom" );
+
+		// jQuery 1.9 improved currying with `this` object
+		fn = function() {
+			assert.equal( Array.prototype.join.call( arguments, "," ),
+				"arg1,arg2,arg3",
+				"args passed" );
+			assert.equal( this.foo, "bar", "this-object passed" );
+		};
+		cb = jQuery.proxy( fn, null, "arg1", "arg2" );
+		cb.call( thisObject, "arg3" );
+	} );
+} );

warnings.md

@@ -237,6 +237,12 @@ See jQuery-ui [commit](https://github.com/jquery/jquery-ui/commit/c0093b599fcd58
 
 **Solution:** Remove any use of `jQuery.isWindow()` from code. If it is truly needed it can be replaced with a check for `obj != null && obj === obj.window` which was the test used inside this method.
 
+### \[proxy\] JQMIGRATE: jQuery.proxy() is deprecated
+
+**Cause:** This method, while having some differences, is similar to native `Function.prototype.bind` so it got deprecated to promote usage of native `bind`.
+
+**Solution:** Replace any calls to `jQuery.proxy(fn, context, param1, param2)` with `fn.bind(context, param1, param2)`. Be careful if you use a proxied function for event handling as jQuery matches a proxied function to its original when removing event handlers which is not the case when native `bind` is used.
+
 ### \[shorthand-deprecated-v3\] JQMIGRATE: jQuery.fn.click() event shorthand is deprecated
 
 **Cause:** The `.on()` and `.trigger()` methods can set an event handler or generate an event for any event type, and should be used instead of the shortcut methods. This message also applies to the other event shorthands, including: blur, focus, focusin, focusout, resize, scroll, dblclick, mousedown, mouseup, mousemove, mouseover, mouseout, mouseenter, mouseleave, change, select, submit, keydown, keypress, keyup, and contextmenu.