tessl/npm-globby

User-friendly glob matching library with Promise API, directory expansion, gitignore support, and streaming capabilities

—

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

Main Globbing API

Name: tessl/npm-globby
Author: tessl

Core file matching functionality providing Promise-based API, synchronous variant, and streaming support for large file sets.

Capabilities

Globby (Async)

Main asynchronous glob matching function that returns a Promise of matching file paths.

/**
 * Find files and directories using glob patterns
 * @param patterns - Glob patterns to match against
 * @param options - Configuration options
 * @returns Promise resolving to array of matching paths
 */
function globby(
  patterns: string | readonly string[],
  options?: Options
): Promise<string[]>;

/**
 * Find files and directories using glob patterns (object mode)
 * @param patterns - Glob patterns to match against
 * @param options - Configuration options with objectMode: true
 * @returns Promise resolving to array of GlobEntry objects
 */
function globby(
  patterns: string | readonly string[],
  options: Options & { objectMode: true }
): Promise<GlobEntry[]>;

Usage Examples:

import { globby } from "globby";

// Basic matching
const paths = await globby(['*', '!cake']);
console.log(paths);
//=> ['unicorn', 'rainbow']

// Multiple patterns
const sourceFiles = await globby([
  'src/**/*.js',
  'lib/**/*.js',
  '!**/*.test.js'
]);

// With options
const files = await globby(['**/*.txt'], {
  cwd: '/path/to/directory',
  gitignore: true,
  expandDirectories: false
});

// Object mode for detailed file information
const entries = await globby(['**/*.js'], { objectMode: true });
entries.forEach(entry => {
  console.log(entry.name, entry.path, entry.dirent);
});

Globby Sync

Synchronous version of the main globby function for scenarios where blocking operations are acceptable.

/**
 * Find files and directories using glob patterns (synchronous)
 * @param patterns - Glob patterns to match against
 * @param options - Configuration options
 * @returns Array of matching paths
 */
function globbySync(
  patterns: string | readonly string[],
  options?: Options
): string[];

/**
 * Find files and directories using glob patterns (synchronous, object mode)
 * @param patterns - Glob patterns to match against
 * @param options - Configuration options with objectMode: true
 * @returns Array of GlobEntry objects
 */
function globbySync(
  patterns: string | readonly string[],
  options: Options & { objectMode: true }
): GlobEntry[];

Usage Examples:

import { globbySync } from "globby";

// Synchronous matching
const paths = globbySync(['src/**/*.js', '!**/*.test.js']);

// With options
const configFiles = globbySync(['**/*.config.js'], {
  cwd: process.cwd(),
  expandDirectories: true
});

Globby Stream

Stream-based glob matching for handling large file sets efficiently without loading all results into memory.

/**
 * Find files and directories using glob patterns (streaming)
 * @param patterns - Glob patterns to match against
 * @param options - Configuration options
 * @returns Readable stream of matching paths
 */
function globbyStream(
  patterns: string | readonly string[],
  options?: Options
): NodeJS.ReadableStream;

Usage Examples:

import { globbyStream } from "globby";

// Stream processing
for await (const path of globbyStream('*.tmp')) {
  console.log(path);
}

// Transform stream
const stream = globbyStream(['**/*.js', '!node_modules/**']);
stream.on('data', (path) => {
  console.log('Found:', path);
});

// Pipeline usage
import { pipeline } from 'stream';
import { Transform } from 'stream';

const processStream = new Transform({
  objectMode: true,
  transform(chunk, encoding, callback) {
    // Process each file path
    callback(null, chunk.toUpperCase());
  }
});

pipeline(
  globbyStream(['src/**/*.txt']),
  processStream,
  process.stdout,
  (err) => {
    if (err) console.error('Pipeline failed:', err);
    else console.log('Pipeline succeeded');
  }
);

Pattern Syntax

Globby supports all standard glob patterns:

* matches any number of characters, but not /
? matches a single character, but not /
** matches any number of characters, including /, as long as it's the only thing in a path part
{} allows for a comma-separated list of "or" expressions
! at the beginning of a pattern will negate the match

Examples:

// Match all JS files in any subdirectory
const jsFiles = await globby('**/*.js');

// Match files with multiple extensions
const sourceFiles = await globby('src/**/*.{js,ts,jsx,tsx}');

// Exclude test files
const prodFiles = await globby(['src/**/*.js', '!src/**/*.test.js']);

// Match specific file names
const configs = await globby(['**/webpack.{config,dev,prod}.js']);

Options

All options from fast-glob are supported, plus globby-specific options:

interface Options {
  /** Auto-expand directories to include files (default: true) */
  readonly expandDirectories?: ExpandDirectoriesOption;
  /** Respect .gitignore files (default: false) */
  readonly gitignore?: boolean;
  /** Custom ignore file patterns */
  readonly ignoreFiles?: string | readonly string[];
  /** Current working directory (supports URL objects) */
  readonly cwd?: URL | string;
  
  // Fast-glob options (selection)
  /** Return only files (default: true) */
  readonly onlyFiles?: boolean;
  /** Return only directories (default: false) */
  readonly onlyDirectories?: boolean;
  /** Follow symbolic links (default: true) */
  readonly followSymbolicLinks?: boolean;
  /** Include directories in results when onlyFiles is false */
  readonly markDirectories?: boolean;
  /** Return entries with additional file information */
  readonly objectMode?: boolean;
  /** Ignore patterns */
  readonly ignore?: readonly string[];
  /** Search depth */
  readonly deep?: number;
  /** Include dot files (default: false) */
  readonly dot?: boolean;
  /** Suppress errors (default: true) */
  readonly suppressErrors?: boolean;
}