Windowed Pagination Plugin

[rogerballard]

Have you considered extending the Relay plugin to implement windowed pagination? Artsy have a thorough write-up of their schema design on their blog that is very interesting. Would be nice to support this behaviour out of the box, and I may have a use-case for it coming up.

[hayes]

This is not something I've thought about. It's a little more manual than having it added via a plugin, but would be simple to just add manuallly witha few helpers.

You could probably just wrap the resolveOffsetConnection helper with something that adds the page cursors data (this is a little awkward right now, because you get the decoded limit and offset inside the callback)

Then you can just define the page cursors field on the connection (you can even do this globally so every connection has it automatically)

On my phone, sorry this is going to be pretty incomplete:

async function resolveWindowedConnrction(...args) {
  let cursors;

  const result = await resolveOffsetConnection(...args, (...moreArgs) => 
    const results = args.cb(moreArgs) // to lazy to destructure args for real on my phone, pretend this makes sense
    cursors = ...
    return results 
  })

   return {...results, pageCursors: cursors }
}

The for extending all connections (and updating the types so that connections need to return):
https://pothos-graphql.dev/docs/plugins/relay#extending-all-connections

Hope thisakes some amount of sense

[hayes]

@rogerballard Created a working example for you: https://github.com/hayes/pothos/blob/main/examples/relay-windowed-pagination/src/schema.ts#L141-L148

Pagination is something that isn't standardized enough to write a plugin that doesn't feel overly opinionated. Relay cursor pagination has a specification that I can follow, but there are too many open questions for windowed pagination.

I think an approach like the one in the above example is simple enough to implement while letting users customize the exact format of their pagination types as needed.

Let me know if this works for you, happy to discuss further if you have other ideas on how this should be handled.

[rogerballard]

@hayes thank you for creating a working example, much appreciated! 🙂

Agreed that pagination isn't exactly standardised in GraphQL. I think it's probably one of the least discussed topics within the GraphQL community, and similarly one essential feature that most GraphQL libraries don't help so much with - which I find surprising considering that many clients eventually want some sort of paginated datasets!

I think from this perspective, having a simple (and reasonably opinionated) plugin/example would be beneficial for many users of pothos.

Again, thanks for implementing an example - I'll base my implementation on your example, and let you know how it goes, and whether anything might be missing. 👍

[bstro]

I'm needing to implement windowed pagination within the context of a prismaConnection and am wondering if I am on the right path. Using resolveWindowedConnection as written by @hayes in the example code

t.prismaConnection({
    type: Ticket,
    cursor: 'id',
    args: {
      where: t.arg({type: TicketWhereInput}),
    },
    resolve: async (query, _, args, ctx) => {
      return resolveWindowedConnection({args}, async ({limit, offset}) => {
        const tickets = await ctx.db.ticket.findMany({
          ...query,
          take: limit,
          skip: offset,
          where: args.where ?? {},
        })
        return {
          items: tickets,
          totalCount: tickets.length,
        }
      })
    },
  })

This throws a type error:

I'm new to all this and would really appreciate any guidance! Thanks :)

[hayes]

looks like your totalCount is also not going to be right, you can't use the length of the result when you apply a limit

t.connection({
    type: Ticket,
    args: {
      where: t.arg({type: TicketWhereInput}),
    },
    resolve: async (_, args, context, info) => {
      return resolveWindowedConnection({args}, async ({limit, offset}) => {
        const tickets = await context.db.ticket.findMany({
          ...queryFromInfo({
            context,
            info,
            path: ['edges', 'node'],
          }),
          take: limit,
          skip: offset,
          where: args.where ?? {},
        })
        
        const totalCount = await context.db.ticket.count({
          where: args.where ?? {},
        })

        return {
          items: tickets,
          totalCount: totalCount,
        }
      })
    },
  })

[arimgibson]

@hayes what would be the suggested implementation of this replacing Prisma relations? I've been able to implement that solution perfectly for all my root queries but am hoping to have the same pagination available on a field inside the query as well.

Consider the following GraphQL query I'd be looking to achieve, with the posts also being able to be paginated. Adapted my actual use case to users/posts just as a universal example, so sorry if some of the code is off!

{
  users {
    pageCursors {
      first {
        cursor
        isCurrent
        pageNumber
      }
      around {
        cursor
        isCurrent
        pageNumber
      }
      last {
        cursor
        isCurrent
        pageNumber
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    edges {
      cursor
      node {
        posts {
          pageCursors {
            first {
              cursor
              isCurrent
              pageNumber
            }
            around {
              cursor
              isCurrent
              pageNumber
            }
            last {
              cursor
              isCurrent
              pageNumber
            }
          }
          pageInfo {
            startCursor
            endCursor
            hasPreviousPage
            hasNextPage
          }
        }
        edges {
          cursor
          node {
            published
            date
          }
        }
      }
    }
  }
}

Here's what I've tried (with the t. examples below used for the posts value):

builder.prismaNode('User', {
  id: { field: 'id' },
  fields: (t) => ({
    posts: ...
  }),
});

t.relatedConnection('posts', { cursor: 'id' })
// schema is able to be loaded and used but throws error upon query
// "message": "Cannot read properties of undefined (reading 'relations')"

t.connection({
  type: 'Post',
  args: ...,
  resolve: (parent, args, context, info) => getAllPosts(args, context, info)
}),
// this works, but is a little slower than I was hoping. Would be fine if this is the only way, but would love to optimize
// this connection is an exact copy of the mutation being used to get all posts
// I'm thinking I could maybe cut down on rewriting it all through builder.connectionObject if this is the only method 

[hayes]

Using t.connection is likely the easiest option. If you want to get it to hoist the queries up into the parent query, that should be possible, but will take a lot of manual work.

You can look at https://pothos-graphql.dev/docs/plugins/prisma#indirect-relations-as-connections as a starting place.

What you would want to do is make your own version of mediaConnectionHelpers that implements windowed pagination instead of cursor pagination. The getQuery would basically implement logic similar to

pothos/packages/plugin-relay/src/utils/connections.ts

Lines 46 to 90 in 27da5c2

	function offsetForArgs(options: ResolveOffsetConnectionOptions) {
	const { before, after, first, last } = options.args;
	const defaultSize = options.defaultSize ?? DEFAULT_SIZE;
	const maxSize = options.maxSize ?? DEFAULT_MAX_SIZE;
	const beforeOffset = before ? cursorToOffset(before) : Number.POSITIVE_INFINITY;
	const afterOffset = after ? cursorToOffset(after) : 0;
	if (first != null && first < 0) {
	throw new PothosValidationError('Argument "first" must be a non-negative integer');
	}
	if (last != null && last < 0) {
	throw new PothosValidationError('Argument "last" must be a non-negative integer');
	}
	let startOffset = after ? afterOffset + 1 : 0;
	let endOffset = before ? Math.max(beforeOffset, startOffset) : Number.POSITIVE_INFINITY;
	if (first != null) {
	endOffset = Math.min(endOffset, startOffset + first);
	}
	if (last != null) {
	if (endOffset === Number.POSITIVE_INFINITY) {
	throw new PothosValidationError(
	'Argument "last" can only be used in combination with "before" or "first"',
	);
	}
	startOffset = Math.max(startOffset, endOffset - last);
	}
	const size = first == null && last == null ? defaultSize : endOffset - startOffset;
	endOffset = Math.min(endOffset, startOffset + Math.min(size, maxSize));
	const totalSize = endOffset - startOffset;
	return {
	offset: startOffset,
	limit: totalSize + 1,
	hasPreviousPage: startOffset > 0,
	expectedSize: totalSize,
	hasNextPage: (resultSize: number) => resultSize > totalSize,
	};
	}

to create a take and skip args as well as the nested selection, and probably a selection for the total count. For the resolve method would need to create the connection object that would take the total count, and create the around args, as well as map the rows into edges/nodes with cursors, and then calculate the page info (hasNext,previousPage, and related cursors).

It's definitely doable, but requires a bit of non-trivial investment to get the implementation working. I don't have time right now to build this out myself, but if you wanted to contribute that back to the windowed pagination example, it might help others trying to do the same thing.

If you do end up trying to build this, and have any questions, I'm happy to help out.

[arimgibson]

Alright, thanks for all the information! I'll look into building it myself and will report back if I do go that route.

[arimgibson]

Ended up not going that route right now at least as I'm rushing to get some features added and don't have time to try and implement the hoisting. However, if anyone is wanting to do this in the future, here's a crude, not type safe but working way to implement below. I'd PR this into the Relay example but there's definitely a better way to do this, and this way probably shouldn't really be used as an example...

const postNode = builder.prismaNode('Post', {
  fields: {
    ...
  }
})

const postsField = {
  type: postNode,
  resolve: (parent, args, context, info) => getAllPosts(args, context, info);
}

builder.queryFields((t) => ({
  fields: {
    posts: t.connection(postsField)
  }
}))

builder.prismaNode('User', {
  id: { field: 'id' },
  fields: (t) => ({
    posts: t.connection(postsField)  
  }),
})