ajrulez / sag-js Goto Github PK

Sag-JS
======

Version 0.4.0
http://www.saggingcouch.com

Sag-JS is a JavaScript library for working with CouchDB that works in both
browsers and Node.JS. It is a port of the popular Sag PHP library and is
completely API compliant, with the addition of callbacks for dealing with
JavaScript's asynchronous nature.

Sag is designed to not force any particular programming method on its users -
you just pass objects in and get objects back. This makes it trivial to
include Sag in your application, build different functionality on top of it,
and expand Sag to include new CouchDB functionality.

Install
-------

Node: `npm install sag` or include the source file in your project.

Browser: Include the source file in your project and embed it with a script
tag.

Compatability
-------------

Sag-JS is API compatible with Sag 0.7.1 with a few asynchronous language
specific additions.

Each release is tested with an automated testing suite against these
combinations of software:

  Apache CouchDB: 1.1.x, 1.2.x, 1.3.x

  Node.JS: 0.8.x and 0.10.x (stable releases only)

  Browsers: FF >= 3.5, Chrome >= 15, and IE >= 7

Lower versions will likely work with Sag-JS but are not officially supported,
so your mileage may vary.

Contents
--------

CHANGELOG                       A detailed list of all changes between
                                releases, including any breaking changes.

LICENSE                         A copy of the license Sag-JS is released under.

NOTICE                          Copyright notices.

README                          This file.

Makefile                        Used to run unit tests, create releases, etc.

src/                            This directory contains the pieces of source
                                code tha will be combined to make the sag.js
                                file. If you are building from source, then
                                just run `make` to generate the file.

tests/                          Contains the automated testing suite for
                                Sag-JS and its own documentation.

Error Handling
--------------

Sag's paradigm of simplicity is carried into its error handling by allowing
you to send data to CouchDB that will result in errors (ex., malformed JSON).
This is because CouchDB knows when there is an error better than Sag. This
also makes Sag more future proof, instead of worrying about each of CouchDB's
API changes. Therefore, Sag will only look for Sag-JS interface problems and
issues that are native to JS, such as passing an int instead of a string.

All local errors are floated back to your application with exceptions. Sag
does not catch any errors itself, allowing your application to care about them
or not.

CouchDB errors will be exposed through the response object. Additionally the
second parameter of the callback functions is set to `true` if a non-2xx HTTP
status was returned.

Networking
----------

Sag-JS automatically detects whether it is in a Node.JS or browser environment
and selects which networking tools to use accordingly.

Node.JS uses the HTTP module found in every Node.JS release.

Browser current uses XHR, which makes cross domain requests unfeasible. Future
versions will include support for cross domain requests.

More Info
---------

Detailed documentation of the functions and API are available at
http://www.saggingcouch.com

License
-------

Sag-JS is released under the Apache License, version 2.0. See the file named
LICENSE for more information.

Copyright information is in the NOTICE file.