@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 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**: By integrating seamlessly with `@prefabs.tech/fastify-config`, it ensures that your GraphQL schema paths, options, and boolean flags are strictly typed and managed in one centralized location.
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 a `graphql` block to your config in `config/index.ts`:
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 the plugin with your fastify instance in `src/index.ts`:
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 `graphql` block in the `ApiConfig` supports all of the [original mercurius plugin's options](https://mercurius.dev/#/docs/api/options?id=plugin-options).
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
- An additional `enabled` (boolean) option allows you to disable the graphql server.
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
- "use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const n=require("graphql-tag"),l=require("fastify-plugin"),a=require("mercurius"),g=require("@graphql-tools/merge"),c=n.gql`
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
- `,s=r=>async(e,i)=>{const t={config:e.config,database:e.slonik,dbSchema:e.dbSchema};if(r)for(const o of r)await o.updateContext(t,e,i);return t},u=async(r,e)=>{if(r.log.info("Registering fastify-graphql plugin"),Object.keys(e).length===0){if(r.log.warn("The graphql plugin now recommends passing graphql options directly to the plugin."),!r.config.graphql)throw new Error("Missing graphql configuration. Did you forget to pass it to the graphql plugin?");e=r.config.graphql}e?.enabled?await r.register(a.mercurius,{context:s(e.plugins),...e}):r.log.info("GraphQL API not enabled")},p=l(u);Object.defineProperty(exports,"gql",{enumerable:!0,get:()=>n.gql});Object.defineProperty(exports,"mergeTypeDefs",{enumerable:!0,get:()=>g.mergeTypeDefs});exports.baseSchema=c;exports.default=p;
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 r } from "graphql-tag";
2
- import { gql as S } from "graphql-tag";
3
- import a from "fastify-plugin";
4
- import { mercurius as l } from "mercurius";
5
- import { mergeTypeDefs as I } from "@graphql-tools/merge";
6
- const m = r`
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
- `, g = (i) => async (e, n) => {
39
- const o = {
40
- config: e.config,
41
- database: e.slonik,
42
- dbSchema: e.dbSchema
43
- };
44
- if (i)
45
- for (const t of i)
46
- await t.updateContext(o, e, n);
47
- return o;
48
- }, c = async (i, e) => {
49
- if (i.log.info("Registering fastify-graphql plugin"), Object.keys(e).length === 0) {
50
- if (i.log.warn(
51
- "The graphql plugin now recommends passing graphql options directly to the plugin."
52
- ), !i.config.graphql)
53
- throw new Error(
54
- "Missing graphql configuration. Did you forget to pass it to the graphql plugin?"
55
- );
56
- e = i.config.graphql;
57
- }
58
- e?.enabled ? await i.register(l, {
59
- context: g(e.plugins),
60
- ...e
61
- }) : i.log.info("GraphQL API not enabled");
62
- }, h = a(c);
63
- export {
64
- m as baseSchema,
65
- h as default,
66
- S as gql,
67
- I as mergeTypeDefs
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 };