# @fnet/list-files

Latest version **0.1.31** (published 2025-10-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @fnet/list-files
pnpm add @fnet/list-files
yarn add @fnet/list-files
bun add @fnet/list-files
```

Provides the command `fnet-list-files`.

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.31 |
| Published | 2025-10-08 |
| First published | 2024-02-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 71.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | serdar986, serdark, gboyraz |

## Links

- npm: https://www.npmjs.com/package/@fnet/list-files
- Repository: https://gitlab.com/fnetai/list-files
- npm.io page: https://npm.io/package/@fnet/list-files

## Dependencies (2)

- [glob](https://npm.io/package/glob.md) ^11.0
- [@fnet/args](https://npm.io/package/@fnet/args.md) ^0.1

## Recent versions

- 0.1.31 (latest) — 2025-10-08
- 0.1.30 — 2025-04-30
- 0.1.29 — 2024-10-14
- 0.1.28 — 2024-10-14
- 0.1.27 — 2024-10-14
- 0.1.26 — 2024-10-10
- 0.1.25 — 2024-10-10
- 0.1.24 — 2024-10-08
- 0.1.23 — 2024-10-08
- 0.1.22 — 2024-07-23
- 0.1.21 — 2024-02-11
- 0.1.20 — 2024-02-10
- 0.1.19 — 2024-02-10
- 0.1.18 — 2024-02-10
- 0.1.17 — 2024-02-10

## README

# @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:

```bash
npm install @fnet/list-files
```

or

```bash
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.

```javascript
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

```javascript
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

```javascript
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

```javascript
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

```yaml
$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: []

```

---
_Source: https://npm.io/package/@fnet/list-files · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._