CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is exiftool-vendored.js, a Node.js library that provides cross-platform access to ExifTool for reading and writing metadata in photos and videos. The library includes comprehensive TypeScript type definitions for metadata tags and is used by PhotoStructure and 500+ other projects.

Key Commands

Building & Development

# Install dependencies
npm install

# Compile TypeScript to JavaScript
npm run compile

# Watch mode for development
npm run compile:watch

# Clean build artifacts
npm run clean

Linting & Formatting

# Run ESLint with TypeScript configuration
npm run lint

# Format all TypeScript and other files with Prettier
npm run fmt

Testing

# Run all tests (requires compilation first)
npm test

# Note: Tests use Mocha and execute the compiled JavaScript files in dist/

Documentation

# Generate TypeDoc documentation
npm run docs

# This runs the typedoc tool and serves the documentation locally

Tag Generation

# Regenerate src/Tags.ts from sample images
npm run mktags ../path/to/images

# This requires a directory of sample images to analyze and extract metadata tags

Architecture & Key Concepts

Core Components

ExifTool Class (src/ExifTool.ts): Main entry point that wraps ExifTool process management using batch-cluster. Provides methods for reading metadata, writing tags, extracting binaries, and rewriting tags.
Tags Interface (src/Tags.ts): Auto-generated TypeScript interface containing ~2000 metadata fields commonly found in photo/video files. Generated by analyzing thousands of sample files to avoid TypeScript union type limits. Fields include popularity ratings and example values.
Date/Time Handling: Custom classes for handling EXIF dates with timezone complexities:
- ExifDate: Date without time
- ExifTime: Time without date
- ExifDateTime: Date and time with optional timezone
Task System: Various task classes for different operations:
- ReadTask: Read metadata from files
- WriteTask: Write metadata to files
- BinaryExtractionTask: Extract thumbnails/previews
- RewriteAllTagsTask: Repair corrupt metadata
Platform Support: Includes platform-specific ExifTool binaries via optional dependencies:
- exiftool-vendored.exe for Windows
- exiftool-vendored.pl for Unix-like systems

Timezone Handling

The library implements sophisticated timezone heuristics to handle underspecified date metadata:

Uses explicit timezone metadata if available
Falls back to GPS location for timezone inference
Uses UTC timestamp deltas to infer timezone offsets
Handles edge cases like daylight saving time transitions

Tag Generation Process

The mktags.ts script analyzes sample images to generate TypeScript interfaces:

Scans image directories for various formats (JPEG, RAW, video)
Extracts metadata using ExifTool
Counts tag frequencies and value types
Generates strongly-typed interfaces for the most common ~2000 tags
Includes popularity ratings (★★★★ = >50% of samples)

Testing Approach

Tests use Mocha with Chai assertions:

Unit tests for individual components (dates, parsers, etc.)
Integration tests for ExifTool operations
Test images in the test/ directory cover various edge cases
Includes non-English filename tests

Important Notes

Always run npm run compile before testing
The singleton exiftool instance must be properly ended with .end() to clean up child processes
Tag interfaces are not comprehensive - less common tags may exist in returned objects
The library uses batch processing for performance, managing process pools automatically
TypeScript's union type limits require careful tag selection to avoid compilation errors

Important TypeScript Hygiene

You MUST use if (x != null) to test for null or undefined values. DO NOT use if (x): this is problematic (especially when handling boolean values).
You MUST use ?? for nullish coalescing. DO NOT use ||: this is problematic (especially when handling boolean values).

4.2 KiB Raw Permalink Blame History