Nutella Peanut-Butter Marshmallow
    Wondering what’s next for npm?Check out our public roadmap! »

    common-circle

    0.3.0 • Public • Published

    common-circle

    A General Implementation of User and Group Management

    Using Waterline under the covers.

    🚧 Highly Work In Progress 🚧

    node npm Travis Gemnasium Coveralls

    toc:

    1. installation
    2. principles
    3. API
    4. adapters
    5. license

    installation:

    $ npm install common-circle

    principles:

    Why did you make common-circle?

    Well, we have been working on some applications that require simple user management. In the different applications, we had to build it from scratch. This means more code to write, more tests to run, etc. This is tiring.

    Using a single module for user and group management would ensure less work. Let's invent the wheel just once.

    Does it work for my application?

    If your application requires simple user and group management, this module might work.

    This module implements common database models and methods such as user tokens, matching user's password, etc. It aims at reducing the work of re-implementing such common stuff while not enforcing a way of doing things in your application.

    This module might not satisfy all your application needs. It is up to you to see if the module suits your application. You can always build around it to meet your needs. This way you just focus on the needs the module does not satisfy.

    API:

    import circle from "common-circle";

    Before starting to handling entities, you'll need to initialize the circle.

    The API is centered around three entities:

    • Group: a group of users, sharing roles (circle.group)
      • each group has its own leaders
    • User: an application user (circle.user)
    • Token: a user's token, usually for authorization (circle.token)

    Also, the following inner modules are exported off circle:

    • errors: for handling errors (currently, almost useless)
    • orm: for handling custom schema/models. See orm.

    circle.init(config, done)

    Initializes the circle.

    • config (Object)
      • config.adapter (Object): configurations for your adapter
      • config.adapter.name (String): name of adapter e.g. "sails-disk". See adapters.
      • config.schemas (Object): mapping of schemas
    • done(err) (Function): called once the circle is done initialized

    By default, circle uses sails-disk. If you are testing out things, you need not configure aything at all. Just pass an empty object, {}.

    The groups, admin and public, are created automatically for you.

    Since you might want to modify the built-in schemas or even add new ones, config.schemas can be used. It is an object of schemas. For example,

    {
      dog: {
        attributes: {
          name: { type: "string" },
        },
      },
      cat: {
        attributes: {
          name: { type: "string" },
          meow() {
            console.log("meow");
          },
        },
      },
    }

    The built-in schemas and user schemas (the ones you pass here) are merged together. This means that you can simply modify a built-in schema by defining the modified properties in config.schemas.<identity>.

    Modifying built-in schemas may be necessary for validations. This module does not wish to enforce any constraints on you. Choose what fits for you.

    For example, modifying user schema,

    {
      user: {
        attributes: {
          hometown: {
            type: "string",
          },
        },
      },
    }

    See how to define schemas. Note that the properties identity and connection can be omitted, in which case, they will default to key of the schema (e.g. "dog" or "cat") and "default" respectively.

    If you wish to modify the built-in schemas, inspect them in the relevant files in src/.

    Errors may occur if:

    • adapter is not installed
    • underlying waterline orm failed to initialize

    Group:

    group identifier:

    • query: (Object)
      • query.name (String): name of group
      • query.id (Number): id of group

    query.name and query.id are mutually exclusive.

    group.createGroup(params, done)

    Creates a new group.

    • params (Object): group properties
      • params.name (String): name of the group
    • done(err) (Function)
      • err (Error)

    Errors may occur if:

    • group already exists

    group.deleteGroup(query, done)

    Deletes group.

    Errors may occur if:

    • group does not exist

    group.getGroup(query, done)

    Get a single group. The group is populated with its members and leaders.

    • query (Object): identifier
    • done(err, group) (Function)
      • err (Error)
      • group (Object|null)

    group.getGroups(done)

    Get all groups.

    • done(err, groups) (Function)
      • err (Error)
      • groups (Array): an array of groups

    User:

    user identifier:

    • query: (Object)
      • query.username (String): username of user
      • query.id (Number): id of group

    query.username and query.id are mutually exclusive.

    user model:

    • username (String)
    • password (String)
    • tokens (String[])
    • matchPassword(password, done)
      • password (String)
      • done(err, isCorrect)

    user.createUser(query, done)

    Create a single user.

    • query (Object):
      • query.user.username (String): username of user
      • query.user.password (String): password of user
      • query.group: identifier. If not specified, user is created in the public group.
    • done(err) (Function)
      • err (Error)

    Errors may occur if:

    • user already exists
    • group does not exist

    user.updateUser(query, updates, done)

    Update user information.

    • query (Object): (identifier)
    • updates (Object): properties to update
    • done(err) (Function)
      • err (Error)

    user.deleteUser(query, done)

    Delete a single user.

    • query (Object): identifier
    • done(err) (Function)
      • err (Error)

    Errors may occur if:

    • user does not exist

    user.getUser(query, done)

    Get a single user. The user, if found, is populated with tokens, groups they are member and leader of.

    user.getUsers(done)

    Get all users.

    • done(err, users) (Function):
      • err (Error)
      • users (Array): array of users

    user.addLeaderToGroup(query, done)

    Add user as leader of group.

    Errors may occur if:

    • user is already a leader in the group
    • user does not exist
    • group does not exist

    user.addMemberToGroup(query, done)

    Add user as member of group.

    Errors may occur if:

    • user is already a member in the group
    • user does not exist
    • group does not exist

    user.isAdmin(query, done)

    Check if user is administrator.

    • query (Object)
    • done(err, isAdmin)
      • err (Error)
      • isAdmin (Boolean)

    user.isMemberInGroup(query, done)

    Check if user is member of group.

    Errors may occur if:

    • group does not exist

    user.isLeaderInGroup(query, done)

    Check if user is a leader of the group.

    Errors may occur if:

    • group does not exist

    user.removeLeaderFromGroup(query, done)

    Remove user as leader from group.

    Errors may occur if:

    • user is not a group leader
    • group does not exist

    user.removeMemberFromGroup(query, done)

    Remove user as member from group.

    Errors may occur if:

    • user is not a group member
    • group does not exist

    Token:

    token:

    A token is a UUID (universally unique identifier). It is hashed and stored into store.

    token.createToken(query, done)

    Create a token for a user.

    • query (Object)
    • done(err, token) (Function)
      • err (Error)
      • token (String): token

    Errors may occur if:

    • user does not exist

    token.deleteToken(query, token, done)

    Delete a token.

    Errors may occur if:

    • token does not exist
    • user does not exist

    token.tokenExists(query, token, done)

    • query (Object)
    • token (String): token
    • done(err, exists) (Function)
      • err (Error)
      • exists (Boolean)

    Errors may occur if:

    • user does not exist

    orm:

    The sub-module, orm, is used to handle custom models you might have defined.

    orm.getModels():

    Returns the models from the underlying orm. See getting started with models/Waterline.

    adapters:

    Since we use different databases for different purposes, we are using an ORM, Waterline. It allows us to use different adapters for different databases.

    See the supported adapters.

    license:

    The MIT License (MIT)

    Copyright © 2015 Forfuture, LLC we@forfuture.co.ke

    Install

    npm i common-circle

    DownloadsWeekly Downloads

    3

    Version

    0.3.0

    License

    MIT

    Last publish

    Collaborators

    • avatar