Using Harmonic programmatically

[jaydson]

We can turn Harmonic into a module that can be loaded locally, so other modules can use it programmatically. Example:

var harmonic = require('harmonic');
harmonic.init();
harmonic.newPost('my post');
harmonic.build();

I think that feature will be helpful in some way.

[UltCombo]

Sounds good to me. The API would be useful for unit tests as well.

[jaydson]

Yep! I'll create a branch for that.

[UltCombo]

How should the API look like?

Rough idea I had:

var harmonic = require('harmonic');

// Factory pattern (like express), to cover use cases that manipulate multiple Harmonic sites.
// The factory constructor takes a sitePath argument that is saved in the instance,
// to avoid repeating it in every .init()/.config()/.build()/.run() call.
var mySite = harmonic('path/to/my/site');

// all async methods return promises
var promise = mySite.init();

promise.then(function() {
    return mySite.build();
}).then(function() {
    console.log('all done!');
}, function(err) {
    console.log('Something went wrong', err);
});

I believe we should give this some priority, so we can write tests for the API instead of using child processes. This way we can throw more meaningful errors without as much effort, and the tests will run much faster which is great for the incremental build workflow (npm run dev) giving faster feedback.

[UltCombo]

IMO we should make an API asap, expose it to users to experiment and gather feedback, then release Harmonic 1.0.0. From then on, we can follow semantic versioning. What do you think @jaydson?

[jaydson]

Totally agree. We just need to assign who will do what.

[UltCombo]

I believe it doesn't matter much who does it, as long as we agree on an API design. =]

[UltCombo]

I believe we can assign issues to ourselves when we start working on them, so others will know there's someone working on it.

[jaydson]

That's a good approach. I only want assignment to avoid duplicated development.

[UltCombo]

@jaydson yes, we can use GitHub's issue assignment for that purpose. =] It would also be nice if we make small, incremental commits (to WIP branches) so that we can provide opinions/suggestions/help to one another as well. Of course, if you prefer to make huge commits on things that you can handle yourself, there's no problem either.

[jaydson]

Yep, sounds good :+1:

[jaydson]

WIP > https://github.com/es6rocks/harmonic/commit/432977c7dfc47e944dbb187a65bdf8e249e6e3f4

Basic example using it:

var Harmonic = require('harmonic');
var mysite = new Harmonic('./path');
mysite.init()
.then(function(data) {
    console.log(data);
});

mysite.newPost()
.then(function(data) {
    console.log(data);
});

mysite.build()
.then(function(data) {
    console.log(data);
});

One of the benefits of a promise-based API: we can use async/await.

(async function(){
  let mysite = new Harmonic('path');
  await mysite.init();
  await mysite.newPost();
  await mysite.build();
}());

[UltCombo]

Nice! :+1: Also see https://github.com/es6rocks/harmonic/commit/432977c7dfc47e944dbb187a65bdf8e249e6e3f4#commitcomment-9663682

[UltCombo]

While at it, perhaps we should do some major refactoring/code organization? Maybe parser.js could become the main Harmonic class.

[jaydson]

Yes, i was thinking exactly the same.

[jaydson]

117