@pothos/plugin-prisma 0.17.1 → 0.19.0

package/README.md

@@ -4,70 +4,74 @@ This plugin provides tighter integration with prisma, making it easier to define
 types, and helps solve n+1 queries for relations. It also has integrations for the relay plugin to
 make defining nodes and connections easy and efficient.
 
-## Disclaimers
+This plugin is NOT required to use prisma with Pothos, but does make things a lot easier and more
+efficient. See the [Using Prisma without a plugin](#using-prisma-without-a-plugin) section below for
+more details.
 
-This plugin is experimental, and will have some breaking changes in the future. DO NOT USE this
-plugin unless you are willing to deal with breaking changes in upcoming versions. This plugin may
-introduce BREAKING changes in minor versions until it's major version has been increased above 0.
+---
 
-This plugin is NOT required to build graphs backed by prisma models, and I would not recommend using
-it unless you have a solid understanding of how it will construct queries.
+## Features
 
-This plugin will allow common queries to be resolved through a single prisma query (prisma may still
-turn this into multiple SQL queries), and provides reasonable, predictable and safe fallbacks for
-more complex queries and edge cases. That being said, graphql APIs are complex, and it is important
-to understand the queries your API is capable of executing.
-
-The way this plugin resolves queries is designed to be efficient, while still being predictable and
-easy to understand. Tools that try to automatically generate queries are often hard to understand
-and reason about, so this plugin tries to make things as clear as possible by providing query
-options to resolvers and a loading user code to initiate the actual queries. The options generally
-only contain `include`s for nested relations (connection fields provide more complex query options).
-The exception to this, is that we provide a default resolver for relations that can handle querying
-for a relation if data was not pre-loaded by a parent field. This query used by this resolver is
-simple, and described in detail below.
-
-With this simple approach, we get an API that is easy to understand, but still provides a lot of
-value and functionality.
+- 🎨 Quickly define GraphQL types based on your Prisma models
+- 🦺 Strong type-safety throughout the entire API
+- 🤝 Automatically resolve relationships defined in your database
+- 🎣 Automatic Query optimization efficiently load the specific data needed to resolve a query
+  (solves common N+1 issues)
+- 💅 Types and fields in GraphQL schema are not implicitly tied to the column names or type in your
+  database.
+- 🔀 Relay integration for defining nodes and connections that can be efficiently loaded.
+- 📚 Supports multiple GraphQL models based on the same Database model
+- 🧮 Count fields can easily be added to objects and connections
 
 ## Example
 
 Here is a quick example of what an API using this plugin might look like. There is a more thorough
 breakdown of what the methods and options used in the example below.
 
-If you are looking for an example integrated with the
-[relay plugin](https://pothos-graphql.dev/docs/plugins/relay), see the
-[Relay integration](#relay-integration) section below.
-
 ```typescript
+// Create an object type based on a prisma model without providing any custom type information
 builder.prismaObject('User', {
-  include: {
-    profile: true,
-  },
+  // findUnique is explained more below, and is required to safely resolve queries in some edge cases
   findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
+    // expose fields from the database
     id: t.exposeID('id'),
     email: t.exposeString('email'),
     bio: t.string({
-      resolve: (user) => user.profile.bio,
+      // automatically load the bio from the profile when this field is queried
+      select: {
+        profile: {
+          select: {
+            bio: true,
+          },
+        },
+      },
+      resolve: (user) => user.profile.bio, // user will be typed correctly to include the selected fields from above
     }),
+    // Load posts as list field.  Posts will automatically be included the posts field is queried
     posts: t.relation('posts', {
       args: {
         oldestFirst: t.arg.boolean(),
       },
+      // Define custom query options that are applied when loading the post relation
       query: (args, context) => ({
         orderBy: {
           createdAt: args.oldestFirst ? 'asc' : 'desc',
         },
       }),
     }),
+    // creates relay connection that handles pagination using prisma's built in cursor based pagination
+    postsConnection: t.relatedConnection('posts', {
+      cursor: 'id',
+    }),
   }),
 });
 
-builder.prismaObject('Post', {
-  findUnique: (post) => ({ id: post.id }),
+// Create a relay node based a prisma model
+builder.prismaNode('Post', {
+  findUnique: (id) => ({ id }),
+  id: { resolve: (post) => post.id },
   fields: (t) => ({
-    id: t.exposeID('id'),
     title: t.exposeString('title'),
     author: t.relation('author'),
   }),
@@ -75,10 +79,12 @@ builder.prismaObject('Post', {
 
 builder.queryType({
   fields: (t) => ({
+    // Define a field that issues an optimized prisma query
     me: t.prismaField({
       type: 'User',
       resolve: async (query, root, args, ctx, info) =>
         prisma.user.findUnique({
+          // the `query` argument will add in `includes` or `selects` to resolve as much of the request in a single query as possible
           ...query,
           rejectOnNotFound: true,
           where: { id: ctx.userId },
@@ -129,153 +135,17 @@ query {
 
 Will result in 2 calls to prisma, one to resolve everything except `oldPosts`, and a second to
 resolve everything inside `oldPosts`. Prisma can only resolve each relation once in a single query,
-so we need a separate to handle the second `posts` relation. This may seem slightly magical, but
-should be predictable and hopefully easy to understand after reading the documentation below.
-
-## Pothos + Prisma without a plugin
-
-If you just want learn about the plugin, feel free to skip this section, but understanding how to
-use prisma without a plugin may be useful for evaluating if this plugin is a good fit for your use
-case.
-
-Using prisma without a plugin is relatively straight forward using the `builder.objectRef` method.
-
-The easiest way to create types backed by prisma looks something like:
-
-```typescript
-import { Post, PrismaClient, User } from '@prisma/client';
-
-const db = new PrismaClient();
-const UserObject = builder.objectRef<User>('User');
-const PostObject = builder.objectRef<Post>('Post');
-
-UserObject.implement({
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    email: t.exposeString('email'),
-    posts: t.field({
-      type: [PostObject],
-      resolve: (user) =>
-        db.post.findMany({
-          where: { authorId: user.id },
-        }),
-    }),
-  }),
-});
-
-PostObject.implement({
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    title: t.exposeString('title'),
-    author: t.field({
-      type: UserObject,
-      resolve: (post) =>
-        db.user.findUnique({ rejectOnNotFound: true, where: { id: post.authorId } }),
-    }),
-  }),
-});
-
-builder.queryType({
-  fields: (t) => ({
-    me: t.field({
-      type: UserObject,
-      resolve: (root, args, ctx) =>
-        db.user.findUnique({ rejectOnNotFound: true, where: { id: ctx.userId } }),
-    }),
-  }),
-});
-```
-
-This sets up User, and Post objects with a few fields, and a `me` query that returns the current
-user. There are a few things to note in this setup:
-
-1. We split up the `builder.objectRef` and the `implement` calls, rather than calling
-   `builder.objectRef(...).implement(...)`. This prevents typescript from getting tripped up by the
-   circular references between posts and users.
-2. We use rejectOnNotFound with our `findUnique` calls because those fields are not nullable.
-   Without this option, prisma will return a null if the object is not found. An alternative is to
-   mark these fields as nullable.
-3. The refs to our object types are called `UserObject` and `PostObject`, this is because `User` and
-   `Post` are the names of the types imported from prisma. We could instead alias the types when we
-   import them so we can name the refs to our GraphQL types after the models.
-
-This setup is fairly simple, but it is easy to see the n+1 issues we might run into. Prisma helps
-with this by batching queries together, but there are also things we can do in our implementation to
-improve things.
-
-One thing we could do if we know we will usually be loading the author any time we load a post is to
-make the author part of shape required for a post:
+so we need a separate to handle the second `posts` relation. These additional queries will use the
+`findUnique` defined for the parent type to create a new efficient query to load any conflicting
+relations.
 
-```typescript
-const UserObject = builder.objectRef<User>('User');
-// We add the author here in the objectRef
-const PostObject = builder.objectRef<Post & { author: User }>('Post');
-
-UserObject.implement({
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    email: t.exposeString('email'),
-    posts: t.field({
-      type: [PostObject],
-      resolve: (user) =>
-        db.post.findMany({
-          // We now need to include the author when we query for posts
-          include: {
-            author: true,
-          },
-          where: { authorId: user.id },
-        }),
-    }),
-  }),
-});
-
-PostObject.implement({
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    title: t.exposeString('title'),
-    author: t.field({
-      type: UserObject,
-      // Now we can just return the author from the post instead of querying for it
-      resolve: (post) => post.author,
-    }),
-  }),
-});
-```
-
-We may not always want to query for the author though, so we could make the author optional and fall
-back to using a query if it was not provided by the parent resolver:
-
-```typescript
-const PostObject = builder.objectRef<Post & { author?: User }>('Post');
-
-PostObject.implement({
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    title: t.exposeString('title'),
-    author: t.field({
-      type: UserObject,
-      resolve: (post) =>
-        post.author ?? db.user.findUnique({ rejectOnNotFound: true, where: { id: post.authorId } }),
-    }),
-  }),
-});
-```
-
-With this setup, a parent resolver has the option to include the author, but we have a fallback
-incase it does not.
-
-There are other patterns like dataloaders than can be used to reduce n+1 issues, and make your graph
-more efficient, but they are too complex to describe here.
-
-## Usage
-
-### Install
+## Install
 
 ```bash
 yarn add @pothos/plugin-prisma
 ```
 
-### Setup
+## Setup
 
 This plugin requires a little more setup than other plugins because it integrates with the prisma to
 generate some types that help the plugin better understand your prisma schema. Previous versions of
@@ -283,7 +153,7 @@ this plugin used to infer all required types from the prisma client itself, but
 poor dev experience because the complex types slowed down editors, and some more advanced use cases
 could not be typed correctly.
 
-#### Add a the `pothos` generator to your prisma schema
+### Add a the `pothos` generator to your prisma schema
 
 ```
 generator pothos {
@@ -294,7 +164,7 @@ generator pothos {
 Now the types Pothos uses will be generated whenever you re-generate your prisma client. Run the
 following command to re-generate the client and create the new types:
 
-```bash
+```sh
 npx prisma generate
 ```
 
@@ -315,7 +185,7 @@ generator pothos {
 }
 ```
 
-#### Set up the builder
+### Set up the builder
 
 ```typescript
 import SchemaBuilder from '@pothos/core';
@@ -341,7 +211,7 @@ It is strongly recommended NOT to put your prisma client into `Context`. This wi
 type-checking and a laggy developer experience in VSCode. See
 https://github.com/microsoft/TypeScript/issues/45405 for more details.
 
-### Creating some types with `builder.prismaObject`
+## Creating some types with `builder.prismaObject`
 
 `builder.prismaObject` takes 2 arguments:
 
@@ -353,7 +223,7 @@ https://github.com/microsoft/TypeScript/issues/45405 for more details.
 builder.prismaObject('User', {
   // Optional name for the object, defaults to the name of the prisma model
   name: 'PostAuthor',
-  findUnique: null,
+  findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
     id: t.exposeID('id'),
     email: t.exposeString('email'),
@@ -361,7 +231,7 @@ builder.prismaObject('User', {
 });
 
 builder.prismaObject('Post', {
-  findUnique: null,
+  findUnique: (post) => ({ id: post.id }),
   fields: (t) => ({
     id: t.exposeID('id'),
     title: t.exposeString('title'),
@@ -375,7 +245,7 @@ or needing imports from prisma client.
 
 The `findUnique` option is described more below.
 
-### Adding prisma fields to non-prisma objects (including Query and Mutation)
+## Adding prisma fields to non-prisma objects (including Query and Mutation)
 
 There is a new `t.prismaField` method which can be used to define fields that resolve to your prisma
 types:
@@ -407,72 +277,29 @@ You do not need to use this method, and the `builder.prismaObject` method return
 can be used like any other object ref (with `t.field`), but using `t.prismaField` will allow you to
 take advantage of more efficient queries.
 
-The `query` object will contain an `include` object to pre-load data needed to resolve nested parts
-of the current query. This is based on fields defined with `t.relation` described below.
+The `query` object will contain an object with `include` or `select` options to pre-load data needed
+to resolve nested parts of the current query. The included/selected fields are based on which fields
+are being queried, and the options provided when defining those fields and types.
 
-If there are no fields using `t.relation` in your query, everything is resolved exactly as it would
-be without this plugin.
-
-### Adding relations
+## Adding relations
 
 You can add fields for relations using the `t.relation` method:
 
 ```typescript
-builder.prismaObject('User', {
-  findUnique: null,
+builder.queryType({
   fields: (t) => ({
-    id: t.exposeID('id'),
-    email: t.exposeString('email'),
-    posts: t.relation('posts', {
-      resolve: (query, user) =>
-        db.post.findMany({
+    me: t.prismaField({
+      type: 'User',
+      resolve: async (query, root, args, ctx, info) =>
+        prisma.user.findUnique({
           ...query,
-          where: { authorId: user.id },
+          rejectOnNotFound: true,
+          where: { id: ctx.userId },
         }),
     }),
   }),
 });
 
-builder.prismaObject('User', {
-  findUnique: null,
-  fields: (t) => ({
-    id: t.exposeID('id'),
-    title: t.exposeString('title'),
-    author: t.relation('author', {
-      resolve: (query, post) =>
-        db.user.findUnique({ ...query, rejectOnNotFound: true, where: { id: post.authorId } }),
-    }),
-  }),
-});
-```
-
-`t.relation` defines a field that can be pre-loaded by a parent resolver, and most of the time, the
-`resolve` function will NOT be called. This is VERY IMPORTANT to understand, because it is the
-biggest place where you can introduce inconsistencies into your API with this plugin. The `resolve`
-function is used to load the relationship if parent resolver did not pre-load the data needed to
-resolve the field. This happens for a number of reasons:
-
-1. The parent object was not loaded through a field defined with `t.prismaField`, or `t.relation`
-2. The `query` object for the parent field was not spread into the query
-3. The graphql query requested multiple fields that depended on the same relationship (described
-   more below)
-
-These are all okay, and expected situations. Graphql APIs are very flexible, and magically pushing
-everything into a single query is impossible for arbitrary queries. This is why we have a `resolve`
-function than can load the relation IF it was not already loaded by the parent.
-
-Like `t.prismaField`, the `resolve` function now as a new first argument that is a query that should
-be spread into the query, and is used to load nested relationships.
-
-### Find Unique
-
-Because the `resolve` function is only used as a fallback, it is harder to test, and if done
-incorrectly can introduce inconsistencies. While it shouldn't be too hard to get right, it might be
-better to avoid it entirely. To do this, we can let the Prisma plugin generate these resolve
-functions for you in a consistent and predictable way. We can do this by providing a findUnique
-option for our object type. Defining a `findUnique` that is not null, will make `resolve` optional.
-
-```typescript
 builder.prismaObject('User', {
   findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
@@ -492,23 +319,91 @@ builder.prismaObject('Post', {
 });
 ```
 
-This greatly simplifies our object types. In these cases, the fallback resolve functions will
-re-load the current object using the `findUnique` as the where clause, and then `include` the
-relation for the current field. This can produce a slightly less efficient query than a manual
-implementation because the parent object is re-loaded first, but it will batch multiple
-relationships into one query, and the findUnique queries should be very fast.
+`t.relation` defines a field that can be pre-loaded by a parent resolver. This will create something
+like `{ include: { author: true }}` that will be passed as part of the `query` argument of a
+`prismaField` resolver. If the parent is another `relation` field, the includes will become nested,
+and the full relation chain will be passed to the `prismaField` that started the chain.
 
-For example, if a `User` was loaded without pre-loading, and both a `posts` and a `profile` relation
-where requested, the generated prisma call would be something like:
+For example the query:
 
-```typescript
-prisma.user.findUnique({
-  rejectOnNotFound: true,
-  where: { id: user.id },
+```graphql
+query {
+  me {
+    posts {
+      author {
+        id
+      }
+    }
+  }
+}
+```
+
+the `me` `prismaField` would receive something like the following as its query parameter:
+
+```ts
+{
   include: {
-    posts: true,
-    profile: true,
-  },
+    posts: {
+      include: {
+        author: true;
+      }
+    }
+  }
+}
+```
+
+This will work perfectly for the majority of queries. There are a number of edge cases that make it
+impossible to resolve everything in a single query. When this happens the `findUnique` option is
+used to ensure that everything is still loaded correctly, and split into as few efficient queries as
+possible.
+
+### Find Unique
+
+The `findUnique` function will receive an instance of the prisma model the current type is defining,
+and should return an object that will be passed as a `where` in a `prisma.findUnique`. Generally,
+this will just be something like: `user => { id: user.id }` where `id` is the primary key for the
+table.
+
+When the prisma plugin encounters a query where the requirements for a field can not be satisfied,
+it will call findUnique for the current prisma model, and include or select all properties that are
+required for the fields that could not be resolved without an additional query.
+
+The following are some edge cases that could cause an additional query to be necessary:
+
+- The parent object was not loaded through a field defined with `t.prismaField`, or `t.relation`
+- The root `prismaField` did not correctly spread the `query` arguments in is prisma call.`
+- The query selects multiple fields that use the same relation with incompatible options (order,
+  limit, or other filters)
+- The query contains multiple aliases for the same relation field with different arguments in a way
+  that results in different query options for the relation.
+- A relation field has a query that is incompatible with the default includes of the parent object
+
+All of the above should be relatively uncommon in normal usage, but the plugin ensures that these
+types of edge cases are automatically handled when they do occur.
+
+### Without Find Unique
+
+This is generally _NOT RECOMMENDED_, but you can set `findUnique` to null for some prisma objects.
+Doing this will prevent the plugin from resolving queries for conflicting relations. Because of
+this, you will need to provide a `resolve` method when defining relations, and some other options
+(like field level selects, described below) will not be available. This `resolve` method is _ONLY
+CALLED AS A FALLBACK_ when the relation has not already been loaded. This means that you should not
+apply any sorting or filtering to the relation queried in the resolve method. Instead used the
+`query` option described in the next section
+
+```typescript
+builder.prismaObject('User', {
+  findUnique: null,
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    posts: t.relation('posts', {
+      resolve: (query, user) =>
+        db.post.findMany({
+          ...query,
+          where: { authorId: user.id },
+        }),
+    }),
+  }),
 });
 ```
 
@@ -516,16 +411,15 @@ prisma.user.findUnique({
 
 So far we have been describing very simple queries without any arguments, filtering, or sorting. For
 `t.prismaField` definitions, you can add arguments to your field like normal, and pass them into
-your prisma query as needed. For `t.relation` the flow is slightly different because we need to make
-sure we are loading the right data if we are pre-loading data in a parent resolver. We do this by
-adding a `query` option to our field options.
+your prisma query as needed. For `t.relation` the flow is slightly different because we are not
+making a prisma query directly. We do this by adding a `query` option to our field options. Query
+can either be a query object, or a method that returns a query object based on the field arguments.
 
 ```typescript
 builder.prismaObject('User', {
   findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
     id: t.exposeID('id'),
-    email: t.exposeString('email'),
     posts: t.relation('posts', {
       // We can define arguments like any other field
       args: {
@@ -542,11 +436,11 @@ builder.prismaObject('User', {
 });
 ```
 
-This query will be part of the `query` that gets passed into the first argument of `resolve`
-function for `t.relation` and `t.prismaField` based fields, and include things like `where`, `skip`,
-`take`, `orderBy`, etc. The `query` function will be passed the arguments for the field, and the
-context for the current request. Because it is used for pre-loading data, and solving n+1 issues, it
-can not be passed the `parent` object because it may not be loaded yet.
+The returned query object will be added to the include section of the `query` argument that gets
+passed into the first argument of the parent `t.prismaField`, and can include things like `where`,
+`skip`, `take`, abd `orderBy`. The `query` function will be passed the arguments for the field, and
+the context for the current request. Because it is used for pre-loading data, and solving n+1
+issues, it can not be passed the `parent` object because it may not be loaded yet.
 
 If your field has a `resolve` method the generated `query` will be passed in as part of the first
 arg to your resolve function
@@ -568,20 +462,37 @@ builder.prismaObject('User', {
           createdAt: args.oldestFirst ? 'asc' : 'desc',
         },
       }),
-      // query here will contain the orderBy (and any other properties returned by the query method)
+      // optional: query here will contain the orderBy (and any other properties returned by the query method)
       resolve: (query, post) => db.post.findMany({ ...query, where: { id: post.authorId } }),
     }),
   }),
 });
 ```
 
-It is VERY IMPORTANT to put all your filtering and sorting into the query method rather than your
+It is _VERY IMPORTANT_ to put all your filtering and sorting into the query method rather than your
 resolver because the resolver is only used as fallback, and any filtering that does not exist in the
 query method will not be applied correctly. If you have a where in both your query and your
 resolver, you will need to ensure these are merged correctly. It is generally better NOT to use a
 custom resolver.
 
-### Includes on types
+## relationCount
+
+Prisma supports querying for
+[relation counts](https://www.prisma.io/docs/concepts/components/prisma-client/aggregation-grouping-summarizing#count-relations)
+which allow including counts for relations along side other `includes`. This does not currently
+support any filters on the counts, but can give a total count for a relation.
+
+```typescript
+builder.prismaObject('User', {
+  findUnique: (user) => ({ id: user.id }),
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    postCount: t.relationCount('posts'),
+  }),
+});
+```
+
+## Includes on types
 
 In some cases, you may want to always pre-load certain relations. This can be helpful for defining
 fields directly on type where the underlying data may come from a related table.
@@ -606,89 +517,140 @@ builder.prismaObject('User', {
 });
 ```
 
-### relationCount
+## Select mode for types
 
-Prisma supports querying for
-[relation counts](https://www.prisma.io/docs/concepts/components/prisma-client/aggregation-grouping-summarizing#count-relations)
-which allow including counts for relations along side other `includes`. This does not currently
-support any filters on the counts, but can give a total count for a relation.
+By default, the prisma plugin will use `include` when including relations, or generating fallback
+queries. This means we are always loading all columns of a table when loading it in a
+`t.prismaField` or a `t.relation`. This is usually what we want, but in some cases, you may want to
+select specific columns instead. This can be useful if you have tables with either a very large
+number of columns, or specific columns with large payloads you want to avoid loading.
+
+To do this, you can add a `select` instead of an include to your `prismaObject`:
 
 ```typescript
 builder.prismaObject('User', {
+  select: {
+    id: true,
+  },
   findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
     id: t.exposeID('id'),
-    postCount: t.relationCount('posts'),
+    email: t.exposeString('email'),
   }),
 });
 ```
 
-## Relay integration
+At the very least, you will need to `select` the properties required by your `findUnique` function.
+The `t.expose*` and `t.relation` methods will all automatically add selections for the exposed
+fields _WHEN THEY ARE QUERIED_, ensuring that only the requested columns will be loaded from the
+database.
 
-This plugin has extensive integration with the
-[relay plugin](https://pothos-graphql.dev/docs/plugins/relay), which makes creating nodes and
-connections very easy.
+In addition to the `t.expose` and `t.relation`, you can also add custom selections to other fields:
 
-### Example
+```typescript
+builder.prismaObject('User', {
+  select: {
+    id: true,
+  },
+  findUnique: (user) => ({ id: user.id }),
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    email: t.exposeString('email'),
+    bio: t.string({
+      // This will select user.profile.bio when the the `bio` field is queried
+      select: {
+        profile: {
+          select: {
+            bio: true,
+          },
+        },
+      },
+      resolve: (user) => user.profile.bio,
+    }),
+  }),
+});
+```
 
-The following example is similar to the one above with a few changes:
+## Type variants
 
-- the `User` and `Post` objects are now relay nodes
-- the `posts` field on the `User` type is now a relay connection using cursor based pagination
-- there is a new `users` query that is also a relay connection
+The prisma plugin supports defining multiple GraphQL types based on the same prisma model.
+Additional types are called `variants`. You will always need to have a "Primary" variant (defined as
+described above). Additional variants can be defined by providing a `variant` option instead of a
+`name` option when creating the type:
+
+```typescript
+const Viewer = builder.prismaObject('User', {
+  variant: 'Viewer',
+  findUnique: (user) => ({ id: user.id }),
+  fields: (t) => ({
+    id: t.exposeID('id'),
+});
+```
 
-Everything in this schema is still queryable via a single prisma query. The relay connections
-handles pre-loading like all the other fields.
+You can define variant fields that reference one variant from another:
 
 ```typescript
-builder.prismaNode('User', {
-  findUnique: (id) => ({ id }),
-  id: { resolve: (user) => user.id },
+const Viewer = builder.prismaObject('User', {
+  variant: 'Viewer',
+  findUnique: (user) => ({ id: user.id }),
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    // Using the model name ('User') will reference the primary variant
+    user: t.variant('User'),
+  });
+});
+
+const User = builder.prismaNode('User', {
+  // Testing that user is typed correctly
+  authScopes: (user) => !!user.id,
+  interfaces: [Named],
+  id: {
+    resolve: (user) => user.id,
+  },
   fields: (t) => ({
+    // To reference another variant, use the returned object Ref instead of the model name:
+    viewer: t.variant(Viewer, {}),
     email: t.exposeString('email'),
-    posts: t.relatedConnection('posts', {
-      cursor: 'id',
-      args: {
-        oldestFirst: t.arg.boolean(),
-      },
-      query: (args, context) => ({
-        orderBy: {
-          createdAt: args.oldestFirst ? 'asc' : 'desc',
-        },
-      }),
-    }),
   }),
 });
+```
 
-builder.prismaNode('Post', {
+You can also use variants when defining relations by providing a `type` option:
+
+```typescript
+const PostDraft = builder.prismaNode('Post', {
+  variant: 'PostDraft'
+  // This is used to load the node by id
   findUnique: (id) => ({ id }),
+  // This is used to get the id from a node
   id: { resolve: (post) => post.id },
+  // fields work just like they do for builder.prismaObject
   fields: (t) => ({
     title: t.exposeString('title'),
     author: t.relation('author'),
   }),
 });
 
-builder.queryType({
+const Viewer = builder.prismaObject('User', {
+  variant: 'Viewer',
+  findUnique: (user) => ({ id: user.id }),
   fields: (t) => ({
-    me: t.prismaField({
-      type: 'User',
-      resolve: async (query, root, args, ctx, info) =>
-        prisma.user.findUnique({
-          ...query,
-          rejectOnNotFound: true,
-          where: { id: ctx.userId },
-        }),
-    }),
-    posts: t.prismaConnection({
-      type: 'Post',
-      cursor: 'id',
-      resolve: (query) => prisma.post.findMany(query),
+    id: t.exposeID('id'),
+    drafts: t.relation('posts', {
+      // This will cause this relation to use the PostDraft variant rather than the default Post variant
+      type: PostDraft,
+      query: { where: { draft: true } },
     }),
-  }),
+  });
 });
 ```
 
+## Relay integration
+
+This plugin has extensive integration with the
+[relay plugin](https://pothos-graphql.dev/docs/plugins/relay), which makes creating nodes and
+connections very easy.
+
 ### `prismaNode`
 
 The `prismaNode` method works just like the `prismaObject` method with a couple of small
@@ -799,6 +761,8 @@ builder.prismaNode('User', {
   passed to prisma.
 - `defaultSize`: (default: 20) The default page size to use if `first` and `last` are not provided.
 - `maxSize`: (default: 100) The maximum number of nodes returned for a connection.
+- `query`: A method that accepts the `args` and `context` for the connection field, and returns
+  filtering and sorting logic that will be merged into the query for the relation.
 - `resolve`: (optional) Used as a fallback when a connection is not pre-loaded. It is optional, and
   generally should NOT be defined manually. If used it works like a combination of the `resolve`
   method of `relation` and `prismaConnection`. The default will use the `findUnique` of the current
@@ -806,3 +770,134 @@ builder.prismaNode('User', {
   relationships to improve query efficiency.
 - `totalCount`: when set to true, this will add a `totalCount` field to the connection object. see
   `relationCount` above for more details.
+
+## Using Prisma without a plugin
+
+Using prisma without a plugin is relatively straight forward using the `builder.objectRef` method.
+
+The easiest way to create types backed by prisma looks something like:
+
+```typescript
+import { Post, PrismaClient, User } from '@prisma/client';
+
+const db = new PrismaClient();
+const UserObject = builder.objectRef<User>('User');
+const PostObject = builder.objectRef<Post>('Post');
+
+UserObject.implement({
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    email: t.exposeString('email'),
+    posts: t.field({
+      type: [PostObject],
+      resolve: (user) =>
+        db.post.findMany({
+          where: { authorId: user.id },
+        }),
+    }),
+  }),
+});
+
+PostObject.implement({
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    title: t.exposeString('title'),
+    author: t.field({
+      type: UserObject,
+      resolve: (post) =>
+        db.user.findUnique({ rejectOnNotFound: true, where: { id: post.authorId } }),
+    }),
+  }),
+});
+
+builder.queryType({
+  fields: (t) => ({
+    me: t.field({
+      type: UserObject,
+      resolve: (root, args, ctx) =>
+        db.user.findUnique({ rejectOnNotFound: true, where: { id: ctx.userId } }),
+    }),
+  }),
+});
+```
+
+This sets up User, and Post objects with a few fields, and a `me` query that returns the current
+user. There are a few things to note in this setup:
+
+1. We split up the `builder.objectRef` and the `implement` calls, rather than calling
+   `builder.objectRef(...).implement(...)`. This prevents typescript from getting tripped up by the
+   circular references between posts and users.
+2. We use rejectOnNotFound with our `findUnique` calls because those fields are not nullable.
+   Without this option, prisma will return a null if the object is not found. An alternative is to
+   mark these fields as nullable.
+3. The refs to our object types are called `UserObject` and `PostObject`, this is because `User` and
+   `Post` are the names of the types imported from prisma. We could instead alias the types when we
+   import them so we can name the refs to our GraphQL types after the models.
+
+This setup is fairly simple, but it is easy to see the n+1 issues we might run into. Prisma helps
+with this by batching queries together, but there are also things we can do in our implementation to
+improve things.
+
+One thing we could do if we know we will usually be loading the author any time we load a post is to
+make the author part of shape required for a post:
+
+```typescript
+const UserObject = builder.objectRef<User>('User');
+// We add the author here in the objectRef
+const PostObject = builder.objectRef<Post & { author: User }>('Post');
+
+UserObject.implement({
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    email: t.exposeString('email'),
+    posts: t.field({
+      type: [PostObject],
+      resolve: (user) =>
+        db.post.findMany({
+          // We now need to include the author when we query for posts
+          include: {
+            author: true,
+          },
+          where: { authorId: user.id },
+        }),
+    }),
+  }),
+});
+
+PostObject.implement({
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    title: t.exposeString('title'),
+    author: t.field({
+      type: UserObject,
+      // Now we can just return the author from the post instead of querying for it
+      resolve: (post) => post.author,
+    }),
+  }),
+});
+```
+
+We may not always want to query for the author though, so we could make the author optional and fall
+back to using a query if it was not provided by the parent resolver:
+
+```typescript
+const PostObject = builder.objectRef<Post & { author?: User }>('Post');
+
+PostObject.implement({
+  fields: (t) => ({
+    id: t.exposeID('id'),
+    title: t.exposeString('title'),
+    author: t.field({
+      type: UserObject,
+      resolve: (post) =>
+        post.author ?? db.user.findUnique({ rejectOnNotFound: true, where: { id: post.authorId } }),
+    }),
+  }),
+});
+```
+
+With this setup, a parent resolver has the option to include the author, but we have a fallback
+incase it does not.
+
+There are other patterns like dataloaders than can be used to reduce n+1 issues, and make your graph
+more efficient, but they are too complex to describe here.