Clearer package and function createUploadLink description.

Fixes #247 .

changelog.md

@@ -26,6 +26,7 @@
 - Simplified JSDoc related package scripts now that [`jsdoc-md`](https://npm.im/jsdoc-md) v10 automatically generates a Prettier formatted readme.
 - Added a package `test:jsdoc` script that checks the readme API docs are up to date with the source JSDoc.
 - Use the `.js` file extension in internal `require` paths.
+- Clearer package and function `createUploadLink` description, fixing [#247](https://github.com/jaydenseric/apollo-upload-client/issues/247).
 - Updated a URL in the changelog entry for v14.0.0.
 - Documentation updates.
 

package.json

@@ -1,7 +1,7 @@
 {
   "name": "apollo-upload-client",
   "version": "14.1.3",
-  "description": "A terminating Apollo Link for Apollo Client that allows FileList, File, Blob or ReactNativeFile instances within query or mutation variables and sends GraphQL multipart requests.",
+  "description": "A terminating Apollo Link for Apollo Client that fetches a GraphQL multipart request if the GraphQL variables contain files (by default FileList, File, Blob, or ReactNativeFile instances), or else fetches a regular GraphQL POST or GET request (depending on the config and GraphQL operation).",
   "license": "MIT",
   "author": {
     "name": "Jayden Seric",

public/createUploadLink.js

@@ -17,21 +17,20 @@ const isExtractableFile = require('./isExtractableFile.js');
 /**
  * Creates a
  * [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link)
- * capable of file uploads.
- *
- * The link matches and extracts files in the GraphQL operation. If there are
- * files it uses a
- * [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData)
- * instance as the
- * [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch)
- * `options.body` to make a
- * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec),
- * otherwise it sends a regular POST request.
+ * for [Apollo Client](https://apollographql.com/docs/react) that fetches a
+ * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec)
+ * if the GraphQL variables contain files (by default
+ * [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList),
+ * [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File),
+ * [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob), or
+ * [`ReactNativeFile`](#class-reactnativefile) instances), or else fetches a
+ * regular
+ * [GraphQL POST or GET request](https://apollographql.com/docs/apollo-server/requests)
+ * (depending on the config and GraphQL operation).
  *
  * Some of the options are similar to the
  * [`createHttpLink` options](https://apollographql.com/docs/react/api/link/apollo-link-http/#httplink-constructor-options).
  * @see [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
- * @see [`apollo-link` on GitHub](https://github.com/apollographql/apollo-link).
  * @kind function
  * @name createUploadLink
  * @param {object} options Options.
@@ -45,7 +44,7 @@ const isExtractableFile = require('./isExtractableFile.js');
  * @param {string} [options.credentials] Overrides `options.fetchOptions.credentials`.
  * @param {object} [options.headers] Merges with and overrides `options.fetchOptions.headers`.
  * @param {boolean} [options.includeExtensions=false] Toggles sending `extensions` fields to the GraphQL server.
- * @returns {ApolloLink} A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) capable of file uploads.
+ * @returns {ApolloLink} A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link).
  * @example <caption>Ways to `import`.</caption>
  * ```js
  * import { createUploadLink } from 'apollo-upload-client';

readme.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://badgen.net/npm/v/apollo-upload-client)](https://npm.im/apollo-upload-client) [![CI status](https://github.com/jaydenseric/apollo-upload-client/workflows/CI/badge.svg)](https://github.com/jaydenseric/apollo-upload-client/actions)
 
-A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) for [Apollo Client](https://apollographql.com/docs/react) that allows [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList), [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) or [`ReactNativeFile`](#class-reactnativefile) instances within query or mutation variables and sends [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec).
+A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) for [Apollo Client](https://apollographql.com/docs/react) that fetches a [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec) if the GraphQL variables contain files (by default [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList), [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob), or [`ReactNativeFile`](#class-reactnativefile) instances), or else fetches a regular [GraphQL POST or GET request](https://apollographql.com/docs/apollo-server/requests) (depending on the config and GraphQL operation).
 
 ## Setup
 
@@ -185,9 +185,7 @@ _A file in [React Native](https://reactnative.dev) that can be used in query or
 
 ### function createUploadLink
 
-Creates a [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) capable of file uploads.
-
-The link matches and extracts files in the GraphQL operation. If there are files it uses a [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) instance as the [`fetch`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) `options.body` to make a [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec), otherwise it sends a regular POST request.
+Creates a [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) for [Apollo Client](https://apollographql.com/docs/react) that fetches a [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec) if the GraphQL variables contain files (by default [`FileList`](https://developer.mozilla.org/en-US/docs/Web/API/FileList), [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File), [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob), or [`ReactNativeFile`](#class-reactnativefile) instances), or else fetches a regular [GraphQL POST or GET request](https://apollographql.com/docs/apollo-server/requests) (depending on the config and GraphQL operation).
 
 Some of the options are similar to the [`createHttpLink` options](https://apollographql.com/docs/react/api/link/apollo-link-http/#httplink-constructor-options).
 
@@ -205,12 +203,11 @@ Some of the options are similar to the [`createHttpLink` options](https://apollo
 | `options.headers` | object? | Merges with and overrides `options.fetchOptions.headers`. |
 | `options.includeExtensions` | boolean? = `false` | Toggles sending `extensions` fields to the GraphQL server. |
 
-**Returns:** ApolloLink — A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link) capable of file uploads.
+**Returns:** ApolloLink — A [terminating Apollo Link](https://apollographql.com/docs/react/api/link/introduction/#the-terminating-link).
 
 #### See
 
 - [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec).
-- [`apollo-link` on GitHub](https://github.com/apollographql/apollo-link).
 
 #### Examples