@squiz/job-runner-lib 1.66.1

package/src/domains/job/core/pagination/services/PaginationService.spec.ts

@@ -0,0 +1,248 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+import { AttributeValue } from '@aws-sdk/client-dynamodb';
+import { faker } from '@faker-js/faker/locale/en';
+import { createMockJob } from '../../../model/Job/mocks/Job.mock';
+import { createMockJobContext } from '../../../model/JobContext/mocks/JobContext.mock';
+import { createMockJobExecution } from '../../../model/JobExecution/mocks/JobExecution.mock';
+import { InternalServerError } from '../../../errors/InternalServerError';
+import { PartitionKey, PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { PaginationInfo } from '../model/PaginationInfo';
+import { PAGINATION_DIRECTION_TYPE_AFTER, PAGINATION_DIRECTION_TYPE_BEFORE } from '../model/PaginationTypes';
+import { encodeTokenString } from '../utils/PaginationUtils';
+import { PaginationService } from './PaginationService';
+import { JobRepository, JobContextRepository, JobExecutionRepository } from '../../../repository';
+
+describe('PaginationService', (): void => {
+  let jobRepository: Record<string, object>;
+  let jobContextRepository: Record<string, object>;
+  let jobExecutionRepository: Record<string, object>;
+  let paginationService: PaginationService<any>;
+
+  const mockConvertToDynamoDbItemJob = jest.fn();
+  const mockConvertToDynamoDbItemContext = jest.fn();
+  const mockConvertToDynamoDbItemExecution = jest.fn();
+
+  beforeAll((): void => {
+    jobRepository = {
+      create: jest.fn(),
+      findOne: jest.fn(),
+      list: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn(),
+
+      getJobs: jest.fn(),
+      convertToDynamoDbItem: mockConvertToDynamoDbItemJob,
+    };
+
+    jobContextRepository = {
+      create: jest.fn(),
+      findOne: jest.fn(),
+      list: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn(),
+      getContexts: jest.fn(),
+
+      getJobs: jest.fn(),
+      convertToDynamoDbItem: mockConvertToDynamoDbItemContext,
+    };
+
+    jobExecutionRepository = {
+      create: jest.fn(),
+      findOne: jest.fn(),
+      list: jest.fn(),
+      update: jest.fn(),
+      delete: jest.fn(),
+
+      getJobs: jest.fn(),
+      convertToDynamoDbItem: mockConvertToDynamoDbItemExecution,
+    };
+
+    paginationService = new PaginationService<any>(
+      jobRepository as unknown as JobRepository,
+      jobContextRepository as unknown as JobContextRepository,
+      jobExecutionRepository as unknown as JobExecutionRepository,
+    );
+  });
+
+  describe('addPaginationLinksToResponse', (): void => {
+    let mockType: PartitionKey;
+    let mockData;
+    let mockPaginationInfo: PaginationInfo;
+    let mockExclusiveStartKey: Record<string, AttributeValue>;
+    let mockLastEvaluatedKey: string | null;
+
+    beforeEach(() => {
+      jest.resetAllMocks();
+
+      mockType = PARTITION_KEYS.job;
+
+      mockPaginationInfo = {
+        direction: PAGINATION_DIRECTION_TYPE_AFTER,
+        limit: 20,
+        requestUrl: 'mockUrl',
+        token: 'mockToken',
+      };
+
+      mockExclusiveStartKey = {
+        pk: { S: 'mockPk' },
+        sk: { S: 'mockSk' },
+      };
+    });
+
+    it('should return a full page of items including links', (): void => {
+      mockData = Array.from({ length: faker.number.int({ min: 1, max: mockPaginationInfo.limit - 1 }) }).map(
+        (_, i) => ({
+          type: mockType,
+          pk: `mockPk${i}`,
+          sk: `mockSk${i}`,
+        }),
+      );
+
+      mockConvertToDynamoDbItemJob
+        .mockImplementationOnce(() => {
+          return mockExclusiveStartKey;
+        })
+        .mockImplementationOnce(() => {
+          return mockExclusiveStartKey;
+        });
+
+      const response = paginationService.addPaginationLinksToResponse(
+        mockData,
+        mockPaginationInfo,
+        mockPaginationInfo.token,
+      );
+
+      expect(mockConvertToDynamoDbItemJob).toBeCalledTimes(1);
+      expect(response.data).toStrictEqual(mockData);
+
+      expect(response.links).toBeTruthy();
+      expect(response.links.prev).toContain(encodeURIComponent(encodeTokenString(mockExclusiveStartKey)));
+      expect(response.links.next).toContain(mockPaginationInfo.token);
+    });
+
+    it('should return a page of items with `null` links when the data is less than the limit', (): void => {
+      mockData = Array.from({
+        length: faker.number.int({
+          min: 1,
+          max: mockPaginationInfo.limit - 1,
+        }),
+      }).map((_, i) => ({ type: mockType, i }));
+
+      mockConvertToDynamoDbItemJob.mockImplementationOnce(() => mockExclusiveStartKey);
+
+      const response = paginationService.addPaginationLinksToResponse(
+        mockData,
+        { ...mockPaginationInfo, token: null },
+        null,
+      );
+
+      expect(mockConvertToDynamoDbItemJob).not.toBeCalled();
+      expect(response.data).toStrictEqual(mockData);
+      expect(response.links).toBeTruthy();
+      expect(response.links.prev).toBeNull();
+      expect(response.links.next).toBeNull();
+    });
+
+    it('should return a page of items with non-null previous links when the data is less than the limit but request included a token', (): void => {
+      mockData = Array.from({
+        length: faker.number.int({
+          min: 1,
+          max: mockPaginationInfo.limit - 1,
+        }),
+      }).map((_, i) => ({ type: mockType, i }));
+
+      mockConvertToDynamoDbItemJob.mockImplementationOnce(() => mockExclusiveStartKey);
+
+      const response = paginationService.addPaginationLinksToResponse(
+        mockData,
+        mockPaginationInfo,
+        mockLastEvaluatedKey,
+      );
+
+      expect(mockConvertToDynamoDbItemJob).toBeCalledTimes(1);
+      expect(response.data).toStrictEqual(mockData);
+      expect(response.links).toBeTruthy();
+      expect(response.links.prev).toBeTruthy();
+      expect(response.links.next).toBeNull();
+    });
+
+    it('should reverse the data appropriately when paginating in reverse', (): void => {
+      mockData = Array.from({
+        length: faker.number.int({
+          min: 1,
+          max: mockPaginationInfo.limit - 1,
+        }),
+      }).map((_, i) => ({ type: mockType, i }));
+
+      mockConvertToDynamoDbItemJob.mockImplementationOnce(() => mockExclusiveStartKey);
+
+      const response = paginationService.addPaginationLinksToResponse(
+        mockData,
+        { ...mockPaginationInfo, direction: PAGINATION_DIRECTION_TYPE_BEFORE },
+        mockLastEvaluatedKey,
+      );
+
+      expect(mockConvertToDynamoDbItemJob).toBeCalledTimes(1);
+      expect(response.data).toStrictEqual(mockData.reverse());
+      expect(response.links).toBeTruthy();
+    });
+
+    it('should only return the limited number of items even if DB contains more', (): void => {
+      mockData = Array.from({
+        length: faker.number.int({
+          min: mockPaginationInfo.limit + 1,
+          max: mockPaginationInfo.limit * 2,
+        }),
+      }).map((_, i) => ({ type: mockType, i }));
+
+      mockConvertToDynamoDbItemJob
+        .mockImplementationOnce(() => mockExclusiveStartKey)
+        .mockImplementationOnce(() => mockExclusiveStartKey);
+
+      const response = paginationService.addPaginationLinksToResponse(
+        mockData,
+        mockPaginationInfo,
+        mockLastEvaluatedKey,
+      );
+
+      expect(mockConvertToDynamoDbItemJob).toBeCalledTimes(2);
+      expect(response.data).toHaveLength(mockPaginationInfo.limit);
+      expect(response.links).toBeTruthy();
+    });
+  });
+
+  describe('convertToDynamoDbItem', (): void => {
+    beforeEach(() => {
+      jest.resetAllMocks();
+    });
+    it('should call the jobRepository method for converting to a DynamoDB object', (): void => {
+      const mockJob = createMockJob();
+
+      (paginationService as any).convertToDynamoDbItem(mockJob);
+      expect(mockConvertToDynamoDbItemJob).toBeCalled();
+    });
+
+    it('should call the jobContextRepository method for converting to a DynamoDB object', (): void => {
+      const mockJobContext = createMockJobContext();
+
+      (paginationService as any).convertToDynamoDbItem(mockJobContext);
+      expect(mockConvertToDynamoDbItemContext).toBeCalled();
+    });
+
+    it('should call the jobExecutionRepository method for converting to a DynamoDB object', (): void => {
+      const mockJobExecution = createMockJobExecution();
+
+      (paginationService as any).convertToDynamoDbItem(mockJobExecution);
+      expect(mockConvertToDynamoDbItemExecution).toBeCalled();
+    });
+
+    it('should should throw an error if the partition key is invalid', (): void => {
+      const mockItem = { type: 'invalid' };
+      expect(() => (paginationService as any).convertToDynamoDbItem(mockItem)).toThrowError(InternalServerError);
+    });
+  });
+});

package/src/domains/job/core/pagination/services/PaginationService.ts

@@ -0,0 +1,142 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+import 'reflect-metadata';
+import { inject } from 'inversify';
+import { provideSingleton } from '../../../singletonProvider';
+import { BaseItem, BaseDto } from '../../../model/Base/Base';
+import { JobRepository } from '../../../repository/JobRepository/JobRepository';
+import { PARTITION_KEYS } from '../../../constants/Repository.constants';
+import { PaginationInfo } from '../model/PaginationInfo';
+import { PaginationTokens } from '../model/PaginationLinks';
+import { PaginationResponse } from '../model/PaginationResponse';
+import { PAGINATION_DIRECTION_TYPE_BEFORE } from '../model/PaginationTypes';
+import { encodeTokenString, getPaginationLinks } from '../utils/PaginationUtils';
+import { InternalServerError } from '../../../errors/InternalServerError';
+import { ERROR_MESSAGES } from '../../../errors/Error.constants';
+import { JobContextRepository } from '../../../repository/JobContextRepository/JobContextRepository';
+import { JobExecutionRepository } from '../../../repository/JobExecutionRepository/JobExecutionRepository';
+
+/**
+ * Helper service to handle pagination.
+ * @export
+ * @abstract
+ * @class PaginationService
+ */
+@provideSingleton(PaginationService)
+export class PaginationService<T extends BaseItem> {
+  constructor(
+    @inject(JobRepository) protected jobRepository: JobRepository,
+    @inject(JobContextRepository) protected jobContextRepository: JobContextRepository,
+    @inject(JobExecutionRepository) protected jobExecutionRepository: JobExecutionRepository,
+  ) {}
+
+  public addPaginationLinksToResponse(
+    data: Array<T>,
+    paginationInfo: PaginationInfo,
+    lastEvaluatedKey: string | null,
+  ): PaginationResponse<T> {
+    const { direction, limit, requestUrl } = paginationInfo;
+
+    const paginationTokens = this.getPaginationTokens(data, paginationInfo, lastEvaluatedKey);
+    const links = getPaginationLinks(requestUrl, paginationTokens);
+    data = data.slice(0, limit);
+
+    if (direction === PAGINATION_DIRECTION_TYPE_BEFORE) {
+      data = data.reverse();
+    }
+
+    return { links, data };
+  }
+
+  protected getPaginationTokens(
+    data: Array<T>,
+    paginationInfo: PaginationInfo,
+    lastEvaluatedKey: string | null,
+  ): PaginationTokens {
+    const { token, direction, limit } = paginationInfo;
+
+    let firstItemToken: string | null = null;
+    let lastItemToken: string | null = null;
+
+    if (token || direction === PAGINATION_DIRECTION_TYPE_BEFORE) {
+      firstItemToken = this.getTokenForFirstData(data);
+    }
+
+    if (data.length <= limit) {
+      lastItemToken = lastEvaluatedKey;
+    } else {
+      data = data.slice(0, limit);
+      lastItemToken = this.getTokenForLastData(data);
+    }
+
+    let nextToken = lastItemToken;
+    let prevToken = firstItemToken;
+
+    if (direction === PAGINATION_DIRECTION_TYPE_BEFORE) {
+      nextToken = firstItemToken;
+      prevToken = lastItemToken;
+    }
+
+    return {
+      next: nextToken ? encodeURIComponent(nextToken) : null,
+      prev: prevToken ? encodeURIComponent(prevToken) : null,
+    };
+  }
+
+  /**
+   * Get the encoded token for the first item of the data array.
+   * @param {Array<T>} data The array of items.
+   * @returns {string} The token string.
+   * @memberof Repository
+   */
+  protected getTokenForFirstData(data: Array<T>): string {
+    const firstData = data[0];
+    const firstDynamoItem = this.convertToDynamoDbItem(firstData);
+
+    const { pk, sk } = firstDynamoItem;
+
+    const primaryKey = {
+      pk,
+      sk,
+    };
+
+    return encodeTokenString(primaryKey);
+  }
+
+  /**
+   * Get the encoded token for last item of the data array.
+   * @param {Array<T>} data The array of items.
+   * @returns {string} The token string.
+   * @memberof Repository
+   */
+  protected getTokenForLastData(data: Array<T>): string {
+    const lastData = data[data.length - 1];
+    const lastDynamoItem = this.convertToDynamoDbItem(lastData);
+
+    const { pk, sk } = lastDynamoItem;
+
+    const primaryKey = {
+      pk,
+      sk,
+    };
+
+    return encodeTokenString(primaryKey);
+  }
+
+  protected convertToDynamoDbItem = (item: any): BaseDto => {
+    if (item.type.startsWith(PARTITION_KEYS.jobExecution)) {
+      return this.jobExecutionRepository.convertToDynamoDbItem(item);
+    }
+    switch (item.type) {
+      case PARTITION_KEYS.job:
+        return this.jobRepository.convertToDynamoDbItem(item);
+      case PARTITION_KEYS.context:
+        return this.jobContextRepository.convertToDynamoDbItem(item);
+      default:
+        throw new InternalServerError(ERROR_MESSAGES.primaryKeyInvalidPK);
+    }
+  };
+}

package/src/domains/job/core/pagination/services/index.ts

@@ -0,0 +1 @@
+export * from './PaginationService';

package/src/domains/job/core/pagination/utils/PaginationUtils.spec.ts

@@ -0,0 +1,263 @@
+/*!
+ * @license
+ * Copyright Squiz Australia Pty Ltd. All Rights Reserved.
+ */
+
+import { faker } from '@faker-js/faker/locale/en';
+import { QUERY } from '../../../constants/QueryParams';
+import { BadRequestError } from '../../../errors/BadRequestError';
+import { InternalServerError } from '../../../errors/InternalServerError';
+import { PAGINATION_DIRECTION_TYPE_AFTER, PAGINATION_DIRECTION_TYPE_BEFORE } from '../model/PaginationTypes';
+import {
+  decodeTokenString,
+  encodeTokenString,
+  getFormattedResponse,
+  getPaginationInfo,
+  getPaginationLinks,
+  validateTokenHasCorrectFormat,
+} from './PaginationUtils';
+import { PaginationLinks } from '../model';
+
+const mockToken = 'eyJwayI6eyJTIjoiZm9vIn0sInNrIjp7IlMiOiJiYXIifX0=';
+const mockPrimaryKey = {
+  pk: { S: 'foo' },
+  sk: { S: 'bar' },
+};
+
+describe('PaginationUtils', () => {
+  describe('decodeTokenString', () => {
+    it('should decode a valid token string', () => {
+      const result = decodeTokenString(mockToken);
+      expect(result).toStrictEqual(mockPrimaryKey);
+    });
+
+    it('should throw a BadRequestError if decode fails', () => {
+      const mockBadToken = '';
+
+      expect(() => {
+        decodeTokenString(mockBadToken);
+      }).toThrow(BadRequestError);
+    });
+  });
+
+  describe('encodeTokenString', () => {
+    it('should encode a valid key', () => {
+      const result = encodeTokenString(mockPrimaryKey);
+      expect(result).toStrictEqual(mockToken);
+    });
+
+    it('should throw a InternalServerError if encode fails', () => {
+      const mockBadKey = undefined;
+
+      expect(() => {
+        encodeTokenString(mockBadKey);
+      }).toThrow(InternalServerError);
+    });
+  });
+
+  describe('getPaginationInfo', () => {
+    let mockPageQuery: Record<string, string | number | undefined>;
+    let mockPageSize: number;
+    let mockRequestUrl: string;
+
+    beforeEach(() => {
+      mockPageSize = faker.helpers.arrayElement([20, 50, 100]);
+      mockRequestUrl = faker.internet.url();
+
+      mockPageQuery = {
+        after: mockToken,
+        size: mockPageSize,
+      };
+    });
+
+    it('should handle page[after] and page[size] params', () => {
+      const result = getPaginationInfo(mockRequestUrl, mockPageQuery);
+      expect(result).toStrictEqual({
+        direction: PAGINATION_DIRECTION_TYPE_AFTER,
+        limit: mockPageSize,
+        requestUrl: mockRequestUrl,
+        token: mockToken,
+      });
+    });
+
+    it('should handle page[before] and page[size] params', () => {
+      mockPageQuery.after = undefined;
+      mockPageQuery.before = mockToken;
+
+      const result = getPaginationInfo(mockRequestUrl, mockPageQuery);
+      expect(result).toStrictEqual({
+        direction: PAGINATION_DIRECTION_TYPE_BEFORE,
+        limit: mockPageSize,
+        requestUrl: mockRequestUrl,
+        token: mockToken,
+      });
+    });
+
+    it('should fallback to default limit if page[size] not defined', () => {
+      mockPageQuery.size = undefined;
+
+      const result = getPaginationInfo(mockRequestUrl, mockPageQuery);
+      expect(result.limit).toBe(100);
+    });
+
+    describe('Error handling', () => {
+      it('should throw a BadRequestError if both page[before] and page[after] are present in the request', () => {
+        mockPageQuery.before = mockToken;
+
+        expect(() => {
+          getPaginationInfo(mockRequestUrl, mockPageQuery);
+        }).toThrow(BadRequestError);
+      });
+    });
+  });
+
+  describe('getPaginationLinks', () => {
+    let mockRequestUrl: string;
+    let mockNextToken;
+    let mockPrevToken;
+
+    let mockTokens: PaginationLinks;
+
+    let mockPageAfterParam: string;
+    let mockPageBeforeParam: string;
+
+    beforeEach(() => {
+      mockRequestUrl = faker.internet.url();
+      mockNextToken = 'mockNextToken';
+      mockPrevToken = 'mockPrevToken';
+
+      mockTokens = {
+        next: mockNextToken,
+        prev: mockPrevToken,
+      };
+
+      mockPageAfterParam = `${QUERY.PAGE.AFTER}=${mockNextToken}`;
+      mockPageBeforeParam = `${QUERY.PAGE.BEFORE}=${mockPrevToken}`;
+    });
+
+    it('should handle a request URL with no other parameters', () => {
+      const result = getPaginationLinks(`${mockRequestUrl}/api`, mockTokens);
+      expect(result).toStrictEqual({
+        next: `${mockRequestUrl}?${mockPageAfterParam}`,
+        prev: `${mockRequestUrl}?${mockPageBeforeParam}`,
+      });
+    });
+
+    it('should handle a request URL with other query parameters', () => {
+      const mockSizeParam = `${QUERY.PAGE.SIZE}=50`;
+
+      const result = getPaginationLinks(`${mockRequestUrl}/api?${mockSizeParam}`, mockTokens);
+      expect(result).toStrictEqual({
+        next: `${mockRequestUrl}?${mockSizeParam}&${mockPageAfterParam}`,
+        prev: `${mockRequestUrl}?${mockSizeParam}&${mockPageBeforeParam}`,
+      });
+    });
+
+    it('should replace page[before] and/or page[after] request params with new tokens', () => {
+      const mockRequestAfterBeforeParams = `${QUERY.PAGE.AFTER}=mockRequestAfter&${QUERY.PAGE.BEFORE}=mockRequestBefore`;
+
+      const result = getPaginationLinks(`${mockRequestUrl}/api?${mockRequestAfterBeforeParams}`, mockTokens);
+      expect(result).toStrictEqual({
+        next: `${mockRequestUrl}?${mockPageAfterParam}`,
+        prev: `${mockRequestUrl}?${mockPageBeforeParam}`,
+      });
+    });
+
+    it('should handle null tokens', () => {
+      mockTokens = {
+        next: null,
+        prev: null,
+      };
+
+      const mockQueryParam = `${QUERY.PAGE.SIZE}=50`;
+
+      const result1 = getPaginationLinks(`${mockRequestUrl}/api?${mockQueryParam}`, mockTokens);
+      expect(result1).toStrictEqual({
+        next: null,
+        prev: null,
+      });
+
+      const result2 = getPaginationLinks(`${mockRequestUrl}/api`, mockTokens);
+      expect(result2).toStrictEqual({
+        next: null,
+        prev: null,
+      });
+    });
+  });
+
+  describe('validateTokenHasCorrectFormat', () => {
+    it('should not throw error for a valid token', () => {
+      expect(() => {
+        validateTokenHasCorrectFormat(mockToken);
+      }).not.toThrow();
+    });
+
+    it('should not throw error for a `null` token', () => {
+      expect(() => {
+        validateTokenHasCorrectFormat(null);
+      }).not.toThrow(BadRequestError);
+    });
+
+    it('should throw a BadRequestError for an invalid token', () => {
+      const badToken1 = 'eyJzayI6InNrIn0='; // missing pk
+      const badToken2 = 'eyJwayI6InBrIn0='; // missing sk
+
+      expect(() => {
+        validateTokenHasCorrectFormat(badToken1);
+      }).toThrow(BadRequestError);
+
+      expect(() => {
+        validateTokenHasCorrectFormat(badToken2);
+      }).toThrow(BadRequestError);
+    });
+  });
+
+  describe('getFormattedResponse', () => {
+    let mockNextToken;
+    let mockPrevToken;
+
+    let mockTokens: PaginationLinks;
+
+    let mockLength;
+    let mockData: object;
+
+    beforeEach(() => {
+      mockNextToken = 'mockNextToken';
+      mockPrevToken = 'mockPrevToken';
+
+      mockTokens = {
+        next: mockNextToken,
+        prev: mockPrevToken,
+      };
+
+      mockLength = faker.number.int({ min: 1, max: 5 });
+      mockData = Array.from({ length: mockLength }).reduce((acc: Record<string, string>, _curr) => {
+        return {
+          ...acc,
+          [faker.lorem.word()]: faker.lorem.words(),
+        };
+      }, {});
+    });
+
+    it('should add links to the final formatted response', (): void => {
+      const response = getFormattedResponse<any>({
+        links: mockTokens,
+        data: [mockData],
+      });
+      expect(response.data[0]).toBe(mockData);
+      expect(response.links).toBe(mockTokens);
+    });
+
+    it('should not add links to the final formatted response if not present', (): void => {
+      const response = getFormattedResponse<any>({
+        links: {
+          next: null,
+          prev: null,
+        },
+        data: [mockData],
+      });
+      expect(response.data[0]).toBe(mockData);
+      expect(response).not.toHaveProperty('links');
+    });
+  });
+});