# file-utils

> Sync file utility for Node.js command line tools

Latest version **0.2.2** (published 2015-02-06) · MIT license · 0 weekly downloads

## Install

```sh
npm install file-utils
pnpm add file-utils
yarn add file-utils
bun add file-utils
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.2 |
| Published | 2015-02-06 |
| First published | 2013-10-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 7 |
| Known vulnerabilities | 0 (+10 in 2 direct dependencies) |
| Install scripts | no |
| GitHub stars | 16 |
| Author | Simon Boudrias |
| Maintainers | sboudrias |
| Keywords | file, fs, utils, util, scaffold, tool, cli |

## Links

- npm: https://www.npmjs.com/package/file-utils
- Repository: https://github.com/SBoudrias/file-utils
- Issues: https://github.com/SBoudrias/file-utils/issues
- npm.io page: https://npm.io/package/file-utils

## Dependencies (7)

- [glob](https://npm.io/package/glob.md) ^4.3.5
- [lodash](https://npm.io/package/lodash.md) ^2.4.1
- [rimraf](https://npm.io/package/rimraf.md) ^2.2.2
- [minimatch](https://npm.io/package/minimatch.md) ^2.0.1
- [iconv-lite](https://npm.io/package/iconv-lite.md) ^0.4.3
- [findup-sync](https://npm.io/package/findup-sync.md) ^0.2.1
- [isbinaryfile](https://npm.io/package/isbinaryfile.md) ^2.0.1

## Alternatives

- [unionfs](https://npm.io/package/unionfs.md) — 2.2M weekly downloads
- [path-starts-with](https://npm.io/package/path-starts-with.md) — 35.9K weekly downloads
- [redzip](https://npm.io/package/redzip.md) — 1.2K weekly downloads
- [vscode-anymatch](https://npm.io/package/vscode-anymatch.md) — 848 weekly downloads
- [@ledgerhq/coin-filecoin](https://npm.io/package/@ledgerhq/coin-filecoin.md) — 793 weekly downloads

## Recent versions

- 0.2.2 (latest) — 2015-02-06
- 0.2.1 — 2014-08-26
- 0.2.0 — 2014-01-16
- 0.1.5 — 2013-11-18
- 0.1.4 — 2013-11-15
- 0.1.3 — 2013-11-14
- 0.1.2 — 2013-10-21
- 0.1.1 — 2013-10-20
- 0.1.0 — 2013-10-16
- 0.0.1 — 2013-10-05

## README

file-utils [![](https://travis-ci.org/SBoudrias/file-utils.png)](https://travis-ci.org/SBoudrias/file-utils)
==========

This is a Grunt.file forks to allow the creation of scoped file utilities and the ability to add write filters.

Same as Grunt.file, this is a set of _synchronous_ utility. As so, it should **never** be used on a Node.js server. This is meant for users/command line utilities.


File API
=========

Upcoming. Meanwhile, check [Grunt.file documentation](http://gruntjs.com/api/grunt.file) as the same methods are available.

#### Setting options - `file.option( name, [ value ])`

```
// Set option
file.option('write', false);

// Get option
file.option('write');
```

**Available Options**
- `write` (Boolean): If write is set to `false`, then no file will be written or deleted. Useful for test run without side effets.
- `logger` (Logger object): Used internally to log information to the console. **API still work in progress**
- `encoding` (String): Defaults `utf8`. Set the default encoding used for reading/writing. Note most methods allow you to overwridde it for a single run.
- `force` (Boolean): `force: true` Force the deletion of folders and file outside the utility scope (or CWD if no scope).


ENV scope and filters
=========

### Creating an Env - file#createEnv([ options ]);

```javascript
var file = require('file-utils');

var env = file.createEnv({
  base: 'my/scoped/path',
  dest: 'destination/path' // optionnal
});

// Alternatively, they can be functions returning a path:

var env = file.createEnv({
  base: function() {
    return 'my/scoped/path';
  },
  dest: function() { // optionnal
    return 'destination/path';
  }
});
```

The `base` directory will prefix any paths passed to `mkdir`, `recurse`, `read`, `readJSON`, `write`, `delete`, `exists`, `isLink`, `isDir` and `isFile` methods.

The `dest` directory will prefix the `destination` path provided in the `copy` method. Note that this option is optionnal and will default to the current working directory.

If [options (`logger`, `write`, etc)](#setting-options---fileoption-name--value-) are not passed, each `Env` instance inherit those of its parent.

Write Filters
---------

Write filters are applied on `env.write` and `env.copy`.

They're used to modifiy the content or the filepath of a file.

#### Add a write filter - `env.registerWriteFilter( name, filter )`

**options**
- `name` (String): The name under which registering the filter
- `filter` (Function): The filter function

The filter function take a file object as parameter. This file object is a hash containing a `path` and a `contents` property. You can modify these two property as you like and returning the modified object.

```javascript
env.registerWriteFilter( 'coffee', function( file ) {
  if (!path.extname(file) !== '.js') return file;

  file.path = file.path.replace(/(\.js)$/, '.coffee');
  file.content = convertJsToCoffee( file.contents );

  return file;
});
```

#### Remove a write filter - `env.removeWriteFilter( name )`

```javascript
env.removeWriteFilter('coffee');
```

#### Async filter

The filter can also be asynchronous. This is done by calling `this.async()` and passing the return value to the callback provided.

```javascript
env.registerWriteFilter( 'coffee', function( file ) {
  var done = this.async();

  // some process
  setTimeout(function() {
    done({ path: '/newfile', contents: 'filtered content' });
  }, 1000);
});
```

**Caution:** Using an asynchronous filter will change the way write and copy method are called to. This will make both of those method to run asynchronously too.

Validation Filters
----------

Validation filters are applied on `env.write` and `env.copy`.

They're used to allow or disallow the write action.

#### Add a validation filter - `env.registerValidationFilter( name, filter )`

**options**
- `name` (String): The name under which registering the filter
- `filter` (Function): The filter function

The filter function take a file object as parameter. This file object is a hash containing a `path` (String) and a `contents` (String if text file, Buffer otherwise) property.

Return `true` to allow the file to be written. Return `false` or an error message `String` to disallow the write action.

```javascript
env.registerValidationFilter( 'checkConflicts', function( toOutput ) {
  if ( file.exists(toOutput.path) ) {
    return 'file is already present';
  }
  return true;
});
```

Just like the write filters, [this filter can be asynchronous](#async-filter).

#### Remove a validation filter - `env.removeValidationFilter( name )`

```javascript
env.removeValidationFilter('checkConflicts');
```


Todos
=========

- Real Logging system

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