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