Throw error if name argument is not provided to .file() when uploading a buffer (#418)

Fixes #344

props @cungminh2710, @mvhirsch

Author: kadamwhite

README.md

@@ -524,7 +524,7 @@ Files may be uploaded to the WordPress media library by creating a media record
 The file to upload can be specified as
 
 - a `String` describing an image file path, _e.g._ `'/path/to/the/image.jpg'`
-- a `Buffer` with file content, _e.g._ `new Buffer()`
+- a `Buffer` with file content, _e.g._ `Buffer.from()` (or the result of a `readFile` call)
 - a file object from a `<input>` element, _e.g._ `document.getElementById( 'file-input' ).files[0]`
 
 The file is passed into the `.file()` method:
@@ -533,7 +533,7 @@ The file is passed into the `.file()` method:
 wp.media().file(content [, name])...
 ```
 
-The optional second string argument specifies the file name to use for the uploaded media. If the name argument is omitted `file()` will try to infer a filename from the provided content.
+The optional second string argument specifies the file name to use for the uploaded media. If the name argument is omitted `file()` will try to infer a filename from the provided file path. Note that when uploading a Buffer object `name` is a required argument, because no name can be automatically inferred from the buffer.
 
 #### Adding Media to a Post
 

lib/constructors/wp-request.js

@@ -633,6 +633,11 @@ WPRequest.prototype.auth = function( credentials ) {
  *       .file( '/path/to/file.jpg' )
  *       .create({})...
  *
+ *     wp.media()
+ *       // Pass .file() an image as a Buffer object, and a filename string
+ *       .file( imgBuffer, 'desired-title.jpg' )
+ *       .create({})...
+ *
  * @example <caption>within a browser context</caption>
  *
  *     wp.media()
@@ -644,10 +649,14 @@ WPRequest.prototype.auth = function( credentials ) {
  * @chainable
  * @param {string|object} file   A path to a file (in Node) or an file object
  *                               (Node or Browser) to attach to the request
- * @param {string}        [name] An (optional) filename to use for the file
+ * @param {string}        [name] A filename to use for the file, required when
+ *                               providing file data as a Buffer object
  * @returns {WPRequest} The WPRequest instance (for chaining)
  */
 WPRequest.prototype.file = function( file, name ) {
+	if ( global.Buffer && file instanceof global.Buffer && ! name ) {
+		throw new Error( '.file(): File name is a required argument when uploading a Buffer' );
+	}
 	this._attachment = file;
 	// Explicitly set to undefined if not provided, to override any previously-
 	// set attachment name property that might exist from a prior `.file()` call