graphql-upload 16.0.1 → 17.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 +10 -2
- package/Upload.mjs +7 -6
- package/graphqlUploadExpress.mjs +29 -23
- package/graphqlUploadKoa.mjs +26 -18
- package/ignoreStream.mjs +3 -1
- package/package.json +27 -23
- package/processRequest.mjs +62 -57
- package/readme.md +23 -13
package/GraphQLUpload.mjs
CHANGED
|
@@ -7,12 +7,12 @@ import Upload from "./Upload.mjs";
|
|
|
7
7
|
/** @typedef {import("./processRequest.mjs").FileUpload} FileUpload */
|
|
8
8
|
|
|
9
9
|
/**
|
|
10
|
-
* A GraphQL `Upload`
|
|
10
|
+
* A GraphQL scalar `Upload` that can be used in a
|
|
11
11
|
* [`GraphQLSchema`](https://graphql.org/graphql-js/type/#graphqlschema). It’s
|
|
12
12
|
* value in resolvers is a promise that resolves
|
|
13
13
|
* {@link FileUpload file upload details} for processing and storage.
|
|
14
14
|
* @example
|
|
15
|
-
* A schema built using
|
|
15
|
+
* A schema built using the function
|
|
16
16
|
* [`makeExecutableSchema`](https://www.graphql-tools.com/docs/api/modules/schema_src#makeexecutableschema)
|
|
17
17
|
* from [`@graphql-tools/schema`](https://npm.im/@graphql-tools/schema):
|
|
18
18
|
*
|
|
@@ -60,6 +60,14 @@ import Upload from "./Upload.mjs";
|
|
|
60
60
|
* }),
|
|
61
61
|
* });
|
|
62
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
|
+
* ```
|
|
63
71
|
*/
|
|
64
72
|
const GraphQLUpload = new GraphQLScalarType({
|
|
65
73
|
name: "Upload",
|
package/Upload.mjs
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
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
|
|
@@ -15,21 +17,20 @@ export default class Upload {
|
|
|
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,5 +1,13 @@
|
|
|
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";
|
|
4
12
|
|
|
5
13
|
/**
|
|
@@ -8,8 +16,8 @@ import defaultProcessRequest from "./processRequest.mjs";
|
|
|
8
16
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
9
17
|
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
10
18
|
* following GraphQL middleware to consume.
|
|
11
|
-
* @param {
|
|
12
|
-
* processRequest?:
|
|
19
|
+
* @param {ProcessRequestOptions & {
|
|
20
|
+
* processRequest?: ProcessRequestFunction,
|
|
13
21
|
* }} options Options.
|
|
14
22
|
* @returns Express middleware.
|
|
15
23
|
* @example
|
|
@@ -41,36 +49,34 @@ export default function graphqlUploadExpress({
|
|
|
41
49
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
42
50
|
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
43
51
|
* following GraphQL middleware to consume.
|
|
44
|
-
* @param {
|
|
45
|
-
* @param {
|
|
46
|
-
* @param {
|
|
52
|
+
* @param {Request} request Express request.
|
|
53
|
+
* @param {Response} response Express response.
|
|
54
|
+
* @param {NextFunction} next Invokes the next middleware.
|
|
47
55
|
*/
|
|
48
56
|
function graphqlUploadExpressMiddleware(request, response, next) {
|
|
49
|
-
if (
|
|
57
|
+
if (request.is("multipart/form-data")) {
|
|
58
|
+
const requestEnd = new Promise((resolve) => request.on("end", resolve));
|
|
59
|
+
const { send } = response;
|
|
50
60
|
|
|
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) => {
|
|
61
|
+
// @ts-ignore Todo: Find a less hacky way to prevent sending a response
|
|
62
|
+
// before the request has ended.
|
|
63
|
+
response.send = (...args) => {
|
|
59
64
|
requestEnd.then(() => {
|
|
60
65
|
response.send = send;
|
|
61
66
|
response.send(...args);
|
|
62
67
|
});
|
|
63
68
|
};
|
|
64
69
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
70
|
+
processRequest(request, response, processRequestOptions)
|
|
71
|
+
.then((body) => {
|
|
72
|
+
request.body = body;
|
|
73
|
+
next();
|
|
74
|
+
})
|
|
75
|
+
.catch((error) => {
|
|
76
|
+
if (error.status && error.expose) response.status(error.status);
|
|
77
|
+
next(error);
|
|
78
|
+
});
|
|
79
|
+
} else next();
|
|
74
80
|
}
|
|
75
81
|
|
|
76
82
|
return graphqlUploadExpressMiddleware;
|
package/graphqlUploadKoa.mjs
CHANGED
|
@@ -1,5 +1,13 @@
|
|
|
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";
|
|
4
12
|
|
|
5
13
|
/**
|
|
@@ -8,8 +16,8 @@ import defaultProcessRequest from "./processRequest.mjs";
|
|
|
8
16
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
9
17
|
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
10
18
|
* following GraphQL middleware to consume.
|
|
11
|
-
* @param {
|
|
12
|
-
* processRequest?:
|
|
19
|
+
* @param {ProcessRequestOptions & {
|
|
20
|
+
* processRequest?: ProcessRequestFunction,
|
|
13
21
|
* }} options Options.
|
|
14
22
|
* @returns Koa middleware.
|
|
15
23
|
* @example
|
|
@@ -42,25 +50,25 @@ export default function graphqlUploadKoa({
|
|
|
42
50
|
* using {@linkcode processRequest}, ignoring non multipart requests. It sets
|
|
43
51
|
* the request `body` to be similar to a conventional GraphQL POST request for
|
|
44
52
|
* following GraphQL middleware to consume.
|
|
45
|
-
* @param {
|
|
46
|
-
* @param {
|
|
53
|
+
* @param {ParameterizedContext} ctx Koa context.
|
|
54
|
+
* @param {Next} next Invokes the next middleware.
|
|
47
55
|
*/
|
|
48
56
|
async function graphqlUploadKoaMiddleware(ctx, next) {
|
|
49
|
-
if (
|
|
50
|
-
|
|
51
|
-
const requestEnd = new Promise((resolve) => ctx.req.on("end", resolve));
|
|
57
|
+
if (ctx.request.is("multipart/form-data")) {
|
|
58
|
+
const requestEnd = new Promise((resolve) => ctx.req.on("end", resolve));
|
|
52
59
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
60
|
+
try {
|
|
61
|
+
// @ts-ignore This is conventional.
|
|
62
|
+
ctx.request.body = await processRequest(
|
|
63
|
+
ctx.req,
|
|
64
|
+
ctx.res,
|
|
65
|
+
processRequestOptions,
|
|
66
|
+
);
|
|
67
|
+
await next();
|
|
68
|
+
} finally {
|
|
69
|
+
await requestEnd;
|
|
70
|
+
}
|
|
71
|
+
} else await next();
|
|
64
72
|
}
|
|
65
73
|
|
|
66
74
|
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.0.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",
|
|
@@ -45,10 +48,10 @@
|
|
|
45
48
|
"./Upload.mjs": "./Upload.mjs"
|
|
46
49
|
},
|
|
47
50
|
"engines": {
|
|
48
|
-
"node": "^
|
|
51
|
+
"node": "^18.18.0 || ^20.9.0 || >=22.0.0"
|
|
49
52
|
},
|
|
50
53
|
"peerDependencies": {
|
|
51
|
-
"@types/express": "
|
|
54
|
+
"@types/express": "4.0.29 - 5",
|
|
52
55
|
"@types/koa": "^2.11.4",
|
|
53
56
|
"graphql": "^16.3.0"
|
|
54
57
|
},
|
|
@@ -70,27 +73,28 @@
|
|
|
70
73
|
"object-path": "^0.11.8"
|
|
71
74
|
},
|
|
72
75
|
"devDependencies": {
|
|
73
|
-
"@
|
|
74
|
-
"@types/
|
|
75
|
-
"
|
|
76
|
-
"
|
|
77
|
-
"
|
|
78
|
-
"
|
|
79
|
-
"
|
|
80
|
-
"
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
"
|
|
84
|
-
"
|
|
85
|
-
"
|
|
86
|
-
"
|
|
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"
|
|
87
91
|
},
|
|
88
92
|
"scripts": {
|
|
89
|
-
"eslint": "eslint .",
|
|
90
93
|
"prettier": "prettier -c .",
|
|
94
|
+
"eslint": "eslint",
|
|
91
95
|
"types": "tsc -p jsconfig.json",
|
|
92
|
-
"tests": "coverage-node --
|
|
93
|
-
"test": "
|
|
94
|
-
"prepublishOnly": "
|
|
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
99
|
}
|
|
96
100
|
}
|
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,8 +17,6 @@ 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).
|
|
@@ -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,7 +376,7 @@ 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).
|
|
@@ -380,8 +386,7 @@ export default function processRequest(
|
|
|
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.
|
|
@@ -389,19 +394,19 @@ export default function processRequest(
|
|
|
389
394
|
* [`Buffer` implementation](https://github.com/nodejs/node/blob/v18.1.0/lib/buffer.js#L590-L680)
|
|
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,31 +2,33 @@
|
|
|
2
2
|
|
|
3
3
|
# graphql-upload
|
|
4
4
|
|
|
5
|
-
[
|
|
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
|
+
>
|
|
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
|
|
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:
|
|
14
16
|
|
|
15
17
|
```sh
|
|
16
18
|
npm install graphql-upload graphql
|
|
17
19
|
```
|
|
18
20
|
|
|
19
|
-
Use the [`graphqlUploadKoa`](./graphqlUploadKoa.mjs) or [`graphqlUploadExpress`](./graphqlUploadExpress.mjs)
|
|
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.mjs)
|
|
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.
|
|
22
24
|
|
|
23
|
-
|
|
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).
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
## Examples
|
|
26
28
|
|
|
27
|
-
|
|
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
|
-
|
|
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,17 +42,25 @@ 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.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.
|
|
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
|
-
|
|
51
|
+
Supported runtime environments:
|
|
52
|
+
|
|
53
|
+
- [Node.js](https://nodejs.org) versions `^18.18.0 || ^20.9.0 || >=22.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
|
-
|
|
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
65
|
- [`GraphQLUpload.mjs`](./GraphQLUpload.mjs)
|
|
56
66
|
- [`graphqlUploadExpress.mjs`](./graphqlUploadExpress.mjs)
|