@digitaldefiance/node-express-suite 3.7.4 → 3.7.5

package/src/builders/application-builder.ts

@@ -0,0 +1,147 @@
+/**
+ * @fileoverview Application builder for fluent application construction.
+ * Provides builder pattern for creating Application instances.
+ * @module builders/application-builder
+ */
+
+import mongoose from '@digitaldefiance/mongoose-types';
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { HelmetOptions } from 'helmet';
+import { Application } from '../application';
+import { BaseApplication } from '../application-base';
+import { IBaseDocument } from '../documents';
+import { Environment } from '../environment';
+import {
+  IApplication,
+  ICSPConfig,
+  IFailableResult,
+  IServerInitResult,
+} from '../interfaces';
+import { IConstants } from '../interfaces/constants';
+import { IFlexibleCSP } from '../interfaces/flexible-csp';
+import { initMiddleware } from '../middleware-utils';
+import { AppRouter } from '../routers/app';
+import { BaseRouter } from '../routers/base';
+import { SchemaMap } from '../types';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Builder for constructing Application instances with fluent API.
+ * @template TID - Platform ID type
+ * @template TModelDocs - Model documents type
+ * @template TInitResults - Initialization results type
+ * @template TConstants - Constants type (defaults to IConstants)
+ */
+export class ApplicationBuilder<
+  TID extends PlatformID,
+  TModelDocs extends Record<string, IBaseDocument<any, TID>>,
+  TInitResults extends IServerInitResult<TID>,
+  TConstants extends IConstants = IConstants,
+> {
+  private environment?: Environment<TID>;
+  private apiRouterFactory?: (app: IApplication<TID>) => BaseRouter<TID>;
+  private appRouterFactory?: (apiRouter: BaseRouter<TID>) => AppRouter<TID>;
+  private schemaMapFactory?: (
+    connection: mongoose.Connection,
+  ) => SchemaMap<TID, TModelDocs>;
+  private databaseInitFunction?: (
+    app: BaseApplication<TID, TModelDocs, TInitResults>,
+  ) => Promise<IFailableResult<TInitResults>>;
+  private initResultHashFunction?: (results: TInitResults) => string;
+  private cspConfig?: ICSPConfig | HelmetOptions | IFlexibleCSP;
+  private constants?: TConstants;
+  private customInitMiddleware?: typeof initMiddleware;
+
+  withEnvironment(env: Environment<TID>): this {
+    this.environment = env;
+    return this;
+  }
+
+  withApiRouter(factory: (app: any) => BaseRouter<TID>): this {
+    this.apiRouterFactory = factory;
+    return this;
+  }
+
+  withAppRouter(factory: (apiRouter: BaseRouter<TID>) => AppRouter<TID>): this {
+    this.appRouterFactory = factory;
+    return this;
+  }
+
+  withSchemaMap(
+    factory: (connection: mongoose.Connection) => SchemaMap<TID, TModelDocs>,
+  ): this {
+    this.schemaMapFactory = factory;
+    return this;
+  }
+
+  withDatabaseInit(
+    initFn: (
+      app: BaseApplication<TID, TModelDocs, TInitResults>,
+    ) => Promise<IFailableResult<TInitResults>>,
+    hashFn: (results: TInitResults) => string,
+  ): this {
+    this.databaseInitFunction = initFn;
+    this.initResultHashFunction = hashFn;
+    return this;
+  }
+
+  withCSP(config: ICSPConfig | HelmetOptions | IFlexibleCSP): this {
+    this.cspConfig = config;
+    return this;
+  }
+
+  withConstants(constants: TConstants): this {
+    this.constants = constants;
+    return this;
+  }
+
+  withMiddleware(middleware: typeof initMiddleware): this {
+    this.customInitMiddleware = middleware;
+    return this;
+  }
+
+  build(): Application<
+    TInitResults,
+    TModelDocs,
+    TID,
+    Environment<TID>,
+    TConstants,
+    AppRouter<TID>
+  > {
+    if (!this.environment)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_EnvironmentIsRequired,
+      );
+    if (!this.apiRouterFactory)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_ApiRouterFactoryIsRequired,
+      );
+    if (!this.schemaMapFactory)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_SchemaMapFactoryIsRequired,
+      );
+    if (!this.databaseInitFunction)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_DatabaseInitFunctionIsRequired,
+      );
+    if (!this.initResultHashFunction)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_InitResultHashFunctionIsRequired,
+      );
+
+    return new Application(
+      this.environment,
+      this.apiRouterFactory,
+      this.schemaMapFactory,
+      this.databaseInitFunction,
+      this.initResultHashFunction,
+      this.cspConfig,
+      this.constants,
+      this.appRouterFactory,
+      this.customInitMiddleware,
+    );
+  }
+}

package/src/builders/{index.d.ts → index.ts}

@@ -1,2 +1 @@
 export * from './application-builder';
-//# sourceMappingURL=index.d.ts.map

package/src/constants.ts

@@ -0,0 +1,89 @@
+/**
+ * @fileoverview Application constants including checksum, JWT, FEC, and ECIES configurations.
+ * Provides factory functions for creating environment-specific constant sets.
+ * @module constants
+ */
+
+import { ECIES as ECIESDefaults } from '@digitaldefiance/ecies-lib';
+import { Constants as NodeEciesConstants } from '@digitaldefiance/node-ecies-lib';
+import {
+  createConstants,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { IFECConsts } from './interfaces';
+import { IChecksumConsts } from './interfaces/checksum-consts';
+import { IConstants } from './interfaces/constants';
+import { IJwtConsts } from './interfaces/jwt-consts';
+
+/**
+ * Constants for checksum operations
+ * These values are critical for data integrity and MUST NOT be changed
+ * in an already established system as it will break all existing checksums.
+ */
+export const CHECKSUM: IChecksumConsts = Object.freeze({
+  /** Default hash bits for SHA3 */
+  SHA3_DEFAULT_HASH_BITS: 512 as const,
+
+  /** Length of a SHA3 checksum buffer in bytes */
+  SHA3_BUFFER_LENGTH: 64 as const,
+
+  /** algorithm to use for checksum */
+  ALGORITHM: 'sha3-512' as const,
+
+  /** encoding to use for checksum */
+  ENCODING: 'hex' as const,
+} as const);
+
+export const JWT: IJwtConsts = {
+  /**
+   * Algorithm to use for JWT
+   */
+  ALGORITHM: 'HS256' as const,
+
+  /**
+   * The expiration time for a JWT token in seconds
+   */
+  EXPIRATION_SEC: 86400 as const,
+} as const;
+
+export const FEC: IFECConsts = {
+  /**
+   * Maximum size of a single shard
+   */
+  MAX_SHARD_SIZE: 1048576 as const,
+} as const;
+
+// use defaults from ecies-lib
+export const ECIES = Object.freeze(ECIESDefaults);
+
+export const createExpressConstants = (
+  siteDomain: string,
+  siteHostname: string,
+  overrides?: Partial<IConstants>,
+): IConstants => {
+  return Object.freeze({
+    ...NodeEciesConstants,
+    CHECKSUM: CHECKSUM,
+    JWT: JWT,
+    FEC: FEC,
+    ECIES: ECIES,
+    ECIES_VERSION_SIZE: 1,
+    ECIES_CIPHER_SUITE_SIZE: 1,
+    ...createConstants(siteDomain, siteHostname, overrides),
+  } as IConstants);
+};
+
+export const LocalhostConstants: IConstants = createExpressConstants(
+  'localhost',
+  'localhost',
+);
+
+if (
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8 ||
+  CHECKSUM.SHA3_BUFFER_LENGTH !== CHECKSUM.SHA3_DEFAULT_HASH_BITS / 8
+) {
+  throw new TranslatableSuiteError(
+    SuiteCoreStringKey.Error_InvalidChecksumConstants,
+  );
+}

package/src/container/{index.d.ts → index.ts}

@@ -1,3 +1,2 @@
 export * from './service-container';
 export * from './service-definitions';
-//# sourceMappingURL=index.d.ts.map

package/src/container/service-container.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Service container for dependency injection.
+ * Manages service registration and lifecycle with singleton support.
+ * @module container/service-container
+ */
+
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+
+/**
+ * Factory function for creating service instances.
+ * @template T - Service type
+ */
+export type ServiceFactory<T = any> = () => T;
+
+/**
+ * Service container for dependency injection.
+ */
+export class ServiceContainer {
+  private services = new Map<string, ServiceFactory>();
+  private instances = new Map<string, any>();
+  private singletons = new Set<string>();
+
+  /**
+   * Registers a service with the container.
+   * @template T - Service type
+   * @param {string} key - Service identifier
+   * @param {ServiceFactory<T>} factory - Factory function to create service
+   * @param {boolean} [singleton=true] - Whether to cache as singleton
+   */
+  register<T>(key: string, factory: ServiceFactory<T>, singleton = true): void {
+    this.services.set(key, factory);
+    if (singleton) {
+      this.singletons.add(key);
+    }
+  }
+
+  /**
+   * Retrieves a service from the container.
+   * @template T - Service type
+   * @param {string} key - Service identifier
+   * @returns {T} Service instance
+   * @throws {TranslatableSuiteError} If service is not registered
+   */
+  get<T>(key: string): T {
+    if (this.singletons.has(key)) {
+      if (!this.instances.has(key)) {
+        const factory = this.services.get(key);
+        if (!factory)
+          throw new TranslatableSuiteError(
+            SuiteCoreStringKey.Error_ServiceIsNotRegisteredTemplate,
+            { key },
+          );
+        this.instances.set(key, factory());
+      }
+      return this.instances.get(key);
+    }
+
+    const factory = this.services.get(key);
+    if (!factory)
+      throw new TranslatableSuiteError(
+        SuiteCoreStringKey.Error_ServiceIsNotRegisteredTemplate,
+        { key },
+      );
+    return factory();
+  }
+
+  /**
+   * Checks if a service is registered.
+   * @param {string} key - Service identifier
+   * @returns {boolean} True if service exists
+   */
+  has(key: string): boolean {
+    return this.services.has(key);
+  }
+
+  /**
+   * Clears all cached singleton instances.
+   */
+  clear(): void {
+    this.instances.clear();
+  }
+}

package/src/container/service-definitions.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Service key definitions for dependency injection.
+ * Defines constants for service registration keys.
+ * @module container/service-definitions
+ */
+
+/**
+ * Service registration keys.
+ */
+export const ServiceKeys = {
+  JWT: 'jwt',
+  EMAIL: 'email',
+  ECIES: 'ecies',
+  KEY_WRAPPING: 'keyWrapping',
+  ROLE: 'role',
+  USER: 'user',
+  BACKUP_CODE: 'backupCode',
+} as const;
+
+/**
+ * Union type of all service keys.
+ */
+export type ServiceKey = (typeof ServiceKeys)[keyof typeof ServiceKeys];