Genie

A CoffeeScript-based task runner. (And nothing else.)

See Masonry for functions that read, write, and process files.

Installation

npm i genie

Usage

npx genie [<task-name>...]

If no arguments are given, the defined tasks are listed.

Task definitions should be placed in the tasks directory.

Defining Tasks

Define tasks in your tasks/index.coffee file. Note that Genie will also check tasks/index.js for task definitions. We like CoffeeScript, so you'll see that in examples below, but as long as Node can require the files referenced in index, Genie can run the defined functions.

For example, here's a simple hello, world task.

import * as Genie from "@dashkite/genie"

Genie.define "hello-world", -> console.log "Hello, World"

Run the task like this:

npx genie hello-world

Dependent Tasks

You can define tasks that a given task depends on by simply listing them in an array or a whitespace-separated string.

Genie.define "build", "clean", ->
  # build task goes here

Parallel Tasks

You can append a ‘&’ to any task you define and it will run in parallel with the other tasks.

Genie.define "server", "html& css& js&", ->
  server "build", fallback: "index.html"

Before And After Tasks

You can add before and after tasks to other tasks as well, which is nice for augment pre-packaged tasks.

import * as Genie from "@dashkite/genie"

Genie.after "build", "images"

Event-Driven Tasks

You can define multiple task handlers via on in place of define:

import * as Genie from "@dashkite/genie"

Genie.on "hello-world", -> console.log "Hello, World"

The advantage of using on instead of define and before or after is that each handler is independent of the others. The disadvantage is that handlers run in the order they're declared, so you can't guarantee one handler will run before another. Using on provides an event-driven interface to tasks.

Important: Using define will overrite any handlers registered with on. You should avoid using define and on together for the same task name.

Parameterized Tasks

You can pass parameters to tasks in two ways. First, you can pass them via the environment.

targets='array' npx genie test

Second, you can define parameterized task names. Components of a task name are separated by :. If the task name is not found, the last component will be treated as an argument instead. This process continues until either a task name is found or there are no components remaining.

For example, suppose we have a task foo that takes a parameter. We can reference foo:bar and the string bar will be passed into the task.

So if our task definition is:

Genie.define "foo", (name) -> console.log "foo", name

and we run it as:

npx genie foo:bar

it will print foo bar.

Configuration

You may define a genie.yaml file in the directory from which you will run genie and that configuration will be available to tasks via the get function. This is useful for dynamically configuring pre-packaged tasks.

Presets

Development dependencies whose names (regardless of their scope) begin with genie- will be preloaded by Genie. Such modules are expected to export a (possibly asynchronous) task definition function taking the Genie instance that called them. They can then use this instance to define new tasks.

Preset loading may be surpressed for a given preset by using the -x option.

API

after

after task-name, task-to-run

Define a task to run after another task.

before

before task-name, task-to-run

Define a task to run before another task.

configure

configure configuration

Set the Genie configuration. The genie command reads this from the genie.yaml file.

define

define name, dependencies, fn

Define a task with the given name and dependencies using the given function.

get

get property → value

Read a property from the configuration.

list

list

List all the tasks that have been defined.

lookup

lookup name

Find a given task.

on

define name, dependencies, fn

Define a task handler with the given name and dependencies using the given function. Similar to define, but allows multiple handlers to run for the same task.

run

run name

Runs the given task name.