Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/rse/graphql-tools-sequelize

Integration of GraphQL-Tools and Sequelize ORM
https://github.com/rse/graphql-tools-sequelize

graphql graphql-tools orm sequelize sql

Last synced: 1 day ago
JSON representation

Integration of GraphQL-Tools and Sequelize ORM

Lists

README 

        

GraphQL-Tools-Sequelize

========================



Integration of [GraphQL-Tools](https://github.com/apollostack/graphql-tools) and

[Sequelize](http://sequelizejs.com) Object-Relational-Mapper (ORM).













About

-----



This [Node.js](https://nodejs.org) module provides an integration of

the [GraphQL.js](https://github.com/graphql/graphql-js) wrapper

[GraphQL-Tools](https://github.com/apollostack/graphql-tools) and the

[Sequelize](http://sequelizejs.com) Object-Relational-Mapper (ORM) in order to operate on

the entities and their relationships of an underlying RDBMS through [GraphQL](http://graphql.org/).

It provides functions for GraphQL schema definition entries and their corresponding resolver functions

for querying and mutating entities and their relationships through GraphQL in a natural

Object-Oriented (OO) way. It optionally provides Full-Text-Search (FTS) functionality

through [ElasticLunr](http://elasticlunr.com/) and validation, authorization and tracing hooks.

It provides an elaborate CRUD (Create, Read, Update, Delete) functionality for the entities and

their relationships.



Installation

------------



```shell

$ npm install \

  graphql \

  graphql-tools \

  graphql-tools-types \

  graphql-tools-sequelize \

  sequelize \

  --save-dev

```



Usage

-----



Suppose we have a simple domain model, consisting of the two

entities `OrgUnit` and `Person` and some relationships between them

(in UML Class Diagram notation):



```txt

 parentUnit                           supervisor

 +------+                             +------+

 |      |                             |      |

 |      V 0..1                   0..1 V      |

 |   +-----------+           +-----------+   |

 +---| OrgUnit   |  belongsTo| Person    |---+

     |-----------|<----------|-----------|

     | id        |           | id        |

     | initials  |--------->*| initials  |

     | name      |  members  | name      |

     +-----------+           +-----------+

               |                 ^

               |     director    |

               +-----------------+

```



With Sequelize ORM this could be defined on the RDBMS level as:



```js

import Sequelize from "sequelize"



const db = new Sequelize(...)

const dm = {}



dm.OrgUnit = db.define("OrgUnit", {

    id:         { type: Sequelize.UUID,        primaryKey: true  },

    initials:   { type: Sequelize.STRING(3),   allowNull:  false },

    name:       { type: Sequelize.STRING(100), allowNull:  false }

})

dm.Person = db.define("Person", {

    id:         { type: Sequelize.UUID,        primaryKey: true  },

    initials:   { type: Sequelize.STRING(3),   allowNull:  false },

    name:       { type: Sequelize.STRING(100), allowNull:  false }

})

dm.OrgUnit.belongsTo(dm.OrgUnit, { as: "parentUnit", foreignKey: "parentUnitId" })

dm.Person .belongsTo(dm.Person,  { as: "supervisor", foreignKey: "personId"     })

dm.Person .belongsTo(dm.OrgUnit, { as: "belongsTo",  foreignKey: "orgUnitId"    })

dm.OrgUnit.hasMany  (dm.Person,  { as: "members",    foreignKey: "orgUnitId"    })

dm.OrgUnit.hasOne   (dm.Person,  { as: "director",   foreignKey: "directorId"   })

```



You then establish a GraphQL-to-Sequelize mapping like this:



```js

import GraphQLToolsSequelize from "graphql-tools-sequelize"



const gts = new GraphQLToolsSequelize(db)

await gts.boot()

```



Now you can use this mapping and its factory functions to conveniently

create a GraphQL schema definition as the interface for operating on

your domain model:



```js

const definition = `

    schema {

        query:    Root

        mutation: Root

    }

    scalar UUID

    scalar JSON

    type Root {

        ${gts.entityQuerySchema("Root", "", "OrgUnit")}

        ${gts.entityQuerySchema("Root", "", "OrgUnit*")}

        ${gts.entityQuerySchema("Root", "", "Person")}

        ${gts.entityQuerySchema("Root", "", "Person*")}

    }

    type OrgUnit {

        ${gts.attrIdSchema("OrgUnit")}

        ${gts.attrHcSchema("OrgUnit")}

        initials: String

        name: String

        director: Person

        members: [Person]!

        parentUnit: OrgUnit

        ${gts.entityCloneSchema ("OrgUnit")}

        ${gts.entityCreateSchema("OrgUnit")}

        ${gts.entityUpdateSchema("OrgUnit")}

        ${gts.entityDeleteSchema("OrgUnit")}

    }

    type Person {

        ${gts.attrIdSchema("Person")}

        ${gts.attrHcSchema("Person")}

        initials: String

        name: String

        belongsTo: OrgUnit

        supervisor: Person

        ${gts.entityCloneSchema ("Person")}

        ${gts.entityCreateSchema("Person")}

        ${gts.entityUpdateSchema("Person")}

        ${gts.entityDeleteSchema("Person")}

    }

`

```



You also use it and its factory functions to define the corresponding

GraphQL resolver functions:



```js

import GraphQLToolsTypes from "graphql-tools-types"



const resolvers = {

    UUID: GraphQLToolsTypes.UUID({ name: "UUID", storage: "string" }),

    JSON: GraphQLToolsTypes.JSON({ name: "JSON" }),

    Root: {

        OrgUnit:    gts.entityQueryResolver ("Root", "", "OrgUnit"),

        OrgUnits:   gts.entityQueryResolver ("Root", "", "OrgUnit*"),

        Person:     gts.entityQueryResolver ("Root", "", "Person"),

        Persons:    gts.entityQueryResolver ("Root", "", "Person*"),

    },

    OrgUnit: {

        id:         gts.attrIdResolver      ("OrgUnit"),

        hc:         gts.attrHcResolver      ("OrgUnit"),

        director:   gts.entityQueryResolver ("OrgUnit", "director",   "Person"),

        members:    gts.entityQueryResolver ("OrgUnit", "members",    "Person*"),

        parentUnit: gts.entityQueryResolver ("OrgUnit", "parentUnit", "OrgUnit"),

        clone:      gts.entityCloneResolver ("OrgUnit"),

        create:     gts.entityCreateResolver("OrgUnit"),

        update:     gts.entityUpdateResolver("OrgUnit"),

        delete:     gts.entityDeleteResolver("OrgUnit")

    },

    Person: {

        id:         gts.attrIdResolver      ("Person"),

        hc:         gts.attrHcResolver      ("Person"),

        belongsTo:  gts.entityQueryResolver ("Person", "belongsTo",  "OrgUnit"),

        supervisor: gts.entityQueryResolver ("Person", "supervisor", "Person"),

        clone:      gts.entityCloneResolver ("Person"),

        create:     gts.entityCreateResolver("Person"),

        update:     gts.entityUpdateResolver("Person"),

        delete:     gts.entityDeleteResolver("Person")

    }

}

```



Then you use the established schema definition and resolver functions to

generate an executable GraphQL schema with the help of GraphQL-Tools:



```js

import * as GraphQLTools from "graphql-tools"



const schema = GraphQLTools.makeExecutableSchema({

    typeDefs: [ definition ],

    resolvers: resolvers

})

```



Finally, you now can execute GraphQL queries against your RDBMS:



```js

const query = `query { OrgUnits { name } }`

const variables = {}



GraphQL.graphql(schema, query, null, null, variables).then((result) => {

    console.log("OK", util.inspect(result, { depth: null, colors: true }))

}).catch((result) => {

    console.log("ERROR", result)

})

```



The following GraphQL mutation is a more elaborate example of how

CRUD operations look like and what is possible:



```txt

mutation {

    m1: Person {

        c1: create(id: "c9965340-a6c8-11e6-ac95-080027e303e4", with: {

            initials:   "BB",

            name:       "Big Boss"

        }) { id }

        c2: create(id: "ca1ace2c-a6c8-11e6-8ef0-080027e303e4", with: {

            initials:   "JD",

            name:       "John Doe",

            supervisor: "c9965340-a6c8-11e6-ac95-080027e303e4"

        }) { id }

    }

    m2: OrgUnit {

        c1: create(id: "ca8c588a-a6c8-11e6-8f19-080027e303e4", with: {

            initials: "EH",

            name:     "Example Holding",

            director: "c9965340-a6c8-11e6-ac95-080027e303e4"

        }) { id }

        c2: create(id: "cabaa4ce-a6c8-11e6-9d6d-080027e303e4", with: {

            initials:   "EC",

            name:       "Example Corporation",

            parentUnit: "ca8c588a-a6c8-11e6-8f19-080027e303e4",

            director:   "ca1ace2c-a6c8-11e6-8ef0-080027e303e4",

            members: { set: [

                "c9965340-a6c8-11e6-ac95-080027e303e4",

                "ca1ace2c-a6c8-11e6-8ef0-080027e303e4"

            ] }

        }) { id }

    }

    q1: OrgUnits(where: {

        initials: "EC"

    }) {

        name

        director   { initials name }

        members    { initials name }

        parentUnit {

            name

            director   { initials name }

            members    { initials name }

        }

    }

    m3: Person(id: "c9965340-a6c8-11e6-ac95-080027e303e4") {

        update(with: { initials: "XXX" }) {

            id initials name

        }

    }

    c1: Person(id: "c9965340-a6c8-11e6-ac95-080027e303e4") {

        clone {

            id initials name

        }

    }

    m4: Person(id: "c9965340-a6c8-11e6-ac95-080027e303e4") {

        delete

    }

    q2: Persons {

        id initials name

    }

}

```



For more details, see the [all-in-one sample](./sample/), which even

provides a network interface through [HAPI](http://hapijs.com/) and the

[GraphiQL](https://github.com/graphql/graphiql) web interface on top of it

(with the help of its HAPI integration [HAPI-Plugin-GraphiQL](https://github.com/rse/hapi-plugin-graphiql)).



Application Programming Interface (API)

---------------------------------------



- `import GraphQLToolsSequelize from "graphql-tools-sequelize"`


  `gts = new GraphQLToolsSequelize(sequelize: Sequelize, options?: Object)`



  Creates a new GraphQL-Tools-Sequelize instance with an existing Sequelize instance `sequelize`.

  The `options` have to given, but can be an empty object. It can contain the following

  fields:



    - `validator(type: String, obj: Object, ctx: Object): Promise`:


      Optionally validate entity object `obj` (of entity type `type`)

      just before create or update operations. If the resulting

      Promise is rejected, the create or update operation fails.

      The `ctx` object is just passed through from the `GraphQL.graphql()` call.



    - `authorizer(moment: String, op: String, type: String, obj: Object, ctx: Object): Promise`:


      Optionally authorize entity object `obj` (of entity type `type`)

      for operation `op` (`create`, `read`, `update` or `delete`) at `moment` (`before` or `after`).

	  Notice that for `read` there is no `before` and for `delete` there is no `after`, of course. The `ctx` object is just passed through from

      the `GraphQL.graphql()` call. If the resulting Promise is rejected

      or returns `false`, the operation fails.



    - `tracer(record: Object, ctx: Object): Promise`:


      Optionally trace the operation via the action `record`. The fields of `record` are:

      `{ op: String, arity: String, dstType: String, dstIds: String[], dstAttrs: String[] }`.

      The `ctx` object is just passed through from the `GraphQL.graphql()` call.



    - `fts: { [String]: String[] }`:


      Enables the Full-Text-Search (FTS) mechanism for all configured entity types

      and their listed attributes.



    - `idname: String = "id"`:


      Configures the GraphQL name of the mandatory unique identifier attribute on each entity.

      The default name is `id`.



    - `idtype: String = "UUID"`:


      Configures the GraphQL type of the mandatory unique identifier attribute on each entity.

      The default type `UUID` assumes that you define the GraphQL scalar type `UUID` with the help of

      [GraphQL-Tools-Types](https://github.com/rse/graphql-tools-types).



    - `idmake: Function = () => (new UUID(1)).format()`:


      Configures a function for generating unique identifiers for the mandatory unique identifier attribute on each entity.

      The default uses [pure-uuid](https://github.com/rse/pure-uuid) to generate UUIDs of version 1.



    - `hcname: String = "hc"`:


      Configures the GraphQL name of the optional hash-code attribute on each entity.

      The default name is `hc`. This attribute is NOT persisted and instead calculated on

      the fly and is intended to be used for optimistic locking purposes.



    - `hctype: String = "UUID"`:


      Configures the GraphQL type of the optional hash-code attribute on each entity.

      The default type `UUID` assumes that you define the GraphQL scalar type `UUID` with the help of

      [GraphQL-Tools-Types](https://github.com/rse/graphql-tools-types).



    - `hcmake: Function = (data) => (new UUID(5, "ns:URL", \`uri:gts:${data}\`)).format()`:


      Configures a function for generating hash-codes for the optional hash-code attribute on each entity.

      The default uses [pure-uuid](https://github.com/rse/pure-uuid) to generate UUIDs of version 5.



- `gts.boot(): Promise`:



  Bootstrap the GraphQL-Tools-Sequelize instance. It internally

  mainly initialized the Full-Text-Search (FTS) mechanism.



- `gts.attrIdSchema(source: String): String`,


  `gts.attrIdResolver(source: String): Function`:



  Generate a GraphQL schema entry and a corresponding GraphQL resolver

  function for querying the mandatory unique identifier attribute

  of an entity of type `source`. By default this generates a schema

  entry `: ` and a resolver which just returns

  `[]`. This mandatory unique identifier attribute has

  to be persisted and hence part of the Sequelize schema definition.



- `gts.attrHcSchema(source: String): String`,


  `gts.attrHcResolver(source: String): Function`:



  Generate a GraphQL schema entry and a corresponding GraphQL resolver

  function for querying the optional hash-code attribute of an

  entity of type `source`. By default this generates a schema entry

  `: ` and a resolver which returns something like

  `(data())`, where `data()` is an internal function

  which deterministically concatenates the values of all attributes of

  ``. This optional hash-code attribute has NOT to be persisted

  and hence SHOULD NOT BE part of the Sequelize schema definition.



- `gts.entityQuerySchema(source: String, relation: String, target: String): String`,


  `gts.entityQueryResolver(source: String, relation: String, target: String): Function`:



  Generate a GraphQL schema entry and a corresponding GraphQL resolver

  function for querying one, many or all entities of particular entity

  type `target` when coming from entity type `source` -- either

  directly (in case `relation` is the empty string) or via relationship

  `relation`. The `target` is either just the name `foo` of an entity

  type `foo` (for relationship of cardinality 0..1) or `foo*` (for

  relationship of cardinality 0..N). Based on the combination of

  `relation` and the cardinality of `target`, four distinct GraphQL schema

  entries (and corresponding GraphQL resolver functions) are generated:



    - empty `relation` and `target` cardinality 0..1:



        ```js

        `# Query one [${target}]() entity by its unique identifier (\`id\`) or condition (\`where\`) or` +

        `# open an anonymous context for the [${target}]() entity.\n` +

        `# The [${target}]() entity can be optionally filtered by a condition on some relationships (\`include\`).\n` +

        `${target}(id: ${idtype}, where: JSON, include: JSON): ${target}\n`

        ```



    - empty `relation` and `target` cardinality 0..N:



        ```js

        `# Query one or many [${target}]() entities,\n` +

        "# by either an (optionally available) full-text-search (`query`)\n" +

        "# or an (always available) attribute-based condition (`where`),\n" +

        "# optionally filter them by a condition on some relationships (`include`),\n" +

        "# optionally sort them (`order`),\n" +

        "# optionally start the result set at the n-th entity (zero-based `offset`), and\n" +

        "# optionally reduce the result set to a maximum number of entities (`limit`).\n" +

        `${target}s(fts: String, where: JSON, include: JSON, order: JSON, offset: Int = 0, limit: Int = 100): [${target}]!\n`

        ```



    - non-empty `relation` and `target` cardinality 0..1:



        ```js

        `# Query one [${target}]() entity by following the **${relation}** relation of [${source}]() entity.\n` +

        `# The [${target}]() entity can be optionally filtered by a condition (\`where\`).\n` +

        `# The [${target}]() entity can be optionally filtered by a condition on some relationships (\`include\`).\n` +

        `${relation}(where: JSON, include: JSON): ${target}\n`

        ```



    - non-empty `relation` and `target` cardinality 0..N:



        ```js

        `# Query one or many [${target}]() entities\n` +

        `# by following the **${relation}** relation of [${source}]() entity,\n` +

        "# optionally filter them by a condition (`where`),\n" +

        "# optionally filter them by a condition on some relationships (`include`),\n" +

        "# optionally sort them (`order`),\n" +

        "# optionally start the result set at the n-th entity (zero-based `offset`), and\n" +

        "# optionally reduce the result set to a maximum number of entities (`limit`).\n" +

        `${relation}(where: JSON, include: JSON, order: JSON, offset: Int = 0, limit: Int = 100): [${target}]!\n`

       ```



  The comments are intentionally also generated, as they document

  the entries in the GraphQL schema and are visible through

  GraphQL schema introspection tools like GraphiQL.



- `gts.entity{Create,Clone,Update,Delete}Schema(type: String): String`,


  `gts.entity{Create,Clone,Update,Delete}Resolver(type: String): Function`:



  Generate a GraphQL schema entry and a corresponding GraphQL resolver

  function for mutating one, many or all entities of particular entity

  type `type`. The following GraphQL schema

  entries (and corresponding GraphQL resolver functions) are generated:



    - For `entityCreate{Schema,Resolver}(type)`:



        ```js

        `# Create new [${type}]() entity, optionally with specified attributes (\`with\`).\n` +

        `create(id: ${idtype}, with: JSON): ${type}!\n`

        ```



    - For `entityClone{Schema,Resolver}(type)`:



        ```js

        `# Clone one [${type}]() entity by cloning its attributes (but not its relationships).\n` +

        `clone: ${type}!\n`

        ```



    - For `entityUpdate{Schema,Resolver}(type)`:



        ```js

        `# Update one [${type}]() entity with specified attributes (\`with\`).\n` +

        `update(with: JSON!): ${type}!\n`

        ```



    - For `entityDelete{Schema,Resolver}(type)`:



        ```js

        `# Delete one [${type}]() entity.\n` +

        `delete: ${idtype}!\n`

        ```



  The comments are intentionally also generated, as they document

  the entries in the GraphQL schema and are visible through

  GraphQL schema introspection tools like GraphiQL.



Assumptions

-----------



It is assumed that all your Sequelize entities have an attribute

`id` (see also `idname` configuration option) which is the

(technical) primary key of an entity. By default, the type of

field `id` is `UUID`, but this can be overridden (see `idtype`

configuration option). In case of the type `UUID`, it is assumed

that you define the GraphQL scalar type `UUID` with the help of

[GraphQL-Tools-Types](https://github.com/rse/graphql-tools-types).



Notice: all entities are required to have the field `id` and the type

of all `id` fields have to be the same. But this does not prevent you

from having *additional* domain-specific primary keys per entity of an

arbitrary type, of course. GraphQL-Tools-Sequelize just uses the field

`id` for its functionality.



In addition, the scalar type `JSON` always has to be defined with the help of

[GraphQL-Tools-Types](https://github.com/rse/graphql-tools-types).



License

-------



Copyright (c) 2016-2023 Dr. Ralf S. Engelschall (http://engelschall.com/)



Permission is hereby granted, free of charge, to any person obtaining

a copy of this software and associated documentation files (the

"Software"), to deal in the Software without restriction, including

without limitation the rights to use, copy, modify, merge, publish,

distribute, sublicense, and/or sell copies of the Software, and to

permit persons to whom the Software is furnished to do so, subject to

the following conditions:



The above copyright notice and this permission notice shall be included

in all copies or substantial portions of the Software.



THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,

EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY

CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,

TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.