Allow number as valid role and grant type

In some cases it makes sense to have `number`s instead of `string`s for
role types.  For example, when using `enum`s in TypeScript

Author: vegerot

.travis.yml

@@ -1,7 +1,8 @@
 language: node_js
 node_js:
-  - '8'
-  - '6'
+  - '14'
+  - '12'
+  - '10'
 before_script: cd $TRAVIS_BUILD_DIR
 script:
   - npm run cover

lib/AccessControl.d.ts

@@ -1,4 +1,5 @@
 import { Access, IAccessInfo, Query, IQueryInfo, Permission } from './core';
+import type { ValidRoleOrArray, ValidRole } from '.';
 /**
  *  @classdesc
  *  AccessControl class that implements RBAC (Role-Based Access Control) basics
@@ -118,7 +119,7 @@ declare class AccessControl {
      *  @name AccessControl#isLocked
      *  @type {Boolean}
      */
-    readonly isLocked: boolean;
+    get isLocked(): boolean;
     /**
      *  Gets the internal grants object that stores all current grants.
      *
@@ -234,7 +235,7 @@ declare class AccessControl {
      *  @throws {AccessControlError} - If a role is extended by itself or a
      *  non-existent role. Or if called after `.lock()` is called.
      */
-    extendRole(roles: string | string[], extenderRoles: string | string[]): AccessControl;
+    extendRole(roles: ValidRoleOrArray, extenderRoles: ValidRoleOrArray): AccessControl;
     /**
      *  Removes all the given role(s) and their granted permissions, at once.
      *  @chainable
@@ -246,7 +247,7 @@ declare class AccessControl {
      *
      *  @throws {AccessControlError} - If called after `.lock()` is called.
      */
-    removeRoles(roles: string | string[]): AccessControl;
+    removeRoles(roles: ValidRoleOrArray): AccessControl;
     /**
      *  Removes all the given resources for all roles, at once.
      *  Pass the `roles` argument to remove access to resources for those
@@ -263,7 +264,7 @@ declare class AccessControl {
      *
      *  @throws {AccessControlError} - If called after `.lock()` is called.
      */
-    removeResources(resources: string | string[], roles?: string | string[]): AccessControl;
+    removeResources(resources: ValidRoleOrArray, roles?: ValidRoleOrArray): AccessControl;
     /**
      *  Gets all the unique roles that have at least one access information.
      *
@@ -284,12 +285,12 @@ declare class AccessControl {
      *
      *  @returns {Array<String>}
      */
-    getInheritedRolesOf(role: string): string[];
+    getInheritedRolesOf(role: ValidRole): ValidRole[];
     /**
      *  Alias of `getInheritedRolesOf`
      *  @private
      */
-    getExtendedRolesOf(role: string): string[];
+    getExtendedRolesOf(role: ValidRole): ValidRole[];
     /**
      *  Gets all the unique resources that are granted access for at
      *  least one role.
@@ -305,7 +306,7 @@ declare class AccessControl {
      *
      *  @returns {Boolean}
      */
-    hasRole(role: string | string[]): boolean;
+    hasRole(role: ValidRoleOrArray): boolean;
     /**
      *  Checks whether grants include the given resource or resources.
      *
@@ -314,7 +315,7 @@ declare class AccessControl {
      *
      *  @returns {Boolean}
      */
-    hasResource(resource: string | string[]): boolean;
+    hasResource(resource: ValidRoleOrArray): boolean;
     /**
      *  Gets an instance of `Query` object. This is used to check whether the
      *  defined access is allowed for the given role(s) and resource. This
@@ -347,12 +348,12 @@ declare class AccessControl {
      *  ac.can(['admin', 'user']).createOwn('profile');
      *  // Note: when multiple roles checked, acquired attributes are unioned (merged).
      */
-    can(role: string | string[] | IQueryInfo): Query;
+    can(role: ValidRoleOrArray | IQueryInfo): Query;
     /**
      *  Alias of `can()`.
      *  @private
      */
-    query(role: string | string[] | IQueryInfo): Query;
+    query(role: ValidRoleOrArray | IQueryInfo): Query;
     /**
      *  Gets an instance of `Permission` object that checks and defines the
      *  granted access permissions for the target resource and role. Normally
@@ -437,12 +438,12 @@ declare class AccessControl {
      *  // Note: when attributes is omitted, it will default to `['*']`
      *  // which means all attributes (of the resource) are allowed.
      */
-    grant(role?: string | string[] | IAccessInfo): Access;
+    grant(role?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  Alias of `grant()`.
      *  @private
      */
-    allow(role?: string | string[] | IAccessInfo): Access;
+    allow(role?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  Gets an instance of `Access` object. This is used to deny access to
      *  specified resource(s) for the given role(s). Denying will only remove a
@@ -495,31 +496,31 @@ declare class AccessControl {
      *  // To deny same resource for multiple roles:
      *  ac.deny(['admin', 'user']).createOwn('profile');
      */
-    deny(role?: string | string[] | IAccessInfo): Access;
+    deny(role?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  Alias of `deny()`.
      *  @private
      */
-    reject(role?: string | string[] | IAccessInfo): Access;
+    reject(role?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  @private
      */
-    _removePermission(resources: string | string[], roles?: string | string[], actionPossession?: string): void;
+    _removePermission(resources: ValidRoleOrArray, roles?: ValidRoleOrArray, actionPossession?: string): void;
     /**
      *  Documented separately in enums/Action
      *  @private
      */
-    static readonly Action: any;
+    static get Action(): any;
     /**
      *  Documented separately in enums/Possession
      *  @private
      */
-    static readonly Possession: any;
+    static get Possession(): any;
     /**
      *  Documented separately in AccessControlError
      *  @private
      */
-    static readonly Error: any;
+    static get Error(): any;
     /**
      *  A utility method for deep cloning the given data object(s) while
      *  filtering its properties by the given attribute (glob) notations.

lib/AccessControl.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessControl = void 0;
 var core_1 = require("./core");
 var enums_1 = require("./enums");
 var utils_1 = require("./utils");
@@ -130,7 +131,7 @@ var AccessControl = /** @class */ (function () {
         get: function () {
             return this._isLocked && Object.isFrozen(this._grants);
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     // -------------------------------
@@ -287,8 +288,8 @@ var AccessControl = /** @class */ (function () {
         var _this = this;
         if (this.isLocked)
             throw new core_1.AccessControlError(utils_1.ERR_LOCK);
-        var rolesToRemove = utils_1.utils.toStringArray(roles);
-        if (rolesToRemove.length === 0 || !utils_1.utils.isFilledStringArray(rolesToRemove)) {
+        var rolesToRemove = utils_1.utils.toValidRoleArray(roles);
+        if (rolesToRemove.length === 0 || !utils_1.utils.isFilledValidRoleArray(rolesToRemove)) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
         }
         rolesToRemove.forEach(function (roleName) {
@@ -631,15 +632,15 @@ var AccessControl = /** @class */ (function () {
      */
     AccessControl.prototype._removePermission = function (resources, roles, actionPossession) {
         var _this = this;
-        resources = utils_1.utils.toStringArray(resources);
+        resources = utils_1.utils.toValidRoleArray(resources);
         // resources is set but returns empty array.
-        if (resources.length === 0 || !utils_1.utils.isFilledStringArray(resources)) {
+        if (resources.length === 0 || !utils_1.utils.isFilledValidRoleArray(resources)) {
             throw new core_1.AccessControlError("Invalid resource(s): " + JSON.stringify(resources));
         }
         if (roles !== undefined) {
-            roles = utils_1.utils.toStringArray(roles);
+            roles = utils_1.utils.toValidRoleArray(roles);
             // roles is set but returns empty array.
-            if (roles.length === 0 || !utils_1.utils.isFilledStringArray(roles)) {
+            if (roles.length === 0 || !utils_1.utils.isFilledValidRoleArray(roles)) {
                 throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
             }
         }
@@ -673,7 +674,7 @@ var AccessControl = /** @class */ (function () {
         get: function () {
             return enums_1.Action;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(AccessControl, "Possession", {
@@ -684,7 +685,7 @@ var AccessControl = /** @class */ (function () {
         get: function () {
             return enums_1.Possession;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(AccessControl, "Error", {
@@ -695,7 +696,7 @@ var AccessControl = /** @class */ (function () {
         get: function () {
             return core_1.AccessControlError;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     // -------------------------------

lib/core/Access.d.ts

@@ -1,5 +1,7 @@
 import { AccessControl } from '../';
 import { IAccessInfo } from '../core';
+export declare type ValidRole = string | number;
+export declare type ValidRoleOrArray = ValidRole | ValidRole[];
 /**
  *  Represents the inner `Access` class that helps build an access information
  *  to be granted or denied; and finally commits it to the underlying grants
@@ -44,38 +46,38 @@ declare class Access {
      *  @param {Boolean} denied
      *         Specifies whether this `Access` is denied.
      */
-    constructor(ac: AccessControl, roleOrInfo?: string | string[] | IAccessInfo, denied?: boolean);
+    constructor(ac: AccessControl, roleOrInfo?: ValidRoleOrArray | IAccessInfo, denied?: boolean);
     /**
      *  Specifies whether this access is initally denied.
      *  @name AccessControl~Access#denied
      *  @type {Boolean}
      *  @readonly
      */
-    readonly denied: boolean;
+    get denied(): boolean;
     /**
      *  A chainer method that sets the role(s) for this `Access` instance.
      *  @param {String|Array<String>} value
      *         A single or array of roles.
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    role(value: string | string[]): Access;
+    role(value: ValidRoleOrArray): Access;
     /**
      *  A chainer method that sets the resource for this `Access` instance.
      *  @param {String|Array<String>} value
      *         Target resource for this `Access` instance.
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    resource(value: string | string[]): Access;
+    resource(value: ValidRoleOrArray): Access;
     /**
      *  Sets the array of allowed attributes for this `Access` instance.
      *  @param {String|Array<String>} value
      *         Attributes to be set.
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    attributes(value: string | string[]): Access;
+    attributes(value: ValidRoleOrArray): Access;
     /**
      *  Sets the roles to be extended for this `Access` instance.
      *  @alias Access#inherit
@@ -93,12 +95,12 @@ declare class Access {
      *  const permission = ac.can('admin').createAny('video');
      *  console.log(permission.granted); // true
      */
-    extend(roles: string | string[]): Access;
+    extend(roles: ValidRoleOrArray): Access;
     /**
      *  Alias of `extend`.
      *  @private
      */
-    inherit(roles: string | string[]): Access;
+    inherit(roles: ValidRoleOrArray): Access;
     /**
      *  Shorthand to switch to a new `Access` instance with a different role
      *  within the method chain.
@@ -114,7 +116,7 @@ declare class Access {
      *  ac.grant('user').createOwn('video')
      *    .grant('admin').updateAny('video');
      */
-    grant(roleOrInfo?: string | string[] | IAccessInfo): Access;
+    grant(roleOrInfo?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  Shorthand to switch to a new `Access` instance with a different
      *  (or same) role within the method chain.
@@ -130,7 +132,7 @@ declare class Access {
      *  ac.grant('admin').createAny('video')
      *    .deny('user').deleteAny('video');
      */
-    deny(roleOrInfo?: string | string[] | IAccessInfo): Access;
+    deny(roleOrInfo?: ValidRoleOrArray | IAccessInfo): Access;
     /**
      *  Chainable, convenience shortcut for {@link ?api=ac#AccessControl#lock|`AccessControl#lock()`}.
      *  @returns {Access}
@@ -159,7 +161,7 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    createOwn(resource?: string | string[], attributes?: string | string[]): Access;
+    createOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"create"` and possession to `"any"` and commits the
      *  current access instance to the underlying grant model.
@@ -185,12 +187,12 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    createAny(resource?: string | string[], attributes?: string | string[]): Access;
+    createAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Alias of `createAny`
      *  @private
      */
-    create(resource?: string | string[], attributes?: string | string[]): Access;
+    create(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"read"` and possession to `"own"` and commits the
      *  current access instance to the underlying grant model.
@@ -213,7 +215,7 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    readOwn(resource?: string | string[], attributes?: string | string[]): Access;
+    readOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"read"` and possession to `"any"` and commits the
      *  current access instance to the underlying grant model.
@@ -239,12 +241,12 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    readAny(resource?: string | string[], attributes?: string | string[]): Access;
+    readAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Alias of `readAny`
      *  @private
      */
-    read(resource?: string | string[], attributes?: string | string[]): Access;
+    read(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"update"` and possession to `"own"` and commits the
      *  current access instance to the underlying grant model.
@@ -267,7 +269,7 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    updateOwn(resource?: string | string[], attributes?: string | string[]): Access;
+    updateOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"update"` and possession to `"any"` and commits the
      *  current access instance to the underlying grant model.
@@ -293,12 +295,12 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    updateAny(resource?: string | string[], attributes?: string | string[]): Access;
+    updateAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Alias of `updateAny`
      *  @private
      */
-    update(resource?: string | string[], attributes?: string | string[]): Access;
+    update(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"delete"` and possession to `"own"` and commits the
      *  current access instance to the underlying grant model.
@@ -321,7 +323,7 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    deleteOwn(resource?: string | string[], attributes?: string | string[]): Access;
+    deleteOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Sets the action to `"delete"` and possession to `"any"` and commits the
      *  current access instance to the underlying grant model.
@@ -347,12 +349,12 @@ declare class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    deleteAny(resource?: string | string[], attributes?: string | string[]): Access;
+    deleteAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  Alias of `deleteAny`
      *  @private
      */
-    delete(resource?: string | string[], attributes?: string | string[]): Access;
+    delete(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access;
     /**
      *  @private
      *  @param {String} action     [description]
@@ -362,6 +364,6 @@ declare class Access {
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    private _prepareAndCommit(action, possession, resource?, attributes?);
+    private _prepareAndCommit;
 }
 export { Access };

lib/core/Access.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Access = void 0;
 var core_1 = require("../core");
 var enums_1 = require("../enums");
 var utils_1 = require("../utils");
@@ -40,7 +41,7 @@ var Access = /** @class */ (function () {
         this._ac = ac;
         this._grants = ac._grants;
         this._.denied = denied;
-        if (typeof roleOrInfo === 'string' || Array.isArray(roleOrInfo)) {
+        if (typeof roleOrInfo === 'string' || typeof roleOrInfo === 'number' || Array.isArray(roleOrInfo)) {
             this.role(roleOrInfo);
         }
         else if (utils_1.utils.type(roleOrInfo) === 'object') {
@@ -73,7 +74,7 @@ var Access = /** @class */ (function () {
         get: function () {
             return this._.denied;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     // -------------------------------
@@ -453,7 +454,7 @@ var Access = /** @class */ (function () {
         }
         else {
             // if omitted and not denied, all attributes are allowed
-            this._.attributes = attributes ? utils_1.utils.toStringArray(attributes) : ['*'];
+            this._.attributes = attributes ? utils_1.utils.toValidRoleArray(attributes) : ['*'];
         }
         utils_1.utils.commitToGrants(this._grants, this._, false);
         // important: reset attributes for chained methods

lib/core/AccessControlError.js

@@ -1,15 +1,19 @@
 "use strict";
 var __extends = (this && this.__extends) || (function () {
-    var extendStatics = Object.setPrototypeOf ||
-        ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
-        function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; };
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
     return function (d, b) {
         extendStatics(d, b);
         function __() { this.constructor = d; }
         d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessControlError = void 0;
 /**
  *  Error class specific to `AccessControl`.
  *  @readonly

lib/core/IAccessInfo.d.ts

@@ -1,3 +1,4 @@
+import type { ValidRoleOrArray } from '.';
 /**
  *  An interface that defines an access information to be granted or denied.
  *  When you start a method chain with `AccessControl#grant` or `AccessControl#deny`
@@ -10,19 +11,19 @@ interface IAccessInfo {
      *  Indicates a single or multiple roles for this access information.
      *  @type {String|Array<String>}
      */
-    role?: string | string[];
+    role?: ValidRoleOrArray;
     /**
      *  Indicates a single or multiple target resources for this access
      *  information.
      *  @type {String|Array<String>}
      */
-    resource?: string | string[];
+    resource?: ValidRoleOrArray;
     /**
      *  Defines the resource attributes which are granted. If denied, this will
      *  default to an empty array.
      *  @type {String|Array<String>}
      */
-    attributes?: string | string[];
+    attributes?: ValidRoleOrArray;
     /**
      *  Defines the type of the operation that is (or not) to be performed on
      *  the resource(s) by the defined role(s).
@@ -39,10 +40,40 @@ interface IAccessInfo {
      */
     possession?: string;
     /**
-     *  Single or multiple roles for this access information.
+     *  Flag for denied access.
      *  @private
      *  @type {String|Array<String>}
      */
     denied?: boolean;
 }
 export { IAccessInfo };
+/**
+ *  An interface that defines an access information to be granted or denied.
+ *  When you start a method chain with `AccessControl#grant` or `AccessControl#deny`
+ *  methods, you're actually building this  object which will eventually be
+ *  committed to the underlying grants model.
+ *  @name AccessControl~IAccessInfo
+ *  @type {Object}
+ *
+ *  @property {String|Array<String>} role
+ *  Indicates a single or multiple roles for this access information.
+ *
+ *  @property {String|Array<String>} resource
+ *  Indicates a single or multiple target resources for this access
+ *  information.
+ *
+ *  @property {String|Array<String>} attributes
+ *  Defines the resource attributes which are granted. If denied, this will
+ *  default to an empty array.
+ *
+ *  @property {String} action
+ *  Defines the type of the operation that is (or not) to be performed on
+ *  the resource(s) by the defined role(s).
+ *  See {@link ?api=ac#AccessControl.Action|`AccessControl.Action` enumeration}
+ *  for possible values.
+ *
+ *  @property {String} possession
+ *  Defines the possession of the resource(s) for the specified action.
+ *  See {@link ?api=ac#AccessControl.Possession|`AccessControl.Possession` enumeration}
+ *  for possible values.
+ */

lib/core/IQueryInfo.d.ts

@@ -1,3 +1,4 @@
+import type { ValidRoleOrArray } from '.';
 /**
  *  An interface that defines an access information to be queried.
  *  When you start a method chain with `AccessControl#can` method, you're
@@ -10,7 +11,7 @@ interface IQueryInfo {
      *  Indicates a single or multiple roles to be queried.
      *  @type {String|Array<String>}
      */
-    role?: string | string[];
+    role?: ValidRoleOrArray;
     /**
      *  Indicates the resource to be queried.
      *  @type {String}
@@ -33,3 +34,28 @@ interface IQueryInfo {
     possession?: string;
 }
 export { IQueryInfo };
+/**
+ *  An interface that defines an access information to be queried.
+ *  When you start a method chain with `AccessControl#can` method, you're
+ *  actually building this query object which will be used to check the access
+ *  permissions.
+ *  @name AccessControl~IQueryInfo
+ *  @type {Object}
+ *
+ *  @property {String|Array<String>} role
+ *  Indicates a single or multiple roles to be queried.
+ *
+ *  @property {String} resource
+ *  Indicates the resource to be queried.
+ *
+ *  @property {String} action
+ *  Defines the type of the operation that is (or not) to be performed on
+ *  the resource by the defined role(s).
+ *  See {@link ?api=ac#AccessControl.Action|`AccessControl.Action` enumeration}
+ *  for possible values.
+ *
+ *  @property {String} possession
+ *  Defines the possession of the resource for the specified action.
+ *  See {@link ?api=ac#AccessControl.Possession|`AccessControl.Possession` enumeration}
+ *  for possible values.
+ */

lib/core/Permission.d.ts

@@ -60,15 +60,15 @@ declare class Permission {
      *  @type {Array<String>}
      *  @readonly
      */
-    readonly roles: string[];
+    get roles(): string[];
     /**
      *  Specifies the target resource for which the permission is queried for.
      *
      *  @name AccessControl~Permission#resource
      *  @type {String}
      *  @readonly
      */
-    readonly resource: string;
+    get resource(): string;
     /**
      *  Gets an array of allowed attributes which are defined via
      *  Glob notation. If access is not granted, this will be an empty array.
@@ -81,7 +81,7 @@ declare class Permission {
      *  @type {Array<String>}
      *  @readonly
      */
-    readonly attributes: string[];
+    get attributes(): string[];
     /**
      *  Specifies whether the permission is granted. If `true`, this means at
      *  least one attribute of the target resource is allowed.
@@ -90,7 +90,7 @@ declare class Permission {
      *  @type {Boolean}
      *  @readonly
      */
-    readonly granted: boolean;
+    get granted(): boolean;
     /**
      *  Filters the given data object (or array of objects) by the permission
      *  attributes and returns this data with allowed attributes.

lib/core/Permission.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Permission = void 0;
 var utils_1 = require("../utils");
 /**
  *  Represents the inner `Permission` class that defines the granted or denied
@@ -71,7 +72,7 @@ var Permission = /** @class */ (function () {
         get: function () {
             return this._.role;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Permission.prototype, "resource", {
@@ -85,7 +86,7 @@ var Permission = /** @class */ (function () {
         get: function () {
             return this._.resource;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Permission.prototype, "attributes", {
@@ -104,7 +105,7 @@ var Permission = /** @class */ (function () {
         get: function () {
             return this._.attributes;
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     Object.defineProperty(Permission.prototype, "granted", {
@@ -124,7 +125,7 @@ var Permission = /** @class */ (function () {
                 return attr.trim().slice(0, 1) !== '!';
             });
         },
-        enumerable: true,
+        enumerable: false,
         configurable: true
     });
     /**

lib/core/Query.d.ts

@@ -1,4 +1,5 @@
 import { IQueryInfo, Permission } from '../core';
+import type { ValidRoleOrArray } from '.';
 /**
  *  Represents the inner `Query` class that helps build an access information
  *  for querying and checking permissions, from the underlying grants model.
@@ -32,15 +33,15 @@ declare class Query {
      *         Either a single or array of roles or an
      *         {@link ?api=ac#AccessControl~IQueryInfo|`IQueryInfo` arbitrary object}.
      */
-    constructor(grants: any, roleOrInfo?: string | string[] | IQueryInfo);
+    constructor(grants: any, roleOrInfo?: ValidRoleOrArray | IQueryInfo);
     /**
      *  A chainer method that sets the role(s) for this `Query` instance.
      *  @param {String|Array<String>} roles
      *         A single or array of roles.
      *  @returns {Query}
      *           Self instance of `Query`.
      */
-    role(role: string | string[]): Query;
+    role(role: ValidRoleOrArray): Query;
     /**
      *  A chainer method that sets the resource for this `Query` instance.
      *  @param {String} resource
@@ -212,6 +213,6 @@ declare class Query {
      *  @param {String} [resource]
      *  @returns {Permission}
      */
-    private _getPermission(action, possession, resource?);
+    private _getPermission;
 }
 export { Query };

lib/core/Query.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Query = void 0;
 var core_1 = require("../core");
 var enums_1 = require("../enums");
 var utils_1 = require("../utils");

lib/core/index.js

@@ -1,9 +1,18 @@
 "use strict";
-function __export(m) {
-    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
-}
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-__export(require("./AccessControlError"));
-__export(require("./Access"));
-__export(require("./Query"));
-__export(require("./Permission"));
+__exportStar(require("./AccessControlError"), exports);
+__exportStar(require("./IAccessInfo"), exports);
+__exportStar(require("./Access"), exports);
+__exportStar(require("./IQueryInfo"), exports);
+__exportStar(require("./Query"), exports);
+__exportStar(require("./Permission"), exports);

lib/enums/Action.d.ts

@@ -8,9 +8,29 @@
  *  @memberof! AccessControl
  */
 declare const Action: {
+    /**
+     *  Specifies a CREATE action to be performed on a resource.
+     *  For example, an HTTP POST request or an INSERT database operation.
+     *  @type {String}
+     */
     CREATE: string;
+    /**
+     *  Specifies a READ action to be performed on a resource.
+     *  For example, an HTTP GET request or an database SELECT operation.
+     *  @type {String}
+     */
     READ: string;
+    /**
+     *  Specifies an UPDATE action to be performed on a resource.
+     *  For example, an HTTP PUT or POST request or an database UPDATE operation.
+     *  @type {String}
+     */
     UPDATE: string;
+    /**
+     *  Specifies a DELETE action to be performed on a resource.
+     *  For example, an HTTP DELETE request or a database DELETE operation.
+     *  @type {String}
+     */
     DELETE: string;
 };
 export { Action };

lib/enums/Action.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Action = void 0;
 /**
  *  Enumerates the possible actions of a role.
  *  An action defines the type of an operation that will be executed on a

lib/enums/Possession.d.ts

@@ -7,7 +7,17 @@
  *  @memberof! AccessControl
  */
 declare const Possession: {
+    /**
+     *  Indicates that the action is (or not) to be performed on <b>own</b>
+     *  resource(s) of the current subject.
+     *  @type {String}
+     */
     OWN: string;
+    /**
+     *  Indicates that the action is (or not) to be performed on <b>any</b>
+     *  resource(s); including <i>own</i> resource(s) of the current subject.
+     *  @type {String}
+     */
     ANY: string;
 };
 export { Possession };

lib/enums/Possession.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.Possession = void 0;
 /**
  *  Enumerates the possible possessions of a resource, for an action.
  *  A possession defines whether the action is (or not) to be performed on "own"

lib/enums/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.possessions = exports.Possession = exports.actions = exports.Action = void 0;
 var Action_1 = require("./Action");
-exports.Action = Action_1.Action;
+Object.defineProperty(exports, "Action", { enumerable: true, get: function () { return Action_1.Action; } });
 var Possession_1 = require("./Possession");
-exports.Possession = Possession_1.Possession;
+Object.defineProperty(exports, "Possession", { enumerable: true, get: function () { return Possession_1.Possession; } });
 var actions = Object.keys(Action_1.Action).map(function (k) { return Action_1.Action[k]; });
 exports.actions = actions;
 var possessions = Object.keys(Possession_1.Possession).map(function (k) { return Possession_1.Possession[k]; });

lib/index.js

@@ -1,7 +1,14 @@
 "use strict";
-function __export(m) {
-    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
-}
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-__export(require("./AccessControl"));
-__export(require("./core"));
+__exportStar(require("./AccessControl"), exports);
+__exportStar(require("./core"), exports);

lib/utils.d.ts

@@ -1,5 +1,6 @@
 import { AccessControl } from './';
 import { IAccessInfo, IQueryInfo } from './core';
+import type { ValidRole, ValidRoleOrArray } from '.';
 /**
  *  List of reserved keywords.
  *  i.e. Roles, resources with these names are not allowed.
@@ -10,40 +11,326 @@ declare const RESERVED_KEYWORDS: string[];
  */
 declare const ERR_LOCK = "Cannot alter the underlying grants model. AccessControl instance is locked.";
 declare const utils: {
+    /**
+     *  Gets the type of the given object.
+     *  @param {Any} o
+     *  @returns {String}
+     */
     type(o: any): string;
+    /**
+     *  Specifies whether the given value is set (other that `null` or
+     *  `undefined`).
+     *  @param {Any} o - Value to be checked.
+     *  @returns {Boolean}
+     */
+    /**
+     *  Specifies whether the property/key is defined on the given object.
+     *  @param {Object} o
+     *  @param {string} propName
+     *  @returns {Boolean}
+     */
     hasDefined(o: any, propName: string): boolean;
-    toStringArray(value: any): string[];
-    isFilledStringArray(arr: any[]): boolean;
+    /**
+     *  Converts the given (string) value into an array of string. Note that
+     *  this does not throw if the value is not a string or array. It will
+     *  silently return `[]` (empty array). So where ever it's used, the host
+     *  function should consider throwing.
+     *  @param {Any} value
+     *  @returns {string[]}
+     */
+    toValidRoleArray(value: unknown): ValidRole[];
+    /**
+     *  Checks whether the given array consists of non-empty string items.
+     *  (Array can be empty but no item should be an empty string.)
+     *  @param {Array} arr - Array to be checked.
+     *  @returns {Boolean}
+     */
+    isFilledValidRoleArray(arr: unknown[]): arr is (string | number)[];
+    isValidRole(e: unknown): e is string | number;
+    /**
+     *  Checks whether the given value is an empty array.
+     *  @param {Any} value - Value to be checked.
+     *  @returns {Boolean}
+     */
     isEmptyArray(value: any): boolean;
-    pushUniq(arr: string[], item: string): string[];
-    uniqConcat(arrA: string[], arrB: string[]): string[];
-    subtractArray(arrA: string[], arrB: string[]): string[];
+    /**
+     *  Ensures that the pushed item is unique in the target array.
+     *  @param {Array} arr - Target array.
+     *  @param {Any} item - Item to be pushed to array.
+     *  @returns {Array}
+     */
+    pushUniq(arr: ValidRole[], item: ValidRole): ValidRole[];
+    /**
+     *  Concats the given two arrays and ensures all items are unique.
+     *  @param {Array} arrA
+     *  @param {Array} arrB
+     *  @returns {Array} - Concat'ed array.
+     */
+    uniqConcat(arrA: ValidRole[], arrB: ValidRole[]): ValidRole[];
+    /**
+     *  Subtracts the second array from the first.
+     *  @param {Array} arrA
+     *  @param {Array} arrB
+     *  @return {Array} - Resulting array.
+     */
+    subtractArray(arrA: ValidRole[], arrB: ValidRole[]): ValidRole[];
+    /**
+     *  Deep freezes the given object.
+     *  @param {Object} o - Object to be frozen.
+     *  @returns {Object} - Frozen object.
+     */
     deepFreeze(o: any): any;
+    /**
+     *  Similar to JS .forEach, except this allows for breaking out early,
+     *  (before all iterations are executed) by returning `false`.
+     *  @param array
+     *  @param callback
+     *  @param thisArg
+     */
     each(array: any, callback: any, thisArg?: any): void;
+    /**
+     *  Iterates through the keys of the given object. Breaking out early is
+     *  possible by returning `false`.
+     *  @param object
+     *  @param callback
+     *  @param thisArg
+     */
     eachKey(object: any, callback: any, thisArg?: any): void;
     eachRole(grants: any, callback: (role: any, roleName: string) => void): void;
+    /**
+     *
+     */
     eachRoleResource(grants: any, callback: (role: string, resource: string, resourceDefinition: any) => void): void;
+    /**
+     *  Checks whether the given access info can be commited to grants model.
+     *  @param {IAccessInfo|IQueryInfo} info
+     *  @returns {Boolean}
+     */
     isInfoFulfilled(info: IAccessInfo | IQueryInfo): boolean;
-    validName(name: string, throwOnInvalid?: boolean): boolean;
+    /**
+     *  Checks whether the given name can be used and is not a reserved keyword.
+     *
+     *  @param {string} name - Name to be checked.
+     *  @param {boolean} [throwOnInvalid=true] - Specifies whether to throw if
+     *  name is not valid.
+     *
+     *  @returns {Boolean}
+     *
+     *  @throws {AccessControlError} - If `throwOnInvalid` is enabled and name
+     *  is invalid.
+     */
+    validName(name: ValidRole, throwOnInvalid?: boolean): boolean;
+    /**
+     *  Checks whether the given array does not contain a reserved keyword.
+     *
+     *  @param {string|string[]} list - Name(s) to be checked.
+     *  @param {boolean} [throwOnInvalid=true] - Specifies whether to throw if
+     *  name is not valid.
+     *
+     *  @returns {Boolean}
+     *
+     *  @throws {AccessControlError} - If `throwOnInvalid` is enabled and name
+     *  is invalid.
+     */
     hasValidNames(list: any, throwOnInvalid?: boolean): boolean;
+    /**
+     *  Checks whether the given object is a valid resource definition object.
+     *
+     *  @param {Object} o - Resource definition to be checked.
+     *
+     *  @returns {Boolean}
+     *
+     *  @throws {AccessControlError} - If `throwOnInvalid` is enabled and object
+     *  is invalid.
+     */
     validResourceObject(o: any): boolean;
+    /**
+     *  Checks whether the given object is a valid role definition object.
+     *
+     *  @param {Object} grants - Original grants object being inspected.
+     *  @param {string} roleName - Name of the role.
+     *
+     *  @returns {Boolean}
+     *
+     *  @throws {AccessControlError} - If `throwOnInvalid` is enabled and object
+     *  is invalid.
+     */
     validRoleObject(grants: any, roleName: string): boolean;
+    /**
+     *  Inspects whether the given grants object has a valid structure and
+     *  configuration; and returns a restructured grants object that can be used
+     *  internally by AccessControl.
+     *
+     *  @param {Object|Array} o - Original grants object to be inspected.
+     *
+     *  @returns {Object} - Inspected, restructured grants object.
+     *
+     *  @throws {AccessControlError} - If given grants object has an invalid
+     *  structure or configuration.
+     */
     getInspectedGrants(o: any): any;
+    /**
+     *  Gets all the unique resources that are granted access for at
+     *  least one role.
+     *
+     *  @returns {string[]}
+     */
     getResources(grants: any): string[];
-    normalizeActionPossession(info: IAccessInfo | IQueryInfo, asString?: boolean): string | IAccessInfo | IQueryInfo;
+    /**
+     *  Normalizes the actions and possessions in the given `IQueryInfo` or
+     *  `IAccessInfo`.
+     *
+     *  @param {IQueryInfo|IAccessInfo} info
+     *  @param {boolean} [asString=false]
+     *
+     *  @return {IQueryInfo|IAccessInfo|string}
+     *
+     *  @throws {AccessControlError} - If invalid action/possession found.
+     */
+    normalizeActionPossession(info: IQueryInfo | IAccessInfo, asString?: boolean): IQueryInfo | IAccessInfo | string;
+    /**
+     *  Normalizes the roles and resources in the given `IQueryInfo`.
+     *
+     *  @param {IQueryInfo} info
+     *
+     *  @return {IQueryInfo}
+     *
+     *  @throws {AccessControlError} - If invalid role/resource found.
+     */
     normalizeQueryInfo(query: IQueryInfo): IQueryInfo;
+    /**
+     *  Normalizes the roles and resources in the given `IAccessInfo`.
+     *
+     *  @param {IAccessInfo} info
+     *  @param {boolean} [all=false] - Whether to validate all properties such
+     *  as `action` and `possession`.
+     *
+     *  @return {IQueryInfo}
+     *
+     *  @throws {AccessControlError} - If invalid role/resource found.
+     */
     normalizeAccessInfo(access: IAccessInfo, all?: boolean): IAccessInfo;
+    /**
+     *  Used to re-set (prepare) the `attributes` of an `IAccessInfo` object
+     *  when it's first initialized with e.g. `.grant()` or `.deny()` chain
+     *  methods.
+     *  @param {IAccessInfo} access
+     *  @returns {IAccessInfo}
+     */
     resetAttributes(access: IAccessInfo): IAccessInfo;
-    getRoleHierarchyOf(grants: any, roleName: string, rootRole?: string): string[];
-    getFlatRoles(grants: any, roles: string | string[]): string[];
-    getNonExistentRoles(grants: any, roles: string[]): string[];
-    getCrossExtendingRole(grants: any, roleName: string, extenderRoles: string | string[]): string;
-    extendRole(grants: any, roles: string | string[], extenderRoles: string | string[]): void;
-    preCreateRoles(grants: any, roles: string | string[]): void;
+    /**
+     *  Gets a flat, ordered list of inherited roles for the given role.
+     *  @param {Object} grants - Main grants object to be processed.
+     *  @param {string} roleName - Role name to be inspected.
+     *  @returns {string[]}
+     */
+    getRoleHierarchyOf(grants: any, roleName: ValidRole, rootRole?: ValidRole): ValidRole[];
+    /**
+     *  Gets roles and extended roles in a flat array.
+     */
+    getFlatRoles(grants: any, roles: ValidRoleOrArray): ValidRole[];
+    /**
+     *  Checks the given grants model and gets an array of non-existent roles
+     *  from the given roles.
+     *  @param {Any} grants - Grants model to be checked.
+     *  @param {string[]} roles - Roles to be checked.
+     *  @returns {ValidRole[]} - Array of non-existent roles. Empty array if
+     *  all exist.
+     */
+    getNonExistentRoles(grants: any, roles: ValidRole[]): (string | number)[];
+    /**
+     *  Checks whether the given extender role(s) is already (cross) inherited
+     *  by the given role and returns the first cross-inherited role. Otherwise,
+     *  returns `false`.
+     *
+     *  Note that cross-inheritance is not allowed.
+     *
+     *  @param {Any} grants - Grants model to be checked.
+     *  @param {string} roles - Target role to be checked.
+     *  @param {string|string[]} extenderRoles - Extender role(s) to be checked.
+     *
+     *  @returns {string|null} - Returns the first cross extending role. `null`
+     *  if none.
+     */
+    getCrossExtendingRole(grants: any, roleName: string, extenderRoles: ValidRoleOrArray): string;
+    /**
+     *  Extends the given role(s) with privileges of one or more other roles.
+     *
+     *  @param {Any} grants
+     *  @param {string|string[]} roles Role(s) to be extended. Single role
+     *         as a `String` or multiple roles as an `Array`. Note that if a
+     *         role does not exist, it will be automatically created.
+     *
+     *  @param {string|string[]} extenderRoles Role(s) to inherit from.
+     *         Single role as a `String` or multiple roles as an `Array`. Note
+     *         that if a extender role does not exist, it will throw.
+     *
+     *  @throws {Error} If a role is extended by itself, a non-existent role or
+     *          a cross-inherited role.
+     */
+    extendRole(grants: any, roles: ValidRoleOrArray, extenderRoles: ValidRoleOrArray): void;
+    /**
+     *  `utils.commitToGrants()` method already creates the roles but it's
+     *  executed when the chain is terminated with either `.extend()` or an
+     *  action method (e.g. `.createOwn()`). In case the chain is not
+     *  terminated, we'll still (pre)create the role(s) with an empty object.
+     *  @param {Any} grants
+     *  @param {string|string[]} roles
+     */
+    preCreateRoles(grants: any, roles: ValidRoleOrArray): void;
+    /**
+     *  Commits the given `IAccessInfo` object to the grants model.
+     *  CAUTION: if attributes is omitted, it will default to `['*']` which
+     *  means "all attributes allowed".
+     *  @param {Any} grants
+     *  @param {IAccessInfo} access
+     *  @param {boolean} normalizeAll
+     *         Specifies whether to validate and normalize all properties of
+     *         the inner `IAccessInfo` object, including `action` and `possession`.
+     *  @throws {Error} If `IAccessInfo` object fails validation.
+     */
     commitToGrants(grants: any, access: IAccessInfo, normalizeAll?: boolean): void;
+    /**
+     *  When more than one role is passed, we union the permitted attributes
+     *  for all given roles; so we can check whether "at least one of these
+     *  roles" have the permission to execute this action.
+     *  e.g. `can(['admin', 'user']).createAny('video')`
+     *
+     *  @param {Any} grants
+     *  @param {IQueryInfo} query
+     *
+     *  @returns {string[]} - Array of union'ed attributes.
+     */
     getUnionAttrsOfRoles(grants: any, query: IQueryInfo): string[];
+    /**
+     *  Locks the given AccessControl instance by freezing underlying grants
+     *  model and disabling all functionality to modify it.
+     *  @param {AccessControl} ac
+     */
     lockAC(ac: AccessControl): void;
+    /**
+     *  Deep clones the source object while filtering its properties by the
+     *  given attributes (glob notations). Includes all matched properties and
+     *  removes the rest.
+     *
+     *  @param {Object} object - Object to be filtered.
+     *  @param {string[]} attributes - Array of glob notations.
+     *
+     *  @returns {Object} - Filtered object.
+     */
     filter(object: any, attributes: string[]): any;
+    /**
+     *  Deep clones the source array of objects or a single object while
+     *  filtering their properties by the given attributes (glob notations).
+     *  Includes all matched properties and removes the rest of each object in
+     *  the array.
+     *
+     *  @param {Array|Object} arrOrObj - Array of objects or single object to be
+     *  filtered.
+     *  @param {string[]} attributes - Array of glob notations.
+     *
+     *  @returns {Array|Object}
+     */
     filterAll(arrOrObj: any, attributes: string[]): any;
 };
 export { utils, RESERVED_KEYWORDS, ERR_LOCK };

lib/utils.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERR_LOCK = exports.RESERVED_KEYWORDS = exports.utils = void 0;
 // dep modules
 var Notation = require("notation");
 var enums_1 = require("./enums");
@@ -57,11 +58,13 @@ var utils = {
      *  @param {Any} value
      *  @returns {string[]}
      */
-    toStringArray: function (value) {
+    toValidRoleArray: function (value) {
         if (Array.isArray(value))
             return value;
         if (typeof value === 'string')
             return value.trim().split(/\s*[;,]\s*/);
+        if (typeof value === 'number')
+            return [value];
         // throw new Error('Expected a string or array of strings, got ' + utils.type(value));
         return [];
     },
@@ -71,14 +74,19 @@ var utils = {
      *  @param {Array} arr - Array to be checked.
      *  @returns {Boolean}
      */
-    isFilledStringArray: function (arr) {
+    isFilledValidRoleArray: function (arr) {
         if (!arr || !Array.isArray(arr))
             return false;
         for (var _i = 0, arr_1 = arr; _i < arr_1.length; _i++) {
-            var s = arr_1[_i];
-            if (typeof s !== 'string' || s.trim() === '')
+            var e = arr_1[_i];
+            if (typeof e !== 'number' && (typeof e !== 'string' || e.trim() === ''))
                 return false;
         }
+        return arr.every(this.isValidRole);
+    },
+    isValidRole: function (e) {
+        if (typeof e !== 'number' && (typeof e !== 'string' || e.trim() === ''))
+            return false;
         return true;
     },
     /**
@@ -221,7 +229,7 @@ var utils = {
      */
     validName: function (name, throwOnInvalid) {
         if (throwOnInvalid === void 0) { throwOnInvalid = true; }
-        if (typeof name !== 'string' || name.trim() === '') {
+        if (!this.isValidRole(name)) {
             if (!throwOnInvalid)
                 return false;
             throw new core_1.AccessControlError('Invalid name, expected a valid string.');
@@ -248,7 +256,7 @@ var utils = {
     hasValidNames: function (list, throwOnInvalid) {
         if (throwOnInvalid === void 0) { throwOnInvalid = true; }
         var allValid = true;
-        utils.each(utils.toStringArray(list), function (name) {
+        utils.each(utils.toValidRoleArray(list), function (name) {
             if (!utils.validName(name, throwOnInvalid)) {
                 allValid = false;
                 return false; // break out of loop
@@ -281,7 +289,7 @@ var utils = {
                 throw new core_1.AccessControlError("Invalid action possession: \"" + action + "\"");
             }
             var perms = o[action];
-            if (!utils.isEmptyArray(perms) && !utils.isFilledStringArray(perms)) {
+            if (!utils.isEmptyArray(perms) && !utils.isFilledValidRoleArray(perms)) {
                 throw new core_1.AccessControlError("Invalid resource attributes for action \"" + action + "\".");
             }
         });
@@ -307,7 +315,7 @@ var utils = {
             if (!utils.validName(resourceName, false)) {
                 if (resourceName === '$extend') {
                     var extRoles = role[resourceName]; // semantics
-                    if (!utils.isFilledStringArray(extRoles)) {
+                    if (!utils.isFilledValidRoleArray(extRoles)) {
                         throw new core_1.AccessControlError("Invalid extend value for role \"" + roleName + "\": " + JSON.stringify(extRoles));
                     }
                     else {
@@ -344,7 +352,7 @@ var utils = {
         var type = utils.type(o);
         if (type === 'object') {
             utils.eachKey(o, function (roleName) {
-                if (utils.validName(roleName)) {
+                if (utils.validName(roleName)) { // throws on failure
                     return utils.validRoleObject(o, roleName); // throws on failure
                 }
                 /* istanbul ignore next */
@@ -436,8 +444,8 @@ var utils = {
         // clone the object
         query = Object.assign({}, query);
         // validate and normalize role(s)
-        query.role = utils.toStringArray(query.role);
-        if (!utils.isFilledStringArray(query.role)) {
+        query.role = utils.toValidRoleArray(query.role);
+        if (!utils.isFilledValidRoleArray(query.role)) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(query.role));
         }
         // validate resource
@@ -467,13 +475,13 @@ var utils = {
         // clone the object
         access = Object.assign({}, access);
         // validate and normalize role(s)
-        access.role = utils.toStringArray(access.role);
-        if (access.role.length === 0 || !utils.isFilledStringArray(access.role)) {
+        access.role = utils.toValidRoleArray(access.role);
+        if (access.role.length === 0 || !utils.isFilledValidRoleArray(access.role)) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(access.role));
         }
         // validate and normalize resource
-        access.resource = utils.toStringArray(access.resource);
-        if (access.resource.length === 0 || !utils.isFilledStringArray(access.resource)) {
+        access.resource = utils.toValidRoleArray(access.resource);
+        if (access.resource.length === 0 || !utils.isFilledValidRoleArray(access.resource)) {
             throw new core_1.AccessControlError("Invalid resource(s): " + JSON.stringify(access.resource));
         }
         // normalize attributes
@@ -482,7 +490,7 @@ var utils = {
         }
         else {
             // if omitted and not denied, all attributes are allowed
-            access.attributes = !access.attributes ? ['*'] : utils.toStringArray(access.attributes);
+            access.attributes = !access.attributes ? ['*'] : utils.toValidRoleArray(access.attributes);
         }
         // this part is not necessary if this is invoked from a comitter method
         // such as `createAny()`. So we'll check if we need to validate all
@@ -545,7 +553,7 @@ var utils = {
      *  Gets roles and extended roles in a flat array.
      */
     getFlatRoles: function (grants, roles) {
-        var arrRoles = utils.toStringArray(roles);
+        var arrRoles = utils.toValidRoleArray(roles);
         if (arrRoles.length === 0) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
         }
@@ -561,7 +569,7 @@ var utils = {
      *  from the given roles.
      *  @param {Any} grants - Grants model to be checked.
      *  @param {string[]} roles - Roles to be checked.
-     *  @returns {string[]} - Array of non-existent roles. Empty array if
+     *  @returns {ValidRole[]} - Array of non-existent roles. Empty array if
      *  all exist.
      */
     getNonExistentRoles: function (grants, roles) {
@@ -590,7 +598,7 @@ var utils = {
      *  if none.
      */
     getCrossExtendingRole: function (grants, roleName, extenderRoles) {
-        var extenders = utils.toStringArray(extenderRoles);
+        var extenders = utils.toValidRoleArray(extenderRoles);
         var crossInherited = null;
         utils.each(extenders, function (e) {
             if (crossInherited || roleName === e) {
@@ -628,14 +636,14 @@ var utils = {
      */
     extendRole: function (grants, roles, extenderRoles) {
         // roles cannot be omitted or an empty array
-        roles = utils.toStringArray(roles);
+        roles = utils.toValidRoleArray(roles);
         if (roles.length === 0) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
         }
         // extenderRoles cannot be omitted or but can be an empty array
         if (utils.isEmptyArray(extenderRoles))
             return;
-        var arrExtRoles = utils.toStringArray(extenderRoles).concat();
+        var arrExtRoles = utils.toValidRoleArray(extenderRoles).concat();
         if (arrExtRoles.length === 0) {
             throw new core_1.AccessControlError("Cannot inherit invalid role(s): " + JSON.stringify(extenderRoles));
         }
@@ -675,7 +683,7 @@ var utils = {
      */
     preCreateRoles: function (grants, roles) {
         if (typeof roles === 'string')
-            roles = utils.toStringArray(roles);
+            roles = utils.toValidRoleArray(roles);
         if (!Array.isArray(roles) || roles.length === 0) {
             throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
         }
@@ -714,7 +722,7 @@ var utils = {
                 // If possession (in action value or as a separate property) is
                 // omitted, it will default to "any". e.g. "create" —>
                 // "create:any"
-                grantItem[res][ap] = utils.toStringArray(access.attributes);
+                grantItem[res][ap] = utils.toValidRoleArray(access.attributes);
             });
         });
     },

package-lock.json

@@ -18,6 +18,7 @@
     "deps": "npm-check -u && snyk test",
     "clean": "rimraf ./lib",
     "build": "npm run clean && mkdirp ./lib && tsc",
+    "watch": "npm run build -- -w",
     "test": "npm run build && jest --verbose --no-cache",
     "test!": "jest --verbose --no-cache",
     "cover": "npm run build && jest --coverage --verbose --no-cache",
@@ -108,7 +109,7 @@
     "rimraf": "^2.6.3",
     "snyk": "^1.122.0",
     "ts-jest": "^22.0.4",
-    "typescript": "^2.7.2"
+    "typescript": "4.1.2"
   },
   "dependencies": {
     "notation": "^1.3.6"

package.json

@@ -2,6 +2,8 @@ import { Access, IAccessInfo, Query, IQueryInfo, Permission, AccessControlError
 import { Action, Possession, actions, possessions } from './enums';
 import { utils, ERR_LOCK } from './utils';
 
+import type { ValidRoleOrArray, ValidRole } from '.';
+
 /**
  *  @classdesc
  *  AccessControl class that implements RBAC (Role-Based Access Control) basics
@@ -273,7 +275,7 @@ class AccessControl {
      *  @throws {AccessControlError} - If a role is extended by itself or a
      *  non-existent role. Or if called after `.lock()` is called.
      */
-    extendRole(roles: string | string[], extenderRoles: string | string[]): AccessControl {
+    extendRole(roles: ValidRoleOrArray, extenderRoles: ValidRoleOrArray): AccessControl {
         if (this.isLocked) throw new AccessControlError(ERR_LOCK);
         utils.extendRole(this._grants, roles, extenderRoles);
         return this;
@@ -290,11 +292,11 @@ class AccessControl {
      *
      *  @throws {AccessControlError} - If called after `.lock()` is called.
      */
-    removeRoles(roles: string | string[]): AccessControl {
+    removeRoles(roles: ValidRoleOrArray): AccessControl {
         if (this.isLocked) throw new AccessControlError(ERR_LOCK);
 
-        let rolesToRemove: string[] = utils.toStringArray(roles);
-        if (rolesToRemove.length === 0 || !utils.isFilledStringArray(rolesToRemove)) {
+        let rolesToRemove: ValidRole[] = utils.toValidRoleArray(roles);
+        if (rolesToRemove.length === 0 || !utils.isFilledValidRoleArray(rolesToRemove)) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(roles)}`);
         }
         rolesToRemove.forEach((roleName: string) => {
@@ -328,7 +330,7 @@ class AccessControl {
      *
      *  @throws {AccessControlError} - If called after `.lock()` is called.
      */
-    removeResources(resources: string | string[], roles?: string | string[]): AccessControl {
+    removeResources(resources: ValidRoleOrArray, roles?: ValidRoleOrArray): AccessControl {
         if (this.isLocked) throw new AccessControlError(ERR_LOCK);
 
         // _removePermission has a third argument `actionPossession`. if
@@ -360,8 +362,8 @@ class AccessControl {
      *
      *  @returns {Array<String>}
      */
-    getInheritedRolesOf(role: string): string[] {
-        let roles: string[] = utils.getRoleHierarchyOf(this._grants, role);
+    getInheritedRolesOf(role: ValidRole): ValidRole[] {
+        let roles: ValidRole[] = utils.getRoleHierarchyOf(this._grants, role);
         roles.shift();
         return roles;
     }
@@ -370,7 +372,7 @@ class AccessControl {
      *  Alias of `getInheritedRolesOf`
      *  @private
      */
-    getExtendedRolesOf(role: string): string[] {
+    getExtendedRolesOf(role: ValidRole): ValidRole[] {
         return this.getInheritedRolesOf(role);
     }
 
@@ -392,7 +394,7 @@ class AccessControl {
      *
      *  @returns {Boolean}
      */
-    hasRole(role: string | string[]): boolean {
+    hasRole(role: ValidRoleOrArray): boolean {
         if (Array.isArray(role)) {
             return role.every((item: string) => this._grants.hasOwnProperty(item));
         }
@@ -407,7 +409,7 @@ class AccessControl {
      *
      *  @returns {Boolean}
      */
-    hasResource(resource: string | string[]): boolean {
+    hasResource(resource: ValidRoleOrArray): boolean {
         let resources = this.getResources();
         if (Array.isArray(resource)) {
             return resource.every((item: string) => resources.indexOf(item) >= 0);
@@ -448,7 +450,7 @@ class AccessControl {
      *  ac.can(['admin', 'user']).createOwn('profile');
      *  // Note: when multiple roles checked, acquired attributes are unioned (merged).
      */
-    can(role: string | string[] | IQueryInfo): Query {
+    can(role: ValidRoleOrArray | IQueryInfo): Query {
         // throw on explicit undefined
         if (arguments.length !== 0 && role === undefined) {
             throw new AccessControlError('Invalid role(s): undefined');
@@ -461,7 +463,7 @@ class AccessControl {
      *  Alias of `can()`.
      *  @private
      */
-    query(role: string | string[] | IQueryInfo): Query {
+    query(role: ValidRoleOrArray | IQueryInfo): Query {
         return this.can(role);
     }
 
@@ -552,7 +554,7 @@ class AccessControl {
      *  // Note: when attributes is omitted, it will default to `['*']`
      *  // which means all attributes (of the resource) are allowed.
      */
-    grant(role?: string | string[] | IAccessInfo): Access {
+    grant(role?: ValidRoleOrArray | IAccessInfo): Access {
         if (this.isLocked) throw new AccessControlError(ERR_LOCK);
         // throw on explicit undefined
         if (arguments.length !== 0 && role === undefined) {
@@ -566,7 +568,7 @@ class AccessControl {
      *  Alias of `grant()`.
      *  @private
      */
-    allow(role?: string | string[] | IAccessInfo): Access {
+    allow(role?: ValidRoleOrArray | IAccessInfo): Access {
         return this.grant(role);
     }
 
@@ -622,7 +624,7 @@ class AccessControl {
      *  // To deny same resource for multiple roles:
      *  ac.deny(['admin', 'user']).createOwn('profile');
      */
-    deny(role?: string | string[] | IAccessInfo): Access {
+    deny(role?: ValidRoleOrArray | IAccessInfo): Access {
         if (this.isLocked) throw new AccessControlError(ERR_LOCK);
         // throw on explicit undefined
         if (arguments.length !== 0 && role === undefined) {
@@ -636,7 +638,7 @@ class AccessControl {
      *  Alias of `deny()`.
      *  @private
      */
-    reject(role?: string | string[] | IAccessInfo): Access {
+    reject(role?: ValidRoleOrArray | IAccessInfo): Access {
         return this.deny(role);
     }
 
@@ -647,25 +649,25 @@ class AccessControl {
     /**
      *  @private
      */
-    _removePermission(resources: string | string[], roles?: string | string[], actionPossession?: string) {
-        resources = utils.toStringArray(resources);
+    _removePermission(resources: ValidRoleOrArray, roles?: ValidRoleOrArray, actionPossession?: string) {
+        resources = utils.toValidRoleArray(resources);
         // resources is set but returns empty array.
-        if (resources.length === 0 || !utils.isFilledStringArray(resources)) {
+        if (resources.length === 0 || !utils.isFilledValidRoleArray(resources)) {
             throw new AccessControlError(`Invalid resource(s): ${JSON.stringify(resources)}`);
         }
 
         if (roles !== undefined) {
-            roles = utils.toStringArray(roles);
+            roles = utils.toValidRoleArray(roles);
             // roles is set but returns empty array.
-            if (roles.length === 0 || !utils.isFilledStringArray(roles)) {
+            if (roles.length === 0 || !utils.isFilledValidRoleArray(roles)) {
                 throw new AccessControlError(`Invalid role(s): ${JSON.stringify(roles)}`);
             }
         }
-        utils.eachRoleResource(this._grants, (role: string, resource: string, permissions: any) => {
-            if (resources.indexOf(resource) >= 0
+        utils.eachRoleResource(this._grants, (role: string, resource: string | number, permissions: any) => {
+            if ((resources as ValidRole[]).indexOf(resource) >= 0
                 // roles is optional. so remove if role is not defined.
                 // if defined, check if the current role is in the list.
-                && (!roles || roles.indexOf(role) >= 0)) {
+                && (!roles || (roles as ValidRole[]).indexOf(role) >= 0)) {
                 if (actionPossession) {
                     // e.g. 'create' » 'create:any'
                     // to parse and normalize actionPossession string:

src/AccessControl.ts

@@ -3,6 +3,10 @@ import { IAccessInfo, AccessControlError } from '../core';
 import { Action, Possession, actions, possessions } from '../enums';
 import { utils } from '../utils';
 
+export type ValidRole = string | number
+export type ValidRoleOrArray = ValidRole | ValidRole[]
+
+
 /**
  *  Represents the inner `Access` class that helps build an access information
  *  to be granted or denied; and finally commits it to the underlying grants
@@ -51,12 +55,12 @@ class Access {
      *  @param {Boolean} denied
      *         Specifies whether this `Access` is denied.
      */
-    constructor(ac: AccessControl, roleOrInfo?: string | string[] | IAccessInfo, denied: boolean = false) {
+    constructor(ac: AccessControl, roleOrInfo?: ValidRoleOrArray | IAccessInfo, denied: boolean = false) {
         this._ac = ac;
         this._grants = (ac as any)._grants;
         this._.denied = denied;
 
-        if (typeof roleOrInfo === 'string' || Array.isArray(roleOrInfo)) {
+        if (typeof roleOrInfo === 'string' || typeof roleOrInfo === 'number' || Array.isArray(roleOrInfo)) {
             this.role(roleOrInfo);
         } else if (utils.type(roleOrInfo) === 'object') {
             if (Object.keys(roleOrInfo).length === 0) {
@@ -99,7 +103,7 @@ class Access {
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    role(value: string | string[]): Access {
+    role(value: ValidRoleOrArray): Access {
         // in case chain is not terminated (e.g. `ac.grant('user')`) we'll
         // create/commit the roles to grants with an empty object.
         utils.preCreateRoles(this._grants, value);
@@ -115,7 +119,7 @@ class Access {
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    resource(value: string | string[]): Access {
+    resource(value: ValidRoleOrArray): Access {
         // this will throw if any item fails
         utils.hasValidNames(value, true);
         this._.resource = value;
@@ -129,7 +133,7 @@ class Access {
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    attributes(value: string | string[]): Access {
+    attributes(value: ValidRoleOrArray): Access {
         this._.attributes = value;
         return this;
     }
@@ -151,7 +155,7 @@ class Access {
      *  const permission = ac.can('admin').createAny('video');
      *  console.log(permission.granted); // true
      */
-    extend(roles: string | string[]): Access {
+    extend(roles: ValidRoleOrArray): Access {
         utils.extendRole(this._grants, this._.role, roles);
         return this;
     }
@@ -160,7 +164,7 @@ class Access {
      *  Alias of `extend`.
      *  @private
      */
-    inherit(roles: string | string[]): Access {
+    inherit(roles: ValidRoleOrArray): Access {
         this.extend(roles);
         return this;
     }
@@ -180,7 +184,7 @@ class Access {
      *  ac.grant('user').createOwn('video')
      *    .grant('admin').updateAny('video');
      */
-    grant(roleOrInfo?: string | string[] | IAccessInfo): Access {
+    grant(roleOrInfo?: ValidRoleOrArray | IAccessInfo): Access {
         return (new Access(this._ac, roleOrInfo, false)).attributes(['*']);
     }
 
@@ -199,7 +203,7 @@ class Access {
      *  ac.grant('admin').createAny('video')
      *    .deny('user').deleteAny('video');
      */
-    deny(roleOrInfo?: string | string[] | IAccessInfo): Access {
+    deny(roleOrInfo?: ValidRoleOrArray | IAccessInfo): Access {
         return (new Access(this._ac, roleOrInfo, true)).attributes([]);
     }
 
@@ -235,7 +239,7 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    createOwn(resource?: string | string[], attributes?: string | string[]): Access {
+    createOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.CREATE, Possession.OWN, resource, attributes);
     }
 
@@ -264,14 +268,14 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    createAny(resource?: string | string[], attributes?: string | string[]): Access {
+    createAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.CREATE, Possession.ANY, resource, attributes);
     }
     /**
      *  Alias of `createAny`
      *  @private
      */
-    create(resource?: string | string[], attributes?: string | string[]): Access {
+    create(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this.createAny(resource, attributes);
     }
 
@@ -297,7 +301,7 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    readOwn(resource?: string | string[], attributes?: string | string[]): Access {
+    readOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.READ, Possession.OWN, resource, attributes);
     }
 
@@ -326,14 +330,14 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    readAny(resource?: string | string[], attributes?: string | string[]): Access {
+    readAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.READ, Possession.ANY, resource, attributes);
     }
     /**
      *  Alias of `readAny`
      *  @private
      */
-    read(resource?: string | string[], attributes?: string | string[]): Access {
+    read(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this.readAny(resource, attributes);
     }
 
@@ -359,7 +363,7 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    updateOwn(resource?: string | string[], attributes?: string | string[]): Access {
+    updateOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.UPDATE, Possession.OWN, resource, attributes);
     }
 
@@ -388,14 +392,14 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    updateAny(resource?: string | string[], attributes?: string | string[]): Access {
+    updateAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.UPDATE, Possession.ANY, resource, attributes);
     }
     /**
      *  Alias of `updateAny`
      *  @private
      */
-    update(resource?: string | string[], attributes?: string | string[]): Access {
+    update(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this.updateAny(resource, attributes);
     }
 
@@ -421,7 +425,7 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    deleteOwn(resource?: string | string[], attributes?: string | string[]): Access {
+    deleteOwn(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.DELETE, Possession.OWN, resource, attributes);
     }
 
@@ -450,14 +454,14 @@ class Access {
      *           Self instance of `Access` so that you can chain and define
      *           another access instance to be committed.
      */
-    deleteAny(resource?: string | string[], attributes?: string | string[]): Access {
+    deleteAny(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this._prepareAndCommit(Action.DELETE, Possession.ANY, resource, attributes);
     }
     /**
      *  Alias of `deleteAny`
      *  @private
      */
-    delete(resource?: string | string[], attributes?: string | string[]): Access {
+    delete(resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         return this.deleteAny(resource, attributes);
     }
 
@@ -474,7 +478,7 @@ class Access {
      *  @returns {Access}
      *           Self instance of `Access`.
      */
-    private _prepareAndCommit(action: string, possession: string, resource?: string | string[], attributes?: string | string[]): Access {
+    private _prepareAndCommit(action: string, possession: string, resource?: ValidRoleOrArray, attributes?: ValidRoleOrArray): Access {
         this._.action = action;
         this._.possession = possession;
         if (resource) this._.resource = resource;
@@ -483,7 +487,7 @@ class Access {
             this._.attributes = [];
         } else {
             // if omitted and not denied, all attributes are allowed
-            this._.attributes = attributes ? utils.toStringArray(attributes) : ['*'];
+            this._.attributes = attributes ? utils.toValidRoleArray(attributes) : ['*'];
         }
 
         utils.commitToGrants(this._grants, this._, false);

src/core/Access.ts

@@ -1,3 +1,4 @@
+import type { ValidRoleOrArray } from '.';
 /**
  *  An interface that defines an access information to be granted or denied.
  *  When you start a method chain with `AccessControl#grant` or `AccessControl#deny`
@@ -10,19 +11,19 @@ interface IAccessInfo {
      *  Indicates a single or multiple roles for this access information.
      *  @type {String|Array<String>}
      */
-    role?: string | string[];
+    role?: ValidRoleOrArray;
     /**
      *  Indicates a single or multiple target resources for this access
      *  information.
      *  @type {String|Array<String>}
      */
-    resource?: string | string[];
+    resource?: ValidRoleOrArray;
     /**
      *  Defines the resource attributes which are granted. If denied, this will
      *  default to an empty array.
      *  @type {String|Array<String>}
      */
-    attributes?: string | string[];
+    attributes?: ValidRoleOrArray;
     /**
      *  Defines the type of the operation that is (or not) to be performed on
      *  the resource(s) by the defined role(s).

src/core/IAccessInfo.ts

@@ -1,3 +1,5 @@
+import type { ValidRoleOrArray } from '.';
+
 /**
  *  An interface that defines an access information to be queried.
  *  When you start a method chain with `AccessControl#can` method, you're
@@ -10,7 +12,7 @@ interface IQueryInfo {
      *  Indicates a single or multiple roles to be queried.
      *  @type {String|Array<String>}
      */
-    role?: string | string[];
+    role?: ValidRoleOrArray;
     /**
      *  Indicates the resource to be queried.
      *  @type {String}

src/core/IQueryInfo.ts

@@ -1,6 +1,7 @@
 import { IQueryInfo, Permission, AccessControlError } from '../core';
 import { Action, Possession } from '../enums';
 import { utils } from '../utils';
+import type { ValidRoleOrArray } from '.';
 
 /**
  *  Represents the inner `Query` class that helps build an access information
@@ -38,7 +39,7 @@ class Query {
      *         Either a single or array of roles or an
      *         {@link ?api=ac#AccessControl~IQueryInfo|`IQueryInfo` arbitrary object}.
      */
-    constructor(grants: any, roleOrInfo?: string | string[] | IQueryInfo) {
+    constructor(grants: any, roleOrInfo?: ValidRoleOrArray | IQueryInfo) {
         this._grants = grants;
 
         if (typeof roleOrInfo === 'string' || Array.isArray(roleOrInfo)) {
@@ -70,7 +71,7 @@ class Query {
      *  @returns {Query}
      *           Self instance of `Query`.
      */
-    role(role: string | string[]): Query {
+    role(role: ValidRoleOrArray): Query {
         this._.role = role;
         return this;
     }

src/core/Query.ts

@@ -5,6 +5,8 @@ import { AccessControl } from './';
 import { Action, actions, Possession, possessions } from './enums';
 import { IAccessInfo, IQueryInfo, AccessControlError } from './core';
 
+import type { ValidRole, ValidRoleOrArray } from '.';
+
 /**
  *  List of reserved keywords.
  *  i.e. Roles, resources with these names are not allowed.
@@ -64,9 +66,10 @@ const utils = {
      *  @param {Any} value
      *  @returns {string[]}
      */
-    toStringArray(value: any): string[] {
+    toValidRoleArray(value: unknown): ValidRole[] {
         if (Array.isArray(value)) return value;
         if (typeof value === 'string') return value.trim().split(/\s*[;,]\s*/);
+        if (typeof value === 'number') return [value]
         // throw new Error('Expected a string or array of strings, got ' + utils.type(value));
         return [];
     },
@@ -77,12 +80,17 @@ const utils = {
      *  @param {Array} arr - Array to be checked.
      *  @returns {Boolean}
      */
-    isFilledStringArray(arr: any[]): boolean {
+    isFilledValidRoleArray(arr: unknown[]): arr is ValidRole[] {
         if (!arr || !Array.isArray(arr)) return false;
-        for (let s of arr) {
-            if (typeof s !== 'string' || s.trim() === '') return false;
+        for (let e of arr) {
+            if (typeof e !== 'number' && (typeof e !== 'string' || e.trim() === '')) return false;
         }
-        return true;
+        return arr.every(this.isValidRole)
+    },
+
+    isValidRole(e: unknown): e is ValidRole {
+      if (typeof e !== 'number' && (typeof e !== 'string' || e.trim() === '')) return false;
+      return true;
     },
 
     /**
@@ -100,7 +108,7 @@ const utils = {
      *  @param {Any} item - Item to be pushed to array.
      *  @returns {Array}
      */
-    pushUniq(arr: string[], item: string): string[] {
+    pushUniq(arr: ValidRole[], item: ValidRole): ValidRole[] {
         if (arr.indexOf(item) < 0) arr.push(item);
         return arr;
     },
@@ -111,9 +119,9 @@ const utils = {
      *  @param {Array} arrB
      *  @returns {Array} - Concat'ed array.
      */
-    uniqConcat(arrA: string[], arrB: string[]): string[] {
-        const arr: string[] = arrA.concat();
-        arrB.forEach((b: string) => {
+    uniqConcat(arrA: ValidRole[], arrB: ValidRole[]): ValidRole[] {
+        const arr = arrA.concat();
+        arrB.forEach((b) => {
             utils.pushUniq(arr, b);
         });
         return arr;
@@ -125,7 +133,7 @@ const utils = {
      *  @param {Array} arrB
      *  @return {Array} - Resulting array.
      */
-    subtractArray(arrA: string[], arrB: string[]): string[] {
+    subtractArray(arrA: ValidRole[], arrB: ValidRole[]): ValidRole[] {
         return arrA.concat().filter(a => arrB.indexOf(a) === -1);
     },
 
@@ -229,12 +237,12 @@ const utils = {
      *  @throws {AccessControlError} - If `throwOnInvalid` is enabled and name
      *  is invalid.
      */
-    validName(name: string, throwOnInvalid: boolean = true): boolean {
-        if (typeof name !== 'string' || name.trim() === '') {
+    validName(name: ValidRole, throwOnInvalid: boolean = true): boolean {
+        if (!this.isValidRole(name)) {
             if (!throwOnInvalid) return false;
             throw new AccessControlError('Invalid name, expected a valid string.');
         }
-        if (RESERVED_KEYWORDS.indexOf(name) >= 0) {
+        if (RESERVED_KEYWORDS.indexOf(name as string) >= 0) {
             if (!throwOnInvalid) return false;
             throw new AccessControlError(`Cannot use reserved name: "${name}"`);
         }
@@ -255,7 +263,7 @@ const utils = {
      */
     hasValidNames(list: any, throwOnInvalid: boolean = true): boolean {
         let allValid = true;
-        utils.each(utils.toStringArray(list), name => {
+        utils.each(utils.toValidRoleArray(list), name => {
             if (!utils.validName(name, throwOnInvalid)) {
                 allValid = false;
                 return false; // break out of loop
@@ -290,7 +298,7 @@ const utils = {
                 throw new AccessControlError(`Invalid action possession: "${action}"`);
             }
             let perms = o[action];
-            if (!utils.isEmptyArray(perms) && !utils.isFilledStringArray(perms)) {
+            if (!utils.isEmptyArray(perms) && !utils.isFilledValidRoleArray(perms)) {
                 throw new AccessControlError(`Invalid resource attributes for action "${action}".`);
             }
         });
@@ -318,7 +326,7 @@ const utils = {
             if (!utils.validName(resourceName, false)) {
                 if (resourceName === '$extend') {
                     let extRoles: string[] = role[resourceName]; // semantics
-                    if (!utils.isFilledStringArray(extRoles)) {
+                    if (!utils.isFilledValidRoleArray(extRoles)) {
                         throw new AccessControlError(`Invalid extend value for role "${roleName}": ${JSON.stringify(extRoles)}`);
                     } else {
                         // attempt to actually extend the roles. this will throw
@@ -449,8 +457,8 @@ const utils = {
         // clone the object
         query = Object.assign({}, query);
         // validate and normalize role(s)
-        query.role = utils.toStringArray(query.role);
-        if (!utils.isFilledStringArray(query.role)) {
+        query.role = utils.toValidRoleArray(query.role);
+        if (!utils.isFilledValidRoleArray(query.role)) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(query.role)}`);
         }
 
@@ -482,14 +490,14 @@ const utils = {
         // clone the object
         access = Object.assign({}, access);
         // validate and normalize role(s)
-        access.role = utils.toStringArray(access.role);
-        if (access.role.length === 0 || !utils.isFilledStringArray(access.role)) {
+        access.role = utils.toValidRoleArray(access.role);
+        if (access.role.length === 0 || !utils.isFilledValidRoleArray(access.role)) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(access.role)}`);
         }
 
         // validate and normalize resource
-        access.resource = utils.toStringArray(access.resource);
-        if (access.resource.length === 0 || !utils.isFilledStringArray(access.resource)) {
+        access.resource = utils.toValidRoleArray(access.resource);
+        if (access.resource.length === 0 || !utils.isFilledValidRoleArray(access.resource)) {
             throw new AccessControlError(`Invalid resource(s): ${JSON.stringify(access.resource)}`);
         }
 
@@ -498,7 +506,7 @@ const utils = {
             access.attributes = [];
         } else {
             // if omitted and not denied, all attributes are allowed
-            access.attributes = !access.attributes ? ['*'] : utils.toStringArray(access.attributes);
+            access.attributes = !access.attributes ? ['*'] : utils.toValidRoleArray(access.attributes);
         }
 
         // this part is not necessary if this is invoked from a comitter method
@@ -533,15 +541,15 @@ const utils = {
      *  @param {string} roleName - Role name to be inspected.
      *  @returns {string[]}
      */
-    getRoleHierarchyOf(grants: any, roleName: string, rootRole?: string): string[] {
+    getRoleHierarchyOf(grants: any, roleName: ValidRole, rootRole?: ValidRole): ValidRole[] {
         // `rootRole` is for memory storage. Do NOT set it when using;
         // and do NOT document this paramter.
         // rootRole = rootRole || roleName;
 
         const role: any = grants[roleName];
         if (!role) throw new AccessControlError(`Role not found: "${roleName}"`);
 
-        let arr: string[] = [roleName];
+        let arr = [roleName];
         if (!Array.isArray(role.$extend) || role.$extend.length === 0) return arr;
 
         role.$extend.forEach((exRoleName: string) => {
@@ -556,7 +564,7 @@ const utils = {
             if (rootRole && (rootRole === exRoleName)) {
                 throw new AccessControlError(`Cross inheritance is not allowed. Role "${exRoleName}" already extends "${rootRole}".`);
             }
-            let ext: string[] = utils.getRoleHierarchyOf(grants, exRoleName, rootRole || roleName);
+            let ext = utils.getRoleHierarchyOf(grants, exRoleName, rootRole || roleName);
             arr = utils.uniqConcat(arr, ext);
         });
         return arr;
@@ -565,12 +573,12 @@ const utils = {
     /**
      *  Gets roles and extended roles in a flat array.
      */
-    getFlatRoles(grants: any, roles: string | string[]): string[] {
-        const arrRoles: string[] = utils.toStringArray(roles);
+    getFlatRoles(grants: any, roles: ValidRoleOrArray): ValidRole[] {
+        const arrRoles = utils.toValidRoleArray(roles);
         if (arrRoles.length === 0) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(roles)}`);
         }
-        let arr: string[] = utils.uniqConcat([], arrRoles); // roles.concat();
+        let arr = utils.uniqConcat([], arrRoles); // roles.concat();
         arrRoles.forEach((roleName: string) => {
             arr = utils.uniqConcat(arr, utils.getRoleHierarchyOf(grants, roleName));
         });
@@ -583,11 +591,11 @@ const utils = {
      *  from the given roles.
      *  @param {Any} grants - Grants model to be checked.
      *  @param {string[]} roles - Roles to be checked.
-     *  @returns {string[]} - Array of non-existent roles. Empty array if
+     *  @returns {ValidRole[]} - Array of non-existent roles. Empty array if
      *  all exist.
      */
-    getNonExistentRoles(grants: any, roles: string[]) {
-        let non: string[] = [];
+    getNonExistentRoles(grants: any, roles: ValidRole[]) {
+        let non: ValidRole[] = [];
         if (utils.isEmptyArray(roles)) return non;
         for (let role of roles) {
             if (!grants.hasOwnProperty(role)) non.push(role);
@@ -609,8 +617,8 @@ const utils = {
      *  @returns {string|null} - Returns the first cross extending role. `null`
      *  if none.
      */
-    getCrossExtendingRole(grants: any, roleName: string, extenderRoles: string | string[]): string {
-        const extenders: string[] = utils.toStringArray(extenderRoles);
+    getCrossExtendingRole(grants: any, roleName: string, extenderRoles: ValidRoleOrArray): string {
+        const extenders: ValidRole[] = utils.toValidRoleArray(extenderRoles);
         let crossInherited: any = null;
         utils.each(extenders, (e: string) => {
             if (crossInherited || roleName === e) {
@@ -647,22 +655,22 @@ const utils = {
      *  @throws {Error} If a role is extended by itself, a non-existent role or
      *          a cross-inherited role.
      */
-    extendRole(grants: any, roles: string | string[], extenderRoles: string | string[]) {
+    extendRole(grants: any, roles: ValidRoleOrArray, extenderRoles: ValidRoleOrArray) {
         // roles cannot be omitted or an empty array
-        roles = utils.toStringArray(roles);
+        roles = utils.toValidRoleArray(roles);
         if (roles.length === 0) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(roles)}`);
         }
 
         // extenderRoles cannot be omitted or but can be an empty array
         if (utils.isEmptyArray(extenderRoles)) return;
 
-        const arrExtRoles: string[] = utils.toStringArray(extenderRoles).concat();
+        const arrExtRoles: ValidRole[] = utils.toValidRoleArray(extenderRoles).concat();
         if (arrExtRoles.length === 0) {
             throw new AccessControlError(`Cannot inherit invalid role(s): ${JSON.stringify(extenderRoles)}`);
         }
 
-        const nonExistentExtRoles: string[] = utils.getNonExistentRoles(grants, arrExtRoles);
+        const nonExistentExtRoles: ValidRole[] = utils.getNonExistentRoles(grants, arrExtRoles);
         if (nonExistentExtRoles.length > 0) {
             throw new AccessControlError(`Cannot inherit non-existent role(s): "${nonExistentExtRoles.join(', ')}"`);
         }
@@ -699,12 +707,12 @@ const utils = {
      *  @param {Any} grants
      *  @param {string|string[]} roles
      */
-    preCreateRoles(grants: any, roles: string | string[]) {
-        if (typeof roles === 'string') roles = utils.toStringArray(roles);
+    preCreateRoles(grants: any, roles: ValidRoleOrArray) {
+        if (typeof roles === 'string') roles = utils.toValidRoleArray(roles);
         if (!Array.isArray(roles) || roles.length === 0) {
             throw new AccessControlError(`Invalid role(s): ${JSON.stringify(roles)}`);
         }
-        (roles as string[]).forEach((role: string) => {
+        roles.forEach((role: string) => {
             if (utils.validName(role) && !grants.hasOwnProperty(role)) {
                 grants[role] = {};
             }
@@ -740,7 +748,7 @@ const utils = {
                 // If possession (in action value or as a separate property) is
                 // omitted, it will default to "any". e.g. "create" —>
                 // "create:any"
-                grantItem[res][ap] = utils.toStringArray(access.attributes);
+                grantItem[res][ap] = utils.toValidRoleArray(access.attributes);
             });
         });
     },
@@ -764,7 +772,7 @@ const utils = {
         let resource: string;
         let attrsList: Array<string[]> = [];
         // get roles and extended roles in a flat array
-        const roles: string[] = utils.getFlatRoles(grants, query.role);
+        const roles: ValidRole[] = utils.getFlatRoles(grants, query.role);
         // iterate through roles and add permission attributes (array) of
         // each role to attrsList (array).
         roles.forEach((roleName: string, index: number) => {

src/utils.ts

@@ -15,7 +15,7 @@ import { helper } from './helper';
 describe('Test Suite: AccessControl', () => {
 
     // grant list fetched from DB (to be converted to a valid grants object)
-    let grantList: any[] = [
+    let grantList = [
         { role: 'admin', resource: 'video', action: 'create:any', attributes: ['*'] },
         { role: 'admin', resource: 'video', action: 'read:any', attributes: ['*'] },
         { role: 'admin', resource: 'video', action: 'update:any', attributes: ['*'] },
@@ -24,11 +24,16 @@ describe('Test Suite: AccessControl', () => {
         { role: 'user', resource: 'video', action: 'create:own', attributes: '*, !id' }, // comma-separated attrs
         { role: 'user', resource: 'video', action: 'read:any', attributes: '*; !id' }, // semi-colon separated attrs
         { role: 'user', resource: 'video', action: 'update:own', attributes: ['*', '!id'] }, // Array attrs
-        { role: 'user', resource: 'video', action: 'delete:own', attributes: ['*'] }
-    ];
+        { role: 'user', resource: 'video', action: 'delete:own', attributes: ['*'] },
+
+        { role: 2, resource:7, action: 'create:any', attributes: ['*']}, // comma-separated attrs
+        { role: 2, resource:7, action: 'read:any', attributes: ['*']}, // semi-colon separated attrs
+        { role: 2, resource:7, action: 'update:any', attributes: ['*'] }, // Array attrs
+        { role: 2, resource:7, action: 'delete:any', attributes: ['*'] }
+    ] as const;
 
     // valid grants object
-    let grantsObject: any = {
+    let grantsObject = {
         admin: {
             video: {
                 'create:any': ['*'],
@@ -44,7 +49,15 @@ describe('Test Suite: AccessControl', () => {
                 'update:own': ['*'],
                 'delete:own': ['*']
             }
-        }
+      },
+        2: {
+            7: {
+                'create:any': ['*'],
+                'read:any': ['*'],
+                'update:any': ['*'],
+                'delete:any': ['*']
+            }
+      },
     };
 
     // let ac;
@@ -203,8 +216,8 @@ describe('Test Suite: AccessControl', () => {
         expect(attrs3.length).toEqual(2);
 
         // check roles & resources
-        expect(ac.getRoles().length).toEqual(2);
-        expect(ac.getResources().length).toEqual(1);
+        expect(ac.getRoles().length).toEqual(3);
+        expect(ac.getResources().length).toEqual(2);
         expect(ac.hasRole('admin')).toEqual(true);
         expect(ac.hasRole('user')).toEqual(true);
         expect(ac.hasRole(['user', 'admin'])).toEqual(true);
@@ -222,8 +235,10 @@ describe('Test Suite: AccessControl', () => {
         helper.expectACError(() => ac.removeRoles([]));
         helper.expectACError(() => ac.removeRoles(['']));
         helper.expectACError(() => ac.removeRoles(['none']));
+        // no role named 69
+        helper.expectACError(() => ac.removeRoles(['user', 69]));
         // no role named moderator
-        helper.expectACError(() => ac.removeRoles(['user', 'moderator']));
+        helper.expectACError(() => ac.removeRoles([2, 'moderator']));
         expect(ac.getRoles().length).toEqual(0);
         // removeRoles should accept a string or array
         ac.removeResources(['video']);

test/ac.test.ts

@@ -36,29 +36,30 @@ describe('Test Suite: utils (generic)', () => {
         expect(() => utils.hasDefined(null, 'prop')).toThrow();
     });
 
-    test('#toStringArray()', () => {
-        expect(utils.toStringArray([])).toEqual([]);
-        expect(utils.toStringArray('a')).toEqual(['a']);
-        expect(utils.toStringArray('a,b,c')).toEqual(['a', 'b', 'c']);
-        expect(utils.toStringArray('a, b,  c  \n')).toEqual(['a', 'b', 'c']);
-        expect(utils.toStringArray('a ; b,c')).toEqual(['a', 'b', 'c']);
-        expect(utils.toStringArray('a;b; c')).toEqual(['a', 'b', 'c']);
-        expect(utils.toStringArray(1)).toEqual([]);
-        expect(utils.toStringArray(true)).toEqual([]);
-        expect(utils.toStringArray(false)).toEqual([]);
-        expect(utils.toStringArray(null)).toEqual([]);
-        expect(utils.toStringArray(undefined)).toEqual([]);
+    test('#toValidRoleArray()', () => {
+        expect(utils.toValidRoleArray([])).toEqual([]);
+        expect(utils.toValidRoleArray('a')).toEqual(['a']);
+        expect(utils.toValidRoleArray('a,b,c')).toEqual(['a', 'b', 'c']);
+        expect(utils.toValidRoleArray('a, b,  c  \n')).toEqual(['a', 'b', 'c']);
+        expect(utils.toValidRoleArray('a ; b,c')).toEqual(['a', 'b', 'c']);
+        expect(utils.toValidRoleArray('a;b; c')).toEqual(['a', 'b', 'c']);
+        expect(utils.toValidRoleArray(1)).toEqual([1]);
+        expect(utils.toValidRoleArray([1, 2, 3])).toEqual([1, 2, 3]);
+        expect(utils.toValidRoleArray(true)).toEqual([]);
+        expect(utils.toValidRoleArray(false)).toEqual([]);
+        expect(utils.toValidRoleArray(null)).toEqual([]);
+        expect(utils.toValidRoleArray(undefined)).toEqual([]);
     });
 
-    test('#isFilledStringArray(), #isEmptyArray()', () => {
-        expect(utils.isFilledStringArray([])).toBe(true); // allowed
-        expect(utils.isFilledStringArray([''])).toBe(false);
-        expect(utils.isFilledStringArray(['a'])).toBe(true);
-        expect(utils.isFilledStringArray(['a', ''])).toBe(false);
-        expect(utils.isFilledStringArray([1])).toBe(false);
-        expect(utils.isFilledStringArray([null])).toBe(false);
-        expect(utils.isFilledStringArray([undefined])).toBe(false);
-        expect(utils.isFilledStringArray([false])).toBe(false);
+    test('#isFilledValidRoleArray(), #isEmptyArray()', () => {
+        expect(utils.isFilledValidRoleArray([])).toBe(true); // allowed
+        expect(utils.isFilledValidRoleArray([''])).toBe(false);
+        expect(utils.isFilledValidRoleArray(['a'])).toBe(true);
+        expect(utils.isFilledValidRoleArray(['a', ''])).toBe(false);
+        expect(utils.isFilledValidRoleArray([1])).toBe(true);
+        expect(utils.isFilledValidRoleArray([null])).toBe(false);
+        expect(utils.isFilledValidRoleArray([undefined])).toBe(false);
+        expect(utils.isFilledValidRoleArray([false])).toBe(false);
 
         expect(utils.isEmptyArray([])).toBe(true);
         expect(utils.isEmptyArray([1])).toBe(false);
@@ -157,7 +158,7 @@ describe('Test Suite: utils (core)', () => {
         helper.expectACError(() => utils.validName(invalid, true));
         expect(utils.validName(invalid, false)).toBe(false);
         expect(utils.validName('', false)).toBe(false);
-        expect((utils as any).validName(1, false)).toBe(false);
+        expect(utils.validName(1, false)).toBe(true);
         expect((utils as any).validName(null, false)).toBe(false);
         expect((utils as any).validName(true, false)).toBe(false);