Contents

Features

Install

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

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

Write a Foyfile

foy --init

// Foyfile.jsconst{ task}=require('foy')task('build',asyncctx=>{awaitctx.exec('tsc')})

foy --init ts

foy build

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',asyncctx=>{awaitctx.exec(`tsc${ctx.options.watch ?'-w' :''}`)})

import{task,desc,option,strict}from'foy'typeBuildOptions={watch:boolean}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<BuildOptions>('build',asyncctx=>{// ctx.options now has type BuildOptions instead of unknownawaitctx.exec(`tsc${ctx.options.watch ?'-w' :''}`)})

foy build -w

import{setGlobalOptions}from'foy'setGlobalOptions({strict:true})// all tasks' options will be strict.option('-aa')// strict via defaulttask('dev',asyncctx=>{})option('-bb')// strict via defaulttask('build',asyncctx=>{})

Using with built-in promised-based API

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

Using with other packages

import{task,logger}from'foy'import*asaxiosfrom'axios'task('build',asyncctx=>{letres=awaitaxios.get('https://your.server/data.json')logger.info(res.data)})

Using dependencies

import{task}from'foy'import*asaxiosfrom'axios'task('test',asyncctx=>{awaitctx.exec('mocha')})task('build',asyncctx=>{letres=awaitaxios.get('https://your.server/data.json')console.log(res.data)awaitctx.exec('build my awesome project')})task('publish:patch',['test','build'],// Run test and build before publishasyncctx=>{awaitctx.exec('npm version patch')awaitctx.exec('npm publish')})

task('publish:patch',[{name:'test',async:true,// run test parallellyforce:true,// force rerun test whether it has been executed before or not.},{name:'build',async:true,force:true,},],asyncctx=>{awaitctx.exec('npm version patch')awaitctx.exec('npm publish')})/* Sugar version */task('publish:patch',['test'.async().force(),'build'.async().force()],asyncctx=>{awaitctx.exec('npm version patch')awaitctx.exec('npm publish')})/*Priority for async tasksDefault is 0, higher values will be run earlier; so, in this next example, `build` will be run before `test`.(Note: If you have multiple async dependencies with same priority, they will be executed in parallel.)*/task('publish:patch',['test'.async(0).force(),'build'.async(1).force()],asyncctx=>{awaitctx.exec('npm version patch')awaitctx.exec('npm publish')})

task('task1',asyncctx=>{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:asyncctx=>{return{lazyOptions:1}}}])// foy task2 -a 1

Using namespaces

import{task,namespace}from'foy'namespace('client',ns=>{before(()=>{logger.info('before')})after(()=>{logger.info('after')})onerror(()=>{logger.info('onerror')})task('start',asyncctx=>{/* ... */})// client:starttask('build',asyncctx=>{/* ... */})// client:buildtask('watch',asyncctx=>{/* ... */})// client:watchnamespace('proj1',ns=>{// nested namespaceonerror(()=>{logger.info('onerror',ns)})task('start',asyncctx=>{/* ... */})// client:proj1:start})})namespace('server',ns=>{task('build',asyncctx=>{/* ... */})// server:buildtask('start',asyncctx=>{/* ... */})// server:starttask('watch',asyncctx=>{/* ... */})// server:watch})task('start',['client:start'.async(),'server:start'.async()])// start// foy start// foy client:build

Useful utils

fs

import{fs}from'foy'task('build',asyncctx=>{letf=awaitfs.readFileSync('./assets/someFile')// copy file or directoryawaitfs.copy('./fromPath','./toPath')// watch a directoryawaitfs.watchDir('./src',(event,filename)=>{logger.info(event,filename)})// make directory with parent directoriesawaitfs.mkdirp('./some/directory/with/parents/not/exists')// write file will auto create missing parent directoriesawaitfs.outputFile('./some/file/with/parents/not/exists','file data')// write json file will auto create missing parent directoriesawaitfs.outputJson('./some/file/with/parents/not/exists',{text:'json data'})letfile=awaitfs.readJson('./some/jsonFile')// iterate directory treeawaitfs.iter('./src',async(path,stat)=>{if(stat.isDirectory()){logger.info('directory:',path)// skip scan node_modulesif(path.endsWith('node_modules')){returntrue}}elseif(stat.isFile()){logger.warn('file:',path)}})})

logger

import{logger}from'foy'task('build',asyncctx=>{logger.debug('debug',{aa:1})logger.info('info')logger.warn('warn')logger.error('error')})

exec command

import{logger}from'foy'task('build',asyncctx=>{awaitctx.exec('tsc')// run multiple commands synchronouslyawaitctx.exec(['tsc --outDir ./lib','tsc --module es6 --outDir ./es',])// run multiple commands concurrentlyawaitPromise.all([ctx.exec('eslint'),ctx.exec('tsc'),ctx.exec('typedoc'),])// restart process when file changesctx.monitor('./src','node ./dist')ctx.monitor('./src',['rm -rf dist','tsc','node dist'])ctx.monitor('./src',async()=>{awaitctx.run('build:server')awaitctx.exec('node ./dist')// auth detect long-running process when using ctx.exec})ctx.monitor('./src',async(p)=>{// manually point out the process need to be killed when restartp.current=require('child_process').exec('node dist')})})

Using in CI servers

import{task,spinner,setGlobalOptions}from'foy'setGlobalOptions({spinner:true})// enable loading animations, default is falsespinner(false)// disable spinner for current tasktask('test',asyncctx=>{/* ... */})/*$ foy testDependencyGraph for task [test]:─ testTask: test...*/

Using lifecycle hooks

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

task('task1',asyncctx=>{/* ... */})task('task2',asyncctx=>{// do things before task1// run task1 manually, so we can// do things before or after itawaitctx.run('task1')// do things after task1})

Watch and build

task('build',asyncctx=>{/* build your project */})letp=nulltask('watch',asyncctx=>{ctx.monitor('./src',async()=>{ctx.exec('node ./src/server.ts')})})

Using with custom compiler

# Write Foyfile in ts, enabled by defaultfoy -r ts-node/register -c ./some/Foyfile.ts build# Write Foyfile in coffeefoy -r coffeescript/register -c ./some/Foyfile.coffee build

zsh/bash auto completion (New!!!)

# for bashfoy --completion-profile>>~/.bashrc# for zshfoy --completion-profile>>~/.zshrc

API documentation

License