graphql-upload 16.0.1 → 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.
package/GraphQLUpload.mjs CHANGED
@@ -12,7 +12,7 @@ import Upload from "./Upload.mjs";
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/ignoreStream.mjs CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  /**
4
4
  * Safely ignores a Node.js readable stream.
5
- * @param {import("stream").Readable} stream Node.js readable stream.
5
+ * @param {import("node:stream").Readable} stream Node.js readable stream.
6
6
  */
7
7
  export default function ignoreStream(stream) {
8
8
  // Prevent an unhandled error from crashing the process.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "graphql-upload",
3
- "version": "16.0.1",
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": {
@@ -72,18 +72,18 @@
72
72
  "devDependencies": {
73
73
  "@types/express": "^4.17.13",
74
74
  "@types/koa": "^2.13.5",
75
- "coverage-node": "^6.1.0",
76
- "eslint": "^8.20.0",
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.9",
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 .",
@@ -370,7 +370,7 @@ export default function processRequest(
370
370
  * all resolvers have resolved, or after an error has interrupted the request.
371
371
  * @callback FileUploadCreateReadStream
372
372
  * @param {FileUploadCreateReadStreamOptions} [options] Options.
373
- * @returns {import("stream").Readable}
373
+ * @returns {import("node:stream").Readable}
374
374
  * [Node.js readable stream](https://nodejs.org/api/stream.html#readable-streams)
375
375
  * of the file’s contents.
376
376
  * @see [Node.js `Readable` stream constructor docs](https://nodejs.org/api/stream.html#new-streamreadableoptions).
@@ -399,9 +399,9 @@ export default function processRequest(
399
399
  * Processes an incoming
400
400
  * [GraphQL multipart request](https://github.com/jaydenseric/graphql-multipart-request-spec).
401
401
  * @callback ProcessRequestFunction
402
- * @param {import("http").IncomingMessage} request
402
+ * @param {import("node:http").IncomingMessage} request
403
403
  * [Node.js HTTP server request instance](https://nodejs.org/api/http.html#http_class_http_incomingmessage).
404
- * @param {import("http").ServerResponse} response
404
+ * @param {import("node:http").ServerResponse} response
405
405
  * [Node.js HTTP server response instance](https://nodejs.org/api/http.html#http_class_http_serverresponse).
406
406
  * @param {ProcessRequestOptions} [options] Options.
407
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)
6
-
7
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.
8
6
 
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
+
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.mjs) or [`graphqlUploadExpress`](./graphqlUploadExpress.mjs) middleware just before GraphQL middleware. Alternatively, use [`processRequest`](./processRequest.mjs) 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.mjs) 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.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.
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.
@@ -46,11 +48,19 @@ The [GraphQL multipart request spec](https://github.com/jaydenseric/graphql-mult
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 ECMAScript 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
65
  - [`GraphQLUpload.mjs`](./GraphQLUpload.mjs)
56
66
  - [`graphqlUploadExpress.mjs`](./graphqlUploadExpress.mjs)