@prefabs.tech/fastify-graphql 0.94.1 → 0.95.1
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/README.md +53 -8
- package/dist/prefabs-tech-fastify-graphql.cjs +2 -2
- package/dist/prefabs-tech-fastify-graphql.js +70 -37
- package/dist/tsconfig.tsbuildinfo +1 -1
- package/dist/types/constants.d.ts +4 -0
- package/dist/types/constants.d.ts.map +1 -0
- package/dist/types/index.d.ts +9 -1
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/plugin.d.ts.map +1 -1
- package/dist/types/types.d.ts +11 -0
- package/dist/types/types.d.ts.map +1 -1
- package/dist/types/uploads/processMultipartFormData.d.ts +5 -0
- package/dist/types/uploads/processMultipartFormData.d.ts.map +1 -0
- package/dist/types/uploads/transport.d.ts +8 -0
- package/dist/types/uploads/transport.d.ts.map +1 -0
- package/package.json +38 -37
- package/LICENSE +0 -21
package/README.md
CHANGED
|
@@ -9,7 +9,7 @@ The plugin is a thin wrapper around the [mercurius](https://mercurius.dev/#/) pl
|
|
|
9
9
|
While registering `mercurius` directly perfectly enables GraphQL in a Fastify backend, enterprise APIs require deep context injection—such as database connections and application configurations—to function effectively within resolvers. We created this plugin to:
|
|
10
10
|
|
|
11
11
|
- **Automate Context Injection**: Instead of manually building context objects on every request, this plugin automatically populates the `MercuriusContext` with the `fastify.config`, `slonik` database connection, and `dbSchema`, making them instantly and safely available to all your GraphQL resolvers out-of-the-box.
|
|
12
|
-
- **Unify Configuration**:
|
|
12
|
+
- **Unify Configuration**: The plugin takes a strictly typed `GraphqlOptions` object (all mercurius options plus our `enabled` and `uploads` flags), so schema paths, options, and feature flags are managed in one place.
|
|
13
13
|
|
|
14
14
|
### Design Decisions: Why not Apollo Server or bare Mercurius?
|
|
15
15
|
|
|
@@ -41,6 +41,8 @@ pnpm add --filter "@scope/project" @prefabs.tech/fastify-config @prefabs.tech/fa
|
|
|
41
41
|
|
|
42
42
|
To set up graphql in fastify project, follow these steps:
|
|
43
43
|
|
|
44
|
+
### Define schema and resolvers
|
|
45
|
+
|
|
44
46
|
Create a resolvers file at `src/graphql/resolvers.ts` to define all GraphQL mutations and queries.
|
|
45
47
|
|
|
46
48
|
```typescript
|
|
@@ -81,10 +83,11 @@ export { default as resolvers } from "./resolvers";
|
|
|
81
83
|
export { default as schema } from "./schema";
|
|
82
84
|
```
|
|
83
85
|
|
|
84
|
-
Add
|
|
86
|
+
### Add the config block
|
|
87
|
+
|
|
88
|
+
Add a `graphql` block (type `GraphqlOptions`) to your central config in `config/index.ts`. A single app-wide config from which every plugin's options are derived remains the recommended pattern — what changed is that the plugin no longer reads it from the fastify instance; you pass its slice explicitly at registration:
|
|
85
89
|
|
|
86
90
|
```typescript
|
|
87
|
-
import { parse } from "@prefabs.tech/fastify-config";
|
|
88
91
|
import dotenv from "dotenv";
|
|
89
92
|
|
|
90
93
|
import { resolvers, schema } from "../src/graphql";
|
|
@@ -108,7 +111,9 @@ const config: ApiConfig = {
|
|
|
108
111
|
export default config;
|
|
109
112
|
```
|
|
110
113
|
|
|
111
|
-
Register
|
|
114
|
+
### Register plugin
|
|
115
|
+
|
|
116
|
+
Register the plugin with your fastify instance in `src/index.ts`, passing its config slice as the second argument:
|
|
112
117
|
|
|
113
118
|
```typescript
|
|
114
119
|
import configPlugin from "@prefabs.tech/fastify-config";
|
|
@@ -122,10 +127,11 @@ const start = async () => {
|
|
|
122
127
|
logger: config.logger,
|
|
123
128
|
});
|
|
124
129
|
|
|
125
|
-
// Register fastify-config plugin
|
|
130
|
+
// Register fastify-config plugin (decorates the app with the global
|
|
131
|
+
// config; also feeds the default graphql resolver context)
|
|
126
132
|
await fastify.register(configPlugin, { config });
|
|
127
133
|
|
|
128
|
-
// Register fastify-graphql plugin
|
|
134
|
+
// Register fastify-graphql plugin, passing its config slice explicitly
|
|
129
135
|
await fastify.register(graphqlPlugin, config.graphql);
|
|
130
136
|
|
|
131
137
|
await fastify.listen({
|
|
@@ -137,11 +143,31 @@ const start = async () => {
|
|
|
137
143
|
start();
|
|
138
144
|
```
|
|
139
145
|
|
|
146
|
+
Registering the plugin without options is deprecated — see [Deprecated: configuration via `fastify.config`](#deprecated-configuration-via-fastifyconfig).
|
|
147
|
+
|
|
140
148
|
## Configuration
|
|
141
149
|
|
|
142
|
-
The `
|
|
150
|
+
The plugin is configured with a `GraphqlOptions` object passed directly to `register()` — typically the `graphql` slice of your central `ApiConfig` (`config.graphql`). The plugin itself makes no assumption that a global config exists; deriving its options from one is an app-level choice. It supports all of the [original mercurius plugin's options](https://mercurius.dev/#/docs/api/options?id=plugin-options), plus:
|
|
151
|
+
|
|
152
|
+
- `enabled` (boolean) — feature switch for the GraphQL server. The plugin registration stays in your code unconditionally; this flag — typically driven by per-environment configuration — decides whether anything is actually mounted. When `true`, mercurius and the upload transport are registered; when `false` or omitted, the plugin logs `"GraphQL API not enabled"` and mounts nothing (no `/graphql` route, no catch-all content-type parser). This lets you turn GraphQL on or off per environment by flipping a config value instead of adding or removing the `register()` call.
|
|
153
|
+
- `uploads` — configure or disable GraphQL file uploads (see below).
|
|
154
|
+
|
|
155
|
+
### File uploads
|
|
156
|
+
|
|
157
|
+
GraphQL file uploads ([graphql multipart request spec](https://github.com/jaydenseric/graphql-multipart-request-spec)) are supported out of the box: when the plugin is enabled it registers an upload transport (content-type parser + `graphql-upload-minimal` processing) before mercurius. Configure or disable it with the `uploads` option:
|
|
158
|
+
|
|
159
|
+
```typescript
|
|
160
|
+
// config/index.ts — inside the graphql block
|
|
161
|
+
graphql: {
|
|
162
|
+
// ...
|
|
163
|
+
uploads: { maxFileSize: 10485760 }, // or { enabled: false } to disable
|
|
164
|
+
},
|
|
165
|
+
|
|
166
|
+
// registration is unchanged
|
|
167
|
+
await fastify.register(graphqlPlugin, config.graphql);
|
|
168
|
+
```
|
|
143
169
|
|
|
144
|
-
|
|
170
|
+
Declare `scalar Upload` in your schema; resolvers receive `Upload` promises. See GUIDE.md (Feature 16) for gotchas, including plugin ordering when combining with REST uploads via `@prefabs.tech/fastify-s3`.
|
|
145
171
|
|
|
146
172
|
## Context
|
|
147
173
|
|
|
@@ -153,6 +179,8 @@ The fastify-graphql plugin will generate a graphql context on every request that
|
|
|
153
179
|
| `database` | `Database` | The fastify server's slonik instance (as per [@prefabs.tech/fastify-slonik](../slonik/)) |
|
|
154
180
|
| `dbSchema` | `string` | The database schema (as per [@prefabs.tech/fastify-slonik](../slonik/)) |
|
|
155
181
|
|
|
182
|
+
The `config` and `database` attributes are populated from the request decorations provided by the config and slonik plugins when those are registered; they are `undefined` otherwise.
|
|
183
|
+
|
|
156
184
|
## Supporting `.gql` files and external schema exports
|
|
157
185
|
|
|
158
186
|
To work with multiple schemas defined in `.gql` files or support GraphQL schema exports from external packages, ensure the following packages are installed in your API:
|
|
@@ -204,3 +232,20 @@ type Query {
|
|
|
204
232
|
add(x: Int, y: Int): Int
|
|
205
233
|
}
|
|
206
234
|
```
|
|
235
|
+
|
|
236
|
+
## Deprecated: configuration via `fastify.config`
|
|
237
|
+
|
|
238
|
+
Earlier versions of this plugin could be registered without options: it then read its configuration from the fastify instance (`fastify.config.graphql`, decorated by [@prefabs.tech/fastify-config](../config/)).
|
|
239
|
+
|
|
240
|
+
This approach is **deprecated**. For backward compatibility it is temporarily still supported: registering without options falls back to `fastify.config.graphql` and logs a deprecation warning; if `fastify.config.graphql` is missing too, registration throws. The fallback will be removed in a future release.
|
|
241
|
+
|
|
242
|
+
To migrate, pass the configuration you previously kept under `config.graphql` directly to `register()`:
|
|
243
|
+
|
|
244
|
+
```typescript
|
|
245
|
+
// Before (deprecated)
|
|
246
|
+
await fastify.register(configPlugin, { config }); // config.graphql
|
|
247
|
+
await fastify.register(graphqlPlugin);
|
|
248
|
+
|
|
249
|
+
// After
|
|
250
|
+
await fastify.register(graphqlPlugin, config.graphql);
|
|
251
|
+
```
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
|
|
1
|
+
Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require("graphql-tag"),l=require("fastify-plugin");l=s(l,1);let u=require("mercurius"),d=require("graphql-upload-minimal"),f=require("busboy");f=s(f,1);let p=require("@graphql-tools/merge");var m=c.gql`
|
|
2
2
|
directive @auth(
|
|
3
3
|
profileValidation: Boolean
|
|
4
4
|
emailVerification: Boolean
|
|
@@ -30,4 +30,4 @@
|
|
|
30
30
|
type DeleteResult {
|
|
31
31
|
result: Boolean!
|
|
32
32
|
}
|
|
33
|
-
`,
|
|
33
|
+
`,h=`/graphql`,g=`prefabs-graphql-upload-transport`,_=e=>async(t,n)=>{let r={config:t.config,database:t.slonik,dbSchema:t.dbSchema};if(e)for(let i of e)await i.updateContext(r,t,n);return r},v=(e,t,n)=>{let r=(0,f.default)({headers:e.headers}),i={},a={};r.on(`field`,(e,t)=>{i[e]=t}),r.on(`file`,(e,t,n)=>{let r=[];t.on(`data`,e=>{r.push(e)}),t.on(`end`,()=>{let t=Buffer.concat(r);a[e]||(a[e]=[]),a[e].push({...n,data:t,mimetype:n.mimeType})})}),r.on(`finish`,()=>{e.body={...i,...a},n(null,e.body)}),r.on(`error`,t=>{e.log.error(t)}),t.pipe(r)},y=(0,l.default)(async(e,t)=>{let{path:n,...r}=t,i=n??`/graphql`;e.addContentTypeParser(`*`,(e,t,n)=>{if((e.headers[`content-type`]||``).includes(`multipart`))if(e.routeOptions.url?.startsWith(i))e.graphqlFileUploadMultipart=!0;else{v(e,t,n);return}n(null)}),e.addHook(`preValidation`,async(e,t)=>{e.graphqlFileUploadMultipart&&(e.body=await(0,d.processRequest)(e.raw,t.raw,r))})},{fastify:`>= 4.x`,name:g}),b=(0,l.default)(async(e,t)=>{if(e.log.info(`Registering fastify-graphql plugin`),Object.keys(t).length===0){if(e.log.warn(`The graphql plugin now recommends passing graphql options directly to the plugin.`),!e.config.graphql)throw Error(`Missing graphql configuration. Did you forget to pass it to the graphql plugin?`);t=e.config.graphql}t?.enabled?(t.uploads?.enabled!==!1&&!e.hasPlugin(`prefabs-graphql-upload-transport`)&&await e.register(y,{path:t.path,...t.uploads}),await e.register(u.mercurius,{context:_(t.plugins),...t})):e.log.info(`GraphQL API not enabled`)});exports.DEFAULT_GRAPHQL_PATH=h,exports.UPLOAD_TRANSPORT_PLUGIN_NAME=g,exports.baseSchema=m,exports.default=b,Object.defineProperty(exports,"gql",{enumerable:!0,get:function(){return c.gql}}),exports.graphqlUploadTransport=y,Object.defineProperty(exports,"mergeTypeDefs",{enumerable:!0,get:function(){return p.mergeTypeDefs}});
|
|
@@ -1,9 +1,11 @@
|
|
|
1
|
-
import { gql as
|
|
2
|
-
import
|
|
3
|
-
import
|
|
4
|
-
import {
|
|
5
|
-
import
|
|
6
|
-
|
|
1
|
+
import { gql as e, gql as t } from "graphql-tag";
|
|
2
|
+
import n from "fastify-plugin";
|
|
3
|
+
import { mercurius as r } from "mercurius";
|
|
4
|
+
import { processRequest as i } from "graphql-upload-minimal";
|
|
5
|
+
import a from "busboy";
|
|
6
|
+
import { mergeTypeDefs as o } from "@graphql-tools/merge";
|
|
7
|
+
//#region src/baseSchema.ts
|
|
8
|
+
var s = t`
|
|
7
9
|
directive @auth(
|
|
8
10
|
profileValidation: Boolean
|
|
9
11
|
emailVerification: Boolean
|
|
@@ -35,34 +37,65 @@ const m = r`
|
|
|
35
37
|
type DeleteResult {
|
|
36
38
|
result: Boolean!
|
|
37
39
|
}
|
|
38
|
-
`,
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
},
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
40
|
+
`, c = "/graphql", l = "prefabs-graphql-upload-transport", u = (e) => async (t, n) => {
|
|
41
|
+
let r = {
|
|
42
|
+
config: t.config,
|
|
43
|
+
database: t.slonik,
|
|
44
|
+
dbSchema: t.dbSchema
|
|
45
|
+
};
|
|
46
|
+
if (e) for (let i of e) await i.updateContext(r, t, n);
|
|
47
|
+
return r;
|
|
48
|
+
}, d = (e, t, n) => {
|
|
49
|
+
let r = a({ headers: e.headers }), i = {}, o = {};
|
|
50
|
+
r.on("field", (e, t) => {
|
|
51
|
+
i[e] = t;
|
|
52
|
+
}), r.on("file", (e, t, n) => {
|
|
53
|
+
let r = [];
|
|
54
|
+
t.on("data", (e) => {
|
|
55
|
+
r.push(e);
|
|
56
|
+
}), t.on("end", () => {
|
|
57
|
+
let t = Buffer.concat(r);
|
|
58
|
+
o[e] || (o[e] = []), o[e].push({
|
|
59
|
+
...n,
|
|
60
|
+
data: t,
|
|
61
|
+
mimetype: n.mimeType
|
|
62
|
+
});
|
|
63
|
+
});
|
|
64
|
+
}), r.on("finish", () => {
|
|
65
|
+
e.body = {
|
|
66
|
+
...i,
|
|
67
|
+
...o
|
|
68
|
+
}, n(null, e.body);
|
|
69
|
+
}), r.on("error", (t) => {
|
|
70
|
+
e.log.error(t);
|
|
71
|
+
}), t.pipe(r);
|
|
72
|
+
}, f = n(async (e, t) => {
|
|
73
|
+
let { path: n, ...r } = t, a = n ?? "/graphql";
|
|
74
|
+
e.addContentTypeParser("*", (e, t, n) => {
|
|
75
|
+
if ((e.headers["content-type"] || "").includes("multipart")) if (e.routeOptions.url?.startsWith(a)) e.graphqlFileUploadMultipart = !0;
|
|
76
|
+
else {
|
|
77
|
+
d(e, t, n);
|
|
78
|
+
return;
|
|
79
|
+
}
|
|
80
|
+
n(null);
|
|
81
|
+
}), e.addHook("preValidation", async (e, t) => {
|
|
82
|
+
e.graphqlFileUploadMultipart && (e.body = await i(e.raw, t.raw, r));
|
|
83
|
+
});
|
|
84
|
+
}, {
|
|
85
|
+
fastify: ">= 4.x",
|
|
86
|
+
name: l
|
|
87
|
+
}), p = n(async (e, t) => {
|
|
88
|
+
if (e.log.info("Registering fastify-graphql plugin"), Object.keys(t).length === 0) {
|
|
89
|
+
if (e.log.warn("The graphql plugin now recommends passing graphql options directly to the plugin."), !e.config.graphql) throw Error("Missing graphql configuration. Did you forget to pass it to the graphql plugin?");
|
|
90
|
+
t = e.config.graphql;
|
|
91
|
+
}
|
|
92
|
+
t?.enabled ? (t.uploads?.enabled !== !1 && !e.hasPlugin("prefabs-graphql-upload-transport") && await e.register(f, {
|
|
93
|
+
path: t.path,
|
|
94
|
+
...t.uploads
|
|
95
|
+
}), await e.register(r, {
|
|
96
|
+
context: u(t.plugins),
|
|
97
|
+
...t
|
|
98
|
+
})) : e.log.info("GraphQL API not enabled");
|
|
99
|
+
});
|
|
100
|
+
//#endregion
|
|
101
|
+
export { c as DEFAULT_GRAPHQL_PATH, l as UPLOAD_TRANSPORT_PLUGIN_NAME, s as baseSchema, p as default, e as gql, f as graphqlUploadTransport, o as mergeTypeDefs };
|