exiftool-vendored/dist/TagDescriptions.d.ts

Efficient, cross-platform access to ExifTool

import type { ExifTool } from "./ExifTool";
/**
 * Description information for a metadata tag.
 */
export interface TagDescription {
    /**
     * Human-readable description of what this tag represents.
     */
    desc: string;
    /**
     * Optional URL reference to ExifTool documentation or other resources.
     */
    see?: string;
}
/**
 * Options for configuring TagDescriptions behavior.
 */
export interface TagDescriptionsOptions {
    /**
     * Directory to cache parsed tag descriptions.
     * Defaults to system temp directory.
     */
    cacheDir?: string;
    /**
     * Language code for descriptions (e.g., 'en', 'de', 'fr').
     * Defaults to 'en'.
     */
    language?: string;
    /**
     * If true, disables disk caching. Useful for testing or memory-constrained environments.
     * Defaults to false.
     */
    disableDiskCache?: boolean;
}
/**
 * Provides access to human-readable descriptions for ExifTool metadata tags.
 *
 * Descriptions are sourced from ExifTool's built-in tag database (via `-listx`)
 * and merged with hand-curated descriptions for important tags.
 *
 * **CAUTION**: The first call to an async method (e.g., `getAsync()`, `preload()`,
 * `getAll()`) may take several seconds as it launches ExifTool to retrieve tag
 * information.
 *
 * **SECOND CAUTION**: The in-memory cache can consume significant memory (several
 * MB).
 *
 * **THIRD CAUTION**: The on-disk cache can consume disk space (several MB).
 *
 * **FOURTH CAUTION**: The synchronous `get()` method only works after descriptions
 * are loaded! Be sure to call `preload()` during application initialization for
 * sync access later.
 *
 * **FIFTH CAUTION**: Tag descriptions may vary between ExifTool versions and languages.
 *
 * @example
 * ```typescript
 * import { exiftool } from "exiftool-vendored";
 *
 * const descriptions = new TagDescriptions(exiftool);
 *
 * // Preload during app initialization for sync access later
 * await descriptions.preload();
 *
 * // Sync lookup (instant if preloaded)
 * const desc = descriptions.get("DateTimeOriginal");
 * // => { desc: "When a photo was taken...", see: "https://..." }
 *
 * // Or use async lookup (auto-loads if needed)
 * const desc2 = await descriptions.getAsync("ISO");
 * ```
 */
export declare class TagDescriptions {
    #private;
    constructor(exiftool: ExifTool, options?: TagDescriptionsOptions);
    /**
     * Preload all tag descriptions into memory.
     * Call this during application initialization for instant sync access later.
     *
     * @returns Promise that resolves when descriptions are loaded
     */
    preload(): Promise<void>;
    /**
     * Whether descriptions have been loaded into memory.
     */
    get isLoaded(): boolean;
    /**
     * Get the number of tag descriptions available.
     * Returns 0 if not yet loaded.
     */
    get size(): number;
    /**
     * Synchronous lookup of a tag description.
     * Returns undefined if descriptions haven't been loaded or tag is unknown.
     *
     * For guaranteed results, call `preload()` first or use `getAsync()`.
     *
     * @param tagName The tag name (e.g., "DateTimeOriginal", "ISO")
     * @returns Tag description or undefined
     */
    get(tagName: string): TagDescription | undefined;
    /**
     * Asynchronous lookup of a tag description.
     * Automatically loads descriptions if not yet loaded.
     *
     * @param tagName The tag name (e.g., "DateTimeOriginal", "ISO")
     * @returns Promise resolving to tag description or undefined
     */
    getAsync(tagName: string): Promise<TagDescription | undefined>;
    /**
     * Get all loaded tag descriptions.
     * Automatically loads descriptions if not yet loaded.
     *
     * @returns Promise resolving to a readonly Map of tag names to descriptions
     */
    getAll(): Promise<ReadonlyMap<string, TagDescription>>;
    /**
     * Clear the in-memory cache.
     * The disk cache is preserved; call `preload()` to reload from disk.
     */
    clear(): void;
}