├── .nvmrc ├── .gitignore ├── src ├── step-04-n+1 │ ├── .env │ ├── server.js │ ├── package.json │ ├── lib │ │ ├── config.js │ │ └── db.js │ ├── README.md │ ├── index.js │ ├── graphql.js │ └── test │ │ └── n+1.test.js ├── step-01-basic │ ├── server.js │ ├── package.json │ ├── graphql.js │ ├── README.md │ ├── index.js │ └── test │ │ └── basic.test.js ├── step-02-loaders │ ├── server.js │ ├── package.json │ ├── README.md │ ├── index.js │ ├── graphql.js │ └── test │ │ └── loaders.test.js ├── step-05-context │ ├── server.js │ ├── package.json │ ├── README.md │ ├── index.js │ ├── graphql.js │ └── test │ │ └── context.test.js ├── step-09-variables │ ├── server.js │ ├── package.json │ ├── graphql.js │ ├── README.md │ ├── index.js │ └── test │ │ └── variables.test.js ├── step-10-fragments │ ├── server.js │ ├── package.json │ ├── index.js │ ├── README.md │ ├── graphql.js │ └── test │ │ └── fragments.test.js ├── step-07-error-handling │ ├── server.js │ ├── package.json │ ├── README.md │ ├── index.js │ ├── graphql.js │ └── test │ │ └── errors.test.js ├── step-03-executable-schema │ ├── server.js │ ├── package.json │ ├── graphql.js │ ├── README.md │ ├── index.js │ └── test │ │ └── schema.test.js ├── step-06-hooks │ ├── package.json │ ├── graphql.js │ ├── README.md │ ├── index.js │ ├── server.js │ └── test │ │ └── hooks.test.js ├── step-08-federation │ ├── package.json │ ├── README.md │ ├── services │ │ ├── service.js │ │ ├── service1.js │ │ └── service2.js │ ├── server.js │ ├── index.js │ ├── data.js │ └── test │ │ └── federation.test.js └── step-11-authorization │ ├── README.md │ ├── package.json │ ├── services │ ├── service.js │ ├── service1.js │ └── service2.js │ ├── server.js │ ├── data.js │ ├── index.js │ └── test │ └── authorization.test.js ├── public └── images │ ├── step-02.jpg │ └── nearform.svg ├── .prettierrc ├── migrations ├── 002.do.sql └── 001.do.sql ├── components └── Copyright.js ├── docker-compose.yml ├── .postgratorrc.json ├── .github ├── dependabot.yml └── workflows │ ├── check-linked-issues.yml │ ├── deploy.yml │ └── ci.yml ├── eslint.config.mjs ├── styles.css ├── README.md ├── package.json ├── LICENSE └── slides.md /.nvmrc: -------------------------------------------------------------------------------- 1 | lts/* -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules/ 2 | .DS_Store 3 | index.html 4 | dist/ 5 | coverage/ 6 | -------------------------------------------------------------------------------- /src/step-04-n+1/.env: -------------------------------------------------------------------------------- 1 | PG_CONNECTION_STRING=postgres://postgres:postgres@localhost:5433/postgres 2 | -------------------------------------------------------------------------------- /public/images/step-02.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nearform/the-graphql-workshop/HEAD/public/images/step-02.jpg -------------------------------------------------------------------------------- /.prettierrc: -------------------------------------------------------------------------------- 1 | { 2 | "semi": false, 3 | "singleQuote": true, 4 | "arrowParens": "avoid", 5 | "trailingComma": "none" 6 | } 7 | -------------------------------------------------------------------------------- /src/step-04-n+1/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-01-basic/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-02-loaders/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-05-context/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-09-variables/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-10-fragments/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /src/step-07-error-handling/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /migrations/002.do.sql: -------------------------------------------------------------------------------- 1 | INSERT INTO owners (name) VALUES ('Jennifer'), ('Simon'); 2 | INSERT INTO pets (name, owner) VALUES ('Max', 2), ('Charlie', 1); 3 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/server.js: -------------------------------------------------------------------------------- 1 | import buildServer from './index.js' 2 | 3 | const app = buildServer() 4 | 5 | app.listen({ port: 3000 }) 6 | -------------------------------------------------------------------------------- /components/Copyright.js: -------------------------------------------------------------------------------- 1 | const Copyright = () => 2 | `© Copyright ${new Date().getFullYear()} Nearform Ltd. All Rights Reserved.` 3 | 4 | export default Copyright 5 | -------------------------------------------------------------------------------- /src/step-01-basic/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "basic", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-06-hooks/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "hooks", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-02-loaders/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "loaders", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-05-context/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "context", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-04-n+1/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "one-plus-n-problem", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-08-federation/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "federation", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-09-variables/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "variables", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-10-fragments/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "fragments", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /docker-compose.yml: -------------------------------------------------------------------------------- 1 | version: '3.6' 2 | services: 3 | postgres: 4 | image: postgres:alpine 5 | environment: 6 | POSTGRES_PASSWORD: postgres 7 | ports: 8 | - '5433:5432' 9 | -------------------------------------------------------------------------------- /src/step-07-error-handling/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "error-handling", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "executable-schema", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /src/step-08-federation/README.md: -------------------------------------------------------------------------------- 1 | # step-8 2 | 3 | ## Setup 4 | 5 | - start the server with `npm start` 6 | 7 | Server is running on port 4000 and http://localhost:4000/graphiql can be used to browse the federated schemas 8 | -------------------------------------------------------------------------------- /src/step-11-authorization/README.md: -------------------------------------------------------------------------------- 1 | # Step 11 2 | 3 | ## Setup 4 | 5 | - start the server with `npm start` 6 | 7 | Server is running on port 4000 and http://localhost:4000/graphiql can be used to browse the federated schemas 8 | -------------------------------------------------------------------------------- /.postgratorrc.json: -------------------------------------------------------------------------------- 1 | { 2 | "migrationPattern": "migrations/*", 3 | "driver": "pg", 4 | "host": "127.0.0.1", 5 | "port": 5433, 6 | "database": "postgres", 7 | "username": "postgres", 8 | "password": "postgres" 9 | } 10 | -------------------------------------------------------------------------------- /src/step-09-variables/graphql.js: -------------------------------------------------------------------------------- 1 | const schema = ` 2 | type Query { 3 | add(x: Int!, y: Int!): Int 4 | } 5 | ` 6 | 7 | const resolvers = { 8 | add: async ({ x, y }) => x + y 9 | } 10 | 11 | export { schema, resolvers } 12 | -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: npm 4 | directory: / 5 | schedule: 6 | interval: weekly 7 | - package-ecosystem: github-actions 8 | directory: / 9 | schedule: 10 | interval: weekly 11 | -------------------------------------------------------------------------------- /src/step-11-authorization/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "authorization", 3 | "type": "module", 4 | "scripts": { 5 | "start": "node server.js", 6 | "test": "node --test" 7 | }, 8 | "dependencies": { 9 | "mercurius-auth": "^6.0.0" 10 | } 11 | } 12 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/graphql.js: -------------------------------------------------------------------------------- 1 | const typeDefs = ` 2 | type Query { 3 | add(x: Int!, y: Int!): Int 4 | } 5 | ` 6 | 7 | const resolvers = { 8 | Query: { 9 | add: async (_, { x, y }) => x + y 10 | } 11 | } 12 | 13 | export { typeDefs, resolvers } 14 | -------------------------------------------------------------------------------- /src/step-01-basic/graphql.js: -------------------------------------------------------------------------------- 1 | const schema = ` 2 | type Query { 3 | add(x: Int!, y: Int!): Int 4 | } 5 | ` 6 | 7 | const resolvers = { 8 | Query: { 9 | add: async (_, obj) => { 10 | const { x, y } = obj 11 | return x + y 12 | } 13 | } 14 | } 15 | 16 | export { schema, resolvers } 17 | -------------------------------------------------------------------------------- /src/step-06-hooks/graphql.js: -------------------------------------------------------------------------------- 1 | const schema = ` 2 | type Query { 3 | add(x: Int!, y: Int!): Int 4 | } 5 | ` 6 | 7 | const resolvers = { 8 | Query: { 9 | add: async (_, obj) => { 10 | const { x, y } = obj 11 | return x + y 12 | } 13 | } 14 | } 15 | 16 | export { schema, resolvers } 17 | -------------------------------------------------------------------------------- /migrations/001.do.sql: -------------------------------------------------------------------------------- 1 | CREATE TABLE owners( 2 | id SERIAL PRIMARY KEY, 3 | name VARCHAR (50) NOT NULL 4 | ); 5 | 6 | CREATE TABLE pets( 7 | id SERIAL PRIMARY KEY, 8 | name VARCHAR (50) NOT NULL, 9 | owner INTEGER NOT NULL, 10 | CONSTRAINT fk_owner 11 | FOREIGN KEY(owner) 12 | REFERENCES owners(id) 13 | ); 14 | -------------------------------------------------------------------------------- /src/step-01-basic/README.md: -------------------------------------------------------------------------------- 1 | # step-1 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | add(x: 2, y: 2) 16 | } 17 | ``` 18 | -------------------------------------------------------------------------------- /src/step-06-hooks/README.md: -------------------------------------------------------------------------------- 1 | # step-6 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | add(x: 2, y: 2) 16 | } 17 | ``` 18 | -------------------------------------------------------------------------------- /src/step-04-n+1/lib/config.js: -------------------------------------------------------------------------------- 1 | import { join } from 'desm' 2 | import envSchema from 'env-schema' 3 | import S from 'fluent-json-schema' 4 | 5 | const schema = S.object().prop('PG_CONNECTION_STRING', S.string().required()) 6 | 7 | export default envSchema({ 8 | schema, 9 | dotenv: { path: join(import.meta.url, '../.env') } 10 | }) 11 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/README.md: -------------------------------------------------------------------------------- 1 | # step-3 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | add(x: 2, y: 2) 16 | } 17 | ``` 18 | -------------------------------------------------------------------------------- /src/step-05-context/README.md: -------------------------------------------------------------------------------- 1 | # step-5 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | getUserByLocale { 16 | name 17 | } 18 | } 19 | ``` 20 | -------------------------------------------------------------------------------- /src/step-07-error-handling/README.md: -------------------------------------------------------------------------------- 1 | # step-7 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | findUser(id: "5") { 16 | name 17 | } 18 | } 19 | ``` 20 | -------------------------------------------------------------------------------- /src/step-02-loaders/README.md: -------------------------------------------------------------------------------- 1 | # step-2 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | pets { 16 | owner { 17 | name 18 | } 19 | } 20 | } 21 | ``` 22 | -------------------------------------------------------------------------------- /src/step-04-n+1/README.md: -------------------------------------------------------------------------------- 1 | # step-4 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | pets { 16 | name 17 | owner { 18 | name 19 | } 20 | } 21 | } 22 | ``` 23 | -------------------------------------------------------------------------------- /src/step-09-variables/README.md: -------------------------------------------------------------------------------- 1 | # step-09 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | query AddQuery ($x: Int!, $y: Int!) { 15 | add(x: $x, y: $y) 16 | } 17 | ``` 18 | 19 | and with variables as: 20 | 21 | ```json 22 | { "x": 3, "y": 5 } 23 | ``` -------------------------------------------------------------------------------- /src/step-01-basic/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | graphiql: true 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-09-variables/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | graphiql: true 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-10-fragments/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | graphiql: true 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-07-error-handling/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | graphiql: true 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-08-federation/services/service.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import { mercuriusFederationPlugin } from '@mercuriusjs/federation' 3 | 4 | const createService = async (port, schema, resolvers) => { 5 | const service = Fastify() 6 | 7 | service.register(mercuriusFederationPlugin, { 8 | schema, 9 | resolvers, 10 | graphiql: true, 11 | jit: 1 12 | }) 13 | await service.listen({ port }) 14 | 15 | return service 16 | } 17 | 18 | export { createService } 19 | -------------------------------------------------------------------------------- /src/step-11-authorization/services/service.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import { mercuriusFederationPlugin } from '@mercuriusjs/federation' 3 | 4 | const createService = async (port, schema, resolvers) => { 5 | const service = Fastify() 6 | 7 | service.register(mercuriusFederationPlugin, { 8 | schema, 9 | resolvers, 10 | graphiql: true, 11 | jit: 1 12 | }) 13 | await service.listen({ port }) 14 | 15 | return service 16 | } 17 | 18 | export { createService } 19 | -------------------------------------------------------------------------------- /src/step-02-loaders/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers, loaders } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | loaders, 18 | graphiql: true 19 | }) 20 | 21 | return server 22 | } 23 | -------------------------------------------------------------------------------- /src/step-10-fragments/README.md: -------------------------------------------------------------------------------- 1 | # step-10 2 | 3 | ## Setup 4 | 5 | - start the server with `npm run start` 6 | 7 | Server is running on port 3000 8 | 9 | ## Running the example 10 | 11 | Send a graphQL request to http://localhost:3000/graphql with the following query: 12 | 13 | ```js 14 | { 15 | getNoviceUsers { 16 | ...userFields 17 | } 18 | getAdvancedUsers { 19 | ...userFields 20 | } 21 | } 22 | fragment userFields on User { 23 | id 24 | name 25 | age 26 | level 27 | } 28 | ``` 29 | -------------------------------------------------------------------------------- /src/step-08-federation/server.js: -------------------------------------------------------------------------------- 1 | import buildGateway from './index.js' 2 | import { createService } from './services/service.js' 3 | import { service1 } from './services/service1.js' 4 | import { service2 } from './services/service2.js' 5 | 6 | async function start() { 7 | await createService(4001, service1.schema, service1.resolvers) 8 | 9 | await createService(4002, service2.schema, service2.resolvers) 10 | 11 | const gateway = buildGateway() 12 | 13 | await gateway.listen({ port: 4000 }) 14 | } 15 | 16 | start() 17 | -------------------------------------------------------------------------------- /src/step-11-authorization/server.js: -------------------------------------------------------------------------------- 1 | import buildGateway from './index.js' 2 | import { createService } from './services/service.js' 3 | import { service1 } from './services/service1.js' 4 | import { service2 } from './services/service2.js' 5 | 6 | async function start() { 7 | await createService(4001, service1.schema, service1.resolvers) 8 | 9 | await createService(4002, service2.schema, service2.resolvers) 10 | 11 | const gateway = buildGateway() 12 | 13 | await gateway.listen({ port: 4000 }) 14 | } 15 | 16 | start() 17 | -------------------------------------------------------------------------------- /src/step-05-context/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.register(mercurius, { 15 | schema, 16 | resolvers, 17 | context: () => ({ 18 | locale: 'en' 19 | }), 20 | graphiql: true 21 | }) 22 | 23 | return server 24 | } 25 | -------------------------------------------------------------------------------- /src/step-08-federation/services/service1.js: -------------------------------------------------------------------------------- 1 | import { users } from '../data.js' 2 | 3 | const service1 = { 4 | schema: ` 5 | extend type Query { 6 | me: User 7 | } 8 | 9 | type User @key(fields: "id") { 10 | id: ID! 11 | name: String! 12 | } 13 | `, 14 | 15 | resolvers: { 16 | Query: { 17 | me: () => { 18 | return users.u1 19 | } 20 | }, 21 | User: { 22 | __resolveReference: user => { 23 | return users[user.id] 24 | } 25 | } 26 | } 27 | } 28 | 29 | export { service1 } 30 | -------------------------------------------------------------------------------- /src/step-04-n+1/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import config from './lib/config.js' 4 | import { schema, resolvers, loaders } from './graphql.js' 5 | 6 | export default function buildServer() { 7 | const server = Fastify(config) 8 | 9 | server.register(import('@fastify/postgres'), { 10 | connectionString: config.PG_CONNECTION_STRING 11 | }) 12 | 13 | server.register(mercurius, { 14 | schema, 15 | resolvers, 16 | loaders, 17 | graphiql: true 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { makeExecutableSchema } from '@graphql-tools/schema' 4 | 5 | import { typeDefs, resolvers } from './graphql.js' 6 | 7 | export default function buildServer() { 8 | const server = Fastify({ 9 | logger: { 10 | transport: { 11 | target: 'pino-pretty' 12 | } 13 | } 14 | }) 15 | 16 | server.register(mercurius, { 17 | schema: makeExecutableSchema({ typeDefs, resolvers }) 18 | }) 19 | 20 | return server 21 | } 22 | -------------------------------------------------------------------------------- /src/step-04-n+1/lib/db.js: -------------------------------------------------------------------------------- 1 | import SQL from '@nearform/sql' 2 | 3 | export async function loadPets(db) { 4 | const { rows } = await db.query('SELECT * FROM pets') 5 | 6 | return rows 7 | } 8 | 9 | export async function ownersByPetNames(db, petNames) { 10 | const { rows } = await db.query( 11 | SQL` 12 | SELECT owners.* 13 | FROM owners 14 | INNER JOIN pets 15 | ON pets.owner = owners.id 16 | AND pets.name = ANY(${petNames}) 17 | ORDER BY 18 | ARRAY_POSITION((${petNames}), pets.name)` 19 | ) 20 | 21 | return rows 22 | } 23 | -------------------------------------------------------------------------------- /.github/workflows/check-linked-issues.yml: -------------------------------------------------------------------------------- 1 | name: Check Linked Issues 2 | 'on': 3 | pull_request_target: 4 | types: 5 | - opened 6 | - edited 7 | - reopened 8 | - synchronize 9 | jobs: 10 | check_pull_requests: 11 | runs-on: ubuntu-latest 12 | name: Check linked issues 13 | steps: 14 | - uses: nearform-actions/github-action-check-linked-issues@v1 15 | with: 16 | github-token: ${{ secrets.GITHUB_TOKEN }} 17 | exclude-branches: release/**, dependabot/** 18 | permissions: 19 | issues: read 20 | pull-requests: write 21 | -------------------------------------------------------------------------------- /src/step-06-hooks/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercurius from 'mercurius' 3 | import { schema, resolvers } from './graphql.js' 4 | 5 | export default function buildServer() { 6 | const server = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | server.get('/', async function (req, reply) { 15 | const query = '{ add(x: 2, y: 2) }' 16 | return reply.graphql(query) 17 | }) 18 | 19 | server.register(mercurius, { 20 | schema, 21 | resolvers, 22 | graphiql: true 23 | }) 24 | 25 | return server 26 | } 27 | -------------------------------------------------------------------------------- /src/step-05-context/graphql.js: -------------------------------------------------------------------------------- 1 | const users = [ 2 | { 3 | id: 1, 4 | name: 'Alice', 5 | locale: 'en' 6 | }, 7 | { 8 | id: 2, 9 | name: 'Bob', 10 | locale: 'de' 11 | }, 12 | { 13 | id: 3, 14 | name: 'Johnny', 15 | locale: 'da' 16 | } 17 | ] 18 | 19 | const schema = ` 20 | type User { 21 | id: Int! 22 | name: String! 23 | } 24 | 25 | type Query { 26 | getUserByLocale: User 27 | } 28 | ` 29 | 30 | const resolvers = { 31 | Query: { 32 | getUserByLocale(_, __, context) { 33 | return users.find(u => u.locale === context.locale) 34 | } 35 | } 36 | } 37 | 38 | export { schema, resolvers } 39 | -------------------------------------------------------------------------------- /src/step-11-authorization/services/service1.js: -------------------------------------------------------------------------------- 1 | import { users } from '../data.js' 2 | 3 | const service1 = { 4 | schema: ` 5 | enum Role { 6 | ADMIN 7 | VERIFIED 8 | } 9 | 10 | directive @auth(role: Role) on OBJECT | FIELD_DEFINITION 11 | 12 | extend type Query { 13 | me: User @auth(role: VERIFIED) 14 | } 15 | 16 | type User @key(fields: "id") { 17 | id: ID! 18 | name: String! 19 | } 20 | `, 21 | 22 | resolvers: { 23 | Query: { 24 | me: () => { 25 | return users.u1 26 | } 27 | }, 28 | User: { 29 | __resolveReference: user => { 30 | return users[user.id] 31 | } 32 | } 33 | } 34 | } 35 | 36 | export { service1 } 37 | -------------------------------------------------------------------------------- /src/step-04-n+1/graphql.js: -------------------------------------------------------------------------------- 1 | import { loadPets, ownersByPetNames } from './lib/db.js' 2 | 3 | const schema = ` 4 | type Person { 5 | name: String! 6 | } 7 | 8 | type Pet { 9 | name: String! 10 | owner: Person 11 | } 12 | 13 | type Query { 14 | pets: [Pet] 15 | } 16 | ` 17 | 18 | const resolvers = { 19 | Query: { 20 | pets(_, __, context) { 21 | return loadPets(context.app.pg) 22 | } 23 | } 24 | } 25 | 26 | const loaders = { 27 | Pet: { 28 | async owner(queries, context) { 29 | const petNames = queries.map(({ obj }) => obj.name) 30 | return ownersByPetNames(context.app.pg, petNames) 31 | } 32 | } 33 | } 34 | 35 | export { schema, resolvers, loaders } 36 | -------------------------------------------------------------------------------- /src/step-08-federation/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercuriusGateway from '@mercuriusjs/gateway' 3 | 4 | export default function buildGateway() { 5 | const gateway = Fastify({ 6 | logger: { 7 | transport: { 8 | target: 'pino-pretty' 9 | } 10 | } 11 | }) 12 | 13 | gateway.register(mercuriusGateway, { 14 | graphiql: true, 15 | jit: 1, 16 | gateway: { 17 | services: [ 18 | { 19 | name: 'user', 20 | url: 'http://localhost:4001/graphql' 21 | }, 22 | { 23 | name: 'post', 24 | url: 'http://localhost:4002/graphql' 25 | } 26 | ] 27 | } 28 | }) 29 | 30 | return gateway 31 | } 32 | -------------------------------------------------------------------------------- /src/step-01-basic/test/basic.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should return sum of two numbers', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { add(x: 3, y:5) }` 11 | 12 | const response = await server.inject({ 13 | method: 'POST', 14 | headers: { 'content-type': 'application/json' }, 15 | url: '/graphql', 16 | payload: JSON.stringify({ query }) 17 | }) 18 | 19 | assert.equal(response.statusCode, 200) 20 | 21 | const { data, errors } = await response.json() 22 | 23 | assert.equal(errors, undefined) 24 | assert.deepStrictEqual(data, { 25 | add: 8 26 | }) 27 | }) 28 | -------------------------------------------------------------------------------- /src/step-08-federation/services/service2.js: -------------------------------------------------------------------------------- 1 | import { posts } from '../data.js' 2 | 3 | const service2 = { 4 | schema: ` 5 | type Post @key(fields: "id") { 6 | id: ID! 7 | title: String 8 | content: String 9 | author: User 10 | } 11 | 12 | type User @key(fields: "id") @extends { 13 | id: ID! @external 14 | name: String @external 15 | posts: [Post] 16 | } 17 | `, 18 | resolvers: { 19 | Post: { 20 | author: post => { 21 | return { 22 | __typename: 'User', 23 | id: post.authorId 24 | } 25 | } 26 | }, 27 | User: { 28 | posts: user => { 29 | return Object.values(posts).filter(p => p.authorId === user.id) 30 | } 31 | } 32 | } 33 | } 34 | 35 | export { service2 } 36 | -------------------------------------------------------------------------------- /src/step-03-executable-schema/test/schema.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should return sum of two numbers', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { add(x: 3, y:5) }` 11 | 12 | const response = await server.inject({ 13 | method: 'POST', 14 | headers: { 'content-type': 'application/json' }, 15 | url: '/graphql', 16 | payload: JSON.stringify({ query }) 17 | }) 18 | 19 | assert.equal(response.statusCode, 200) 20 | 21 | const { data, errors } = await response.json() 22 | 23 | assert.equal(errors, undefined) 24 | assert.deepStrictEqual(data, { 25 | add: 8 26 | }) 27 | }) 28 | -------------------------------------------------------------------------------- /src/step-08-federation/data.js: -------------------------------------------------------------------------------- 1 | const users = { 2 | u1: { 3 | id: 'u1', 4 | name: 'John' 5 | }, 6 | u2: { 7 | id: 'u2', 8 | name: 'Jane' 9 | }, 10 | u3: { 11 | id: 'u3', 12 | name: 'Jack' 13 | } 14 | } 15 | 16 | const posts = { 17 | p1: { 18 | id: 'p1', 19 | title: 'Post 1', 20 | content: 'Content 1', 21 | authorId: 'u1' 22 | }, 23 | p2: { 24 | id: 'p2', 25 | title: 'Post 2', 26 | content: 'Content 2', 27 | authorId: 'u2' 28 | }, 29 | p3: { 30 | id: 'p3', 31 | title: 'Post 3', 32 | content: 'Content 3', 33 | authorId: 'u1' 34 | }, 35 | p4: { 36 | id: 'p4', 37 | title: 'Post 4', 38 | content: 'Content 4', 39 | authorId: 'u2' 40 | } 41 | } 42 | 43 | export { users, posts } 44 | -------------------------------------------------------------------------------- /src/step-11-authorization/data.js: -------------------------------------------------------------------------------- 1 | const users = { 2 | u1: { 3 | id: 'u1', 4 | name: 'John' 5 | }, 6 | u2: { 7 | id: 'u2', 8 | name: 'Jane' 9 | }, 10 | u3: { 11 | id: 'u3', 12 | name: 'Jack' 13 | } 14 | } 15 | 16 | const posts = { 17 | p1: { 18 | id: 'p1', 19 | title: 'Post 1', 20 | content: 'Content 1', 21 | authorId: 'u1' 22 | }, 23 | p2: { 24 | id: 'p2', 25 | title: 'Post 2', 26 | content: 'Content 2', 27 | authorId: 'u2' 28 | }, 29 | p3: { 30 | id: 'p3', 31 | title: 'Post 3', 32 | content: 'Content 3', 33 | authorId: 'u1' 34 | }, 35 | p4: { 36 | id: 'p4', 37 | title: 'Post 4', 38 | content: 'Content 4', 39 | authorId: 'u2' 40 | } 41 | } 42 | 43 | export { users, posts } 44 | -------------------------------------------------------------------------------- /src/step-02-loaders/graphql.js: -------------------------------------------------------------------------------- 1 | const pets = [ 2 | { 3 | name: 'Max' 4 | }, 5 | { 6 | name: 'Charlie' 7 | } 8 | ] 9 | 10 | const owners = { 11 | Max: { 12 | name: 'Jennifer' 13 | }, 14 | Charlie: { 15 | name: 'Simon' 16 | } 17 | } 18 | 19 | const schema = ` 20 | type Person { 21 | name: String! 22 | } 23 | 24 | type Pet { 25 | name: String! 26 | owner: Person 27 | } 28 | 29 | type Query { 30 | pets: [Pet] 31 | } 32 | ` 33 | 34 | const resolvers = { 35 | Query: { 36 | pets() { 37 | return pets 38 | } 39 | } 40 | } 41 | 42 | const loaders = { 43 | Pet: { 44 | async owner(queries) { 45 | return queries.map(({ obj: pet }) => owners[pet.name]) 46 | } 47 | } 48 | } 49 | 50 | export { schema, resolvers, loaders } 51 | -------------------------------------------------------------------------------- /src/step-07-error-handling/graphql.js: -------------------------------------------------------------------------------- 1 | import mercurius from 'mercurius' 2 | const { ErrorWithProps } = mercurius 3 | 4 | const users = { 5 | 1: { 6 | id: '1', 7 | name: 'John' 8 | }, 9 | 2: { 10 | id: '2', 11 | name: 'Jane' 12 | } 13 | } 14 | 15 | const schema = ` 16 | type Query { 17 | findUser(id: String!): User 18 | } 19 | 20 | type User { 21 | id: ID! 22 | name: String 23 | } 24 | ` 25 | 26 | const resolvers = { 27 | Query: { 28 | findUser: (_, { id }) => { 29 | const user = users[id] 30 | 31 | if (user) { 32 | return users[id] 33 | } 34 | 35 | throw new ErrorWithProps('Invalid User ID', { 36 | id, 37 | code: 'USER_ID_INVALID' 38 | }) 39 | } 40 | } 41 | } 42 | 43 | export { schema, resolvers } 44 | -------------------------------------------------------------------------------- /src/step-10-fragments/graphql.js: -------------------------------------------------------------------------------- 1 | const users = [ 2 | { 3 | id: 1, 4 | name: 'John Doe', 5 | age: 32, 6 | level: 'novice' 7 | }, 8 | { 9 | id: 2, 10 | name: 'Jane Doe', 11 | age: 28, 12 | level: 'advanced' 13 | } 14 | ] 15 | 16 | const schema = ` 17 | type User { 18 | id: Int! 19 | name: String! 20 | age: Int! 21 | level: String! 22 | } 23 | 24 | type Query { 25 | getNoviceUsers: [User] 26 | getAdvancedUsers: [User] 27 | } 28 | ` 29 | 30 | const resolvers = { 31 | Query: { 32 | getNoviceUsers() { 33 | return users.filter(user => user.level === 'novice') 34 | }, 35 | getAdvancedUsers() { 36 | return users.filter(user => user.level === 'advanced') 37 | } 38 | } 39 | } 40 | 41 | export { schema, resolvers } 42 | -------------------------------------------------------------------------------- /src/step-06-hooks/server.js: -------------------------------------------------------------------------------- 1 | 'use strict' 2 | 3 | import buildServer from './index.js' 4 | 5 | async function start() { 6 | const app = buildServer() 7 | 8 | await app.ready() 9 | 10 | app.graphql.addHook('preParsing', async function () { 11 | app.log.info('preParsing called') 12 | }) 13 | 14 | app.graphql.addHook('preValidation', async function () { 15 | app.log.info('preValidation called') 16 | }) 17 | 18 | app.graphql.addHook('preExecution', async function (schema, document) { 19 | app.log.info('preExecution called') 20 | return { 21 | document, 22 | errors: [new Error('foo')] 23 | } 24 | }) 25 | 26 | app.graphql.addHook('onResolution', async function () { 27 | app.log.info('onResolution called') 28 | }) 29 | 30 | app.listen({ port: 3000 }) 31 | } 32 | 33 | start() 34 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: deploy 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | 8 | permissions: 9 | contents: write 10 | 11 | jobs: 12 | deploy: 13 | runs-on: ubuntu-latest 14 | steps: 15 | - uses: actions/checkout@v6 16 | - uses: actions/setup-node@v6 17 | with: 18 | node-version-file: .nvmrc 19 | # We do install instead of ci due to a bug in npm that doesn't 20 | # properly handle optional dependencies in the lockfile when doing 21 | # cross platform installs 22 | # https://github.com/nearform/the-graphql-workshop/pull/742 23 | - run: npm install 24 | - run: npm run build -- --base /the-graphql-workshop/ 25 | - uses: peaceiris/actions-gh-pages@v4 26 | with: 27 | github_token: ${{ secrets.GITHUB_TOKEN }} 28 | publish_dir: dist 29 | -------------------------------------------------------------------------------- /src/step-05-context/test/context.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should retrieve correct value from context', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { 11 | getUserByLocale { 12 | name 13 | } 14 | }` 15 | 16 | const response = await server.inject({ 17 | method: 'POST', 18 | headers: { 'content-type': 'application/json' }, 19 | url: '/graphql', 20 | payload: JSON.stringify({ query }) 21 | }) 22 | 23 | assert.equal(response.statusCode, 200) 24 | 25 | const { data, errors } = await response.json() 26 | 27 | assert.equal(errors, undefined) 28 | assert.deepStrictEqual(data, { 29 | getUserByLocale: { 30 | name: 'Alice' 31 | } 32 | }) 33 | }) 34 | -------------------------------------------------------------------------------- /src/step-11-authorization/services/service2.js: -------------------------------------------------------------------------------- 1 | import { posts } from '../data.js' 2 | 3 | const service2 = { 4 | schema: ` 5 | enum Role { 6 | ADMIN 7 | VERIFIED 8 | } 9 | 10 | directive @auth(role: Role) on OBJECT | FIELD_DEFINITION 11 | 12 | type Post @key(fields: "id") { 13 | id: ID! 14 | title: String 15 | content: String 16 | author: User @auth(role: ADMIN) 17 | } 18 | 19 | type User @key(fields: "id") @extends { 20 | id: ID! @external 21 | name: String @external 22 | posts: [Post] 23 | }`, 24 | resolvers: { 25 | Post: { 26 | author: post => { 27 | return { 28 | __typename: 'User', 29 | id: post.authorId 30 | } 31 | } 32 | }, 33 | User: { 34 | posts: user => { 35 | return Object.values(posts).filter(p => p.authorId === user.id) 36 | } 37 | } 38 | } 39 | } 40 | 41 | export { service2 } 42 | -------------------------------------------------------------------------------- /src/step-09-variables/test/variables.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should accept parameters as variables and return sum of two numbers', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const response = await server.inject({ 11 | method: 'POST', 12 | headers: { 'content-type': 'application/json' }, 13 | url: '/graphql', 14 | payload: { 15 | operationName: 'AddQuery', 16 | variables: { x: 3, y: 5 }, 17 | query: ` 18 | query AddQuery ($x: Int!, $y: Int!) { 19 | add(x: $x, y: $y) 20 | }` 21 | } 22 | }) 23 | 24 | assert.equal(response.statusCode, 200) 25 | 26 | const { data, errors } = await response.json() 27 | 28 | assert.equal(errors, undefined) 29 | assert.deepStrictEqual(data, { 30 | add: 8 31 | }) 32 | }) 33 | -------------------------------------------------------------------------------- /eslint.config.mjs: -------------------------------------------------------------------------------- 1 | import { defineConfig, globalIgnores } from 'eslint/config' 2 | import globals from 'globals' 3 | import path from 'node:path' 4 | import { fileURLToPath } from 'node:url' 5 | import js from '@eslint/js' 6 | import { FlatCompat } from '@eslint/eslintrc' 7 | 8 | const __filename = fileURLToPath(import.meta.url) 9 | const __dirname = path.dirname(__filename) 10 | const compat = new FlatCompat({ 11 | baseDirectory: __dirname, 12 | recommendedConfig: js.configs.recommended, 13 | allConfig: js.configs.all 14 | }) 15 | 16 | export default defineConfig([ 17 | globalIgnores([ 18 | '**/coverage/', 19 | '**/node_modules/', 20 | '**/dist/', 21 | '**/public/', 22 | '**/migrations/', 23 | '**/theme/' 24 | ]), 25 | { 26 | extends: compat.extends( 27 | 'eslint:recommended', 28 | 'plugin:prettier/recommended' 29 | ), 30 | 31 | languageOptions: { 32 | globals: { 33 | ...globals.node 34 | }, 35 | 36 | ecmaVersion: 2020, 37 | sourceType: 'module' 38 | } 39 | } 40 | ]) 41 | -------------------------------------------------------------------------------- /styles.css: -------------------------------------------------------------------------------- 1 | img { 2 | width: 100%; 3 | } 4 | 5 | #slide-empty-center-page { 6 | text-align: center; 7 | } 8 | 9 | #slide-empty-center-page img { 10 | width: 50%; 11 | } 12 | 13 | #slide-using-inspector p img { 14 | width: 80%; 15 | } 16 | 17 | #slide-clinic p { 18 | text-align: center; 19 | } 20 | 21 | #slide-clinic p img { 22 | width: 50% !important; 23 | } 24 | 25 | #slide-deopt p { 26 | text-align: center; 27 | } 28 | 29 | #slide-deopt p img { 30 | width: 90%; 31 | } 32 | 33 | .no-border h1 { 34 | border-bottom: none; 35 | padding-top: 20%; 36 | text-align: center; 37 | } 38 | 39 | ul, 40 | ol { 41 | font-size: 1.3rem; 42 | } 43 | 44 | .remark-code-line { 45 | font-size: 0.8rem; 46 | } 47 | 48 | #slide-clinic-flame-img img, 49 | #slide-clinic-flame-img-zoomed img { 50 | height: 80%; 51 | } 52 | 53 | #slide-shapes-image img, 54 | #slide-shapes-transitions-image img { 55 | height: 25rem; 56 | } 57 | 58 | .slidev-layout { 59 | display: flex; 60 | flex-direction: column; 61 | } 62 | .slidev-code-wrapper { 63 | overflow-y: auto; 64 | } 65 | -------------------------------------------------------------------------------- /src/step-04-n+1/test/n+1.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should return owner of the pet', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { 11 | pets { 12 | name 13 | owner { 14 | name 15 | } 16 | } 17 | }` 18 | 19 | const response = await server.inject({ 20 | method: 'POST', 21 | headers: { 'content-type': 'application/json' }, 22 | url: '/graphql', 23 | payload: JSON.stringify({ query }) 24 | }) 25 | 26 | assert.equal(response.statusCode, 200) 27 | 28 | const { data, errors } = await response.json() 29 | 30 | assert.equal(errors, undefined) 31 | assert.deepStrictEqual(data, { 32 | pets: [ 33 | { 34 | name: 'Max', 35 | owner: { 36 | name: 'Simon' 37 | } 38 | }, 39 | { 40 | name: 'Charlie', 41 | owner: { 42 | name: 'Jennifer' 43 | } 44 | } 45 | ] 46 | }) 47 | }) 48 | -------------------------------------------------------------------------------- /src/step-02-loaders/test/loaders.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should return owner of the pet ', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { 11 | pets { 12 | name 13 | owner { 14 | name 15 | } 16 | } 17 | }` 18 | 19 | const response = await server.inject({ 20 | method: 'POST', 21 | headers: { 'content-type': 'application/json' }, 22 | url: '/graphql', 23 | payload: JSON.stringify({ query }) 24 | }) 25 | 26 | assert.equal(response.statusCode, 200) 27 | 28 | const { data, errors } = await response.json() 29 | 30 | assert.equal(errors, undefined) 31 | assert.deepStrictEqual(data, { 32 | pets: [ 33 | { 34 | name: 'Max', 35 | owner: { 36 | name: 'Jennifer' 37 | } 38 | }, 39 | { 40 | name: 'Charlie', 41 | owner: { 42 | name: 'Simon' 43 | } 44 | } 45 | ] 46 | }) 47 | }) 48 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The GraphQL Workshop 2 | 3 | [![ci](https://github.com/nearform/the-graphql-workshop/actions/workflows/ci.yml/badge.svg)](https://github.com/nearform/the-graphql-workshop/actions/workflows/ci.yml) 4 | [![deploy](https://github.com/nearform/the-graphql-workshop/actions/workflows/deploy.yml/badge.svg)](https://github.com/nearform/the-graphql-workshop/actions/workflows/deploy.yml) 5 | 6 | A step by step guide to implement a GraphQL server with Fastify and Mercurius. 7 | 8 | ## Slideshow Presentation 9 | 10 | [The GraphQL Workshop Slides](https://nearform.github.io/the-graphql-workshop) 11 | 12 | ## Requirements 13 | 14 | - Node LTS 15 | - docker 16 | - docker-compose 17 | 18 | ## Setup 19 | 20 | - `npm ci` 21 | - `npm run db:up` 22 | - `npm run db:migrate` 23 | 24 | ### Run automated tests 25 | 26 | - `npm test --workspaces` 27 | 28 | #### Run automated tests on a single project 29 | 30 | - `npm test -w src/step-05-context` 31 | 32 | ## Running the modules 33 | 34 | - `cd src/step-{n}-{name}` 35 | - check each module's README file to see which scripts are available 36 | 37 | ## Presenting 38 | 39 | - `npm start` 40 | -------------------------------------------------------------------------------- /src/step-11-authorization/index.js: -------------------------------------------------------------------------------- 1 | import Fastify from 'fastify' 2 | import mercuriusGateway from '@mercuriusjs/gateway' 3 | import mercuriusAuth from 'mercurius-auth' 4 | 5 | export default function buildGateway() { 6 | const gateway = Fastify({ 7 | logger: { 8 | transport: { 9 | target: 'pino-pretty' 10 | } 11 | } 12 | }) 13 | 14 | gateway.register(mercuriusGateway, { 15 | graphiql: true, 16 | jit: 1, 17 | gateway: { 18 | services: [ 19 | { 20 | name: 'user', 21 | url: 'http://localhost:4001/graphql' 22 | }, 23 | { 24 | name: 'post', 25 | url: 'http://localhost:4002/graphql' 26 | } 27 | ] 28 | } 29 | }) 30 | 31 | gateway.register(mercuriusAuth, { 32 | authContext(context) { 33 | return { 34 | role: context.reply.request.headers['x-role'] 35 | } 36 | }, 37 | async applyPolicy(authDirectiveAST, parent, args, context) { 38 | const directiveRole = authDirectiveAST.arguments.find( 39 | arg => arg.name.value === 'role' 40 | ).value.value 41 | 42 | return ( 43 | context.auth.role === directiveRole || context.auth.role === 'ADMIN' 44 | ) 45 | }, 46 | authDirective: 'auth' 47 | }) 48 | 49 | return gateway 50 | } 51 | -------------------------------------------------------------------------------- /src/step-10-fragments/test/fragments.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should use fragments and return users correctly', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `{ 11 | getNoviceUsers { 12 | ...userFields 13 | } 14 | getAdvancedUsers { 15 | ...userFields 16 | } 17 | } 18 | fragment userFields on User { 19 | id 20 | name 21 | age 22 | level 23 | }` 24 | 25 | const response = await server.inject({ 26 | method: 'POST', 27 | headers: { 'content-type': 'application/json' }, 28 | url: '/graphql', 29 | payload: JSON.stringify({ query }) 30 | }) 31 | 32 | assert.equal(response.statusCode, 200) 33 | 34 | const { data, errors } = await response.json() 35 | 36 | assert.equal(errors, undefined) 37 | assert.deepStrictEqual(data, { 38 | getNoviceUsers: [ 39 | { 40 | id: 1, 41 | name: 'John Doe', 42 | age: 32, 43 | level: 'novice' 44 | } 45 | ], 46 | getAdvancedUsers: [ 47 | { 48 | id: 2, 49 | name: 'Jane Doe', 50 | age: 28, 51 | level: 'advanced' 52 | } 53 | ] 54 | }) 55 | }) 56 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "the-graphql-workshop", 3 | "private": true, 4 | "type": "module", 5 | "workspaces": [ 6 | "src/*" 7 | ], 8 | "version": "1.0.0", 9 | "license": "CC-BY-SA-4.0", 10 | "author": "Sameer Srivastava ", 11 | "contributors": [ 12 | "Simone Busoli " 13 | ], 14 | "scripts": { 15 | "build": "slidev build", 16 | "start": "slidev --open", 17 | "export": "slidev export", 18 | "db:up": "docker compose up -d", 19 | "db:migrate": "postgrator", 20 | "db:down": "docker compose down", 21 | "lint": "eslint .", 22 | "test": "node --test --test-concurrency 1" 23 | }, 24 | "devDependencies": { 25 | "eslint": "^9.39.2", 26 | "eslint-config-prettier": "^10.1.8", 27 | "eslint-plugin-prettier": "^5.5.4", 28 | "prettier": "^3.7.4" 29 | }, 30 | "dependencies": { 31 | "@fastify/postgres": "^6.0.2", 32 | "@graphql-tools/schema": "^10.0.30", 33 | "@mercuriusjs/federation": "^5.0.0", 34 | "@mercuriusjs/gateway": "^5.0.0", 35 | "@nearform/sql": "^1.10.7", 36 | "@slidev/cli": "^52.11.0", 37 | "@slidev/theme-default": "^0.25.0", 38 | "@vueuse/shared": "^14.1.0", 39 | "desm": "^1.3.1", 40 | "env-schema": "^7.0.0", 41 | "fastify": "^5.6.2", 42 | "fluent-json-schema": "^6.0.0", 43 | "graphql": "^16.12.0", 44 | "mercurius": "^16.6.0", 45 | "pg": "^8.16.3", 46 | "pino-pretty": "^13.1.3", 47 | "postgrator-cli": "^9.1.0", 48 | "slidev-theme-nearform": "^2.1.0" 49 | } 50 | } 51 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | 3 | on: 4 | pull_request: 5 | branches: 6 | - master 7 | push: 8 | branches: 9 | - master 10 | 11 | jobs: 12 | build_linux: 13 | runs-on: ubuntu-latest 14 | 15 | services: 16 | postgres: 17 | image: postgres:alpine 18 | env: 19 | POSTGRES_PASSWORD: postgres 20 | ports: 21 | - 5433:5432 22 | options: >- 23 | --health-cmd pg_isready 24 | --health-interval 10s 25 | --health-timeout 5s 26 | --health-retries 5 27 | steps: 28 | - uses: actions/checkout@v6 29 | - uses: actions/setup-node@v6 30 | with: 31 | node-version-file: .nvmrc 32 | - run: npm ci 33 | - run: npm run lint 34 | - run: npm run db:migrate 35 | - run: npm test 36 | 37 | build_windows: 38 | runs-on: windows-latest 39 | steps: 40 | - name: Setup PostgreSQL for Linux/macOS/Windows 41 | uses: ikalnytskyi/action-setup-postgres@v8 42 | id: postgres 43 | with: 44 | port: 5433 45 | - uses: actions/checkout@v6 46 | - uses: actions/setup-node@v6 47 | with: 48 | node-version-file: .nvmrc 49 | - run: npm ci 50 | - run: npm run db:migrate 51 | - run: npm test 52 | 53 | automerge: 54 | needs: [build_linux, build_windows] 55 | runs-on: ubuntu-latest 56 | permissions: 57 | pull-requests: write 58 | contents: write 59 | steps: 60 | - uses: fastify/github-action-merge-dependabot@v3 61 | -------------------------------------------------------------------------------- /src/step-07-error-handling/test/errors.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import buildServer from '../index.js' 4 | 5 | test('should throw error with proper message and code if user not found', async () => { 6 | const server = buildServer() 7 | 8 | await server.ready() 9 | 10 | const query = `query { 11 | findUser(id: "5") { 12 | name 13 | } 14 | }` 15 | 16 | const response = await server.inject({ 17 | method: 'POST', 18 | headers: { 'content-type': 'application/json' }, 19 | url: '/graphql', 20 | payload: JSON.stringify({ query }) 21 | }) 22 | 23 | assert.equal(response.statusCode, 200) 24 | 25 | const { errors } = await response.json() 26 | 27 | assert.equal(errors.length, 1) 28 | assert.deepStrictEqual(errors, [ 29 | { 30 | message: 'Invalid User ID', 31 | locations: [ 32 | { 33 | line: 2, 34 | column: 5 35 | } 36 | ], 37 | path: ['findUser'], 38 | extensions: { 39 | id: '5', 40 | code: 'USER_ID_INVALID' 41 | } 42 | } 43 | ]) 44 | }) 45 | 46 | test('should return user', async () => { 47 | const server = buildServer() 48 | 49 | const query = `query { 50 | findUser(id: "1") { 51 | name 52 | } 53 | }` 54 | 55 | const response = await server.inject({ 56 | method: 'POST', 57 | headers: { 'content-type': 'application/json' }, 58 | url: '/graphql', 59 | payload: JSON.stringify({ query }) 60 | }) 61 | 62 | assert.equal(response.statusCode, 200) 63 | 64 | const { data, errors } = await response.json() 65 | 66 | assert.equal(errors, undefined) 67 | assert.deepStrictEqual(data, { 68 | findUser: { 69 | name: 'John' 70 | } 71 | }) 72 | }) 73 | -------------------------------------------------------------------------------- /src/step-06-hooks/test/hooks.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import { parse, GraphQLSchema } from 'graphql' 3 | import buildServer from '../index.js' 4 | 5 | const query = '{ add(x: 3, y: 5) }' 6 | 7 | test('hooks', async t => { 8 | t.plan(17) 9 | const server = buildServer() 10 | 11 | await server.ready() 12 | 13 | server.graphql.addHook( 14 | 'preParsing', 15 | async function (schema, source, context) { 16 | t.assert.ok(schema instanceof GraphQLSchema) 17 | t.assert.equal(source, query) 18 | t.assert.equal(typeof context, 'object') 19 | t.assert.ok('preParsing called') 20 | } 21 | ) 22 | 23 | server.graphql.addHook( 24 | 'preValidation', 25 | async function (schema, document, context) { 26 | t.assert.ok(schema instanceof GraphQLSchema) 27 | 28 | t.assert.deepEqual(document, parse(query)) 29 | t.assert.equal(typeof context, 'object') 30 | t.assert.ok('preValidation called') 31 | } 32 | ) 33 | 34 | server.graphql.addHook( 35 | 'preExecution', 36 | async function (schema, document, context) { 37 | t.assert.ok(schema instanceof GraphQLSchema) 38 | t.assert.deepEqual(document, parse(query)) 39 | t.assert.equal(typeof context, 'object') 40 | t.assert.ok('preExecution called') 41 | } 42 | ) 43 | 44 | server.graphql.addHook('onResolution', async function (execution, context) { 45 | t.assert.equal(typeof execution, 'object') 46 | t.assert.equal(typeof context, 'object') 47 | t.assert.ok('onResolution called') 48 | }) 49 | 50 | const response = await server.inject({ 51 | method: 'POST', 52 | headers: { 'content-type': 'application/json' }, 53 | url: '/graphql', 54 | payload: JSON.stringify({ query }) 55 | }) 56 | 57 | const { data, errors } = await response.json() 58 | 59 | t.assert.equal(errors, undefined) 60 | t.assert.deepStrictEqual(data, { 61 | add: 8 62 | }) 63 | }) 64 | 65 | test('GET /', async t => { 66 | const server = buildServer() 67 | const response = await server.inject({ 68 | method: 'GET', 69 | url: '/' 70 | }) 71 | 72 | const { data, errors } = await response.json() 73 | 74 | t.assert.equal(errors, undefined) 75 | t.assert.deepStrictEqual(data, { 76 | add: 4 77 | }) 78 | }) 79 | -------------------------------------------------------------------------------- /src/step-08-federation/test/federation.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import { createService } from '../services/service.js' 4 | import { service1 } from '../services/service1.js' 5 | import { service2 } from '../services/service2.js' 6 | import buildGateway from '../index.js' 7 | 8 | let userService 9 | let postService 10 | let gateway 11 | 12 | test.before(async () => { 13 | userService = await createService(4001, service1.schema, service1.resolvers) 14 | postService = await createService(4002, service2.schema, service2.resolvers) 15 | gateway = buildGateway() 16 | }) 17 | 18 | test.after(async () => { 19 | await gateway.close() 20 | await postService.close() 21 | await userService.close() 22 | }) 23 | 24 | test('Runs in gateway mode with two services ', async () => { 25 | const query = ` 26 | query { 27 | me { 28 | id 29 | name 30 | posts { 31 | ...PostFragment 32 | } 33 | } 34 | } 35 | fragment UserFragment on User { 36 | id 37 | name 38 | } 39 | fragment PostFragment on Post { 40 | id 41 | title 42 | content 43 | ...AuthorFragment 44 | } 45 | 46 | fragment AuthorFragment on Post { 47 | author { 48 | ...UserFragment 49 | } 50 | }` 51 | const res = await gateway.inject({ 52 | method: 'POST', 53 | headers: { 54 | 'content-type': 'application/json', 55 | authorization: 'bearer supersecret' 56 | }, 57 | url: '/graphql', 58 | payload: JSON.stringify({ 59 | query, 60 | variables: { 61 | count: 1 62 | } 63 | }) 64 | }) 65 | 66 | assert.deepEqual(JSON.parse(res.body), { 67 | data: { 68 | me: { 69 | id: 'u1', 70 | name: 'John', 71 | posts: [ 72 | { 73 | id: 'p1', 74 | title: 'Post 1', 75 | content: 'Content 1', 76 | author: { 77 | id: 'u1', 78 | name: 'John' 79 | } 80 | }, 81 | { 82 | id: 'p3', 83 | title: 'Post 3', 84 | content: 'Content 3', 85 | author: { 86 | id: 'u1', 87 | name: 'John' 88 | } 89 | } 90 | ] 91 | } 92 | } 93 | }) 94 | }) 95 | -------------------------------------------------------------------------------- /public/images/nearform.svg: -------------------------------------------------------------------------------- 1 | 2 | 6 | 7 | 8 | 9 | 13 | 17 | 21 | 25 | 29 | 33 | 37 | 38 | 39 | -------------------------------------------------------------------------------- /src/step-11-authorization/test/authorization.test.js: -------------------------------------------------------------------------------- 1 | import { test } from 'node:test' 2 | import assert from 'node:assert/strict' 3 | import { createService } from '../services/service.js' 4 | import { service1 } from '../services/service1.js' 5 | import { service2 } from '../services/service2.js' 6 | import buildGateway from '../index.js' 7 | 8 | const query = ` 9 | { 10 | me { 11 | name 12 | posts { 13 | title 14 | author { 15 | name 16 | } 17 | } 18 | } 19 | }` 20 | 21 | let userService 22 | let postService 23 | let gateway 24 | 25 | test.before(async () => { 26 | userService = await createService(4001, service1.schema, service1.resolvers) 27 | postService = await createService(4002, service2.schema, service2.resolvers) 28 | gateway = buildGateway() 29 | }) 30 | 31 | test.after(async () => { 32 | await gateway.close() 33 | await postService.close() 34 | await userService.close() 35 | }) 36 | 37 | test('Runs in gateway mode with two services and no X-Role header', async () => { 38 | const res = await gateway.inject({ 39 | method: 'POST', 40 | headers: { 41 | 'content-type': 'application/json' 42 | }, 43 | url: '/graphql', 44 | payload: JSON.stringify({ query }) 45 | }) 46 | 47 | assert.deepEqual(JSON.parse(res.body), { 48 | data: { 49 | me: null 50 | }, 51 | errors: [ 52 | { 53 | message: 'Failed auth policy check on me', 54 | locations: [ 55 | { 56 | line: 3, 57 | column: 3 58 | } 59 | ], 60 | path: ['me'] 61 | } 62 | ] 63 | }) 64 | }) 65 | 66 | test('Runs in gateway mode with two services with X-Role: VERIFIED', async () => { 67 | const res = await gateway.inject({ 68 | method: 'POST', 69 | headers: { 70 | 'content-type': 'application/json', 71 | 'X-Role': 'VERIFIED' 72 | }, 73 | url: '/graphql', 74 | payload: JSON.stringify({ query }) 75 | }) 76 | 77 | assert.deepEqual(JSON.parse(res.body), { 78 | data: { 79 | me: { 80 | name: 'John', 81 | posts: [ 82 | { 83 | title: 'Post 1', 84 | author: null 85 | }, 86 | { 87 | title: 'Post 3', 88 | author: null 89 | } 90 | ] 91 | } 92 | }, 93 | errors: [ 94 | { 95 | message: 'Failed auth policy check on author', 96 | locations: [ 97 | { 98 | line: 7, 99 | column: 7 100 | } 101 | ], 102 | path: ['me', 'posts', '0', 'author'] 103 | }, 104 | { 105 | message: 'Failed auth policy check on author', 106 | locations: [ 107 | { 108 | line: 7, 109 | column: 7 110 | } 111 | ], 112 | path: ['me', 'posts', '1', 'author'] 113 | } 114 | ] 115 | }) 116 | }) 117 | 118 | test('Runs in gateway mode with two services with X-Role: ADMIN', async () => { 119 | const res = await gateway.inject({ 120 | method: 'POST', 121 | headers: { 122 | 'content-type': 'application/json', 123 | 'X-Role': 'ADMIN' 124 | }, 125 | url: '/graphql', 126 | payload: JSON.stringify({ query }) 127 | }) 128 | 129 | assert.deepEqual(JSON.parse(res.body), { 130 | data: { 131 | me: { 132 | name: 'John', 133 | posts: [ 134 | { 135 | title: 'Post 1', 136 | author: { 137 | name: 'John' 138 | } 139 | }, 140 | { 141 | title: 'Post 3', 142 | author: { 143 | name: 'John' 144 | } 145 | } 146 | ] 147 | } 148 | } 149 | }) 150 | }) 151 | 152 | test('Runs in gateway mode with two services with X-Role: UNKNOWN', async () => { 153 | const res = await gateway.inject({ 154 | method: 'POST', 155 | headers: { 156 | 'content-type': 'application/json', 157 | 'X-Role': 'UNKNOWN' 158 | }, 159 | url: '/graphql', 160 | payload: JSON.stringify({ query }) 161 | }) 162 | 163 | assert.deepEqual(JSON.parse(res.body), { 164 | data: { 165 | me: null 166 | }, 167 | errors: [ 168 | { 169 | message: 'Failed auth policy check on me', 170 | locations: [ 171 | { 172 | line: 3, 173 | column: 3 174 | } 175 | ], 176 | path: ['me'] 177 | } 178 | ] 179 | }) 180 | }) 181 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-ShareAlike 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-ShareAlike 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. Share means to provide material to the public by any means or 126 | process that requires permission under the Licensed Rights, such 127 | as reproduction, public display, public performance, distribution, 128 | dissemination, communication, or importation, and to make material 129 | available to the public including in ways that members of the 130 | public may access the material from a place and at a time 131 | individually chosen by them. 132 | 133 | l. Sui Generis Database Rights means rights other than copyright 134 | resulting from Directive 96/9/EC of the European Parliament and of 135 | the Council of 11 March 1996 on the legal protection of databases, 136 | as amended and/or succeeded, as well as other essentially 137 | equivalent rights anywhere in the world. 138 | 139 | m. You means the individual or entity exercising the Licensed Rights 140 | under this Public License. Your has a corresponding meaning. 141 | 142 | 143 | Section 2 -- Scope. 144 | 145 | a. License grant. 146 | 147 | 1. Subject to the terms and conditions of this Public License, 148 | the Licensor hereby grants You a worldwide, royalty-free, 149 | non-sublicensable, non-exclusive, irrevocable license to 150 | exercise the Licensed Rights in the Licensed Material to: 151 | 152 | a. reproduce and Share the Licensed Material, in whole or 153 | in part; and 154 | 155 | b. produce, reproduce, and Share Adapted Material. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. Additional offer from the Licensor -- Adapted Material. 186 | Every recipient of Adapted Material from You 187 | automatically receives an offer from the Licensor to 188 | exercise the Licensed Rights in the Adapted Material 189 | under the conditions of the Adapter's License You apply. 190 | 191 | c. No downstream restrictions. You may not offer or impose 192 | any additional or different terms or conditions on, or 193 | apply any Effective Technological Measures to, the 194 | Licensed Material if doing so restricts exercise of the 195 | Licensed Rights by any recipient of the Licensed 196 | Material. 197 | 198 | 6. No endorsement. Nothing in this Public License constitutes or 199 | may be construed as permission to assert or imply that You 200 | are, or that Your use of the Licensed Material is, connected 201 | with, or sponsored, endorsed, or granted official status by, 202 | the Licensor or others designated to receive attribution as 203 | provided in Section 3(a)(1)(A)(i). 204 | 205 | b. Other rights. 206 | 207 | 1. Moral rights, such as the right of integrity, are not 208 | licensed under this Public License, nor are publicity, 209 | privacy, and/or other similar personality rights; however, to 210 | the extent possible, the Licensor waives and/or agrees not to 211 | assert any such rights held by the Licensor to the limited 212 | extent necessary to allow You to exercise the Licensed 213 | Rights, but not otherwise. 214 | 215 | 2. Patent and trademark rights are not licensed under this 216 | Public License. 217 | 218 | 3. To the extent possible, the Licensor waives any right to 219 | collect royalties from You for the exercise of the Licensed 220 | Rights, whether directly or through a collecting society 221 | under any voluntary or waivable statutory or compulsory 222 | licensing scheme. In all other cases the Licensor expressly 223 | reserves any right to collect such royalties. 224 | 225 | 226 | Section 3 -- License Conditions. 227 | 228 | Your exercise of the Licensed Rights is expressly made subject to the 229 | following conditions. 230 | 231 | a. Attribution. 232 | 233 | 1. If You Share the Licensed Material (including in modified 234 | form), You must: 235 | 236 | a. retain the following if it is supplied by the Licensor 237 | with the Licensed Material: 238 | 239 | i. identification of the creator(s) of the Licensed 240 | Material and any others designated to receive 241 | attribution, in any reasonable manner requested by 242 | the Licensor (including by pseudonym if 243 | designated); 244 | 245 | ii. a copyright notice; 246 | 247 | iii. a notice that refers to this Public License; 248 | 249 | iv. a notice that refers to the disclaimer of 250 | warranties; 251 | 252 | v. a URI or hyperlink to the Licensed Material to the 253 | extent reasonably practicable; 254 | 255 | b. indicate if You modified the Licensed Material and 256 | retain an indication of any previous modifications; and 257 | 258 | c. indicate the Licensed Material is licensed under this 259 | Public License, and include the text of, or the URI or 260 | hyperlink to, this Public License. 261 | 262 | 2. You may satisfy the conditions in Section 3(a)(1) in any 263 | reasonable manner based on the medium, means, and context in 264 | which You Share the Licensed Material. For example, it may be 265 | reasonable to satisfy the conditions by providing a URI or 266 | hyperlink to a resource that includes the required 267 | information. 268 | 269 | 3. If requested by the Licensor, You must remove any of the 270 | information required by Section 3(a)(1)(A) to the extent 271 | reasonably practicable. 272 | 273 | b. ShareAlike. 274 | 275 | In addition to the conditions in Section 3(a), if You Share 276 | Adapted Material You produce, the following conditions also apply. 277 | 278 | 1. The Adapter's License You apply must be a Creative Commons 279 | license with the same License Elements, this version or 280 | later, or a BY-SA Compatible License. 281 | 282 | 2. You must include the text of, or the URI or hyperlink to, the 283 | Adapter's License You apply. You may satisfy this condition 284 | in any reasonable manner based on the medium, means, and 285 | context in which You Share Adapted Material. 286 | 287 | 3. You may not offer or impose any additional or different terms 288 | or conditions on, or apply any Effective Technological 289 | Measures to, Adapted Material that restrict exercise of the 290 | rights granted under the Adapter's License You apply. 291 | 292 | 293 | Section 4 -- Sui Generis Database Rights. 294 | 295 | Where the Licensed Rights include Sui Generis Database Rights that 296 | apply to Your use of the Licensed Material: 297 | 298 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 299 | to extract, reuse, reproduce, and Share all or a substantial 300 | portion of the contents of the database; 301 | 302 | b. if You include all or a substantial portion of the database 303 | contents in a database in which You have Sui Generis Database 304 | Rights, then the database in which You have Sui Generis Database 305 | Rights (but not its individual contents) is Adapted Material, 306 | 307 | including for purposes of Section 3(b); and 308 | c. You must comply with the conditions in Section 3(a) if You Share 309 | all or a substantial portion of the contents of the database. 310 | 311 | For the avoidance of doubt, this Section 4 supplements and does not 312 | replace Your obligations under this Public License where the Licensed 313 | Rights include other Copyright and Similar Rights. 314 | 315 | 316 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 317 | 318 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 319 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 320 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 321 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 322 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 323 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 324 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 325 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 326 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 327 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 328 | 329 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 330 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 331 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 332 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 333 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 334 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 335 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 336 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 337 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 338 | 339 | c. The disclaimer of warranties and limitation of liability provided 340 | above shall be interpreted in a manner that, to the extent 341 | possible, most closely approximates an absolute disclaimer and 342 | waiver of all liability. 343 | 344 | 345 | Section 6 -- Term and Termination. 346 | 347 | a. This Public License applies for the term of the Copyright and 348 | Similar Rights licensed here. However, if You fail to comply with 349 | this Public License, then Your rights under this Public License 350 | terminate automatically. 351 | 352 | b. Where Your right to use the Licensed Material has terminated under 353 | Section 6(a), it reinstates: 354 | 355 | 1. automatically as of the date the violation is cured, provided 356 | it is cured within 30 days of Your discovery of the 357 | violation; or 358 | 359 | 2. upon express reinstatement by the Licensor. 360 | 361 | For the avoidance of doubt, this Section 6(b) does not affect any 362 | right the Licensor may have to seek remedies for Your violations 363 | of this Public License. 364 | 365 | c. For the avoidance of doubt, the Licensor may also offer the 366 | Licensed Material under separate terms or conditions or stop 367 | distributing the Licensed Material at any time; however, doing so 368 | will not terminate this Public License. 369 | 370 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 371 | License. 372 | 373 | 374 | Section 7 -- Other Terms and Conditions. 375 | 376 | a. The Licensor shall not be bound by any additional or different 377 | terms or conditions communicated by You unless expressly agreed. 378 | 379 | b. Any arrangements, understandings, or agreements regarding the 380 | Licensed Material not stated herein are separate from and 381 | independent of the terms and conditions of this Public License. 382 | 383 | 384 | Section 8 -- Interpretation. 385 | 386 | a. For the avoidance of doubt, this Public License does not, and 387 | shall not be interpreted to, reduce, limit, restrict, or impose 388 | conditions on any use of the Licensed Material that could lawfully 389 | be made without permission under this Public License. 390 | 391 | b. To the extent possible, if any provision of this Public License is 392 | deemed unenforceable, it shall be automatically reformed to the 393 | minimum extent necessary to make it enforceable. If the provision 394 | cannot be reformed, it shall be severed from this Public License 395 | without affecting the enforceability of the remaining terms and 396 | conditions. 397 | 398 | c. No term or condition of this Public License will be waived and no 399 | failure to comply consented to unless expressly agreed to by the 400 | Licensor. 401 | 402 | d. Nothing in this Public License constitutes or may be interpreted 403 | as a limitation upon, or waiver of, any privileges and immunities 404 | that apply to the Licensor or You, including from the legal 405 | processes of any jurisdiction or authority. 406 | 407 | 408 | ======================================================================= 409 | 410 | Creative Commons is not a party to its public licenses. 411 | Notwithstanding, Creative Commons may elect to apply one of its public 412 | licenses to material it publishes and in those instances will be 413 | considered the “Licensor.” The text of the Creative Commons public 414 | licenses is dedicated to the public domain under the CC0 Public Domain 415 | Dedication. Except for the limited purpose of indicating that material 416 | is shared under a Creative Commons public license or as otherwise 417 | permitted by the Creative Commons policies published at 418 | creativecommons.org/policies, Creative Commons does not authorize the 419 | use of the trademark "Creative Commons" or any other trademark or logo 420 | of Creative Commons without its prior written consent including, 421 | without limitation, in connection with any unauthorized modifications 422 | to any of its public licenses or any other arrangements, 423 | understandings, or agreements concerning use of licensed material. For 424 | the avoidance of doubt, this paragraph does not form part of the public 425 | licenses. 426 | 427 | Creative Commons may be contacted at creativecommons.org. 428 | -------------------------------------------------------------------------------- /slides.md: -------------------------------------------------------------------------------- 1 | --- 2 | theme: slidev-theme-nearform 3 | layout: default 4 | highlighter: shiki 5 | lineNumbers: false 6 | --- 7 | 8 | 9 | 10 | # The GraphQL Workshop 11 | 12 | ### **A guide to GraphQL with Fastify and Mercurius** 13 | 14 |
15 | 16 | 17 | 18 |
19 | 20 | --- 21 | 22 | # Why Mercurius 23 | 24 |
25 | 26 | - [Mercurius](https://mercurius.dev/) is a **high-performance** GraphQL adapter for the [Fastify](https://www.fastify.io/) web framework 27 | - It has many core features and plugins for building world class production-ready applications 28 | - It supports advanced features out of the box such as [Apollo Federation specification](https://www.apollographql.com/docs/federation/federation-spec/) and Subscriptions 29 | - It's entirely **Open Source** and made available under the MIT license 30 | - It has a rich and vibrant community contributing to its development 31 | 32 |
33 | 34 | --- 35 | 36 | # Prerequisites 37 | 38 |
39 | 40 | - This workshop requires an understanding of the **Fastify** framework. 41 | 42 | - We recommend a basic knowledge of the Fastify plugin system which can be acquired by following a workshop similar to this one, focused on Fastify: https://github.com/nearform/the-fastify-workshop 43 | 44 | - A basic grasp on how to write **GraphQL queries** so you can check your working via curl or [graphiql](https://graphql-dotnet.github.io/docs/getting-started/graphiql/) (a browser based GraphQL IDE). 45 | - We recommend the [GraphQL queries documentation](https://graphql.org/learn/queries/) 46 | 47 |
48 | 49 | --- 50 | 51 |
52 | 53 | # Mercurius core features 54 | 55 | - **Caching** of query parsing and validation 56 | - Automatic **loader** integration to avoid the N+1 problem 57 | - Just-In-Time compiler via graphql-jit 58 | - **Subscriptions** 59 | - **Federation** support 60 | - Federated subscriptions support 61 | - Gateway implementation, including Subscriptions 62 | - **Batched** query support 63 | - Customizable persisted queries 64 | 65 |
66 | 67 | --- 68 | 69 | # Getting setup 70 | 71 |
72 | 73 | Clone the repository: 74 | 75 | ```bash 76 | git clone https://github.com/nearform/the-graphql-workshop 77 | ``` 78 | 79 | Follow the instructions in the [README](https://github.com/nearform/the-graphql-workshop) file 80 | 81 | 💡 Ask if anything doesn't work! 82 | 83 |
84 | 85 | --- 86 | 87 |
88 | 89 | # Workshop structure 90 | 91 | - This workshop is made of multiple, incremental modules 92 | - Each module builds on top of the previous one 93 | - At each step you are asked to add features and solve problems 94 | - You will find the solution to each step in the `src/step-{n}-{name}` folder 95 | - The 🏆 icon indicates bonus features 96 | - The 💡 icon indicates hints 97 | 98 |
99 | 100 | --- 101 | 102 |
103 | 104 | # Running the modules 105 | 106 | - `cd src/step-{n}-{name}` 107 | - Check out the README file in each step 108 | 109 | #### Example 110 | 111 | ```bash 112 | cd src/step-01-basic 113 | 114 | npm start 115 | ``` 116 | 117 |
118 | 119 | --- 120 | 121 |
122 | 123 | # Step 1: Basic 💻 124 | 125 | Create a GraphQL server which exposes an `add` function to compute the sum of two numbers. 126 | 127 | - Expose a GraphQL `POST /graphql` route 128 | - Listen on port 3000 129 | - Create a schema including an `add` Query accepting parameters `x` and `y` 130 | - Implement a resolver for the `add` query 131 | - Respond with the JSON object when invoked with `(x:5, y:3)` 132 | 133 | ```json 134 | { 135 | "data": { 136 | "add": 8 137 | } 138 | } 139 | ``` 140 | 141 |
142 | 143 | --- 144 | 145 | # Step 1: Solution / 1 146 | 147 | ```js 148 | // index.js 149 | import Fastify from 'fastify' 150 | import mercurius from 'mercurius' 151 | import { schema, resolvers } from './graphql.js' 152 | 153 | export default function buildServer() { 154 | const server = Fastify({ 155 | logger: { 156 | transport: { 157 | target: 'pino-pretty' 158 | } 159 | } 160 | }) 161 | 162 | server.register(mercurius, { 163 | schema, 164 | resolvers, 165 | graphiql: true 166 | }) 167 | 168 | return server 169 | } 170 | ``` 171 | 172 | --- 173 | 174 | # Step 1: Solution / 2 175 | 176 | ```js 177 | // graphql.js 178 | const schema = ` 179 | type Query { 180 | add(x: Int!, y: Int!): Int 181 | } 182 | ` 183 | 184 | const resolvers = { 185 | Query: { 186 | add: async (_, { x, y }) => x + y 187 | } 188 | } 189 | 190 | export { schema, resolvers } 191 | ``` 192 | 193 | ```js 194 | // server.js 195 | import buildServer from './index.js' 196 | 197 | const app = buildServer() 198 | 199 | app.listen({ port: 3000 }) 200 | ``` 201 | 202 | --- 203 | 204 | # Step 1: Trying it out 205 | 206 | ### In the terminal: 207 | 208 | ```bash 209 | curl --request POST \ 210 | --url http://localhost:3000/graphql \ 211 | --header 'Content-Type: application/json' \ 212 | --data '{"query":"{ add(x: 5, y:3) }"}' 213 | ``` 214 | 215 | ```json 216 | { 217 | "data": { 218 | "add": 8 219 | } 220 | } 221 | ``` 222 | 223 | --- 224 | 225 |
226 | 227 | # Step 2: Loaders 💻 228 | 229 | A loader is an utility to avoid the N+1 query problem of GraphQL. Each defined loader will register a resolver that coalesces each of the request and combines them into a single, bulk query. 230 | 231 | Moreover, it can also cache the results, so that other parts of the GraphQL do not have to fetch the same data. 232 | 233 | - Create a `Person` type with `name` property 234 | - Create a `Pet` type with `name` and `owner` property (of type `Person`) 235 | - Expose a `pets` query which returns all pets and, for each pet, its owner, using **GraphQL loaders** 236 | 237 |
238 | 239 | --- 240 | 241 |
242 | 243 | - The query should return a JSON object: 244 | 245 | ```json 246 | { 247 | "data": { 248 | "pets": [ 249 | { 250 | "owner": { 251 | "name": "Jennifer" 252 | } 253 | }, 254 | { 255 | "owner": { 256 | "name": "Simon" 257 | } 258 | } 259 | ] 260 | } 261 | } 262 | ``` 263 | 264 |
265 | 266 | --- 267 | 268 | # Step 2: Solution / 1 269 | 270 | ```js 271 | // index.js 272 | import Fastify from 'fastify' 273 | import mercurius from 'mercurius' 274 | import { schema, resolvers, loaders } from './graphql.js' 275 | 276 | export default function buildServer() { 277 | const server = Fastify(...) 278 | 279 | server.register(mercurius, { 280 | schema, 281 | resolvers, 282 | loaders, 283 | graphiql: true 284 | }) 285 | 286 | return server 287 | } 288 | ``` 289 | 290 | --- 291 | 292 | # Step 2: Solution / 2 293 | 294 |
295 | 296 | ```js 297 | // graphql.js 298 | const pets = [ 299 | { 300 | name: 'Max' 301 | }, 302 | { 303 | name: 'Charlie' 304 | } 305 | ] 306 | 307 | const owners = { 308 | Max: { 309 | name: 'Jennifer' 310 | }, 311 | Charlie: { 312 | name: 'Simon' 313 | } 314 | } 315 | ``` 316 | 317 | ```js 318 | const schema = ` 319 | type Person { 320 | name: String! 321 | } 322 | 323 | type Pet { 324 | name: String! 325 | owner: Person 326 | } 327 | 328 | type Query { 329 | pets: [Pet] 330 | } 331 | ` 332 | 333 | const resolvers = { 334 | Query: { 335 | pets() { 336 | return pets 337 | } 338 | } 339 | } 340 | ``` 341 | 342 |
343 | 344 | --- 345 | 346 | # Step 2: Solution / 3 347 | 348 | ```js 349 | // graphql.js (cont.) 350 | const loaders = { 351 | Pet: { 352 | async owner(queries) { 353 | return queries.map(({ obj: pet }) => owners[pet.name]) 354 | } 355 | } 356 | } 357 | 358 | export { schema, resolvers, loaders } 359 | ``` 360 | 361 | --- 362 | 363 | # Step 2: Trying it out 364 | 365 | ### In Graphiql 366 | 367 | You can navigate to graphql query editor on http://localhost:3000/graphiql 368 | 369 | 370 | 371 | --- 372 | 373 |
374 | 375 | # Step 3: Executable schema 💻 376 | 377 | The `@graphql-tools/schema` package allows you to create a GraphQL.js [GraphQLSchema](https://graphql.org/graphql-js/type/) instance from GraphQL schema language using the function `makeExecutableSchema`. 378 | 379 | Besides common options such as `typeDefs` and `resolvers`, it supports more advanced options to customize the creation of the schema. 380 | 381 | - Create an executable schema using `typeDefs` and `resolvers` 382 | - Use the `@graphql-tools/schema` package to create the executable schema 383 | - Implement the same "add" functionality as in the earlier step 384 | 385 |
386 | 387 | --- 388 | 389 | # Step 3: Solution 390 | 391 |
392 | 393 | ```js 394 | // index.js 395 | import Fastify from 'fastify' 396 | import mercurius from 'mercurius' 397 | import { makeExecutableSchema } from '@graphql-tools/schema' 398 | 399 | import { typeDefs, resolvers } from './graphql.js' 400 | 401 | export default function buildServer() { 402 | const server = Fastify(...) 403 | 404 | server.register(mercurius, { 405 | schema: makeExecutableSchema({ typeDefs, resolvers }) 406 | }) 407 | 408 | return server 409 | } 410 | ``` 411 | 412 | ```js 413 | // graphql.js 414 | const typeDefs = ` 415 | type Query { 416 | add(x: Int!, y: Int!): Int 417 | } 418 | ` 419 | 420 | const resolvers = { 421 | Query: { 422 | add: async (_, { x, y }) => x + y 423 | } 424 | } 425 | 426 | export { typeDefs, resolvers } 427 | ``` 428 | 429 |
430 | 431 | --- 432 | 433 |
434 | 435 | # Step 4: SELECT N+1 💻 436 | 437 | - Implement the same Pet and Owners functionality as before 438 | - Allows to query all pets and its owners by using GraphQL loaders 439 | - Stores the pets and owners in postgres database 440 | - Uses a **single database query** to get owners for all pets 441 | 442 |
443 | 444 | --- 445 | 446 | # Step 4: Solution 447 | 448 |
449 | 450 | ```js 451 | export async function ownersByPetNames(db, petNames) { 452 | const { rows } = await db.query( 453 | SQL` 454 | SELECT owners.* 455 | FROM owners 456 | INNER JOIN pets 457 | ON pets.owner = owners.id 458 | AND pets.name = ANY(${petNames}) 459 | ORDER BY 460 | ARRAY_POSITION((${petNames}), pets.name)` 461 | ` 462 | ) 463 | 464 | return rows 465 | } 466 | ``` 467 | 468 | ```js 469 | const loaders = { 470 | Pet: { 471 | async owner(queries, context) { 472 | const petNames = queries.map(({ obj }) => obj.name) 473 | return ownersByPetNames(context.app.pg, petNames) 474 | } 475 | } 476 | } 477 | ``` 478 | 479 |
480 | 481 | 💡 For the full code examples and db setup instructions, see the repository 482 | 483 | --- 484 | 485 |
486 | 487 | # Step 5: Context 💻 488 | 489 | Context is an object populated at the server level which is made accessible to resolvers. 490 | 491 | - Create a `User` type with `name` and `locale` properties 492 | - Create an in-memory array of `User` with different locales 493 | - Create a query called `getUserByLocale` returning the first user with `en` locale 494 | - Set the property `locale: 'en'` in the mercurius context 495 | - Respond with JSON object: 496 | 497 | ```json 498 | { 499 | "data": { 500 | "getUserByLocale": { 501 | "name": "Alice" 502 | } 503 | } 504 | } 505 | ``` 506 | 507 |
508 | 509 | --- 510 | 511 | # Step 5: Solution 512 | 513 | ```js 514 | const server = Fastify(...) 515 | 516 | server.register(mercurius, { 517 | schema, 518 | resolvers, 519 | context: () => ({ 520 | locale: 'en' 521 | }) 522 | }) 523 | ``` 524 | 525 | ```js 526 | const resolvers = { 527 | Query: { 528 | getUserByLocale(_, __, context) { 529 | return users.find(u => u.locale === context.locale) 530 | } 531 | } 532 | } 533 | ``` 534 | 535 | --- 536 | 537 |
538 | 539 | # Step 6: Hooks 💻 540 | 541 | Hooks are registered with the `fastify.graphql.addHook` method and allow you to listen to specific events in the GraphQL request/response lifecycle. 542 | 543 | By using hooks you can interact directly with the GraphQL lifecycle of Mercurius. 544 | 545 | - Create a query called `sum` which returns the sum of two numbers 546 | - Create and print logs for the following hooks: 547 | - `preParsing` 548 | - `preValidation` 549 | - `preExecution` 550 | - `onResolution` 551 | - Enrich the response with an error with the message "foo" in the `preExecution` hook 552 | 553 |
554 | 555 | --- 556 | 557 |
558 | 559 | - The query should return something similar to: 560 | 561 | ```json 562 | { 563 | "data": { 564 | "add": 10 565 | }, 566 | "errors": [ 567 | { 568 | "message": "foo" 569 | } 570 | ] 571 | } 572 | ``` 573 | 574 |
575 | 576 | --- 577 | 578 | # Step 6: Solution 579 | 580 | ```js 581 | // server.js 582 | app.graphql.addHook('preParsing', async function () { 583 | app.log.info('preParsing called') 584 | }) 585 | 586 | app.graphql.addHook('preValidation', async function () { 587 | app.log.info('preValidation called') 588 | }) 589 | 590 | app.graphql.addHook('preExecution', async function (schema, document) { 591 | app.log.info('preExecution called') 592 | 593 | return { 594 | document, 595 | errors: [new Error('foo')] 596 | } 597 | }) 598 | 599 | app.graphql.addHook('onResolution', async function () { 600 | app.log.info('onResolution called') 601 | }) 602 | ``` 603 | 604 | --- 605 | 606 | # Step 6: Trying it out 607 | 608 |
609 | 610 | In terminal 611 | 612 | ```bash 613 | curl --request POST \ 614 | --url http://localhost:3000/graphql \ 615 | --header 'Content-Type: application/json' \ 616 | --data '{"query":"{ add(x: 5, y:3) }"}' 617 | ``` 618 | 619 |
620 | 621 | Output 622 | 623 |
624 | 625 | ```bash 626 | preParsing called 627 | preValidation called 628 | preExecution called 629 | onResolution called 630 | ``` 631 | 632 | ```json 633 | { 634 | "data": { 635 | "add": 10 636 | }, 637 | "errors": [ 638 | { 639 | "message": "foo" 640 | } 641 | ] 642 | } 643 | ``` 644 | 645 |
646 | 647 | --- 648 | 649 |
650 | 651 | # Step 7: Error handling 💻 652 | 653 | - Create `User` type with `name` and `id` property 654 | - Create an in-memory array of users of type `User` 655 | - Create a query `findUser` which accepts an `id` and 656 | - If the `id` matches then the corresponding user is returned 657 | - If the `id` does not match with any user then an error is thrown with the message `"Invalid User ID"` 658 | - Add a property `extensions` to the error object with properties: 659 | - `code: USER_ID_INVALID` 660 | - `id: ` 661 | - 💡 Use Mercurius `ErrorWithProps` to create the error 662 | 663 |
664 | 665 | --- 666 | 667 |
668 | 669 | # Step 7: Error handling 💻 670 | 671 | - The query should return something similar to: 672 | 673 | ```json 674 | { 675 | "data": { 676 | "findUser": null 677 | }, 678 | "errors": [ 679 | { 680 | "message": "Invalid User ID", 681 | "locations": [{ "line": 2, "column": 3 }], 682 | "path": ["findUser"], 683 | "extensions": { 684 | "code": "USER_ID_INVALID", 685 | "id": "5" 686 | } 687 | } 688 | ] 689 | } 690 | ``` 691 | 692 |
693 | 694 | --- 695 | 696 | # Step 7: Solution 697 | 698 | ```js 699 | const resolvers = { 700 | Query: { 701 | findUser: (_, { id }) => { 702 | const user = users[id] 703 | 704 | if (user) { 705 | return users[id] 706 | } 707 | 708 | throw new ErrorWithProps('Invalid User ID', { 709 | id, 710 | code: 'USER_ID_INVALID' 711 | }) 712 | } 713 | } 714 | } 715 | ``` 716 | 717 | --- 718 | 719 |
720 | 721 | # Step 8: Federation 💻 722 | 723 | A GraphQL server can act as a Gateway that composes the schemas of the underlying services into one federated schema and executes queries across the services. Every underlying service must be a GraphQL server that supports the federation. 724 | 725 | - Create a Federated GraphQL gateway which listens on port 4000 726 | - Run and expose to the gateway two GraphQL services on ports 4001 and 4002 727 | - In order to use gateway, you should import the following lib: 728 | 729 | ```js 730 | import mercuriusGateway from '@mercuriusjs/gateway' 731 | ... 732 | gateway.register(mercuriusGateway, {...}); 733 | ``` 734 | 735 | - Service 1 has a `User` type and a `me` query which returns the user 736 | - Service 2 has a `Post` type and extends `User` with a `posts` array which are the posts of that user 737 | 738 |
739 | 740 | --- 741 | 742 |
743 | 744 | # Step 8: Federation 💻 745 | 746 | - Use the import below for registering the service with federation enabled: 747 | 748 | ```js 749 | import { mercuriusFederationPlugin } from '@mercuriusjs/federation' 750 | 751 | service.register(mercuriusFederationPlugin, {...} 752 | ``` 753 | 754 | - Keep an in-memory array of users of the type `User` and posts of type `Post` 755 | - The query should return something similar to: 756 | 757 | ```json 758 | { 759 | "data": { 760 | "me": { 761 | "name": "John", 762 | "posts": [ 763 | { "id": "p1", "title": "Post 1", "content": "Content 1" }, 764 | { "id": "p3", "title": "Post 3", "content": "Content 3" } 765 | ] 766 | } 767 | } 768 | } 769 | ``` 770 | 771 |
772 | 773 | --- 774 | 775 | # Step 8: Solution / 1 776 | 777 | ```js 778 | // server.js 779 | ... 780 | await createService( 781 | 4001, 782 | service1.schema, 783 | service1.resolvers 784 | ) 785 | await createService( 786 | 4002, 787 | service2.schema, 788 | service2.resolvers 789 | ) 790 | 791 | const gateway = buildGateway() 792 | await gateway.listen({ port: 4000 }) 793 | ... 794 | ``` 795 | 796 | --- 797 | 798 | # Step 8: Solution / 2 799 | 800 | ```js 801 | // index.js 802 | import Fastify from 'fastify' 803 | import mercuriusGateway from '@mercuriusjs/gateway' 804 | 805 | export default function buildGateway() { 806 | const gateway = Fastify({ 807 | logger: { transport: { target: 'pino-pretty' } } 808 | }) 809 | 810 | gateway.register(mercuriusGateway, { 811 | graphiql: true, 812 | jit: 1, 813 | gateway: { 814 | services: [ 815 | { name: 'user', url: 'http://localhost:4001/graphql' }, 816 | { name: 'post', url: 'http://localhost:4002/graphql' } 817 | ] 818 | } 819 | }) 820 | 821 | return gateway 822 | } 823 | ``` 824 | 825 | --- 826 | 827 | # Step 8: Solution / 3 828 | 829 | ```js 830 | // services/service.js 831 | import Fastify from 'fastify' 832 | import { mercuriusFederationPlugin } from '@mercuriusjs/federation' 833 | 834 | const createService = async (port, schema, resolvers) => { 835 | const service = Fastify() 836 | 837 | service.register(mercuriusFederationPlugin, { 838 | schema, 839 | resolvers, 840 | graphiql: true, 841 | jit: 1 842 | }) 843 | await service.listen({ port }) 844 | 845 | return service 846 | } 847 | 848 | export { createService } 849 | ``` 850 | 851 | > 💡 see service1 and service2 implementations in the repo 852 | 853 | --- 854 | 855 | # Step 9: Variables 💻 856 | 857 |
858 | 859 | - Review the `add` functionality implemented before 860 | - The `add` function is supplied with dynamic parameters
`($x: Int!, $y: Int!)` 861 | - The inputs to the `add` function should be passed as query variables, e.g
`{ "x": 3, "y": 5 }` 862 | - The query should return something similar to: 863 | 864 | ```json 865 | { 866 | "data": { 867 | "add": 8 868 | } 869 | } 870 | ``` 871 | 872 |
873 | 874 | --- 875 | 876 | # Step 9: Solution 877 | 878 | ```js 879 | const schema = ` 880 | type Query { 881 | add(x: Int!, y: Int!): Int 882 | } 883 | ` 884 | 885 | const resolvers = { 886 | add: async ({ x, y }) => x + y 887 | } 888 | ``` 889 | 890 | > 💡 The implementation is the same as before 891 | 892 | --- 893 | 894 | # Step 9: Trying it out 895 | 896 | In terminal 897 | 898 | ```bash 899 | curl --request POST \ 900 | --url http://localhost:3000/graphql \ 901 | --header 'Content-Type: application/json' \ 902 | --data '{"query":"query AddQuery ($x: Int!, $y: Int!) { add(x: $x, y: $y) }","variables":{"x":3,"y":5},"operationName":"AddQuery"}' 903 | ``` 904 | 905 | Output 906 | 907 | ```json 908 | { 909 | "data": { 910 | "add": 8 911 | } 912 | } 913 | ``` 914 | 915 | --- 916 | 917 |
918 | 919 | # Step 10: Fragments 💻 920 | 921 | Create a GraphQL server using mercurius which: 922 | 923 | - Has `User` type with `id`, `name`, `age` and `level` properties 924 | - Has two Query methods named `getNoviceUsers` and `getAdvancedUsers` which return type `User` 925 | - `getNoviceUsers` query returns users with `level: novice` 926 | - `getAdvancedUsers` query returns users with `level: advanced` 927 | - Query both methods using a fragment on the type `User` 928 | 929 |
930 | 931 | --- 932 | 933 |
934 | 935 | - The query should return something similar to: 936 | 937 | ```json 938 | { 939 | "data": { 940 | "getNoviceUsers": [ 941 | { 942 | "id": 1, 943 | "name": "John Doe", 944 | "age": 32, 945 | "level": "novice" 946 | } 947 | ], 948 | "getAdvancedUsers": [ 949 | { 950 | "id": 2, 951 | "name": "Jane Doe", 952 | "age": 28, 953 | "level": "advanced" 954 | } 955 | ] 956 | } 957 | } 958 | ``` 959 | 960 |
961 | 962 | --- 963 | 964 | # Step 10: Solution 965 | 966 |
967 | 968 | ```js 969 | const schema = ` 970 | type User { 971 | id: Int! 972 | name: String! 973 | age: Int! 974 | level: String! 975 | } 976 | 977 | type Query { 978 | getNoviceUsers: [User] 979 | getAdvancedUsers: [User] 980 | } 981 | ` 982 | const resolvers = { 983 | Query: { 984 | getNoviceUsers() { 985 | return users.filter(user => user.level === 'novice') 986 | }, 987 | getAdvancedUsers() { 988 | return users.filter(user => user.level === 'advanced') 989 | } 990 | } 991 | } 992 | ``` 993 | 994 |
995 | 996 | --- 997 | 998 |
999 | 1000 | # Step 10: Trying it out 1001 | 1002 | ### In terminal 1003 | 1004 | ```bash 1005 | curl --request POST \ 1006 | --url http://localhost:3000/graphql \ 1007 | --header 'Content-Type: application/json' \ 1008 | --data '{"query":"{ getNoviceUsers { ...userFields } getAdvancedUsers { ...userFields } } fragment userFields on User { id name age level }"}' 1009 | ``` 1010 | 1011 | ```json 1012 | { 1013 | "data": { 1014 | "getNoviceUsers": [ 1015 | { "id": 1, "name": "John Doe", "age": 32, "level": "novice" } 1016 | ], 1017 | "getAdvancedUsers": [ 1018 | { "id": 2, "name": "Jane Doe", "age": 28, "level": "advanced" } 1019 | ] 1020 | } 1021 | } 1022 | ``` 1023 | 1024 |
1025 | 1026 | --- 1027 | 1028 |
1029 | 1030 | # Step 11: Authorization 1031 | 1032 | In RESTful APIs, a common use case is to restrict access to certain endpoints unless the user has permission to access them. Likewise in GraphQL, you can restrict access to certain fields unless the user has permission to access them. 1033 | 1034 | In this step, we will carry on from Step 8 (Federation) and modify the `me` query so that it only returns the current user and their posts, and no one else's. 1035 | 1036 | - In the service containing the `me` query, update the schema to define a new directive 1037 | - Define a `role` argument for the directive that can be either `VERIFIED` or `ADMIN` 1038 | - Annotate the `me` query with the new directive and pass in an argument of `role: VERIFIED` 1039 | - Annotate the `author` field with the new directive and pass in an argument of `role: ADMIN` 1040 |
1041 | 1042 | --- 1043 | 1044 |
1045 | 1046 | # Step 11: Authorization 1047 | 1048 | - Install the `mercurius-auth` package and register it with the gateway 1049 | - Specify the following properties in the options object for the plugin: 1050 | - `authDirective` - the name of the directive you just defined 1051 | - `authContext` - logic to extract the user's role. For simplicity's sake, we will extract the user's role from the `X-Role` request header. In a real-world application, you may pass a JSON Web Token (JWT) via the headers, verify and decode it to extract the user's ID, role(s), and permission(s). 1052 | - `applyPolicy` - logic that determines, given the user's role, whether the server should allow the client to access this field or object? 1053 | 1054 |
1055 | 1056 | --- 1057 | 1058 | # Step 11: Solution / 1 1059 | 1060 |
1061 | 1062 | ```js {1,4-11,14} 1063 | // services/service1.js 1064 | const service1 = { 1065 | schema: ` 1066 | enum Role { 1067 | ADMIN 1068 | VERIFIED 1069 | } 1070 | 1071 | directive @auth( 1072 | role: Role 1073 | ) on OBJECT | FIELD_DEFINITION 1074 | 1075 | extend type Query { 1076 | me: User @auth(role: VERIFIED) 1077 | } 1078 | 1079 | type User @key(fields: "id") { 1080 | id: ID! 1081 | name: String! 1082 | } 1083 | `, 1084 | ... 1085 | } 1086 | ``` 1087 | 1088 |
1089 | 1090 | 1091 | --- 1092 | 1093 | # Step 11: Solution / 2 1094 | 1095 |
1096 | 1097 | ```js {1,4-9,15} 1098 | // services/service2.js 1099 | const service2 = { 1100 | schema: ` 1101 | enum Role { 1102 | ADMIN 1103 | VERIFIED 1104 | } 1105 | 1106 | directive @auth(role: Role) on OBJECT | FIELD_DEFINITION 1107 | 1108 | type Post @key(fields: "id") { 1109 | id: ID! 1110 | title: String 1111 | content: String 1112 | author: User @auth(role: ADMIN) 1113 | } 1114 | 1115 | type User @key(fields: "id") @extends { 1116 | id: ID! @external 1117 | name: String @external 1118 | posts: [Post] 1119 | }`, 1120 | ... 1121 | } 1122 | ``` 1123 | 1124 |
1125 | 1126 | --- 1127 | 1128 | # Step 11: Solution / 3 1129 | 1130 |
1131 | 1132 | ```js 1133 | // index.js 1134 | import mercuriusAuth from 'mercurius-auth'; 1135 | ... 1136 | gateway.register(mercuriusAuth, { 1137 | authContext (context) { 1138 | return { 1139 | role: context.reply.request.headers['x-role'] 1140 | } 1141 | }, 1142 | async applyPolicy (authDirectiveAST, parent, args, context, info) { 1143 | const directiveRole = authDirectiveAST.arguments 1144 | .find(arg => arg.name.value === 'role') 1145 | .value.value; 1146 | 1147 | return context.auth.role === directiveRole || context.auth.role === 'ADMIN'; 1148 | }, 1149 | authDirective: 'auth' 1150 | }) 1151 | 1152 | ``` 1153 | 1154 |
1155 | 1156 | --- 1157 | 1158 |
1159 | 1160 | # Step 11: Trying it out / No header 1161 | 1162 | ### In terminal 1163 | 1164 | ```bash 1165 | curl --request POST \ 1166 | --url http://localhost:4000/graphql \ 1167 | --header 'Content-Type: application/json' \ 1168 | --data '{"query":"{ me { name posts { title author { name }}}}"}' 1169 | ``` 1170 | 1171 | ```json 1172 | { 1173 | "data": { "me": null }, 1174 | "errors": [{ 1175 | "message": "Failed auth policy check on me", 1176 | "locations": [{ 1177 | "line": 1, 1178 | "column": 3 1179 | }], 1180 | "path": [ "me" ] 1181 | }] 1182 | } 1183 | ``` 1184 | 1185 |
1186 | 1187 | --- 1188 | 1189 |
1190 | 1191 | # Step 11: Trying it out / VERIFIED 1192 | 1193 | ### In terminal 1194 | 1195 | ```bash 1196 | curl --request POST \ 1197 | --url http://localhost:4000/graphql \ 1198 | --header 'Content-Type: application/json' \ 1199 | --header 'X-Role: VERIFIED' \ 1200 | --data '{"query":"{ me { name posts { title author { name }}}}"}' 1201 | ``` 1202 | 1203 | ```json 1204 | { 1205 | "data": { 1206 | "me": { 1207 | "name": "John", 1208 | "posts": [{ 1209 | "title": "Post 1", 1210 | "author": null 1211 | }, { 1212 | "title": "Post 3", 1213 | "author": null 1214 | }] 1215 | } 1216 | }, 1217 | "errors": [{ 1218 | "message": "Failed auth policy check on author", 1219 | "locations": [ ... ], 1220 | "path": [ ... ] 1221 | }, 1222 | ... 1223 | ] 1224 | } 1225 | ``` 1226 | 1227 |
1228 | 1229 | --- 1230 | 1231 |
1232 | 1233 | # Step 11: Trying it out / ADMIN 1234 | 1235 | ### In terminal 1236 | 1237 | ```bash 1238 | curl --request POST \ 1239 | --url http://localhost:4000/graphql \ 1240 | --header 'Content-Type: application/json' \ 1241 | --header 'X-Role: ADMIN' \ 1242 | --data '{"query":"{ me { name posts { title author { name }}}}"}' 1243 | ``` 1244 | 1245 | ```json 1246 | { 1247 | "data": { 1248 | "me": { 1249 | "name": "John", 1250 | "posts": [{ 1251 | "title": "Post 1", 1252 | "author": { "name": "John" } 1253 | }, { 1254 | "title": "Post 3", 1255 | "author": { "name": "John" } 1256 | }] 1257 | } 1258 | } 1259 | } 1260 | ``` 1261 | 1262 |
1263 | 1264 | --- 1265 | 1266 |
1267 | 1268 | # 🏆 Write Tests 🏆 1269 | 1270 | > 💡 inspire from the code in the completed steps 1271 | 1272 |
1273 | 1274 | --- 1275 | 1276 |
1277 | 1278 | # Thanks For Having Us! 1279 | 1280 | ## 👏👏👏 1281 | 1282 | 1283 | 1284 |
1285 | --------------------------------------------------------------------------------