nx-mongo 3.3.0

package/src/simpleMongoHelper.ts

@@ -0,0 +1,1660 @@
+import { MongoClient, Db, Collection, Filter, UpdateFilter, OptionalUnlessRequiredId, Document, WithId, ClientSession, Sort, IndexSpecification, CreateIndexesOptions } from 'mongodb';
+import { createHash } from 'crypto';
+
+export interface PaginationOptions {
+  page?: number;
+  limit?: number;
+  sort?: Sort;
+}
+
+export interface PaginatedResult<T> {
+  data: WithId<T>[];
+  total: number;
+  page: number;
+  limit: number;
+  totalPages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}
+
+export interface RetryOptions {
+  maxRetries?: number;
+  retryDelay?: number;
+  exponentialBackoff?: boolean;
+}
+
+export interface InputConfig {
+  ref: string;
+  collection: string;
+  query?: Filter<any>;
+}
+
+export interface OutputConfig {
+  ref: string;
+  collection: string;
+  keys?: string[];
+  mode?: 'append' | 'replace';
+}
+
+export interface HelperConfig {
+  inputs: InputConfig[];
+  outputs: OutputConfig[];
+  output?: {
+    mode?: 'append' | 'replace';
+  };
+  progress?: {
+    collection?: string;
+    uniqueIndexKeys?: string[];
+    provider?: string;
+  };
+}
+
+export interface WriteByRefResult {
+  inserted: number;
+  updated: number;
+  errors: Array<{ index: number; error: Error; doc?: any }>;
+  indexCreated: boolean;
+}
+
+export interface EnsureSignatureIndexResult {
+  created: boolean;
+  indexName: string;
+}
+
+export interface StageIdentity {
+  key: string;
+  process?: string;
+  provider?: string;
+  name?: string;
+}
+
+export interface StageMetadata {
+  itemCount?: number;
+  errorCount?: number;
+  durationMs?: number;
+  [key: string]: any;
+}
+
+export interface StageRecord extends StageIdentity {
+  completed: boolean;
+  startedAt?: Date;
+  completedAt?: Date;
+  metadata?: StageMetadata;
+}
+
+export type ProgressSessionOptions = { session?: ClientSession };
+
+export interface ProgressAPI {
+  isCompleted(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<boolean>;
+  start(identity: StageIdentity, options?: ProgressSessionOptions): Promise<void>;
+  complete(
+    identity: StageIdentity & { metadata?: StageMetadata },
+    options?: ProgressSessionOptions
+  ): Promise<void>;
+  getCompleted(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<Array<Pick<StageRecord, 'key' | 'name' | 'completedAt'>>>;
+  getProgress(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<StageRecord[]>;
+  reset(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<void>;
+}
+
+export interface WriteStageOptions {
+  ensureIndex?: boolean;
+  session?: ClientSession;
+  complete?: {
+    key: string;
+    process?: string;
+    name?: string;
+    provider?: string;
+    metadata?: StageMetadata;
+  };
+}
+
+export interface WriteStageResult extends WriteByRefResult {
+  completed?: boolean;
+}
+
+/**
+ * Extracts values from an object using dot-notation paths with array wildcard support.
+ * Supports nested object paths (dot notation) and array wildcards ([]) to collect values from all array elements.
+ * @param value - The object to extract values from
+ * @param path - Dot-notation path (e.g., "meta.id", "edges[].from", "segments[]")
+ * @returns Array of extracted values (flattened and deduplicated for arrays)
+ * @example
+ * getByDotPath({ segments: [1, 2, 3] }, "segments[]") // [1, 2, 3]
+ * getByDotPath({ edges: [{ from: "A" }, { from: "B" }] }, "edges[].from") // ["A", "B"]
+ * getByDotPath({ meta: { id: "123" } }, "meta.id") // ["123"]
+ */
+export function getByDotPath(value: any, path: string): any[] {
+  if (value == null) {
+    return [];
+  }
+
+  // Handle array wildcard at the end (e.g., "segments[]", "edges[]")
+  if (path.endsWith('[]')) {
+    const basePath = path.slice(0, -2);
+    const arrayValue = getByDotPath(value, basePath);
+    
+    if (!Array.isArray(arrayValue)) {
+      return [];
+    }
+    
+    // Flatten nested arrays recursively
+    const flatten = (arr: any[]): any[] => {
+      const result: any[] = [];
+      for (const item of arr) {
+        if (Array.isArray(item)) {
+          result.push(...flatten(item));
+        } else {
+          result.push(item);
+        }
+      }
+      return result;
+    };
+    
+    return flatten(arrayValue);
+  }
+
+  // Handle array wildcard in the middle (e.g., "edges[].from", "items[].meta.id")
+  const arrayWildcardMatch = path.match(/^(.+?)\[\]\.(.+)$/);
+  if (arrayWildcardMatch) {
+    const [, arrayPath, remainingPath] = arrayWildcardMatch;
+    const arrayValue = getByDotPath(value, arrayPath);
+    
+    if (!Array.isArray(arrayValue)) {
+      return [];
+    }
+    
+    // Collect values from all array elements
+    const results: any[] = [];
+    for (const item of arrayValue) {
+      const nestedValues = getByDotPath(item, remainingPath);
+      results.push(...nestedValues);
+    }
+    
+    // Flatten nested arrays recursively
+    const flatten = (arr: any[]): any[] => {
+      const result: any[] = [];
+      for (const item of arr) {
+        if (Array.isArray(item)) {
+          result.push(...flatten(item));
+        } else {
+          result.push(item);
+        }
+      }
+      return result;
+    };
+    
+    return flatten(results);
+  }
+
+  // Handle simple dot-notation path (e.g., "meta.id")
+  const parts = path.split('.');
+  let current: any = value;
+  
+  for (const part of parts) {
+    if (current == null) {
+      return [];
+    }
+    
+    if (Array.isArray(current)) {
+      // If we hit an array in the middle of the path, collect from all elements
+      const results: any[] = [];
+      for (const item of current) {
+        const nestedValue = getByDotPath(item, parts.slice(parts.indexOf(part)).join('.'));
+        results.push(...nestedValue);
+      }
+      return results;
+    }
+    
+    current = current[part];
+  }
+  
+  return current != null ? [current] : [];
+}
+
+/**
+ * Normalizes a value to a string representation for signature computation.
+ * @param value - The value to normalize
+ * @returns Normalized string representation
+ */
+function normalizeValue(value: any): string {
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+  
+  if (typeof value === 'string') {
+    return value;
+  }
+  
+  if (typeof value === 'number') {
+    return String(value);
+  }
+  
+  if (typeof value === 'boolean') {
+    return String(value);
+  }
+  
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  
+  if (Array.isArray(value)) {
+    // Flatten, normalize, deduplicate, and sort
+    const flatten = (arr: any[]): any[] => {
+      const result: any[] = [];
+      for (const item of arr) {
+        if (Array.isArray(item)) {
+          result.push(...flatten(item));
+        } else {
+          result.push(item);
+        }
+      }
+      return result;
+    };
+    
+    const flattened = flatten(value);
+    const normalized = flattened.map(normalizeValue);
+    const unique = Array.from(new Set(normalized));
+    const sorted = unique.sort();
+    return JSON.stringify(sorted);
+  }
+  
+  if (typeof value === 'object') {
+    // Sort keys for consistent stringification
+    const sortedKeys = Object.keys(value).sort();
+    const sortedObj: any = {};
+    for (const key of sortedKeys) {
+      sortedObj[key] = value[key];
+    }
+    return JSON.stringify(sortedObj);
+  }
+  
+  return String(value);
+}
+
+/**
+ * Computes a deterministic signature for a document based on specified keys.
+ * The signature is a SHA-256 hash of a canonical representation of the key values.
+ * @param doc - The document to compute signature for
+ * @param keys - Array of dot-notation paths to extract values from
+ * @param options - Optional configuration
+ * @param options.algorithm - Hash algorithm to use (default: "sha256")
+ * @returns Hex string signature
+ * @example
+ * computeSignature({ segments: [1, 2], role: "admin" }, ["segments[]", "role"])
+ */
+export function computeSignature(
+  doc: any,
+  keys: string[],
+  options?: {
+    algorithm?: 'sha256' | 'sha1' | 'md5';
+  }
+): string {
+  const algorithm = options?.algorithm || 'sha256';
+  
+  // Extract values for each key
+  const canonicalMap: Record<string, any[]> = {};
+  
+  for (const key of keys) {
+    const values = getByDotPath(doc, key);
+    // Normalize and deduplicate values
+    const normalized = values.map(normalizeValue);
+    const unique = Array.from(new Set(normalized));
+    const sorted = unique.sort();
+    canonicalMap[key] = sorted;
+  }
+  
+  // Sort keys alphabetically
+  const sortedKeys = Object.keys(canonicalMap).sort();
+  const sortedMap: Record<string, any[]> = {};
+  for (const key of sortedKeys) {
+    sortedMap[key] = canonicalMap[key];
+  }
+  
+  // Stringify and hash
+  const jsonString = JSON.stringify(sortedMap);
+  const hash = createHash(algorithm);
+  hash.update(jsonString);
+  return hash.digest('hex');
+}
+
+/**
+ * Internal class that implements the ProgressAPI interface for stage tracking.
+ */
+class ProgressAPIImpl implements ProgressAPI {
+  private helper: SimpleMongoHelper;
+  private config: { collection: string; uniqueIndexKeys: string[]; defaultProvider?: string };
+  private indexEnsured: boolean = false;
+
+  constructor(helper: SimpleMongoHelper, progressConfig?: HelperConfig['progress']) {
+    this.helper = helper;
+    this.config = {
+      collection: progressConfig?.collection || 'progress_states',
+      uniqueIndexKeys: progressConfig?.uniqueIndexKeys || ['process', 'provider', 'key'],
+      defaultProvider: progressConfig?.provider,
+    };
+  }
+
+  /**
+   * Ensures the progress collection and unique index exist.
+   * Called lazily on first use.
+   */
+  private async ensureProgressIndex(session?: ClientSession): Promise<void> {
+    if (this.indexEnsured) {
+      return;
+    }
+
+    this.helper.ensureInitialized();
+
+    try {
+      const collection = this.helper.getDb().collection(this.config.collection);
+      const indexes = await collection.indexes();
+      
+      // Build index spec from uniqueIndexKeys
+      const indexSpec: IndexSpecification = {};
+      for (const key of this.config.uniqueIndexKeys) {
+        indexSpec[key] = 1;
+      }
+
+      // Check if index already exists
+      const existingIndex = indexes.find(idx => {
+        const keys = idx.key as Document;
+        const indexKeys = Object.keys(keys).sort();
+        const expectedKeys = Object.keys(indexSpec).sort();
+        return JSON.stringify(indexKeys) === JSON.stringify(expectedKeys);
+      });
+
+      if (!existingIndex) {
+        const indexOptions: CreateIndexesOptions = { unique: true };
+        if (session) {
+          indexOptions.session = session;
+        }
+        await collection.createIndex(indexSpec, indexOptions);
+      }
+
+      this.indexEnsured = true;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (errorMessage.includes('not authorized') || errorMessage.includes('unauthorized')) {
+        throw new Error(
+          `Failed to create progress index on collection '${this.config.collection}': ${errorMessage}. ` +
+          `This operation requires 'createIndex' privilege.`
+        );
+      }
+      throw new Error(`Failed to ensure progress index on collection '${this.config.collection}': ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Resolves the provider value, using options provider, then default provider, then undefined.
+   */
+  private resolveProvider(options?: { provider?: string }): string | undefined {
+    return options?.provider ?? this.config.defaultProvider;
+  }
+
+  /**
+   * Builds a filter for finding a stage record.
+   */
+  private buildFilter(key: string, process?: string, provider?: string): Filter<StageRecord> {
+    const filter: Filter<StageRecord> = { key };
+    if (process !== undefined) {
+      filter.process = process;
+    }
+    if (provider !== undefined) {
+      filter.provider = provider;
+    }
+    return filter;
+  }
+
+  async isCompleted(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<boolean> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider(options);
+    const process = options?.process;
+    const filter = this.buildFilter(key, process, provider);
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+    
+    const findOptions: any = {};
+    if (options?.session) {
+      findOptions.session = options.session;
+    }
+
+    const record = await collection.findOne(filter, findOptions);
+    return record?.completed === true;
+  }
+
+  async start(identity: StageIdentity, options?: ProgressSessionOptions): Promise<void> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider({ provider: identity.provider });
+    const process = identity.process;
+    const filter = this.buildFilter(identity.key, process, provider);
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+
+    const update: UpdateFilter<StageRecord> = {
+      $set: {
+        key: identity.key,
+        name: identity.name,
+        completed: false,
+      },
+      $setOnInsert: {
+        startedAt: new Date(),
+      },
+    };
+
+    if (process !== undefined) {
+      (update.$set as any).process = process;
+    }
+    if (provider !== undefined) {
+      (update.$set as any).provider = provider;
+    }
+
+    const updateOptions: any = { upsert: true };
+    if (options?.session) {
+      updateOptions.session = options.session;
+    }
+
+    await collection.updateOne(filter, update, updateOptions);
+  }
+
+  async complete(
+    identity: StageIdentity & { metadata?: StageMetadata },
+    options?: ProgressSessionOptions
+  ): Promise<void> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider({ provider: identity.provider });
+    const process = identity.process;
+    const filter = this.buildFilter(identity.key, process, provider);
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+
+    const update: UpdateFilter<StageRecord> = {
+      $set: {
+        key: identity.key,
+        completed: true,
+        completedAt: new Date(),
+      },
+    };
+
+    if (identity.name !== undefined) {
+      (update.$set as any).name = identity.name;
+    }
+
+    if (process !== undefined) {
+      (update.$set as any).process = process;
+    }
+    if (provider !== undefined) {
+      (update.$set as any).provider = provider;
+    }
+
+    if (identity.metadata) {
+      // Merge metadata
+      (update.$set as any).metadata = identity.metadata;
+    }
+
+    const updateOptions: any = { upsert: true };
+    if (options?.session) {
+      updateOptions.session = options.session;
+    }
+
+    await collection.updateOne(filter, update, updateOptions);
+  }
+
+  async getCompleted(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<Array<Pick<StageRecord, 'key' | 'name' | 'completedAt'>>> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider(options);
+    const process = options?.process;
+    const filter: Filter<StageRecord> = { completed: true };
+    if (process !== undefined) {
+      filter.process = process;
+    }
+    if (provider !== undefined) {
+      filter.provider = provider;
+    }
+
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+    const findOptions: any = { projection: { key: 1, name: 1, completedAt: 1 } };
+    if (options?.session) {
+      findOptions.session = options.session;
+    }
+
+    const records = await collection.find(filter, findOptions).toArray();
+    return records.map(r => ({
+      key: r.key,
+      name: r.name,
+      completedAt: r.completedAt,
+    }));
+  }
+
+  async getProgress(options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<StageRecord[]> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider(options);
+    const process = options?.process;
+    const filter: Filter<StageRecord> = {};
+    if (process !== undefined) {
+      filter.process = process;
+    }
+    if (provider !== undefined) {
+      filter.provider = provider;
+    }
+
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+    const findOptions: any = {};
+    if (options?.session) {
+      findOptions.session = options.session;
+    }
+
+    return await collection.find(filter, findOptions).toArray();
+  }
+
+  async reset(key: string, options?: ProgressSessionOptions & { process?: string; provider?: string }): Promise<void> {
+    await this.ensureProgressIndex(options?.session);
+    this.helper.ensureInitialized();
+
+    const provider = this.resolveProvider(options);
+    const process = options?.process;
+    const filter = this.buildFilter(key, process, provider);
+    const collection = this.helper.getDb().collection<StageRecord>(this.config.collection);
+
+    const update: UpdateFilter<StageRecord> = {
+      $set: {
+        completed: false,
+      },
+      $unset: {
+        completedAt: '',
+        metadata: '',
+      },
+    };
+
+    const updateOptions: any = {};
+    if (options?.session) {
+      updateOptions.session = options.session;
+    }
+
+    await collection.updateOne(filter, update, updateOptions);
+  }
+}
+
+export class SimpleMongoHelper {
+  private connectionString: string;
+  private client: MongoClient | null = null;
+  protected db: Db | null = null;
+  private isInitialized: boolean = false;
+  private retryOptions: RetryOptions;
+  private config: HelperConfig | null = null;
+  public readonly progress: ProgressAPI;
+
+  constructor(connectionString: string, retryOptions?: RetryOptions, config?: HelperConfig) {
+    this.connectionString = connectionString;
+    this.retryOptions = {
+      maxRetries: retryOptions?.maxRetries ?? 3,
+      retryDelay: retryOptions?.retryDelay ?? 1000,
+      exponentialBackoff: retryOptions?.exponentialBackoff ?? true,
+    };
+    this.config = config || null;
+    this.progress = new ProgressAPIImpl(this, config?.progress);
+  }
+
+  /**
+   * Sets or updates the configuration for ref-based operations.
+   * @param config - Configuration object with inputs and outputs
+   * @returns This instance for method chaining
+   */
+  useConfig(config: HelperConfig): this {
+    this.config = config;
+    return this;
+  }
+
+  /**
+   * Tests the MongoDB connection and returns detailed error information if it fails.
+   * This method does not establish a persistent connection - use initialize() for that.
+   * @returns Object with success status and optional error details
+   */
+  async testConnection(): Promise<{
+    success: boolean;
+    error?: {
+      type: 'missing_credentials' | 'invalid_connection_string' | 'connection_failed' | 'authentication_failed' | 'config_error' | 'unknown';
+      message: string;
+      details?: string;
+    };
+  }> {
+    // Check connection string
+    if (!this.connectionString || this.connectionString.trim() === '') {
+      return {
+        success: false,
+        error: {
+          type: 'invalid_connection_string',
+          message: 'Connection string is missing or empty',
+          details: 'Provide a valid MongoDB connection string in the format: mongodb://[username:password@]host[:port][/database][?options]'
+        }
+      };
+    }
+
+    // Validate connection string format
+    try {
+      const url = new URL(this.connectionString);
+      if (url.protocol !== 'mongodb:' && url.protocol !== 'mongodb+srv:') {
+        return {
+          success: false,
+          error: {
+            type: 'invalid_connection_string',
+            message: 'Invalid connection string protocol',
+            details: `Expected protocol 'mongodb://' or 'mongodb+srv://', got '${url.protocol}'`
+          }
+        };
+      }
+    } catch (urlError) {
+      return {
+        success: false,
+        error: {
+          type: 'invalid_connection_string',
+          message: 'Connection string is not a valid URL',
+          details: `Failed to parse connection string: ${urlError instanceof Error ? urlError.message : String(urlError)}`
+        }
+      };
+    }
+
+    // Check for credentials in connection string
+    const hasCredentials = this.connectionString.includes('@') && 
+                          (this.connectionString.match(/:\/\/[^:]+:[^@]+@/) || 
+                           this.connectionString.match(/:\/\/[^@]+@/));
+    
+    // Try to extract username/password from connection string
+    const authMatch = this.connectionString.match(/:\/\/([^:]+):([^@]+)@/);
+    if (authMatch) {
+      const username = authMatch[1];
+      const password = authMatch[2];
+      if (!username || username.trim() === '') {
+        return {
+          success: false,
+          error: {
+            type: 'missing_credentials',
+            message: 'Username is missing in connection string',
+            details: 'Connection string contains @ but username is empty. Format: mongodb://username:password@host:port/database'
+          }
+        };
+      }
+      if (!password || password.trim() === '') {
+        return {
+          success: false,
+          error: {
+            type: 'missing_credentials',
+            message: 'Password is missing in connection string',
+            details: 'Connection string contains @ but password is empty. Format: mongodb://username:password@host:port/database'
+          }
+        };
+      }
+    } else if (this.connectionString.includes('@')) {
+      // Has @ but no password format - might be using connection string options
+      // This is okay, continue to connection test
+    }
+
+    // Test actual connection
+    let testClient: MongoClient | null = null;
+    try {
+      testClient = new MongoClient(this.connectionString, {
+        serverSelectionTimeoutMS: 5000, // 5 second timeout for test
+        connectTimeoutMS: 5000
+      });
+      
+      await testClient.connect();
+      
+      // Try to ping the server
+      const dbName = this.extractDatabaseName(this.connectionString);
+      const testDb = testClient.db(dbName);
+      await testDb.admin().ping();
+      
+      // Test basic operation (list collections)
+      try {
+        await testDb.listCollections().toArray();
+      } catch (listError) {
+        // If listCollections fails, might be permission issue but connection works
+        const errorMsg = listError instanceof Error ? listError.message : String(listError);
+        if (errorMsg.includes('not authorized') || errorMsg.includes('unauthorized')) {
+          await testClient.close();
+          return {
+            success: false,
+            error: {
+              type: 'authentication_failed',
+              message: 'Connection successful but insufficient permissions',
+              details: `Connected to MongoDB but cannot list collections. Error: ${errorMsg}. Check user permissions.`
+            }
+          };
+        }
+      }
+      
+      await testClient.close();
+      return { success: true };
+      
+    } catch (error) {
+      if (testClient) {
+        try {
+          await testClient.close();
+        } catch {
+          // Ignore close errors
+        }
+      }
+      
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorString = String(error).toLowerCase();
+      
+      // Analyze error type
+      if (errorString.includes('authentication failed') || 
+          errorString.includes('auth failed') ||
+          errorString.includes('invalid credentials') ||
+          errorMessage.includes('Authentication failed')) {
+        return {
+          success: false,
+          error: {
+            type: 'authentication_failed',
+            message: 'Authentication failed',
+            details: `Invalid username or password. Error: ${errorMessage}. Verify credentials in connection string.`
+          }
+        };
+      }
+      
+      if (errorString.includes('timeout') || 
+          errorMessage.includes('timeout') ||
+          errorMessage.includes('ETIMEDOUT')) {
+        return {
+          success: false,
+          error: {
+            type: 'connection_failed',
+            message: 'Connection timeout',
+            details: `Cannot reach MongoDB server. Error: ${errorMessage}. Check if server is running, host/port is correct, and firewall allows connections.`
+          }
+        };
+      }
+      
+      if (errorString.includes('dns') || 
+          errorMessage.includes('ENOTFOUND') ||
+          errorMessage.includes('getaddrinfo')) {
+        return {
+          success: false,
+          error: {
+            type: 'connection_failed',
+            message: 'DNS resolution failed',
+            details: `Cannot resolve hostname. Error: ${errorMessage}. Check if hostname is correct and DNS is configured properly.`
+          }
+        };
+      }
+      
+      if (errorString.includes('refused') || 
+          errorMessage.includes('ECONNREFUSED')) {
+        return {
+          success: false,
+          error: {
+            type: 'connection_failed',
+            message: 'Connection refused',
+            details: `MongoDB server refused connection. Error: ${errorMessage}. Check if MongoDB is running on the specified host and port.`
+          }
+        };
+      }
+      
+      if (errorString.includes('network') || 
+          errorMessage.includes('network')) {
+        return {
+          success: false,
+          error: {
+            type: 'connection_failed',
+            message: 'Network error',
+            details: `Network connectivity issue. Error: ${errorMessage}. Check network connection and firewall settings.`
+          }
+        };
+      }
+      
+      // Generic connection error
+      return {
+        success: false,
+        error: {
+          type: 'connection_failed',
+          message: 'Connection failed',
+          details: `Failed to connect to MongoDB. Error: ${errorMessage}. Verify connection string, server status, and network connectivity.`
+        }
+      };
+    }
+  }
+
+  /**
+   * Establishes MongoDB connection internally with retry logic.
+   * Must be called before using other methods.
+   * @throws Error if connection fails or if already initialized
+   */
+  async initialize(): Promise<void> {
+    if (this.isInitialized) {
+      throw new Error('SimpleMongoHelper is already initialized');
+    }
+
+    let lastError: Error | null = null;
+    for (let attempt = 0; attempt <= this.retryOptions.maxRetries!; attempt++) {
+      try {
+        this.client = new MongoClient(this.connectionString);
+        await this.client.connect();
+        // Extract database name from connection string or use default
+        const dbName = this.extractDatabaseName(this.connectionString);
+        this.db = this.client.db(dbName);
+        this.isInitialized = true;
+        return;
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        this.client = null;
+        this.db = null;
+        
+        if (attempt < this.retryOptions.maxRetries!) {
+          const delay = this.retryOptions.exponentialBackoff
+            ? this.retryOptions.retryDelay! * Math.pow(2, attempt)
+            : this.retryOptions.retryDelay!;
+          await new Promise(resolve => setTimeout(resolve, delay));
+        }
+      }
+    }
+    
+    throw new Error(`Failed to initialize MongoDB connection after ${this.retryOptions.maxRetries! + 1} attempts: ${lastError?.message}`);
+  }
+
+  /**
+   * Loads data from a collection with optional query filter.
+   * @param collectionName - Name of the collection to query
+   * @param query - Optional MongoDB query filter
+   * @param options - Optional pagination and sorting options
+   * @returns Array of documents matching the query or paginated result
+   * @throws Error if not initialized or if query fails
+   */
+  async loadCollection<T extends Document = Document>(
+    collectionName: string, 
+    query?: Filter<T>,
+    options?: PaginationOptions
+  ): Promise<WithId<T>[] | PaginatedResult<T>> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const filter = query || {};
+      let cursor = collection.find(filter);
+
+      // Apply sorting if provided
+      if (options?.sort) {
+        cursor = cursor.sort(options.sort);
+      }
+
+      // Apply pagination if provided
+      if (options?.page && options?.limit) {
+        const page = Math.max(1, options.page);
+        const limit = Math.max(1, options.limit);
+        const skip = (page - 1) * limit;
+
+        cursor = cursor.skip(skip).limit(limit);
+        
+        // Get total count for pagination
+        const total = await collection.countDocuments(filter);
+        const results = await cursor.toArray();
+        const totalPages = Math.ceil(total / limit);
+
+        return {
+          data: results,
+          total,
+          page,
+          limit,
+          totalPages,
+          hasNext: page < totalPages,
+          hasPrev: page > 1,
+        };
+      }
+
+      // Return all results if no pagination
+      const results = await cursor.toArray();
+      return results;
+    } catch (error) {
+      throw new Error(`Failed to load collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Finds a single document in a collection.
+   * @param collectionName - Name of the collection to query
+   * @param query - MongoDB query filter
+   * @param options - Optional find options (e.g., sort, projection)
+   * @returns Single document matching the query or null
+   * @throws Error if not initialized or if query fails
+   */
+  async findOne<T extends Document = Document>(
+    collectionName: string,
+    query: Filter<T>,
+    options?: { sort?: Sort; projection?: Document }
+  ): Promise<WithId<T> | null> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      let findOptions: any = {};
+      
+      if (options?.sort) {
+        findOptions.sort = options.sort;
+      }
+      if (options?.projection) {
+        findOptions.projection = options.projection;
+      }
+
+      const result = await collection.findOne(query, findOptions);
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to find document in collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Inserts data into a collection.
+   * @param collectionName - Name of the collection to insert into
+   * @param data - Single document or array of documents to insert
+   * @param options - Optional insert options (e.g., session for transactions)
+   * @returns Insert result(s)
+   * @throws Error if not initialized or if insert fails
+   */
+  async insert<T extends Document = Document>(
+    collectionName: string, 
+    data: OptionalUnlessRequiredId<T> | OptionalUnlessRequiredId<T>[],
+    options?: { session?: ClientSession }
+  ): Promise<any> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const insertOptions = options?.session ? { session: options.session } : {};
+      
+      if (Array.isArray(data)) {
+        const result = await collection.insertMany(data as OptionalUnlessRequiredId<T>[], insertOptions);
+        return result;
+      } else {
+        const result = await collection.insertOne(data as OptionalUnlessRequiredId<T>, insertOptions);
+        return result;
+      }
+    } catch (error) {
+      throw new Error(`Failed to insert into collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Updates records in a collection.
+   * @param collectionName - Name of the collection to update
+   * @param filter - MongoDB query filter to match documents
+   * @param updateData - Update operations to apply
+   * @param options - Optional update options (e.g., upsert, multi, session for transactions)
+   * @returns Update result
+   * @throws Error if not initialized or if update fails
+   */
+  async update<T extends Document = Document>(
+    collectionName: string,
+    filter: Filter<T>,
+    updateData: UpdateFilter<T>,
+    options?: { upsert?: boolean; multi?: boolean; session?: ClientSession }
+  ): Promise<any> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const updateOptions: any = {};
+      if (options?.upsert !== undefined) updateOptions.upsert = options.upsert;
+      if (options?.session) updateOptions.session = options.session;
+      
+      if (options?.multi) {
+        const result = await collection.updateMany(filter, updateData, updateOptions);
+        return result;
+      } else {
+        const result = await collection.updateOne(filter, updateData, updateOptions);
+        return result;
+      }
+    } catch (error) {
+      throw new Error(`Failed to update collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Deletes documents from a collection.
+   * @param collectionName - Name of the collection to delete from
+   * @param filter - MongoDB query filter to match documents
+   * @param options - Optional delete options (multi: true for deleteMany, false for deleteOne)
+   * @returns Delete result
+   * @throws Error if not initialized or if delete fails
+   */
+  async delete<T extends Document = Document>(
+    collectionName: string,
+    filter: Filter<T>,
+    options?: { multi?: boolean }
+  ): Promise<any> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      
+      if (options?.multi) {
+        const result = await collection.deleteMany(filter);
+        return result;
+      } else {
+        const result = await collection.deleteOne(filter);
+        return result;
+      }
+    } catch (error) {
+      throw new Error(`Failed to delete from collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Counts documents in a collection matching a query.
+   * @param collectionName - Name of the collection to count
+   * @param query - Optional MongoDB query filter
+   * @returns Number of documents matching the query
+   * @throws Error if not initialized or if count fails
+   */
+  async countDocuments<T extends Document = Document>(
+    collectionName: string,
+    query?: Filter<T>
+  ): Promise<number> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const count = await collection.countDocuments(query || {});
+      return count;
+    } catch (error) {
+      throw new Error(`Failed to count documents in collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Gets an estimated document count for a collection (faster but less accurate).
+   * @param collectionName - Name of the collection to count
+   * @returns Estimated number of documents
+   * @throws Error if not initialized or if count fails
+   */
+  async estimatedDocumentCount(collectionName: string): Promise<number> {
+    this.ensureInitialized();
+
+    try {
+      const collection = this.db!.collection(collectionName);
+      const count = await collection.estimatedDocumentCount();
+      return count;
+    } catch (error) {
+      throw new Error(`Failed to estimate document count in collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Runs an aggregation pipeline on a collection.
+   * @param collectionName - Name of the collection to aggregate
+   * @param pipeline - Array of aggregation pipeline stages
+   * @returns Array of aggregated results
+   * @throws Error if not initialized or if aggregation fails
+   */
+  async aggregate<T extends Document = Document>(
+    collectionName: string,
+    pipeline: Document[]
+  ): Promise<T[]> {
+    this.ensureInitialized();
+
+    try {
+      const collection: Collection<T> = this.db!.collection<T>(collectionName);
+      const results = await collection.aggregate<T>(pipeline).toArray();
+      return results;
+    } catch (error) {
+      throw new Error(`Failed to aggregate collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Creates an index on a collection.
+   * @param collectionName - Name of the collection
+   * @param indexSpec - Index specification (field name or index spec object)
+   * @param options - Optional index creation options
+   * @returns Index name
+   * @throws Error if not initialized or if index creation fails
+   */
+  async createIndex(
+    collectionName: string,
+    indexSpec: IndexSpecification,
+    options?: CreateIndexesOptions
+  ): Promise<string> {
+    this.ensureInitialized();
+
+    try {
+      const collection = this.db!.collection(collectionName);
+      const indexName = await collection.createIndex(indexSpec, options);
+      return indexName;
+    } catch (error) {
+      throw new Error(`Failed to create index on collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Drops an index from a collection.
+   * @param collectionName - Name of the collection
+   * @param indexName - Name of the index to drop
+   * @returns Result object
+   * @throws Error if not initialized or if index drop fails
+   */
+  async dropIndex(collectionName: string, indexName: string): Promise<any> {
+    this.ensureInitialized();
+
+    try {
+      const collection = this.db!.collection(collectionName);
+      const result = await collection.dropIndex(indexName);
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to drop index '${indexName}' from collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Lists all indexes on a collection.
+   * @param collectionName - Name of the collection
+   * @returns Array of index information
+   * @throws Error if not initialized or if listing fails
+   */
+  async listIndexes(collectionName: string): Promise<Document[]> {
+    this.ensureInitialized();
+
+    try {
+      const collection = this.db!.collection(collectionName);
+      const indexes = await collection.indexes();
+      return indexes;
+    } catch (error) {
+      throw new Error(`Failed to list indexes for collection '${collectionName}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Starts a new client session for transactions.
+   * @returns Client session
+   * @throws Error if not initialized
+   */
+  startSession(): ClientSession {
+    this.ensureInitialized();
+    
+    if (!this.client) {
+      throw new Error('MongoDB client is not available');
+    }
+    
+    return this.client.startSession();
+  }
+
+  /**
+   * Executes a function within a transaction.
+   * @param callback - Function to execute within the transaction
+   * @returns Result of the callback function
+   * @throws Error if not initialized or if transaction fails
+   */
+  async withTransaction<T>(
+    callback: (session: ClientSession) => Promise<T>
+  ): Promise<T> {
+    this.ensureInitialized();
+    
+    if (!this.client) {
+      throw new Error('MongoDB client is not available');
+    }
+
+    const session = this.client.startSession();
+    
+    try {
+      let result: T;
+      await session.withTransaction(async () => {
+        result = await callback(session);
+      });
+      return result!;
+    } catch (error) {
+      throw new Error(`Transaction failed: ${error instanceof Error ? error.message : String(error)}`);
+    } finally {
+      await session.endSession();
+    }
+  }
+
+  /**
+   * Loads data from a collection using a ref name from the configuration.
+   * @param ref - Application-level reference name (must exist in config.inputs)
+   * @param options - Optional pagination and session options
+   * @returns Array of documents or paginated result
+   * @throws Error if ref not found in config, not initialized, or query fails
+   */
+  async loadByRef<T extends Document = Document>(
+    ref: string,
+    options?: PaginationOptions & { session?: ClientSession }
+  ): Promise<WithId<T>[] | PaginatedResult<T>> {
+    this.ensureInitialized();
+    
+    if (!this.config) {
+      throw new Error('Configuration is required for loadByRef. Set config using constructor or useConfig().');
+    }
+    
+    const inputConfig = this.config.inputs.find(input => input.ref === ref);
+    if (!inputConfig) {
+      throw new Error(`Ref '${ref}' not found in configuration inputs.`);
+    }
+    
+    // Note: loadCollection doesn't support session yet, but we'll pass it through options
+    // For now, we'll use the collection directly with session support
+    const collection: Collection<T> = this.db!.collection<T>(inputConfig.collection);
+    const filter = inputConfig.query || {};
+    const session = options?.session;
+    
+    try {
+      const findOptions: any = {};
+      if (session) {
+        findOptions.session = session;
+      }
+      
+      let cursor = collection.find(filter, findOptions);
+      
+      // Apply sorting if provided
+      if (options?.sort) {
+        cursor = cursor.sort(options.sort);
+      }
+      
+      // Apply pagination if provided
+      if (options?.page && options?.limit) {
+        const page = Math.max(1, options.page);
+        const limit = Math.max(1, options.limit);
+        const skip = (page - 1) * limit;
+        
+        cursor = cursor.skip(skip).limit(limit);
+        
+        // Get total count for pagination
+        const countOptions = session ? { session } : {};
+        const total = await collection.countDocuments(filter, countOptions);
+        const results = await cursor.toArray();
+        const totalPages = Math.ceil(total / limit);
+        
+        return {
+          data: results,
+          total,
+          page,
+          limit,
+          totalPages,
+          hasNext: page < totalPages,
+          hasPrev: page > 1,
+        };
+      }
+      
+      // Return all results if no pagination
+      const results = await cursor.toArray();
+      return results;
+    } catch (error) {
+      throw new Error(`Failed to load by ref '${ref}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Ensures a unique index exists on the _sig field for signature-based deduplication.
+   * @param collectionName - Name of the collection
+   * @param options - Optional configuration
+   * @param options.fieldName - Field name for signature (default: "_sig")
+   * @param options.unique - Whether index should be unique (default: true)
+   * @returns Result object with creation status and index name
+   * @throws Error if not initialized or if index creation fails (with permission hints)
+   */
+  async ensureSignatureIndex(
+    collectionName: string,
+    options?: {
+      fieldName?: string;
+      unique?: boolean;
+    }
+  ): Promise<EnsureSignatureIndexResult> {
+    this.ensureInitialized();
+    
+    const fieldName = options?.fieldName || '_sig';
+    const unique = options?.unique !== false; // Default to true
+    
+    try {
+      const collection = this.db!.collection(collectionName);
+      const indexes = await collection.indexes();
+      
+      // Find existing index on the signature field
+      const existingIndex = indexes.find(idx => {
+        const keys = idx.key as Document;
+        return keys[fieldName] !== undefined;
+      });
+      
+      // Check if existing index has correct options
+      if (existingIndex && existingIndex.name) {
+        const isUnique = existingIndex.unique === unique;
+        if (isUnique) {
+          // Index exists with correct options
+          return {
+            created: false,
+            indexName: existingIndex.name,
+          };
+        } else {
+          // Index exists but with wrong options - drop and recreate
+          try {
+            await collection.dropIndex(existingIndex.name);
+          } catch (dropError) {
+            // Ignore drop errors (index might not exist)
+          }
+        }
+      }
+      
+      // Create the index
+      const indexSpec: IndexSpecification = { [fieldName]: 1 };
+      const indexOptions: CreateIndexesOptions = { unique };
+      const indexName = await collection.createIndex(indexSpec, indexOptions);
+      
+      return {
+        created: true,
+        indexName,
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      if (errorMessage.includes('not authorized') || errorMessage.includes('unauthorized')) {
+        throw new Error(
+          `Failed to create signature index on collection '${collectionName}': ${errorMessage}. ` +
+          `This operation requires 'createIndex' privilege.`
+        );
+      }
+      throw new Error(`Failed to ensure signature index on collection '${collectionName}': ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Writes documents to a collection using a ref name from the configuration.
+   * Supports signature-based deduplication and append/replace modes.
+   * @param ref - Application-level reference name (must exist in config.outputs)
+   * @param documents - Array of documents to write
+   * @param options - Optional write options
+   * @param options.session - Transaction session
+   * @param options.ensureIndex - Whether to ensure signature index exists (default: true)
+   * @returns Result object with counts and errors
+   * @throws Error if ref not found in config or not initialized
+   */
+  async writeByRef(
+    ref: string,
+    documents: any[],
+    options?: {
+      session?: ClientSession;
+      ensureIndex?: boolean;
+    }
+  ): Promise<WriteByRefResult> {
+    this.ensureInitialized();
+    
+    if (!this.config) {
+      throw new Error('Configuration is required for writeByRef. Set config using constructor or useConfig().');
+    }
+    
+    const outputConfig = this.config.outputs.find(output => output.ref === ref);
+    if (!outputConfig) {
+      throw new Error(`Ref '${ref}' not found in configuration outputs.`);
+    }
+    
+    const collectionName = outputConfig.collection;
+    const keys = outputConfig.keys;
+    const mode = outputConfig.mode || this.config.output?.mode || 'append';
+    const ensureIndex = options?.ensureIndex !== false; // Default to true
+    const session = options?.session;
+    
+    const result: WriteByRefResult = {
+      inserted: 0,
+      updated: 0,
+      errors: [],
+      indexCreated: false,
+    };
+    
+    try {
+      const collection = this.db!.collection(collectionName);
+      
+      // Handle replace mode: clear collection first
+      if (mode === 'replace') {
+        const deleteOptions = session ? { session } : {};
+        await collection.deleteMany({}, deleteOptions);
+      }
+      
+      // If no keys specified, use regular insertMany
+      if (!keys || keys.length === 0) {
+        try {
+          const insertOptions = session ? { session, ordered: false } : { ordered: false };
+          const insertResult = await collection.insertMany(documents, insertOptions);
+          result.inserted = insertResult.insertedCount;
+        } catch (error) {
+          // Aggregate errors from insertMany
+          if (error && typeof error === 'object' && 'writeErrors' in error) {
+            const writeErrors = (error as any).writeErrors || [];
+            for (const writeError of writeErrors) {
+              result.errors.push({
+                index: writeError.index,
+                error: new Error(writeError.errmsg || String(writeError.err)),
+                doc: documents[writeError.index],
+              });
+            }
+            result.inserted = (error as any).insertedCount || 0;
+          } else {
+            // Single error
+            result.errors.push({
+              index: 0,
+              error: error instanceof Error ? error : new Error(String(error)),
+            });
+          }
+        }
+        return result;
+      }
+      
+      // Ensure signature index exists
+      if (ensureIndex) {
+        try {
+          const indexResult = await this.ensureSignatureIndex(collectionName, {
+            fieldName: '_sig',
+            unique: true,
+          });
+          result.indexCreated = indexResult.created;
+        } catch (indexError) {
+          result.errors.push({
+            index: -1,
+            error: indexError instanceof Error ? indexError : new Error(String(indexError)),
+          });
+          // Continue even if index creation fails
+        }
+      }
+      
+      // Compute signatures and prepare bulk operations
+      const bulkOps: any[] = [];
+      const docWithSigs: Array<{ doc: any; sig: string }> = [];
+      
+      for (const doc of documents) {
+        try {
+          const sig = computeSignature(doc, keys);
+          docWithSigs.push({ doc, sig });
+          
+          // Add _sig field to document
+          const docWithSig = { ...doc, _sig: sig };
+          
+          bulkOps.push({
+            updateOne: {
+              filter: { _sig: sig },
+              update: { $set: docWithSig },
+              upsert: true,
+            },
+          });
+        } catch (error) {
+          result.errors.push({
+            index: docWithSigs.length,
+            error: error instanceof Error ? error : new Error(String(error)),
+            doc,
+          });
+        }
+      }
+      
+      // Process in batches of 1000
+      const batchSize = 1000;
+      for (let i = 0; i < bulkOps.length; i += batchSize) {
+        const batch = bulkOps.slice(i, i + batchSize);
+        
+        try {
+          const bulkOptions: any = { ordered: false };
+          if (session) {
+            bulkOptions.session = session;
+          }
+          
+          const bulkResult = await collection.bulkWrite(batch, bulkOptions);
+          
+          result.inserted += bulkResult.upsertedCount || 0;
+          result.updated += bulkResult.modifiedCount || 0;
+          
+          // Handle write errors
+          if (bulkResult.hasWriteErrors()) {
+            const writeErrors = bulkResult.getWriteErrors();
+            for (const writeError of writeErrors) {
+              const originalIndex = i + writeError.index;
+              result.errors.push({
+                index: originalIndex,
+                error: new Error(writeError.errmsg || String(writeError.err)),
+                doc: documents[originalIndex],
+              });
+            }
+          }
+        } catch (error) {
+          // Aggregate batch errors
+          if (error && typeof error === 'object' && 'writeErrors' in error) {
+            const writeErrors = (error as any).writeErrors || [];
+            for (const writeError of writeErrors) {
+              const originalIndex = i + writeError.index;
+              result.errors.push({
+                index: originalIndex,
+                error: new Error(writeError.errmsg || String(writeError.err)),
+                doc: documents[originalIndex],
+              });
+            }
+            result.inserted += (error as any).upsertedCount || 0;
+            result.updated += (error as any).modifiedCount || 0;
+          } else {
+            // Batch-level error - mark all documents in batch as errors
+            for (let j = 0; j < batch.length; j++) {
+              result.errors.push({
+                index: i + j,
+                error: error instanceof Error ? error : new Error(String(error)),
+                doc: documents[i + j],
+              });
+            }
+          }
+        }
+      }
+      
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to write by ref '${ref}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Writes documents to a collection using a ref name and optionally marks a stage as complete.
+   * Combines writeByRef() with progress.complete() for atomic write-and-complete operations.
+   * @param ref - Application-level reference name (must exist in config.outputs)
+   * @param documents - Array of documents to write
+   * @param options - Optional write and completion options
+   * @param options.ensureIndex - Whether to ensure signature index exists (default: true)
+   * @param options.session - Transaction session (if provided, write and complete are atomic)
+   * @param options.complete - Stage completion information (optional)
+   * @returns Result object with write counts, errors, and completion status
+   * @throws Error if ref not found in config or not initialized
+   */
+  async writeStage(
+    ref: string,
+    documents: any[],
+    options?: WriteStageOptions
+  ): Promise<WriteStageResult> {
+    this.ensureInitialized();
+
+    // Write documents using existing writeByRef method
+    const writeResult = await this.writeByRef(ref, documents, {
+      session: options?.session,
+      ensureIndex: options?.ensureIndex,
+    });
+
+    const result: WriteStageResult = {
+      ...writeResult,
+      completed: false,
+    };
+
+    // If complete option is provided, mark stage as complete
+    if (options?.complete) {
+      try {
+        await this.progress.complete(
+          {
+            key: options.complete.key,
+            process: options.complete.process,
+            name: options.complete.name,
+            provider: options.complete.provider,
+            metadata: options.complete.metadata,
+          },
+          { session: options.session }
+        );
+        result.completed = true;
+      } catch (error) {
+        // If completion fails, still return write result but indicate completion failed
+        // Don't throw - let caller decide how to handle partial success
+        result.completed = false;
+        // Could add a completionError field if needed, but keeping it simple for now
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Closes the MongoDB connection and cleans up resources.
+   * @throws Error if disconnect fails
+   */
+  async disconnect(): Promise<void> {
+    if (!this.isInitialized || !this.client) {
+      return;
+    }
+
+    try {
+      await this.client.close();
+      this.client = null;
+      this.db = null;
+      this.isInitialized = false;
+    } catch (error) {
+      throw new Error(`Failed to disconnect: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  /**
+   * Ensures the helper is initialized before performing operations.
+   * @throws Error if not initialized
+   * @internal
+   */
+  public ensureInitialized(): void {
+    if (!this.isInitialized || !this.client || !this.db) {
+      throw new Error('SimpleMongoHelper must be initialized before use. Call initialize() first.');
+    }
+  }
+
+  /**
+   * Gets the database instance. Public for use by internal classes.
+   * @internal
+   */
+  public getDb(): Db {
+    if (!this.db) {
+      throw new Error('Database is not initialized. Call initialize() first.');
+    }
+    return this.db;
+  }
+
+  /**
+   * Extracts database name from MongoDB connection string.
+   * @param connectionString - MongoDB connection string
+   * @returns Database name or 'test' as default
+   */
+  private extractDatabaseName(connectionString: string): string {
+    try {
+      const url = new URL(connectionString);
+      const dbName = url.pathname.slice(1); // Remove leading '/'
+      return dbName || 'test';
+    } catch {
+      // If URL parsing fails, try to extract from connection string pattern
+      const match = connectionString.match(/\/([^\/\?]+)(\?|$)/);
+      return match ? match[1] : 'test';
+    }
+  }
+}
+