{"id":15650878,"url":"https://github.com/zkat/chillax","last_synced_at":"2025-08-15T20:36:36.545Z","repository":{"id":769206,"uuid":"452929","full_name":"zkat/chillax","owner":"zkat","description":"CouchDB abstraction layer for Common Lisp","archived":false,"fork":false,"pushed_at":"2015-01-13T08:47:44.000Z","size":800,"stargazers_count":35,"open_issues_count":3,"forks_count":7,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-23T15:05:25.929Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zkat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2009-12-30T02:12:02.000Z","updated_at":"2025-04-15T15:12:40.000Z","dependencies_parsed_at":"2022-07-05T14:00:46.129Z","dependency_job_id":null,"html_url":"https://github.com/zkat/chillax","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zkat/chillax","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkat%2Fchillax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkat%2Fchillax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkat%2Fchillax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkat%2Fchillax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zkat","download_url":"https://codeload.github.com/zkat/chillax/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zkat%2Fchillax/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270626824,"owners_count":24618689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-15T02:00:12.559Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T12:36:10.163Z","updated_at":"2025-08-15T20:36:36.502Z","avatar_url":"https://github.com/zkat.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quickstart example\n\nChillax is [Quicklisp](http://quicklisp.org)-installable, allowing for super-quick, painless\ninstallation of Chillax and all its dependencies.\n\nMake sure CouchDB is installed, and currently running. This example assumes that the server is\nrunning in localhost, using the default 5984 port. Yason's alist encoder/decoder is used below to\nmake replies readable (by default, it uses hash tables as JSON objects, instead of alists, and\nstrings as keys).\n\n    CL-USER\u003e (ql:quickload 'chillax)\n             ...\n             ...\n             ...\n    CL-USER\u003e (in-package :chillax)\n    CHILLAX\u003e (defparameter *server* (make-instance 'yason-server :object-as-alist-p t\n                                                   :parse-object-key-fun\n                                                   (lambda (string) (intern string *package*))))\n    *SERVER*\n    CHILLAX\u003e (defparameter *db* (ensure-db *server* \"test\"))\n    *DB*\n    CHILLAX\u003e (all-documents *db*)\n    ((|rows|) (|offset| . 0) (|total_rows| . 0))\n    CHILLAX\u003e (put-document *db* \"my_test_doc\" '((name . \"Kat\") (favorite-language . \"common-lisp\")))\n    ((|rev| . \"1-3c964cc898c03c48903a91d90b24a269\")\n     (|id| . \"my_test_doc\") (|ok| . T))\n    CHILLAX\u003e (get-document *db* \"my_test_doc\")\n    ((FAVORITE-LANGUAGE . \"common-lisp\")\n     (NAME . \"Kat\")\n     (|_rev| . \"1-3c964cc898c03c48903a91d90b24a269\")\n     (|_id| . \"my_test_doc\"))\n    CHILLAX\u003e (delete-document *db* (cdr (assoc '|_id| *)) (cdr (assoc '|_rev| *)))\n    ((|rev| . \"2-2221fc2b97c1fac1a82ba07d2835ac80\")\n     (|id| . \"my_test_doc\")\n     (|ok| . T))\n\n# Introduction\n\nChillax is a [CouchDB](http://couchdb.apache.org) abstraction layer for Common Lisp. It is **not** an\nORM or similar library, although it may be used to build such things.\n\nChillax also includes a CouchDB view server, which can be used to write CouchDB views in full,\nnative Common Lisp.\n\nChillax includes several systems:\n\n* chillax.asd - This is a 'DWIM' system. It includes the Yason server for parsing/encoding JSON\n  data. It also defines a single `#:chillax` package that includes the symbols in both\n  `#:chillax.core` and `#:chillax.yason`. If you don't know what you want, **this is probably what\n  you want**.\n* chillax.core.asd - Core API and protocols for servers, databases, documents, and\n  design-docs.\n* chillax.yason.asd - Implementation of the server protocol using Yason's JSON parser.\n* chillax.jsown.asd - Implementation of the server protocol using JSOWN's JSON parser.\n* chillax.utils.asd - Some handy utilities.\n* chillax.view-server.asd - The Chillax view server. This only depends on chillax.utils.\n\n# About this document\n\nThis README is not meant to document how to use CouchDB itself, or how to successfully design\napplications with it. If you're new to CouchDB, it is recommended that you follow a guide (which can\nbe done while using Chillax).\n\nThe [CouchDB Guide](http://guide.couchdb.org/) is recommended, and the\n[CouchDB Wiki](http://wiki.apache.org/couchdb/) can be used as a general reference for CouchDB's\nAPI.\n\n# Core API\n\nChillax is a thin, lispy layer on top of CouchDB's RESTful API. Its main purpose is to provide Lisp\nfunctions to all of CouchDB's API calls, while translating certain things into Lisp data and\nconcepts. For example, Chillax takes care of checking CouchDB's HTTP response codes for sanity. When\nerror codes are returned, Chillax will signal Lisp corresponding Lisp conditions.\n\nAdditionally, Chillax is able to use any representation for CouchDB documents, provided the core\nChillax protocols are implemented for that representation, i.e, you can use hash tables, alists, or\ninstances of classes as your 'documents', and Chillax will automatically serialize/deserialize JSON\ncommunications with CouchDB according to the protocol's implementation.\n\nNote that, since Chillax really is just a thin layer, it abstracts very little beyond the\nabove. Most Chillax functions will simply return the de-JSON-ified CouchDB responses, and leave you\nto digging through the response objects for the data you need.\n\n## Server API\n\nChillax's Server API provides access to server-level functionality. Server objects not only give\naccess to these database-independent features, but also act as mediators for all data that goes\nthrough Chillax. Chillax's server objects are in charge, for example, of translating CouchDB's JSON\nresponses to and from whatever data format the user has chosen to use Lisp-side.\n\nServer objects are created through appropriate protocol implementations. See STANDARD-SERVER, and\nYASON-SERVER below for the included implementations. Additional or alternate functionality for\nserialization can easily be implemented through Chillax's server protocol.\n\n*[function]* `server-uri server`\n\n  Returns a string representation of the URL SERVER represents.\n\n\n*[function]* `all-dbs server`\n\n  Requests a list of all existing databases from SERVER.\n\n\n*[function]* `config-info server`\n\n  Requests the current configuration from SERVER.\n\n\n*[function]* `replicate server target \u0026key create-target-p continuousp`\n\n  Replicates the database in SOURCE to TARGET. SOURCE and TARGET can both be either database names\n  in the local server, or full URLs to local or remote databases. If CREATE-TARGET-P is true, the\n  target database will automatically be created if it does not exist. If CONTINUOUSP is true,\n  CouchDB will continue propagating any changes in SOURCE to TARGET.\n\n\n*[function]* `stats server`\n\n  Requests general statistics from SERVER.\n\n\n*[function]* `active-tasks server`\n\n  Lists all the currently active tasks on SERVER.\n\n\n*[function]* `get-uuids server \u0026key (number 10)`\n\n  Returns a list of NUMBER unique IDs requested from SERVER. The UUIDs generated by the server are\n  reasonably unique, but are not checked against existing UUIDs, so conflicts may still happen.\n\n\n## Database API\n\nConnecting to a database in Chillax involves creating a database object with one of 3 constructors,\nall of which accept a server object (see Server API above), and the name of the database.\n\nThe Database API additionally provides some utility functions for accessing database-level\nfunctionality in CouchDB.\n\nWiki: [HTTP Database API](http://wiki.apache.org/couchdb/HTTP_database_API)\n\n*[function]* `db-connect server name`\n\n  Confirms that a particular CouchDB database exists. If so, returns a new database object that can\n  be used to perform operations on it. Will signal a DB-NOT-FOUND error if the database does not\n  already exist.\n\n\n*[function]* `db-create server name`\n\n  Creates a new CouchDB database. Returns a database object that can be used to operate on it. Will\n  signal a DB-ALREADY-EXISTS error if there is already a database with the same NAME in SERVER.\n\n\n*[function]* `ensure-db server name`\n\n  Either connects to an existing database, or creates a new one. Returns two values: If a new\n  database was created, (DB-OBJECT T) is returned. Otherwise, (DB-OBJECT NIL).\n\n\n*[function]* `db-info db`\n\n  Fetches info about a given database from the CouchDB server.\n\n\n*[function]* `db-delete db`\n\n  Deletes a CouchDB database.\n\n\n*[function]* `db-compact db`\n\n  Triggers a database compaction.\n\n\n*[function]* `db-changes db`\n\n  Returns the changes feed for DB\n\n\n*[function]* `db-uri db`\n\n  Returns a string representing the full URI for DB.\n\n\n## Document API\n\nAll document arguments to these functions must be Lisp objects that the database's server is able to\nencode to JSON. These functions will likewise return Lisp objects that represent the parsed JSON\nresponses from CouchDB. Exact representations will depend on the server being used.\n\nWiki: [HTTP Document API](http://wiki.apache.org/couchdb/HTTP_Document_API)\n\n*[function]* `get-document db id \u0026key attachmentsp (errorpt)`\n\n  Finds a CouchDB document in DB, named by ID. PARAMS should be an alist containing the parameters\nfor the HTTP GET request. If ATTACHMENTSP is TRUE, the document's attachments will be included in\ntheir entirety in their base64-encoded version. It is not recommended you use this unless you really\nknow what you're doing. If ERRORP is NIL, GET-DOCUMENT will simply return NIL on 404.\n\n\n*[function]* `get-document-revision db doc-id \u0026key (errorp t)`\n\n  Quickly fetches the latest revision for DOC-ID. If ERRORP is NIL, this can be used to quickly test\n  the existence of a document.\n\n\n*[function]* `put-document db id doc \u0026key batch-ok-p`\n\n  Puts a document into DB, using ID. DOC must be Lisp data that DB's server is able to convert to\n  JSON.\n\n\n*[function]* `post-document db doc`\n\n  POSTs a document into DB. CouchDB will automatically assign a UUID if the document does not\n  already exist. Note that using this function is discouraged in the CouchDB documentation, since it\n  may result in duplicate documents because of proxies and other network intermediaries. If what you\n  need is to create a new document with a generated id, consider using GET-UUIDS with PUT-DOCUMENT.\n\n\n*[function]* `delete-document db id revision`\n\n  Deletes an existing document.\n\n\n*[function]* `copy-document from-id to-id \u0026key revision`\n\n  Copies a document's content in-database.\n\n\n## Bulk Document API\n\nCouchDB supports a bulk document API for fetching, updating, and deleting documents in batches.\n\nWiki: [HTTP Bulk Document API](http://wiki.apache.org/couchdb/HTTP_Bulk_Document_API)\n\n*[function]* `all-documents db \u0026rest all-keys`\n\n  Requests the \\_all\\_docs document. ALL-KEYS correspond to GET-DOCUMENT's keyword arguments.\n\n\n*[function]* `batch-get-documents db \u0026rest doc-ids`\n\n  Uses \\_all\\_docs to quickly fetch the given DOC-IDs in a single request. Note that this function\n  will NOT signal a DOCUMENT-NOT-FOUND error when one or more DOC-IDs are not found. Instead, the\n  results will be returned, and it's the user's responsibility to deal with any missing docs.\n\n\n*[function]* `bulk-post-documents documents \u0026key all-or-nothing-p`\n\n  Allows you to update or submit multiple documents at the same time, using CouchDB's \\_bulk\\_docs\n  API. In order to delete a document through this API, the document must have a \\_document attribute\n  with JSON 'true' as its value (note that what gets translated into 'true' depends on the server).\n\n  DOCUMENTS must be a sequence or sequence-like (depending on what DATA-\u003eJSON will do to it).\n\n  If ALL-OR-NOTHING-P is true, the entire submission will fail if a single one fails.\"\n\n\n## Standalone Attachment API\n\nCouchDB has an API for uploading and downloading standalone attachments.\n\nWiki: [Standalone Attachments](http://wiki.apache.org/couchdb/HTTP_Document_API#Standalone_Attachments)\n\n*[function]* `put-attachment db doc-id attachment-name data \u0026key rev content-type`\n\n  Adds DATA as an attachment. DATA can be a number of things:\n\n  * String or sequence of octets - DATA will be sent as-is directly to the server (using EXTERNAL-FORMAT-OUT for strings).\n  * Stream - The stream will be read until EOF is reached.\n  * Pathname - The file the pathname denotes will be opened and its data uploaded.\n  * Function designator - The corresponding function will be called with one argument, the stream to the server, to which it should send data.\n\n  If the document already exists, REV is required. This function can be used on non-existent\n  documents. If so, REV is not needed, and a document will be created automatically, and the\n  attachment associated with it.\n\n  The CONTENT-TYPE should be a string specifying the content type for DATA. (default: \"application/octet-stream\")\n\n\n*[function]* `get-attachment db doc-id attachment-name`\n\n  Returns 3 values:\n\n  1. STREAM - An open flexi-stream that can be READ. In order to read straight binary data, you must first fetch the underlying stream with FLEXI-STREAMS:FLEXI-STREAM-STREAM.\n  2. MUST-CLOSE-P - A boolean. If TRUE, the user must CLOSE this stream themselves once reading is done.\n  3. CONTENT-LENGTH - Declared content length for the incoming data.\n\n\n*[function]* `delete-attachment db doc-id attachment-name doc-revision`\n\n  Deletes an attachment from a document. DOC-REVISION must be the latest revision for the document.\n\n\n*[function]* `copy-attachment db doc-id attachment-name output-stream`\n\n  Copies data from the named attachment to OUTPUT-STREAM. Returns the number of bytes copied.\n\n\n## Design Document API\n\nChillax currently includes a basic wrapper for Design Document-related operations. This API is\nlikely to expand in the future as good ideas reveal themselves. Design documents will still need to\nbe created through the regular document API.\n\nWiki: [HTTP View API](http://wiki.apache.org/couchdb/HTTP_view_API)\n\n*[function]* `view-cleanup db`\n\n  Invokes \\_view\\_cleanup on DB. Old view output will remain on disk until this is invoked.\n\n\n*[function]* `compact-design-doc db design-doc-name`\n\n  Compaction can really help when you have very large views, very little space, or both.\n\n\n*[function]* `design-doc-info db design-doc-name`\n\n  Returns an object with various bits of status information. Refer to CouchDB documentation for\n  specifics on each value.\n\n\n*[function]* `query-view db design-doc-name view-name \u0026key ... (see below) ...`\n\n  Queries view named by VIEW-NAME in DESIGN-DOC-NAME. Keyword arguments correspond to CouchDB view\n  query arguments.\n\n  * key - Single key to search for.\n  * multi-keys - Multiple keys to search for.\n  * startkey - When searching for a range of keys, the key to start from.\n  * endkey - When searching for a range of keys, the key to end at. Whether this is inclusive or not depends on inclusive-end-p (default: true)\n  * inclusive-end-p - If TRUE, endkey is included in the result. (default: true)\n  * startkey-docid - Like startkey, but keyed on the result documents' doc-ids.\n  * endkey-docid - Like endkey, but keyed on the result documents' doc-ids.\n  * limit - Maximum number of results to return.\n  * stalep - If TRUE, CouchDB will not refresh the view, even if it is stalled. (default: false)\n  * descendingp - If TRUE, will return reversed results. (default: false)\n  * skip - Number of documents to skip while querying.\n  * groupp - Controls whether the reduce function reduces to a set of distinct keys, or to a single result row.\n  * group-level - It's complicated. Google it!\n  * reducep - If FALSE, return the view without applying its reduce function (if any). (default: true)\n  * include-docs-p - If TRUE, includes the entire document with the result of the query. (default: false)\n\n\n*[function]* `query-temporary-view db \u0026key (map (error)) reduce (language \"javascript\")`\n\n  Queries a temporary view. These views are meant to be for testing and development purposes, and\n  should _not_ be used in actual code.\n\n\n# Core Protocol\n\nYou can use the core protocol to customize behavior of Chillax. Writing your own implementation for\nthis protocol is relatively simple and painless, and it allows you to do things such as use your own\ncustom JSON encoder/decoder, if Yason doesn't fit your needs. Classes that implement the protocols,\nand their behavior, is documented here, as well.\n\nFor more information on the design of Chillax's protocol, refer to\n[Chillax and Protocols](http://sykosomatic.org/blog/?p=92).\n\n## Server Protocol\n\nSelf-explanatory readers:\n\n* *[generic function]* `server-host server`\n* *[generic function]* `server-port server`\n* *[generic function]* `server-username server`\n* *[generic function]* `server-password server`\n* *[generic function]* `server-secure-p server`\n\n\n*[generic function]* `data-\u003ejson server data \u0026key`\n\n  Converts DATA to JSON suitable for sending to CouchDB.\n\n\n*[generic function]* `json-\u003edata server json \u0026key`\n\n  Converts JSON to the desired data structure.\n\n\n*[generic function]* `make-db-object server name`\n\n  Creates an object which represents a database connection in SERVER. The object must conform to the\n  database protocol.\n\n\n### Included protocol implementations\n\n*[standard class]* `standard-server`\n\n  Basic implementation of the server protocol. JSON data is handled literally as strings, with no\n  conversion.\n\n  It supports the following initargs:\n\n  * :host - Host or IP address, in string form, of the CouchDB server. (default: \"127.0.0.1\")\n  * :port - Port, as an integer, for the CouchDB server. (default: 5984)\n  * :username - Username to use to authenticate with CouchDB server. (default: nil)\n  * :password - Password to use to authenticate with CouchDB server. (default: nil)\n  * :securep - Whether to use a secure SSL/TLS connection with the server. (default: nil)\n\n\n*[standard class]* `yason-server`\n\n  YASON-SERVERs use Yason's JSON parser/encoder to automatically translate content going to/coming\n  from the associated CouchDB server.\n\n  YASON-SERVER is a subclass of STANDARD-SERVER, and the same initargs apply.\n\n  It additionally supports the following initargs:\n\n  * :array-as-vector-p - If TRUE, parses JSON arrays as Lisp vectors. (default: nil)\n  * :boolean-as-symbol-p - If TRUE, parses JSON booleans as symbols instead of CL booleans. (default: nil)\n  * :object-as-alist-p - If TRUE, parses JSON objects as alists, instead of hash tables. (default: nil)\n  * :parse-object-key-fun - Function to process object keys with. (default: #'cl:identity)\n\n\n*[standard class]* `jsown-server`\n\n   JSOWN-SERVERs use JSOWN's JSON parser/encoder to automatically translate content going to/coming\n   from the associated CouchDB server.\n\n   JSOWN-SERVER is a subclass of STANDARD-SERVER, and the same initargs apply.\n\n\n*[function]* `call-with-key-container`\n\n  This function is part of the chillax.jsown package.\n\n  Calls FUNCTION, which require zero arguments, in a context where CONTAINER will be used for\n  jsown:parse-with-container.\n\n\n*[macro]* `with-key-container`\n\n  This macro is part of the chillax.jsown package.\n\n  Convenience macro for call-with-key-container.\n\n\n## Database Protocol\n\n*[generic function]* `database-server database`\n\n  Returns the server object with which DATABASE is associated.\n\n\n*[generic function]* `database-name database`\n\n  Returns the URL-encoded name of the database, a string. Note that CouchDB accepts certain\n  characters in database names -only- if they are URL-encoded (such as #\\/). It is up to individual\n  implementations of DATABASE-NAME to implement this encoding.\n\n\n### Included protocol implementation\n\n*[standard class]* `standard-database`\n\n  Minimal, class-based implementation of the database protocol.\n\n\n# View Server\n\nThe Chillax View Server allows you to write views in full-fledged Common Lisp. In order to use the\nserver, you must create a binary using code loaded by chillax.view-server.asd, and make\nchillax-server::run-server the toplevel function.\n\nOnce you put the binary in a place visible to the CouchDB process, add the following to\n/etc/couchdb/local.ini (or wherever your local.ini is located):\n\n    [query_servers]\n    common-lisp = /path/to/chillax-view-server\n\nAdd the common-lisp entry if there's already a query\\_servers entry.\n\nOnce you've done this, you can start making queries directly in Lisp!\n\n    CHILLAX\u003e (invoke-temporary-view *db* :language \"common-lisp\"\n                                         :map (prin1-to-string '(lambda (doc) (emit doc 1))))\n\nYou can load anything you want into the view server image before dumping it, customize which package\nit executes views in, etc. The source code is fairly short and easy to digest. It's designed to be\ncustomizable for whatever your needs are.\n\n## Status\n\nCurrently, the view server only provides basic features. A future release of Chillax will bring it\nback in sync with CouchDB's current line protocol.\n\n# Yason Problem\n\nNote that, at least on some systems, versions of [Yason](http://github.com/hanshuebner/Yason) prior\nto commit\n[00b9a5c06b7c4113a48518a1f136637efb4458b9](http://github.com/hanshuebner/Yason/commit/00b9a5c06b7c4113a48518a1f136637efb4458b9)\nwill not work (in this commit, #\\Return was added to the list of whitespace characters\nrecognized). Using these versions instead of 0.1 is recommended anyway for performance reasons.\n\n# History\n\nThe original author and current maintainer/developer of Chillax is\n[Kat Marchán](http://github.com/zkat); [Ian McEwen](http://github.com/ianmcorvidae)\nsubsequently worked on CLOS bindings, since the original version was written for\n[Sheeple](http://github.com/zkat/sheeple). Chillax has since been mostly rewritten (again) to\nuse a simple protocol-based extension API, allowing users to easily extend or alter Chillax's\nbehavior, with minimal code.\n\n# Contributors\n\n* Kat Marchán \u003czkat at sykosomatic.org\u003e\n* Adlai Chandrasekhar \u003cmunchking at gmail.com\u003e\n* Ian McEwen \u003cianmcorvidae at ianmcorvidae.net\u003e\n* Felix Lange \u003cfjl at twurst.com\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzkat%2Fchillax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzkat%2Fchillax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzkat%2Fchillax/lists"}