@ask-ell/back-end 0.1.1 → 0.2.3

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @ask-ell/back-end
+
+## 0.2.3
+
+### Patch Changes
+
+- [`473e25b`](https://github.com/ask-ell/stacks/commit/473e25b399b8ac336dabb5f8c9fda3b1428cabb6) Thanks [@timbitwin](https://github.com/timbitwin)! - Exported `CreateKeyvStoreAdapterOptions`, `ErrorInterceptorProps`, `NestApplicationFactoryParams`, and the `update-dependencies-versions` script types so they resolve correctly in generated documentation. Also wired up the `http`, `add-ons`, `filters`, `interceptors`, and `modules` barrels that were left disconnected from the package entry point after the last refactor, so the public API is fully reachable and documented from `index.ts`.
+- Updated dependencies [[`473e25b`](https://github.com/ask-ell/stacks/commit/473e25b399b8ac336dabb5f8c9fda3b1428cabb6), [`473e25b`](https://github.com/ask-ell/stacks/commit/473e25b399b8ac336dabb5f8c9fda3b1428cabb6), [`473e25b`](https://github.com/ask-ell/stacks/commit/473e25b399b8ac336dabb5f8c9fda3b1428cabb6)]:
+  - @ask-ell/core@1.3.6
+  - @ask-ell/nest@0.0.15
+  - @ask-ell/node@0.0.5

package/jest.config.ts

@@ -1,4 +1,3 @@
- 
 import { readFileSync } from 'fs';
 
 // Reading the SWC compilation config for the spec files

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ask-ell/back-end",
-  "version": "0.1.1",
+  "version": "0.2.3",
   "private": false,
   "type": "commonjs",
   "main": "./src/index.js",
@@ -17,9 +17,11 @@
     "@nestjs/swagger": "*",
     "@nestjs/throttler": "*",
     "@sentry/nestjs": "*",
+    "express": "*",
     "helmet": "*",
     "keyv": "*",
     "pg": "*",
-    "tslib": "*"
+    "tslib": "*",
+    "rxjs": "*"
   }
 }

package/project.json

@@ -8,22 +8,19 @@
     "build": {
       "executor": "@nx/js:tsc",
       "dependsOn": ["^build"],
-      "outputs": [
-        "{options.outputPath}"
-      ],
+      "outputs": ["{options.outputPath}"],
       "options": {
         "outputPath": "dist/packages/back-end",
         "main": "packages/back-end/src/index.ts",
         "tsConfig": "packages/back-end/tsconfig.lib.json",
-        "assets": [
-          "packages/back-end/*.md"
-        ]
+        "assets": ["packages/back-end/*.md"]
       }
     },
     "test": {
       "options": {
         "passWithNoTests": true
       }
-    }
+    },
+    "format": {}
   }
 }

package/src/http/index.ts

@@ -0,0 +1 @@
+export * from './types';

package/src/http/types.ts

@@ -0,0 +1,4 @@
+export type HttpResponseBody<Data = unknown> = {
+  message: string;
+  data?: Data;
+};

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * @module @ask-ell/back-end
  */
-export * from './add-ons';
 export * from './scripts';
+export * from './http';
+export * from './nest';
 export * from './keyv.store.adapter.factory';
-export * from "./application.base";

package/src/keyv.store.adapter.factory.ts

@@ -1,37 +1,43 @@
-import { Injectable } from "@nestjs/common";
-import { KeyvStoreAdapter } from "keyv";
+import { Injectable } from '@nestjs/common';
+import { KeyvStoreAdapter } from 'keyv';
 import KeyvSqlite from '@keyv/sqlite';
 import KeyvPostgres from '@keyv/postgres';
-import { ILogger, MaybeUndefined } from "@ask-ell/core";
+import { ILogger, MaybeUndefined } from '@ask-ell/core';
 import { NestLogger } from '@ask-ell/nest';
-import { join } from "node:path";
+import { join } from 'node:path';
 
-import { createTmpFolder, TMP_FOLDER_PATH } from "./utils";
+import { createTmpFolder, TMP_FOLDER_PATH } from './tmp';
 
-
-type CreateKeyvStoreAdapterOptions = {
-    postgresUri: MaybeUndefined<string>;
-}
+export type CreateKeyvStoreAdapterOptions = {
+  postgresUri: MaybeUndefined<string>;
+};
 
 @Injectable()
 export class KeyvStoreAdapterFactory {
-    private logger: ILogger = NestLogger.fromClass(KeyvStoreAdapterFactory);
+  private logger: ILogger = NestLogger.fromClass(KeyvStoreAdapterFactory);
 
-    create(options: CreateKeyvStoreAdapterOptions): KeyvStoreAdapter {
-        const adapter: KeyvStoreAdapter = this.getKeyvStoreAdapter(options);
-        this.logger.log(`Connected to database with adapter "${adapter.constructor.name}"`);
-        return adapter;
-    }
+  create(options: CreateKeyvStoreAdapterOptions): KeyvStoreAdapter {
+    const adapter: KeyvStoreAdapter = this.getKeyvStoreAdapter(options);
+    this.logger.log(
+      `Connected to database with adapter "${adapter.constructor.name}"`
+    );
+    return adapter;
+  }
 
-    private getKeyvStoreAdapter({ postgresUri }: CreateKeyvStoreAdapterOptions): KeyvStoreAdapter {
-        if (!postgresUri) {
-            createTmpFolder(this.logger);
-            const localDatabaseFilePath: string = join(TMP_FOLDER_PATH, 'database.sqlite');
-            return new KeyvSqlite(localDatabaseFilePath);
-        }
-
-        return new KeyvPostgres({
-            uri: postgresUri,
-        });
+  private getKeyvStoreAdapter({
+    postgresUri,
+  }: CreateKeyvStoreAdapterOptions): KeyvStoreAdapter {
+    if (!postgresUri) {
+      createTmpFolder(this.logger);
+      const localDatabaseFilePath: string = join(
+        TMP_FOLDER_PATH,
+        'database.sqlite'
+      );
+      return new KeyvSqlite(localDatabaseFilePath);
     }
+
+    return new KeyvPostgres({
+      uri: postgresUri,
+    });
+  }
 }

package/src/nest/add-ons/add-on.interface.ts

@@ -0,0 +1,5 @@
+import { INestApplication } from '@nestjs/common';
+
+export interface IAddOn<T> {
+  apply(application: INestApplication<T>): void;
+}

package/src/nest/add-ons/add-on.wrapper.ts

@@ -0,0 +1,31 @@
+import { INestApplication } from '@nestjs/common';
+
+import { IAddOn } from './add-on.interface';
+import { SecurityAddOn } from './implementations/security/security.add-on';
+import { AddOnWrapperParams } from './types';
+import { SwaggerAddon } from './implementations/swagger/swagger.add-on';
+import { SentryAddon } from './implementations/sentry/sentry.add-on';
+
+export class AddOnWrapper<T> implements IAddOn<T> {
+  private implementations: IAddOn<T>[] = [new SecurityAddOn()];
+
+  constructor(private params: AddOnWrapperParams) {
+    this.appendImplementations();
+  }
+
+  apply(application: INestApplication<T>): void {
+    this.implementations.forEach((addOn: IAddOn<T>): void => {
+      addOn.apply(application);
+    });
+  }
+
+  private appendImplementations(): void {
+    const { sentry, swagger } = this.params;
+    if (swagger) {
+      this.implementations.push(new SwaggerAddon(swagger));
+    }
+    if (sentry) {
+      this.implementations.push(new SentryAddon(sentry));
+    }
+  }
+}

package/src/{add-ons → nest/add-ons}/implementations/security/security.add-on.ts

@@ -1,8 +1,7 @@
-import { INestApplication, ValidationPipe } from "@nestjs/common";
+import { INestApplication, ValidationPipe } from '@nestjs/common';
 import helmet from 'helmet';
 
-import { IAddOn } from "../../add-on.interface";
-
+import { IAddOn } from '../../add-on.interface';
 
 export class SecurityAddOn<T> implements IAddOn<T> {
   apply(application: INestApplication<T>): void {
@@ -11,7 +10,7 @@ export class SecurityAddOn<T> implements IAddOn<T> {
     application.useGlobalPipes(
       new ValidationPipe({
         transform: true,
-        whitelist: false
+        whitelist: false,
       })
     );
   }

package/src/nest/add-ons/implementations/sentry/sentry.add-on.interface.ts

@@ -0,0 +1,8 @@
+import { IEntity } from '@ask-ell/core';
+
+import { ISentryAddOnState } from './sentry.add-on.state.interface';
+import { IAddOn } from '../../add-on.interface';
+
+export interface ISentryAddOn<T>
+  extends IEntity<ISentryAddOnState>,
+    IAddOn<T> {}

package/src/{add-ons → nest/add-ons}/implementations/sentry/sentry.add-on.state.interface.ts

@@ -2,4 +2,4 @@ export interface ISentryAddOnState {
   publicKey: string;
   host: string;
   projectId: string;
-}
+}

package/src/{add-ons → nest/add-ons}/implementations/sentry/sentry.add-on.ts

@@ -1,9 +1,8 @@
-import { Entity, type IResult, ok } from "@ask-ell/core";
-import { NestSentryConfiguration } from "@ask-ell/nest"
-
-import { ISentryAddOnState } from "./sentry.add-on.state.interface";
-import { ISentryAddOn } from "./sentry.add-on.interface";
+import { Entity, type IResult, ok } from '@ask-ell/core';
+import { NestSentryConfiguration } from '@ask-ell/nest';
 
+import { ISentryAddOnState } from './sentry.add-on.state.interface';
+import { ISentryAddOn } from './sentry.add-on.interface';
 
 export class SentryAddon<T>
   extends Entity<ISentryAddOnState>
@@ -17,9 +16,9 @@ export class SentryAddon<T>
     const { host, projectId, publicKey } = this.getSnapshot();
 
     new NestSentryConfiguration({
-        publicKey,
-        host,
-        projectId
+      publicKey,
+      host,
+      projectId,
     }).init();
   }
-}
+}

package/src/nest/add-ons/implementations/swagger/swagger.add-on.interface.ts

@@ -0,0 +1,8 @@
+import { IEntity } from '@ask-ell/core';
+
+import { ISwaggerAddOnState } from './swagger.add-on.state.interface';
+import { IAddOn } from '../../add-on.interface';
+
+export interface ISwaggerAddOn<T>
+  extends IEntity<ISwaggerAddOnState>,
+    IAddOn<T> {}

package/src/{add-ons → nest/add-ons}/implementations/swagger/swagger.add-on.state.interface.ts

@@ -1,6 +1,7 @@
-import { AuthMethod } from "./types";
+import { AuthMethod } from './types';
 
 export interface ISwaggerAddOnState {
   title: string;
   auths?: AuthMethod[];
-}
+  enabledInProduction?: boolean;
+}

package/src/nest/add-ons/implementations/swagger/swagger.add-on.ts

@@ -0,0 +1,59 @@
+import {
+  Entity,
+  ILogger,
+  type IResult,
+  isOnDevelopmentMode,
+  ok,
+} from '@ask-ell/core';
+import { NestLogger } from '@ask-ell/nest';
+import { type INestApplication } from '@nestjs/common';
+import {
+  DocumentBuilder,
+  type OpenAPIObject,
+  SwaggerModule,
+} from '@nestjs/swagger';
+
+import { ISwaggerAddOnState } from './swagger.add-on.state.interface';
+import { ISwaggerAddOn } from './swagger.add-on.interface';
+import { AuthMethod } from './types';
+
+export class SwaggerAddon<T>
+  extends Entity<ISwaggerAddOnState>
+  implements ISwaggerAddOn<T>
+{
+  private logger: ILogger = NestLogger.fromClass(SwaggerAddon);
+
+  checkStateValidity(): IResult<void> {
+    return ok();
+  }
+
+  apply(application: INestApplication<T>): void {
+    const { title, auths, enabledInProduction } = this.getSnapshot();
+
+    if (!enabledInProduction && !isOnDevelopmentMode()) {
+      return;
+    }
+
+    const documentBuilder: DocumentBuilder = new DocumentBuilder().setTitle(
+      title
+    );
+
+    auths?.forEach((auth: AuthMethod): void => {
+      if (auth === 'bearer') {
+        documentBuilder.addBearerAuth();
+      }
+    });
+
+    const documentBuild: Omit<OpenAPIObject, 'paths'> = documentBuilder.build();
+
+    const documentFactory = (): OpenAPIObject =>
+      SwaggerModule.createDocument(application, documentBuild);
+
+    SwaggerModule.setup('/swagger', application, documentFactory, {
+      customSiteTitle: title,
+      jsonDocumentUrl: '/swagger/json',
+    });
+
+    this.logger.log('Swagger initialized');
+  }
+}

package/src/nest/add-ons/implementations/swagger/types.ts

@@ -0,0 +1 @@
+export type AuthMethod = 'bearer' | 'cookie';

package/src/nest/add-ons/index.ts

@@ -0,0 +1,6 @@
+export * from './add-on.interface';
+export * from './add-on.wrapper';
+export * from './types';
+export * from './implementations/sentry/sentry.add-on.state.interface';
+export * from './implementations/swagger/swagger.add-on.state.interface';
+export * from './implementations/swagger/types';

package/src/nest/add-ons/types.ts

@@ -0,0 +1,7 @@
+import { ISentryAddOnState } from './implementations/sentry/sentry.add-on.state.interface';
+import { ISwaggerAddOnState } from './implementations/swagger/swagger.add-on.state.interface';
+
+export type AddOnWrapperParams = Partial<{
+  swagger: ISwaggerAddOnState;
+  sentry: ISentryAddOnState;
+}>;

package/src/nest/application.base.ts

@@ -0,0 +1,18 @@
+import { DynamicModule, Provider, Module, Global } from '@nestjs/common';
+
+import { RequirementModule } from './modules';
+
+@Global()
+@Module({
+  imports: [RequirementModule],
+})
+export class ApplicationBase {
+  static withProviders(providers: Provider[]): DynamicModule {
+    const providersAndExports: Provider[] = [...providers];
+    return {
+      module: this,
+      providers: providersAndExports,
+      exports: [...providersAndExports],
+    };
+  }
+}

package/src/nest/application.factory.ts

@@ -0,0 +1,23 @@
+import { ConsoleLogger, DynamicModule, INestApplication } from '@nestjs/common';
+import { NestFactory } from '@nestjs/core';
+import { IServerProvider } from '@ask-ell/node';
+
+import { AddOnWrapper, AddOnWrapperParams } from './add-ons';
+
+export type NestApplicationFactoryParams = {
+  addons: AddOnWrapperParams;
+  module: DynamicModule;
+};
+
+export async function createNestApplication({
+  module,
+  addons: addonsParams,
+}: NestApplicationFactoryParams): Promise<IServerProvider> {
+  const application: INestApplication = await NestFactory.create(module, {
+    logger: new ConsoleLogger({
+      json: true,
+    }),
+  });
+  new AddOnWrapper(addonsParams).apply(application);
+  return application;
+}

package/src/nest/filters/http.exception.filter.ts

@@ -0,0 +1,23 @@
+import {
+  type ExceptionFilter,
+  type ArgumentsHost,
+  Catch,
+  HttpException,
+} from '@nestjs/common';
+import type { HttpArgumentsHost } from '@nestjs/common/interfaces';
+import type { Response } from 'express';
+
+import type { HttpResponseBody } from '../../http';
+
+@Catch(HttpException)
+export class HttpExceptionFilter implements ExceptionFilter {
+  catch(exception: HttpException, host: ArgumentsHost): void {
+    const context: HttpArgumentsHost = host.switchToHttp();
+    const response: Response = context.getResponse<Response>();
+    const status: number = exception.getStatus();
+    const responseData: HttpResponseBody = {
+      message: exception.message,
+    };
+    response.status(status).json(responseData);
+  }
+}

package/src/nest/filters/index.ts

@@ -0,0 +1 @@
+export * from './http.exception.filter';

package/src/nest/index.ts

@@ -0,0 +1,6 @@
+export * from './add-ons';
+export * from './application.base';
+export * from './application.factory';
+export * from './filters';
+export * from './interceptors';
+export * from './modules';

package/src/nest/interceptors/error.interceptor.ts

@@ -0,0 +1,25 @@
+import { Entity, IResult, ok } from '@ask-ell/core';
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { catchError, Observable, throwError } from 'rxjs';
+
+export type ErrorInterceptorProps = {
+  errorConvertor: (error: unknown) => unknown;
+};
+
+export class ErrorInterceptor
+  extends Entity<ErrorInterceptorProps>
+  implements NestInterceptor
+{
+  override checkStateValidity(): IResult {
+    return ok();
+  }
+
+  intercept(_: ExecutionContext, next: CallHandler): Observable<unknown> {
+    const { errorConvertor } = this.getSnapshot();
+    return next.handle().pipe(
+      catchError((error: unknown): Observable<never> => {
+        return throwError((): unknown => errorConvertor(error));
+      })
+    );
+  }
+}

package/src/nest/interceptors/index.ts

@@ -0,0 +1,2 @@
+export * from './error.interceptor';
+export * from './response.format.interceptor';

package/src/nest/interceptors/response.format.interceptor.ts

@@ -0,0 +1,29 @@
+import {
+  Injectable,
+  NestInterceptor,
+  ExecutionContext,
+  CallHandler,
+} from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { map } from 'rxjs/operators';
+
+import { HttpResponseBody } from '../../http/types';
+
+@Injectable()
+export class ResponseFormatInterceptor<T>
+  implements NestInterceptor<T, HttpResponseBody<T>>
+{
+  intercept(
+    _context: ExecutionContext,
+    next: CallHandler
+  ): Observable<HttpResponseBody<T>> {
+    return next.handle().pipe(
+      map(
+        (data: T): HttpResponseBody<T> => ({
+          data,
+          message: 'ok',
+        })
+      )
+    );
+  }
+}

package/src/nest/modules/health/health.module.ts

@@ -0,0 +1,20 @@
+import {
+  MiddlewareConsumer,
+  Module,
+  NestModule,
+  RequestMethod,
+} from '@nestjs/common';
+
+import { PingMiddleware } from './middlewares';
+
+@Module({
+  providers: [PingMiddleware],
+})
+export class HealthModule implements NestModule {
+  configure(consumer: MiddlewareConsumer): void {
+    consumer.apply(PingMiddleware).forRoutes({
+      path: '/health/ping',
+      method: RequestMethod.GET,
+    });
+  }
+}

package/src/nest/modules/health/index.ts

@@ -0,0 +1 @@
+export * from './health.module';

package/src/nest/modules/health/middlewares/index.ts

@@ -0,0 +1 @@
+export * from './ping.middleware';

package/src/nest/modules/health/middlewares/ping.middleware.ts

@@ -0,0 +1,9 @@
+import { Injectable, NestMiddleware } from '@nestjs/common';
+import type { Request, Response } from 'express';
+
+@Injectable()
+export class PingMiddleware implements NestMiddleware {
+  use(_request: Request, response: Response): void {
+    response.end('Pong');
+  }
+}

package/src/nest/modules/index.ts

@@ -0,0 +1,2 @@
+export * from './health';
+export * from './requirement';

package/src/nest/modules/requirement/index.ts

@@ -0,0 +1 @@
+export * from './requirement.module';

package/src/nest/modules/requirement/requirement.module.ts

@@ -0,0 +1,56 @@
+import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import { APP_FILTER, APP_GUARD, APP_INTERCEPTOR } from '@nestjs/core';
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
+import type { ILogger } from '@ask-ell/core';
+import { NestLogger } from '@ask-ell/nest';
+import { SentryGlobalFilter, SentryModule } from '@sentry/nestjs/setup';
+
+import { KeyvStoreAdapterFactory } from '../../../keyv.store.adapter.factory';
+import { dockerSecretGetter, localSecretGetter } from '../../../secrets';
+import { HealthModule } from '../health';
+import { ResponseFormatInterceptor } from '../../interceptors';
+import { HttpExceptionFilter } from '../../filters';
+
+const configModuleLogger: ILogger = NestLogger.fromClass(ConfigModule);
+
+@Module({
+  imports: [
+    HealthModule,
+    SentryModule.forRoot(),
+    ThrottlerModule.forRoot([
+      {
+        ttl: 60000,
+        limit: 30,
+      },
+    ]),
+    ConfigModule.forRoot({
+      isGlobal: true,
+      load: [
+        dockerSecretGetter(configModuleLogger),
+        localSecretGetter(configModuleLogger),
+      ],
+    }),
+  ],
+  providers: [
+    KeyvStoreAdapterFactory,
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: ResponseFormatInterceptor,
+    },
+    {
+      provide: APP_FILTER,
+      useClass: HttpExceptionFilter,
+    },
+    {
+      provide: APP_FILTER,
+      useClass: SentryGlobalFilter,
+    },
+  ],
+  exports: [ConfigModule, SentryModule, KeyvStoreAdapterFactory],
+})
+export class RequirementModule {}