README.md · zaaack/foy

# Foy

[![Build Status](https://travis-ci.org/zaaack/foy.svg?branch=master)](https://travis-ci.org/zaaack/foy) [![npm](https://img.shields.io/npm/v/foy.svg)](https://www.npmjs.com/package/foy) [![npm](https://img.shields.io/npm/dm/foy.svg)](https://www.npmjs.com/package/foy) [![install size](https://packagephobia.now.sh/badge?p=foy)](https://packagephobia.now.sh/result?p=foy)

A simple, light-weight and modern task runner for general purpose.

## Contents

- [Foy](#foy)
  - [Contents](#contents)
  - [Features](#features)
  - [Install](#install)
  - [Write a Foyfile](#write-a-foyfile)
  - [Using with built-in promised-based API](#using-with-built-in-promised-based-api)
  - [Using with other packages](#using-with-other-packages)
  - [Using dependencies](#using-dependencies)
  - [Using namespaces](#using-namespaces)
  - [Useful utils](#useful-utils)
    - [fs](#fs)
    - [logger](#logger)
    - [exec command](#exec-command)
  - [Using in CI servers](#using-in-ci-servers)
  - [Using lifecycle hooks](#using-lifecycle-hooks)
  - [run task in task](#run-task-in-task)
  - [Watch and build](#watch-and-build)
  - [Using with custom compiler](#using-with-custom-compiler)
  - [API documentation](#api-documentation)
  - [License](#license)

## Features

- Promise-based tasks and built-in utilities.
- <a href="https://github.com/shelljs/shelljs" target="_blank">shelljs</a> like commands
- Easy to learn, stop spending hours for build tools.
- Small install size
  - foy: [![install size](https://packagephobia.now.sh/badge?p=foy)](https://packagephobia.now.sh/result?p=foy)
  - gulp: [![install size](https://packagephobia.now.sh/badge?p=gulp)](https://packagephobia.now.sh/result?p=gulp)
  - grunt: [![install size](https://packagephobia.now.sh/badge?p=grunt)](https://packagephobia.now.sh/result?p=grunt)

![GIF](https://github.com/zaaack/foy/blob/master/docs/capture.gif?raw=true)

## Install

```sh
yarn add -D foy # or npm i -D foy
```

Or Install globally with

```sh
yarn add -g foy # or npm i -g foy
```

## Write a Foyfile

You need to add a Foyfile.js(or Foyfile.ts with [ts-node](https://github.com/TypeStrong/ts-node) installed) in your project root.

Also, you can simply generate a Foyfile.js via:

```sh
foy --init
```

Then it will put a simple `Foyfile.js` in current folder:

```js
// Foyfile.js
const { task } = require('foy')

task('build', async ctx => {
  await ctx.exec('tsc')
})
```

You can also generate a `Foyfile.ts` via

```sh
foy --init ts
```

Then we can run `foy build` to execute the `build` task.

```sh
foy build
```

You can also add some options and description to a single task:

```ts
import { task, desc, option, strict } from 'foy'

desc('Build ts files with tsc')
option('-w, --watch', 'watch file changes')
strict() // This will throw an error if you passed some options that doesn't defined via `option()`
task('build', async ctx => {
  await ctx.exec(`tsc ${ctx.options.watch ? '-w' : ''}`)
})
```

```sh
foy build -w
```

Warning! If you want to set flags like strict to all tasks, please use `setGlobalOptions`, e.g.

```ts
import { setGlobalOptions } from 'foy'

setGlobalOptions({ strict: true }) // all tasks' options will be strict.

option('-aa') // strict via default
task('dev', async ctx => {

})
option('-bb') // strict via default
task('build', async ctx => {

})

```

## Using with built-in promised-based API

```ts
import { fs, task } from 'foy'

task('some task', async ctx => {
  await fs.rmrf('/some/dir/or/file') // Remove directory or file
  await fs.copy('/src', '/dist') // Copy folder or file
  let json = await fs.readJson('./xx.json')
  await ctx
    .env('NODE_ENV', 'production')
    .cd('./src')
    .exec('some command') // Execute an command
  let { stdout } = await ctx.exec('ls', { stdio: 'pipe' }) // Get the stdout, default is empty because it's redirected to current process via `stdio: 'inherit'`.
})
```

## Using with other packages

```ts
import { task, logger } from 'foy'
import * as axios from 'axios'

task('build', async ctx => {
  let res = await axios.get('https://your.server/data.json')
  logger.info(res.data)
})
```

## Using dependencies

```ts

import { task } from 'foy'
import * as axios from 'axios'

task('test', async ctx => {
  await ctx.exec('mocha')
})

task('build', async ctx => {
  let res = await axios.get('https://your.server/data.json')
  console.log(res.data)
  await ctx.exec('build my awesome project')
})
task(
  'publish:patch',
  ['test', 'build'], // Run test and build before publish
  async ctx => {
    await ctx.exec('npm version patch')
    await ctx.exec('npm publish')
  }
)
```

Dependencies are running serially by default, but you can specific them running concurrently.

e.g. Passing running options to dependencies.

```ts
task(
  'publish:patch',
  [{
    name: 'test',
    async: true, // run test parallelly
    force: true, // force rerun test whether it is executed before or not,
  }, {
    name: 'build',
    async: true,
    force: true,
  },],
  async ctx => {
    await ctx.exec('npm version patch')
    await ctx.exec('npm publish')
  }
)

/* Sugar version */
task(
  'publish:patch',
  [ 'test'.async().force(),
    'build'.async().force() ],
  async ctx => {
    await ctx.exec('npm version patch')
    await ctx.exec('npm publish')
  }
)

/*
Priority for async tasks

Default is 0, bigger is formmer, then we will run `build` before `test`.
If you have multi async dependencies with same priority, they will be executed parallel.
*/
task(
  'publish:patch',
  [ 'test'.async(0).force(),
    'build'.async(1).force() ],
  async ctx => {
    await ctx.exec('npm version patch')
    await ctx.exec('npm publish')
  }
)
```

You can also pass options to dependences:

```ts
task('task1', async ctx => {
  console.log(ctx.options) // "{ forceRebuild: true, lazyOptions: 1 }"
  console.log(ctx.global.options) // options from command line "{ a: 1 }"
})

task('task2', [{
  name: 'task1',
  options: {
    forceRebuild: true,
  },
  // Some options that rely on ctx or asynchronization,
  // it will be merged to options.
  resolveOptions: async ctx => {
    return { lazyOptions: 1 }
  }
}])

// foy task2 -a 1
```

## Using namespaces

If you have lots of tasks, naming might be a problem, what foy do is to making life easier, but more anxious. So we provide a `namespace` function to group tasks with namespaces.

```ts
import { task, namespace } from 'foy'

namespace('client', ns => {
  before(() => {
    logger.info('before')
  })
  after(() => {
    logger.info('after')
  })
  onerror(() => {
    logger.info('onerror')
  })
  task('start', async ctx => { /* ... */ }) // client:start
  task('build', async ctx => { /* ... */ }) // client:build
  task('watch', async ctx => { /* ... */ }) // client:watch
  namespace('proj1', ns => { // nested namespace
    onerror(() => {
      logger.info('onerror', ns)
    })
    task('start', async ctx => { /* ... */ }) // client:proj1:start

})
})

namespace('server', ns => {
  task('build', async ctx => { /* ... */ }) // server:build
  task('start', async ctx => { /* ... */ }) // server:start
  task('watch', async ctx => { /* ... */ }) // server:watch
})

task('start', ['client:start'.async(), 'server:start'.async()]) // start

// foy start
// foy client:build
```

## Useful utils

### fs

Foy wrap fs module with promises, so we can use it in async/await smoothly. Foy also implements some useful functions for build scripts which missing in nodejs built-in modules.

```ts
import { fs } from 'foy'

task('build', async ctx => {
  let f = await fs.readFileSync('./assets/someFile')

// copy file or directory
  await fs.copy('./fromPath', './toPath')

// watch a directory
  await fs.watchDir('./src', (event, filename) => {
    logger.info(event, filename)
  })

// make directory with parent directories
  await fs.mkdirp('./some/directory/with/parents/not/exists')

// write file will auto create missing parent directories
  await fs.outputFile('./some/file/with/parents/not/exists', 'file data')

// write json file will auto create missing parent directories
  await fs.outputJson('./some/file/with/parents/not/exists', {text: 'json data'})
  let file = await fs.readJson('./some/jsonFile')

// iterate directory tree
  await fs.iter('./src', async (path, stat) => {
    if (stat.isDirectory()) {
      logger.info('directory:', path)
      // skip scan node_modules
      if (path.endsWith('node_modules')) {
        return true
      }
    } else if (stat.isFile()) {
      logger.warn('file:', path)
    }
  })
})
```

### logger

Light weight built-in logger

```ts
import { logger } from 'foy'

task('build', async ctx => {

logger.debug('debug', { aa: 1})
  logger.info('info')
  logger.warn('warn')
  logger.error('error')

})

```

### exec command

A simple wrapper for sindresorhus' lovely module
[execa](https://github.com/sindresorhus/execa)

```ts
import { logger } from 'foy'

task('build', async ctx => {
  await ctx.exec('tsc')

// run multiple commands synchronously
  await ctx.exec([
    'tsc --outDir ./lib',
    'tsc --module es6 --outDir ./es',
  ])

// run multiple commands concurrently
  await Promise.all([
    ctx.exec('eslint'),
    ctx.exec('tsc'),
    ctx.exec('typedoc'),
  ])
})

```

## Using in CI servers

If you use Foy in CI servers, you might won't want the loading because most CI servers will log the stdout and stderr to files, the loading will be logged as frames. Luckily, Foy has already considered this use case, you can simple disable the loading behavior like this:

```ts
import { task, setGlobalOptions } from 'foy'

setGlobalOptions({ loading: false }) // disable loading animations

task('test', async cyx => { /* ... */ })
/*
$ foy test
DependencyGraph for task [test]:
─ test

Task: test
...
*/
```

## Using lifecycle hooks

You can use before/after/onerror to do something in lifecycles.

```ts
import { before, after, onerror } from 'foy'
before(() => { // do something before all tasks tree start
  // ...
})
after(() => { // do something after all tasks tree finished
  // ...
})
onerror((err) => { // do something when error happens
  // ...
})
```

## run task in task

```ts

task('task1', async ctx => { /* ... */ })
task('task2', async ctx => {
  // do things before task1

// run task1 manually, so we can
  // do things before or after it
  await ctx.run('task1')

// do things after task1
})

```

## Watch and build

```ts

task('build', async ctx => { /* build your project */ })
task('run', async ctx => { /* start your project */ })

let p = null
task('watch', async ctx => {
  ctx.fs.watchDir('./src', async (evt, file) => {
    await ctx.run('build')
    p && !p.killed && p.kill()
    p = await ctx.run('run')
  })
})
```

## Using with custom compiler

```sh

# Write Foyfile in ts, enabled by default
foy -r ts-node/register -c ./some/Foyfile.ts build

# Write Foyfile in coffee
foy -r coffeescript/register -c ./some/Foyfile.coffee build

```

## API documentation

<https://zaaack.github.io/foy/api>

## License

MIT

zaaack/foy

简介

发行版

贡献者

近期动态

zaaack/foy .gitee-modal { width: 500px !important; }

简介

发行版

开源评估指数源自 OSS-Compass 评估体系，评估体系围绕以下三个维度对项目展开评估：

贡献者

近期动态

搜索帮助

zaaack/foy