helix-flare

helix-flare helps you build GraphQL services on Cloudflare Workers® in an instant.

With help of the great library graphql-helix this is made possible.

Features

• Build GraphQL server on Cloudflare Workers in seconds
• Delegate execution to Durable Objects. Workers will only act as a proxy.
• Have one schema, resolve some things in your DO, others in the Worker
• Add middlewares and context
• Live subscriptions (over server-sent events)
• Easy to use with envelop
• Full type safety with Typescript

Upcoming

• Combine multiple worker to one endpoint (stitch)

Installation

1yarn add helix-flare
2
3## or
4
5npm install --save helix-flare

API

helixFlare(request: Request, schema: GraphQLSchema)

Returns: Promise<Response>

This will take a request from a worker (or durable object) and return a response via GraphQL.

All you need is:

1import helixFlare from 'helix-flare'
2import { makeExecutableSchema } from '@graphql-tools/schema'
3
4export default {
5  async fetch(request: Request) {
6    const typeDefs = /* GraphQL */ `
7      type Query {
8        hello: String!
9      }
10    `
11    const schema = makeExecutableSchema({
12      typeDefs,
13      resolvers: {
14        Query: { user: () => 'Hello World 🌍' },
15      },
16    })
17
18    return helixFlare(request, schema)
19  },
20}

With just a few lines you got your GraphQL server up and running.

Example call to worker:

1const workerURL = 'https://my.worker.dev/graphql'
2
3fetch(workerURL, {
4  body: JSON.stringify({ query: '{ hello }' }),
5  method: 'POST',
6  headers: { 'Content-Type': 'application/json' },
7})
8
9// ➜ 'Hello World 🌍'

Head to the GraphQL docs for more information on how to build a GraphQL server.

createExecutor(request, selectDurableObject)

Allows you to resolve a query by forwarding the request to a durable object. The durable object can be selected by inspecting the graphql query in the selectDurableObject callback.

Returns: AsyncExecutor

request: Request

The request passed to the worker or durable object.

selectDurableObject: (args, context) => Promise<DurableObjectStub>

With this callback function you can select which durable object this request should be delegated to.

1import helixFlare, { createExecutor } from 'helix-flare'
2import { makeExecutableSchema } from '@graphql-tools/schema'
3import { wrapSchema } from '@graphql-tools/wrap'
4
5export default {
6  async fetch(request, env) {
7    const schema = wrapSchema({
8      schema: makeExecutableSchema({
9        // type defs and resolvers here…
10      }),
11      // with this executor the requests will be delegated a durable object
12      executor: createExecutor(request, async (args) => {
13        return env.DURABLE_OBJECT.get(args.userId)
14      }),
15    })
16
17    return helixFlare(request, schema)
18  },
19}

createSubscription(options)

Returns: [emitter, resolver]

Inspired by hooks this function returns an emitter and a resolver as a tuple. With the emitter you can publish new events to the client. The resolver can just be used as is and put into the resolvers of your schema.

topic

Type: string

An identifier for the subscription that is used internally.

resolve

Type: Function
Default: (value) => value

This is to make subscription emissions less verbose. See example below for more clarity.

getInitialValue

Type: Function
Default: undefined

1import helixFlare, { createSubscription } from 'helix-flare'
2import { makeExecutableSchema } from '@graphql-tools/schema'
3
4export default {
5  async fetch(request, env) {
6    const [emit, resolver] = createSubscription({
7      topic: 'comments',
8    })
9
10    const typeDefs = /* GraphQL */ `
11      type Subscription {
12        comments($id: ID!): [String!]!
13      }
14    `
15
16    const schema = makeExecutableSchema({
17      typeDefs,
18      resolvers: {
19        comments: {
20          subscribe: resolver,
21        },
22      },
23    })
24
25    return helixFlare(request, schema)
26
27    // Now you can emit new comments like so:
28    emit({ comments: 'This is a new comment 💬' })
29  },
30}

To avoid repeating the need to emit the structure of the subscription resolver everytime you can use the resolve option:

1const [emit, resolver] = createSubscription({
2  topic: 'comments',
3  resolve: (value) => ({ comments: value }),
4})
5
6// Now you can simply just emit the following
7emit('This is a new comment 💬')

Usage with envelop

1import helixFlare from 'helix-flare/envelop'
2import { envelop, useSchema } from '@envelop/core'
3
4const schema = `…`
5
6const getEnvelopedFn = envelop({
7  plugins: [
8    useSchema(schema),
9    // add other envelop plugins here…
10  ],
11})
12
13// worker
14export default {
15  fetch(request: Request) {
16    return helixFlare(request, getEnvelopedFn)
17  },
18}

Examples

1import helixFlare from 'helix-flare'
2import { makeExecutableSchema } from '@graphql-tools/schema'
3
4export default {
5  async fetch(request: Request) {
6    const typeDefs = /* GraphQL */ `
7      type Query {
8        hello(name: String!): String!
9      }
10    `
11
12    const schema = makeExecutableSchema({
13      typeDefs,
14      resolvers: {
15        Query: {
16          user: (_, { name }) => `Hello ${name}!`,
17        },
18      },
19    })
20
21    return helixFlare(request, schema)
22  },
23}

1// worker.ts
2import helixFlare, { createExecutor } from 'helix-flare'
3import { makeExecutableSchema } from '@graphql-tools/schema'
4import { wrapSchema } from '@graphql-tools/wrap'
5
6const typeDefs = /* GraphQL */ `
7  type Post {
8    id: Int!
9    title: String
10    votes: Int
11  }
12
13  type Mutation {
14    upvotePost(postId: Int!): Post
15  }
16`
17export default {
18  async fetch(request: Request, env: Env) {
19    const schema = wrapSchema({
20      schema: makeExecutableSchema({ typeDefs }),
21      executor: createExecutor<{ postId?: string }>(request, async (args) => {
22        if (!args.postId) {
23          throw new Error('No postId argument found')
24        }
25
26        const doId = env.PostDurableObject.idFromString(args.postId)
27        return env.PostDurableObject.get(doId)
28      }),
29    })
30
31    return helixFlare(request, schema)
32  },
33}

1// schema.ts
2const schema = /* GraphQL */ `
3  type Post {
4    id: Int!
5    votes: Int
6  }
7
8  type Subscription {
9    """
10    Returns the positions for given live Id
11    """
12    subscribePostVotes(postId: Int!): Int!
13  }
14
15  type Mutation {
16    upvotePost(postId: Int!): Post
17  }
18`
19export default schema

1// worker.ts
2import helixFlare, { createExecutor } from 'helix-flare'
3import { makeExecutableSchema } from '@graphql-tools/schema'
4import { wrapSchema } from '@graphql-tools/wrap'
5import typeDefs from './schema'
6
7export { Post } from './PostObject'
8
9// ExportedHandler from `@cloudflare/workers-types`
10type WorkerType = ExportedHandler<{ PostDurableObject: DurableObjectStub }>
11
12const Worker: WorkerType = {
13  async fetch(request, env) {
14    const schema = wrapSchema({
15      schema: makeExecutableSchema({ typeDefs }),
16      executor: createExecutor(request, async (args, context) => {
17        if (!args.postId) {
18          throw new Error('No postId argument found')
19        }
20
21        const doId = env.PostDurableObject.idFromString(args.postId)
22
23        return env.PostDurableObject.get(doId)
24      }),
25    })
26
27    return helixFlare(request, schema)
28  },
29}
30
31export default Worker

1// PostObject.ts
2import { makeExecutableSchema } from '@graphql-tools/schema'
3import { wrapSchema } from '@graphql-tools/wrap'
4import helixFlare, { createExecutor, createSubscription } from 'helix-flare'
5import typeDefs from './typedefs'
6
7export class Post implements DurableObject {
8  private likes = 0
9
10  async fetch() {
11    const [emitLikes, likesSubscriptionResolver] = createSubscription<
12      number,
13      { subscribePostVotes: number }
14    >({
15      topic: 'likes',
16      resolve: (value) => ({ subscribePostVotes: value }),
17      getInitialValue: () => this.likes,
18    })
19
20    const resolvers = {
21      Mutation: {
22        upvotePost: () => {
23          this.likes++
24          emitLikes(this.likes)
25
26          return { likes: this.likes, id: this.state.id }
27        },
28      },
29      Subscription: {
30        subscribePostVotes: {
31          subscribe: likesSubscriptionResolver,
32        },
33      },
34    }
35
36    const schema = makeExecutableSchema({
37      resolvers,
38      typeDefs,
39    })
40
41    return helixFlare(request, schema)
42  }
43}