orchid-graphql v1.5.1
orchid-graphql
A helper library to resolve GraphQL queries directly with Orchid ORM tables and relations.
- Highly effective: selects only requested fields and relations.
- Unlimited nested resolvers.
- Pagination.
- Filters like
{ date: "2020-10-01", category__in: ["News", "Politics"] }
. - Hook into (sub)queries with query modifiers.
- Hook into field results to restrict access to sensitive information.
Note that there is a sister project: objection-graphql-resolver
which does the same for Objection.js ORM.
Status and limitations
This is pre-release and not battle tested. orchid-graphql
is a quick adaptation of objection-graphql-resolver
.
In particular the typings are not ready. The resolver returns a generic Query
most of the time.
Install
npm i orchid-graphql
Minimal all-in-one example
Run GraphQL server:
// Everything is put into a single file for demonstration purposes.
//
// In real projects, you will want to separate tables, typedefs,
// resolvers, and the server into their own modules.
import { ApolloServer, ApolloServerOptions } from "@apollo/server"
import { startStandaloneServer } from "@apollo/server/standalone"
import gql from "graphql-tag"
import * as r from "orchid-graphql"
import { createBaseTable, orchidORM } from "orchid-orm"
// Define database tables
const BaseTable = createBaseTable()
class PostTable extends BaseTable {
readonly table = "post"
columns = this.setColumns((t) => ({
id: t.identity().primaryKey(),
text: t.text(0, 5000),
}))
}
const db = orchidORM(
{
databaseURL: process.env.DATABASE_URL,
log: true,
},
{
post: PostTable,
},
)
await db.$query`
create table post (
id serial primary key,
text text not null
);
`
// Define GraphQL schema
const typeDefs = gql`
type Post {
id: Int!
text: String!
}
type Mutation {
create_post(text: String!): Post!
}
type Query {
posts: [Post!]!
}
`
// Map GraphQL types to table resolvers
const graph = r.graph({
Post: r.table(db.post),
})
// Define resolvers
const resolvers: ApolloServerOptions<any>["resolvers"] = {
Mutation: {
async create_post(_parent, args, context, info) {
const post = await db.post.create(args)
return await graph.resolve(db.post.find(post.id), { context, info })
},
},
Query: {
async posts(_parent, _args, context, info) {
return await graph.resolve(db.post, { context, info })
},
},
}
// Start GraphQL server
const server = new ApolloServer({ typeDefs, resolvers })
const { url } = await startStandaloneServer(server, {
listen: { port: 4000 },
})
console.log(`Listening on ${url}`)
Query it with GraphQL client:
import { GraphQLClient } from "graphql-request"
import gql from "graphql-tag"
const client = new GraphQLClient("http://127.0.0.1:4000")
await client.request(
gql`
mutation create_post($text: String!) {
new_post: create_post(text: $text) {
id
}
}
`,
{ text: "Hello, world!" },
)
const { posts } = await client.request(gql`
query {
posts {
id
text
}
}
`)
console.log(posts)
Relations
Relations will be fetched automatically when resolving nested fields.
Example:
const graph = r.graph({
User: r.type(db.user),
Post: r.type(db.post),
})
query posts_with_author {
posts {
id
text
# will use subquery if requested
author {
name
}
}
}
query user_with_posts {
user(id: ID!) {
name
# will use subquery if requested
posts {
id
text
}
}
}
More details and examples for relations.
Fields access
Access to individual fields can be limited:
const graph = r.graph({
User: r.type(db.user, {
fields: {
id: true,
name: true,
// other fields not specified here, such as user password,
// will not be accessible
},
}),
})
This API also allows to fine-tune field selectors, see API section below.
Pagination
Root queries and -to-many nested relations can be paginated.
const graph = r.graph({
User: r.type(db.user, {
fields: {
id: true,
name: true,
// user.posts will be a page with nodes and continuation cursor
posts: r.page(r.cursor({ fields: ["-id"], take: 10 })),
},
}),
Post: r.type(db.post),
})
To paginate root query, use:
const resolvers = {
Query: {
posts: async (parent, args, context, info) => {
return await graph.resolvePage(
db.post,
r.cursor({ take: 10, fields: ["-id"] }),
{ context, info },
)
},
},
}
More details and examples for pagination.
Filters
Both root and nested queries can be filtered with GraphQL arguments:
query {
posts(filter: { date: "2020-10-01", author_id__in: [123, 456] }) {
id
date
text
author {
id
name
}
}
}
Filters will run against database fields, or call field modifiers.
More details and examples for filters.
API
import * as r from "orchid-graphql"
const graph = r.graph(
// Map GraphQL types to table resolvers (required)
{
Post: r.table(
// orchid-orm bound table (required)
db.post,
// Table resolver options
{
// List fields that can be accessed via GraphQL
// if not provided, all fields can be accessed
fields: {
// Select field from database
id: true,
// Descend into relation
// (related table must be also registered in this graph resolver)
author: true,
// Modify query when this field is resolved
preview: (q) =>
q.select({ preview: q.sql<string>`substr(text,1,100)` }),
// Same as text: true
text: r.field(),
// Custom field resolver
text2: r.field({
// Table field, if different from GraphQL field
tableField: "text",
}),
preview2: r.field({
// Modify query
modify: (q) =>
q.select({ preview2: q.sql<string>`substr(text,1,100)` }),
// Post-process selected value
transform(
// Selected value
preview,
// Current instance
post,
// Field resolve context: graph, tree, type, field, filters, context
context,
) {
if (preview.length < 100) {
return preview
} else {
return preview + "..."
}
},
}),
// Select all objects in -to-many relation
comments: true,
// Select all objects in -to-many relation
all_comments: r.relation({
// Table field, if different from GraphQL field
tableField: "comments",
// Enable filters on -to-many relation
filters: true,
// Modify subquery
modify: (q, { liked }) => q.where({ liked }).order({ id: "DESC" }),
// Post-process selected values, see r.field()
// transform: ...,
}),
// Paginate subquery in -to-many relation
comments_page: r.page(
// Paginator
r.cursor(
// Pagination options
// Default: { fields: ["id"], take: 10 }
{
// Which fields to use for ordering
// Prefix with - for descending sort
fields: ["name", "-id"],
// How many object to take per page
take: 10,
},
),
{
// All r.relation() options, such as:
tableField: "comments",
},
),
},
// Modify all queries to this table
modify: (
// ORM (sub)query
query,
// Table resolve context: graph, tree, type, filters, context
context,
) => query.where(context.tree.args).order({ id: "DESC" }),
// Allow all fields (`fields` will be used for overrides)
allowAllFields: true,
// Allow filters in all relations
allowAllFilters: true,
},
),
},
// Graph options
{
// Allow all fields in all tables (`fields` will be used for overrides)
allowAllFields: true,
// Allow filters in all relations of all tables
allowAllFilters: true,
},
)
const resolvers = {
Query: {
posts: async (parent, args, context, info) => {
return await graph.resolve(
// Root query (required)
db.post,
// Options (required)
{
// Resolver context
context,
// GraphQLResolveInfo object, as passed by GraphQL executor (required)
info,
// Enable filters
filters: true,
},
)
},
posts_page: async (parent, args, context, info) => {
return await graph.resolvePage(
// Root query (required)
db.post,
// Paginator (required)
r.cursor({ fields: ["-id"], take: 10 }),
// Options (required) - see graph.resolve
{
context,
info,
filters: true,
},
)
},
},
}
graph.resolve(db.user.find(1), {
// As comes from Apollo
context,
// As comes from Apollo
info,
// If resolving subfield
path: ["subfield"],
})
3 months ago
3 months ago
3 months ago
4 months ago
9 months ago
9 months ago
9 months ago
9 months ago
10 months ago
11 months ago
11 months ago
11 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago
12 months ago