@digitaldefiance/node-express-suite 3.6.20 → 3.6.21

package/src/services/xor.ts

@@ -0,0 +1,34 @@
+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 The data to process.
+   * @param key The key to use for the XOR operation.
+   * @returns A 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 The length of the key in bytes.
+   * @returns A Buffer containing the random key.
+   */
+  public static generateKey(length: number): Buffer {
+    return randomBytes(length);
+  }
+}

package/src/testing.ts

@@ -0,0 +1,3 @@
+// 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,37 @@
+import { ClientSession, Connection } from '@digitaldefiance/mongoose-types';
+
+export interface TransactionOptions {
+  timeoutMs?: number;
+  maxRetries?: number;
+}
+
+export class TransactionManager {
+  constructor(
+    private connection: Connection,
+    private useTransactions: boolean,
+  ) {}
+
+  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.d.ts → app-config.ts}

@@ -1,16 +1,17 @@
 import { Types } from '@digitaldefiance/mongoose-types';
 import { Environment } from '../environment';
 import { IConstants } from '../interfaces';
+
 export interface AppConfig<TModelDocs = unknown, TInitResults = unknown> {
-    environment: Environment;
-    constants: IConstants;
-    models: TModelDocs;
-    initResults: TInitResults;
-    idType: Types.ObjectId | string;
-    dateType: Date;
+  environment: Environment;
+  constants: IConstants;
+  models: TModelDocs;
+  initResults: TInitResults;
+  idType: Types.ObjectId | string;
+  dateType: Date;
 }
+
 export interface DefaultAppConfig extends AppConfig<unknown, unknown> {
-    idType: Types.ObjectId;
-    dateType: Date;
+  idType: Types.ObjectId;
+  dateType: Date;
 }
-//# sourceMappingURL=app-config.d.ts.map

package/src/types/{controller-config.d.ts → controller-config.ts}

@@ -1,14 +1,15 @@
 import { Types } from '@digitaldefiance/mongoose-types';
 import { Environment } from '../environment';
 import { IConstants } from '../interfaces';
+
 export interface ControllerConfig {
-    idType: Types.ObjectId | string;
-    dateType: Date;
-    constants: IConstants;
-    environment: Environment;
+  idType: Types.ObjectId | string;
+  dateType: Date;
+  constants: IConstants;
+  environment: Environment;
 }
+
 export interface DefaultControllerConfig extends ControllerConfig {
-    idType: Types.ObjectId;
-    dateType: Date;
+  idType: Types.ObjectId;
+  dateType: Date;
 }
-//# sourceMappingURL=controller-config.d.ts.map

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

@@ -1,31 +1,52 @@
 /**
  * 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/id-converters.ts

@@ -0,0 +1,53 @@
+/**
+ * Type-safe ID conversion utilities for node-express-suite
+ */
+import { Types } from '@digitaldefiance/mongoose-types';
+
+/**
+ * Type constraint for valid ID types
+ */
+export type ValidIdType = string | Types.ObjectId;
+
+/**
+ * Convert a MongoDB ObjectId to a generic ID type
+ * This is a type-safe wrapper for ID conversions in the generic context
+ * @param id - The MongoDB ObjectId to convert
+ * @returns The ID as the generic type I
+ */
+export function convertObjectIdToGenericId<I extends ValidIdType>(
+  id: Types.ObjectId,
+): I {
+  // When I is Types.ObjectId, return as-is
+  // When I is string, this would need conversion (but we return ObjectId)
+  // This function assumes I is compatible with Types.ObjectId
+  return id as I;
+}
+
+/**
+ * Convert a string to a generic ID type via MongoDB ObjectId
+ * @param idString - The string representation of the ID
+ * @returns The ID as the generic type I
+ */
+export function convertStringToGenericId<I extends ValidIdType>(
+  idString: string,
+): I {
+  return new Types.ObjectId(idString) as I;
+}
+
+/**
+ * Convert a generic ID to a MongoDB ObjectId
+ * @param id - The generic ID to convert
+ * @returns The ID as a MongoDB ObjectId
+ */
+export function convertGenericIdToObjectId<I extends ValidIdType>(
+  id: I,
+): Types.ObjectId {
+  if (id instanceof Types.ObjectId) {
+    return id;
+  }
+  if (typeof id === 'string') {
+    return new Types.ObjectId(id);
+  }
+  // If it's already an ObjectId but TypeScript doesn't know
+  return id as Types.ObjectId;
+}

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,11 @@
 /**
  * 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.d.ts

@@ -1,72 +1,39 @@
-import { ClientSession } from '@digitaldefiance/mongoose-types';
-import { NextFunction, RequestHandler, Response } from 'express';
+import { Member } from '@digitaldefiance/node-ecies-lib';
+import { IRequestUserDTO } from '@digitaldefiance/suite-core-lib';
 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;
-};
-/**
- * Schema map interface
- */
-type ModelDocMap<TModelDocs extends Record<string, IBaseDocument<any>>> = {
-    [K in keyof TModelDocs]: TModelDocs[K];
-};
-export type SchemaMap<TModelDocs extends Record<string, IBaseDocument<any>>> = {
-    [K in keyof ModelDocMap<TModelDocs>]: ISchema<ModelDocMap<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;
+import { ValidatedBody } from './types';
+
+declare module 'express-serve-static-core' {
+  interface Request {
+    user?: IRequestUserDTO;
+    eciesUser?: Member;
+    validatedBody?: ValidatedBody<string>;
+    validate?: {
+      body: (field: string) => ValidationChain;
+      param: (field: string) => ValidationChain;
+      query: (field: string) => ValidationChain;
+      header: (field: string) => ValidationChain;
+      cookie: (field: string) => ValidationChain;
     };
+  }
 }
-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;
+
+declare global {
+  namespace Express {
+    interface Request {
+      user?: IRequestUserDTO;
+      eciesUser?: Member;
+      validatedBody?: ValidatedBody<string>;
+      validate?: {
+        body: (field: string) => ValidationChain;
+        param: (field: string) => ValidationChain;
+        query: (field: string) => ValidationChain;
+        header: (field: string) => ValidationChain;
+        cookie: (field: string) => ValidationChain;
+      };
+    }
+  }
 }
-export declare 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>;
-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;
+
+// This export makes the file a module, ensuring the augmentations are applied
 export {};
-//# sourceMappingURL=types.d.ts.map

package/src/types.ts

@@ -0,0 +1,130 @@
+import { ClientSession } from '@digitaldefiance/mongoose-types';
+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;
+};
+
+/**
+ * Schema map interface
+ */
+type ModelDocMap<TModelDocs extends Record<string, IBaseDocument<any>>> = {
+  [K in keyof TModelDocs]: TModelDocs[K];
+};
+
+export type SchemaMap<TModelDocs extends Record<string, IBaseDocument<any>>> = {
+  /**
+   * For each model name, contains the corresponding schema and model
+   */
+  [K in keyof ModelDocMap<TModelDocs>]: ISchema<ModelDocMap<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;
+}
+
+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;