@flusys/nestjs-core 7.0.2 → 8.0.0-beta.1

package/fesm/docs/docs.config.spec.js

@@ -1,919 +0,0 @@
-import { DocumentBuilder } from '@nestjs/swagger';
-const mockCreateDocument = jest.fn();
-const mockSetup = jest.fn();
-jest.mock('@nestjs/swagger', ()=>{
-    const actual = jest.requireActual('@nestjs/swagger');
-    return {
-        ...actual,
-        SwaggerModule: {
-            createDocument: (...args)=>mockCreateDocument(...args),
-            setup: (...args)=>mockSetup(...args)
-        }
-    };
-});
-import { setupModuleSwaggerDocs, setupSwaggerDocs } from './docs.config';
-describe('docs.config', ()=>{
-    const mockApp = {};
-    function baseDocument(overrides = {}) {
-        return {
-            openapi: '3.0.0',
-            info: {
-                title: 't',
-                version: '1.0'
-            },
-            paths: {},
-            ...overrides
-        };
-    }
-    beforeEach(()=>{
-        jest.clearAllMocks();
-    });
-    it('should build a document with the given title/description/version and register it', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 'Auth API',
-                description: 'desc',
-                version: '2.0',
-                path: 'api/docs/auth'
-            }
-        ]);
-        expect(mockCreateDocument).toHaveBeenCalledWith(mockApp, expect.any(Object), {});
-        expect(mockSetup).toHaveBeenCalledWith('api/docs/auth', mockApp, expect.any(Object));
-    });
-    it('should default the version to 1.0 when not provided', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        const buildSpy = jest.spyOn(DocumentBuilder.prototype, 'setVersion');
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p'
-            }
-        ]);
-        expect(buildSpy).toHaveBeenCalledWith('1.0');
-        buildSpy.mockRestore();
-    });
-    it('should add bearer auth when bearerAuth is true', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        const bearerSpy = jest.spyOn(DocumentBuilder.prototype, 'addBearerAuth');
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p',
-                bearerAuth: true
-            }
-        ]);
-        expect(bearerSpy).toHaveBeenCalled();
-        bearerSpy.mockRestore();
-    });
-    it('should not add bearer auth when bearerAuth is falsy', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        const bearerSpy = jest.spyOn(DocumentBuilder.prototype, 'addBearerAuth');
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p'
-            }
-        ]);
-        expect(bearerSpy).not.toHaveBeenCalled();
-        bearerSpy.mockRestore();
-    });
-    it('should add global headers with defaults for optional fields', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        const headerSpy = jest.spyOn(DocumentBuilder.prototype, 'addGlobalParameters');
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p',
-                globalHeaders: [
-                    {
-                        name: 'X-Tenant-Id',
-                        description: 'tenant'
-                    }
-                ]
-            }
-        ]);
-        expect(headerSpy).toHaveBeenCalledWith({
-            name: 'X-Tenant-Id',
-            in: 'header',
-            description: 'tenant',
-            required: false,
-            schema: {
-                type: 'string',
-                example: ''
-            }
-        });
-        headerSpy.mockRestore();
-    });
-    it('should pass required/example through for global headers when provided', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        const headerSpy = jest.spyOn(DocumentBuilder.prototype, 'addGlobalParameters');
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p',
-                globalHeaders: [
-                    {
-                        name: 'X-Tenant-Id',
-                        description: 'tenant',
-                        required: true,
-                        example: 'tenant-1'
-                    }
-                ]
-            }
-        ]);
-        expect(headerSpy).toHaveBeenCalledWith(expect.objectContaining({
-            required: true,
-            schema: {
-                type: 'string',
-                example: 'tenant-1'
-            }
-        }));
-        headerSpy.mockRestore();
-    });
-    it('should scope the document to specific modules when provided', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        let FakeModule = class FakeModule {
-        };
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 't',
-                description: 'd',
-                path: 'p',
-                modules: [
-                    FakeModule
-                ]
-            }
-        ]);
-        expect(mockCreateDocument).toHaveBeenCalledWith(mockApp, expect.any(Object), {
-            include: [
-                FakeModule
-            ]
-        });
-    });
-    it('should set up multiple module configs independently', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        setupModuleSwaggerDocs(mockApp, [
-            {
-                title: 'A',
-                description: 'a',
-                path: 'a'
-            },
-            {
-                title: 'B',
-                description: 'b',
-                path: 'b'
-            }
-        ]);
-        expect(mockCreateDocument).toHaveBeenCalledTimes(2);
-        expect(mockSetup).toHaveBeenCalledTimes(2);
-        expect(mockSetup).toHaveBeenNthCalledWith(1, 'a', mockApp, expect.any(Object));
-        expect(mockSetup).toHaveBeenNthCalledWith(2, 'b', mockApp, expect.any(Object));
-    });
-    it('setupSwaggerDocs should forward all configs as varargs to setupModuleSwaggerDocs', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument());
-        setupSwaggerDocs(mockApp, {
-            title: 'A',
-            description: 'a',
-            path: 'a'
-        }, {
-            title: 'B',
-            description: 'b',
-            path: 'b'
-        });
-        expect(mockSetup).toHaveBeenCalledTimes(2);
-    });
-    describe('excludeSchemaProperties', ()=>{
-        it('should remove excluded properties and drop them from the required array', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                components: {
-                    schemas: {
-                        User: {
-                            properties: {
-                                id: {
-                                    type: 'string'
-                                },
-                                password: {
-                                    type: 'string'
-                                }
-                            },
-                            required: [
-                                'id',
-                                'password'
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeSchemaProperties: [
-                        {
-                            schemaName: 'User',
-                            properties: [
-                                'password'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            const userSchema = document.components.schemas.User;
-            expect(userSchema.properties).toEqual({
-                id: {
-                    type: 'string'
-                }
-            });
-            expect(userSchema.required).toEqual([
-                'id'
-            ]);
-        });
-        // BUG: when filteredRequired becomes empty, the code spreads `{}` (falsy branch) instead of
-        // `{ required: undefined }`, so the stale `required` array from `...schema` survives untouched —
-        // the excluded property stays listed as required even though it was removed from `properties`.
-        it('should currently leave a stale required array when every required prop is excluded (known bug)', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                components: {
-                    schemas: {
-                        User: {
-                            properties: {
-                                password: {
-                                    type: 'string'
-                                }
-                            },
-                            required: [
-                                'password'
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeSchemaProperties: [
-                        {
-                            schemaName: 'User',
-                            properties: [
-                                'password'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            const userSchema = document.components.schemas.User;
-            expect(userSchema.properties).toEqual({});
-            expect(userSchema.required).toEqual([
-                'password'
-            ]);
-        });
-        it('should be a no-op when the schema does not exist', ()=>{
-            const doc = baseDocument({
-                components: {
-                    schemas: {}
-                }
-            });
-            mockCreateDocument.mockReturnValue(doc);
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeSchemaProperties: [
-                        {
-                            schemaName: 'Missing',
-                            properties: [
-                                'x'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.components.schemas).toEqual({});
-        });
-        it('should be a no-op when there are no components/schemas on the document', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument());
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeSchemaProperties: [
-                        {
-                            schemaName: 'User',
-                            properties: [
-                                'x'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.components).toBeUndefined();
-        });
-    });
-    describe('excludeQueryParameters', ()=>{
-        it('should strip matching query parameters from operations matching the path pattern', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/users': {
-                        get: {
-                            parameters: [
-                                {
-                                    name: 'internalDebug',
-                                    in: 'query'
-                                },
-                                {
-                                    name: 'page',
-                                    in: 'query'
-                                }
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeQueryParameters: [
-                        {
-                            pathPattern: '/users',
-                            parameters: [
-                                'internalDebug'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            const params = document.paths['/users'].get.parameters;
-            expect(params).toEqual([
-                {
-                    name: 'page',
-                    in: 'query'
-                }
-            ]);
-        });
-        it('should only strip parameters for the specified method when method is set', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/users': {
-                        get: {
-                            parameters: [
-                                {
-                                    name: 'debug',
-                                    in: 'query'
-                                }
-                            ]
-                        },
-                        post: {
-                            parameters: [
-                                {
-                                    name: 'debug',
-                                    in: 'query'
-                                }
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeQueryParameters: [
-                        {
-                            pathPattern: '/users',
-                            method: 'get',
-                            parameters: [
-                                'debug'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths['/users'].get.parameters).toEqual([]);
-            expect(document.paths['/users'].post.parameters).toEqual([
-                {
-                    name: 'debug',
-                    in: 'query'
-                }
-            ]);
-        });
-        it('should not touch parameters that are not in-query', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/users/{id}': {
-                        get: {
-                            parameters: [
-                                {
-                                    name: 'id',
-                                    in: 'path'
-                                }
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeQueryParameters: [
-                        {
-                            pathPattern: '/users/{id}',
-                            parameters: [
-                                'id'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths['/users/{id}'].get.parameters).toEqual([
-                {
-                    name: 'id',
-                    in: 'path'
-                }
-            ]);
-        });
-        it('should leave non-matching paths untouched', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/orders': {
-                        get: {
-                            parameters: [
-                                {
-                                    name: 'debug',
-                                    in: 'query'
-                                }
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeQueryParameters: [
-                        {
-                            pathPattern: '/users',
-                            parameters: [
-                                'debug'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths['/orders'].get.parameters).toEqual([
-                {
-                    name: 'debug',
-                    in: 'query'
-                }
-            ]);
-        });
-    });
-    describe('excludeExamples', ()=>{
-        it('should remove named examples from response media types without mutating the source document', ()=>{
-            const originalDoc = baseDocument({
-                paths: {
-                    '/users': {
-                        get: {
-                            responses: {
-                                '200': {
-                                    content: {
-                                        'application/json': {
-                                            examples: {
-                                                admin: {
-                                                    value: {}
-                                                },
-                                                guest: {
-                                                    value: {}
-                                                }
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    }
-                }
-            });
-            mockCreateDocument.mockReturnValue(originalDoc);
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeExamples: [
-                        {
-                            pathPattern: '/users',
-                            examples: [
-                                'admin'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            const examples = document.paths['/users'].get.responses['200'].content['application/json'].examples;
-            expect(examples).toEqual({
-                guest: {
-                    value: {}
-                }
-            });
-            // original untouched
-            const originalExamples = originalDoc.paths['/users'].get.responses['200'].content['application/json'].examples;
-            expect(originalExamples).toEqual({
-                admin: {
-                    value: {}
-                },
-                guest: {
-                    value: {}
-                }
-            });
-        });
-        it('should be a no-op when responses have no examples', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/users': {
-                        get: {
-                            responses: {
-                                '200': {
-                                    content: {}
-                                }
-                            }
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeExamples: [
-                        {
-                            pathPattern: '/users',
-                            examples: [
-                                'admin'
-                            ]
-                        }
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths['/users'].get.responses['200'].content).toEqual({});
-        });
-    });
-    describe('excludePaths', ()=>{
-        it('should remove paths matching a wildcard pattern', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/internal/health': {
-                        get: {}
-                    },
-                    '/users': {
-                        get: {}
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludePaths: [
-                        '/internal/*'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(Object.keys(document.paths)).toEqual([
-                '/users'
-            ]);
-        });
-        // BUG: pathMatchesPattern replaces single `*` before `**`, so by the time the `**` replace
-        // runs there are no literal `**` left to match (they've already become `[^/]+[^/]+`) — the
-        // "match across slashes" wildcard is effectively dead code and behaves like two single-segment
-        // wildcards instead, so a pattern like '/internal/**' will NOT exclude multi-segment paths.
-        it('should currently fail to match multi-segment paths with ** (known bug)', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/internal/a/b/c': {
-                        get: {}
-                    },
-                    '/internal/ab': {
-                        get: {}
-                    },
-                    '/users': {
-                        get: {}
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludePaths: [
-                        '/internal/**'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            // '**' can't cross the extra path segment boundaries, so the nested path survives.
-            expect(Object.keys(document.paths).sort()).toEqual([
-                '/internal/a/b/c',
-                '/users'
-            ].sort());
-        });
-        it('should leave paths untouched when excludePaths is empty', ()=>{
-            const doc = baseDocument({
-                paths: {
-                    '/users': {
-                        get: {}
-                    }
-                }
-            });
-            mockCreateDocument.mockReturnValue(doc);
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludePaths: []
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths).toEqual(doc.paths);
-        });
-    });
-    describe('excludeTags', ()=>{
-        it('should drop operations that carry an excluded tag, case-insensitively', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/internal': {
-                        get: {
-                            tags: [
-                                'Internal'
-                            ]
-                        }
-                    },
-                    '/users': {
-                        get: {
-                            tags: [
-                                'Users'
-                            ]
-                        }
-                    }
-                },
-                tags: [
-                    {
-                        name: 'Internal'
-                    },
-                    {
-                        name: 'Users'
-                    }
-                ]
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeTags: [
-                        'internal'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(Object.keys(document.paths)).toEqual([
-                '/users'
-            ]);
-            expect(document.tags).toEqual([
-                {
-                    name: 'Users'
-                }
-            ]);
-        });
-        it('should drop the whole path entry when every operation is excluded', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/internal': {
-                        get: {
-                            tags: [
-                                'Internal'
-                            ]
-                        },
-                        post: {
-                            tags: [
-                                'Internal'
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeTags: [
-                        'Internal'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths).toEqual({});
-        });
-        it('should keep a path when only some of its operations are excluded', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/mixed': {
-                        get: {
-                            tags: [
-                                'Public'
-                            ]
-                        },
-                        post: {
-                            tags: [
-                                'Internal'
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeTags: [
-                        'Internal'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(Object.keys(document.paths['/mixed'])).toEqual([
-                'get'
-            ]);
-        });
-        it('should preserve non-operation keys like shared parameters on the path item', ()=>{
-            mockCreateDocument.mockReturnValue(baseDocument({
-                paths: {
-                    '/mixed': {
-                        parameters: [
-                            {
-                                name: 'shared',
-                                in: 'query'
-                            }
-                        ],
-                        get: {
-                            tags: [
-                                'Public'
-                            ]
-                        }
-                    }
-                }
-            }));
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeTags: [
-                        'Nonexistent'
-                    ]
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document.paths['/mixed'].parameters).toEqual([
-                {
-                    name: 'shared',
-                    in: 'query'
-                }
-            ]);
-        });
-        it('should be a no-op when excludeTags is empty', ()=>{
-            const doc = baseDocument({
-                paths: {
-                    '/users': {
-                        get: {
-                            tags: [
-                                'Users'
-                            ]
-                        }
-                    }
-                },
-                tags: [
-                    {
-                        name: 'Users'
-                    }
-                ]
-            });
-            mockCreateDocument.mockReturnValue(doc);
-            setupModuleSwaggerDocs(mockApp, [
-                {
-                    title: 't',
-                    description: 'd',
-                    path: 'p',
-                    excludeTags: []
-                }
-            ]);
-            const document = mockSetup.mock.calls[0][2];
-            expect(document).toBe(doc);
-        });
-    });
-    it('should apply exclusion filters in combination', ()=>{
-        mockCreateDocument.mockReturnValue(baseDocument({
-            paths: {
-                '/internal/debug': {
-                    get: {
-                        tags: [
-                            'Internal'
-                        ]
-                    }
-                },
-                '/users': {
-                    get: {
-                        tags: [
-                            'Users'
-                        ],
-                        parameters: [
-                            {
-                                name: 'debug',
-                                in: 'query'
-                            }
-                        ]
-                    }
-                }
-            },
-            components: {
-                schemas: {
-                    User: {
-                        properties: {
-                            password: {}
-                        },
-                        required: [
-                            'password'
-                        ]
-                    }
-                }
-            }
-        }));
-        const config = {
-            title: 't',
-            description: 'd',
-            path: 'p',
-            excludePaths: [
-                '/internal/**'
-            ],
-            excludeSchemaProperties: [
-                {
-                    schemaName: 'User',
-                    properties: [
-                        'password'
-                    ]
-                }
-            ],
-            excludeQueryParameters: [
-                {
-                    pathPattern: '/users',
-                    parameters: [
-                        'debug'
-                    ]
-                }
-            ]
-        };
-        setupModuleSwaggerDocs(mockApp, [
-            config
-        ]);
-        const document = mockSetup.mock.calls[0][2];
-        expect(Object.keys(document.paths)).toEqual([
-            '/users'
-        ]);
-        expect(document.paths['/users'].get.parameters).toEqual([]);
-        expect(document.components.schemas.User.properties).toEqual({});
-    });
-});