tessl/npm-fast-glob

A very fast and efficient glob library for Node.js with async/sync/stream APIs and advanced pattern matching

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Configuration Options

Name: tessl/npm-fast-glob
Author: tessl

Comprehensive configuration system controlling matching behavior, output format, performance tuning, and file system interaction. Options provide fine-grained control over glob operations to handle diverse use cases and environments.

Capabilities

Options Interface

Complete configuration interface with all available options organized by category.

interface Options {
  // Common options
  concurrency?: number;
  cwd?: string;
  deep?: number;
  followSymbolicLinks?: boolean;
  fs?: Partial<FileSystemAdapter>;
  ignore?: string[];
  suppressErrors?: boolean;
  throwErrorOnBrokenSymbolicLink?: boolean;
  
  // Output control options
  absolute?: boolean;
  markDirectories?: boolean;
  objectMode?: boolean;
  onlyDirectories?: boolean;
  onlyFiles?: boolean;
  stats?: boolean;
  unique?: boolean;
  
  // Matching control options
  braceExpansion?: boolean;
  caseSensitiveMatch?: boolean;
  dot?: boolean;
  extglob?: boolean;
  globstar?: boolean;
  baseNameMatch?: boolean;
}

Common Options

Core options controlling basic glob operation behavior and performance.

Concurrency Control

Control the number of concurrent file system operations for performance tuning.

interface Options {
  /**
   * Maximum number of concurrent requests from reader to read directories
   * @default os.cpus().length
   */
  concurrency?: number;
}

Usage Examples:

// High performance (more concurrent operations)
const files = await fg('**/*.js', { concurrency: 16 });

// Conservative (fewer concurrent operations, less system load)
const files = await fg('**/*.js', { concurrency: 2 });

// Single-threaded (minimal system impact)
const files = await fg('**/*.js', { concurrency: 1 });

Working Directory

Set the starting directory for pattern matching operations.

interface Options {
  /**
   * Current working directory in which to search
   * @default process.cwd()
   */
  cwd?: string;
}

Usage Examples:

// Search within specific directory
const srcFiles = await fg('**/*.ts', { cwd: './src' });

// Search in sibling directory
const testFiles = await fg('**/*.spec.js', { cwd: '../tests' });

// Absolute path as working directory
const libFiles = await fg('**/*.js', { cwd: '/usr/local/lib/myapp' });

Traversal Depth Limit

Control maximum directory traversal depth to prevent excessive nesting.

interface Options {
  /**
   * Maximum depth of directory traversal relative to start directory
   * @default Infinity
   */
  deep?: number;
}

Usage Examples:

// Limit to 2 levels deep: ./src/components but not ./src/components/ui/buttons
const files = await fg('**/*.js', { deep: 2 });

// Only immediate children (depth 1)
const topLevel = await fg('*/*.js', { deep: 1 });

// No depth limit (default)
const allFiles = await fg('**/*.js', { deep: Infinity });

Symbolic Link Handling

Control whether to follow symbolic links during traversal.

interface Options {
  /**
   * Whether to traverse descendants of symbolic link directories
   * @default true
   */
  followSymbolicLinks?: boolean;
  
  /**
   * Throw error when symbolic link is broken
   * @default false
   */
  throwErrorOnBrokenSymbolicLink?: boolean;
}

Usage Examples:

// Don't follow symbolic links (safer, prevents loops)
const files = await fg('**/*.js', { followSymbolicLinks: false });

// Follow symlinks but throw on broken ones
const files = await fg('**/*.js', { 
  followSymbolicLinks: true,
  throwErrorOnBrokenSymbolicLink: true 
});

Custom File System

Provide custom file system implementation for testing or special environments.

interface Options {
  /**
   * Custom implementation of file system methods
   * @default Node.js fs methods
   */
  fs?: Partial<FileSystemAdapter>;
}

interface FileSystemAdapter {
  lstat: typeof fs.lstat;
  lstatSync: typeof fs.lstatSync;
  stat: typeof fs.stat;
  statSync: typeof fs.statSync;
  readdir: typeof fs.readdir;
  readdirSync: typeof fs.readdirSync;
}

Usage Examples:

import { Volume } from 'memfs';

// Use in-memory file system for testing
const vol = Volume.fromJSON({
  './test.js': 'console.log("test");',
  './src/index.js': 'module.exports = {};'
});

const files = await fg('**/*.js', {
  fs: {
    lstat: vol.lstat.bind(vol),
    lstatSync: vol.lstatSync.bind(vol),
    stat: vol.stat.bind(vol),
    statSync: vol.statSync.bind(vol),
    readdir: vol.readdir.bind(vol),
    readdirSync: vol.readdirSync.bind(vol)
  }
});

Pattern Exclusions

Additional patterns to ignore during matching.

interface Options {
  /**
   * Array of glob patterns to exclude matches
   * Alternative to negative patterns in main pattern list
   * @default []
   */
  ignore?: string[];
}

Usage Examples:

// Ignore patterns via options
const files = await fg('**/*.js', {
  ignore: ['node_modules/**', '**/*.test.js', 'dist/**']
});

// Equivalent using negative patterns
const files = await fg([
  '**/*.js',
  '!node_modules/**',
  '!**/*.test.js', 
  '!dist/**'
]);

Error Handling

Control error suppression and handling behavior.

interface Options {
  /**
   * Suppress all errors during traversal
   * By default only ENOENT errors are suppressed
   * @default false
   */
  suppressErrors?: boolean;
}

Usage Examples:

// Suppress all errors (continue on permission denied, etc.)
const files = await fg('**/*.js', { suppressErrors: true });

// Default behavior (only suppress ENOENT - file not found)
const files = await fg('**/*.js', { suppressErrors: false });

Output Control Options

Options controlling the format and content of returned results.

Path Format

Control whether returned paths are absolute or relative.

interface Options {
  /**
   * Return absolute paths for entries
   * @default false
   */
  absolute?: boolean;
}

Usage Examples:

// Relative paths (default)
const relative = await fg('**/*.js');
// ['src/index.js', 'lib/utils.js']

// Absolute paths
const absolute = await fg('**/*.js', { absolute: true });
// ['/full/path/to/src/index.js', '/full/path/to/lib/utils.js']

Directory Marking

Add trailing slashes to directory entries for easy identification.

interface Options {
  /**
   * Mark directory paths with final slash
   * @default false
   */
  markDirectories?: boolean;
}

Usage Examples:

// Mark directories with trailing slash
const entries = await fg('**/*', { 
  markDirectories: true,
  onlyDirectories: false 
});
// ['src/', 'lib/', 'src/index.js', 'lib/utils.js']

Object Mode

Return detailed Entry objects instead of simple strings.

interface Options {
  /**
   * Return Entry objects instead of strings
   * @default false
   */
  objectMode?: boolean;
  
  /**
   * Include fs.Stats in Entry objects (implies objectMode: true)
   * @default false
   */
  stats?: boolean;
}

Usage Examples:

// Object mode
const entries = await fg('**/*.js', { objectMode: true });
// [{ name: 'index.js', path: '/full/path/src/index.js', dirent: Dirent }]

// With file stats
const entriesWithStats = await fg('**/*.js', { stats: true });
// [{ name: 'index.js', path: '/path', dirent: Dirent, stats: Stats }]

Entry Type Filtering

Control whether to return files, directories, or both.

interface Options {
  /**
   * Return only directories
   * @default false
   */
  onlyDirectories?: boolean;
  
  /**
   * Return only files
   * @default true
   */
  onlyFiles?: boolean;
}

Usage Examples:

// Only files (default)
const files = await fg('**/*', { onlyFiles: true });

// Only directories
const dirs = await fg('**/*', { onlyDirectories: true });

// Both files and directories
const all = await fg('**/*', { 
  onlyFiles: false, 
  onlyDirectories: false 
});

Result Deduplication

Control whether to remove duplicate entries from results.

interface Options {
  /**
   * Ensure returned entries are unique
   * @default true
   */
  unique?: boolean;
}

Usage Examples:

// Unique results (default) - duplicates removed
const unique = await fg(['**/*.js', 'src/**/*.js']);

// Allow duplicates
const withDupes = await fg(['**/*.js', 'src/**/*.js'], { unique: false });

Matching Control Options

Options controlling pattern matching behavior and glob feature support.

Brace Expansion

Enable or disable brace expansion in patterns.

interface Options {
  /**
   * Enable Bash-like brace expansion
   * @default true
   */
  braceExpansion?: boolean;
}

Usage Examples:

// Brace expansion enabled (default)
const files = await fg('*.{js,ts,json}'); // Expands to *.js, *.ts, *.json

// Brace expansion disabled
const literal = await fg('*.{js,ts,json}', { braceExpansion: false });
// Searches for literal filename "*.{js,ts,json}"

Case Sensitivity

Control case-sensitive pattern matching.

interface Options {
  /**
   * Enable case-sensitive mode for matching files
   * @default true
   */
  caseSensitiveMatch?: boolean;
}

Usage Examples:

// Case sensitive (default)
const files = await fg('*.JS'); // Only matches *.JS, not *.js

// Case insensitive
const files = await fg('*.JS', { caseSensitiveMatch: false });
// Matches *.js, *.JS, *.Js, etc.

Dotfile Matching

Control whether patterns match files beginning with dots.

interface Options {
  /**
   * Allow patterns to match entries beginning with period (.)
   * @default false
   */
  dot?: boolean;
}

Usage Examples:

// Exclude dotfiles (default)
const files = await fg('*'); // Doesn't match .gitignore, .env

// Include dotfiles
const files = await fg('*', { dot: true }); // Matches .gitignore, .env

Extended Glob Support

Enable extended glob patterns like !(pattern), @(pattern), etc.

interface Options {
  /**
   * Enable Bash-like extended glob functionality
   * @default true
   */
  extglob?: boolean;
}

Usage Examples:

// Extended globs enabled (default)
const files = await fg('!(node_modules)/**/*.js'); // Everything except node_modules

// Extended globs disabled
const files = await fg('!(node_modules)/**/*.js', { extglob: false });
// Treats !(...) as literal characters

Globstar Support

Control whether ** behaves as globstar or regular *.

interface Options {
  /**
   * Enable recursive repeats of pattern containing **
   * If false, ** behaves exactly like *
   * @default true
   */
  globstar?: boolean;
}

Usage Examples:

// Globstar enabled (default)
const files = await fg('**/*.js'); // Recursively searches all subdirectories

// Globstar disabled
const files = await fg('**/*.js', { globstar: false });
// ** behaves like *, searches only immediate subdirectories

Base Name Matching

Enable matching against file basename for patterns without slashes.

interface Options {
  /**
   * Match patterns without slashes against basename if path contains slashes
   * @default false
   */
  baseNameMatch?: boolean;
}

Usage Examples:

// Base name matching disabled (default)
const files = await fg('index.js'); // Only matches ./index.js

// Base name matching enabled
const files = await fg('index.js', { baseNameMatch: true });
// Matches ./index.js, ./src/index.js, ./lib/components/index.js

Option Combinations

Common Configuration Patterns

// Development build file gathering
const devFiles = await fg(['src/**/*.{js,ts}', '!**/*.test.*'], {
  absolute: true,
  dot: false,
  onlyFiles: true
});

// Production file analysis with stats
const prodFiles = await fg('dist/**/*', {
  stats: true,
  onlyFiles: true,
  suppressErrors: true
});

// Directory structure analysis
const structure = await fg('**/*', {
  objectMode: true,
  markDirectories: true,
  onlyFiles: false,
  deep: 3
});

// Safe user input handling
function findUserFiles(userPattern: string, userDir: string) {
  return fg(userPattern, {
    cwd: userDir,
    dot: false,
    followSymbolicLinks: false,
    suppressErrors: true,
    deep: 10
  });
}

docs

configuration-options.md

tessl/npm-fast-glob