nx-mongo 3.3.0

package/dist/simpleMongoHelper.js

@@ -0,0 +1,1333 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SimpleMongoHelper = void 0;
+exports.getByDotPath = getByDotPath;
+exports.computeSignature = computeSignature;
+const mongodb_1 = require("mongodb");
+const crypto_1 = require("crypto");
+/**
+ * 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"]
+ */
+function getByDotPath(value, path) {
+    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) => {
+            const result = [];
+            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 = [];
+        for (const item of arrayValue) {
+            const nestedValues = getByDotPath(item, remainingPath);
+            results.push(...nestedValues);
+        }
+        // Flatten nested arrays recursively
+        const flatten = (arr) => {
+            const result = [];
+            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 = 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 = [];
+            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) {
+    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) => {
+            const result = [];
+            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 = {};
+        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"])
+ */
+function computeSignature(doc, keys, options) {
+    const algorithm = options?.algorithm || 'sha256';
+    // Extract values for each key
+    const canonicalMap = {};
+    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 = {};
+    for (const key of sortedKeys) {
+        sortedMap[key] = canonicalMap[key];
+    }
+    // Stringify and hash
+    const jsonString = JSON.stringify(sortedMap);
+    const hash = (0, crypto_1.createHash)(algorithm);
+    hash.update(jsonString);
+    return hash.digest('hex');
+}
+/**
+ * Internal class that implements the ProgressAPI interface for stage tracking.
+ */
+class ProgressAPIImpl {
+    constructor(helper, progressConfig) {
+        this.indexEnsured = false;
+        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.
+     */
+    async ensureProgressIndex(session) {
+        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 = {};
+            for (const key of this.config.uniqueIndexKeys) {
+                indexSpec[key] = 1;
+            }
+            // Check if index already exists
+            const existingIndex = indexes.find(idx => {
+                const keys = idx.key;
+                const indexKeys = Object.keys(keys).sort();
+                const expectedKeys = Object.keys(indexSpec).sort();
+                return JSON.stringify(indexKeys) === JSON.stringify(expectedKeys);
+            });
+            if (!existingIndex) {
+                const indexOptions = { 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.
+     */
+    resolveProvider(options) {
+        return options?.provider ?? this.config.defaultProvider;
+    }
+    /**
+     * Builds a filter for finding a stage record.
+     */
+    buildFilter(key, process, provider) {
+        const filter = { key };
+        if (process !== undefined) {
+            filter.process = process;
+        }
+        if (provider !== undefined) {
+            filter.provider = provider;
+        }
+        return filter;
+    }
+    async isCompleted(key, options) {
+        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(this.config.collection);
+        const findOptions = {};
+        if (options?.session) {
+            findOptions.session = options.session;
+        }
+        const record = await collection.findOne(filter, findOptions);
+        return record?.completed === true;
+    }
+    async start(identity, options) {
+        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(this.config.collection);
+        const update = {
+            $set: {
+                key: identity.key,
+                name: identity.name,
+                completed: false,
+            },
+            $setOnInsert: {
+                startedAt: new Date(),
+            },
+        };
+        if (process !== undefined) {
+            update.$set.process = process;
+        }
+        if (provider !== undefined) {
+            update.$set.provider = provider;
+        }
+        const updateOptions = { upsert: true };
+        if (options?.session) {
+            updateOptions.session = options.session;
+        }
+        await collection.updateOne(filter, update, updateOptions);
+    }
+    async complete(identity, options) {
+        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(this.config.collection);
+        const update = {
+            $set: {
+                key: identity.key,
+                completed: true,
+                completedAt: new Date(),
+            },
+        };
+        if (identity.name !== undefined) {
+            update.$set.name = identity.name;
+        }
+        if (process !== undefined) {
+            update.$set.process = process;
+        }
+        if (provider !== undefined) {
+            update.$set.provider = provider;
+        }
+        if (identity.metadata) {
+            // Merge metadata
+            update.$set.metadata = identity.metadata;
+        }
+        const updateOptions = { upsert: true };
+        if (options?.session) {
+            updateOptions.session = options.session;
+        }
+        await collection.updateOne(filter, update, updateOptions);
+    }
+    async getCompleted(options) {
+        await this.ensureProgressIndex(options?.session);
+        this.helper.ensureInitialized();
+        const provider = this.resolveProvider(options);
+        const process = options?.process;
+        const filter = { completed: true };
+        if (process !== undefined) {
+            filter.process = process;
+        }
+        if (provider !== undefined) {
+            filter.provider = provider;
+        }
+        const collection = this.helper.getDb().collection(this.config.collection);
+        const findOptions = { 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) {
+        await this.ensureProgressIndex(options?.session);
+        this.helper.ensureInitialized();
+        const provider = this.resolveProvider(options);
+        const process = options?.process;
+        const filter = {};
+        if (process !== undefined) {
+            filter.process = process;
+        }
+        if (provider !== undefined) {
+            filter.provider = provider;
+        }
+        const collection = this.helper.getDb().collection(this.config.collection);
+        const findOptions = {};
+        if (options?.session) {
+            findOptions.session = options.session;
+        }
+        return await collection.find(filter, findOptions).toArray();
+    }
+    async reset(key, options) {
+        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(this.config.collection);
+        const update = {
+            $set: {
+                completed: false,
+            },
+            $unset: {
+                completedAt: '',
+                metadata: '',
+            },
+        };
+        const updateOptions = {};
+        if (options?.session) {
+            updateOptions.session = options.session;
+        }
+        await collection.updateOne(filter, update, updateOptions);
+    }
+}
+class SimpleMongoHelper {
+    constructor(connectionString, retryOptions, config) {
+        this.client = null;
+        this.db = null;
+        this.isInitialized = false;
+        this.config = null;
+        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) {
+        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() {
+        // 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 = null;
+        try {
+            testClient = new mongodb_1.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() {
+        if (this.isInitialized) {
+            throw new Error('SimpleMongoHelper is already initialized');
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= this.retryOptions.maxRetries; attempt++) {
+            try {
+                this.client = new mongodb_1.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(collectionName, query, options) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(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(collectionName, query, options) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(collectionName);
+            let findOptions = {};
+            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(collectionName, data, options) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(collectionName);
+            const insertOptions = options?.session ? { session: options.session } : {};
+            if (Array.isArray(data)) {
+                const result = await collection.insertMany(data, insertOptions);
+                return result;
+            }
+            else {
+                const result = await collection.insertOne(data, 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(collectionName, filter, updateData, options) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(collectionName);
+            const updateOptions = {};
+            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(collectionName, filter, options) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(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(collectionName, query) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(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) {
+        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(collectionName, pipeline) {
+        this.ensureInitialized();
+        try {
+            const collection = this.db.collection(collectionName);
+            const results = await collection.aggregate(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, indexSpec, options) {
+        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, indexName) {
+        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) {
+        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() {
+        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(callback) {
+        this.ensureInitialized();
+        if (!this.client) {
+            throw new Error('MongoDB client is not available');
+        }
+        const session = this.client.startSession();
+        try {
+            let result;
+            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(ref, options) {
+        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 = this.db.collection(inputConfig.collection);
+        const filter = inputConfig.query || {};
+        const session = options?.session;
+        try {
+            const findOptions = {};
+            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, options) {
+        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;
+                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 = { [fieldName]: 1 };
+            const indexOptions = { 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, documents, options) {
+        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 = {
+            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.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.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 = [];
+            const docWithSigs = [];
+            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 = { 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.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.upsertedCount || 0;
+                        result.updated += error.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, documents, options) {
+        this.ensureInitialized();
+        // Write documents using existing writeByRef method
+        const writeResult = await this.writeByRef(ref, documents, {
+            session: options?.session,
+            ensureIndex: options?.ensureIndex,
+        });
+        const result = {
+            ...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() {
+        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
+     */
+    ensureInitialized() {
+        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
+     */
+    getDb() {
+        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
+     */
+    extractDatabaseName(connectionString) {
+        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';
+        }
+    }
+}
+exports.SimpleMongoHelper = SimpleMongoHelper;
+//# sourceMappingURL=simpleMongoHelper.js.map