Repository files navigation

Create a graphql service easily, integrated with typeorm, middlewares, standard logs, and more!

Polaris is a set of libraries that help you create the perfect graphql service, integrated with type orm and the hottest API standards.polaris-core organizes all of the libraries for you, and let you create your graphql service as easily as it can be.

• GraphQL service creation (integrated with apollo-server & express)
• Auto soft deletion of entities
• Fetching Deltas of entities (including irrelevant entities)
• Support realities
• Standard errors
• Standard logs
• Standard GraphQL scalars

This is the server that you will use in order to create your own standardized GraphQL server.
PolarisServer usesApolloServer and starts the server withExpress.

Through this interface you should set the following configurations which will be supplied to thePolarisServer:

• typeDefs (any) - The GraphQL schema written in SDL (Schema Definition Language).This will be used in order to create your GraphQL API.
• resolvers (any) - The GraphQL resolvers that will be tied to your GraphQL schema.This object contains functions and logic for the GraphQL engine to invoke when using fields from the schema.
• port (number) - Specify a port thePolarisServer should start the server on.
• applicationProperties (ApplicationProperties - optional) - Properties that describe your repository.If you don't provide those properties, the core will put 'v1' in the version.
• allowSubscription (boolean - optional) - Responsible for creating a websocket endpoint for graphql subscriptions.
• customMiddlewares (any[] - optional) - Custom middlewares that can be provided thePolarisServer with.
• customContext ((context: any, connection?: Connection) => any - optional) - You can provide thePolarisServer your own custom context.If you do not set your custom context, the core will use a default context.
• loggerConfiguration (LoggerConfiguration - optional) - This is an interface that defines the logger in thePolarisServer.If you do not provide this property, the core will use default values for the logger.
• middlewareConfiguration (MiddlewareConfiguration - optional) - This is an interface that defines what core middlewares should be activated/disabled.
• connection (Connection - optional) - This class represents your connection with the database. Used in the core middlewares.
• allowSubscription (boolean - optional) -Default: false. Responsible for creating a websocket endpoint for graphql subscriptions.
• shouldAddWarningsToExtensions (boolean - optional) -Default: true. Specifies whether to return the warnings in the response extensions or not.
• allowMandatoryHeaders (boolean - optional) -Default: false. When set to true, every request must havereality-id andrequesting-sys headers.

As mentioned above, this interface defines what core middlewares should be activated/disabled.

• allowDataVersionAndIrrelevantEntitiesMiddleware (boolean) - Determine ifDataVersionMiddleware andIrrelevantEntitiesMiddleware should be applied to the request.
• allowSoftDeleteMiddleware (boolean) - Determine ifSoftDeleteMiddleware should be applied to the request.
• allowRealityMiddleware (boolean) - Determine ifRealityMiddleware should be applied to the request.

First we will define the new context type, pay attention that we just added a new field in the root of the context,and a new header in the request headers object.

import{PolarisGraphQLContext,PolarisRequestHeaders}from'@enigmatis/polaris-core';interfaceCustomRequestHeadersextendsPolarisRequestHeaders{customHeader?:string|string[];}exportinterfaceCustomContextextendsPolarisGraphQLContext{customField:number;requestHeaders:CustomRequestHeaders;}

Then we will pass the custom context like this:

import{ExpressContext,PolarisServer}from'@enigmatis/polaris-core';consttypeDefs=`...`;constresolvers={ ...};constcustomContext=(context:ExpressContext):Partial<CustomContext>=>{const{ req}=context;return{customField:1000,requestHeaders:{customHeader:req.headers['custom-header'],},};};constserver=newPolarisServer({    typeDefs,    resolvers,port:8082,    customContext,});

Add the Subscription object to your schema

export const typeDefs = `    type Query {        ...    }    type Mutation {        ...        updateBook(id: String!, newTitle: String!): [Book]!        ...    }    type Subscription {        bookUpdated: Book    }    type Book implements RepositoryEntity {        ...    }`;

now let's implement the subscription resolver logic

import { PubSub } from '@enigmatis/polaris-core';const pubsub = new PubSub();const BOOK_UPDATED = 'BOOK_UPDATED';export const resolvers = {    Query: { ... },    Mutation: { ... },    Subscription: {        bookUpdated: {            subscribe: () => pubsub.asyncIterator([BOOK_UPDATED]),        },    },};

and inside the updateBook resolver we will publish the book that got changed:

pubsub.publish(BOOK_UPDATED, { bookUpdated: myBook })

When you create the server you have to allow subscriptions, so the server could create the endpoint

const server = new PolarisServer({    typeDefs,    resolvers,    port: 8080,    allowSubscription: true,});

Just pay attention that in case you are using custom context as well, the subscription context will be different,you can handle it like so:

const customContext = (context: ExpressContext): Partial<CustomContext> => {    const { req, connection } = context;    const headers = req ? req.headers : connection?.context;    return {        customField: 1000,        requestHeaders: {            customHeader: headers['custom-header'],        },    };};

In order to have the ability of warnings, which returned in the extensions of the response, you will need to supply them topolaris. you can supply the warnings through the context. let's see an example:

allBooksWithWarnings: async (    parent: any,    args: any,    context: PolarisGraphQLContext,): Promise<Book[]> => {    const connection = getPolarisConnectionManager().get();    context.returnedExtensions.warnings = ['warning 1', 'warning 2'];    return connection.getRepository(Book).find(context, { relations: ['author'] });}

And let's see an example of response with the warnings:

{"data": {"allBooks": [            {"id":"53afd7e5-bf59-4408-acbc-1c5ebb5ff146","title":"Book1","author": {"firstName":"Author1","lastName":"First"                }            },            {"id":"4fab24e4-f584-4077-bb93-09cdfc88b202","title":"Book2","author": {"firstName":"Author2","lastName":"Two"                }            }        ]    },"extensions": {"globalDataVersion":2,"warnings": ["warning 1","warning 2"]    }}

You can see inside theextensions that we have the warnings we defined earlier.

import{ApplicationProperties,PolarisServer}from'@enigmatis/polaris-core';consttypeDefs=`    type Query {        allPersons: [Person]    }    type Person implements RepositoryEntity {        id: String!        deleted: Boolean!        createdBy: String!        creationTime: DateTime!        lastUpdatedBy: String        lastUpdateTime: DateTime        realityId: Int!        name: String    }`;constresolvers={Query:{allPersons:()=>[{name:'foo bar',realityId:0,deleted:false,dataVersion:2},{name:'superman',realityId:0,deleted:true,dataVersion:3},{name:'hello world',realityId:1,deleted:true,dataVersion:3},{name:'something',realityId:1,deleted:false,dataVersion:4},],},};constapplicationProperties:ApplicationProperties={id:'p0laris-c0re',name:'polaris-core',version:'v1',environment:'environment',component:'component',};constserver=newPolarisServer({    typeDefs,    resolvers,port:4000,    applicationProperties,});server.start();

For any additional help and requests, feel free to contact us 😄