@fnet/up-list-files

Introduction

The @fnet/up-list-files project is a utility designed to help users search for files within a specified directory or the current working directory if none is specified. It aims to provide a convenient way to locate files based on specific patterns, offering flexibility through various search options.

How It Works

This tool operates by searching a given directory, or its parent directories if needed, to find files that match a provided pattern. You can specify the type of files you want to include or exclude by adjusting the search parameters such as directory depth, file visibility (including hidden files), and other pattern-related options.

Key Features

• Pattern Matching: Search for files using patterns that can be specified as strings or arrays.
• Directory Navigation: Automatically climbs up directory levels in search of files that match the pattern.
• File Type Filtering: Can filter results to include only files or directories, depending on user preference.
• Hidden Files: Allows for inclusion or exclusion of hidden files in the search results.
• Absolute Paths: Optionally retrieves file paths as absolute or relative to the starting directory.

Conclusion

@fnet/up-list-files serves as a practical tool for users looking to efficiently search for files based on specific patterns within a directory. With straightforward functionality and various customizable options, it helps in managing file searches with ease.

Developer Guide for @fnet/up-list-files

Overview

The @fnet/up-list-files library is a utility designed to help developers efficiently search and list files within a directory structure. By leveraging pattern matching similar to the glob package, it allows developers to specify patterns to find files, with options to control visibility, recursion, and path formats. This makes it ideal for any node.js project that requires file traversal and discovery.

Installation

To include @fnet/up-list-files in your project, you can use either npm or yarn:

npm install @fnet/up-list-files

or

yarn add @fnet/up-list-files

Usage

The main function provided by the library is the index function, which is used to list files in a directory structure based on specified patterns and options.

Basic Usage

To utilize the library, you will need to import it and then call the index function with the desired parameters. Here’s an example:

import listFiles from '@fnet/up-list-files';

const options = {
  dir: './src',            // Directory to start searching
  pattern: ['*.js'],       // Pattern to match files
  nodir: true,             // Do not include directories in results
  dot: true,               // Include dotfiles
  absolute: false,         // Return relative paths
  ignore: ['node_modules'],// Ignore specific paths
};

const files = listFiles(options);

console.log(files);

Advanced Usage

For more specific needs, such as searching beyond the initial directory or requiring verbose logs during the file search, adjust the options as necessary:

const options = {
  dir: './src',
  pattern: ['*.js', '*.jsx'],
  nodir: true,
  dot: true,
  absolute: true,        // Return absolute paths
  ignore: ['node_modules'],
  follow: true,          // Follow symbolic links
  matchBase: true,       // Match patterns against the base name
  verbose: true,         // Print directories as they are searched
};

const files = listFiles(options);

files.forEach(file => {
  console.log(`File found: ${file}`);
});

Examples

Here are some scenarios showing how @fnet/up-list-files can be used:

Example 1: Getting JavaScript files in a directory

const jsFiles = listFiles({
  dir: './lib',
  pattern: ['*.js'],
});
console.log(jsFiles);

Example 2: Including dotfiles and searching recursively

const dotAndJsFiles = listFiles({
  dir: './app',
  pattern: ['*.js', '.*'],
  dot: true,
  follow: true,
});
console.log(dotAndJsFiles);

Example 3: Ignoring specific directories

const filesExcludingNodeModules = listFiles({
  dir: './project',
  pattern: ['*'],
  ignore: ['node_modules', 'dist'],
});
console.log(filesExcludingNodeModules);

Acknowledgement

This project builds upon concepts inspired by file pattern matching utilities and open-source software practices. We acknowledge contributions from the Node.js community in enhancing file system navigation capabilities.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
  dir:
    type: string
    description: The directory to search in. Defaults to current working directory
      if not provided.
  pattern:
    oneOf:
      - type: string
        description: Glob pattern to match filenames, must be a relative path.
      - type: array
        items:
          type: string
          description: An array of glob patterns to match filenames, all must be relative
            paths.
    default:
      - "*"
    description: Pattern(s) to search for.
  nodir:
    type: boolean
    default: false
    description: When true, excludes directories from the results.
  dot:
    type: boolean
    default: true
    description: Include dotfiles in matching.
  absolute:
    type: boolean
    default: false
    description: When true, the results include absolute paths.
  ignore:
    oneOf:
      - type: string
        description: Pattern to ignore.
      - type: array
        items:
          type: string
          description: An array of patterns to ignore.
    description: Pattern(s) to ignore during search.
  follow:
    type: boolean
    default: false
    description: When true, follows symbolic links.
  matchBase:
    type: boolean
    default: false
    description: When true, performs matching based on the basename of the file.
  verbose:
    type: boolean
    default: false
    description: When true, enables verbose logging of the search process.
required: []