role.js

const _ = require('underscore');
const AVError = require('./error');

module.exports = function(AV) {
  AV.Role = AV.Object.extend(
    '_Role',
    /** @lends AV.Role.prototype */ {
      // Instance Methods

      /**
       * Represents a Role on the AV server. Roles represent groupings of
       * Users for the purposes of granting permissions (e.g. specifying an ACL
       * for an Object). Roles are specified by their sets of child users and
       * child roles, all of which are granted any permissions that the parent
       * role has.
       *
       * <p>Roles must have a name (which cannot be changed after creation of the
       * role), and must specify an ACL.</p>
       * An AV.Role is a local representation of a role persisted to the AV
       * cloud.
       * @class AV.Role
       * @param {String} name The name of the Role to create.
       * @param {AV.ACL} acl The ACL for this role.
       */
      constructor: function(name, acl) {
        if (_.isString(name)) {
          AV.Object.prototype.constructor.call(this, null, null);
          this.setName(name);
        } else {
          AV.Object.prototype.constructor.call(this, name, acl);
        }
        if (acl) {
          if (!(acl instanceof AV.ACL)) {
            throw new TypeError('acl must be an instance of AV.ACL');
          } else {
            this.setACL(acl);
          }
        }
      },

      /**
       * Gets the name of the role.  You can alternatively call role.get("name")
       *
       * @return {String} the name of the role.
       */
      getName: function() {
        return this.get('name');
      },

      /**
       * Sets the name for a role. This value must be set before the role has
       * been saved to the server, and cannot be set once the role has been
       * saved.
       *
       * <p>
       *   A role's name can only contain alphanumeric characters, _, -, and
       *   spaces.
       * </p>
       *
       * <p>This is equivalent to calling role.set("name", name)</p>
       *
       * @param {String} name The name of the role.
       */
      setName: function(name, options) {
        return this.set('name', name, options);
      },

      /**
       * Gets the AV.Relation for the AV.Users that are direct
       * children of this role. These users are granted any privileges that this
       * role has been granted (e.g. read or write access through ACLs). You can
       * add or remove users from the role through this relation.
       *
       * <p>This is equivalent to calling role.relation("users")</p>
       *
       * @return {AV.Relation} the relation for the users belonging to this
       *     role.
       */
      getUsers: function() {
        return this.relation('users');
      },

      /**
       * Gets the AV.Relation for the AV.Roles that are direct
       * children of this role. These roles' users are granted any privileges that
       * this role has been granted (e.g. read or write access through ACLs). You
       * can add or remove child roles from this role through this relation.
       *
       * <p>This is equivalent to calling role.relation("roles")</p>
       *
       * @return {AV.Relation} the relation for the roles belonging to this
       *     role.
       */
      getRoles: function() {
        return this.relation('roles');
      },

      /**
       * @ignore
       */
      validate: function(attrs, options) {
        if ('name' in attrs && attrs.name !== this.getName()) {
          var newName = attrs.name;
          if (this.id && this.id !== attrs.objectId) {
            // Check to see if the objectId being set matches this.id.
            // This happens during a fetch -- the id is set before calling fetch.
            // Let the name be set in this case.
            return new AVError(
              AVError.OTHER_CAUSE,
              "A role's name can only be set before it has been saved."
            );
          }
          if (!_.isString(newName)) {
            return new AVError(
              AVError.OTHER_CAUSE,
              "A role's name must be a String."
            );
          }
          if (!/^[0-9a-zA-Z\-_ ]+$/.test(newName)) {
            return new AVError(
              AVError.OTHER_CAUSE,
              "A role's name can only contain alphanumeric characters, _," +
                ' -, and spaces.'
            );
          }
        }
        if (AV.Object.prototype.validate) {
          return AV.Object.prototype.validate.call(this, attrs, options);
        }
        return false;
      },
    }
  );
};