Clutch 0.3.0 refactoring

[Chas Emerick]

As part of Clutch 0.3.0, I wanted to give the API a proper spit-shine. The initial results of that have been pushed to the 0.3.0 branch[1], and depoyed to clojars in a new 0.3.0-SNAPSHOT.

The result of this is a fair bit of API breakage — all for the significant better, IMHO. I've compiled a basic accounting of the damage in a partial changelog in the readme[1].

The most significant change — ironically, not in the changelog! — is that you can now use the entire API with *either* a dynamic scope via `with-db`, or you can pass database configuration to any function. e.g. these are equivalent:

(with-db "http://hostname/databasename"
(put-document {:a 5 :b 6} :id "foo"))

(put-document "http://hostname/databasename" {:a 5 :b 6} :id "foo")

For those who are interested, some of the "backstory" of implementing this more flexible configuration interface can read up on it elsewhere[2].

Configuration options have also changed quite a bit, though I'm going to document those properly in the readme instead of ferreting them here.

I know that API breakage always makes things hard on people who have been successfully using a library, but I think the breakage is worth it in this case — all on its own, really, but also as a necessary step to enable other things I have in mind to make working with CouchDB databases from Clojure even easier and transparent.

I'd love to get some reports about "porting" efforts; I'd be happy to help with any snags people run into along the way.

Cheers,

- Chas

[1] https://github.com/ashafa/clutch/tree/0.3.0
[2] http://wp.me/10OJi

[Dave Barker]

Hi Chas,

Hope my message gets through this time, here's my experience:

I updated my project file to use 0.3.0, changed create-document to put-
document a few times and replaced my couchDB map with a URL string.

All was well appart from the watch-changes feature which seemed to
completely stop working. I've gone back to 0.2.5 for now.

Cheers, Dave.

[Dave Barker]

Hi Chas,

I fell at the first hurdle, could not get my database using a map any
more.

I put the details in this Gist: https://gist.github.com/1351873

Cheers, Dave.

On Oct 17, 4:23 pm, Chas Emerick <cemer...@snowtide.com> wrote:

[Chas Emerick]

Yes, that's a known breaking change w/ 0.3.0; I've added some
documentation around the new configuration options to the README:

https://github.com/ashafa/clutch/tree/0.3.0

- Chas

[Chas Emerick]

FYI, I have deployed a new 0.3.0-SNAPSHOT that includes a couple of
fixes, as well as one new feature: all view results (i.e. from `get-
view`, `all-documents`, etc) are now returned as a lazy seq. This
should make working with larger datasets a lot easier than the
previous state of affairs (where view results from couch were gathered
and decoded into one [potentially huge] map with a :rows slot that had
all the data you actually cared about). This feature and some details
(e.g. where other view metadata has gone) is now in the README.

I'm working through the issue backlog right now, with all fixes going
into 0.3.0. My current thinking is that 0.3.0 will be released after
those are closed, and the documentation is properly refreshed to fully
account for the new API, etc.

Any feedback / unintended breakage / etc most welcome.

Thanks,

- Chas