gulp-changed

import gulpChanged, { compareLastModifiedTime, compareContents } from 'gulp-changed';

import gulp from 'gulp';
import gulpChanged from 'gulp-changed';
import ngAnnotate from 'gulp-ng-annotate'; // Example processor

const SOURCE = 'src/*.js';
const DESTINATION = 'dist';

export default function build() {
  return gulp.src(SOURCE)
    .pipe(gulpChanged(DESTINATION))
    // ngAnnotate will only get the files that
    // changed since the last time it was run
    .pipe(ngAnnotate())
    .pipe(gulp.dest(DESTINATION));
}

/**
 * Create a gulp plugin that only passes through changed files
 * @param destination - Destination directory path or function returning destination path
 * @param options - Configuration options for comparison behavior
 * @returns Transform stream for use in gulp pipeline
 */
function gulpChanged(destination: string | ((file: Vinyl) => string), options?: ChangedOptions): Transform;

interface ChangedOptions {
  /** Working directory the folder is relative to (default: process.cwd()) */
  cwd?: string;
  /** Function that determines whether the source file is different from the destination file */
  hasChanged?: (sourceFile: Vinyl, targetPath: string) => Promise<Vinyl | undefined>;
  /** Extension of the destination files (useful if different from source) */
  extension?: string;
  /** Function to transform the path to the destination file */
  transformPath?: (newPath: string) => string;
}

// Basic usage with destination directory
gulp.src('src/**/*.js')
  .pipe(gulpChanged('dist'))
  .pipe(babel())
  .pipe(gulp.dest('dist'));

// With different file extension
gulp.src('src/**/*.jade')
  .pipe(gulpChanged('app', {extension: '.html'}))
  .pipe(jade())
  .pipe(gulp.dest('app'));

// With custom path transformation
gulp.src('src/content/*.md')
  .pipe(gulpChanged('dist', {
    transformPath: (newPath) => path.join(
      path.dirname(newPath), 
      path.basename(newPath, '.md'), 
      'index.html'
    )
  }))
  .pipe(marked())
  .pipe(gulp.dest('dist'));

// With function-based destination
gulp.src('src/**/*.js')
  .pipe(gulpChanged((file) => `dist/${file.relative.split('/')[0]}`))
  .pipe(babel())
  .pipe(gulp.dest('dist'));

/**
 * Compare files based on modification time
 * @param sourceFile - Source vinyl file object with stat information
 * @param targetPath - Absolute path to target file for comparison
 * @returns Promise resolving to sourceFile if changed, undefined if not
 */
async function compareLastModifiedTime(sourceFile: Vinyl, targetPath: string): Promise<Vinyl | undefined>;

// Explicitly use modification time comparison (this is the default)
gulp.src('src/**/*.js')
  .pipe(gulpChanged('dist', {hasChanged: compareLastModifiedTime}))
  .pipe(babel())
  .pipe(gulp.dest('dist'));

/**
 * Compare files based on content differences
 * @param sourceFile - Source vinyl file object with contents buffer
 * @param targetPath - Absolute path to target file for comparison
 * @returns Promise resolving to sourceFile if changed, undefined if not
 */
async function compareContents(sourceFile: Vinyl, targetPath: string): Promise<Vinyl | undefined>;

// Use content-based comparison for more accurate change detection
gulp.src('src/**/*.js')
  .pipe(gulpChanged('dist', {hasChanged: compareContents}))
  .pipe(babel())
  .pipe(gulp.dest('dist'));

// Vinyl file object (from vinyl package)
interface Vinyl {
  /** Current working directory */
  cwd: string;
  /** Base directory for relative paths */
  base: string;
  /** Full file path */
  path: string;
  /** Relative file path from base */
  relative: string;
  /** File contents as Buffer or Stream */
  contents: Buffer | Stream | null;
  /** File system stat object */
  stat?: {
    /** Modification time in milliseconds */
    mtimeMs: number;
    [key: string]: any;
  };
}

// Transform stream (from Node.js streams)
interface Transform extends Stream.Transform {
  /** Write a file to the stream */
  write(file: Vinyl): boolean;
  /** End the stream */
  end(): void;
  /** Event emitted when stream ends */
  on(event: 'end', callback: () => void): this;
  /** Event emitted for each file passing through */
  on(event: 'data', callback: (file: Vinyl) => void): this;
}

function customComparator(sourceFile, targetPath) {
  // Custom logic here - must return Promise<Vinyl | undefined>
  // Return sourceFile if it should be processed, undefined if not
  return Promise.resolve(sourceFile);
}

gulp.src('src/**/*.js')
  .pipe(gulpChanged('dist', {hasChanged: customComparator}))
  .pipe(babel())
  .pipe(gulp.dest('dist'));

gulp.src('src/**/*.js')
  .pipe(gulpChanged('dist', {
    cwd: '/custom/working/directory'
  }))
  .pipe(babel())
  .pipe(gulp.dest('dist'));