common-circle

A General Implementation of User and Group Management

Using Waterline under the covers.

🚧 Highly Work In Progress 🚧

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.

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

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.

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

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.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err) (Function)

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.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err) (Function)

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)
  • query.user: user identifier
• done(err, isAdmin)
  • err (Error)
  • isAdmin (Boolean)

user.isMemberInGroup(query, done)

Check if user is member of group.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err, isUser) (Function)
  • err (Error)
  • isUser (Boolean)

Errors may occur if:

• group does not exist

user.isLeaderInGroup(query, done)

Check if user is a leader of the group.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err, isUser) (Function)
  • err (Error)
  • isLeader (Boolean)

Errors may occur if:

• group does not exist

user.removeLeaderFromGroup(query, done)

Remove user as leader from group.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err, isUser) (Function)
  • err (Error)

Errors may occur if:

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

user.removeMemberFromGroup(query, done)

Remove user as member from group.

• query (Object)
  • query.user: user identifier
  • query.group: group identifier
• done(err, isUser) (Function)
  • err (Error)

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)
  • query.user: user identifier
• 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.

• query (Object)
  • query.user: user identifier
• token (String): token
• done(err) (Function)
  • err (Error)

Errors may occur if:

• token does not exist
• user does not exist

token.tokenExists(query, token, done)

• query (Object)
  • query.user: user identifier
• 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 [e-mail]