or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration-options.mdcore-operations.mdindex.mdpattern-utilities.mdtask-management.md
tile.json

tessl/npm-fast-glob

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fast-glob@3.3.x

To install, run

npx @tessl/cli install tessl/npm-fast-glob@3.3.0

index.mddocs/

fast-glob

fast-glob is a high-performance file system traversal library for Node.js that enables developers to find files and directories using glob patterns. It provides async, sync, and stream APIs with advanced pattern matching, cross-platform path handling, and extensive configuration options for maximum flexibility.

Package Information

  • Package Name: fast-glob
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install fast-glob

Core Imports

import fg from "fast-glob";

For CommonJS:

const fg = require("fast-glob");

Alternative imports:

import * as fg from "fast-glob";
// Access via fg.glob, fg.sync, fg.stream

// Import specific functions and types
import { 
  glob, 
  sync, 
  stream, 
  generateTasks, 
  isDynamicPattern, 
  escapePath, 
  convertPathToPattern 
} from "fast-glob";

// Import types
import type { Options, Entry, Task, Pattern, FileSystemAdapter } from "fast-glob";

Basic Usage

import fg from "fast-glob";

// Async (Promise-based) - most common usage
const files = await fg(['src/**/*.ts', '!src/**/*.spec.ts']);
// ['src/index.ts', 'src/utils.ts', 'src/lib/helper.ts']

// Synchronous
const filesSync = fg.sync(['**/*.js'], { cwd: './dist' });

// Stream
const stream = fg.stream(['**/*.md']);
for await (const file of stream) {
  console.log(file);
}

// Object mode with file stats
const entries = await fg(['**/*'], { 
  objectMode: true, 
  stats: true 
});
// [{ name: 'file.js', path: '/full/path/file.js', stats: Stats, ... }]

Architecture

fast-glob is built around several key components:

  • Multiple APIs: Async (Promise), synchronous, and streaming interfaces for different use cases
  • Pattern Engine: Advanced glob pattern matching with support for negative patterns, brace expansion, and extended globs
  • Task System: Internal task generation that optimizes file system traversal by grouping patterns by base directory
  • Cross-Platform: Unified API with platform-specific path utilities for Windows and POSIX systems
  • Performance Optimization: Concurrent directory reading with configurable concurrency limits
  • File System Abstraction: Pluggable file system adapter for testing and custom implementations

Capabilities

Core Glob Operations

Primary file matching functionality supporting async, sync, and stream patterns with comprehensive glob syntax support.

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

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

function fg(
  patterns: string | string[], 
  options: Options & { stats: true }
): Promise<Entry[]>;

Core Operations

Pattern Utilities

Helper functions for working with glob patterns including dynamic pattern detection, path escaping, and pattern conversion.

function isDynamicPattern(pattern: string, options?: Options): boolean;
function escapePath(path: string): string;
function convertPathToPattern(path: string): string;

namespace posix {
  function escapePath(path: string): string;
  function convertPathToPattern(path: string): string;
}

namespace win32 {
  function escapePath(path: string): string;
  function convertPathToPattern(path: string): string;
}

Pattern Utilities

Task Management

Internal task generation system that optimizes file system traversal by analyzing patterns and grouping them efficiently.

function generateTasks(patterns: string | string[], options?: Options): Task[];

interface Task {
  base: string;
  dynamic: boolean;
  patterns: string[];
  positive: string[];
  negative: string[];
}

Task Management

Configuration Options

Comprehensive configuration system controlling matching behavior, output format, performance, and file system interaction.

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

Configuration Options

Core Types

import type { Stats, Dirent } from "fs";

type Pattern = string;

interface Entry {
  /** The last part of the path (basename) */
  name: string;
  /** Full path relative to the pattern base directory */
  path: string;
  /** Instance of fs.Dirent */
  dirent: Dirent;
  /** File system stats (when stats: true) */
  stats?: Stats;
}

type EntryItem = string | Entry;

interface FileSystemAdapter {
  lstat: typeof import("fs").lstat;
  lstatSync: typeof import("fs").lstatSync;
  stat: typeof import("fs").stat;
  statSync: typeof import("fs").statSync;
  readdir: typeof import("fs").readdir;
  readdirSync: typeof import("fs").readdirSync;
}