or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ignore-handling.mdindex.mdmain-globbing.mdutilities.md
tile.json

main-globbing.mddocs/

Main Globbing API

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;
}