ZappaJS 4.0

[step...@shimaore.net]

Hello,

ZappaJS 4.0 is out. I wanted to iron out all the details before
releasing but I think it's better I stop delaying this, the first commit
is three months old. :)

Documentation and examples still need some work, but the README and
specifications documents are up-to-date. The test suite has been updated.

The major release number indicates that some things were removed, while
some (I think) cool things were added in. Here are the details:

- Support for route handlers that return Promises;
support for route handlers that return generators.

This means that using the promise-and-generator pattern, you can
implement `async`-like functionality in ES5:

@get '/user/:name', ->
user = yield user_db.getAsync @params.name
group = yield group_db.getAsync user.group
@json {user,group}

- `@session` is still available in both ExpressJS and Socket.IO, but
it can now be updated and saved in Socket.IO handlers. Actually, it is
saved automatically in Socket.IO handlers, similarly to what ExpressJS
does.

- Client-side code has been moved to a separate package, 'zappajs-client'.
(The package works fine with Browserify, but could use the help of
someone who knows about AMD etc.)

The obvious advantage is that the ExpressJS-to-Socket.IO binding that
needs to happen client-side can be automated in your application
without having to include Zappa in the application.

- Sammy.js and jQuery are not longer embedded.

Really, I'm not sure about the state of Sammy. Commits haven't been
forthcoming, and I've never used it fully on the client side. There
are plenty of alternatives. I suspect Maurice Machado used it because
it allowed to nicely deal with `@shared`, but I don't see the point
anymore.

Removing it was really the first thing that triggered spawning the 4.x
branch. Once Sammy was gone, jQuery didn't have a reason to stay (it
was only used for DOM-readyness).

Once that was done, having a clean, separate cliend-side library
started to make sense.

As a consequence the `zappa` middleware has been removed, and the
various bundles are not generated anymore.
It's easy to build them back if you really need to, though:

@browserify '/zappa.js', ->
window.zappa = require 'zappajs-client'
window.jQuery = window.$ = require 'jquery'

- `@client` has been replaced by `@browserify`.

That choice is more arguable, but `@client` really was a magic
wrapper for the client-side Zappa code. Magic doesn't make me happy. :)
And the client-side code has been replaced, so might as well make sure
people don't assume the new client-side code will behave the same way
as the old one.

On the other hand, browserify has made things very tempting on the
client-side:

@browserify '/app.js', ->
$ = require 'component-dom'
$('.div').addClass 'amazing'

If there is an equivalent to the old `@client`, it probably looks like
this:

@browresify '/app.js', ->
(require 'zappajs-client') ->
@ready ->
# your code here

I guess this could become the new `@client` if there is a strong need
for it. :)

I also added `@isomorph` to somewhat reproduce what `@shared` used to
do. That's recent and I haven't had time to iron things out though,
I'll see if there's a real need for it.

- Socket.io's `ack` is now supported for all `@emit` functions, and has
access to a proper scope.

- Uses the `debug` module.


Now, ZappaJS 3.x is still present and you're welcome to keep using it.
I'll make the occasional patch if needed.
However starting with the next version of 4.x I'll be moving the `latest`
branch to 4.x (from 3.x). Make sure your package.json dependencies are
correct especially if you're depending on client-side details.

I've been using this new version in production for a few months and
I just couldn't keep it for myself. I hope you like the new features,
maybe give it a run and see if you find any bugs, and as usual let me
know if there is anything else you'd like to see.

The API reference https://zappajs.github.io/zappajs/docs/reference
and README https://github.com/zappajs/zappajs/blob/3.x/README.md
have more details.

S.

--
tel:+33643482771
http://stephane.shimaore.net/