graphql-upload 17.0.0 → 18.0.0

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.
package/GraphQLUpload.mjs CHANGED
@@ -1,19 +1,20 @@
1
1
  // @ts-check
2
2
 
3
- import { GraphQLError, GraphQLScalarType } from "graphql";
3
+ /** @import { FileUpload } from "./processRequest.mjs" */
4
4
 
5
- import Upload from "./Upload.mjs";
5
+ import { GraphQLError } from "graphql/error";
6
+ import { GraphQLScalarType } from "graphql/type";
6
7
 
7
- /** @typedef {import("./processRequest.mjs").FileUpload} FileUpload */
8
+ import Upload from "./Upload.mjs";
8
9
 
9
10
  /**
10
11
  * A GraphQL scalar `Upload` that can be used in a
11
- * [`GraphQLSchema`](https://graphql.org/graphql-js/type/#graphqlschema). It’s
12
- * value in resolvers is a promise that resolves
12
+ * [`GraphQLSchema`](https://www.graphql-js.org/api-v17/type/#graphqlschema).
13
+ * Its value in resolvers is a promise that resolves
13
14
  * {@link FileUpload file upload details} for processing and storage.
14
15
  * @example
15
16
  * A schema built using the function
16
- * [`makeExecutableSchema`](https://www.graphql-tools.com/docs/api/modules/schema_src#makeexecutableschema)
17
+ * [`makeExecutableSchema`](https://the-guild.dev/graphql/tools/docs/generate-schema#makeexecutableschema)
17
18
  * from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema):
18
19
  *
19
20
  * ```js
@@ -33,7 +34,7 @@ import Upload from "./Upload.mjs";
33
34
  * A manually constructed schema with an image upload mutation:
34
35
  *
35
36
  * ```js
36
- * import { GraphQLBoolean, GraphQLObjectType, GraphQLSchema } from "graphql";
37
+ * import { GraphQLBoolean, GraphQLObjectType, GraphQLSchema } from "graphql/type";
37
38
  * import GraphQLUpload from "graphql-upload/GraphQLUpload.mjs";
38
39
  *
39
40
  * const schema = new GraphQLSchema({
@@ -72,14 +73,14 @@ import Upload from "./Upload.mjs";
72
73
  const GraphQLUpload = new GraphQLScalarType({
73
74
  name: "Upload",
74
75
  description: "The `Upload` scalar type represents a file upload.",
75
- parseValue(value) {
76
+ coerceInputValue(value) {
76
77
  if (value instanceof Upload) return value.promise;
77
78
  throw new GraphQLError("Upload value invalid.");
78
79
  },
79
- parseLiteral(node) {
80
+ coerceInputLiteral(node) {
80
81
  throw new GraphQLError("Upload literal unsupported.", { nodes: node });
81
82
  },
82
- serialize() {
83
+ coerceOutputValue() {
83
84
  throw new GraphQLError("Upload serialization unsupported.");
84
85
  },
85
86
  });
package/Upload.mjs CHANGED
@@ -10,7 +10,7 @@
10
10
  * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
11
11
  * The {@linkcode processRequest} function places references to an instance of
12
12
  * this class wherever the file is expected in the GraphQL operation. The scalar
13
- * {@linkcode GraphQLUpload} derives it’s value from {@linkcode Upload.promise}.
13
+ * {@linkcode GraphQLUpload} derives its value from {@linkcode Upload.promise}.
14
14
  */
15
15
  export default class Upload {
16
16
  constructor() {
@@ -9,13 +9,20 @@
9
9
  */
10
10
 
11
11
  import defaultProcessRequest from "./processRequest.mjs";
12
+ import requestFinished from "./requestFinished.mjs";
12
13
 
13
14
  /**
14
15
  * Creates [Express](https://expressjs.com) middleware that processes incoming
15
16
  * [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
16
17
  * using {@linkcode processRequest}, ignoring non multipart requests. It sets
17
- * the request `body` to be similar to a conventional GraphQL POST request for
18
- * following GraphQL middleware to consume.
18
+ * the Express request property `body` to be similar to a conventional GraphQL
19
+ * POST request for following GraphQL middleware to consume. Also, it
20
+ * temporarily monkey patches the Express response method
21
+ * {@linkcode Response.send send} to first wait for the request to finish
22
+ * (either because it disconnects early, or it finishes uploading and the
23
+ * response can be sent), because sending a response before the request has
24
+ * finished uploading typically causes the HTTP client to error without
25
+ * processing the response.
19
26
  * @param {ProcessRequestOptions & {
20
27
  * processRequest?: ProcessRequestFunction,
21
28
  * }} options Options.
@@ -44,27 +51,21 @@ export default function graphqlUploadExpress({
44
51
  ...processRequestOptions
45
52
  } = {}) {
46
53
  /**
47
- * [Express](https://expressjs.com) middleware that processes incoming
48
- * [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
49
- * using {@linkcode processRequest}, ignoring non multipart requests. It sets
50
- * the request `body` to be similar to a conventional GraphQL POST request for
51
- * following GraphQL middleware to consume.
52
54
  * @param {Request} request Express request.
53
55
  * @param {Response} response Express response.
54
56
  * @param {NextFunction} next Invokes the next middleware.
55
57
  */
56
58
  function graphqlUploadExpressMiddleware(request, response, next) {
57
59
  if (request.is("multipart/form-data")) {
58
- const requestEnd = new Promise((resolve) => request.on("end", resolve));
60
+ // Todo: Find a less hacky way that avoids monkey patching.
59
61
  const { send } = response;
60
-
61
- // @ts-ignore Todo: Find a less hacky way to prevent sending a response
62
- // before the request has ended.
63
62
  response.send = (...args) => {
64
- requestEnd.then(() => {
63
+ requestFinished(request).then(() => {
65
64
  response.send = send;
66
65
  response.send(...args);
67
66
  });
67
+
68
+ return response;
68
69
  };
69
70
 
70
71
  processRequest(request, response, processRequestOptions)
@@ -9,13 +9,19 @@
9
9
  */
10
10
 
11
11
  import defaultProcessRequest from "./processRequest.mjs";
12
+ import requestFinished from "./requestFinished.mjs";
12
13
 
13
14
  /**
14
15
  * Creates [Koa](https://koajs.com) middleware that processes incoming
15
16
  * [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
16
17
  * using {@linkcode processRequest}, ignoring non multipart requests. It sets
17
- * the request `body` to be similar to a conventional GraphQL POST request for
18
- * following GraphQL middleware to consume.
18
+ * the Koa context `request` property `body` to be similar to a conventional
19
+ * GraphQL POST request for following GraphQL middleware to consume. Also, after
20
+ * awaiting the next middleware it waits for the request to finish (either
21
+ * because it disconnects early, or it finishes uploading and the response can
22
+ * be sent), because sending a response before the request has finished
23
+ * uploading typically causes the HTTP client to error without processing the
24
+ * response.
19
25
  * @param {ProcessRequestOptions & {
20
26
  * processRequest?: ProcessRequestFunction,
21
27
  * }} options Options.
@@ -45,18 +51,11 @@ export default function graphqlUploadKoa({
45
51
  ...processRequestOptions
46
52
  } = {}) {
47
53
  /**
48
- * [Koa](https://koajs.com) middleware that processes incoming
49
- * [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
50
- * using {@linkcode processRequest}, ignoring non multipart requests. It sets
51
- * the request `body` to be similar to a conventional GraphQL POST request for
52
- * following GraphQL middleware to consume.
53
54
  * @param {ParameterizedContext} ctx Koa context.
54
55
  * @param {Next} next Invokes the next middleware.
55
56
  */
56
57
  async function graphqlUploadKoaMiddleware(ctx, next) {
57
58
  if (ctx.request.is("multipart/form-data")) {
58
- const requestEnd = new Promise((resolve) => ctx.req.on("end", resolve));
59
-
60
59
  try {
61
60
  // @ts-ignore This is conventional.
62
61
  ctx.request.body = await processRequest(
@@ -66,7 +65,7 @@ export default function graphqlUploadKoa({
66
65
  );
67
66
  await next();
68
67
  } finally {
69
- await requestEnd;
68
+ await requestFinished(ctx.req);
70
69
  }
71
70
  } else await next();
72
71
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphql-upload",
3
- "version": "17.0.0",
3
+ "version": "18.0.0",
4
4
  "description": "Middleware and a scalar Upload 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": {
@@ -36,6 +36,7 @@
36
36
  "graphqlUploadKoa.mjs",
37
37
  "ignoreStream.mjs",
38
38
  "processRequest.mjs",
39
+ "requestFinished.mjs",
39
40
  "Upload.mjs"
40
41
  ],
41
42
  "sideEffects": false,
@@ -48,12 +49,12 @@
48
49
  "./Upload.mjs": "./Upload.mjs"
49
50
  },
50
51
  "engines": {
51
- "node": "^18.18.0 || ^20.9.0 || >=22.0.0"
52
+ "node": "^22.13.0 || ^24.0.0 || >=26.0.0"
52
53
  },
53
54
  "peerDependencies": {
54
- "@types/express": "4.0.29 - 5",
55
- "@types/koa": "^2.11.4",
56
- "graphql": "^16.3.0"
55
+ "@types/express": "^5.0.0",
56
+ "@types/koa": "^3.0.0",
57
+ "graphql": "^17.0.0"
57
58
  },
58
59
  "peerDependenciesMeta": {
59
60
  "@types/express": {
@@ -73,28 +74,26 @@
73
74
  "object-path": "^0.11.8"
74
75
  },
75
76
  "devDependencies": {
76
- "@eslint/js": "^9.12.0",
77
- "@types/express": "^5.0.0",
78
- "@types/koa": "^2.15.0",
79
- "async-listen": "^3.0.1",
80
- "coverage-node": "^8.0.0",
81
- "eslint": "^9.12.0",
82
- "eslint-plugin-jsdoc": "^50.3.1",
83
- "eslint-plugin-simple-import-sort": "^12.1.1",
84
- "express": "^5.0.0",
85
- "form-data-encoder": "^4.0.2",
86
- "globals": "^15.10.0",
87
- "graphql": "^16.9.0",
88
- "koa": "^2.15.3",
89
- "prettier": "^3.3.3",
90
- "typescript": "^5.6.2"
77
+ "@eslint/js": "^10.0.1",
78
+ "@types/express": "^5.0.6",
79
+ "@types/koa": "^3.0.3",
80
+ "async-listen": "^3.1.0",
81
+ "eslint": "^10.6.0",
82
+ "eslint-plugin-jsdoc": "^63.0.10",
83
+ "eslint-plugin-simple-import-sort": "^14.0.0",
84
+ "express": "^5.2.1",
85
+ "globals": "^17.7.0",
86
+ "graphql": "^17.0.2",
87
+ "koa": "^3.2.1",
88
+ "prettier": "^3.9.1",
89
+ "typescript": "^7.0.2"
91
90
  },
92
91
  "scripts": {
93
92
  "prettier": "prettier -c .",
94
93
  "eslint": "eslint",
95
94
  "types": "tsc -p jsconfig.json",
96
- "tests": "coverage-node --test-reporter=spec --test *.test.mjs",
97
- "test": "node --run prettier && node --run eslint && node --run types && node --run tests",
98
- "prepublishOnly": "node --run test"
95
+ "test": "node --test --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-exclude='**/*.test.*' --test-reporter=spec",
96
+ "check": "node --run prettier && node --run eslint && node --run types && node --run test",
97
+ "prepublishOnly": "node --run check"
99
98
  }
100
99
  }
@@ -23,7 +23,7 @@ import Upload from "./Upload.mjs";
23
23
  * It parses the `operations` and `map` fields to create an {@linkcode Upload}
24
24
  * instance for each expected file upload, placing references wherever the file
25
25
  * is expected in the GraphQL operation for the {@linkcode GraphQLUpload} scalar
26
- * to derive it’s value. Errors are created with
26
+ * to derive its value. Errors are created with
27
27
  * [`http-errors`](https://npm.im/http-errors) to assist in sending responses
28
28
  * with appropriate HTTP status codes. Used to create custom middleware.
29
29
  * @type {ProcessRequestFunction}
@@ -380,7 +380,7 @@ export default function processRequest(
380
380
  * [Node.js readable stream](https://nodejs.org/api/stream.html#readable-streams)
381
381
  * of the file’s contents.
382
382
  * @see [Node.js `Readable` stream constructor docs](https://nodejs.org/api/stream.html#new-streamreadableoptions).
383
- * @see [Node.js stream backpressure guide](https://nodejs.org/en/docs/guides/backpressuring-in-streams).
383
+ * @see [Node.js stream backpressure guide](https://nodejs.org/learn/modules/backpressuring-in-streams).
384
384
  */
385
385
 
386
386
  /**
@@ -391,7 +391,7 @@ export default function processRequest(
391
391
  * strings (without splitting multi-byte characters across chunks) instead of
392
392
  * Node.js [`Buffer`](https://nodejs.org/api/buffer.html#buffer) instances.
393
393
  * Supported values depend on the
394
- * [`Buffer` implementation](https://github.com/nodejs/node/blob/v18.1.0/lib/buffer.js#L590-L680)
394
+ * [`Buffer` implementation](https://github.com/nodejs/node/blob/v26.5.0/lib/buffer.js#L695-L788)
395
395
  * and include `utf8`, `ucs2`, `utf16le`, `latin1`, `ascii`, `base64`,
396
396
  * `base64url`, or `hex`. Defaults to `utf8`.
397
397
  * @property {ReadStreamOptions["highWaterMark"]} [highWaterMark] Maximum number
package/readme.md CHANGED
@@ -12,7 +12,7 @@ Middleware and a scalar [`Upload`](./GraphQLUpload.mjs) to add support for [Grap
12
12
  >
13
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.
14
14
 
15
- To install [`graphql-upload`](https://npm.im/graphql-upload) and its peer dependency [`graphql`](https://npm.im/graphql) with [npm](https://npmjs.com/get-npm), run:
15
+ To install [`graphql-upload`](https://npm.im/graphql-upload) and its peer dependency [`graphql`](https://npm.im/graphql) with [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm), run:
16
16
 
17
17
  ```sh
18
18
  npm install graphql-upload graphql
@@ -20,7 +20,7 @@ npm install graphql-upload graphql
20
20
 
21
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.
22
22
 
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 scalar [`Upload`](./GraphQLUpload.mjs) to be setup.
23
+ A schema built with separate SDL and resolvers (e.g. using the function [`makeExecutableSchema`](https://the-guild.dev/graphql/tools/docs/generate-schema#makeexecutableschema) from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema)) requires the scalar [`Upload`](./GraphQLUpload.mjs) to be setup.
24
24
 
25
25
  Then, the scalar [`Upload`](./GraphQLUpload.mjs) 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).
26
26
 
@@ -50,7 +50,7 @@ The [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-mult
50
50
 
51
51
  Supported runtime environments:
52
52
 
53
- - [Node.js](https://nodejs.org) versions `^18.18.0 || ^20.9.0 || >=22.0.0`.
53
+ - [Node.js](https://nodejs.org) versions `^22.13.0 || ^24.0.0 || >=26.0.0`.
54
54
 
55
55
  Projects must configure [TypeScript](https://typescriptlang.org) to use types from the ECMAScript modules that have a `// @ts-check` comment:
56
56
 
@@ -0,0 +1,17 @@
1
+ // @ts-check
2
+
3
+ /** @import { IncomingMessage } from "node:http" */
4
+
5
+ /**
6
+ * Waits for a request to finish (either because it disconnects early, or it
7
+ * finishes uploading).
8
+ * @see [Node.js stream utility function `finished`](https://nodejs.org/api/stream.html#streamfinishedstream-options).
9
+ * @param {IncomingMessage} request Request.
10
+ * @returns {Promise<void>} Resolves once the request has finished.
11
+ */
12
+ export default async function requestFinished(request) {
13
+ if (!request.closed)
14
+ await new Promise((resolve) => {
15
+ request.once("close", resolve);
16
+ });
17
+ }