{"id":13743777,"url":"https://github.com/bustardcelly/as3couchdb","last_synced_at":"2025-04-06T16:16:38.110Z","repository":{"id":828360,"uuid":"544642","full_name":"bustardcelly/as3couchdb","owner":"bustardcelly","description":"An ActionScript 3 clientside API for interacting with a CouchDB instance.","archived":false,"fork":false,"pushed_at":"2010-11-19T14:20:34.000Z","size":13956,"stargazers_count":39,"open_issues_count":4,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-02-12T21:51:22.737Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://custardbelly.com/blog/?page_id=127","language":"ActionScript","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/bustardcelly.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2010-03-03T15:05:50.000Z","updated_at":"2023-07-17T20:35:59.000Z","dependencies_parsed_at":"2022-08-16T11:05:07.347Z","dependency_job_id":null,"html_url":"https://github.com/bustardcelly/as3couchdb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustardcelly%2Fas3couchdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustardcelly%2Fas3couchdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustardcelly%2Fas3couchdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustardcelly%2Fas3couchdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bustardcelly","download_url":"https://codeload.github.com/bustardcelly/as3couchdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247509238,"owners_count":20950232,"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","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-08-03T05:00:56.976Z","updated_at":"2025-04-06T16:16:38.088Z","avatar_url":"https://github.com/bustardcelly.png","language":"ActionScript","funding_links":[],"categories":["Networking","Database"],"sub_categories":["Database"],"readme":"# License\n\nSee the accompanying LICENSE file.\n\n# About\n\nas3couchdb is an ActionScript 3 clientside API for interacting with a CouchDB instance.\n\nas3couchdb at its core is a library to perform CRUD requests on a CouchDB instance. There are two basic entities\non which these requests are made - Database and Document - though the library includes making ancillary request\non the CouchDB instance itself as well (such as listing all available databases).\n\nas3couchdb aims to address performing CRUD requests with ease by exposing correlating methods on the models for\nDatabase and Document directly. To resolve this goal, custom metadata is required for these models that relate\nto the url of the CouchDB instance, the database name, the target mediating class between the model and the service,\nand the base request instance that communicates with the service. These are explained in futher detail within the Usage section.\n\n# Requirements\n\nThe following libraries are required to compile the as3couchdb library project:\n\n## as3corelib\n\nThe as3couchdb library requires the as3corelib project (found at [http://code.google.com/p/as3corelib/](http://code.google.com/p/as3corelib/)).\nThe classes from the as3corelib project that as3couchdb utilizes is SHA1 for generating unique ids\non the client side, and JSON for serializing objects for CouchDB service communication.\n\n## as3httpclient\n\nThe as3couchdb library requires the as3httpclient project (found at [http://code.google.com/p/as3httpclientlib](http://code.google.com/p/as3httpclientlib)).\nas3couchdb utilizes the as3httpclient API to make proper PUT and DELETE requests on the CouchDB instance.\nas3httpclient has a dependency on the following libraries: as3corelib and as3crypto.\n\n## as3crypto\n\nThe as3crypto library is used by the as3httpclient (see above requirement).\nas3crypt can be found at [http://code.google.com/p/as3crypto/](http://code.google.com/p/as3crypto/)\n\n# Usage \n\nAt the core of as3couchdb are models representing two basic entities within a CouchDB instance - \na Database and a Document. A CouchDB instance can hold many Databases and Databases can hold many Documents.\nIn as3couchdb, these entity models have their own methods for performing CRUD requests on a CouchDB instance.\nAs such, the CouchDatabase, CouchDocument and CouchUser classes allow for custom entity models that contain the business objects that perform these requests.\n\n## CouchModelEntity\n\nThe CouchModelEntity class holds properties related to a target database within a CouchDB instance, as well as the business objects that are the basis of transactions.\nThe role of the CouchModelEntity object is to wire up the associated service mediator for the target model (CouchDatabase, CouchDocument and CouchUser) upon instantiation of a new instance of that model.\nThe model uses the service mediator to make requests in relation to its exposed action (CRUD) methods.\n\nas3couchdb allows for this wiring to happen by either supplying a custom CouchModelEntity upon instantiation of a model, or by declaring custom metadata for the model class. The metadata directly relates to the properties of a custom CouchModelEntity.\n\nThe optional annotations are as follows:\n\n## DocumentService\n\nThe DocumentService metadata declares to the url of the CouchDB and the target Database name.\nIn the following example, the url points to the localhost at port 5984 (the default for CouchDB)\nand the database 'contacts'. Any requests made will be perfomed on the 'contacts' database at the CouchDB location.\n\n    [DocumentService(url=\"http://127.0.0.1:5984\", name=\"contacts\")]\n\n## ServiceMediator\n\nThe ServiceMediator metadata declares the mediating class between a model and the service. The CouchDatabase\nand CouchDocument models calls methods on this mediator to make CRUD requests.\n \n    [ServiceMediator(name=\"com.custardbelly.as3couchdb.mediator.CouchDatabaseActionMediator\")]\n\n## RequestType\n\nThe RequestType metadata delcares the interfacing request class with the service. The ICouchRequest implementation\nis handed to the ServiceMediator in order to establish the proper handling of requests from the service.\nThe main purpose of the RequestType is to handle multiple runtimes and there URLRequest restrictions.\nThe Flash Player for AIR supports PUT and DELETE requests, but such requests are not available in the web-based\nFlash Player. As such, HTTPCouchRequest is available in as3couchdb and uses the as3httpclient library to make the\nrequests over a socket. Other implementations are ExInCouchRequest which uses ExternalInterface.\n\n    [RequestType(name=\"com.custardbelly.as3couchdb.service.HTTPCouchRequest\")]\n\nThe CouchDatabase and CouchDocument models extend CouchModel which uses a CouchModelEntity to parse these annotations\nand wire the models up to perform requests by calling methods on the model themselves.\n\nThe models are extensions to EventDispatcher and the ServiceMediator handles dispatching the appropriate events\nrelated to response from the CouchDB service. You can listen for these corresponding CRUD events on the models as well\nas basic result and fault events.\n\n# Examples #\n\nTo start off, you would create custom models in your application that extend CouchDatabase and CouchDocument.\n\nThe following is an example of a custom CouchDatabase model using annotations:\n\n    [DocumentService(url=\"http://127.0.0.1:5984\", name=\"contacts\")]\n    [ServiceMediator(name=\"com.custardbelly.as3couchdb.mediator.CouchDatabaseActionMediator\")]\n    [RequestType(name=\"com.custardbelly.as3couchdb.service.HTTPCouchRequest\")]\n    public class ContactDatabase extends CouchDatabase\n    {\n      public function ContactDatabase()\n      {\n        super();\n      }\n    }\n\nThe following is an example of instantiating a CouchDatabase with a custom CouchModelEntity:\n\n\tvar mediator:ICouchActionMediator = new CouchDatabaseActionMediator();\n\tvar request:IServiceRequest = new HTTPCouchRequest();\n\tvar entity:CouchModelEntity = new CouchModelEntity( \"http://127.0.0.1:5984\", \"contacts\", request, mediator );\n\tvar database:ContactDatabase = new ContactDatabase( entity );\n\tdatabase.addEventListener( CouchActionType.CREATE, handleDatabaseReadCreate, false, 0, true );\n\tdatabase.createIfNotExist();\n\t...\n\tprotected function handleDatabaseReadCreate( evt:CouchEvent ):void\n\t{\n\t\tvar result:CouchServiceResult = evt.data as CouchServiceResult;\n\t\tvar database:ContactDatabase = result.data as ContactDatabase;\n\t}\n\nThe following is an example of a custom CouchDocument model using annotations:\n    \n    [DocumentService(url=\"http://127.0.0.1:5984\", name=\"contacts\")]\n    [ServiceMediator(name=\"com.custardbelly.as3couchdb.mediator.CouchDocumentActionMediator\")]\n    [RequestType(name=\"com.custardbelly.as3couchdb.service.HTTPCouchRequest\")]\n    \t\n    [Bindable]\n    public class ContactDocument extends CouchDocument\n    {\n    \tpublic var firstName:String;\n    \tpublic var lastName:String;\n    \tpublic var email:String;\n    \t\n    \tpublic function ContactDocument()\n    \t{\n    \t\tsuper();\n    \t}\n    }\n    \nThe following is an example of instantiating a CouchDocument with a custom CouchModelEntity:\n\n\tvar mediator:ICouchActionMediator = new CouchDatabaseActionMediator();\n\tvar request:IServiceRequest = new HTTPCouchRequest();\n\tvar entity:CouchModelEntity = new CouchModelEntity( \"http://127.0.0.1:5984\", \"contacts\", request, mediator );\n\tvar document:ContactDocument = new ContactDocument( entity );\n\tdocument.addEventListener( CouchActionType.CREATE, handleDocumentCreate, false, 0, true );\n\tdocument.create();\n\t...\n\tprotected function handleDocumentCreate( evt:CouchEvent )\n\t{\n\t\tvar result:CouchServiceResult = evt.data as CouchServiceResult;\n\t\tvar document:ContactDocument = result.data as ContactDocument;\n\t}\n\nThe following is an example of a CouchUser model using annotations:\n  \n    [DocumentService(url=\"http://127.0.0.1:5984\", name=\"contacts\")]\n    [ServiceMediator(name=\"com.custardbelly.as3couchdb.mediator.CouchSessionActionMediator\")]\n    [RequestType(name=\"com.custardbelly.as3couchdb.service.HTTPSessionRequest\")]\n    public class ContactUser extends CouchSession\n    {\n    \tpublic function ContactUser( username:String = null, password:String = null )\n    \t{\n    \t\tsuper( username, password );\n    \t}\n    }\n    \nThe following is an example of instantiating a CouchUser with a custom CouchModelEntity:\n\n\tvar mediator:ICouchActionMediator = new CouchDatabaseActionMediator();\n\tvar request:IServiceRequest = new HTTPCouchRequest();\n\tvar entity:CouchModelEntity = new CouchModelEntity( \"http://127.0.0.1:5984\", \"contacts\", request, mediator );\n\tvar user:ContactUser = new ContactUser( entity );\n\tuser.addEventListener( CouchActionType.CREATE, handleUserCreate, false, 0, true );\n\tuser.addEventListener( CouchActionType.LOGIN, handleUserLogin, false, 0, true );\n\tuser.signUp();\n\t...\n\tprotected function handleUserCreate( evt:CouchEvent )\n\t{\n\t\tvar result:CouchServiceResult = evt.data as CouchServiceResult;\n\t\tvar user:ContactUser = result.data as ContactUser;\n\t\tuser.login();\n\t}\n\tprotected function handleUserLogin( evt:CouchEvent )\n\t{\n\t\t// persistant session has been created and will be used on any further transactions with the CouchDB instance.\n\t}\n\nOnce a CouchUser has been logged in, any subsequent request on documents and databases will be based on the current session. as3couchdb handles renewing\na session after a defined time lapse (the default time lapse for CouchDB is 10 minutes. This can be modified in the CouchDB instance).\n\nCouchUser is required if you are not running what is referred to as an \"admin party\" on your CouchDB instance. This means there are no administrators defined for your CouchDB instance,\nand any one can make any type of transaction. Once you have set up the CouchDB instance to have at least on administrator, that administrator must be logged in (using CouchUser) and a valid session available in order\nto signUp() new CouchUser objects and to createIfNotExists() new CouchDatabase objects.\n\n## Further Examples\n\nThe following is an example of accessing all the documents within the ContactDatabase:\n  \n    var database:CouchDatabase = new ContactDatabase();\n    database.addEventListener( CouchActionType.CREATE, handleCouchDatabaseReady );\n    database.createIfNotExist();\n    \n    private function handleCouchDatabaseReady( evt:CouchEvent ):void\n    {\n    \tdatabase.addEventListener( CouchActionType.READ_ALL, handleReadAllDocuments );\n    \t// Pass the class type to resolve payload documents to.\n    \tdatabase.getAllDocuments( \"com.custardbelly.couchdb.model.ContactDocument\" );\n    }\n    \t\t\n    private function handleReadAllDocuments( evt:CouchEvent ):void\n    {\n    \tdatabase.removeEventListener( CouchActionType.READ_ALL, handleReadAllDocuments );\n    \t\n    \tvar contacts:ArrayCollection = new ArrayCollection();\n    \tvar contactList:Array = ( evt.data as CouchServiceResult ).data as Array;\n    \tvar i:int = contactList.length;\n    \twhile( --i \u003e -1 )\n    \t{\n    \t\tcontacts.addItem( contactList[i] );\n    \t}\n    }\n\nTo create a new document in CouchDatabase:\n\n    var contact:ContactDocument = new ContactDocument();\n    contact.firstName = firstNameField.text;\n    contact.lastName = lastNameField.text;\n    contact.email = emailField.text;\n    contact.addEventListener( CouchActionType.CREATE, handleContactSave );\n    contact.addEventListener( CouchEvent.FAULT, handleContactFault );\n    contact.create();\n\nThe create() method is used for Create and Update. The read() method Reads the document from the\ndatabase and populates the model. The update() method saves any changes to the database instance.\nThe remove() method Deletes the document from the database.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustardcelly%2Fas3couchdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbustardcelly%2Fas3couchdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustardcelly%2Fas3couchdb/lists"}