graphql-upload 16.0.2 → 17.1.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 +4 -4
- package/Upload.mjs +8 -7
- package/graphqlUploadExpress.mjs +39 -32
- package/graphqlUploadKoa.mjs +33 -26
- package/ignoreStream.mjs +3 -1
- package/package.json +34 -25
- package/processRequest.mjs +65 -60
- package/readme.md +7 -7
- package/requestFinished.mjs +17 -0
package/GraphQLUpload.mjs
CHANGED
|
@@ -7,13 +7,13 @@ import Upload from "./Upload.mjs";
|
|
|
7
7
|
/** @typedef {import("./processRequest.mjs").FileUpload} FileUpload */
|
|
8
8
|
|
|
9
9
|
/**
|
|
10
|
-
* A GraphQL `Upload`
|
|
11
|
-
* [`GraphQLSchema`](https://graphql.org/
|
|
12
|
-
* value in resolvers is a promise that resolves
|
|
10
|
+
* A GraphQL scalar `Upload` that can be used in a
|
|
11
|
+
* [`GraphQLSchema`](https://www.graphql-js.org/api-v17/type/#graphqlschema).
|
|
12
|
+
* Its value in resolvers is a promise that resolves
|
|
13
13
|
* {@link FileUpload file upload details} for processing and storage.
|
|
14
14
|
* @example
|
|
15
15
|
* A schema built using the function
|
|
16
|
-
* [`makeExecutableSchema`](https://
|
|
16
|
+
* [`makeExecutableSchema`](https://the-guild.dev/graphql/tools/docs/generate-schema#makeexecutableschema)
|
|
17
17
|
* from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema):
|
|
18
18
|
*
|
|
19
19
|
* ```js
|
package/Upload.mjs
CHANGED
|
@@ -1,35 +1,36 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
|
|
3
|
-
/**
|
|
4
|
-
|
|
3
|
+
/**
|
|
4
|
+
* @import GraphQLUpload from "./GraphQLUpload.mjs"
|
|
5
|
+
* @import processRequest, { FileUpload } from "./processRequest.mjs"
|
|
6
|
+
*/
|
|
5
7
|
|
|
6
8
|
/**
|
|
7
9
|
* A file expected to be uploaded as it was declared in the `map` field of a
|
|
8
10
|
* [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
|
|
9
11
|
* The {@linkcode processRequest} function places references to an instance of
|
|
10
12
|
* this class wherever the file is expected in the GraphQL operation. The scalar
|
|
11
|
-
* {@linkcode GraphQLUpload} derives
|
|
13
|
+
* {@linkcode GraphQLUpload} derives its value from {@linkcode Upload.promise}.
|
|
12
14
|
*/
|
|
13
15
|
export default class Upload {
|
|
14
16
|
constructor() {
|
|
15
17
|
/**
|
|
16
18
|
* Promise that resolves file upload details. This should only be utilized
|
|
17
19
|
* by {@linkcode GraphQLUpload}.
|
|
18
|
-
* @type {Promise<
|
|
20
|
+
* @type {Promise<FileUpload>}
|
|
19
21
|
*/
|
|
20
22
|
this.promise = new Promise((resolve, reject) => {
|
|
21
23
|
/**
|
|
22
24
|
* Resolves the upload promise with the file upload details. This should
|
|
23
25
|
* only be utilized by {@linkcode processRequest}.
|
|
24
|
-
* @param {
|
|
25
|
-
* details.
|
|
26
|
+
* @param {FileUpload} file File upload details.
|
|
26
27
|
*/
|
|
27
28
|
this.resolve = (file) => {
|
|
28
29
|
/**
|
|
29
30
|
* The file upload details, available when the
|
|
30
31
|
* {@linkcode Upload.promise} resolves. This should only be utilized by
|
|
31
32
|
* {@linkcode processRequest}.
|
|
32
|
-
* @type {
|
|
33
|
+
* @type {FileUpload | undefined}
|
|
33
34
|
*/
|
|
34
35
|
this.file = file;
|
|
35
36
|
|
package/graphqlUploadExpress.mjs
CHANGED
|
@@ -1,15 +1,30 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* @import { NextFunction, Request, Response } from "express"
|
|
5
|
+
* @import {
|
|
6
|
+
* ProcessRequestFunction,
|
|
7
|
+
* ProcessRequestOptions,
|
|
8
|
+
* } from "./processRequest.mjs"
|
|
9
|
+
*/
|
|
10
|
+
|
|
3
11
|
import defaultProcessRequest from "./processRequest.mjs";
|
|
12
|
+
import requestFinished from "./requestFinished.mjs";
|
|
4
13
|
|
|
5
14
|
/**
|
|
6
15
|
* Creates [Express](https://expressjs.com) middleware that processes incoming
|
|
7
16
|
* [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
|
|
8
17
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
9
|
-
* the request `body` to be similar to a conventional GraphQL
|
|
10
|
-
* following GraphQL middleware to consume.
|
|
11
|
-
*
|
|
12
|
-
*
|
|
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.
|
|
26
|
+
* @param {ProcessRequestOptions & {
|
|
27
|
+
* processRequest?: ProcessRequestFunction,
|
|
13
28
|
* }} options Options.
|
|
14
29
|
* @returns Express middleware.
|
|
15
30
|
* @example
|
|
@@ -36,41 +51,33 @@ export default function graphqlUploadExpress({
|
|
|
36
51
|
...processRequestOptions
|
|
37
52
|
} = {}) {
|
|
38
53
|
/**
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
43
|
-
* following GraphQL middleware to consume.
|
|
44
|
-
* @param {import("express").Request} request
|
|
45
|
-
* @param {import("express").Response} response
|
|
46
|
-
* @param {import("express").NextFunction} next
|
|
54
|
+
* @param {Request} request Express request.
|
|
55
|
+
* @param {Response} response Express response.
|
|
56
|
+
* @param {NextFunction} next Invokes the next middleware.
|
|
47
57
|
*/
|
|
48
58
|
function graphqlUploadExpressMiddleware(request, response, next) {
|
|
49
|
-
if (
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
// @ts-ignore Todo: Find a less hacky way to prevent sending a response
|
|
55
|
-
// before the request has ended.
|
|
56
|
-
response.send =
|
|
57
|
-
/** @param {Array<unknown>} args */
|
|
58
|
-
(...args) => {
|
|
59
|
-
requestEnd.then(() => {
|
|
59
|
+
if (request.is("multipart/form-data")) {
|
|
60
|
+
// Todo: Find a less hacky way that avoids monkey patching.
|
|
61
|
+
const { send } = response;
|
|
62
|
+
response.send = (...args) => {
|
|
63
|
+
requestFinished(request).then(() => {
|
|
60
64
|
response.send = send;
|
|
61
65
|
response.send(...args);
|
|
62
66
|
});
|
|
67
|
+
|
|
68
|
+
return response;
|
|
63
69
|
};
|
|
64
70
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
71
|
+
processRequest(request, response, processRequestOptions)
|
|
72
|
+
.then((body) => {
|
|
73
|
+
request.body = body;
|
|
74
|
+
next();
|
|
75
|
+
})
|
|
76
|
+
.catch((error) => {
|
|
77
|
+
if (error.status && error.expose) response.status(error.status);
|
|
78
|
+
next(error);
|
|
79
|
+
});
|
|
80
|
+
} else next();
|
|
74
81
|
}
|
|
75
82
|
|
|
76
83
|
return graphqlUploadExpressMiddleware;
|
package/graphqlUploadKoa.mjs
CHANGED
|
@@ -1,15 +1,29 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* @import { Next, ParameterizedContext } from "koa"
|
|
5
|
+
* @import {
|
|
6
|
+
* ProcessRequestFunction,
|
|
7
|
+
* ProcessRequestOptions,
|
|
8
|
+
* } from "./processRequest.mjs"
|
|
9
|
+
*/
|
|
10
|
+
|
|
3
11
|
import defaultProcessRequest from "./processRequest.mjs";
|
|
12
|
+
import requestFinished from "./requestFinished.mjs";
|
|
4
13
|
|
|
5
14
|
/**
|
|
6
15
|
* Creates [Koa](https://koajs.com) middleware that processes incoming
|
|
7
16
|
* [GraphQL multipart requests](https://github.com/jaydenseric/graphql-multipart-request-spec)
|
|
8
17
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
9
|
-
* the request `body` to be similar to a conventional
|
|
10
|
-
* following GraphQL middleware to consume.
|
|
11
|
-
*
|
|
12
|
-
*
|
|
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.
|
|
25
|
+
* @param {ProcessRequestOptions & {
|
|
26
|
+
* processRequest?: ProcessRequestFunction,
|
|
13
27
|
* }} options Options.
|
|
14
28
|
* @returns Koa middleware.
|
|
15
29
|
* @example
|
|
@@ -37,30 +51,23 @@ export default function graphqlUploadKoa({
|
|
|
37
51
|
...processRequestOptions
|
|
38
52
|
} = {}) {
|
|
39
53
|
/**
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
43
|
-
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
44
|
-
* following GraphQL middleware to consume.
|
|
45
|
-
* @param {import("koa").ParameterizedContext} ctx
|
|
46
|
-
* @param {() => Promise<unknown>} next
|
|
54
|
+
* @param {ParameterizedContext} ctx Koa context.
|
|
55
|
+
* @param {Next} next Invokes the next middleware.
|
|
47
56
|
*/
|
|
48
57
|
async function graphqlUploadKoaMiddleware(ctx, next) {
|
|
49
|
-
if (
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
}
|
|
62
|
-
await requestEnd;
|
|
63
|
-
}
|
|
58
|
+
if (ctx.request.is("multipart/form-data")) {
|
|
59
|
+
try {
|
|
60
|
+
// @ts-ignore This is conventional.
|
|
61
|
+
ctx.request.body = await processRequest(
|
|
62
|
+
ctx.req,
|
|
63
|
+
ctx.res,
|
|
64
|
+
processRequestOptions,
|
|
65
|
+
);
|
|
66
|
+
await next();
|
|
67
|
+
} finally {
|
|
68
|
+
await requestFinished(ctx.req);
|
|
69
|
+
}
|
|
70
|
+
} else await next();
|
|
64
71
|
}
|
|
65
72
|
|
|
66
73
|
return graphqlUploadKoaMiddleware;
|
package/ignoreStream.mjs
CHANGED
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
|
|
3
|
+
/** @import { Readable } from "node:stream" */
|
|
4
|
+
|
|
3
5
|
/**
|
|
4
6
|
* Safely ignores a Node.js readable stream.
|
|
5
|
-
* @param {
|
|
7
|
+
* @param {Readable} stream Node.js readable stream.
|
|
6
8
|
*/
|
|
7
9
|
export default function ignoreStream(stream) {
|
|
8
10
|
// Prevent an unhandled error from crashing the process.
|
package/package.json
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "graphql-upload",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Middleware and
|
|
3
|
+
"version": "17.1.0",
|
|
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": {
|
|
7
7
|
"name": "Jayden Seric",
|
|
8
8
|
"email": "me@jaydenseric.com",
|
|
9
9
|
"url": "https://jaydenseric.com"
|
|
10
10
|
},
|
|
11
|
-
"repository":
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/jaydenseric/graphql-upload.git"
|
|
14
|
+
},
|
|
12
15
|
"homepage": "https://github.com/jaydenseric/graphql-upload#readme",
|
|
13
16
|
"bugs": "https://github.com/jaydenseric/graphql-upload/issues",
|
|
14
17
|
"funding": "https://github.com/sponsors/jaydenseric",
|
|
@@ -33,6 +36,7 @@
|
|
|
33
36
|
"graphqlUploadKoa.mjs",
|
|
34
37
|
"ignoreStream.mjs",
|
|
35
38
|
"processRequest.mjs",
|
|
39
|
+
"requestFinished.mjs",
|
|
36
40
|
"Upload.mjs"
|
|
37
41
|
],
|
|
38
42
|
"sideEffects": false,
|
|
@@ -45,12 +49,18 @@
|
|
|
45
49
|
"./Upload.mjs": "./Upload.mjs"
|
|
46
50
|
},
|
|
47
51
|
"engines": {
|
|
48
|
-
"node": "^
|
|
52
|
+
"node": "^18.18.0 || ^20.9.0 || >=22.0.0"
|
|
53
|
+
},
|
|
54
|
+
"devEngines": {
|
|
55
|
+
"runtime": {
|
|
56
|
+
"name": "node",
|
|
57
|
+
"version": "^22.13.0 || ^24.0.0 || >=26.0.0"
|
|
58
|
+
}
|
|
49
59
|
},
|
|
50
60
|
"peerDependencies": {
|
|
51
|
-
"@types/express": "^4.0.29",
|
|
52
|
-
"@types/koa": "^2.11.4",
|
|
53
|
-
"graphql": "^16.3.0"
|
|
61
|
+
"@types/express": "^4.0.29 || ^5.0.0",
|
|
62
|
+
"@types/koa": "^2.11.4 || ^3.0.0",
|
|
63
|
+
"graphql": "^16.3.0 || ^17.0.0"
|
|
54
64
|
},
|
|
55
65
|
"peerDependenciesMeta": {
|
|
56
66
|
"@types/express": {
|
|
@@ -70,27 +80,26 @@
|
|
|
70
80
|
"object-path": "^0.11.8"
|
|
71
81
|
},
|
|
72
82
|
"devDependencies": {
|
|
73
|
-
"@
|
|
74
|
-
"@types/
|
|
75
|
-
"
|
|
76
|
-
"
|
|
77
|
-
"eslint
|
|
78
|
-
"
|
|
79
|
-
"
|
|
80
|
-
"
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
"
|
|
84
|
-
"prettier": "^
|
|
85
|
-
"
|
|
86
|
-
"typescript": "^4.8.2"
|
|
83
|
+
"@eslint/js": "^10.0.1",
|
|
84
|
+
"@types/express": "^5.0.6",
|
|
85
|
+
"@types/koa": "^3.0.3",
|
|
86
|
+
"async-listen": "^3.1.0",
|
|
87
|
+
"eslint": "^10.6.0",
|
|
88
|
+
"eslint-plugin-jsdoc": "^63.0.10",
|
|
89
|
+
"eslint-plugin-simple-import-sort": "^14.0.0",
|
|
90
|
+
"express": "^5.2.1",
|
|
91
|
+
"globals": "^17.7.0",
|
|
92
|
+
"graphql": "^17.0.2",
|
|
93
|
+
"koa": "^3.2.1",
|
|
94
|
+
"prettier": "^3.9.1",
|
|
95
|
+
"typescript": "^7.0.2"
|
|
87
96
|
},
|
|
88
97
|
"scripts": {
|
|
89
|
-
"eslint": "eslint .",
|
|
90
98
|
"prettier": "prettier -c .",
|
|
99
|
+
"eslint": "eslint",
|
|
91
100
|
"types": "tsc -p jsconfig.json",
|
|
92
|
-
"tests": "coverage-
|
|
93
|
-
"test": "
|
|
94
|
-
"prepublishOnly": "
|
|
101
|
+
"tests": "node --test --experimental-test-coverage --test-coverage-lines=100 --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-exclude='**/*.test.*' --test-reporter=spec",
|
|
102
|
+
"test": "node --run prettier && node --run eslint && node --run types && node --run tests",
|
|
103
|
+
"prepublishOnly": "node --run test"
|
|
95
104
|
}
|
|
96
105
|
}
|
package/processRequest.mjs
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
|
|
3
|
+
/**
|
|
4
|
+
* @import { IncomingMessage, ServerResponse } from "node:http"
|
|
5
|
+
* @import { Readable } from "node:stream"
|
|
6
|
+
* @import { ReadStreamOptions } from "fs-capacitor"
|
|
7
|
+
* @import { ObjectPathBound } from "object-path"
|
|
8
|
+
* @import GraphQLUpload from "./GraphQLUpload.mjs"
|
|
9
|
+
*/
|
|
10
|
+
|
|
3
11
|
import busboy from "busboy";
|
|
4
12
|
import { WriteStream } from "fs-capacitor";
|
|
5
13
|
import createError from "http-errors";
|
|
@@ -9,15 +17,13 @@ import GRAPHQL_MULTIPART_REQUEST_SPEC_URL from "./GRAPHQL_MULTIPART_REQUEST_SPEC
|
|
|
9
17
|
import ignoreStream from "./ignoreStream.mjs";
|
|
10
18
|
import Upload from "./Upload.mjs";
|
|
11
19
|
|
|
12
|
-
/** @typedef {import("./GraphQLUpload.mjs").default} GraphQLUpload */
|
|
13
|
-
|
|
14
20
|
/**
|
|
15
21
|
* Processes an incoming
|
|
16
22
|
* [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
|
|
17
23
|
* It parses the `operations` and `map` fields to create an {@linkcode Upload}
|
|
18
24
|
* instance for each expected file upload, placing references wherever the file
|
|
19
25
|
* is expected in the GraphQL operation for the {@linkcode GraphQLUpload} scalar
|
|
20
|
-
* to derive
|
|
26
|
+
* to derive its value. Errors are created with
|
|
21
27
|
* [`http-errors`](https://npm.im/http-errors) to assist in sending responses
|
|
22
28
|
* with appropriate HTTP status codes. Used to create custom middleware.
|
|
23
29
|
* @type {ProcessRequestFunction}
|
|
@@ -29,7 +35,7 @@ export default function processRequest(
|
|
|
29
35
|
maxFieldSize = 1000000, // 1 MB
|
|
30
36
|
maxFileSize = Infinity,
|
|
31
37
|
maxFiles = Infinity,
|
|
32
|
-
} = {}
|
|
38
|
+
} = {},
|
|
33
39
|
) {
|
|
34
40
|
return new Promise((resolve, reject) => {
|
|
35
41
|
/** @type {boolean} */
|
|
@@ -46,7 +52,7 @@ export default function processRequest(
|
|
|
46
52
|
let operations;
|
|
47
53
|
|
|
48
54
|
/**
|
|
49
|
-
* @type {
|
|
55
|
+
* @type {ObjectPathBound<
|
|
50
56
|
* { [key: string]: unknown } | Array<{ [key: string]: unknown }>
|
|
51
57
|
* >}
|
|
52
58
|
*/
|
|
@@ -101,20 +107,20 @@ export default function processRequest(
|
|
|
101
107
|
return exit(
|
|
102
108
|
createError(
|
|
103
109
|
413,
|
|
104
|
-
`The ‘${fieldName}’ multipart field value exceeds the ${maxFieldSize} byte size limit
|
|
105
|
-
)
|
|
110
|
+
`The ‘${fieldName}’ multipart field value exceeds the ${maxFieldSize} byte size limit.`,
|
|
111
|
+
),
|
|
106
112
|
);
|
|
107
113
|
|
|
108
114
|
switch (fieldName) {
|
|
109
115
|
case "operations":
|
|
110
116
|
try {
|
|
111
117
|
operations = JSON.parse(value);
|
|
112
|
-
} catch
|
|
118
|
+
} catch {
|
|
113
119
|
return exit(
|
|
114
120
|
createError(
|
|
115
121
|
400,
|
|
116
|
-
`Invalid JSON in the ‘operations’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
117
|
-
)
|
|
122
|
+
`Invalid JSON in the ‘operations’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
123
|
+
),
|
|
118
124
|
);
|
|
119
125
|
}
|
|
120
126
|
|
|
@@ -124,8 +130,8 @@ export default function processRequest(
|
|
|
124
130
|
return exit(
|
|
125
131
|
createError(
|
|
126
132
|
400,
|
|
127
|
-
`Invalid type for the ‘operations’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
128
|
-
)
|
|
133
|
+
`Invalid type for the ‘operations’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
134
|
+
),
|
|
129
135
|
);
|
|
130
136
|
|
|
131
137
|
operationsPath = objectPath(operations);
|
|
@@ -136,19 +142,19 @@ export default function processRequest(
|
|
|
136
142
|
return exit(
|
|
137
143
|
createError(
|
|
138
144
|
400,
|
|
139
|
-
`Misordered multipart fields; ‘map’ should follow ‘operations’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
140
|
-
)
|
|
145
|
+
`Misordered multipart fields; ‘map’ should follow ‘operations’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
146
|
+
),
|
|
141
147
|
);
|
|
142
148
|
|
|
143
149
|
let parsedMap;
|
|
144
150
|
try {
|
|
145
151
|
parsedMap = JSON.parse(value);
|
|
146
|
-
} catch
|
|
152
|
+
} catch {
|
|
147
153
|
return exit(
|
|
148
154
|
createError(
|
|
149
155
|
400,
|
|
150
|
-
`Invalid JSON in the ‘map’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
151
|
-
)
|
|
156
|
+
`Invalid JSON in the ‘map’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
157
|
+
),
|
|
152
158
|
);
|
|
153
159
|
}
|
|
154
160
|
|
|
@@ -161,8 +167,8 @@ export default function processRequest(
|
|
|
161
167
|
return exit(
|
|
162
168
|
createError(
|
|
163
169
|
400,
|
|
164
|
-
`Invalid type for the ‘map’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
165
|
-
)
|
|
170
|
+
`Invalid type for the ‘map’ multipart field (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
171
|
+
),
|
|
166
172
|
);
|
|
167
173
|
|
|
168
174
|
const mapEntries = Object.entries(parsedMap);
|
|
@@ -171,7 +177,7 @@ export default function processRequest(
|
|
|
171
177
|
// to parse might not match the map provided by the client.
|
|
172
178
|
if (mapEntries.length > maxFiles)
|
|
173
179
|
return exit(
|
|
174
|
-
createError(413, `${maxFiles} max file uploads exceeded.`)
|
|
180
|
+
createError(413, `${maxFiles} max file uploads exceeded.`),
|
|
175
181
|
);
|
|
176
182
|
|
|
177
183
|
map = new Map();
|
|
@@ -180,8 +186,8 @@ export default function processRequest(
|
|
|
180
186
|
return exit(
|
|
181
187
|
createError(
|
|
182
188
|
400,
|
|
183
|
-
`Invalid type for the ‘map’ multipart field entry key ‘${fieldName}’ array (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
184
|
-
)
|
|
189
|
+
`Invalid type for the ‘map’ multipart field entry key ‘${fieldName}’ array (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
190
|
+
),
|
|
185
191
|
);
|
|
186
192
|
|
|
187
193
|
map.set(fieldName, new Upload());
|
|
@@ -191,18 +197,18 @@ export default function processRequest(
|
|
|
191
197
|
return exit(
|
|
192
198
|
createError(
|
|
193
199
|
400,
|
|
194
|
-
`Invalid type for the ‘map’ multipart field entry key ‘${fieldName}’ array index ‘${index}’ value (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
195
|
-
)
|
|
200
|
+
`Invalid type for the ‘map’ multipart field entry key ‘${fieldName}’ array index ‘${index}’ value (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
201
|
+
),
|
|
196
202
|
);
|
|
197
203
|
|
|
198
204
|
try {
|
|
199
205
|
operationsPath.set(path, map.get(fieldName));
|
|
200
|
-
} catch
|
|
206
|
+
} catch {
|
|
201
207
|
return exit(
|
|
202
208
|
createError(
|
|
203
209
|
400,
|
|
204
|
-
`Invalid object path for the ‘map’ multipart field entry key ‘${fieldName}’ array index ‘${index}’ value ‘${path}’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
205
|
-
)
|
|
210
|
+
`Invalid object path for the ‘map’ multipart field entry key ‘${fieldName}’ array index ‘${index}’ value ‘${path}’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
211
|
+
),
|
|
206
212
|
);
|
|
207
213
|
}
|
|
208
214
|
}
|
|
@@ -221,8 +227,8 @@ export default function processRequest(
|
|
|
221
227
|
return exit(
|
|
222
228
|
createError(
|
|
223
229
|
400,
|
|
224
|
-
`Misordered multipart fields; files should follow ‘map’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
225
|
-
)
|
|
230
|
+
`Misordered multipart fields; files should follow ‘map’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
231
|
+
),
|
|
226
232
|
);
|
|
227
233
|
}
|
|
228
234
|
|
|
@@ -248,7 +254,7 @@ export default function processRequest(
|
|
|
248
254
|
stream.on("limit", () => {
|
|
249
255
|
fileError = createError(
|
|
250
256
|
413,
|
|
251
|
-
`File truncated as it exceeds the ${maxFileSize} byte size limit
|
|
257
|
+
`File truncated as it exceeds the ${maxFileSize} byte size limit.`,
|
|
252
258
|
);
|
|
253
259
|
stream.unpipe();
|
|
254
260
|
capacitor.destroy(fileError);
|
|
@@ -281,11 +287,11 @@ export default function processRequest(
|
|
|
281
287
|
|
|
282
288
|
stream.pipe(capacitor);
|
|
283
289
|
upload.resolve(file);
|
|
284
|
-
}
|
|
290
|
+
},
|
|
285
291
|
);
|
|
286
292
|
|
|
287
293
|
parser.once("filesLimit", () =>
|
|
288
|
-
exit(createError(413, `${maxFiles} max file uploads exceeded.`))
|
|
294
|
+
exit(createError(413, `${maxFiles} max file uploads exceeded.`)),
|
|
289
295
|
);
|
|
290
296
|
|
|
291
297
|
parser.once("finish", () => {
|
|
@@ -296,16 +302,16 @@ export default function processRequest(
|
|
|
296
302
|
return exit(
|
|
297
303
|
createError(
|
|
298
304
|
400,
|
|
299
|
-
`Missing multipart field ‘operations’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
300
|
-
)
|
|
305
|
+
`Missing multipart field ‘operations’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
306
|
+
),
|
|
301
307
|
);
|
|
302
308
|
|
|
303
309
|
if (!map)
|
|
304
310
|
return exit(
|
|
305
311
|
createError(
|
|
306
312
|
400,
|
|
307
|
-
`Missing multipart field ‘map’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL})
|
|
308
|
-
)
|
|
313
|
+
`Missing multipart field ‘map’ (${GRAPHQL_MULTIPART_REQUEST_SPEC_URL}).`,
|
|
314
|
+
),
|
|
309
315
|
);
|
|
310
316
|
|
|
311
317
|
for (const upload of map.values())
|
|
@@ -336,8 +342,8 @@ export default function processRequest(
|
|
|
336
342
|
exit(
|
|
337
343
|
createError(
|
|
338
344
|
499,
|
|
339
|
-
"Request disconnected during file upload stream parsing."
|
|
340
|
-
)
|
|
345
|
+
"Request disconnected during file upload stream parsing.",
|
|
346
|
+
),
|
|
341
347
|
);
|
|
342
348
|
});
|
|
343
349
|
|
|
@@ -350,14 +356,14 @@ export default function processRequest(
|
|
|
350
356
|
* [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec)
|
|
351
357
|
* has begun streaming in.
|
|
352
358
|
* @typedef {object} FileUpload
|
|
353
|
-
* @
|
|
354
|
-
* @
|
|
355
|
-
* trusted.
|
|
356
|
-
* @
|
|
357
|
-
* @
|
|
358
|
-
*
|
|
359
|
+
* @property {string} filename File name.
|
|
360
|
+
* @property {string} mimetype File MIME type. Provided by the client and can’t
|
|
361
|
+
* be trusted.
|
|
362
|
+
* @property {string} encoding File stream transfer encoding.
|
|
363
|
+
* @property {WriteStream} capacitor A private implementation detail that
|
|
364
|
+
* shouldn’t be used outside
|
|
359
365
|
* [`graphql-upload`](https://npm.im/graphql-upload).
|
|
360
|
-
* @
|
|
366
|
+
* @property {FileUploadCreateReadStream} createReadStream Creates a
|
|
361
367
|
* [Node.js readable stream](https://nodejs.org/api/stream.html#readable-streams)
|
|
362
368
|
* of the file’s contents, for processing and storage.
|
|
363
369
|
*/
|
|
@@ -370,38 +376,37 @@ export default function processRequest(
|
|
|
370
376
|
* all resolvers have resolved, or after an error has interrupted the request.
|
|
371
377
|
* @callback FileUploadCreateReadStream
|
|
372
378
|
* @param {FileUploadCreateReadStreamOptions} [options] Options.
|
|
373
|
-
* @returns {
|
|
379
|
+
* @returns {Readable}
|
|
374
380
|
* [Node.js readable stream](https://nodejs.org/api/stream.html#readable-streams)
|
|
375
381
|
* of the file’s contents.
|
|
376
382
|
* @see [Node.js `Readable` stream constructor docs](https://nodejs.org/api/stream.html#new-streamreadableoptions).
|
|
377
|
-
* @see [Node.js stream backpressure guide](https://nodejs.org/
|
|
383
|
+
* @see [Node.js stream backpressure guide](https://nodejs.org/learn/modules/backpressuring-in-streams).
|
|
378
384
|
*/
|
|
379
385
|
|
|
380
386
|
/**
|
|
381
387
|
* {@linkcode FileUploadCreateReadStream} options.
|
|
382
388
|
* @typedef {object} FileUploadCreateReadStreamOptions
|
|
383
|
-
* @
|
|
384
|
-
* .ReadStreamOptions["encoding"]} [options.encoding] Specify an encoding for
|
|
389
|
+
* @property {ReadStreamOptions["encoding"]} [encoding] Specify an encoding for
|
|
385
390
|
* the [`data`](https://nodejs.org/api/stream.html#event-data) chunks to be
|
|
386
391
|
* strings (without splitting multi-byte characters across chunks) instead of
|
|
387
392
|
* Node.js [`Buffer`](https://nodejs.org/api/buffer.html#buffer) instances.
|
|
388
393
|
* Supported values depend on the
|
|
389
|
-
* [`Buffer` implementation](https://github.com/nodejs/node/blob/
|
|
394
|
+
* [`Buffer` implementation](https://github.com/nodejs/node/blob/v26.5.0/lib/buffer.js#L695-L788)
|
|
390
395
|
* and include `utf8`, `ucs2`, `utf16le`, `latin1`, `ascii`, `base64`,
|
|
391
396
|
* `base64url`, or `hex`. Defaults to `utf8`.
|
|
392
|
-
* @
|
|
393
|
-
* .ReadStreamOptions["highWaterMark"]} [options.highWaterMark] Maximum number
|
|
397
|
+
* @property {ReadStreamOptions["highWaterMark"]} [highWaterMark] Maximum number
|
|
394
398
|
* of bytes to store in the internal buffer before ceasing to read from the
|
|
395
|
-
* underlying resource. Defaults to
|
|
399
|
+
* underlying resource. Defaults to the Node.js default high water mark for
|
|
400
|
+
* non object mode streams.
|
|
396
401
|
*/
|
|
397
402
|
|
|
398
403
|
/**
|
|
399
404
|
* Processes an incoming
|
|
400
405
|
* [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
|
|
401
406
|
* @callback ProcessRequestFunction
|
|
402
|
-
* @param {
|
|
407
|
+
* @param {IncomingMessage} request
|
|
403
408
|
* [Node.js HTTP server request instance](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
|
|
404
|
-
* @param {
|
|
409
|
+
* @param {ServerResponse} response
|
|
405
410
|
* [Node.js HTTP server response instance](https://nodejs.org/api/http.html#http_class_http_serverresponse).
|
|
406
411
|
* @param {ProcessRequestOptions} [options] Options.
|
|
407
412
|
* @returns {Promise<
|
|
@@ -414,10 +419,10 @@ export default function processRequest(
|
|
|
414
419
|
/**
|
|
415
420
|
* {@linkcode ProcessRequestFunction} options.
|
|
416
421
|
* @typedef {object} ProcessRequestOptions
|
|
417
|
-
* @
|
|
418
|
-
* size in bytes; enough for your queries. Defaults to `1000000` (1 MB).
|
|
419
|
-
* @
|
|
420
|
-
* `Infinity`.
|
|
421
|
-
* @
|
|
422
|
+
* @property {number} [maxFieldSize] Maximum allowed non file multipart form
|
|
423
|
+
* field size in bytes; enough for your queries. Defaults to `1000000` (1 MB).
|
|
424
|
+
* @property {number} [maxFileSize] Maximum allowed file size in bytes. Defaults
|
|
425
|
+
* to `Infinity`.
|
|
426
|
+
* @property {number} [maxFiles] Maximum allowed number of files. Defaults to
|
|
422
427
|
* `Infinity`.
|
|
423
428
|
*/
|
package/readme.md
CHANGED
|
@@ -2,17 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
# graphql-upload
|
|
4
4
|
|
|
5
|
-
Middleware and
|
|
5
|
+
Middleware and a scalar [`Upload`](./GraphQLUpload.mjs) 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
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
|
-
>
|
|
11
|
+
> [!TIP]
|
|
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 [`graphql`](https://npm.im/graphql)
|
|
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,9 +20,9 @@ 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://
|
|
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
|
-
Then, the [`Upload`](./GraphQLUpload.mjs)
|
|
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
|
|
|
27
27
|
## Examples
|
|
28
28
|
|
|
@@ -42,7 +42,7 @@ Then, the [`Upload`](./GraphQLUpload.mjs) scalar can be used for query or mutati
|
|
|
42
42
|
|
|
43
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.
|
|
44
44
|
|
|
45
|
-
[`busboy`](https://npm.im/busboy) parses multipart request streams. Once the `operations` and `map` fields have been parsed, [`Upload`](./GraphQLUpload.mjs)
|
|
45
|
+
[`busboy`](https://npm.im/busboy) parses multipart request streams. Once the `operations` and `map` fields have been parsed, scalar [`Upload`](./GraphQLUpload.mjs) values in the GraphQL operations are populated with promises, and the operations are passed down the middleware chain to GraphQL resolvers.
|
|
46
46
|
|
|
47
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.
|
|
48
48
|
|
|
@@ -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 `^
|
|
53
|
+
- [Node.js](https://nodejs.org) versions `^18.18.0 || ^20.9.0 || >=22.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
|
+
}
|