feat(api): Add pagination metadata to Environment module

apps/api/src/common/paginate.spec.ts

@@ -0,0 +1,93 @@
+import { paginate } from './paginate'
+
+describe('paginate', () => {
+  it('should paginate without default query', () => {
+    const totalCount = 100
+    const relativeUrl = '/items'
+    const query = { page: 2, limit: 10 }
+
+    const result = paginate(totalCount, relativeUrl, query)
+
+    expect(result).toBeDefined()
+    expect(result).toEqual(
+      expect.objectContaining({
+        page: 2,
+        perPage: 10,
+        pageCount: 10,
+        totalCount: 100
+      })
+    )
+    expect(result.links.self).toEqual('/items?page=2&limit=10')
+    expect(result.links.first).toEqual('/items?page=0&limit=10')
+    expect(result.links.previous).toEqual('/items?page=1&limit=10')
+    expect(result.links.next).toEqual('/items?page=3&limit=10')
+    expect(result.links.last).toEqual('/items?page=9&limit=10')
+  })
+
+  it('should paginate with default query', () => {
+    const totalCount = 100
+    const relativeUrl = '/items'
+    const query = { page: 5, limit: 10 }
+    const defaultQuery = { pricing: 'pro', filter: 'admin' }
+
+    const result = paginate(totalCount, relativeUrl, query, defaultQuery)
+
+    expect(result).toBeDefined()
+    expect(result).toEqual(
+      expect.objectContaining({
+        page: 5,
+        perPage: 10,
+        pageCount: 10,
+        totalCount: 100
+      })
+    )
+    expect(result.links.self).toEqual(
+      '/items?filter=admin&pricing=pro&page=5&limit=10'
+    )
+    expect(result.links.first).toEqual(
+      '/items?filter=admin&pricing=pro&page=0&limit=10'
+    )
+    expect(result.links.previous).toEqual(
+      '/items?filter=admin&pricing=pro&page=4&limit=10'
+    )
+    expect(result.links.next).toEqual(
+      '/items?filter=admin&pricing=pro&page=6&limit=10'
+    )
+    expect(result.links.last).toEqual(
+      '/items?filter=admin&pricing=pro&page=9&limit=10'
+    )
+  })
+
+  it('should paginate correctly edge cases where pervious or next is null', () => {
+    const totalCount = 10
+    const relativeUrl = '/items'
+    const query = { page: 0, limit: 10 }
+
+    const result = paginate(totalCount, relativeUrl, query)
+
+    expect(result).toBeDefined()
+    expect(result).toEqual(
+      expect.objectContaining({
+        page: 0,
+        perPage: 10,
+        pageCount: 1,
+        totalCount: 10
+      })
+    )
+    expect(result.links.self).toEqual('/items?page=0&limit=10')
+    expect(result.links.first).toEqual('/items?page=0&limit=10')
+    expect(result.links.previous).toBeNull()
+    expect(result.links.next).toBeNull()
+    expect(result.links.last).toEqual('/items?page=0&limit=10')
+  })
+
+  it('should not be able to paginate when limit is 0 or undefined', () => {
+    const totalCount = 10
+    const relativeUrl = '/items'
+    const query = { page: 0, limit: 0 }
+
+    expect(() => paginate(totalCount, relativeUrl, query)).toThrow(
+      'Limit is required'
+    )
+  })
+})

apps/api/src/common/paginate.ts

@@ -0,0 +1,75 @@
+export interface PaginatedMetadata {
+  page: number
+  perPage: number
+  pageCount: number
+  totalCount: number
+  links: {
+    self: string
+    first: string
+    previous: string | null
+    next: string | null
+    last: string
+  }
+}
+
+interface QueryOptions {
+  page: number
+  limit: number
+  sort?: string
+  order?: string
+  search?: string
+}
+
+//convert query object to query string to use in links
+const getQueryString = (query: QueryOptions) => {
+  return Object.keys(query)
+    .map((key) => `${key}=${query[key]}`)
+    .join('&')
+}
+
+export const paginate = (
+  totalCount: number,
+  relativeUrl: string,
+  query: QueryOptions,
+  defaultQuery?: Record<string, any>
+) => {
+  //query.limit cannot be 0 or undefined
+  if (!query.limit) throw new Error('Limit is required')
+  let defaultQueryStr = ''
+  if (defaultQuery) {
+    //sorting entries to make sure the order is consistent and predictable during tests
+    const sortedEntries = Object.entries(defaultQuery).sort(([keyA], [keyB]) =>
+      keyA.localeCompare(keyB)
+    )
+    //ignore keys with undefined values. Undefined values may occur when qury params are optional
+    defaultQueryStr = sortedEntries.reduce((res, [key, value]) => {
+      if (value !== undefined) {
+        res += `${key}=${value}&`
+      }
+      return res
+    }, '')
+  }
+
+  const metadata = {} as PaginatedMetadata
+  metadata.page = query.page
+  metadata.perPage = query.limit
+  metadata.pageCount = Math.ceil(totalCount / query.limit)
+  metadata.totalCount = totalCount
+
+  //create links from relativeUrl , defalutQueryStr and query of type QueryOptions
+  metadata.links = {
+    self: `${relativeUrl}?${defaultQueryStr + getQueryString(query)}`,
+    first: `${relativeUrl}?${defaultQueryStr + getQueryString({ ...query, page: 0 })}`,
+    previous:
+      query.page === 0
+        ? null
+        : `${relativeUrl}?${defaultQueryStr + getQueryString({ ...query, page: query.page - 1 })}`,
+    next:
+      query.page === metadata.pageCount - 1
+        ? null
+        : `${relativeUrl}?${defaultQueryStr + getQueryString({ ...query, page: query.page + 1 })}`,
+    last: `${relativeUrl}?${defaultQueryStr + getQueryString({ ...query, page: metadata.pageCount - 1 })}`
+  }
+
+  return metadata
+}

apps/api/src/environment/controller/environment.controller.ts

@@ -57,7 +57,7 @@ export class EnvironmentController {
   async getEnvironmentsOfProject(
     @CurrentUser() user: User,
     @Param('projectId') projectId: string,
-    @Query('page') page: number = 1,
+    @Query('page') page: number = 0,
     @Query('limit') limit: number = 10,
     @Query('sort') sort: string = 'name',
     @Query('order') order: string = 'asc',

apps/api/src/environment/environment.e2e.spec.ts

@@ -27,6 +27,7 @@ import { EventService } from '../event/service/event.service'
 import { EnvironmentService } from './service/environment.service'
 import { UserModule } from '../user/user.module'
 import { UserService } from '../user/service/user.service'
+import { QueryTransformPipe } from '../common/query.transform.pipe'
 
 describe('Environment Controller Tests', () => {
   let app: NestFastifyApplication
@@ -64,6 +65,8 @@ describe('Environment Controller Tests', () => {
     environmentService = moduleRef.get(EnvironmentService)
     userService = moduleRef.get(UserService)
 
+    app.useGlobalPipes(new QueryTransformPipe())
+
     await app.init()
     await app.getHttpAdapter().getInstance().ready()
   })
@@ -399,13 +402,27 @@ describe('Environment Controller Tests', () => {
   it('should be able to fetch all environments of a project', async () => {
     const response = await app.inject({
       method: 'GET',
-      url: `/environment/all/${project1.id}`,
+      url: `/environment/all/${project1.id}?page=0&limit=10`,
       headers: {
         'x-e2e-user-email': user1.email
       }
     })
 
     expect(response.statusCode).toBe(200)
+    //check metadata
+    const metadata = response.json().metadata
+    expect(metadata.totalCount).toEqual(2)
+    expect(metadata.links.self).toBe(
+      `/environment/all/${project1.id}?page=0&limit=10&sort=name&order=asc&search=`
+    )
+    expect(metadata.links.first).toBe(
+      `/environment/all/${project1.id}?page=0&limit=10&sort=name&order=asc&search=`
+    )
+    expect(metadata.links.previous).toBeNull()
+    expect(metadata.links.next).toBeNull()
+    expect(metadata.links.last).toBe(
+      `/environment/all/${project1.id}?page=0&limit=10&sort=name&order=asc&search=`
+    )
   })
 
   it('should not be able to fetch all environments of a project that does not exist', async () => {

apps/api/src/environment/service/environment.service.ts

@@ -17,6 +17,7 @@ import { UpdateEnvironment } from '../dto/update.environment/update.environment'
 import { PrismaService } from '../../prisma/prisma.service'
 import createEvent from '../../common/create-event'
 import { AuthorityCheckerService } from '../../common/authority-checker.service'
+import { paginate } from '../../common/paginate'
 
 @Injectable()
 export class EnvironmentService {
@@ -171,8 +172,8 @@ export class EnvironmentService {
       prisma: this.prisma
     })
 
-    // Get the environments
-    return await this.prisma.environment.findMany({
+    // Get the environments for the required page
+    const items = await this.prisma.environment.findMany({
       where: {
         projectId,
         name: {
@@ -200,6 +201,24 @@ export class EnvironmentService {
         [sort]: order
       }
     })
+    // Calculate metadata for pagination
+    const totalCount = await this.prisma.environment.count({
+      where: {
+        projectId,
+        name: {
+          contains: search
+        }
+      }
+    })
+    const metadata = paginate(totalCount, `/environment/all/${projectId}`, {
+      page,
+      limit,
+      sort,
+      order,
+      search
+    })
+
+    return { items, metadata }
   }
 
   async deleteEnvironment(user: User, environmentId: Environment['id']) {

apps/cli/src/types/index.types.d.ts

@@ -12,4 +12,21 @@ export interface ProfileConfig {
   }
 }
 
+export interface Page<T> {
+  items: T[]
+  metadata: {
+    page: number
+    perPage: number
+    pageCount: number
+    totalCount: number
+    links: {
+      self: string
+      first: string
+      previous: string | null
+      next: string | null
+      last: string
+    }
+  }
+}
+
 export type PrivateKeyConfig = Record<string, string>

packages/api-client/src/types/environment.types.d.ts

@@ -1,3 +1,5 @@
+import { Page } from '../../../../apps/cli/src/types/index.types'
+
 export interface CreateEnvironmentRequest {
   name: string
   description?: string
@@ -53,8 +55,8 @@ export interface GetAllEnvironmentsOfProjectRequest {
   search?: string
 }
 
-export interface GetAllEnvironmentsOfProjectResponse {
-  items: {
+export interface GetAllEnvironmentsOfProjectResponse
+  extends Page<{
     id: string
     name: string
     description: string | null
@@ -66,8 +68,7 @@ export interface GetAllEnvironmentsOfProjectResponse {
       email: string
       profilePictureUrl: string | null
     }
-  }[]
-}
+  }> {}
 
 export interface DeleteEnvironmentRequest {
   id: string