[WIP] Full Rework (v2.0.0)

[lukeed]

This area is reserved for notes, thoughts, and a (wip) changelog.

Please feel free to comment below 🙇

Notes

• with 1.4: 117 tests in ~980ms
• with 2.0: 228 tests in ~150ms

  Todo

• [x] add fly.target (lol) & tests
• [x] add fly.watch & tests
• [x] finalize fly.plugin API definition
• [x] define plugins using fly.plugin
• [x] bind plugins to this instance
• [x] move examples, contributing, etc

  Changelog

• Upgraded minimum Node requirement from 0.12 to 4.6 (LTS)
• Rewrite with (most) ES2015 syntax
• Dropped --harmony flag
• Replaced tj/co with bluebird.coroutine generators
  • every prototype method must be yielded, for performance & consistency
  • every util method (fly.$) must be yielded, for performance & consistency
• Replaced custom EventEmitter with built-in EventEmitter
• Globs are only expanded once per task lifecycle
• Rewrote all tests
  • added 65+ new tests!
  • more fine-tuning and control
  • far less prone to core bugs

    API

• Fly can be initialized anywhere programmatically
• removed fly.concat and fly._.cat
• removed fly.flatten
• removed fly.unwrap (use fly.$.expand)
• removed fly.filter (use fly.plugin)
• removed fly.exec (use fly.start)
• changed fly.start
  • acts as the base executor
  • resets the stored internal values (fly._)
  • initializes the fly instance, if not already
  • accepts an opts object in addition to a task name
  • opts may contain a src and val
  • removed opts.parallel (see below)
• added fly.init
  • adds additional instance validations
  • alerts instance of ready status
• added fly.serial
  • sequentially runs an array of task names
  • allows for opts to be shared & mutated by each chain member
  • interrupts & aborts chain when a member throws
• added fly.parallel
  • run a group of tasks in parallel, completely indifferent to member order
  • shares opts across all members; does not cascade
  • is correctly yielded
  • prevents next sequence from running until all members have finished
• changed fly.source
  • eagerly expands globs once per lifecycle
  • populates fly._.globs and fly._.files
  • fly._.files is an array of modified pathObjects. Each entry consists of:
  • dir - the full directory path of the source file
  • base - the file's name, including extension
  • data - a Buffer of the file's contents
• replaced fly._.host with fly._.tasks

  Utilities

• every must be yielded, for performance & consistency
• exposed publicly as fly.$
• added expand
• changed 'write'
  • will now handle/create its own ancestor tree (mkdir)
• removed bind
• removed defer
• removed apply
• removed diff
• removed shallow-copy
• removed arrayToMap
• removed custom UnknownOption and UnknownInput error classes (see CLI)

  CLI

• added -m and --mode flag
  • defaults to serial
  • toggles the execution type for tasks
• added additional cli.help content
• improved cli.list output
• changed -f and --file to -p and --pwd
  • always expected a directory anyway
  • still defaults to process.cwd()
• wrapped cli.spawn with bluebird
  • must be yielded
• merged UnknownOption and UnknownInput into generic CLI error handler
• moved all cli-related ramp up to cli.js
  • stopped using child_process.spawn
  • dropped --harmony flag

    Plugins

• replaced fly.filter with fly.plugin
  • the "filter" name implied "filter down"
• define plugins using three parameters: name, opts and func
  • the name will be used within fly; eg .babel()
  • if another plugin shares your name, a unique replacment will be generated & used instead. Users will be notified of the conflict & namechange.
  • the opts tell Fly how to run the plugin
  • opts.files - if true then use fly._.files else use fly._.globs
  • opts.every - if true, apply the plugin to **each**globorfile` individually
  • the func is a generator method that binds to Fly, allowing you to use any method, including the helper methods (fly.$)
• plugins are properly awaited, which means that each subsequent plugin may read previous values (eg, modified data values) and continue to alter/append custom values.

  Extras

• Includes #212 , #177, #170
• Closes #203

[hzlmn]

@lukeed

Please, ping me when API will be stable for 2.* release. I work on a tool for migrating from one major version to other one for Fly.

Basically, it will have web UI where owner of project, that uses Fly, can add his repo, and then receive PRs from bot that will scan flyfile, detect old api parts, etc and suggest changes, that should be done.

[lukeed]

@hzlmn Sounds awesome! Will do

[hzlmn]

@lukeed Hey, I'm writting backend for tool, and wondering, if you have any preferences for tech stack? I was thinking about Python3.5 + Aiohttp and some sort of key-value storage (I pretty familiar with this stack, as used actively at work). For node.js I thought about Koa (I don't like callback nature of Express).

[lukeed]

@hzlmn I always write backends in Elixir...or PHP if the current team/project sets that limitation. I don't actually write much Node (Fly pretty much covers it, or other small CLI utilities), but the last time I wrote a web-related Node project, it was with Feathers.js. Although, it's based on express.

Koa would be interesting, I haven't tried it. But if you wanted to keep the Koa / generator system, you could always just require tj/co or bluebird directly & wrap your callbacks.

[lukeed]

@hzlmn API is largely complete. Only minor (internal) things may change.

Still working on examples, new docs & readme

[lukeed]

@hzlmn Currently published with the beta flag if you want to start fiddling with it. I haven't had time to write up an "Upgrade Guide" yet, but I surely will.

npm i -D fly@beta

[hzlmn]

@lukeed thx, will start playing with it.

[Akkuma]

I just want to say thank you for

Fly can be initialized anywhere programmatically

I've been doing this programmatically for awhile now, but it is basically a copy of how the CLI instantiated a task, so the code looks pretty awful compared to what a public api will look like.

const reporter = require('fly/lib/reporter');
const spawn = require('fly/lib/cli/spawn');
const creed = require('creed');
const path = require('path');

module.exports = function() {
   creed.coroutine(spawn)(path.resolve(__dirname, '../../'))
    .then(function onSpawn(fly) {
      return reporter.call(fly)
        .emit('fly_run', { path: fly.file })
        .start(['build:dynamic'], { value: opts });
    })
}

[lukeed]

@akkuma you're welcome, great suggestion! All of the Fly tests use this method in case you need any examples while using the beta flag.