graphql-upload 15.0.2 → 16.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,5 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
4
-
5
3
  /**
6
4
  * [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec)
7
5
  * URL. Useful for error messages, etc.
@@ -9,4 +7,4 @@
9
7
  const GRAPHQL_MULTIPART_REQUEST_SPEC_URL =
10
8
  "https://github.com/jaydenseric/graphql-multipart-request-spec";
11
9
 
12
- module.exports = GRAPHQL_MULTIPART_REQUEST_SPEC_URL;
10
+ export default GRAPHQL_MULTIPART_REQUEST_SPEC_URL;
@@ -1,11 +1,10 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
3
+ import { GraphQLError, GraphQLScalarType } from "graphql";
4
4
 
5
- const { GraphQLScalarType, GraphQLError } = require("graphql");
6
- const Upload = require("./Upload.js");
5
+ import Upload from "./Upload.mjs";
7
6
 
8
- /** @typedef {import("./processRequest").FileUpload} FileUpload */
7
+ /** @typedef {import("./processRequest.mjs").FileUpload} FileUpload */
9
8
 
10
9
  /**
11
10
  * A GraphQL `Upload` scalar that can be used in a
@@ -13,13 +12,13 @@ const Upload = require("./Upload.js");
13
12
  * value in resolvers is a promise that resolves
14
13
  * {@link FileUpload file upload details} for processing and storage.
15
14
  * @example
16
- * A schema built using
15
+ * A schema built using the function
17
16
  * [`makeExecutableSchema`](https://www.graphql-tools.com/docs/api/modules/schema_src#makeexecutableschema)
18
17
  * from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema):
19
18
  *
20
19
  * ```js
21
- * const { makeExecutableSchema } = require("@graphql-tools/schema");
22
- * const GraphQLUpload = require("graphql-upload/GraphQLUpload.js");
20
+ * import { makeExecutableSchema } from "@graphql-tools/schema/makeExecutableSchema";
21
+ * import GraphQLUpload from "graphql-upload/GraphQLUpload.mjs";
23
22
  *
24
23
  * const schema = makeExecutableSchema({
25
24
  * typeDefs: `
@@ -34,8 +33,8 @@ const Upload = require("./Upload.js");
34
33
  * A manually constructed schema with an image upload mutation:
35
34
  *
36
35
  * ```js
37
- * const { GraphQLSchema, GraphQLObjectType, GraphQLBoolean } = require("graphql");
38
- * const GraphQLUpload = require("graphql-upload/GraphQLUpload.js");
36
+ * import { GraphQLBoolean, GraphQLObjectType, GraphQLSchema } from "graphql";
37
+ * import GraphQLUpload from "graphql-upload/GraphQLUpload.mjs";
39
38
  *
40
39
  * const schema = new GraphQLSchema({
41
40
  * mutation: new GraphQLObjectType({
@@ -61,6 +60,14 @@ const Upload = require("./Upload.js");
61
60
  * }),
62
61
  * });
63
62
  * ```
63
+ * @example
64
+ * In a [TypeScript](https://typescriptlang.org) module, how to import the type
65
+ * for the {@link FileUpload file upload details} that the
66
+ * {@linkcode GraphQLUpload} scalar resolver value promise resolves:
67
+ *
68
+ * ```ts
69
+ * import type { FileUpload } from "graphql-upload/processRequest.mjs";
70
+ * ```
64
71
  */
65
72
  const GraphQLUpload = new GraphQLScalarType({
66
73
  name: "Upload",
@@ -77,4 +84,4 @@ const GraphQLUpload = new GraphQLScalarType({
77
84
  },
78
85
  });
79
86
 
80
- module.exports = GraphQLUpload;
87
+ export default GraphQLUpload;
@@ -1,9 +1,7 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
4
-
5
- /** @typedef {import("./GraphQLUpload.js")} GraphQLUpload */
6
- /** @typedef {import("./processRequest.js")} processRequest */
3
+ /** @typedef {import("./GraphQLUpload.mjs").default} GraphQLUpload */
4
+ /** @typedef {import("./processRequest.mjs").default} processRequest */
7
5
 
8
6
  /**
9
7
  * A file expected to be uploaded as it was declared in the `map` field of a
@@ -12,18 +10,18 @@
12
10
  * this class wherever the file is expected in the GraphQL operation. The scalar
13
11
  * {@linkcode GraphQLUpload} derives it’s value from {@linkcode Upload.promise}.
14
12
  */
15
- class Upload {
13
+ export default class Upload {
16
14
  constructor() {
17
15
  /**
18
16
  * Promise that resolves file upload details. This should only be utilized
19
17
  * by {@linkcode GraphQLUpload}.
20
- * @type {Promise<import("./processRequest.js").FileUpload>}
18
+ * @type {Promise<import("./processRequest.mjs").FileUpload>}
21
19
  */
22
20
  this.promise = new Promise((resolve, reject) => {
23
21
  /**
24
22
  * Resolves the upload promise with the file upload details. This should
25
23
  * only be utilized by {@linkcode processRequest}.
26
- * @param {import("./processRequest.js").FileUpload} file File upload
24
+ * @param {import("./processRequest.mjs").FileUpload} file File upload
27
25
  * details.
28
26
  */
29
27
  this.resolve = (file) => {
@@ -31,7 +29,7 @@ class Upload {
31
29
  * The file upload details, available when the
32
30
  * {@linkcode Upload.promise} resolves. This should only be utilized by
33
31
  * {@linkcode processRequest}.
34
- * @type {import("./processRequest.js").FileUpload | undefined}
32
+ * @type {import("./processRequest.mjs").FileUpload | undefined}
35
33
  */
36
34
  this.file = file;
37
35
 
@@ -51,5 +49,3 @@ class Upload {
51
49
  this.promise.catch(() => {});
52
50
  }
53
51
  }
54
-
55
- module.exports = Upload;
@@ -1,8 +1,6 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
4
-
5
- const defaultProcessRequest = require("./processRequest.js");
3
+ import defaultProcessRequest from "./processRequest.mjs";
6
4
 
7
5
  /**
8
6
  * Creates [Express](https://expressjs.com) middleware that processes incoming
@@ -10,29 +8,30 @@ const defaultProcessRequest = require("./processRequest.js");
10
8
  * using {@linkcode processRequest}, ignoring non multipart requests. It sets
11
9
  * the request `body` to be similar to a conventional GraphQL POST request for
12
10
  * following GraphQL middleware to consume.
13
- * @param {import("./processRequest.js").ProcessRequestOptions & {
14
- * processRequest?: import("./processRequest.js").ProcessRequestFunction
11
+ * @param {import("./processRequest.mjs").ProcessRequestOptions & {
12
+ * processRequest?: import("./processRequest.mjs").ProcessRequestFunction
15
13
  * }} options Options.
16
14
  * @returns Express middleware.
17
15
  * @example
18
16
  * Basic [`express-graphql`](https://npm.im/express-graphql) setup:
19
17
  *
20
18
  * ```js
21
- * const express = require("express");
22
- * const graphqlHTTP = require("express-graphql");
23
- * const graphqlUploadExpress = require("graphql-upload/graphqlUploadExpress.js");
24
- * const schema = require("./schema.js");
19
+ * import express from "express";
20
+ * import expressGraphQL from "express-graphql";
21
+ * import graphqlUploadExpress from "graphql-upload/graphqlUploadExpress.mjs";
22
+ *
23
+ * import schema from "./schema.mjs";
25
24
  *
26
25
  * express()
27
26
  * .use(
28
27
  * "/graphql",
29
28
  * graphqlUploadExpress({ maxFileSize: 10000000, maxFiles: 10 }),
30
- * graphqlHTTP({ schema })
29
+ * expressGraphQL.graphqlHTTP({ schema })
31
30
  * )
32
31
  * .listen(3000);
33
32
  * ```
34
33
  */
35
- function graphqlUploadExpress({
34
+ export default function graphqlUploadExpress({
36
35
  processRequest = defaultProcessRequest,
37
36
  ...processRequestOptions
38
37
  } = {}) {
@@ -76,5 +75,3 @@ function graphqlUploadExpress({
76
75
 
77
76
  return graphqlUploadExpressMiddleware;
78
77
  }
79
-
80
- module.exports = graphqlUploadExpress;
@@ -1,8 +1,6 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
4
-
5
- const defaultProcessRequest = require("./processRequest.js");
3
+ import defaultProcessRequest from "./processRequest.mjs";
6
4
 
7
5
  /**
8
6
  * Creates [Koa](https://koajs.com) middleware that processes incoming
@@ -10,19 +8,21 @@ const defaultProcessRequest = require("./processRequest.js");
10
8
  * using {@linkcode processRequest}, ignoring non multipart requests. It sets
11
9
  * the request `body` to be similar to a conventional GraphQL POST request for
12
10
  * following GraphQL middleware to consume.
13
- * @param {import("./processRequest.js").ProcessRequestOptions & {
14
- * processRequest?: import("./processRequest.js").ProcessRequestFunction
11
+ * @param {import("./processRequest.mjs").ProcessRequestOptions & {
12
+ * processRequest?: import("./processRequest.mjs").ProcessRequestFunction
15
13
  * }} options Options.
16
14
  * @returns Koa middleware.
17
15
  * @example
18
16
  * Basic [`graphql-api-koa`](https://npm.im/graphql-api-koa) setup:
19
17
  *
20
18
  * ```js
21
- * const Koa = require("koa");
22
- * const bodyParser = require("koa-bodyparser");
23
- * const { errorHandler, execute } = require("graphql-api-koa");
24
- * const graphqlUploadKoa = require("graphql-upload/graphqlUploadKoa.js");
25
- * const schema = require("./schema.js");
19
+ * import errorHandler from "graphql-api-koa/errorHandler.mjs";
20
+ * import execute from "graphql-api-koa/execute.mjs";
21
+ * import graphqlUploadKoa from "graphql-upload/graphqlUploadKoa.mjs";
22
+ * import Koa from "koa";
23
+ * import bodyParser from "koa-bodyparser";
24
+ *
25
+ * import schema from "./schema.mjs";
26
26
  *
27
27
  * new Koa()
28
28
  * .use(errorHandler())
@@ -32,7 +32,7 @@ const defaultProcessRequest = require("./processRequest.js");
32
32
  * .listen(3000);
33
33
  * ```
34
34
  */
35
- function graphqlUploadKoa({
35
+ export default function graphqlUploadKoa({
36
36
  processRequest = defaultProcessRequest,
37
37
  ...processRequestOptions
38
38
  } = {}) {
@@ -65,5 +65,3 @@ function graphqlUploadKoa({
65
65
 
66
66
  return graphqlUploadKoaMiddleware;
67
67
  }
68
-
69
- module.exports = graphqlUploadKoa;
@@ -1,17 +1,13 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
4
-
5
3
  /**
6
4
  * Safely ignores a Node.js readable stream.
7
- * @param {import("stream").Readable} stream Node.js readable stream.
5
+ * @param {import("node:stream").Readable} stream Node.js readable stream.
8
6
  */
9
- function ignoreStream(stream) {
7
+ export default function ignoreStream(stream) {
10
8
  // Prevent an unhandled error from crashing the process.
11
9
  stream.on("error", () => {});
12
10
 
13
11
  // Waste the stream.
14
12
  stream.resume();
15
13
  }
16
-
17
- module.exports = ignoreStream;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphql-upload",
3
- "version": "15.0.2",
3
+ "version": "16.0.2",
4
4
  "description": "Middleware and an Upload scalar to add support for GraphQL multipart requests (file uploads via queries and mutations) to various Node.js GraphQL servers.",
5
5
  "license": "MIT",
6
6
  "author": {
@@ -27,22 +27,22 @@
27
27
  "mjs"
28
28
  ],
29
29
  "files": [
30
- "GRAPHQL_MULTIPART_REQUEST_SPEC_URL.js",
31
- "GraphQLUpload.js",
32
- "graphqlUploadExpress.js",
33
- "graphqlUploadKoa.js",
34
- "ignoreStream.js",
35
- "processRequest.js",
36
- "Upload.js"
30
+ "GRAPHQL_MULTIPART_REQUEST_SPEC_URL.mjs",
31
+ "GraphQLUpload.mjs",
32
+ "graphqlUploadExpress.mjs",
33
+ "graphqlUploadKoa.mjs",
34
+ "ignoreStream.mjs",
35
+ "processRequest.mjs",
36
+ "Upload.mjs"
37
37
  ],
38
38
  "sideEffects": false,
39
39
  "exports": {
40
- "./GraphQLUpload.js": "./GraphQLUpload.js",
41
- "./graphqlUploadExpress.js": "./graphqlUploadExpress.js",
42
- "./graphqlUploadKoa.js": "./graphqlUploadKoa.js",
40
+ "./GraphQLUpload.mjs": "./GraphQLUpload.mjs",
41
+ "./graphqlUploadExpress.mjs": "./graphqlUploadExpress.mjs",
42
+ "./graphqlUploadKoa.mjs": "./graphqlUploadKoa.mjs",
43
43
  "./package.json": "./package.json",
44
- "./processRequest.js": "./processRequest.js",
45
- "./Upload.js": "./Upload.js"
44
+ "./processRequest.mjs": "./processRequest.mjs",
45
+ "./Upload.mjs": "./Upload.mjs"
46
46
  },
47
47
  "engines": {
48
48
  "node": "^14.17.0 || ^16.0.0 || >= 18.0.0"
@@ -65,25 +65,25 @@
65
65
  "@types/node": "*",
66
66
  "@types/object-path": "^0.11.1",
67
67
  "busboy": "^1.6.0",
68
- "fs-capacitor": "^6.2.0",
68
+ "fs-capacitor": "^8.0.0",
69
69
  "http-errors": "^2.0.0",
70
70
  "object-path": "^0.11.8"
71
71
  },
72
72
  "devDependencies": {
73
73
  "@types/express": "^4.17.13",
74
- "@types/koa": "^2.13.4",
75
- "coverage-node": "^6.1.0",
76
- "eslint": "^8.18.0",
74
+ "@types/koa": "^2.13.5",
75
+ "coverage-node": "^8.0.0",
76
+ "eslint": "^8.23.0",
77
77
  "eslint-plugin-simple-import-sort": "^7.0.0",
78
78
  "express": "^4.18.1",
79
- "form-data-encoder": "^2.0.1",
80
- "graphql": "^16.5.0",
79
+ "form-data-encoder": "^2.1.0",
80
+ "graphql": "^16.6.0",
81
81
  "koa": "^2.13.4",
82
82
  "node-abort-controller": "^3.0.1",
83
- "node-fetch": "^3.2.6",
83
+ "node-fetch": "^3.2.10",
84
84
  "prettier": "^2.6.2",
85
- "test-director": "^8.0.2",
86
- "typescript": "^4.7.4"
85
+ "test-director": "^10.0.0",
86
+ "typescript": "^4.8.2"
87
87
  },
88
88
  "scripts": {
89
89
  "eslint": "eslint .",
@@ -1,16 +1,15 @@
1
1
  // @ts-check
2
2
 
3
- "use strict";
3
+ import busboy from "busboy";
4
+ import { WriteStream } from "fs-capacitor";
5
+ import createError from "http-errors";
6
+ import objectPath from "object-path";
4
7
 
5
- const busboy = require("busboy");
6
- const { WriteStream } = require("fs-capacitor");
7
- const createError = require("http-errors");
8
- const objectPath = require("object-path");
9
- const GRAPHQL_MULTIPART_REQUEST_SPEC_URL = require("./GRAPHQL_MULTIPART_REQUEST_SPEC_URL.js");
10
- const ignoreStream = require("./ignoreStream.js");
11
- const Upload = require("./Upload.js");
8
+ import GRAPHQL_MULTIPART_REQUEST_SPEC_URL from "./GRAPHQL_MULTIPART_REQUEST_SPEC_URL.mjs";
9
+ import ignoreStream from "./ignoreStream.mjs";
10
+ import Upload from "./Upload.mjs";
12
11
 
13
- /** @typedef {import("./GraphQLUpload.js")} GraphQLUpload */
12
+ /** @typedef {import("./GraphQLUpload.mjs").default} GraphQLUpload */
14
13
 
15
14
  /**
16
15
  * Processes an incoming
@@ -23,7 +22,7 @@ const Upload = require("./Upload.js");
23
22
  * with appropriate HTTP status codes. Used to create custom middleware.
24
23
  * @type {ProcessRequestFunction}
25
24
  */
26
- function processRequest(
25
+ export default function processRequest(
27
26
  request,
28
27
  response,
29
28
  {
@@ -57,8 +56,8 @@ function processRequest(
57
56
  let map;
58
57
 
59
58
  const parser = busboy({
60
- // @ts-ignore This is about to change with `busboy` v1 types.
61
59
  headers: request.headers,
60
+ defParamCharset: "utf8",
62
61
  limits: {
63
62
  fieldSize: maxFieldSize,
64
63
  fields: 2, // Only operations and map.
@@ -346,8 +345,6 @@ function processRequest(
346
345
  });
347
346
  }
348
347
 
349
- module.exports = processRequest;
350
-
351
348
  /**
352
349
  * File upload details that are only available after the file’s field in the
353
350
  * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec)
@@ -373,7 +370,7 @@ module.exports = processRequest;
373
370
  * all resolvers have resolved, or after an error has interrupted the request.
374
371
  * @callback FileUploadCreateReadStream
375
372
  * @param {FileUploadCreateReadStreamOptions} [options] Options.
376
- * @returns {import("stream").Readable}
373
+ * @returns {import("node:stream").Readable}
377
374
  * [Node.js readable stream](https://nodejs.org/api/stream.html#readable-streams)
378
375
  * of the file’s contents.
379
376
  * @see [Node.js `Readable` stream constructor docs](https://nodejs.org/api/stream.html#new-streamreadableoptions).
@@ -383,26 +380,28 @@ module.exports = processRequest;
383
380
  /**
384
381
  * {@linkcode FileUploadCreateReadStream} options.
385
382
  * @typedef {object} FileUploadCreateReadStreamOptions
386
- * @prop {string} [options.encoding] Specify an encoding for the
387
- * [`data`](https://nodejs.org/api/stream.html#event-data) chunks to be
383
+ * @prop {import("fs-capacitor")
384
+ * .ReadStreamOptions["encoding"]} [options.encoding] Specify an encoding for
385
+ * the [`data`](https://nodejs.org/api/stream.html#event-data) chunks to be
388
386
  * strings (without splitting multi-byte characters across chunks) instead of
389
387
  * Node.js [`Buffer`](https://nodejs.org/api/buffer.html#buffer) instances.
390
388
  * Supported values depend on the
391
389
  * [`Buffer` implementation](https://github.com/nodejs/node/blob/v18.1.0/lib/buffer.js#L590-L680)
392
390
  * and include `utf8`, `ucs2`, `utf16le`, `latin1`, `ascii`, `base64`,
393
391
  * `base64url`, or `hex`. Defaults to `utf8`.
394
- * @prop {number} [options.highWaterMark] Maximum number of bytes to store in
395
- * the internal buffer before ceasing to read from the underlying resource.
396
- * Defaults to `16384`.
392
+ * @prop {import("fs-capacitor")
393
+ * .ReadStreamOptions["highWaterMark"]} [options.highWaterMark] Maximum number
394
+ * of bytes to store in the internal buffer before ceasing to read from the
395
+ * underlying resource. Defaults to `16384`.
397
396
  */
398
397
 
399
398
  /**
400
399
  * Processes an incoming
401
400
  * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
402
401
  * @callback ProcessRequestFunction
403
- * @param {import("http").IncomingMessage} request
402
+ * @param {import("node:http").IncomingMessage} request
404
403
  * [Node.js HTTP server request instance](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
405
- * @param {import("http").ServerResponse} response
404
+ * @param {import("node:http").ServerResponse} response
406
405
  * [Node.js HTTP server response instance](https://nodejs.org/api/http.html#http_class_http_serverresponse).
407
406
  * @param {ProcessRequestOptions} [options] Options.
408
407
  * @returns {Promise<
package/readme.md CHANGED
@@ -2,31 +2,33 @@
2
2
 
3
3
  # graphql-upload
4
4
 
5
- [![npm version](https://badgen.net/npm/v/graphql-upload)](https://npm.im/graphql-upload) [![CI status](https://github.com/jaydenseric/graphql-upload/workflows/CI/badge.svg)](https://github.com/jaydenseric/graphql-upload/actions)
5
+ Middleware and an [`Upload`](./GraphQLUpload.mjs) scalar to add support for [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec) (file uploads via queries and mutations) to various Node.js GraphQL servers.
6
6
 
7
- Middleware and an [`Upload`](./GraphQLUpload.js) scalar to add support for [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec) (file uploads via queries and mutations) to various Node.js GraphQL servers.
7
+ [Clients implementing the GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec#client) upload files as [`Upload`](./GraphQLUpload.mjs) scalar query or mutation variables. Their resolver values are promises that resolve file upload details for processing and storage. Files are typically streamed into cloud storage but may also be stored in the filesystem.
8
8
 
9
9
  ## Installation
10
10
 
11
- First, check if there are [GraphQL multipart request spec server implementations](https://github.com/jaydenseric/graphql-multipart-request-spec#server) (most for Node.js integrate [`graphql-upload`](https://npm.im/graphql-upload)) that are more suitable for your environment than a manual setup.
11
+ > **Note**
12
+ >
13
+ > First, check if there are [GraphQL multipart request spec server implementations](https://github.com/jaydenseric/graphql-multipart-request-spec#server) (most for Node.js integrate [`graphql-upload`](https://npm.im/graphql-upload)) that are more suitable for your environment than a manual setup.
12
14
 
13
- To install [`graphql-upload`](https://npm.im/graphql-upload) and the [`graphql`](https://npm.im/graphql) peer dependency with [npm](https://npmjs.com/get-npm), run:
15
+ To install [`graphql-upload`](https://npm.im/graphql-upload) and its [`graphql`](https://npm.im/graphql) peer dependency with [npm](https://npmjs.com/get-npm), run:
14
16
 
15
17
  ```sh
16
18
  npm install graphql-upload graphql
17
19
  ```
18
20
 
19
- Use the [`graphqlUploadKoa`](./graphqlUploadKoa.js) or [`graphqlUploadExpress`](./graphqlUploadExpress.js) middleware just before GraphQL middleware. Alternatively, use [`processRequest`](./processRequest.js) to create custom middleware.
21
+ Use the middleware [`graphqlUploadKoa`](./graphqlUploadKoa.mjs) or [`graphqlUploadExpress`](./graphqlUploadExpress.mjs) just before GraphQL middleware. Alternatively, use the function [`processRequest`](./processRequest.mjs) to create custom middleware.
20
22
 
21
- A schema built with separate SDL and resolvers (e.g. using [`makeExecutableSchema`](https://www.graphql-tools.com/docs/api/modules/schema_src#makeexecutableschema) from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema)) requires the [`Upload`](./GraphQLUpload.js) scalar to be setup.
23
+ A schema built with separate SDL and resolvers (e.g. using the function [`makeExecutableSchema`](https://www.graphql-tools.com/docs/api/modules/schema_src#makeexecutableschema) from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema)) requires the [`Upload`](./GraphQLUpload.mjs) scalar to be setup.
22
24
 
23
- ## Usage
25
+ Then, the [`Upload`](./GraphQLUpload.mjs) scalar can be used for query or mutation arguments. For how to use the scalar value in resolvers, see the documentation in the module [`GraphQLUpload.mjs`](./GraphQLUpload.mjs).
24
26
 
25
- [Clients implementing the GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec#client) upload files as [`Upload`](./GraphQLUpload.js) scalar query or mutation variables. Their resolver values are promises that resolve file upload details for processing and storage. Files are typically streamed into cloud storage but may also be stored in the filesystem.
27
+ ## Examples
26
28
 
27
- See the [example API and client](https://github.com/jaydenseric/apollo-upload-examples).
29
+ - [Apollo upload examples repo](https://github.com/jaydenseric/apollo-upload-examples); a full stack demo of file uploads via GraphQL mutations using [`apollo-server-koa`](https://npm.im/apollo-server-koa) and [`@apollo/client`](https://npm.im/@apollo/client).
28
30
 
29
- ### Tips
31
+ ## Tips
30
32
 
31
33
  - The process must have both read and write access to the directory identified by [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir).
32
34
  - The device requires sufficient disk space to buffer the expected number of concurrent upload requests.
@@ -40,20 +42,28 @@ See the [example API and client](https://github.com/jaydenseric/apollo-upload-ex
40
42
 
41
43
  The [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec) allows a file to be used for multiple query or mutation variables (file deduplication), and for variables to be used in multiple places. GraphQL resolvers need to be able to manage independent file streams. As resolvers are executed asynchronously, it’s possible they will try to process files in a different order than received in the multipart request.
42
44
 
43
- [`busboy`](https://npm.im/busboy) parses multipart request streams. Once the `operations` and `map` fields have been parsed, [`Upload`](./GraphQLUpload.js) scalar values in the GraphQL operations are populated with promises, and the operations are passed down the middleware chain to GraphQL resolvers.
45
+ [`busboy`](https://npm.im/busboy) parses multipart request streams. Once the `operations` and `map` fields have been parsed, [`Upload`](./GraphQLUpload.mjs) scalar values in the GraphQL operations are populated with promises, and the operations are passed down the middleware chain to GraphQL resolvers.
44
46
 
45
47
  [`fs-capacitor`](https://npm.im/fs-capacitor) is used to buffer file uploads to the filesystem and coordinate simultaneous reading and writing. As soon as a file upload’s contents begins streaming, its data begins buffering to the filesystem and its associated promise resolves. GraphQL resolvers can then create new streams from the buffer by calling the function `createReadStream`. The buffer is destroyed once all streams have ended or closed and the server has responded to the request. Any remaining buffer files will be cleaned when the process exits.
46
48
 
47
49
  ## Requirements
48
50
 
49
- - [Node.js](https://nodejs.org): `^14.17.0 || ^16.0.0 || >= 18.0.0`
51
+ Supported runtime environments:
52
+
53
+ - [Node.js](https://nodejs.org) versions `^14.17.0 || ^16.0.0 || >= 18.0.0`.
54
+
55
+ Projects must configure [TypeScript](https://typescriptlang.org) to use types from the ECMAScript modules that have a `// @ts-check` comment:
56
+
57
+ - [`compilerOptions.allowJs`](https://typescriptlang.org/tsconfig#allowJs) should be `true`.
58
+ - [`compilerOptions.maxNodeModuleJsDepth`](https://typescriptlang.org/tsconfig#maxNodeModuleJsDepth) should be reasonably large, e.g. `10`.
59
+ - [`compilerOptions.module`](https://typescriptlang.org/tsconfig#module) should be `"node16"` or `"nodenext"`.
50
60
 
51
61
  ## Exports
52
62
 
53
- These CommonJS modules are published to [npm](https://npmjs.com) and exported via the [`package.json`](./package.json) `exports` field:
63
+ The [npm](https://npmjs.com) package [`graphql-upload`](https://npm.im/graphql-upload) features [optimal JavaScript module design](https://jaydenseric.com/blog/optimal-javascript-module-design). It doesn’t have a main index module, so use deep imports from the ECMAScript modules that are exported via the [`package.json`](./package.json) field [`exports`](https://nodejs.org/api/packages.html#exports):
54
64
 
55
- - [`GraphQLUpload.js`](./GraphQLUpload.js)
56
- - [`graphqlUploadExpress.js`](./graphqlUploadExpress.js)
57
- - [`graphqlUploadKoa.js`](./graphqlUploadKoa.js)
58
- - [`processRequest.js`](./processRequest.js)
59
- - [`Upload.js`](./Upload.js)
65
+ - [`GraphQLUpload.mjs`](./GraphQLUpload.mjs)
66
+ - [`graphqlUploadExpress.mjs`](./graphqlUploadExpress.mjs)
67
+ - [`graphqlUploadKoa.mjs`](./graphqlUploadKoa.mjs)
68
+ - [`processRequest.mjs`](./processRequest.mjs)
69
+ - [`Upload.mjs`](./Upload.mjs)