CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-glob-promise

Promise version of glob - wrapper around glob library providing Promise-based API

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

glob-promise

glob-promise provides a Promise-based wrapper around the popular glob library for Node.js, enabling asynchronous file pattern matching using shell-style wildcards and patterns. It transforms the callback-based glob API into a modern Promise-based interface, making it easier to integrate with async/await workflows and Promise chains.

Package Information

  • Package Name: glob-promise
  • Package Type: npm
  • Language: JavaScript (with TypeScript definitions)
  • Installation: npm install glob-promise glob

Core Imports

const glob = require('glob-promise');

For named imports:

const { promise, sync, hasMagic, Glob } = require('glob-promise');

TypeScript:

import glob = require('glob-promise');

Basic Usage

const glob = require('glob-promise');

// Basic promise-based globbing
glob('src/**/*.js')
  .then(files => {
    console.log('Found files:', files);
  })
  .catch(err => {
    console.error('Glob error:', err);
  });

// With async/await
async function findFiles() {
  try {
    const files = await glob('**/*.md');
    return files;
  } catch (error) {
    throw new Error(`Failed to find files: ${error.message}`);
  }
}

// With options
const files = await glob('lib/**/*.js', { 
  ignore: ['**/node_modules/**'],
  cwd: '/project/root'
});

// Using the callback-based glob function
const { glob: globCallback } = require('glob-promise');
globCallback('src/**/*.js', (err, files) => {
  if (err) throw err;
  console.log('Found files:', files);
});

Capabilities

Promise-based Globbing

The main export provides Promise-based file pattern matching using glob patterns.

/**
 * Promise-based glob function for file pattern matching
 * @param pattern - Glob pattern string (e.g., "src/**/*.js")
 * @param options - Optional glob options object
 * @returns Promise that resolves to array of matched file paths
 */
function glob(pattern: string, options?: import('glob').IOptions): Promise<string[]>;

Promise Function (Named Export)

Explicit named export of the main promise function.

/**
 * Named export of the promise-based glob function
 * @param pattern - Glob pattern string
 * @param options - Optional glob options object  
 * @returns Promise that resolves to array of matched file paths
 */
function promise(pattern: string, options?: import('glob').IOptions): Promise<string[]>;

Synchronous Globbing

Synchronous version of glob that returns results immediately.

/**
 * Synchronous glob function that returns results immediately
 * @param pattern - Glob pattern string
 * @param options - Optional glob options object
 * @returns Array of matched file paths
 */
function sync(pattern: string, options?: import('glob').IOptions): string[];

Usage Example:

const { sync } = require('glob-promise');

const files = sync('test/**/*.js');
console.log('Test files:', files);

Callback-based Globbing

Direct access to the original glob callback-based function via the glob export.

/**
 * Original callback-based glob function from glob library
 * @param pattern - Glob pattern string
 * @param options - Optional glob options object
 * @param callback - Callback function (err, matches) => void
 */
const { glob: globCallback } = require('glob-promise');
function globCallback(pattern: string, options?: import('glob').IOptions, callback?: (err: Error | null, matches: string[]) => void): void;
function globCallback(pattern: string, callback: (err: Error | null, matches: string[]) => void): void;

Usage Example:

const { glob: globCallback } = require('glob-promise');

// With options
globCallback('src/**/*.js', { ignore: '**/node_modules/**' }, (err, matches) => {
  if (err) throw err;
  console.log('Found files:', matches);
});

// Without options
globCallback('test/**/*.js', (err, matches) => {
  if (err) throw err;
  console.log('Test files:', matches);
});

Magic Pattern Detection

Tests whether a pattern contains glob magic characters (wildcards, brackets, etc.).

/**
 * Tests if a pattern contains glob magic characters
 * @param pattern - Pattern string to test
 * @param options - Optional glob options object
 * @returns True if pattern contains magic characters, false otherwise
 */
function hasMagic(pattern: string, options?: import('glob').IOptions): boolean;

Usage Example:

const { hasMagic } = require('glob-promise');

console.log(hasMagic('src/**/*.js')); // true
console.log(hasMagic('src/index.js')); // false
console.log(hasMagic('src/*.{js,ts}')); // true

Glob Class

Direct access to the underlying Glob class for advanced usage and streaming.

/**
 * Glob class constructor for advanced usage and streaming
 * @param pattern - Glob pattern string
 * @param options - Optional glob options object
 * @param callback - Optional callback function
 */
class Glob {
  constructor(pattern: string, options?: import('glob').IOptions, callback?: (err: Error | null, matches: string[]) => void);
  constructor(pattern: string, callback: (err: Error | null, matches: string[]) => void);
}

Usage Example:

const { Glob } = require('glob-promise');

const g = new Glob('**/*.js', { ignore: '**/node_modules/**' }, (err, matches) => {
  if (err) throw err;
  console.log('Found files:', matches);
});

// The Glob class is an EventEmitter
g.on('match', (match) => {
  console.log('Found:', match);
});

Types

/**
 * Type definition for the promise-based glob function
 */
type GlobPromise = (pattern: string, options?: import('glob').IOptions) => Promise<string[]>;

/**
 * Main export interface extending the promise function with utility exports
 */
interface Export extends GlobPromise {
  readonly glob: typeof import('glob');
  readonly Glob: typeof import('glob').Glob;
  readonly hasMagic: typeof import('glob').hasMagic;
  readonly sync: typeof import('glob').sync;
  readonly promise: GlobPromise;
}

The import('glob').IOptions interface contains all glob options including:

  • cwd?: string - Current working directory to search from
  • root?: string - Root directory to mount the filesystem
  • mark?: boolean - Add a / character to directory matches
  • nosort?: boolean - Don't sort the results
  • dot?: boolean - Include .dot files in normal matches
  • noglobstar?: boolean - Disable ** pattern expansion
  • nocase?: boolean - Case insensitive matching
  • ignore?: string | string[] - Glob patterns to ignore
  • follow?: boolean - Follow symbolic links
  • silent?: boolean - Suppress warnings and errors
  • strict?: boolean - Continue on errors
  • maxLength?: number - Maximum number of file system calls
  • And many more options from the glob library

Error Handling

The promise-based functions will reject with an error in the following cases:

  • Invalid pattern: When the pattern is not a string or is empty
  • File system errors: When there are permission issues or file system problems
  • Invalid options: When provided options contain invalid values
// Error handling example
try {
  const files = await glob('**/*.js');
  console.log('Files found:', files.length);
} catch (error) {
  if (error.message === 'invalid pattern') {
    console.error('Pattern must be a non-empty string');
  } else {
    console.error('Glob operation failed:', error.message);
  }
}

Compatibility Notes

  • Peer Dependency: Requires glob ^8.0.3 as a peer dependency
  • Node.js: Requires Node.js >= 16
  • Glob Library: This package wraps glob v8.x - newer versions of glob (v9+) have native Promise support
  • TypeScript: Full TypeScript definitions included with proper type inference

docs

index.md

tile.json