feat: pagination endpoints for areas and climbs

glassbead0 · glassbead0 · commit ee137c96a7cd · 2025-02-17T13:59:19.000-07:00
TODO:
* write unit tests
diff --git a/src/db/MediaObjectTypes.ts b/src/db/MediaObjectTypes.ts
@@ -58,17 +58,32 @@ export interface TagsLeaderboardType {
  */
 export type NewMediaObjectDoc = Omit<MediaObject, '_id' | 'createdAt'>
 
-export interface UserMediaGQLQueryInput {
-  userUuid: string
+/**
+ * GQL input type for getting paginated media for an "Entity", which is either a user, an area, or a climb.
+ * The userUuid is omitted from the Area and Climb versions of this type, which are defined below
+ * as AreaMediaQueryInput and ClimbMediaQueryInput
+ * @param maxFiles - the maximum number of media files to return
+ * @param first - the number of media files to return
+ * @param after - the cursor to start from
+ */
+export interface EntityMediaGQLQueryInput {
   maxFiles?: number
   first?: number
   after?: string
 }
 
-export type UserMediaQueryInput = Omit<UserMediaGQLQueryInput, 'userUuid'> & {
+export type UserMediaQueryInput = EntityMediaGQLQueryInput & {
   userUuid: MUUID
 }
 
+export type AreaMediaQueryInput = EntityMediaGQLQueryInput & {
+  areaUuid: MUUID
+}
+
+export type ClimbMediaQueryInput = EntityMediaGQLQueryInput & {
+  climbUuid: MUUID
+}
+
 /**
  * GQL user input type for remove tag mutation
  */
@@ -123,6 +138,14 @@ export interface UserMedia {
   }
 }
 
+export type AreaMedia = Omit<UserMedia, 'userUuid'> & {
+  areaUuid: string
+}
+
+export type ClimbMedia = Omit<UserMedia, 'userUuid'> & {
+  climbUuid: string
+}
+
 interface MediaEdge {
   node: MediaObject
   cursor: string
diff --git a/src/graphql/media/queries.ts b/src/graphql/media/queries.ts
@@ -1,6 +1,6 @@
 import mongoose from 'mongoose'
 import muuid from 'uuid-mongodb'
-import { TagsLeaderboardType, MediaObject, MediaByUsers, UserMediaGQLQueryInput, MediaForFeedInput } from '../../db/MediaObjectTypes.js'
+import { TagsLeaderboardType, MediaObject, MediaByUsers, UserMediaQueryInput, AreaMediaQueryInput, ClimbMediaQueryInput, MediaForFeedInput } from '../../db/MediaObjectTypes.js'
 import { GQLContext } from '../../types.js'
 
 const MediaQueries = {
@@ -19,16 +19,28 @@ const MediaQueries = {
 
   getUserMedia: async (_: any, { input }, { dataSources }: GQLContext): Promise<MediaObject[]> => {
     const { media } = dataSources
-    const { userUuid, maxFiles = 1000 } = input as UserMediaGQLQueryInput
-    return await media.getOneUserMedia(userUuid, maxFiles)
+    const { userUuid, maxFiles = 1000 } = input as UserMediaQueryInput
+    return await media.getOneUserMedia(userUuid.toString(), maxFiles)
   },
 
   getUserMediaPagination: async (_: any, { input }, { dataSources }: GQLContext): Promise<any> => {
     const { media } = dataSources
-    const { userUuid } = input as UserMediaGQLQueryInput
+    const { userUuid } = input as UserMediaQueryInput
     return await media.getOneUserMediaPagination({ ...input, userUuid: muuid.from(userUuid) })
   },
 
+  areaMediaPagination: async (_: any, { input }, { dataSources }: GQLContext): Promise<any> => {
+    const { media } = dataSources
+    const { areaUuid } = input as AreaMediaQueryInput
+    return await media.getOneAreaMediaPagination({ ...input, areaUuid: muuid.from(areaUuid) })
+  },
+
+  climbMediaPagination: async (_: any, { input }, { dataSources }: GQLContext): Promise<any> => {
+    const { media } = dataSources
+    const { climbUuid } = input as ClimbMediaQueryInput
+    return await media.getOneClimbMediaPagination({ ...input, climbUuid: muuid.from(climbUuid) })
+  },
+
   getTagsLeaderboard: async (_, { limit = 30 }: { limit: number }, { dataSources }: GQLContext): Promise<TagsLeaderboardType> => {
     const { media } = dataSources
     return await media.getTagsLeaderboard(limit)
diff --git a/src/graphql/schema/Media.gql b/src/graphql/schema/Media.gql
@@ -48,6 +48,16 @@ type Query {
   """
   getUserMediaPagination(input: UserMediaInput): UserMedia
 
+  """
+  Get media cursor with paginationg for an area
+  """
+  areaMediaPagination(input: AreaMediaInput): AreaMedia
+
+  """
+  Get media cursor with paginationg for a climb
+  """
+  climbMediaPagination(input: ClimbMediaInput): ClimbMedia
+
   """
   Get a list of users and their tagged photo count.
   """
@@ -63,6 +73,24 @@ type UserMedia {
   mediaConnection: MediaConnection!
 }
 
+"""
+Area media cursor with pagination support.
+See https://graphql.org/learn/pagination/
+"""
+type AreaMedia {
+  areaUuid: ID!
+  mediaConnection: MediaConnection!
+}
+
+"""
+Climb media cursor with pagination support.
+See https://graphql.org/learn/pagination/
+"""
+type ClimbMedia {
+  climbUuid: ID!
+  mediaConnection: MediaConnection!
+}
+
 """
 Media connection.
 See https://graphql.org/learn/pagination/
@@ -230,6 +258,29 @@ input UserMediaInput {
   after: ID
 }
 
+"Input parameters for area and climb media queries."
+input AreaMediaInput {
+  "Area UUID   Ex: 5f5b4b4b-0b3b-4b3b-8b3b-7b3b2b3b2b3b"
+  areaUuid: ID!
+  "Max number of objects return.  Ignore when using with pagination query."
+  maxFiles: Int
+  "Number of objects per page (Default = 6)."
+  first: Int
+  "Returning page data after this cursor (exclusive).  Return the first page if omitted."
+  after: ID
+}
+
+"Input parameters for climb media queries."
+input ClimbMediaInput {
+  "Climb UUID   Ex: 5f5b4b4b-0b3b-4b3b-8b3b-7b3b2b3b2b3b"
+  climbUuid: ID!
+  "Max number of objects return.  Ignore when using with pagination query."
+  maxFiles: Int
+  "Number of objects per page (Default = 6)."
+  first: Int
+  "Returning page data after this cursor (exclusive).  Return the first page if omitted."
+  after: ID
+}
 input MediaForFeedInput {
   maxUsers: Int
   maxFiles: Int
diff --git a/src/model/MediaDataSource.ts b/src/model/MediaDataSource.ts
@@ -3,7 +3,7 @@ import muid, { MUUID } from 'uuid-mongodb'
 import mongoose from 'mongoose'
 import { logger } from '../logger.js'
 import { getMediaObjectModel } from '../db/index.js'
-import { TagsLeaderboardType, UserMediaQueryInput, AllTimeTagStats, MediaByUsers, MediaForFeedInput, MediaObject, UserMedia } from '../db/MediaObjectTypes.js'
+import { TagsLeaderboardType, UserMediaQueryInput, AreaMediaQueryInput, ClimbMediaQueryInput, AllTimeTagStats, MediaByUsers, MediaForFeedInput, MediaObject, UserMedia, AreaMedia, ClimbMedia } from '../db/MediaObjectTypes.js'
 
 const HARD_MAX_FILES = 1000
 const HARD_MAX_USERS = 100
@@ -127,71 +127,64 @@ export default class MediaDataSource extends MongoDataSource<MediaObject> {
    */
   async getOneUserMediaPagination (input: UserMediaQueryInput): Promise<UserMedia> {
     const { userUuid, first = 6, after } = input
-    let nextCreatedDate: number
-    let nextId: mongoose.Types.ObjectId
-    let filters: any
-    if (after != null) {
-      const d = after.split('_')
-      nextCreatedDate = Number.parseInt(d[0])
-      nextId = new mongoose.Types.ObjectId(d[1])
-      filters = {
-        $match: {
-          $and: [
-            { userUuid },
-            {
-              $or: [{
-                createdAt: { $lt: new Date(nextCreatedDate) }
-              },
-              {
-                // If the created date is an exact match, we need a tiebreaker,
-                // so we use the _id field from the cursor.
-                createdAt: new Date(nextCreatedDate),
-                _id: { $lt: nextId }
-              }
-              ]
-            }
-          ]
-        }
-      }
-    } else {
-      filters = { $match: { userUuid } }
+    const filters = this.mediaFilters(after, userUuid, 'user')
+    const filteredMedia = await this.aggregateMedia(filters, first)
+    const itemCount = await this.mediaObjectModel.countDocuments({ userUuid })
+    let hasNextPage = false
+    if (filteredMedia.length > first) {
+      // ok there's a next page. remove the extra item.
+      filteredMedia.pop()
+      hasNextPage = true
     }
 
-    const rs = await this.mediaObjectModel.aggregate<MediaObject>([
-      filters,
-      {
-        $sort: { createdAt: -1, _id: -1 }
-      },
-      {
-        $limit: first + 1 // fetch 1 extra to see if there's a next page
-      }
-    ])
+    return {
+      userUuid: userUuid.toUUID().toString(),
+      mediaConnection: this.getMediaConnection(filteredMedia, itemCount, hasNextPage)
+    }
+  }
 
-    const itemCount = await this.mediaObjectModel.countDocuments({ userUuid })
+  /**
+ * Get Area media by page.
+ *
+ * See
+ * - https://engage.so/blog/a-deep-dive-into-offset-and-cursor-based-pagination-in-mongodb/#what-is-cursor-based-pagination
+ * - https://www.mixmax.com/engineering/api-paging-built-the-right-way
+ * - https://graphql.org/learn/pagination/
+ * @param input
+ * @returns
+ */
 
+  async getOneAreaMediaPagination (input: AreaMediaQueryInput): Promise<AreaMedia> {
+    const { areaUuid, first = 6, after } = input
+    const filters = this.mediaFilters(after, areaUuid, 'area')
+    const filteredMedia = await this.aggregateMedia(filters, first)
+    const itemCount = await this.mediaObjectModel.countDocuments({ 'entityTags.ancestors': { $regex: areaUuid.toUUID().toString() } })
     let hasNextPage = false
-    if (rs.length > first) {
-      // ok there's a next page. remove the extra item.
-      rs.pop()
+    if (filteredMedia.length > first) {
+      filteredMedia.pop()
       hasNextPage = true
     }
 
     return {
-      userUuid: userUuid.toUUID().toString(),
-      mediaConnection: {
-        edges: rs.map(node => (
-          {
-            node,
-            cursor: `${node.createdAt.getTime()}_${node._id.toString()}`
-          }
-        )),
-        pageInfo: {
-          hasNextPage,
-          totalItems: itemCount,
-          endCursor: null
-        }
+      areaUuid: areaUuid.toUUID().toString(),
+      mediaConnection: this.getMediaConnection(filteredMedia, itemCount, hasNextPage)
+    }
+  }
 
-      }
+  async getOneClimbMediaPagination (input: ClimbMediaQueryInput): Promise<ClimbMedia> {
+    const { climbUuid, first = 6, after } = input
+    const filters = this.mediaFilters(after, climbUuid, 'climb')
+    const filteredMedia = await this.aggregateMedia(filters, first)
+    const itemCount = await this.mediaObjectModel.countDocuments({ 'entityTags.targetId': muid.from(climbUuid) })
+    let hasNextPage = false
+    if (filteredMedia.length > first) {
+      filteredMedia.pop()
+      hasNextPage = true
+    }
+
+    return {
+      climbUuid: climbUuid.toUUID().toString(),
+      mediaConnection: this.getMediaConnection(filteredMedia, itemCount, hasNextPage)
     }
   }
 
@@ -270,7 +263,7 @@ export default class MediaDataSource extends MongoDataSource<MediaObject> {
    *
    * @param areaId
    * @param ancestors
-   * @returns `UserMediaWithTags` array
+   * @returns `MediaWithTags` array
    */
   async findMediaByAreaId (areaId: MUUID, projection: any, shouldConvertUuidToString = false): Promise<MediaObject[]> {
     const transformFn = (doc: MediaObject): any => {
@@ -304,4 +297,82 @@ export default class MediaDataSource extends MongoDataSource<MediaObject> {
     const doc = await this.mediaObjectModel.find({ _id, userUuid }, { _id: 1 }).lean()
     return doc != null
   }
+
+  /**
+   * helper functions for quering media objects by user, area, or climb. Each query has slightly different syntax,
+   * so these private functions return the appropriate filter for the query.
+   * @param entityUuid area, climb or user uuid
+   * @param entityType 'area', 'climb', or 'user'
+   * @returns
+   */
+
+  private mediaFilters (after: string | undefined, entityUuid: MUUID, entityType: string): any {
+    let nextCreatedDate: number
+    let nextId: mongoose.Types.ObjectId
+    let filters: any
+    const matchClause = this.getMatchClause(entityUuid, entityType)
+
+    if (after != null) {
+      const d = after.split('_')
+      nextCreatedDate = Number.parseInt(d[0])
+      nextId = new mongoose.Types.ObjectId(d[1])
+      filters = {
+        $match: {
+          $and: [
+            matchClause,
+            {
+              $or: [{
+                createdAt: { $lt: new Date(nextCreatedDate) }
+              },
+              {
+                // If the created date is an exact match, we need a tiebreaker,
+                // so we use the _id field from the cursor.
+                createdAt: new Date(nextCreatedDate),
+                _id: { $lt: nextId }
+              }
+              ]
+            }
+          ]
+        }
+      }
+    } else {
+      filters = { $match: matchClause }
+    }
+    return filters
+  }
+
+  private getMatchClause (entityUuid: MUUID, entityType: string): any {
+    if (entityType === 'user') {
+      return { userUuid: entityUuid }
+    } else if (entityType === 'area') {
+      return { 'entityTags.ancestors': { $regex: entityUuid.toUUID().toString() } }
+    } else if (entityType === 'climb') {
+      return { 'entityTags.targetId': entityUuid }
+    }
+    throw new Error(`Unexpected entity type: ${entityType}`)
+  }
+
+  private async aggregateMedia (filters: any, first: number): Promise<MediaObject[]> {
+    return await this.mediaObjectModel.aggregate<MediaObject>([
+      filters,
+      { $sort: { createdAt: -1, _id: -1 } },
+      { $limit: first + 1 } // fetch 1 extra to see if there's a next page
+    ])
+  }
+
+  private getMediaConnection (filteredMedia: MediaObject[], itemCount: number, hasNextPage: boolean): any {
+    return {
+      edges: filteredMedia.map(node => (
+        {
+          node,
+          cursor: `${node.createdAt.getTime()}_${node._id.toString()}`
+        }
+      )),
+      pageInfo: {
+        hasNextPage,
+        totalItems: itemCount,
+        endCursor: null
+      }
+    }
+  }
 }
