@digitaldefiance/node-express-suite 3.7.3 → 3.7.5

package/src/services/xor.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Simple XOR cipher service for obfuscating data in memory.
+ * Provides lightweight protection against plaintext storage without strong cryptography.
+ * @module services/xor
+ */
+
+import { randomBytes } from 'crypto';
+
+/**
+ * A simple and fast XOR cipher for obfuscating data in memory.
+ * This is not a substitute for strong cryptography but provides a lightweight way
+ * to prevent sensitive data from being stored in plaintext in memory.
+ */
+export class XorService {
+  /**
+   * Encrypts or decrypts data using a simple XOR cipher.
+   * The key is XORed with the data. The same function is used for
+   * both encryption and decryption.
+   * @param data Data to process
+   * @param key Key to use for the XOR operation
+   * @returns New Buffer containing the result of the XOR operation
+   */
+  public static xor(data: Buffer, key: Buffer): Buffer {
+    const result = Buffer.alloc(data.length);
+    for (let i = 0; i < data.length; i++) {
+      result[i] = data[i] ^ key[i % key.length];
+    }
+    return result;
+  }
+
+  /**
+   * Generates a random key of a specified length.
+   * @param length Length of the key in bytes
+   * @returns Buffer containing the random key
+   */
+  public static generateKey(length: number): Buffer {
+    return randomBytes(length);
+  }
+}

package/src/testing.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Test utilities entry point.
+ * Re-exports test helpers and setup utilities.
+ * @module testing
+ */
+
+// Test utilities entry point - import from '@digitaldefiance/node-express-suite/testing'
+export * from './__tests__';
+export * from './__tests__/helpers/setup-test-env';

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

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

package/src/transactions/transaction-manager.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Transaction manager for MongoDB transactions.
+ * Manages transaction lifecycle with retry logic and timeout support.
+ * @module transactions/transaction-manager
+ */
+
+import { ClientSession, Connection } from '@digitaldefiance/mongoose-types';
+
+/**
+ * Options for transaction execution.
+ */
+export interface TransactionOptions {
+  /** Transaction timeout in milliseconds */
+  timeoutMs?: number;
+  /** Maximum number of retry attempts */
+  maxRetries?: number;
+}
+
+/**
+ * Manager for MongoDB transactions.
+ */
+export class TransactionManager {
+  /**
+   * Creates a new transaction manager.
+   * @param {Connection} connection - Mongoose connection
+   * @param {boolean} useTransactions - Whether to use transactions
+   */
+  constructor(
+    private connection: Connection,
+    private useTransactions: boolean,
+  ) {}
+
+  /**
+   * Executes a callback within a transaction.
+   * @template T - Return type
+   * @param {Function} callback - Function to execute in transaction
+   * @param {TransactionOptions} [options] - Transaction options
+   * @returns {Promise<T>} Result of callback execution
+   */
+  async execute<T>(
+    callback: (session: ClientSession | undefined) => Promise<T>,
+    options?: TransactionOptions,
+  ): Promise<T> {
+    if (!this.useTransactions) {
+      return callback(undefined);
+    }
+
+    const session = await this.connection.startSession();
+    try {
+      return await session.withTransaction(
+        (sess: ClientSession) => callback(sess),
+        {
+          readConcern: { level: 'snapshot' },
+          writeConcern: { w: 'majority' },
+          readPreference: 'primary',
+          maxCommitTimeMS: options?.timeoutMs,
+        },
+      );
+    } finally {
+      await session.endSession();
+    }
+  }
+}

package/src/types/app-config.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Application configuration type.
+ * Defines structure for application-wide configuration.
+ * @module types/app-config
+ */
+
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Application configuration interface.
+ * @template TModelDocs - Model documents type
+ * @template TInitResults - Initialization results type
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export interface AppConfig<
+  TModelDocs = unknown,
+  TInitResults = unknown,
+  TID extends PlatformID = Buffer,
+> {
+  environment: Environment;
+  constants: IConstants;
+  models: TModelDocs;
+  initResults: TInitResults;
+  idType: TID;
+  dateType: Date;
+}
+
+/**
+ * Default application configuration with standard types.
+ */
+export interface DefaultAppConfig extends AppConfig<unknown, unknown> {
+  idType: Buffer;
+  dateType: Date;
+}

package/src/types/controller-config.ts

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Controller configuration type.
+ * Defines type configuration for controllers.
+ * @module types/controller-config
+ */
+
+import { Environment } from '../environment';
+import { IConstants } from '../interfaces';
+import type { PlatformID } from '@digitaldefiance/node-ecies-lib';
+
+/**
+ * Controller configuration interface.
+ * @template TID - Platform ID type (defaults to Buffer)
+ */
+export interface ControllerConfig<TID extends PlatformID = Buffer> {
+  idType: TID;
+  dateType: Date;
+  constants: IConstants;
+  environment: Environment;
+}
+
+/**
+ * Default controller configuration with standard types.
+ */
+export interface DefaultControllerConfig extends ControllerConfig {
+  idType: Buffer;
+  dateType: Date;
+}

package/src/types/{environment-variables.d.ts → environment-variables.ts}

@@ -1,31 +1,58 @@
+/**
+ * @fileoverview Type-safe environment variable access utilities.
+ * Provides utilities for safely accessing environment variables.
+ * @module types/environment-variables
+ */
+
 /**
  * Type-safe environment variable access utilities
  */
+
 /**
  * Interface for environment variables with index signature
  */
 export interface EnvironmentVariables {
-    [key: string]: string | undefined;
+  [key: string]: string | undefined;
 }
+
 /**
  * Type-safe function to get environment variable
  * @param obj - The environment object (typically process.env)
  * @param key - The environment variable key
  * @returns The environment variable value or undefined
  */
-export declare function getEnvVar(obj: EnvironmentVariables, key: string): string | undefined;
+export function getEnvVar(
+  obj: EnvironmentVariables,
+  key: string,
+): string | undefined {
+  return obj[key];
+}
+
 /**
  * Type guard to check if an object has a specific property
  * @param obj - The object to check
  * @param key - The property key
  * @returns True if the object has the property
  */
-export declare function hasProperty<T extends object, K extends PropertyKey>(obj: T, key: K): obj is T & Record<K, unknown>;
+export function hasProperty<T extends object, K extends PropertyKey>(
+  obj: T,
+  key: K,
+): obj is T & Record<K, unknown> {
+  return key in obj;
+}
+
 /**
  * Type-safe function to get a property from an object
  * @param obj - The object to get the property from
  * @param key - The property key
  * @returns The property value or undefined
  */
-export declare function getProperty<T extends object, K extends string>(obj: T, key: K): unknown;
-//# sourceMappingURL=environment-variables.d.ts.map
+export function getProperty<T extends object, K extends string>(
+  obj: T,
+  key: K,
+): unknown {
+  if (hasProperty(obj, key)) {
+    return obj[key];
+  }
+  return undefined;
+}

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

@@ -1,3 +1,2 @@
 export * from './app-config';
 export * from './controller-config';
-//# sourceMappingURL=index.d.ts.map

package/src/types/{mongoose-helpers.d.ts → mongoose-helpers.ts}

@@ -1,11 +1,17 @@
+/**
+ * @fileoverview Type-safe helpers for Mongoose operations.
+ * Provides utility types for Mongoose queries and projections.
+ * @module types/mongoose-helpers
+ */
+
 /**
  * Type-safe helpers for Mongoose operations
  */
+
 /**
  * Type for Mongoose projection objects
  * Allows specifying which fields to include (1) or exclude (0)
  */
 export type MongooseProjection<T> = {
-    [K in keyof T]?: 0 | 1 | boolean;
+  [K in keyof T]?: 0 | 1 | boolean;
 };
-//# sourceMappingURL=mongoose-helpers.d.ts.map

package/src/types/mongoose-override.d.ts

@@ -0,0 +1 @@
+// Type overrides for mongoose - intentionally empty

package/src/types/mongoose.d.ts

@@ -0,0 +1 @@
+// Local mongoose-types submodule provides custom ID type support via paths mapping in tsconfig

package/src/types.ts

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview Type definitions and Express module augmentation.
+ * Defines core types for routing, validation, and API responses.
+ * @module types
+ */
+
+import { ClientSession } from '@digitaldefiance/mongoose-types';
+import { Member, PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { IRequestUserDTO } from '@digitaldefiance/suite-core-lib';
+import { NextFunction, RequestHandler, Response } from 'express';
+import { ValidationChain } from 'express-validator';
+import { IBaseDocument } from './documents';
+import {
+  IApiErrorResponse,
+  IApiExpressValidationErrorResponse,
+  IApiMessageResponse,
+  IApiMongoValidationErrorResponse,
+  IStatusCodeResponse,
+} from './interfaces';
+import { ISchema } from './interfaces/schema';
+
+/**
+ * Transaction callback type for withTransaction
+ */
+export type TransactionCallback<T> = (
+  session: ClientSession | undefined,
+  ...args: Array<unknown>
+) => Promise<T>;
+
+/**
+ * Validated body for express-validator
+ */
+export type ValidatedBody<T extends string> = {
+  [K in T]: unknown;
+};
+
+declare module 'express-serve-static-core' {
+  interface Request {
+    user?: IRequestUserDTO;
+    eciesUser?: Member<PlatformID>;
+    validatedBody?: ValidatedBody<string>;
+    validate?: {
+      body: (field: string) => ValidationChain;
+      param: (field: string) => ValidationChain;
+      query: (field: string) => ValidationChain;
+      header: (field: string) => ValidationChain;
+      cookie: (field: string) => ValidationChain;
+    };
+  }
+}
+
+declare global {
+  /* eslint-disable @typescript-eslint/no-namespace */
+  namespace Express {
+    interface Request {
+      user?: IRequestUserDTO;
+      eciesUser?: Member<PlatformID>;
+      validatedBody?: ValidatedBody<string>;
+      validate?: {
+        body: (field: string) => ValidationChain;
+        param: (field: string) => ValidationChain;
+        query: (field: string) => ValidationChain;
+        header: (field: string) => ValidationChain;
+        cookie: (field: string) => ValidationChain;
+      };
+    }
+  }
+}
+
+/**
+ * Schema map interface
+ */
+type ModelDocMap<
+  TID extends PlatformID,
+  TModelDocs extends Record<string, IBaseDocument<any, TID>>,
+> = {
+  [K in keyof TModelDocs]: TModelDocs[K];
+};
+
+export type SchemaMap<
+  TID extends PlatformID,
+  TModelDocs extends Record<string, IBaseDocument<any, TID>>,
+> = {
+  /**
+   * For each model name, contains the corresponding schema and model
+   */
+  [K in keyof ModelDocMap<TID, TModelDocs>]: ISchema<
+    TID,
+    ModelDocMap<TID, TModelDocs>[K]
+  >;
+};
+
+export type ApiRequestHandler<T extends ApiResponse> = (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+) => Promise<IStatusCodeResponse<T>>;
+
+export type TypedHandlers = {
+  [key: string]: ApiRequestHandler<ApiResponse>;
+};
+
+export interface IRouteDefinition<
+  T extends TypedHandlers,
+  TLanguage extends string,
+> {
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch';
+  path: string;
+  options: {
+    handlerKey: keyof T;
+    validation?: (validationLanguage: TLanguage) => ValidationChain[];
+    useAuthentication: boolean;
+    useCryptoAuthentication: boolean;
+  };
+}
+
+export type RouteHandlers = Record<string, ApiRequestHandler<ApiResponse>>;
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch';
+
+export interface RouteConfig<H extends object, TLanguage extends string> {
+  method: HttpMethod;
+  path: string;
+  handlerKey: keyof H;
+  handlerArgs?: Array<unknown>;
+  useAuthentication: boolean;
+  useCryptoAuthentication: boolean;
+  middleware?: RequestHandler[];
+  validation?: FlexibleValidationChain<TLanguage>;
+  rawJsonHandler?: boolean;
+  authFailureStatusCode?: number;
+  useTransaction?: boolean;
+  transactionTimeout?: number;
+}
+
+/**
+ * Creates a route configuration object.
+ * @template T - Handler object type
+ * @template TLanguage - Language code type
+ * @param {HttpMethod} method - HTTP method
+ * @param {string} path - Route path
+ * @param {object} options - Route options
+ * @returns {RouteConfig<T, TLanguage>} Route configuration
+ */
+export function routeConfig<T extends object, TLanguage extends string>(
+  method: 'get' | 'post' | 'put' | 'delete' | 'patch',
+  path: string,
+  options: {
+    handlerKey: keyof T;
+    validation?: (validationLanguage: TLanguage) => ValidationChain[];
+    useAuthentication: boolean;
+    useCryptoAuthentication: boolean;
+  },
+): RouteConfig<T, TLanguage> {
+  return {
+    method,
+    path,
+    handlerKey: options.handlerKey,
+    validation: options.validation,
+    useAuthentication: options.useAuthentication,
+    useCryptoAuthentication: options.useCryptoAuthentication,
+  };
+}
+
+export type THandlerArgs<T extends Array<unknown>> = T;
+
+export type FlexibleValidationChain<TLanguage extends string> =
+  | ValidationChain[]
+  | ((lang: TLanguage) => ValidationChain[]);
+
+export type JsonPrimitive = string | number | boolean | null | undefined;
+
+export type JsonResponse =
+  | JsonPrimitive
+  | { [key: string]: JsonResponse }
+  | JsonResponse[];
+
+export type ApiErrorResponse =
+  | IApiErrorResponse
+  | IApiExpressValidationErrorResponse
+  | IApiMongoValidationErrorResponse;
+
+export type ApiResponse = IApiMessageResponse | ApiErrorResponse | JsonResponse;
+
+export type SendFunction<T extends ApiResponse> = (
+  statusCode: number,
+  data: T,
+  res: Response<T>,
+) => void;