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 = ;;;{t;}
- 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 paramatert
, 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'))
- list of tasks that should be run and completed prior calling
chronic.source
an array or commma separated list of globby strings passed tovinyl.src
(see globby)- passed down to
t.src()
andt.files
- passed down to
chronic.dest
a single string- passed down to
t.dest()
andt.path
- passed down to
chronic.watch
an array or commma separated list of globby strings to watch (see globby)- passed down to
t.watching
- passed down to
chronic.transform
a comma separated list of functions that are stream transforms- these functions are piped inbetween
t.src
andt.dest
ifchronic.build
is used - only gulp-plugins can safely be used at the moment
- these functions are piped inbetween
func( t ) :
t.done
- callback which determines if a task has completed- optionally pass in an error
t.done([err])
- optionally pass in an error
t.src
- returnsvinyl.src
(gulp.src)- if
chronic.source
is defined, callingt.src()
is populated with the content oft.files
- this can be easily overridden by defining
t.src('glob')
manually
- if
t.dest
- returnsvinyl.dest
(gulp.dest)- if
chronic.dest
is defined, callingt.dest()
is populated with the content oft.path
- this can also be overriden
- if
t.build
- returns an instance of pump that callst.done
upon completion or error of stream- example:
t.build(t.src(), t.dest())
- example:
t.exec
- returns formatted npm-execspawn callingt.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 linet.files
- returns an array of strings fromchronic.source
t.path
- returns an array of strings fromchronic.dest
t.watching
- returns an array of files fromchronic.watch
- used internally to watch files being watched,
t.source
- returns vinyl-source-streamt.buffer
- return vinyl-buffert.pump
- returns pumpt.eos
- returns end-of-stream
chronic.build
- returns
function(t)
withpump(t.src(), -> [transforms], -> t.dest())
, returningt.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