Core Operations

/**
 * Find files matching glob patterns asynchronously
 * @param patterns - Single pattern or array of glob patterns
 * @param options - Configuration options
 * @returns Promise resolving to array of matching file paths
 */
function fg(patterns: string | string[], options?: Options): Promise<string[]>;

/**
 * Find files with entry objects when objectMode or stats is enabled
 * @param patterns - Single pattern or array of glob patterns
 * @param options - Configuration options with objectMode: true or stats: true
 * @returns Promise resolving to array of Entry objects
 */
function fg(
  patterns: string | string[], 
  options: Options & ({ objectMode: true } | { stats: true })
): Promise<Entry[]>;

// Aliases for async operation (accessed via fg.glob, fg.async)
fg.glob(patterns: string | string[], options?: Options): Promise<string[]>;
fg.async(patterns: string | string[], options?: Options): Promise<string[]>;

import fg from "fast-glob";

// Basic async usage
const jsFiles = await fg('src/**/*.js');
// ['src/index.js', 'src/utils.js', 'src/components/header.js']

// Multiple patterns with exclusions
const sourceFiles = await fg([
  'src/**/*.{js,ts}',
  '!src/**/*.spec.{js,ts}',
  '!src/**/*.test.{js,ts}'
]);

// Object mode for detailed file information
const entries = await fg('**/*.md', { 
  objectMode: true,
  cwd: './docs'
});
// [{ name: 'README.md', path: '/full/path/docs/README.md', dirent: Dirent }]

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

/**
 * Find files matching glob patterns synchronously
 * @param patterns - Single pattern or array of glob patterns
 * @param options - Configuration options
 * @returns Array of matching file paths
 */
function sync(patterns: string | string[], options?: Options): string[];

/**
 * Find files with entry objects when objectMode or stats is enabled
 * @param patterns - Single pattern or array of glob patterns
 * @param options - Configuration options with objectMode: true or stats: true
 * @returns Array of Entry objects
 */
function sync(
  patterns: string | string[], 
  options: Options & ({ objectMode: true } | { stats: true })
): Entry[];

// Alias for sync operation (accessed via fg.globSync)
fg.globSync(patterns: string | string[], options?: Options): string[];

import fg from "fast-glob";

// Basic sync usage
const configFiles = fg.sync('*.{json,yaml,yml}');
// ['package.json', 'tsconfig.json', 'docker-compose.yml']

// Sync with options
const testFiles = fg.sync('**/*.test.js', {
  cwd: './src',
  absolute: true
});
// ['/full/path/src/utils.test.js', '/full/path/src/helpers.test.js']

// Object mode sync
const directories = fg.sync('*/', { 
  objectMode: true,
  onlyDirectories: true 
});

/**
 * Find files matching glob patterns as a stream
 * @param patterns - Single pattern or array of glob patterns
 * @param options - Configuration options
 * @returns ReadableStream emitting matching file paths or Entry objects
 */
function stream(patterns: string | string[], options?: Options): NodeJS.ReadableStream;

// Alias for stream operation (accessed via fg.globStream)
fg.globStream(patterns: string | string[], options?: Options): NodeJS.ReadableStream;

import fg from "fast-glob";

// Basic stream usage
const stream = fg.stream('**/*.log');

// Process files as they are found
for await (const file of stream) {
  console.log(`Processing: ${file}`);
  // Process each file immediately
}

// Stream with async iterator
const logStream = fg.stream(['**/*.log', '**/*.txt'], {
  cwd: './logs',
  absolute: true
});

// Alternative: event-based stream handling
stream.on('data', (file) => {
  console.log('Found:', file);
});

stream.on('end', () => {
  console.log('Stream completed');
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

// Complex pattern examples
const complexMatch = await fg([
  'src/**/*.{js,ts}',           // All JS/TS files in src
  '!src/**/*.{spec,test}.*',    // Exclude test files
  'docs/**/*.md',               // Include markdown docs
  '!docs/internal/**'           // Exclude internal docs
]);

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