README

chronic

adjective: from Greek khronikos ‘of time,’ from khronos ‘time.’

npm install chronic --save-dev

Background

My goal is to provide a balance between configuration and customization through the creation of task-transducers. This library is now a heavily modified version of azer's bud and gulp's vinyl-fs. The original rationale for this project can be found here.

Why did I put together this library?

So why not just use gulp? Gulp got one problem fundamentally wrong, and its this: gulp.src and gulp.watch shouldn't exist inside task functions - file IO, including watching, should be declared at the highest level possible in the system. Bud, on the other hand, it's just a tiny library that does one thing well (and it's good), but it's like a tool box without that many tools. I want to put as many useful tools in here as I can fit (the ones I use everyday, like vinyl-source-stream). Also, node pipes are notorious bad at error handling, so I included some 'fixes' to help with that. I'm currently rewriting the API in es6 (half the original methods seem to be es6 hacks), but it'll be nice to have a standard to build on top of. Enjoy!!

Usage

Please read the CHANGELOG

var chron = require('chronic');

chron('default', chron.after('task2'), function(t) {
  t.exec('echo dat {bud}!', t.params);
});

chron('task1', chron.source('./one/**').dest('./two'), chron.build)

chron('task2', chron.after('task1'), tasktwo);

function tasktwo(t) {
  t.build(t.src('./two/**'), t.dest('./three'));
}

Run:

$ node <filename> --bud=chronic

Should run 'task1', 'task2', then 'default' in that order, returning this output:

  default  Running...
  task2    Running...
  task1    Running...
  task1    Completed in 6ms
  task2    Completed in 7ms
  default  Executing "echo dat chronic!"
  default  dat chronic!
  default  Completed in 10ms

Command Line Usage

To run tasks:

$ node <filename> <tasks> <params>

to watch files:

$ node <filename> -w # or --watch

to list available tasks in a file:

$ node <filename> -l # or --list

API

chronic(task, [opts, func])

task a string used to name tasks.
opts a chainable series chronic methods.
func a function that contains the paramater t, optionally use chronic.build

opts:

chronic.after a comma separated list of tasks (strings)
- list of tasks that should be run and completed prior calling func
- may be used without func eg: chron('default', chron.after('task'))
chronic.source an array or commma separated list of globby strings passed to vinyl.src (see globby)
- passed down to t.src() and t.files
chronic.dest a single string
- passed down to t.dest() and t.path
chronic.watch an array or commma separated list of globby strings to watch (see globby)
- passed down to t.watching
chronic.transform a comma separated list of functions that are stream transforms
- these functions are piped inbetween t.src and t.dest if chronic.build is used
- only gulp-plugins can safely be used at the moment

func( t ) :

t.done - callback which determines if a task has completed
- optionally pass in an error t.done([err])
t.src - returns vinyl.src (gulp.src)
- if chronic.source is defined, calling t.src() is populated with the content of t.files
- this can be easily overridden by defining t.src('glob') manually
t.dest - returns vinyl.dest (gulp.dest)
- if chronic.dest is defined, calling t.dest() is populated with the content of t.path
- this can also be overriden
t.build - returns an instance of pump that calls t.done upon completion or error of stream
- example: t.build(t.src(), t.dest())
t.exec - returns formatted npm-execspawn calling t.done() upon completion
- uses format-text instead of looking for env variables
- example: t.exec('echo hello {place}!', {place: 'world'})

t.params - paramaters returned from command line
t.files - returns an array of strings from chronic.source
t.path - returns an array of strings from chronic.dest
t.watching - returns an array of files from chronic.watch
- used internally to watch files being watched,
t.source - returns vinyl-source-stream
t.buffer - return vinyl-buffer
t.pump - returns pump
t.eos - returns end-of-stream

chronic.build

returns function(t) with pump(t.src(), -> [transforms], -> t.dest()), returning t.done upon completion or error
this method is syntactical sugar over the most common use pattern of this library

TODO

More examples and tests
integrate some philosophy and modules from folktale - specifically data.task

The Task(a, b) structure represents values that depend on time. This allows one to model time-based effects explicitly, such that one can have full knowledge of when they're dealing with delayed computations, latency, or anything that can not be computed immediately.

maxogen/atomic-queue to persist the state / order of tasks if it crashes

a crash friendly queue that persists queue state and can restart. uses a worker pool and has configurable concurrency

ast-trees / transform plugin / code analysis bridges into the filesystem. This can all be done in gulp / webpack of course, but I want to find the right plugins and put them in where appropriate (I'm more of a tool finder than builder).
long term goal... build-system IDE - file system visualizer - npm repo gui / easy download config for all build systems - and to fully leverage these AST transforms being used by everyone to visually and interactively compose complex systems that currently resides in our short term memory.

License

MIT

Usage no npm install needed!