feat: added control of soft deletion in query params (#1097)

Author: vsamofal

README.md

@@ -53,7 +53,7 @@ The following code exposes a route that can be utilized like so:
 #### Endpoint
 
 ```url
-http://localhost:3000/cats?limit=5&page=2&sortBy=color:DESC&search=i&filter.age=$gte:3&select=id,name,color,age
+http://localhost:3000/cats?limit=5&page=2&sortBy=color:DESC&search=i&filter.age=$gte:3&select=id,name,color,age&withDeleted=true
 ```
 
 #### Result
@@ -339,6 +339,13 @@ const paginateConfig: PaginateConfig<CatEntity> {
    */
   withDeleted: false,
 
+  /**
+   * Required: false
+   * Type: boolean
+   * Description: Allows to specify withDeleted in query params to retrieve soft deleted records, convinient when you have archive functionality and some toggle to show or hide them. If not enabled explicitly the withDeleted query param will be ignored.
+   */
+  allowWithDeletedInQuery: false,
+
   /**
    * Required: false
    * Type: string

src/decorator.spec.ts

@@ -109,6 +109,7 @@ describe('Decorator', () => {
             filter: undefined,
             select: undefined,
             cursor: undefined,
+            withDeleted: undefined,
             path: 'http://localhost/items',
         })
     })
@@ -127,6 +128,7 @@ describe('Decorator', () => {
             filter: undefined,
             select: undefined,
             cursor: undefined,
+            withDeleted: undefined,
             path: 'http://localhost/items',
         })
     })
@@ -137,6 +139,7 @@ describe('Decorator', () => {
             limit: '20',
             sortBy: ['id:ASC', 'createdAt:DESC'],
             search: 'white',
+            withDeleted: 'true',
             'filter.name': '$not:$eq:Kitty',
             'filter.createdAt': ['$gte:2020-01-01', '$lte:2020-12-31'],
             select: ['name', 'createdAt'],
@@ -154,6 +157,7 @@ describe('Decorator', () => {
             ],
             search: 'white',
             searchBy: undefined,
+            withDeleted: true,
             select: ['name', 'createdAt'],
             path: 'http://localhost/items',
             filter: {
@@ -170,6 +174,7 @@ describe('Decorator', () => {
             limit: '20',
             sortBy: ['id:ASC', 'createdAt:DESC'],
             search: 'white',
+            withDeleted: 'false',
             'filter.name': '$not:$eq:Kitty',
             'filter.createdAt': ['$gte:2020-01-01', '$lte:2020-12-31'],
             select: ['name', 'createdAt'],
@@ -187,6 +192,7 @@ describe('Decorator', () => {
             ],
             search: 'white',
             searchBy: undefined,
+            withDeleted: false,
             path: 'http://localhost/items',
             filter: {
                 name: '$not:$eq:Kitty',

src/decorator.ts

@@ -20,6 +20,7 @@ export interface PaginateQuery {
     filter?: { [column: string]: string | string[] }
     select?: string[]
     cursor?: string
+    withDeleted?: boolean
     path: string
 }
 
@@ -103,6 +104,7 @@ export const Paginate = createParamDecorator((_data: unknown, ctx: ExecutionCont
         filter: Object.keys(filter).length ? filter : undefined,
         select,
         cursor: query.cursor ? query.cursor.toString() : undefined,
+        withDeleted: query.withDeleted === 'true' ? true : query.withDeleted === 'false' ? false : undefined,
         path,
     }
 })

src/paginate.spec.ts

@@ -2627,6 +2627,51 @@ describe('paginate', () => {
         await catRepo.restore({ id: cats[0].id })
     })
 
+    it('should return all items even if deleted, by passing with deleted in query params', async () => {
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+            allowWithDeletedInQuery: true,
+        }
+        const query: PaginateQuery = {
+            path: '',
+            withDeleted: true,
+        }
+        await catRepo.softDelete({ id: cats[0].id })
+        const result = await paginate<CatEntity>(query, catRepo, config)
+        expect(result.meta.totalItems).toBe(cats.length)
+        await catRepo.restore({ id: cats[0].id })
+    })
+
+    it('should return all items even if deleted if config specified withDeleted false', async () => {
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+            allowWithDeletedInQuery: true,
+            withDeleted: false,
+        }
+        const query: PaginateQuery = {
+            path: '',
+            withDeleted: true,
+        }
+        await catRepo.softDelete({ id: cats[0].id })
+        const result = await paginate<CatEntity>(query, catRepo, config)
+        expect(result.meta.totalItems).toBe(cats.length)
+        await catRepo.restore({ id: cats[0].id })
+    })
+
+    it('should not return items with deleted not allowed in config', async () => {
+        const config: PaginateConfig<CatEntity> = {
+            sortableColumns: ['id'],
+        }
+        const query: PaginateQuery = {
+            path: '',
+            withDeleted: true,
+        }
+        await catRepo.softDelete({ id: cats[0].id })
+        const result = await paginate<CatEntity>(query, catRepo, config)
+        expect(result.meta.totalItems).toBe(cats.length - 1)
+        await catRepo.restore({ id: cats[0].id })
+    })
+
     it('should return all relation items even if deleted', async () => {
         const config: PaginateConfig<CatHomeEntity> = {
             sortableColumns: ['id'],

src/paginate.ts

@@ -94,6 +94,7 @@ export interface PaginateConfig<T> {
     filterableColumns?: Partial<MappedColumns<T, (FilterOperator | FilterSuffix)[] | true>>
     loadEagerRelations?: boolean
     withDeleted?: boolean
+    allowWithDeletedInQuery?: boolean
     paginationType?: PaginationType
     relativePath?: boolean
     origin?: string
@@ -653,7 +654,7 @@ export async function paginate<T extends ObjectLiteral>(
         }
     }
 
-    if (config.withDeleted) {
+    if (config.withDeleted || (config.allowWithDeletedInQuery && query.withDeleted)) {
         queryBuilder.withDeleted()
     }
 

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

@@ -180,6 +180,17 @@ ${li('Available Fields', paginateConfig.searchableColumns)}
     })
 }
 
+export function WithDeleted(paginateConfig: PaginateConfig<any>) {
+    if (!paginateConfig.allowWithDeletedInQuery) return
+
+    return ApiQuery({
+        name: 'withDeleted',
+        description: `Retrieve records including soft deleted ones`,
+        required: false,
+        type: 'boolean',
+    })
+}
+
 export const ApiPaginationQuery = (paginationConfig: PaginateConfig<any>) => {
     return applyDecorators(
         ...[
@@ -190,6 +201,7 @@ export const ApiPaginationQuery = (paginationConfig: PaginateConfig<any>) => {
             Search(paginationConfig),
             SearchBy(paginationConfig),
             Select(paginationConfig),
+            WithDeleted(paginationConfig),
         ].filter((v): v is MethodDecorator => v !== undefined)
     )
 }