@dephub/glob 🌟

Enhanced glob utility with gitignore support, pattern negation, and flexible filtering. A modern alternative to traditional glob libraries with better defaults and TypeScript support.

Features ✨

• 🎯 Pattern Negation - Support for !pattern to exclude files
• 📁 Gitignore Support - Automatic respect for .gitignore rules
• 🔧 Sensible Defaults - Ignore node_modules, .git by default
• 🌐 Cross-Platform - Windows and POSIX path normalization
• 🔒 Type Safe - Full TypeScript support with precise types
• ⚡ Fast - Optimized traversal with parallel processing
• 🎪 Flexible Filtering - Dotfiles, symlinks, case sensitivity options

Installation 📦

npm install @dephub/glob
# or
pnpm add @dephub/glob
# or
yarn add @dephub/glob

Quick Start 🚀

import { glob } from '@dephub/glob';

// Find all TypeScript files excluding tests
const files = await glob(['src/**/*.ts', '!**/*.test.ts']);

// With gitignore support and absolute paths
const projectFiles = await glob('**/*', {
  gitignore: true,
  absolute: true,
  onlyFiles: true,
});

Usage Examples 🎯

Basic File Discovery

import { glob } from '@dephub/glob';

// All source files
const sourceFiles = await glob('src/**/*.{js,ts}');

// Multiple patterns with exclusion
const assets = await glob([
  '**/*.png',
  '**/*.jpg',
  '!**/node_modules/**',
  '!**/dist/**',
]);

// From specific directory
const configFiles = await glob('**/*.json', {
  projectRoot: './config',
});

Advanced Filtering

import { glob } from '@dephub/glob';

// Respect gitignore and include dotfiles
const allFiles = await glob('**/*', {
  gitignore: true,
  dot: true,
  onlyFiles: true,
});

// Case-insensitive search
const caseInsensitive = await glob('**/*.JSX', {
  ignoreCase: true,
});

// Follow symbolic links
const withSymlinks = await glob('**/*', {
  followSymlinks: true,
});

Project Configuration

import { glob } from '@dephub/glob';

// Common project setup
const projectFiles = await glob(['**/*', '!**/node_modules/**'], {
  projectRoot: process.cwd(),
  gitignore: true,
  onlyFiles: true,
  dot: false,
  ignores: ['*.log', 'temp/**'],
});

API Reference 📚

glob(pattern, options)

The main glob function that returns a promise resolving to matched file paths.

Parameters:

• pattern (string | string[]) - Glob pattern or array of patterns. Use !pattern for exclusion.
• options (Options) - Configuration options

Returns: Promise<string[]>

Options

| Option | Type | Default | Description | | ---------------- | -------- | --------------- | ---------------------------------- | | projectRoot | string | process.cwd() | Root directory for search | | ignores | string[] | [] | Additional patterns to ignore | | ignoreCase | boolean | false | Case-insensitive matching | | gitignore | boolean | false | Respect .gitignore files | | onlyFiles | boolean | false | Return only files, not directories | | dot | boolean | false | Include dotfiles (e.g., .env) | | followSymlinks | boolean | false | Follow symbolic links | | absolute | boolean | false | Return absolute paths |

Pattern Syntax 🎪

Positive Patterns

// Include all TypeScript files
await glob('src/**/*.ts');

// Multiple file extensions
await glob('src/**/*.{js,ts,jsx,tsx}');

Negative Patterns (Exclusion)

// Exclude test files and node_modules
await glob([
  'src/**/*.ts',
  '!**/*.test.ts',
  '!**/*.spec.ts',
  '!node_modules/**',
]);

Advanced Patterns

// Complex inclusion/exclusion
await glob([
  '**/*.ts',
  '!**/dist/**',
  '!**/node_modules/**',
  '!**/*.d.ts',
  '**/*.js',
  '!**/vendor/**',
]);

Common Use Cases 🔧

Build System Integration

import { glob } from '@dephub/glob';

const sourceFiles = await glob(
  ['src/**/*.{js,ts}', '!**/*.test.*', '!**/*.spec.*'],
  {
    gitignore: true,
    onlyFiles: true,
  },
);

Asset Collection

const assets = await glob(
  [
    '**/*.{png,jpg,svg,gif}',
    '**/*.{woff,woff2,ttf}',
    '!node_modules/**',
    '!dist/**',
  ],
  {
    onlyFiles: true,
  },
);

Configuration Discovery

const configFiles = await glob(
  ['**/*config*.{json,js,ts}', '**/.env*', '!node_modules/**'],
  {
    dot: true,
    gitignore: true,
  },
);

Integration Examples 🔗

With File Operations

import { glob } from '@dephub/glob';
import { readFile, writeFile } from '@dephub/read-write';

// Process all Markdown files
const markdownFiles = await glob('**/*.md', {
  gitignore: true,
  onlyFiles: true,
});

for (const file of markdownFiles) {
  const content = await readFile(file, 'utf-8');
  const processed = transformContent(content);
  await writeFile(file, processed);
}

With Testing Frameworks

import { glob } from '@dephub/glob';

// Find all test files
const testFiles = await glob('**/*.{test,spec}.{js,ts}', {
  ignores: ['node_modules/**', 'dist/**'],
});

// Configure test runner with found files
configureTests(testFiles);

CLI Tool Integration

#!/usr/bin/env node
import { glob } from '@dephub/glob';

const patterns = process.argv.slice(2);
const files = await glob(patterns, {
  gitignore: true,
  onlyFiles: true,
});

console.log(files.join('\n'));

Migration from Other Glob Libraries

From fast-glob

// Before
import fastGlob from 'fast-glob';
const files = await fastGlob(['**/*.ts', '!**/*.d.ts'], {
  ignore: ['node_modules/**'],
  dot: true,
});

// After
import { glob } from '@dephub/glob';
const files = await glob(['**/*.ts', '!**/*.d.ts'], {
  ignores: ['node_modules/**'],
  dot: true,
});

From globby

// Before
import { globby } from 'globby';
const files = await globby('**/*.ts', {
  gitignore: true,
  dot: true,
});

// After
import { glob } from '@dephub/glob';
const files = await glob('**/*.ts', {
  gitignore: true,
  dot: true,
});

Performance Tips ⚡

• Use onlyFiles: true when you don't need directories
• Set gitignore: true to avoid traversing ignored paths
• Use specific patterns instead of **/* when possible
• Combine multiple exclusions in a single ignores array

License 📄

MIT License – see LICENSE for details.

Author: Estarlin R (estarlincito.com)