tessl/npm-vinyl-fs

Vinyl adapter for the file system providing streaming file operations.

—

Pending

Overview

Eval results

Files

File Writing (dest)

Name: tessl/npm-vinyl-fs
Author: tessl

Stream-based file writing functionality that accepts Vinyl File objects and writes them to the filesystem. Automatically creates directories, handles file permissions, and supports sourcemap output.

Capabilities

dest Function

Creates a writable stream that saves Vinyl File objects to the filesystem with comprehensive options for file writing behavior.

/**
 * Creates a writable stream that saves Vinyl File objects to filesystem
 * @param {string|function} outFolder - Destination folder path or function returning path
 * @param {Object} [options] - Configuration options
 * @returns {Transform} Transform stream that consumes Vinyl File objects
 * @throws {Error} When outFolder argument is invalid
 */
function dest(outFolder, options);

interface DestOptions {
  /** Working directory for relative paths (default: process.cwd()) */
  cwd?: string;
  /** File permissions mode (default: file.stat.mode) */
  mode?: number | ((file: File) => number);
  /** Directory permissions mode */
  dirMode?: number | ((file: File) => number);
  /** Overwrite existing files (default: true) */
  overwrite?: boolean;
  /** Append to existing files (default: false) */
  append?: boolean;
  /** Output encoding (default: 'utf8') */
  encoding?: string | boolean;
  /** Sourcemap handling (default: false) */
  sourcemaps?: boolean | string;
  /** Create relative symlinks (default: false) */
  relativeSymlinks?: boolean;
  /** Use junctions on Windows (default: true) */
  useJunctions?: boolean;
}

Folder Path Resolution

The outFolder parameter can be a string or function:

// Static folder path
vfs.dest('./output');

// Dynamic folder based on file properties
vfs.dest((file) => {
  return file.extname === '.css' ? './css' : './js';
});

File Modification Behavior

After writing files, vinyl-fs attempts to preserve file metadata:

Timestamps: Sets mtime and atime if they differ from filesystem
Permissions: Updates file mode if different and process owns the file
Ownership: Only on Unix-like systems with proper permissions

Note: Metadata updates are disabled on Windows due to platform limitations.

Option Details

mode

Controls file permissions for written files.

// Use original file permissions (default)
vfs.dest('./output', { mode: undefined });

// Set specific permissions
vfs.dest('./output', { mode: 0o644 });

// Dynamic permissions based on file
vfs.dest('./output', {
  mode: (file) => file.extname === '.sh' ? 0o755 : 0o644
});

dirMode

Controls directory permissions when creating directories.

// Set directory permissions
vfs.dest('./output', { dirMode: 0o755 });

overwrite

Controls behavior when files already exist.

// Overwrite existing files (default)
vfs.dest('./output', { overwrite: true });

// Skip existing files
vfs.dest('./output', { overwrite: false });

append

Controls whether new content is appended to existing files.

// Replace existing content (default)
vfs.dest('./output', { append: false });

// Append to existing files
vfs.dest('./logs', { append: true });

sourcemaps

Controls sourcemap output behavior.

// Write inline sourcemaps
vfs.dest('./output', { sourcemaps: true });

// Write external sourcemaps to same folder
vfs.dest('./output', { sourcemaps: '.' });

// Write external sourcemaps to specific folder
vfs.dest('./output', { sourcemaps: './maps' });

relativeSymlinks

Controls symbolic link creation behavior.

// Create absolute symlinks (default)
vfs.dest('./output', { relativeSymlinks: false });

// Create relative symlinks
vfs.dest('./output', { relativeSymlinks: true });

useJunctions

Windows-specific option for directory symlinks.

// Use junctions for directory symlinks on Windows (default)
vfs.dest('./output', { useJunctions: true });

// Use standard symlinks (may require elevated permissions)
vfs.dest('./output', { useJunctions: false });

Error Handling

The dest function throws errors for invalid inputs:

// Throws: "Invalid dest() folder argument..."
try {
  vfs.dest('');
} catch (error) {
  console.error(error.message);
}

Usage Examples

Basic file writing:

const vfs = require('vinyl-fs');

vfs.src('src/**/*.js')
  .pipe(vfs.dest('./output'));

Advanced configuration:

vfs.src('src/**/*.js')
  .pipe(vfs.dest('./output', {
    mode: 0o644,           // Set file permissions
    dirMode: 0o755,        // Set directory permissions
    sourcemaps: '.',       // Write external sourcemaps
    overwrite: true        // Replace existing files
  }));

Dynamic output paths:

vfs.src(['src/**/*.js', 'src/**/*.css'])
  .pipe(vfs.dest((file) => {
    // Organize by file type
    return file.extname === '.css' ? './dist/css' : './dist/js';
  }));

Conditional writing:

vfs.src('src/**/*')
  .pipe(vfs.dest('./output', {
    // Only overwrite if source is newer
    overwrite: (file) => {
      const destPath = path.join('./output', file.relative);
      if (!fs.existsSync(destPath)) return true;
      
      const destStat = fs.statSync(destPath);
      return file.stat.mtime > destStat.mtime;
    }
  }));

Appending to log files:

const through = require('through2');

vfs.src('logs/*.log')
  .pipe(through.obj((file, enc, cb) => {
    file.contents = Buffer.concat([
      file.contents,
      Buffer.from('\n--- Processing complete ---\n')
    ]);
    cb(null, file);
  }))
  .pipe(vfs.dest('archive/', { append: true }));

Install with Tessl CLI