The users module

This module contains functions for managing user documents. This includes listing available users as well as CRUD operations on user documents.

Functions in this module follow the node.js callback style. The first argument is an error object (if one occurred), the following arguments are the results of the operation. The callback is always the last argument to a function.

Usage

First, add users to the dependencies in kanso.json.

// in kanso.json
{
    "dependencies": {
        ...
        "users": null
    }
}

Remember to do kanso install, then simply require the users module.

// in your code
var users = require("users");

Functions in the user module must be used client-side. You cannot use them in CouchDB show, list or update functions. If you are using the Duality framework, you can use them inside an 'afterResponse' event handler.

API

delete(username, callback)

Deletes an existing user document, given its username. You must be logged in as an administrative user for this function to succeed.

• username - String - the username of the user to delete
• callback - Function - function called on completion of the operation

users.delete('username', function (err) {
    if (err) // there was an error deleting the user
    else     // success
});

get(username, callback)

Get a single user document by username.

• username - String - the username of the user to get
• callback - Function - function called on completion

users.get('testuser', function (err, doc) {
    if (err) // there was an error fetching the user document
    else     // success 
});

list([q], callback)

List users in the auth database. By default, it will list all users. By using the optional q parameter, you can pass additional options to the \_all\_docs view for the auth database.

• q - Object - parameters to pass to authdb's _all_docs (optional)
• callback - Function - function called with the resulting list (or error)

users.list(function (err, list) {
    if (err) // there was an error querying the auth database
    else     // success
});

create(username, password, [properties], callback)

Creates a new user document with given username and password. If properties.roles contains '_admin', user will be made admin.

• username - String - the username of the new user
• password - String - the unhashed password for the new user
• properties - Object - additional properties such as roles to extend the user document with (optional)
• callback - Function - function called on completion or error

users.create('testuser', 'testing', {roles: ['example']}, function (err) {
    if (err) // an error occurred
    else     // successfully created new user
});

update(username, password, [properties], callback)

Updates an existing user document. Similar usage to the create function.

• username - String - the username of the new user
• password - String - the unhashed password for the new user
• properties - Object - additional properties such as roles to extend the user document with (optional)
• callback - Function - function called on completion or error

users.update('testuser', 'testing', {roles: ['example']}, function (err) {
    if (err) // an error occurred
    else     // successfully updated user
});

Reference

For up to date API information be sure to check out the users package page. On this page, you can also find API details for older versions of the package.