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

Globby

Name: tessl/npm-globby
Author: tessl

Globby is a user-friendly glob matching library built on top of fast-glob with additional convenience features. It provides Promise-based APIs for matching file paths using glob patterns, with support for negated patterns, automatic directory expansion, gitignore integration, and streaming capabilities.

Package Information

Package Name: globby
Package Type: npm
Language: JavaScript with TypeScript definitions
Installation: npm install globby

Core Imports

import { globby, globbySync, globbyStream } from "globby";

Additional imports for ignore handling and utilities:

import { 
  isGitIgnored, 
  isIgnoredByIgnoreFiles, 
  GITIGNORE_FILES_PATTERN,
  isDynamicPattern,
  generateGlobTasks,
  generateGlobTasksSync,
  convertPathToPattern
} from "globby";

For CommonJS:

const { globby, globbySync, globbyStream } = require("globby");
const { isGitIgnored, isIgnoredByIgnoreFiles, GITIGNORE_FILES_PATTERN } = require("globby");

Basic Usage

import { globby } from "globby";

// Basic glob matching
const paths = await globby(['*', '!node_modules']);
console.log(paths);
//=> ['index.js', 'package.json', 'readme.md']

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

// Directory expansion (default behavior)
const allFiles = await globby(['src', 'docs'], {
  expandDirectories: {
    files: ['*.js', '*.md'],
    extensions: ['ts']
  }
});

// Gitignore support
const trackedFiles = await globby(['**/*'], { gitignore: true });

Architecture

Globby is built around several key components:

Core Globbing Functions: Main async/sync/stream APIs (globby, globbySync, globbyStream)
Pattern Processing: Automatic directory expansion and negative pattern handling
Ignore Integration: Built-in support for .gitignore and custom ignore files
Utility Functions: Pattern analysis and task generation for integration with other tools
Type System: Complete TypeScript definitions with generic type support

Capabilities

Main Globbing API

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

function globby(
  patterns: string | readonly string[],
  options?: Options
): Promise<string[]>;

function globby(
  patterns: string | readonly string[],
  options: Options & { objectMode: true }
): Promise<GlobEntry[]>;

Main Globbing API

Ignore File Handling

Integration with .gitignore and custom ignore file formats for excluding files from glob results.

function isGitIgnored(options?: GitignoreOptions): Promise<GlobbyFilterFunction>;

function isIgnoredByIgnoreFiles(
  patterns: string | readonly string[],
  options?: Options
): Promise<GlobbyFilterFunction>;

Ignore File Handling

Utility Functions

Helper functions for pattern analysis, task generation, and integration with other globbing tools.

function isDynamicPattern(
  patterns: string | readonly string[],
  options?: { cwd?: URL | string }
): boolean;

function generateGlobTasks(
  patterns: string | readonly string[],
  options?: Options
): Promise<GlobTask[]>;

Utility Functions

Types

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
  /** Return only files (default: true) */
  readonly onlyFiles?: boolean;
  /** Return only directories (default: false) */
  readonly onlyDirectories?: boolean;
  /** Follow symbolic links (default: true) */
  readonly followSymbolicLinks?: boolean;
  /** Add trailing slash to directory paths 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;
  /** Throw error on broken symbolic link */
  readonly throwErrorOnBrokenSymbolicLink?: boolean;
  /** Return absolute paths (default: false) */
  readonly absolute?: boolean;
  /** Add stats property to entries (requires objectMode: true) */
  readonly stats?: boolean;
  /** Case sensitive matching (default: true) */
  readonly caseSensitiveMatch?: boolean;
  /** Transform paths in results */
  readonly transform?: (entry: GlobEntry) => GlobEntry;
}

type ExpandDirectoriesOption =
  | boolean
  | readonly string[]
  | { files?: readonly string[]; extensions?: readonly string[] };

interface GlobEntry {
  /** The name of the file/directory without path */
  name: string;
  /** The path relative to the search directory */
  path: string;
  /** Node.js directory entry with file type methods */
  dirent: import('fs').Dirent;
  /** Optional file stats (when stats option is true) */
  stats?: import('fs').Stats;
}

interface GlobTask {
  readonly patterns: string[];
  readonly options: Options;
}

type GlobbyFilterFunction = (path: URL | string) => boolean;

interface GitignoreOptions {
  readonly cwd?: URL | string;
}