getting the file uploads stuff more in line with the actual way the API expects things now

Author: newhouse

README.md

@@ -117,10 +117,11 @@ Creates an Etch Packet and optionally sends it to the first signer.
 
 ### Class Methods
 
-##### prepareGraphQLFile(pathOrStreamOrBuffer[, options])
+##### prepareGraphQLFile(pathOrStreamLikeThing[, options])
 A nice helper to prepare a Stream-backed or Buffer-backed file upload for use with our GraphQL API.
-* `pathOrStream` (String | Stream | Buffer) - An existing `Stream` OR an existing `Buffer` OR a string representing a fully resolved path to a file to be read into a new `Stream`.
-* `options` (Object) - [UploadOptions](#uploadoptions) for the resulting object.
+* `pathOrStreamLikeThing` (String | Stream | Buffer) - An existing `Stream`, `Buffer` or other Stream-like thing supported by [FormData.append](https://github.com/form-data/form-data#void-append-string-field-mixed-value--mixed-options-) OR a string representing a fully resolved path to a file to be read into a new `Stream`.
+* `options` (Object) - Anything supported by [FormData.append](https://github.com/form-data/form-data#void-append-string-field-mixed-value--mixed-options-). Likely required when providing a non-standard stream. From the `form-data` docs:
+  > Form-Data can recognize and fetch all the required information from common types of streams (fs.readStream, http.response and mikeal's request), for some other types of streams you'd need to provide "file"-related information manually
 * Returns an `Object` that is properly formatted to be coerced by the client for use against our GraphQL API wherever an `Upload` type is required.
 
 ### Types
@@ -135,16 +136,6 @@ Options for the Anvil Client. Defaults are shown after each option key.
 }
 ```
 
-##### UploadOptions
-
-Options for the upload preparation class methods.
-```js
-{
-  filename: <filename>, // String
-  mimetype: <mimetype> // String
-}
-```
-
 ### Rate Limits
 
 Our API has request rate limits in place. This API client handles `429 Too Many Requests` errors by waiting until it can retry again, then retrying the request. The client attempts to avoid `429` errors by throttling requests after the number of requests within the specified time period has been reached.

package.json

@@ -55,7 +55,6 @@
     "form-data": "^3.0.0",
     "limiter": "^1.1.5",
     "lodash.get": "^4.4.2",
-    "mime-types": "^2.1.27",
     "node-fetch": "^2.6.0"
   },
   "resolutions": {

src/UploadWithOptions.js

@@ -0,0 +1,20 @@
+class UploadWithOptions {
+  constructor (streamLikeThing, formDataAppendOptions) {
+    this.streamLikeThing = streamLikeThing
+    this.formDataAppendOptions = formDataAppendOptions
+  }
+
+  get options () {
+    return this.formDataAppendOptions
+  }
+
+  get file () {
+    return this.streamLikeThing
+  }
+
+  appendToForm (form, fieldName) {
+    form.append(fieldName, this.streamLikeThing, this.formDataAppendOptions)
+  }
+}
+
+module.exports = UploadWithOptions

src/index.js

@@ -1,14 +1,13 @@
 const fs = require('fs')
-const path = require('path')
 
 const get = require('lodash.get')
 const fetch = require('node-fetch')
 const FormData = require('form-data')
-const Mime = require('mime-types')
 const AbortController = require('abort-controller')
 const { extractFiles } = require('extract-files')
 const { RateLimiter } = require('limiter')
 
+const UploadWithOptions = require('./UploadWithOptions')
 const { version, description } = require('../package.json')
 
 const {
@@ -63,12 +62,25 @@ class Anvil {
     this.limiter = new RateLimiter(this.requestLimit, this.requestLimitMS, true)
   }
 
-  static prepareGraphQLFile (pathOrStreamOrBuffer, options) {
-    if (pathOrStreamOrBuffer instanceof Buffer) {
-      return this._prepareGraphQLBuffer(pathOrStreamOrBuffer, options)
+  /**
+   * Perform some handy/necessary things for a GraphQL file upload to make it work
+   * with this client and with our backend
+   *
+   * @param  {string|Buffer|Stream-like-thing} pathOrStreamLikeThing - Either a string path to a file,
+   *   a Buffer, or a Stream-like thing that is compatible with form-data as an append.
+   * @param  {object} formDataAppendOptions - User can specify options to be passed to the form-data.append
+   *   call. This should be done if a stream-like thing is not one of the common types that
+   *   form-data can figure out on its own.
+   *
+   * @return {UploadWithOptions} - A class that wraps the stream-like-thing and any options
+   *   up together nicely in a way that we can also tell that it was us who did it.
+   */
+  static prepareGraphQLFile (pathOrStreamLikeThing, options) {
+    if (typeof pathOrStreamLikeThing === 'string') {
+      pathOrStreamLikeThing = fs.createReadStream(pathOrStreamLikeThing)
     }
 
-    return this._prepareGraphQLStream(pathOrStreamOrBuffer, options)
+    return new UploadWithOptions(pathOrStreamLikeThing, options)
   }
 
   fillPDF (pdfTemplateID, payload, clientOptions = {}) {
@@ -145,17 +157,22 @@ class Anvil {
 
       i = 0
       filesMap.forEach((paths, file) => {
-        // If this is a Stream, will attach a listener to the 'error' event so that we
+        let appendOptions = {}
+        if (file instanceof UploadWithOptions) {
+          appendOptions = file.formDataAppendOptions
+          file = file.file
+        }
+        // If this is a stream-like thing, attach a listener to the 'error' event so that we
         // can cancel the API call if something goes wrong
-        if (file instanceof fs.ReadStream) {
+        if (typeof file.on === 'function') {
           file.on('error', (err) => {
             console.warn(err)
             abortController.abort()
           })
         }
+
         // Pass in some things explicitly to the form.append so that we get the
         // desired/expected filename and mimetype, etc
-        const appendOptions = extractFormAppendOptions({ paths, object: originalOperation })
         form.append(`${++i}`, file, appendOptions)
       })
 
@@ -321,22 +338,6 @@ class Anvil {
     })
   }
 
-  static _prepareGraphQLStream (pathOrStream, options) {
-    if (typeof pathOrStream === 'string') {
-      pathOrStream = fs.createReadStream(pathOrStream)
-    }
-
-    return this._prepareGraphQLStreamOrBuffer(pathOrStream, options)
-  }
-
-  static _prepareGraphQLBuffer (pathOrBuffer, options) {
-    if (typeof pathOrBuffer === 'string') {
-      pathOrBuffer = fs.readFileSync(pathOrBuffer)
-    }
-
-    return this._prepareGraphQLStreamOrBuffer(pathOrBuffer, options)
-  }
-
   static _prepareGraphQLBase64 (data, options = {}) {
     const { filename, mimetype } = options
     if (!filename) {
@@ -357,65 +358,6 @@ class Anvil {
       mimetype,
     }
   }
-
-  static _prepareGraphQLStreamOrBuffer (streamOrBuffer, options) {
-    const filename = this._getFilename(streamOrBuffer, options)
-    const mimetype = this._getMimetype(streamOrBuffer, options)
-    return {
-      name: filename,
-      mimetype,
-      file: streamOrBuffer,
-    }
-  }
-
-  static _getFilename (thing, options = {}) {
-    // Very heavily influenced by:
-    // https://github.com/form-data/form-data/blob/55d90ce4a4c22b0ea0647991d85cb946dfb7395b/lib/form_data.js#L217
-
-    if (typeof options.filepath === 'string') {
-      // custom filepath for relative paths
-      return path.normalize(options.filepath).replace(/\\/g, '/')
-    }
-    if (options.filename || thing.name || thing.path) {
-      // custom filename take precedence
-      // formidable and the browser add a name property
-      // fs- and request- streams have path property
-      return path.basename(options.filename || thing.name || thing.path)
-    }
-    if (thing.readable && Object.prototype.hasOwnProperty.call(thing, 'httpVersion')) {
-      // or try http response
-      return path.basename(thing.client._httpMessage.path || '')
-    }
-
-    throw new Error('Unable to determine file name for this upload. Please pass it via options.filename.')
-  }
-
-  static _getMimetype (thing, options = {}) {
-    // Very heavily influenced by:
-    // https://github.com/form-data/form-data/blob/55d90ce4a4c22b0ea0647991d85cb946dfb7395b/lib/form_data.js#L243
-
-    // use custom content-type above all
-    if (typeof options.mimetype === 'string') {
-      return options.mimetype
-    }
-
-    // or try `name` from formidable, browser
-    if (thing.name || thing.path) {
-      return Mime.lookup(thing.name || thing.path)
-    }
-
-    // or if it's http-reponse
-    if (thing.readable && Object.prototype.hasOwnProperty.call(thing, 'httpVersion')) {
-      return thing.headers['content-type'] || thing.headers['Content-Type']
-    }
-
-    // or guess it from the filepath or filename
-    if ((options.filepath || options.filename)) {
-      Mime.lookup(options.filepath || options.filename)
-    }
-
-    throw new Error('Unable to determine mime type for this upload. Please pass it via options.mimetype.')
-  }
 }
 
 function getRetryMS (retryAfterSeconds) {
@@ -428,23 +370,4 @@ function sleep (ms) {
   })
 }
 
-function extractFormAppendOptions ({ paths, object }) {
-  const length = paths.length
-  if (length !== 1) {
-    if (length === 0) {
-      throw new Error('No file map paths received')
-    }
-    console.warn(`WARNING: received ${length} file map paths. Expected exactly 1.`)
-  }
-  const path = paths[0].split('.')
-  path.pop()
-
-  const parent = get(object, path.join('.'))
-
-  return {
-    filename: parent.name,
-    contentType: parent.mimetype,
-  }
-}
-
 module.exports = Anvil

src/validation.js

@@ -1,18 +1,18 @@
 const fs = require('fs')
 
+const UploadWithOptions = require('./UploadWithOptions')
+
 // https://www.npmjs.com/package/extract-files/v/6.0.0#type-extractablefilematcher
 function isFile (value) {
-  return value instanceof fs.ReadStream || value instanceof Buffer
+  return value instanceof UploadWithOptions || value instanceof fs.ReadStream || value instanceof Buffer
 }
 
 function graphQLUploadSchemaIsValid (schema, parent, key) {
   if (typeof schema === 'undefined') {
     return true
   }
 
-  // There is not a great/easy/worthwhile way to determine if a string is base64-encoded data,
-  // so our best proxy is to check the keyname
-  if (key !== 'base64File') {
+  if (key !== 'file') {
     if (schema instanceof Array) {
       return schema.every((subSchema) => graphQLUploadSchemaIsValid(subSchema, schema))
     }
@@ -21,35 +21,26 @@ function graphQLUploadSchemaIsValid (schema, parent, key) {
       return Object.entries(schema).every(([key, subSchema]) => graphQLUploadSchemaIsValid(subSchema, schema, key))
     }
 
-    if (!isFile(schema)) {
-      return true
-    }
+    return !isFile(schema)
   }
 
+  // OK, the key is 'file'
+
   // All flavors should be nested, and not top-level
-  if (!parent) {
+  if (!(parent && parent.file === schema)) {
     return false
   }
 
-  // File Upload
-  if (key === 'file') {
-    if (parent.file !== schema) {
-      return false
-    }
-
-    return ['name', 'mimetype'].every((requiredKey) => parent[requiredKey])
-  }
-
   // Base64 Upload
-  if (key === 'base64File') {
-    if (parent.base64File !== schema) {
-      return false
-    }
-
-    return ['filename', 'mimetype'].every((requiredKey) => schema[requiredKey])
+  if (schema.data) {
+    // Must be a string and also have the provided keys
+    return (
+      typeof schema.data === 'string' &&
+      ['filename', 'mimetype'].every((requiredKey) => schema[requiredKey])
+    )
   }
 
-  return false
+  return isFile(schema)
 }
 
 module.exports = {