# roots-util

> a utility for building roots extensions

Latest version **0.2.0** (published 2016-01-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install roots-util
pnpm add roots-util
yarn add roots-util
bun add roots-util
```

## 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.0 |
| Published | 2016-01-12 |
| First published | 2014-03-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=0.10.0 |
| Dependencies | 8 |
| Known vulnerabilities | 0 (+6 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 7 |
| Author | Jeff Escalante |
| Maintainers | jenius |
| Keywords | roots, extension, utility |

## Links

- npm: https://www.npmjs.com/package/roots-util
- Repository: https://github.com/carrot/roots-util
- Homepage: https://github.com/carrot/roots-util#readme
- Issues: https://github.com/carrot/roots-util/issues
- npm.io page: https://npm.io/package/roots-util

## Dependencies (8)

- [glob](https://npm.io/package/glob.md) 6.x
- [when](https://npm.io/package/when.md) 3.x
- [vinyl](https://npm.io/package/vinyl.md) 1.1.x
- [colors](https://npm.io/package/colors.md) 1.x
- [lodash](https://npm.io/package/lodash.md) 3.x
- [mkdirp](https://npm.io/package/mkdirp.md) 0.5.x
- [rimraf](https://npm.io/package/rimraf.md) 2.x
- [minimatch](https://npm.io/package/minimatch.md) 3.x

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2016-01-12
- 0.1.0 — 2014-09-29
- 0.0.5 — 2014-07-29
- 0.0.4 — 2014-03-31
- 0.0.3 — 2014-03-31
- 0.0.2 — 2014-03-25
- 0.0.1 — 2014-03-25

## README

Roots Util
----------

[![npm](http://img.shields.io/npm/v/roots-util.svg?style=flat)](http://badge.fury.io/js/roots-util) [![tests](http://img.shields.io/travis/carrot/roots-util/master.svg?style=flat)](https://travis-ci.org/carrot/roots-util) [![dependencies](http://img.shields.io/gemnasium/carrot/roots-util.svg?style=flat)](https://gemnasium.com/carrot/roots-util) [![Coverage Status](http://img.shields.io/coveralls/carrot/roots-util.svg?style=flat)](https://coveralls.io/r/carrot/roots-util?branch=master)

A utility that makes building roots extensions a little easier.

### Why should you care?

Roots extensions, while quite powerful, can be complex to build, and difficult if you don't understand how roots core works thoroughly. Roots util provides utilities you can use to abstract common functionality if/when you need it.

### Installation

```
npm install roots-util
```

### Usage

Roots-util simply provides a bunch of utility functions, which are documented below. Before using any of them, you want to create an instance of roots-util, typically by passing through the roots object from the constructor as such:

```coffee
RootsUtil = require 'roots-util'

class TestExtension
  constructor: (@roots) ->
    @util = new RootsUtil(@roots)
```

#### write(path, contents)

Writes a given relative path (starting at the roots public output directory) with the given content.

**Example:**  
```coffee
compile_hooks:
  write: => @util.write('testing.html', '<p>wow</p>')
```

This example will write to `public/testing.html` (or whatever the output directory was set to), and will also create any directories that were not already present. For example, if you wanted to write to `public/foobar/testing.html`, and the `foobar` directory didn't exist, it would create that directory rather than erroring out.

#### files(minimatch_str)

Given a minimatch string or array of minimatch strings, this function will grab all files in your roots project that match, excluding directories and files that were ignored by the roots config. Returns an array of [vinyl](https://github.com/wearefractal/vinyl)-wrapped files.

**Example:**  
```coffee
constructor: (roots) ->
  util = new RootsUtil(roots)
  @css_files = util.files('assets/css/**').map((f) -> f.relative)

fs: ->
  detect: (f) => @css_files.indexOf(f.relative) > -1
```

This example pulls all non-ignored files in the css directory and tests whether we have a match in the `fs.detect` function. There are many other ways this can be used, just a quick example here.

#### output_path(path, ext)

Given the path to a source file in a roots project, produces the output path that it will be written to. Accepts an optional extension override (by default will return with the same file extension as the input). Returns a [vinyl](https://github.com/wearefractal/vinyl)-wrapped file object.

**Example:**  
```coffee
compile_hooks: ->
  write: (ctx) =>
    out = @util.output_path(ctx.file.path).relative.split('.')
    out.splice(-1, 0, 'min')
    { path: out.join() }
```

In this example, we calculate the output path, add a `.min` extension, and pass that path in as the new path to be written. Again, contrived and this utility function can be used in many other ways, just a quick usage example.

#### with_extension(f, ext)

For use with the `detect` function, this is a helper that allows you to easily detect file extensions. Consider this a less powerful, but simpler version of the `files` helper. This function can accept a string or an array.

**Example:**  
```coffee
constructor: (@roots) ->
  @util = new RootsUtil(@roots)

fs: ->
  category: 'markdown'
  extract: true
  detect: (f) => @util.with_extension(f, ['md', 'markdown'])
```

### Test Helpers

Roots-Util also includes a number of test helpers that might make testing your extensions a bit easier. The test helpers can be accessed as seen below:

```coffee
path      = require 'path'
RootsUtil = require 'root-util'

# basic initialization
helpers = new RootsUtil.Helpers
# you can also initialize with a base fixtures directory, for example
helpers2 = new RootsUtil.Helpers(base: path.join(__dirname, 'fixtures'))
```

If you instantiate your helper with a base path, that base will be joined to any file path that's passed into any of the helper functions. Otherwise, you'll need to pass the full path. This `helpers` instance has a bunch of functions you can use to help out with your tests, documented below:

##### file.exists(path)
tests whether a file exists

##### file.doesnt_exist(path)
tests whether a file doesn't exist

##### file.has_content(path)
tests whether a file contains any content

##### file.is_empty(path)
tests whether a file contains no content

##### file.contains(path, string)
tests whether a file's contents contain a given string

##### file.contains_match(path, regex)
tests whether a file's content match a given regex

##### file.matches_file(path, path2)
tests whether a file's contents match a second file's contents

##### directory.is_directory(path)
tests whether a path is a directory

##### directory.exists(path)
tests whether a path is a directory and exists

##### directory.doesnt_exist(path)
tests whether a path does not exist

##### directory.has_contents(path)
tests whether a directory contains files

##### directory.is_empty(path)
tests whether a directory doesn't contain files

##### directory.contains_file(dirpath, filename)
tests whether a directory contains a file with a given filename

##### directory.matches_dir(path, path2)
tests whether a directory's contents match that of a second directory

##### project.compile(Roots, path)
returns a promise, compiles a roots project given the `Roots` class and a path for the project.

##### project.remove_folders(minimatchString)
given a minimatch string, removes all folders that match (good for removing public folders after tests have completed)

##### project.install_dependencies(baseDir, callback)
given a base directory (minimatch compatible), installs dependencies for any matches of `baseDir/package.json` then hits a callback

### License & Contributing

- Details on the license [can be found here](LICENSE.md)
- Details on running tests and contributing [can be found here](contributing.md)

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