/**
 * Helper functions for updating cache entries
 *
 * @module cache-update-helper
 */
import { CachedData } from '../types/cache';
import { ArtifactStatusUpdate } from '../types/cache';
/**
 * Updates an artifact's status in a cache entry
 * Handles various cache formats (Array, OData-Format, etc.)
 *
 * @param cachedData - The cached data to update
 * @param artifactId - The ID of the artifact to update
 * @param statusData - The status data to apply
 * @returns Updated cached data, or null if artifact not found
 *
 * @example
 * const updated = updateArtifactInCache(cachedData, 'MyArtifact', {
 *   Status: 'STARTED',
 *   DeployedBy: 'user@example.com',
 *   DeployedOn: '2024-01-01T00:00:00Z'
 * });
 */
export declare function updateArtifactInCache(cachedData: CachedData, artifactId: string, statusData: ArtifactStatusUpdate): CachedData | null;
/**
 * Updates an artifact's status in a package cache entry
 * Finds the artifact in the package's artifact arrays and updates it
 *
 * @param cachedData - The cached package data to update
 * @param artifactId - The ID of the artifact to update
 * @param statusData - The status data to apply
 * @returns Updated cached data, or null if artifact not found
 *
 * @example
 * const updated = updateArtifactInPackageCache(cachedData, 'MyArtifact', {
 *   Status: 'STARTED'
 * });
 */
export declare function updateArtifactInPackageCache(cachedData: CachedData, artifactId: string, statusData: ArtifactStatusUpdate): CachedData | null;
/**
 * Gets a nested value from an object using a dot-notation path
 * Supports array indexing (e.g. 'data.d.results[0].Status')
 *
 * @param obj - The object to get the value from
 * @param path - The dot-notation path (e.g. 'data.Status' or 'data.d.results[0].Status')
 * @returns The value at the path, or undefined if the path doesn't exist
 *
 * @example
 * const value = getNestedValue(data, 'data.Status');
 * const arrayValue = getNestedValue(data, 'data.d.results[0].Name');
 */
export declare function getNestedValue(obj: any, path: string): any;
/**
 * Sets a nested value in an object using a dot-notation path
 * Supports array indexing (e.g. 'data.d.results[0].Status')
 * Creates intermediate objects/arrays if they don't exist
 *
 * @param obj - The object to set the value in
 * @param path - The dot-notation path (e.g. 'data.Status' or 'data.d.results[0].Status')
 * @param value - The value to set
 * @returns true if the value was set successfully, false otherwise
 *
 * @example
 * setNestedValue(data, 'data.Status', 'STARTED');
 * setNestedValue(data, 'data.d.results[0].Name', 'MyArtifact');
 */
export declare function setNestedValue(obj: any, path: string, value: any): boolean;
/**
 * Adds an artifact to a cache array
 * Handles various cache formats (Array, OData-Format, etc.)
 *
 * @param cachedData - The cached data to update
 * @param artifact - The artifact to add
 * @param options - Optional configuration
 * @param options.arrayPath - Custom dot-notation path to the array (e.g. 'data.custom.path')
 * @param options.preventDuplicates - If true, prevents adding duplicate artifacts (checks Id/id property)
 * @returns Updated cached data, or null if error or duplicate found (when preventDuplicates is true)
 *
 * @example
 * const updated = addArtifactToCacheArray(cachedData, newArtifact, {
 *   preventDuplicates: true
 * });
 */
export declare function addArtifactToCacheArray(cachedData: CachedData, artifact: any, options?: {
    arrayPath?: string;
    preventDuplicates?: boolean;
}): CachedData | null;
/**
 * Comparison result for two arrays of artifacts
 */
export interface ComparisonResult {
    /** Newly added artifacts (exist in new data but not in old) */
    added: any[];
    /** Updated artifacts (exist in both but have changed) */
    updated: any[];
    /** Removed artifacts (exist in old data but not in new) */
    removed: any[];
    /** Unchanged artifacts (exist in both and are identical) */
    unchanged: any[];
    /** Whether any changes were detected */
    hasChanges: boolean;
}
/**
 * Options for differential merge operations
 */
export interface DifferentialMergeOptions {
    /** Time-to-live in seconds (how long to keep in cache) */
    ttl: number;
    /** Time in seconds after which to revalidate the cache */
    revalidateAfter: number;
}
/**
 * Compares two arrays of artifacts and identifies changes
 * Used for differential cache updates during background revalidation
 *
 * @param oldArtifacts - The old artifacts from cache
 * @param newArtifacts - The new artifacts from SAP API
 * @returns Comparison result with added, updated, removed, and unchanged artifacts
 *
 * @example
 * const comparison = compareArtifacts(cachedData.data, freshData);
 * console.log(`Added: ${comparison.added.length}, Updated: ${comparison.updated.length}`);
 */
export declare function compareArtifacts(oldArtifacts: any[], newArtifacts: any[]): ComparisonResult;
/**
 * Merges old cached data with comparison results using differential updates
 * Performs selective updates: only changes added/updated/removed artifacts
 * ALWAYS updates cache metadata (cachedAt, expiresAt, revalidateAfter) to mark cache as "fresh"
 *
 * @param cachedData - The old cached data
 * @param newArtifacts - The complete new artifacts from SAP API
 * @param comparison - The comparison result between old and new
 * @param options - Cache options for metadata updates
 * @returns Updated CachedData with refreshed metadata
 *
 * @example
 * const comparison = compareArtifacts(oldArtifacts, newArtifacts);
 * const merged = mergeArtifactsDifferentially(cachedData, newArtifacts, comparison, options);
 */
export declare function mergeArtifactsDifferentially(cachedData: CachedData, newArtifacts: any[], comparison: ComparisonResult, options: DifferentialMergeOptions): CachedData;
/**
 * Removes an artifact from a cache array
 * Handles various cache formats (Array, OData-Format, etc.)
 *
 * @param cachedData - The cached data to update
 * @param artifactId - The ID of the artifact to remove
 * @param options - Optional configuration
 * @param options.arrayPath - Custom dot-notation path to the array (e.g. 'data.custom.path')
 * @returns Updated cached data, or null if artifact not found or error occurred
 *
 * @example
 * const updated = removeArtifactFromCacheArray(cachedData, 'MyArtifactId');
 */
export declare function removeArtifactFromCacheArray(cachedData: CachedData, artifactId: string, options?: {
    arrayPath?: string;
}): CachedData | null;