Content Appending Operations

/**
 * Appends content to archive from Buffer, Stream, or String
 * @param {Buffer|Stream|string} source - Content source
 * @param {EntryData} data - Entry metadata including name (required)
 * @returns {Archiver} This instance for chaining
 * @fires entry - When entry is processed and appended
 */
append(source, data);

const archiver = require('archiver');
const fs = require('fs');

const archive = archiver('zip');

// Append string content
archive.append('Hello World!', { name: 'hello.txt' });

// Append buffer content
const buffer = Buffer.from('Binary data', 'utf8');
archive.append(buffer, { name: 'data.bin' });

// Append stream content
const stream = fs.createReadStream('/path/to/source.txt');
archive.append(stream, { name: 'streamed.txt' });

// Append with additional metadata
archive.append('Content with metadata', {
  name: 'file.txt',
  date: new Date('2023-01-01'),
  mode: 0644,
  prefix: 'folder/'
});

/**
 * Appends a file from filesystem using lazy stream
 * @param {string} filepath - Path to file on filesystem
 * @param {EntryData} data - Entry metadata including name (required)
 * @returns {Archiver} This instance for chaining
 * @throws {Error} If filepath is empty or not a string
 */
file(filepath, data);

// Append file with same name
archive.file('/path/to/document.pdf', { name: 'document.pdf' });

// Append file with different name in archive
archive.file('/path/to/source.txt', { name: 'renamed.txt' });

// Append file to subdirectory in archive
archive.file('/path/to/image.jpg', { name: 'images/photo.jpg' });

// Append file with custom metadata
archive.file('/path/to/executable', { 
  name: 'bin/app',
  mode: 0755,
  date: new Date()
});

/**
 * Recursively appends directory and its contents
 * @param {string} dirpath - Directory path on filesystem
 * @param {string|false} destpath - Destination path in archive, false to use dirpath
 * @param {EntryData|Function} data - Entry metadata or filter/transform function
 * @returns {Archiver} This instance for chaining
 * @throws {Error} If dirpath is empty or not a string
 */
directory(dirpath, destpath, data);

// Append entire directory maintaining structure
archive.directory('/path/to/source/dir', 'archived-dir');

// Append directory contents to archive root
archive.directory('/path/to/source/dir', false);

// Append directory with filter function
archive.directory('/path/to/source/dir', 'filtered-dir', function(entryData) {
  // Skip hidden files
  if (entryData.name.startsWith('.')) {
    return false;
  }
  // Modify entry data
  entryData.name = entryData.name.toLowerCase();
  return entryData;
});

// Append directory with static metadata
archive.directory('/path/to/source/dir', 'modified-dir', {
  mode: 0755,
  date: new Date('2023-01-01')
});

/**
 * Appends files matching glob pattern
 * @param {string} pattern - Glob pattern to match files
 * @param {Object} options - Glob options passed to readdir-glob
 * @param {EntryData} data - Entry metadata for matched files
 * @returns {Archiver} This instance for chaining
 */
glob(pattern, options, data);

// Append all JavaScript files recursively
archive.glob('**/*.js', {}, { name: 'js-files' });

// Append specific file types with options
archive.glob('src/**/*.{js,ts}', {
  cwd: '/project/root',
  ignore: ['**/*.test.js', '**/node_modules/**']
}, { prefix: 'source/' });

// Append with glob options and metadata
archive.glob('docs/**/*.md', {
  cwd: '/project',
  nodir: true, // Skip directories
  follow: true // Follow symlinks
}, {
  mode: 0644,
  date: new Date()
});

/**
 * Creates symbolic link entry (programmatic, no filesystem interaction)
 * @param {string} filepath - Link path in archive
 * @param {string} target - Link target path
 * @param {number} mode - File mode (optional, defaults to symlink mode)
 * @returns {Archiver} This instance for chaining
 * @throws {Error} If format doesn't support symlinks
 */
symlink(filepath, target, mode);

// Create symbolic link
archive.symlink('link-to-file.txt', '../original/file.txt');

// Create symbolic link with custom mode
archive.symlink('bin/app', '../lib/executable', 0755);

// Create directory symlink
archive.symlink('shortcut', '../very/long/path/to/directory');

/**
 * Entry metadata for archive entries
 */
interface EntryData {
  /** Entry name including internal path (required) */
  name: string;
  /** Entry date, defaults to current time */
  date?: string | Date;
  /** Entry permissions (0755 for dirs, 0644 for files) */
  mode?: number;
  /** Path prefix for entry name */
  prefix?: string;
  /** Filesystem stats to avoid additional calls */
  stats?: fs.Stats;
}

const archive = archiver('zip');

archive
  .append('String content', { name: 'string.txt' })
  .file('/path/to/file.pdf', { name: 'document.pdf' })
  .directory('/path/to/dir', 'archived-dir')
  .glob('**/*.js', {}, { prefix: 'scripts/' })
  .symlink('link.txt', 'target.txt')
  .finalize();