@flusys/nestjs-shared 6.0.1 → 6.1.0

package/fesm/classes/api-controller.class.spec.js

@@ -0,0 +1,680 @@
+function _define_property(obj, key, value) {
+    if (key in obj) {
+        Object.defineProperty(obj, key, {
+            value: value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
+    } else {
+        obj[key] = value;
+    }
+    return obj;
+}
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+import 'reflect-metadata';
+import { Expose } from 'class-transformer';
+import { HttpStatus } from '@nestjs/common';
+import { createApiController } from './api-controller.class';
+import { Identity } from '../entities';
+import { BaseAppException, NotFoundException } from '../exceptions';
+import { IS_PUBLIC_KEY, PERMISSIONS_KEY } from '../constants';
+import { buildMockUser } from '@test-utils/mocks/logged-user.mock';
+const GUARDS_METADATA = '__guards__';
+const API_EXCLUDE_ENDPOINT_METADATA = 'swagger/apiExcludeEndpoint';
+function guardNames(target, method) {
+    const guards = Reflect.getMetadata(GUARDS_METADATA, target.prototype[method]) ?? [];
+    return guards.map((g)=>g.name);
+}
+let ProductEntity = class ProductEntity extends Identity {
+    constructor(...args){
+        super(...args), _define_property(this, "name", void 0), _define_property(this, "secret", void 0);
+    }
+};
+let CreateProductDto = class CreateProductDto {
+    constructor(){
+        _define_property(this, "name", void 0);
+    }
+};
+let UpdateProductDto = class UpdateProductDto {
+    constructor(){
+        _define_property(this, "id", void 0);
+        _define_property(this, "name", void 0);
+    }
+};
+let ProductResponseDto = class ProductResponseDto {
+    constructor(){
+        _define_property(this, "id", void 0);
+        _define_property(this, "name", void 0);
+    }
+};
+_ts_decorate([
+    Expose(),
+    _ts_metadata("design:type", String)
+], ProductResponseDto.prototype, "id", void 0);
+_ts_decorate([
+    Expose(),
+    _ts_metadata("design:type", String)
+], ProductResponseDto.prototype, "name", void 0);
+function makeController(options = {}) {
+    const ControllerClass = createApiController(CreateProductDto, UpdateProductDto, ProductResponseDto, options);
+    const mockService = {
+        insert: jest.fn(),
+        insertMany: jest.fn(),
+        findById: jest.fn(),
+        findByIds: jest.fn(),
+        update: jest.fn(),
+        updateMany: jest.fn(),
+        bulkUpsert: jest.fn(),
+        getAll: jest.fn(),
+        delete: jest.fn()
+    };
+    const controller = new ControllerClass(mockService);
+    return {
+        controller,
+        mockService,
+        ControllerClass
+    };
+}
+describe('createApiController', ()=>{
+    const mockUser = buildMockUser();
+    describe('isEnabled', ()=>{
+        it('should treat every endpoint as enabled by default', ()=>{
+            const { controller } = makeController();
+            expect(controller.isEnabled('insert')).toBe(true);
+            expect(controller.isEnabled('delete')).toBe(true);
+        });
+        it('should only enable the endpoints explicitly listed', ()=>{
+            const { controller } = makeController({
+                enabledEndpoints: [
+                    'getById'
+                ]
+            });
+            expect(controller.isEnabled('getById')).toBe(true);
+            expect(controller.isEnabled('insert')).toBe(false);
+        });
+    });
+    describe('insert', ()=>{
+        it('should return a success response with the converted dto', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.insert.mockResolvedValue({
+                id: '1',
+                name: 'Widget',
+                secret: 'shh'
+            });
+            const result = await controller.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(result.success).toBe(true);
+            expect(result.messageKey).toBe('item.create.success');
+            expect(result.message).toBe('Item created successfully');
+            expect(result.data).toEqual({
+                id: '1',
+                name: 'Widget'
+            });
+        });
+        it('should strip fields without @Expose() by default (excludeExtraneousValues)', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.insert.mockResolvedValue({
+                id: '1',
+                name: 'Widget',
+                secret: 'shh'
+            });
+            const result = await controller.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(result.data.secret).toBeUndefined();
+        });
+        it('should keep all fields when excludeExtraneousValues is false', async ()=>{
+            const { controller, mockService } = makeController({
+                excludeExtraneousValues: false
+            });
+            mockService.insert.mockResolvedValue({
+                id: '1',
+                name: 'Widget',
+                secret: 'shh'
+            });
+            const result = await controller.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(result.data.secret).toBe('shh');
+        });
+        it('should use the configured entityName in message/messageKey', async ()=>{
+            const { controller, mockService } = makeController({
+                entityName: 'product'
+            });
+            mockService.insert.mockResolvedValue({
+                id: '1',
+                name: 'Widget'
+            });
+            const result = await controller.insert({
+                name: 'Widget'
+            }, mockUser);
+            expect(result.message).toBe('Product created successfully');
+            expect(result.messageKey).toBe('product.create.success');
+        });
+        it('should throw a 403 BaseAppException when insert is disabled', async ()=>{
+            const { controller } = makeController({
+                enabledEndpoints: [
+                    'getById'
+                ]
+            });
+            await expect(controller.insert({
+                name: 'Widget'
+            }, mockUser)).rejects.toMatchObject({
+                message: expect.stringContaining("'insert' is disabled")
+            });
+            try {
+                await controller.insert({
+                    name: 'Widget'
+                }, mockUser);
+                fail('expected throw');
+            } catch (e) {
+                expect(e).toBeInstanceOf(BaseAppException);
+                expect(e.getStatus()).toBe(HttpStatus.FORBIDDEN);
+            }
+        });
+    });
+    describe('insertMany', ()=>{
+        it('should return bulk meta counting successes and failures', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.insertMany.mockResolvedValue([
+                {
+                    id: '1',
+                    name: 'A'
+                }
+            ]);
+            const result = await controller.insertMany([
+                {
+                    name: 'A'
+                },
+                {
+                    name: 'B'
+                }
+            ], mockUser);
+            expect(result.data).toHaveLength(1);
+            expect(result.meta).toEqual({
+                count: 1,
+                total: 2,
+                failed: 1
+            });
+        });
+    });
+    describe('getById', ()=>{
+        it('should return the converted entity', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.findById.mockResolvedValue({
+                id: '1',
+                name: 'Widget'
+            });
+            const result = await controller.getById('1', {
+                select: [
+                    'name'
+                ]
+            }, mockUser);
+            expect(mockService.findById).toHaveBeenCalledWith('1', mockUser, [
+                'name'
+            ]);
+            expect(result.data).toEqual({
+                id: '1',
+                name: 'Widget'
+            });
+        });
+        it('should throw a 403 when getById is disabled', async ()=>{
+            const { controller } = makeController({
+                enabledEndpoints: []
+            });
+            await expect(controller.getById('1', {}, mockUser)).rejects.toBeInstanceOf(BaseAppException);
+        });
+    });
+    describe('getByIds', ()=>{
+        it('should return correct pluralization and meta for multiple items', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.findByIds.mockResolvedValue([
+                {
+                    id: '1',
+                    name: 'A'
+                },
+                {
+                    id: '2',
+                    name: 'B'
+                }
+            ]);
+            const result = await controller.getByIds({
+                ids: [
+                    '1',
+                    '2'
+                ]
+            }, mockUser);
+            expect(result.message).toBe('2 items retrieved successfully');
+            expect(result.meta).toEqual({
+                total: 2,
+                page: 0,
+                pageSize: 2,
+                count: 2,
+                totalPages: 1
+            });
+        });
+        it('should use singular wording for exactly one item', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.findByIds.mockResolvedValue([
+                {
+                    id: '1',
+                    name: 'A'
+                }
+            ]);
+            const result = await controller.getByIds({
+                ids: [
+                    '1'
+                ]
+            }, mockUser);
+            expect(result.message).toBe('1 item retrieved successfully');
+        });
+    });
+    describe('update / updateMany', ()=>{
+        it('update should return the updated entity', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.update.mockResolvedValue({
+                id: '1',
+                name: 'Updated'
+            });
+            const result = await controller.update({
+                id: '1',
+                name: 'Updated'
+            }, mockUser);
+            expect(result.data).toEqual({
+                id: '1',
+                name: 'Updated'
+            });
+            expect(result.messageKey).toBe('item.update.success');
+        });
+        it('updateMany should report per-item failure counts', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.updateMany.mockResolvedValue([
+                {
+                    id: '1',
+                    name: 'A'
+                }
+            ]);
+            const result = await controller.updateMany([
+                {
+                    id: '1',
+                    name: 'A'
+                },
+                {
+                    id: '2',
+                    name: 'B'
+                }
+            ], mockUser);
+            expect(result.meta).toEqual({
+                count: 1,
+                total: 2,
+                failed: 1
+            });
+        });
+    });
+    describe('bulkUpsert', ()=>{
+        it('should split dtos into insert/update sets based on a truthy id', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.bulkUpsert.mockResolvedValue([
+                {
+                    id: '1',
+                    name: 'A'
+                }
+            ]);
+            await controller.bulkUpsert([
+                {
+                    name: 'NoId'
+                },
+                {
+                    id: '',
+                    name: 'EmptyId'
+                },
+                {
+                    id: 'x-1',
+                    name: 'HasId'
+                }
+            ], mockUser);
+            expect(mockService.bulkUpsert).toHaveBeenCalledWith([
+                {
+                    name: 'NoId'
+                },
+                {
+                    id: '',
+                    name: 'EmptyId'
+                }
+            ], [
+                {
+                    id: 'x-1',
+                    name: 'HasId'
+                }
+            ], mockUser);
+        });
+    });
+    describe('getByFilter', ()=>{
+        it('should query getAll with a single-item page and return the first match', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [
+                    {
+                        id: '1',
+                        name: 'A'
+                    }
+                ],
+                total: 1
+            });
+            const result = await controller.getByFilter({
+                name: 'A'
+            }, mockUser);
+            expect(mockService.getAll).toHaveBeenCalledWith('', {
+                filter: {
+                    name: 'A'
+                },
+                pagination: {
+                    currentPage: 0,
+                    pageSize: 1
+                }
+            }, mockUser);
+            expect(result.data).toEqual({
+                id: '1',
+                name: 'A'
+            });
+        });
+        it('should throw NotFoundException when nothing matches the filter', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [],
+                total: 0
+            });
+            await expect(controller.getByFilter({
+                name: 'ghost'
+            }, mockUser)).rejects.toThrow(NotFoundException);
+        });
+    });
+    describe('getAll', ()=>{
+        it('should compute pagination meta with hasMore=true when more pages remain', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [
+                    {
+                        id: '1',
+                        name: 'A'
+                    }
+                ],
+                total: 25
+            });
+            const result = await controller.getAll({
+                pagination: {
+                    currentPage: 0,
+                    pageSize: 10
+                }
+            }, mockUser);
+            expect(result.meta).toEqual({
+                total: 25,
+                page: 0,
+                pageSize: 10,
+                count: 1,
+                hasMore: true,
+                totalPages: 3
+            });
+        });
+        it('should compute hasMore=false on the last page', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [
+                    {
+                        id: '3',
+                        name: 'C'
+                    }
+                ],
+                total: 25
+            });
+            const result = await controller.getAll({
+                pagination: {
+                    currentPage: 2,
+                    pageSize: 10
+                }
+            }, mockUser);
+            expect(result.meta.hasMore).toBe(false);
+            expect(result.meta.totalPages).toBe(3);
+        });
+        it('should default page/pageSize and force totalPages=1 when no pagination is supplied', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [
+                    {
+                        id: '1',
+                        name: 'A'
+                    },
+                    {
+                        id: '2',
+                        name: 'B'
+                    }
+                ],
+                total: 2
+            });
+            const result = await controller.getAll({}, mockUser);
+            expect(result.meta.page).toBe(0);
+            expect(result.meta.pageSize).toBe(2);
+            expect(result.meta.totalPages).toBe(1);
+        });
+        it('should forward the search query param to the service', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [],
+                total: 0
+            });
+            await controller.getAll({}, mockUser, 'widget');
+            expect(mockService.getAll).toHaveBeenCalledWith('widget', {}, mockUser);
+        });
+        it('should default search to an empty string when the q param is absent', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.getAll.mockResolvedValue({
+                data: [],
+                total: 0
+            });
+            await controller.getAll({}, mockUser);
+            expect(mockService.getAll).toHaveBeenCalledWith('', {}, mockUser);
+        });
+    });
+    describe('delete', ()=>{
+        it('should report singular deletion for one id', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.delete.mockResolvedValue(null);
+            const result = await controller.delete({
+                id: '1',
+                type: 'delete'
+            }, mockUser);
+            expect(result.message).toBe('1 item deleted successfully');
+            expect(result.messageKey).toBe('item.delete.success');
+            expect(result.messageVariables).toEqual({
+                count: 1
+            });
+        });
+        it('should report plural deletion for multiple ids', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.delete.mockResolvedValue(null);
+            const result = await controller.delete({
+                id: [
+                    '1',
+                    '2',
+                    '3'
+                ],
+                type: 'permanent'
+            }, mockUser);
+            expect(result.message).toBe('3 items deleted successfully');
+        });
+        it('should label the action "restore" (not delete) for type=restore', async ()=>{
+            const { controller, mockService } = makeController();
+            mockService.delete.mockResolvedValue(null);
+            const result = await controller.delete({
+                id: [
+                    '1',
+                    '2'
+                ],
+                type: 'restore'
+            }, mockUser);
+            expect(result.message).toBe('2 items restored successfully');
+            expect(result.messageKey).toBe('item.restore.success');
+        });
+        it('should throw a 403 when delete is disabled', async ()=>{
+            const { controller } = makeController({
+                enabledEndpoints: [
+                    'getById'
+                ]
+            });
+            await expect(controller.delete({
+                id: '1',
+                type: 'delete'
+            }, mockUser)).rejects.toBeInstanceOf(BaseAppException);
+        });
+    });
+    describe('security configuration', ()=>{
+        it('should default every endpoint to public when no security option is given at all', ()=>{
+            const { ControllerClass } = makeController();
+            expect(Reflect.getMetadata(IS_PUBLIC_KEY, ControllerClass.prototype.insert)).toBe(true);
+            expect(Reflect.getMetadata(IS_PUBLIC_KEY, ControllerClass.prototype.delete)).toBe(true);
+            expect(guardNames(ControllerClass, 'insert')).toEqual([]);
+        });
+        it('should apply JwtAuthGuard + ApiBearerAuth to every endpoint for global "jwt" security', ()=>{
+            const { ControllerClass } = makeController({
+                security: 'jwt'
+            });
+            expect(guardNames(ControllerClass, 'insert')).toEqual([
+                'JwtAuthGuard'
+            ]);
+            expect(guardNames(ControllerClass, 'delete')).toEqual([
+                'JwtAuthGuard'
+            ]);
+            expect(Reflect.getMetadata(IS_PUBLIC_KEY, ControllerClass.prototype.insert)).toBeUndefined();
+        });
+        it('should apply JwtAuthGuard + PermissionGuard and AND-logic permissions by default', ()=>{
+            const { ControllerClass } = makeController({
+                security: {
+                    level: 'permission',
+                    permissions: [
+                        'product.create'
+                    ]
+                }
+            });
+            expect(guardNames(ControllerClass, 'insert')).toEqual([
+                'JwtAuthGuard',
+                'PermissionGuard'
+            ]);
+            expect(Reflect.getMetadata(PERMISSIONS_KEY, ControllerClass.prototype.insert)).toEqual({
+                permissions: [
+                    'product.create'
+                ],
+                operator: 'AND'
+            });
+        });
+        it('should use OR-logic permissions when operator is "OR"', ()=>{
+            const { ControllerClass } = makeController({
+                security: {
+                    level: 'permission',
+                    permissions: [
+                        'a',
+                        'b'
+                    ],
+                    operator: 'OR'
+                }
+            });
+            expect(Reflect.getMetadata(PERMISSIONS_KEY, ControllerClass.prototype.insert)).toEqual({
+                permissions: [
+                    'a',
+                    'b'
+                ],
+                operator: 'OR'
+            });
+        });
+        it('should prefer complex `logic` over `permissions`/`operator` when both are given', ()=>{
+            const logic = {
+                type: 'action',
+                actionId: 'product.create'
+            };
+            const { ControllerClass } = makeController({
+                security: {
+                    level: 'permission',
+                    permissions: [
+                        'ignored'
+                    ],
+                    logic: logic
+                }
+            });
+            expect(Reflect.getMetadata(PERMISSIONS_KEY, ControllerClass.prototype.insert)).toEqual(logic);
+        });
+        it('should apply no permission decorator when permission level has neither logic nor permissions', ()=>{
+            const { ControllerClass } = makeController({
+                security: {
+                    level: 'permission'
+                }
+            });
+            expect(guardNames(ControllerClass, 'insert')).toEqual([
+                'JwtAuthGuard',
+                'PermissionGuard'
+            ]);
+            expect(Reflect.getMetadata(PERMISSIONS_KEY, ControllerClass.prototype.insert)).toBeUndefined();
+        });
+        it('should apply per-endpoint security for configured endpoints', ()=>{
+            const { ControllerClass } = makeController({
+                security: {
+                    insert: 'public',
+                    delete: {
+                        level: 'permission',
+                        permissions: [
+                            'x.delete'
+                        ]
+                    }
+                }
+            });
+            expect(Reflect.getMetadata(IS_PUBLIC_KEY, ControllerClass.prototype.insert)).toBe(true);
+            expect(guardNames(ControllerClass, 'delete')).toEqual([
+                'JwtAuthGuard',
+                'PermissionGuard'
+            ]);
+        });
+        // KNOWN GAP: the `defaultSecurity = { level: 'jwt' }` fallback (api-controller.class.ts
+        // lines 230-232) is dead code. It is only ever assigned to endpoints when `isGlobalSecurity`
+        // is true, in which case every endpoint already shares the same global config anyway. In
+        // per-endpoint mode (or when no `security` option is passed at all), each endpoint's security
+        // is resolved independently via `normalizeSecurity(securityConfig?.<endpoint>)`, and
+        // `normalizeSecurity(undefined)` returns `{ level: 'public' }` -- not the intended 'jwt'
+        // fallback described in the source comment. This means any endpoint omitted from a
+        // per-endpoint `security` config (or the config itself) is silently PUBLIC. Pin the current
+        // (buggy) behavior here so a fix is visible as an intentional test change, not a silent one.
+        it('BUG: leaves endpoints unconfigured in per-endpoint mode PUBLIC instead of defaulting to jwt', ()=>{
+            const { ControllerClass } = makeController({
+                security: {
+                    insert: 'public',
+                    delete: {
+                        level: 'permission',
+                        permissions: [
+                            'x.delete'
+                        ]
+                    }
+                }
+            });
+            expect(Reflect.getMetadata(IS_PUBLIC_KEY, ControllerClass.prototype.getAll)).toBe(true);
+            expect(guardNames(ControllerClass, 'getAll')).toEqual([]);
+        });
+        it('should mark disabled endpoints with ApiExcludeEndpoint', ()=>{
+            const { ControllerClass } = makeController({
+                enabledEndpoints: [
+                    'getById'
+                ]
+            });
+            expect(Reflect.getMetadata(API_EXCLUDE_ENDPOINT_METADATA, ControllerClass.prototype.insert)).toEqual({
+                disable: true
+            });
+            expect(Reflect.getMetadata(API_EXCLUDE_ENDPOINT_METADATA, ControllerClass.prototype.getById)).toBeUndefined();
+        });
+    });
+});