pagination: add unified PageInfo, PaginatedResponse factory, and pagination utilities

Author: digitalnomad91

src/common/models/paginated-response.ts

@@ -0,0 +1,23 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { PageInfo } from '../pagination/page-info.model';
+
+/**
+ * Helper factory to create a Swagger-described paginated response class for a given item type.
+ * Example: export class PaginatedJobResponse extends PaginatedResponse(JobDto) {}
+ */
+export function PaginatedResponse<T extends new (...args: any[]) => any>(ItemType: T) {
+  class PaginatedResponseClass {
+    @ApiProperty({ isArray: true, type: ItemType })
+    items!: InstanceType<T>[];
+
+    @ApiProperty({ type: () => PageInfo })
+    pageInfo!: PageInfo;
+
+    @ApiProperty({ description: 'Total number of matching items' })
+    totalCount!: number;
+
+    @ApiProperty({ description: 'Optional contextual metadata (e.g., company, tag)', required: false })
+    meta?: Record<string, any> | null;
+  }
+  return PaginatedResponseClass;
+}

src/common/pagination/page-info.model.ts

@@ -1,16 +1,29 @@
 import { Field, ObjectType } from '@nestjs/graphql';
+import { ApiProperty } from '@nestjs/swagger';
 
 @ObjectType()
 export class PageInfo {
+  @ApiProperty({ required: false, nullable: true, description: 'Cursor of last item in current page' })
   @Field(() => String, { nullable: true })
   endCursor?: string;
 
+  @ApiProperty({ description: 'Is there another page after this one?' })
   @Field(() => Boolean)
   hasNextPage: boolean;
 
+  @ApiProperty({ description: 'Is there a page before this one?' })
   @Field(() => Boolean)
   hasPreviousPage: boolean;
 
+  @ApiProperty({ required: false, nullable: true, description: 'Cursor of first item in current page' })
   @Field(() => String, { nullable: true })
   startCursor?: string;
+
+  // Retained for backward compatibility in REST where totalCount previously lived under pageInfo
+  @ApiProperty({
+    description: '(Deprecated – use top-level totalCount) Total number of matching items',
+    required: false,
+  })
+  @Field(() => Number, { nullable: true })
+  totalCount?: number;
 }

src/common/pagination/pagination.args.ts

@@ -1,14 +1,60 @@
 import { ArgsType } from '@nestjs/graphql';
+import { Field } from '../decorators/field.decorator';
 
 @ArgsType()
 export class PaginationArgs {
+  @Field({
+    name: 'skip',
+    description: 'Number of records to skip (offset based pagination).',
+    isInt: { message: 'skip must be an integer.' },
+    optional: true,
+    inQuery: true,
+    example: 0,
+    type: Number,
+  })
   skip?: number;
 
+  @Field({
+    name: 'after',
+    description: 'Cursor to start after (forward cursor pagination).',
+    isString: { message: 'after must be a string cursor.' },
+    optional: true,
+    inQuery: true,
+    example: 'cursor123',
+    type: String,
+  })
   after?: string;
 
+  @Field({
+    name: 'before',
+    description: 'Cursor to end before (backward cursor pagination).',
+    isString: { message: 'before must be a string cursor.' },
+    optional: true,
+    inQuery: true,
+    example: 'cursor122',
+    type: String,
+  })
   before?: string;
 
+  @Field({
+    name: 'first',
+    description: 'Max number of items to return going forward from the cursor.',
+    isInt: { message: 'first must be an integer.' },
+    optional: true,
+    inQuery: true,
+    example: 25,
+    type: Number,
+  })
   first?: number;
 
+  @Field({
+    name: 'last',
+    description: 'Max number of items to return going backward from the cursor.',
+    isInt: { message: 'last must be an integer.' },
+    optional: true,
+    inQuery: true,
+    example: 25,
+    type: Number,
+  })
   last?: number;
 }

src/common/pagination/pagination.util.ts

@@ -0,0 +1,33 @@
+import { PageInfo } from './page-info.model';
+
+export interface BuildPaginationArgs {
+  skip: number;
+  take: number;
+  totalCount: number;
+  currentItemsLength: number;
+}
+
+export function buildPageInfo({ skip, take, totalCount, currentItemsLength }: BuildPaginationArgs): PageInfo {
+  return {
+    hasNextPage: skip + take < totalCount,
+    hasPreviousPage: skip > 0,
+    startCursor: String(skip),
+    endCursor: String(skip + currentItemsLength),
+  } as PageInfo;
+}
+
+export function buildPaginatedResult<T>(params: {
+  items: T[];
+  skip: number;
+  take: number;
+  totalCount: number;
+  meta?: Record<string, any> | null;
+}) {
+  const { items, skip, take, totalCount, meta = null } = params;
+  return {
+    items,
+    pageInfo: buildPageInfo({ skip, take, totalCount, currentItemsLength: items.length }),
+    totalCount,
+    meta,
+  };
+}