feat: added global configuration to simplify global routes configs and fixed a bug with an empty string origin (#1092)

Author: vsamofal

README.md

@@ -27,6 +27,25 @@ npm install nestjs-paginate
 
 ## Usage
 
+### Global configurations
+
+You can configure the global settings for all paginated routes by updating the default global configuration
+using below method. Ideally, you need to do it as soon as possible in your application main bootstrap method,
+as it affects all paginated routes, and swagger generation logic.
+
+```typescript
+import { updateGlobalConfig } from 'nestjs-paginate'
+
+updateGlobalConfig({
+  // this is default configuration
+  defaultOrigin: undefined,
+  defaultLimit: 20,
+  defaultMaxLimit: 100,
+});
+```
+
+
+
 ### Example
 
 The following code exposes a route that can be utilized like so:

src/global-config.ts

@@ -0,0 +1,17 @@
+export interface NestjsPaginateGlobalConfig {
+    defaultOrigin: string | undefined
+    defaultLimit: number
+    defaultMaxLimit: number
+}
+
+const globalConfig: NestjsPaginateGlobalConfig = {
+    defaultOrigin: undefined,
+    defaultLimit: 20,
+    defaultMaxLimit: 100,
+}
+
+export const updateGlobalConfig = (newConfig: Partial<NestjsPaginateGlobalConfig>) => {
+    Object.assign(globalConfig, newConfig)
+}
+
+export default globalConfig

src/helper.ts

@@ -351,3 +351,11 @@ export function isDateColumnType(type: any): boolean {
 export function quoteVirtualColumn(columnName: string, isMySqlOrMariaDb: boolean): string {
     return isMySqlOrMariaDb ? `\`${columnName}\`` : `"${columnName}"`
 }
+
+export function isNil(v: unknown): boolean {
+    return v === null || v === undefined
+}
+
+export function isNotNil(v: unknown): boolean {
+    return !isNil(v)
+}

src/index.ts

@@ -1,3 +1,4 @@
 export * from './decorator'
 export * from './paginate'
 export * from './swagger'
+export * from './global-config'

src/paginate.spec.ts

@@ -22,6 +22,7 @@ import {
     parseFilterToken,
 } from './filter'
 import { paginate, PaginateConfig, Paginated, PaginationLimit, PaginationType } from './paginate'
+import globalConfig, { updateGlobalConfig } from './global-config'
 
 // Disable debug logs during tests
 beforeAll(() => {
@@ -285,6 +286,57 @@ describe('paginate', () => {
         expect(result.data).toStrictEqual(cats.slice(0, 1))
     })
 
+    it('should accept and use empty string as default origin in config, even if global provided', async () => {
+        updateGlobalConfig({
+            defaultOrigin: 'http://localhost:8081',
+        })
+
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+            defaultSortBy: [['id', 'ASC']],
+            defaultLimit: 1,
+            origin: '',
+        }
+
+        const query: PaginateQuery = {
+            path: 'http://localhost:8080/cat',
+        }
+
+        const result = await paginate<CatEntity>(query, catRepo, config)
+
+        expect(result).toBeInstanceOf(Paginated)
+        expect(result.links.current).toStrictEqual('/cat?page=1&limit=1&sortBy=id:ASC')
+
+        updateGlobalConfig({
+            defaultOrigin: undefined,
+        })
+    })
+
+    it('should use default origin from global config if provided, over the one from request', async () => {
+        updateGlobalConfig({
+            defaultOrigin: 'http://localhost:8081',
+        })
+
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+            defaultSortBy: [['id', 'ASC']],
+            defaultLimit: 1,
+        }
+
+        const query: PaginateQuery = {
+            path: 'http://localhost:8080/cat',
+        }
+
+        const result = await paginate<CatEntity>(query, catRepo, config)
+
+        expect(result).toBeInstanceOf(Paginated)
+        expect(result.links.current).toStrictEqual('http://localhost:8081/cat?page=1&limit=1&sortBy=id:ASC')
+
+        updateGlobalConfig({
+            defaultOrigin: undefined,
+        })
+    })
+
     it('should accept a query builder', async () => {
         const config: PaginateConfig<CatEntity> = {
             sortableColumns: ['id'],
@@ -499,7 +551,7 @@ describe('paginate', () => {
 
         const result = await paginate<CatEntity>(query, catRepo, config)
 
-        expect(result.data).toStrictEqual(cats.slice(0, PaginationLimit.DEFAULT_LIMIT))
+        expect(result.data).toStrictEqual(cats.slice(0, globalConfig.defaultLimit))
     })
 
     it('should return the count without data ignoring maxLimit if limit is COUNTER_ONLY', async () => {

src/paginate.ts

@@ -28,6 +28,8 @@ import {
     isEntityKey,
     isFindOperator,
     isISODate,
+    isNil,
+    isNotNil,
     isRepository,
     JoinMethod,
     MappedColumns,
@@ -39,6 +41,7 @@ import {
     RelationSchemaInput,
     SortBy,
 } from './helper'
+import globalConfig from './global-config'
 
 const logger: Logger = new Logger('nestjs-paginate')
 
@@ -105,8 +108,6 @@ export interface PaginateConfig<T> {
 export enum PaginationLimit {
     NO_PAGINATION = -1,
     COUNTER_ONLY = 0,
-    DEFAULT_LIMIT = 20,
-    DEFAULT_MAX_LIMIT = 100,
 }
 
 function generateWhereStatement<T>(
@@ -208,8 +209,8 @@ export async function paginate<T extends ObjectLiteral>(
 
     const page = positiveNumberOrDefault(query.page, 1, 1)
 
-    const defaultLimit = config.defaultLimit || PaginationLimit.DEFAULT_LIMIT
-    const maxLimit = config.maxLimit || PaginationLimit.DEFAULT_MAX_LIMIT
+    const defaultLimit = config.defaultLimit || globalConfig.defaultLimit
+    const maxLimit = config.maxLimit || globalConfig.defaultMaxLimit
 
     const isPaginated = !(
         query.limit === PaginationLimit.COUNTER_ONLY ||
@@ -951,10 +952,10 @@ export async function paginate<T extends ObjectLiteral>(
         const { queryOrigin, queryPath } = getQueryUrlComponents(query.path)
         if (config.relativePath) {
             path = queryPath
-        } else if (config.origin) {
+        } else if (isNotNil(config.origin)) {
             path = config.origin + queryPath
         } else {
-            path = queryOrigin + queryPath
+            path = (isNil(globalConfig.defaultOrigin) ? queryOrigin : globalConfig.defaultOrigin) + queryPath
         }
     }
 

src/swagger/api-paginated-query.decorator.ts

@@ -1,7 +1,8 @@
 import { applyDecorators } from '@nestjs/common'
 import { ApiQuery } from '@nestjs/swagger'
 import { FilterComparator } from '../filter'
-import { FilterOperator, FilterSuffix, PaginateConfig, PaginationLimit } from '../paginate'
+import { FilterOperator, FilterSuffix, PaginateConfig } from '../paginate'
+import globalConfig from '../global-config'
 
 const DEFAULT_VALUE_KEY = 'Default Value'
 
@@ -45,8 +46,8 @@ function Limit(paginationConfig: PaginateConfig<any>) {
         name: 'limit',
         description: `Number of records per page.
       ${p('Example', '20')}
-      ${p(DEFAULT_VALUE_KEY, paginationConfig?.defaultLimit?.toString() || PaginationLimit.DEFAULT_LIMIT.toString())}
-      ${p('Max Value', paginationConfig.maxLimit?.toString() || PaginationLimit.DEFAULT_MAX_LIMIT.toString())}
+      ${p(DEFAULT_VALUE_KEY, paginationConfig?.defaultLimit?.toString() || globalConfig.defaultLimit.toString())}
+      ${p('Max Value', paginationConfig.maxLimit?.toString() || globalConfig.defaultMaxLimit.toString())}
 
       If provided value is greater than max value, max value will be applied.
       `,