@fnet/list-files

This project is a simple utility designed to list files matching specified patterns within a directory. It is primarily used to retrieve an array of file paths based on the defined criteria, supporting versatile pattern matching with additional options to customize the search. It leverages the functionality provided by the 'glob' library to achieve this.

How It Works

The utility operates by accepting a directory and a pattern (or patterns) to match files within the specified directory. It resolves the directory path, and then uses these inputs along with several optional parameters to generate a list of file paths that align with the given criteria.

Key Features

• Pattern Matching: Search for files using simple pattern syntax.
• Directory Specification: Specify the directory to search within; defaults to the current working directory if not provided.
• Inclusion of Dot Files: Option to include or exclude dot files (hidden files).
• Exclude Directories: Decide whether to include directories in the results.
• Ignore Patterns: Set patterns to ignore certain files or directories.
• Absolute Paths: Choose whether the returned paths are absolute.
• Base Matching: Match patterns against the basename of the files.
• Follow Symbolic Links: Option to follow symbolic links in the search.

Conclusion

This project provides a straightforward means of listing files via pattern matching, offering flexibility with several configuration options. It serves as a convenient tool for developers needing to work with file lists in Node.js environments, providing functionality akin to that of the 'glob' library.

Developer Guide for @fnet/list-files

Overview

The @fnet/list-files library is a simple tool designed to help developers list files in a specified directory matching given patterns. It leverages the familiar glob pattern syntax to allow users to flexibly filter the files they are interested in. The primary function exported by this library, index, lets you specify patterns and options to customize the file listing process, making it easy to integrate into file management tasks.

Installation

To use the @fnet/list-files library in your project, install it via npm or yarn:

npm install @fnet/list-files

or

yarn add @fnet/list-files

Usage

Basic Example

Start by importing the index function from the @fnet/list-files library. You can use this function to list files in a directory based on your specified pattern and options.

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

const files = listFiles({
  dir: './src',      // Directory to search in
  pattern: '*.js',   // Pattern to match JavaScript files
});

console.log(files); // Outputs list of JavaScript files in the './src' directory

Customizing Options

You can further customize the search by using additional options like nodir, dot, ignore, absolute, matchBase, and follow. Each of these options influences how files are listed:

• nodir: When set to true, directories will not be included in the results.
• dot: Include files starting with a dot (e.g., .gitignore). Defaults to true.
• ignore: Patterns to exclude from the results.
• absolute: Outputs absolute paths if set to true.
• matchBase: When true, matches a pattern to a file path's basename.
• follow: Follows symbolic links if set to true.

Advanced Example

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

// Search for all files except ignored ones, include dotfiles, and provide absolute paths
const files = listFiles({
  dir: './src',        // Directory to search in
  pattern: '**/*.js',  // Pattern to match all JavaScript files recursively
  ignore: 'node_modules/**',  // Ignore files in the node_modules directory
  dot: true,           // Include dotfiles
  absolute: true,      // Return absolute file paths
});

console.log(files); // Outputs absolute paths of all matching JavaScript files

Examples

Listing All Files in a Directory

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

const allFiles = listFiles({
  dir: '/my-project',
  pattern: '**/*', // Match all files and subdirectories
});

console.log(allFiles);

Ignoring Specific File Types

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

const filesWithoutImages = listFiles({
  dir: '/my-project',
  pattern: '**/*',
  ignore: ['**/*.png', '**/*.jpg'], // Ignore image files
});

console.log(filesWithoutImages);

Acknowledgement

The @fnet/list-files library uses glob, a well-known pattern-matching library, to perform its file search operations, allowing it to leverage powerful and flexible pattern matching capabilities.

Input Schema

$schema: https://json-schema.org/draft/2020-12/schema
title: DirectoryGlobSchema
description: Schema for directory globbing function arguments
type: object
properties:
  dir:
    type: string
    description: Root directory for glob pattern matching; defaults to the current
      working directory.
  pattern:
    type:
      - string
      - array
    items:
      type: string
    description: Glob pattern(s) to match files.
    default: "*"
  nodir:
    type: boolean
    description: If true, matches will exclude directories.
    default: false
  dot:
    type: boolean
    description: If true, files/directories starting with '.' will be matched.
    default: true
  ignore:
    type:
      - string
      - array
    items:
      type: string
    description: Glob pattern(s) to exclude files.
    default: []
  absolute:
    type: boolean
    description: If true, returns absolute paths.
    default: false
  matchBase:
    type: boolean
    description: If true, patterns without slashes will match against the basename.
    default: false
  follow:
    type: boolean
    description: If true, symbolic links will be followed.
    default: false
required: []