@nest-yalc-2/app 1.3.3

package/README.md

@@ -0,0 +1,49 @@
+# @nest-yalc-2/app
+
+Application bootstrap helpers and base NestJS module utilities for YALC apps.
+
+Use this package when an application wants shared configuration loading,
+application-scoped logger and event providers, CLS wiring, lifecycle handling,
+Swagger setup, and consistent bootstrap behavior.
+
+## Installation
+
+```bash
+npm install @nest-yalc-2/app
+```
+
+Install the NestJS peer packages used by your application, such as
+`@nestjs/common`, `@nestjs/core`, `@nestjs/config`, and the selected HTTP
+platform package.
+
+## Import Surface
+
+The package ships helpers through subpath exports. Import the specific helper
+module you need, for example `@nest-yalc-2/app/app-bootstrap.helper.js`.
+
+- `AppBootstrap` and `StandaloneAppBootstrap` for HTTP and standalone Nest app
+  startup.
+- `YalcBaseAppModule` and `YalcDefaultAppModule` for reusable base module
+  composition.
+- `AppDependencyFactory` for assembling common app imports and providers.
+- `AppConfigService`, `createAppConfigProvider`, and token helpers for
+  application-scoped configuration.
+- `YalcClsModule`, `YalcAlsService`, and `YalcGlobalClsService` for context
+  storage.
+- `UnwrapResultInterceptor` for unwrapping `neverthrow` Result values.
+
+## Example
+
+```ts
+import { AppBootstrap } from '@nest-yalc-2/app/app-bootstrap.helper.js';
+import { AppModule } from './app.module.js';
+
+await new AppBootstrap(AppModule).bootstrap();
+```
+
+## Documentation
+
+- Integration guide:
+  https://github.com/NestDevLab/nestjs-yalc/blob/dev/docs/how-to-integrate-nestjs-yalc.md
+- Backend blueprint:
+  https://github.com/NestDevLab/nestjs-yalc/blob/dev/docs/backend-blueprint.md

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@nest-yalc-2/app",
+  "version": "1.3.3",
+  "type": "module",
+  "description": "",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./*.js": "./src/*.js",
+    "./*": "./src/*"
+  },
+  "author": "",
+  "license": "MIT",
+  "types": "./src/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "tslib": "^2.6.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nek97/nestjs-yalc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nek97/nestjs-yalc/issues"
+  },
+  "homepage": "https://github.com/Nek97/nestjs-yalc#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/__tests__/app-bootstrap-base.helper.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { BaseAppBootstrap } from '../app-bootstrap-base.helper.js';
+
+class DummyModule {}
+
+class TestBootstrap extends BaseAppBootstrap<any> {
+  constructor() {
+    super('test-app', DummyModule as any, {
+      globalsOptions: { skipMultiServerCheck: true },
+    });
+  }
+}
+
+describe('BaseAppBootstrap', () => {
+  it('should monkey patch app init/close and update flags', async () => {
+    const bootstrap = new TestBootstrap();
+
+    const closeFn = jest.fn().mockResolvedValue(undefined);
+    const initFn = jest.fn().mockResolvedValue(undefined);
+
+    const fakeApp: any = {
+      close: closeFn,
+      init: initFn,
+      get: jest.fn(),
+      useLogger: jest.fn(),
+    };
+
+    bootstrap.setApp(fakeApp);
+
+    expect(bootstrap.isAppClosed()).toBe(false);
+    await fakeApp.init();
+    expect(bootstrap.isAppClosed()).toBe(false);
+
+    await bootstrap.closeApp();
+    expect(closeFn).toHaveBeenCalled();
+    expect(bootstrap.isAppClosed()).toBe(true);
+  });
+});

package/src/__tests__/app-bootstrap-standalone.helper.spec.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it, jest, beforeEach } from '@jest/globals';
+import { StandaloneAppBootstrap } from '../app-bootstrap-standalone.helper.js';
+import { NestFactory } from '@nestjs/core';
+
+describe('StandaloneAppBootstrap', () => {
+  const logger = { log: jest.fn(), debug: jest.fn() };
+  const initMock = jest.fn().mockResolvedValue(undefined);
+  const fakeApp = {
+    init: initMock,
+    close: jest.fn().mockResolvedValue(undefined),
+    get: jest.fn().mockReturnValue(logger),
+    useLogger: jest.fn(),
+  };
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest
+      .spyOn(NestFactory, 'createApplicationContext')
+      .mockResolvedValue(fakeApp as any);
+  });
+
+  it('should create application context and initialize', async () => {
+    const bootstrap = new StandaloneAppBootstrap(
+      'standalone',
+      class Dummy {},
+      { skipMultiServerCheck: true } as any,
+    );
+
+    await bootstrap.initApp();
+
+    expect(NestFactory.createApplicationContext).toHaveBeenCalled();
+    expect(initMock).toHaveBeenCalled();
+    expect(bootstrap.getApp()).toBe(fakeApp);
+  });
+});

package/src/__tests__/app-bootstrap.helper.spec.ts

@@ -0,0 +1,98 @@
+import { describe, expect, it, jest, beforeEach } from '@jest/globals';
+import '@nest-yalc-2/jest/common-mocks.helper.js';
+
+import { AppBootstrap } from '../app-bootstrap.helper.js';
+import { SYSTEM_LOGGER_SERVICE } from '../def.const.js';
+import { UnwrapResultInterceptor } from '../unwrap-result.interceptor.js';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
+
+jest.mock('class-validator', () => ({
+  useContainer: jest.fn(),
+}));
+
+jest.mock('@fastify/cookie', () => jest.fn());
+
+describe('AppBootstrap.applyBootstrapGlobals', () => {
+  const logger = { log: jest.fn(), debug: jest.fn() };
+  const customFilter = { handle: jest.fn() };
+  const createDocumentMock = jest.fn().mockReturnValue({ doc: true });
+  const setupSwaggerMock = jest.fn();
+  const setTitleMock = jest.fn().mockReturnThis();
+  const setDescriptionMock = jest.fn().mockReturnThis();
+  const buildMock = jest.fn().mockReturnValue({ swagger: true });
+
+  const fakeApp = {
+    useGlobalPipes: jest.fn(),
+    setGlobalPrefix: jest.fn(),
+    register: jest.fn(),
+    useGlobalInterceptors: jest.fn(),
+    useGlobalFilters: jest.fn(),
+    useLogger: jest.fn(),
+    get: jest.fn().mockImplementation((token) =>
+      token === SYSTEM_LOGGER_SERVICE ? logger : undefined,
+    ),
+    select: jest.fn().mockReturnValue({}),
+  };
+
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    jest.clearAllMocks();
+    jest.spyOn(SwaggerModule, 'createDocument').mockImplementation((...args: any[]) =>
+      createDocumentMock(...args),
+    );
+    jest.spyOn(SwaggerModule, 'setup').mockImplementation((...args: any[]) =>
+      setupSwaggerMock(...args),
+    );
+    jest
+      .spyOn(DocumentBuilder.prototype, 'setTitle')
+      .mockImplementation(function (...args: any[]) {
+        setTitleMock(...args);
+        return this;
+      });
+    jest
+      .spyOn(DocumentBuilder.prototype, 'setDescription')
+      .mockImplementation(function (...args: any[]) {
+        setDescriptionMock(...args);
+        return this;
+      });
+    jest.spyOn(DocumentBuilder.prototype, 'build').mockImplementation((...args: any[]) =>
+      buildMock(...args),
+    );
+  });
+
+  it('should set up pipes, filters, interceptors and swagger', async () => {
+    const bootstrap = new AppBootstrap(
+      'app',
+      class Dummy {},
+      { skipMultiServerCheck: true } as any,
+    );
+
+    bootstrap['app'] = fakeApp as any;
+    bootstrap['loggerService'] = logger as any;
+    bootstrap.getConf = jest.fn().mockReturnValue({
+      apiPrefix: 'api',
+      host: 'localhost',
+      port: 3000,
+    }) as any;
+    bootstrap.getModule = jest.fn().mockReturnValue({}) as any;
+
+    await bootstrap.applyBootstrapGlobals({
+      enableSwagger: true,
+      apiPrefix: 'api',
+      filters: [customFilter as any],
+      validationPipeOptions: { transformOptions: { enableImplicitConversion: true } },
+    });
+
+    expect(fakeApp.useGlobalPipes).toHaveBeenCalled();
+    expect(fakeApp.setGlobalPrefix).toHaveBeenCalledWith('api');
+    expect(fakeApp.register).toHaveBeenCalled();
+    expect(fakeApp.useGlobalInterceptors).toHaveBeenCalledWith(
+      expect.any(UnwrapResultInterceptor),
+    );
+    expect(fakeApp.useGlobalFilters).toHaveBeenCalled();
+    expect(createDocumentMock).toHaveBeenCalled();
+    expect(setTitleMock).toHaveBeenCalled();
+    expect(setDescriptionMock).toHaveBeenCalled();
+    expect(setupSwaggerMock).toHaveBeenCalled();
+  });
+});

package/src/__tests__/app-config.service.spec.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { ConfigService } from '@nestjs/config';
+import {
+  AppConfigService,
+  createAppConfigProvider,
+  getAppConfigToken,
+  getAppEventToken,
+  getAppLoggerToken,
+} from '../app-config.service.js';
+
+describe('AppConfigService', () => {
+  it('should expose config values', () => {
+    const config = { appName: 'demo' };
+    const configService = {
+      get: jest.fn().mockReturnValue(config),
+    } as unknown as ConfigService;
+
+    const service = new AppConfigService(configService, 'demoAlias');
+
+    expect(service.values).toBe(config);
+    expect(service.get()).toBe(config);
+    expect(configService.get).toHaveBeenCalledWith('demoAlias');
+  });
+
+  it('should throw when config is missing', () => {
+    const configService = {
+      get: jest.fn().mockReturnValue(undefined),
+    } as unknown as ConfigService;
+
+    expect(() => new AppConfigService(configService, 'missing')).toThrow(
+      "AppConfigService: No config found for app alias 'missing'",
+    );
+  });
+});
+
+describe('AppConfigService tokens', () => {
+  it('should generate token names', () => {
+    expect(getAppConfigToken('alias')).toBe('aliasConfig');
+    expect(getAppEventToken('alias')).toBe('aliasEvent');
+    expect(getAppLoggerToken('alias')).toBe('aliasLogger');
+  });
+
+  it('should build a provider that resolves AppConfigService', () => {
+    const provider = createAppConfigProvider('alias');
+    const config = { foo: 'bar' };
+    const configService = { get: jest.fn().mockReturnValue(config) };
+
+    const instance = (provider as any).useFactory(
+      configService as ConfigService,
+    ) as AppConfigService;
+
+    expect(provider.inject).toEqual([ConfigService]);
+    expect(instance.values).toBe(config);
+  });
+});

package/src/__tests__/app-context.service.spec.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  GraphQLObjectType,
+  GraphQLSchema,
+  GraphQLString,
+} from 'graphql';
+import { AppContextService } from '../app-context.service.js';
+
+describe('AppContextService', () => {
+  it('should store initialized apps and schema', () => {
+    const service = new AppContextService();
+    service.initializedApps.add('app1');
+
+    const schema = new GraphQLSchema({
+      query: new GraphQLObjectType({
+        name: 'Query',
+        fields: {
+          hello: { type: GraphQLString },
+        },
+      }),
+    });
+
+    service.setSchema(schema);
+
+    expect(service.initializedApps.has('app1')).toBe(true);
+    expect(service.schema).toBe(schema);
+  });
+});

package/src/__tests__/app.events.spec.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from '@jest/globals';
+import { AppEvents } from '../app.events.js';
+
+describe('AppEvents enum', () => {
+  it('should expose the expected event names', () => {
+    expect(AppEvents.BEFORE_ALL_ROUTES).toBe('app.before_all_routes');
+    expect(AppEvents.AFTER_ALL_ROUTES).toBe('app.after_all_routes');
+    expect(AppEvents.BEFORE_GQL_CONTEXT_MIDDLEWARE).toBe(
+      'app.before_gql_context_middleware',
+    );
+  });
+});

package/src/__tests__/app.helper.spec.ts

@@ -0,0 +1,204 @@
+import { jest } from '@jest/globals';
+import '@nest-yalc-2/jest/common-mocks.helper.js';
+import { expect, describe, it, beforeEach, afterEach } from '@jest/globals';
+import { createMock, DeepMocked } from '@golevelup/ts-jest';
+import { DynamicModule, INestApplicationContext, Module } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { executeStandaloneFunction } from '../app.helper.js';
+import {
+  getBootstrappedApps,
+  getMainBootstrappedApp,
+} from '../app-bootstrap-base.helper.js';
+import { AppBootstrap } from '../app-bootstrap.helper.js';
+import { yalcBaseAppModuleMetadataFactory } from '../base-app-module.helper.js';
+
+@Module(
+  yalcBaseAppModuleMetadataFactory(TestModule1, 'test1', {
+    configFactory: () => ({}),
+    logger: true,
+  }),
+)
+class TestModule1 {}
+
+@Module(
+  yalcBaseAppModuleMetadataFactory(TestModule2, 'test2', {
+    configFactory: () => ({}),
+    logger: true,
+  }),
+)
+class TestModule2 {}
+
+@Module(
+  yalcBaseAppModuleMetadataFactory(BrokenModule, 'brokenModule', {
+    configFactory: () => ({}),
+    logger: true,
+    providers: [
+      {
+        provide: 'brokenService',
+        useFactory: () => {
+          throw new Error('Test');
+        },
+      },
+    ],
+  }),
+)
+class BrokenModule {}
+
+describe('test standalone app functions', () => {
+  let mockedModule: DeepMocked<DynamicModule>;
+  let mockedServiceFunction: jest.Mock<() => string>;
+
+  beforeEach(async () => {
+    jest.resetAllMocks();
+    mockedServiceFunction = jest.fn(() => 'Test');
+
+    mockedModule = createMock<DynamicModule>({
+      imports: [],
+    });
+
+    const mockedCreateApplicationContext = jest.spyOn(
+      NestFactory,
+      'createApplicationContext',
+    );
+
+    mockedCreateApplicationContext.mockImplementation(
+      () =>
+        createMock<INestApplicationContext>({
+          get: mockedServiceFunction,
+        }) as any,
+    );
+  });
+
+  afterEach(() => {
+    getBootstrappedApps().forEach((app) => app.closeApp());
+    getBootstrappedApps().clear();
+  });
+
+  it('should run executeStandaloneFunction', async () => {
+    const mockedFunction = jest.fn(async (service: any) => {
+      return service;
+    });
+
+    await executeStandaloneFunction(
+      mockedModule,
+      mockedServiceFunction,
+      mockedFunction,
+      {},
+      { closeApp: true },
+    );
+
+    expect(mockedFunction).toHaveBeenCalledTimes(1);
+  });
+
+  it('should run executeStandaloneFunction without close app', async () => {
+    const mockedFunction = jest.fn(async (service: any) => {
+      return service;
+    });
+
+    await executeStandaloneFunction(
+      mockedModule,
+      mockedServiceFunction,
+      mockedFunction,
+      {},
+    );
+
+    expect(mockedFunction).toHaveBeenCalledTimes(1);
+  });
+
+  it('should run executeStandaloneFunction with class module', async () => {
+    const mockedFunction = jest.fn(async (service: any) => {
+      return service;
+    });
+
+    class TestModule {
+      constructor() {}
+    }
+
+    await executeStandaloneFunction(
+      TestModule,
+      mockedServiceFunction,
+      mockedFunction,
+      {},
+    );
+
+    expect(mockedFunction).toHaveBeenCalledTimes(1);
+  });
+
+  it('should trigger an error if we bootstrap multiple servers', async () => {
+    await new AppBootstrap('test1', TestModule1).initApp();
+
+    let error: any = null;
+    try {
+      await new AppBootstrap('test2', TestModule2, {}).initApp();
+    } catch (e: any) {
+      // eslint-disable-next-line no-console
+      console.log(e);
+      error = e;
+    }
+
+    await expect(error).not.toBe(null);
+  });
+
+  it('should not trigger an error when the first app cannot be initialized because of an error', async () => {
+    try {
+      await new AppBootstrap('brokenModule', BrokenModule).initApp();
+    } catch (e: any) {
+      // nothing
+    }
+
+    let error: any = null;
+    try {
+      await new AppBootstrap('test2', TestModule2, {}).initApp();
+    } catch (e: any) {
+      // eslint-disable-next-line no-console
+      console.log(e);
+      error = e;
+    }
+
+    await expect(error).toBe(null);
+  });
+
+  it('should not trigger an error if we bootstrap multiple servers with the skip option', async () => {
+    await new AppBootstrap('test1', TestModule1, {
+      skipMultiServerCheck: true,
+    }).initApp();
+
+    let error: any = null;
+    try {
+      await new AppBootstrap('test2', TestModule2, {
+        skipMultiServerCheck: true,
+      }).initApp();
+    } catch (e: any) {
+      // eslint-disable-next-line no-console
+      console.log(e);
+      error = e;
+    }
+
+    await expect(error).toBe(null);
+  });
+
+  it('should not trigger an error if we bootstrap multiple servers with the env variable', async () => {
+    process.env.APP_SKIP_MULTISERVER_CHECK = 'true';
+
+    await new AppBootstrap('test1', TestModule1).initApp();
+
+    let error: any = null;
+    try {
+      await new AppBootstrap('test2', TestModule2).initApp();
+    } catch (e: any) {
+      // eslint-disable-next-line no-console
+      console.log(e);
+      error = e;
+    }
+
+    await expect(error).toBe(null);
+  });
+
+  it('should get the main bootstrapped app', async () => {
+    const app = await new AppBootstrap('test1', TestModule1).initApp();
+
+    const mainApp = getMainBootstrappedApp();
+
+    expect(mainApp === app).toBe(true);
+  });
+});