graphql-tools-sequelize
v2.3.0
Integration of GraphQL-Tools and Sequelize ORM
0/weekUpdated 3 years agoMITUnpacked: 169.2 KB
Published by Dr. Ralf S. Engelschall
npm install graphql-tools-sequelize
GraphQL-Tools-Sequelize
========================
Integration of GraphQL-Tools and
Sequelize Object-Relational-Mapper (ORM).
About
-----
This Node.js module provides an integration of
the GraphQL.js wrapper
GraphQL-Tools and the
Sequelize Object-Relational-Mapper (ORM) in order to operate on
the entities and their relationships of an underlying RDBMS through GraphQL.
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 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:
`jsquery { OrgUnits { name } }
const query =
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, which even
provides a network interface through HAPI and the
GraphiQL web interface on top of it
(with the help of its HAPI integration HAPI-Plugin-GraphiQL).
Application Programming Interface (API)
---------------------------------------
- import GraphQLToolsSequelize from "graphql-tools-sequelize"
Creates a new GraphQL-Tools-Sequelize instance with an existing Sequelize instance sequelize.options
The have to given, but can be an empty object. It can contain the following
fields:
- validator(type: String, obj: Object, ctx: Object): Promise:obj
Optionally validate entity object (of entity type type)ctx
just before create or update operations. If the resulting
Promise is rejected, the create or update operation fails.
The object is just passed through from the GraphQL.graphql() call.
- authorizer(moment: String, op: String, type: String, obj: Object, ctx: Object): Promise:obj
Optionally authorize entity object (of entity type type)op
for operation (create, read, update or delete) at moment (before or after).read
Notice that for there is no before and for delete there is no after, of course. The ctx object is just passed through fromGraphQL.graphql()
the call. If the resulting Promise is rejectedfalse
or returns , the operation fails.
- tracer(record: Object, ctx: Object): Promise:record
Optionally trace the operation via the action . The fields of record are:{ op: String, arity: String, dstType: String, dstIds: String[], dstAttrs: String[] }
.ctx
The 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":id
Configures the GraphQL name of the mandatory unique identifier attribute on each entity.
The default name is .
- idtype: String = "UUID":UUID
Configures the GraphQL type of the mandatory unique identifier attribute on each entity.
The default type assumes that you define the GraphQL scalar type UUID with the help of
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 to generate UUIDs of version 1.
- hcname: String = "hc":hc
Configures the GraphQL name of the optional hash-code attribute on each entity.
The default name is . This attribute is NOT persisted and instead calculated on
the fly and is intended to be used for optimistic locking purposes.
- hctype: String = "UUID":UUID
Configures the GraphQL type of the optional hash-code attribute on each entity.
The default type assumes that you define the GraphQL scalar type UUID with the help of
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 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
- 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
- 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 -- eitherrelation
directly (in case is the empty string) or via relationshiprelation
. The target is either just the name foo of an entityfoo
type (for relationship of cardinality 0..1) or foo* (forrelation
relationship of cardinality 0..N). Based on the combination of
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
+query
"# by either an (optionally available) full-text-search ()\n" +where
"# or an (always available) attribute-based condition (),\n" +include
"# optionally filter them by a condition on some relationships (),\n" +order
"# optionally sort them (),\n" +offset
"# optionally start the result set at the n-th entity (zero-based ), and\n" +limit
"# optionally reduce the result set to a maximum number of entities ().\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
+where
"# optionally filter them by a condition (),\n" +include
"# optionally filter them by a condition on some relationships (),\n" +order
"# optionally sort them (),\n" +offset
"# optionally start the result set at the n-th entity (zero-based ), and\n" +limit
"# optionally reduce the result set to a maximum number of entities ().\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 theid
(technical) primary key of an entity. By default, the type of
field is UUID, but this can be overridden (see idtype
configuration option). In case of the type , it is assumedUUID
that you define the GraphQL scalar type with the help of
GraphQL-Tools-Types.
Notice: all entities are required to have the field id and the typeid
of all fields have to be the same. But this does not prevent youid
from having additional domain-specific primary keys per entity of an
arbitrary type, of course. GraphQL-Tools-Sequelize just uses the field for its functionality.
In addition, the scalar type JSON` always has to be defined with the help of
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.