Enhance typing

lib/AccessControl.d.ts

@@ -1,4 +1,6 @@
-import { Access, IAccessInfo, Query, IQueryInfo, Permission } from './core';
+import { Access, IAccessInfo, Query, IQueryInfo, Permission, AccessControlError } from './core';
+import { Action, Possession } from './enums';
+import { Grants } from './utils';
 /**
  *  @classdesc
  *  AccessControl class that implements RBAC (Role-Based Access Control) basics
@@ -68,7 +70,7 @@ import { Access, IAccessInfo, Query, IQueryInfo, Permission } from './core';
  *  // since these permissions have common resources, there is an alternative way:
  *  ac.grant('admin')
  *      .resource('profile').createAny().readAny(null, ["*", "!password"])
- *      .resource('video').readAny()..deleteAny();
+ *      .resource('video').readAny().deleteAny();
  *
  *  ac.grant('user')
  *      .readOwn('profile', ["uid", "email", "address.*", "account.*", "!account.roles"])
@@ -111,7 +113,7 @@ declare class AccessControl {
      *  @param {Object|Array} [grants] - A list containing the access grant
      *      definitions. See the structure of this object in the examples.
      */
-    constructor(grants?: any);
+    constructor(grants?: Grants);
     /**
      *  Specifies whether the underlying grants object is frozen and all
      *  functionality for modifying it is disabled.
@@ -163,7 +165,7 @@ declare class AccessControl {
      *    }
      *  }
      */
-    getGrants(): any;
+    getGrants(): Grants;
     /**
      *  Sets all access grants at once, from an object or array. Note that this
      *  will reset the object and remove all previous grants.
@@ -177,7 +179,7 @@ declare class AccessControl {
      *  @throws {AccessControlError} - If called after `.lock()` is called or if
      *  passed grants object fails inspection.
      */
-    setGrants(grantsObject: any): AccessControl;
+    setGrants(grantsObject: Grants): AccessControl;
     /**
      *  Resets the internal grants object and removes all previous grants.
      *  @chainable
@@ -504,33 +506,32 @@ declare class AccessControl {
     /**
      *  @private
      */
-    _removePermission(resources: string | string[], roles?: string | string[], actionPossession?: string): void;
+    _removePermission(resources: string | string[], roles?: string | string[], actionPossession?: Action): void;
     /**
      *  Documented separately in enums/Action
      *  @private
      */
-    static readonly Action: any;
+    static readonly Action: typeof Action;
     /**
      *  Documented separately in enums/Possession
      *  @private
      */
-    static readonly Possession: any;
+    static readonly Possession: typeof Possession;
     /**
      *  Documented separately in AccessControlError
      *  @private
      */
-    static readonly Error: any;
+    static readonly Error: typeof AccessControlError;
     /**
-     *  A utility method for deep cloning the given data object(s) while
+     *  A utility method for deep cloning the given data object while
      *  filtering its properties by the given attribute (glob) notations.
      *  Includes all matched properties and removes the rest.
      *
      *  Note that this should be used to manipulate data / arbitrary objects
      *  with enumerable properties. It will not deal with preserving the
      *  prototype-chain of the given object.
      *
-     *  @param {Object|Array} data - A single or array of data objects
-     *      to be filtered.
+     *  @param {Object} data - A single data objects to be filtered.
      *  @param {Array|String} attributes - The attribute glob notation(s)
      *      to be processed. You can use wildcard stars (*) and negate
      *      the notation by prepending a bang (!). A negated notation
@@ -543,8 +544,7 @@ declare class AccessControl {
      *      Passing no parameters or passing an empty string (`""` or `[""]`)
      *      will empty the source object.
      *
-     *  @returns {Object|Array} - Returns the filtered data object or array
-     *      of data objects.
+     *  @returns {Object} - Returns the filtered data object.
      *
      *  @example
      *  var assets = { notebook: "Mac", car: { brand: "Ford", model: "Mustang", year: 1970, color: "red" } };
@@ -558,7 +558,33 @@ declare class AccessControl {
      *  filtered = AccessControl.filter(assets); // or AccessControl.filter(assets, "");
      *  console.log(assets); // {}
      */
-    static filter(data: any, attributes: string[]): any;
+    static filter<T>(data: T, attributes: string[]): Partial<T>;
+    /**
+     *  A utility method for deep cloning the given data objects while
+     *  filtering its properties by the given attribute (glob) notations.
+     *  Includes all matched properties and removes the rest.
+     *
+     *  Note that this should be used to manipulate data / arbitrary objects
+     *  with enumerable properties. It will not deal with preserving the
+     *  prototype-chain of the given object.
+     *
+     *  @param {Array} data - An array of data objects
+     *      to be filtered.
+     *  @param {Array|String} attributes - The attribute glob notation(s)
+     *      to be processed. You can use wildcard stars (*) and negate
+     *      the notation by prepending a bang (!). A negated notation
+     *      will be excluded. Order of the globs do not matter, they will
+     *      be logically sorted. Loose globs will be processed first and
+     *      verbose globs or normal notations will be processed last.
+     *      e.g. `[ "car.model", "*", "!car.*" ]`
+     *      will be sorted as:
+     *      `[ "*", "!car.*", "car.model" ]`.
+     *      Passing no parameters or passing an empty string (`""` or `[""]`)
+     *      will empty the source object.
+     *
+     *  @returns {Array} - Returns the filtered array of data objects.
+     */
+    static filter<T>(data: T[], attributes: string[]): Partial<T>[];
     /**
      *  Checks whether the given object is an instance of `AccessControl.Error`.
      *  @name AccessControl.isACError

lib/AccessControl.js

@@ -72,7 +72,7 @@ var utils_1 = require("./utils");
  *  // since these permissions have common resources, there is an alternative way:
  *  ac.grant('admin')
  *      .resource('profile').createAny().readAny(null, ["*", "!password"])
- *      .resource('video').readAny()..deleteAny();
+ *      .resource('video').readAny().deleteAny();
  *
  *  ac.grant('user')
  *      .readOwn('profile', ["uid", "email", "address.*", "account.*", "!account.roles"])
@@ -246,7 +246,17 @@ var AccessControl = /** @class */ (function () {
      *  // underlying grants model is not changed
      */
     AccessControl.prototype.lock = function () {
-        utils_1.utils.lockAC(this);
+        if (!this._grants || Object.keys(this._grants).length === 0) {
+            throw new core_1.AccessControlError('Cannot lock empty or invalid grants model.');
+        }
+        var locked = this.isLocked && Object.isFrozen(this._grants);
+        if (!locked)
+            locked = Boolean(utils_1.utils.deepFreeze(this._grants));
+        /* istanbul ignore next */
+        if (!locked) {
+            throw new core_1.AccessControlError("Could not lock grants: " + typeof this._grants);
+        }
+        this._isLocked = locked;
         return this;
     };
     /**
@@ -643,7 +653,7 @@ var AccessControl = /** @class */ (function () {
                 throw new core_1.AccessControlError("Invalid role(s): " + JSON.stringify(roles));
             }
         }
-        utils_1.utils.eachRoleResource(this._grants, function (role, resource, permissions) {
+        utils_1.utils.eachRoleResource(this._grants, function (role, resource) {
             if (resources.indexOf(resource) >= 0
                 // roles is optional. so remove if role is not defined.
                 // if defined, check if the current role is in the list.

lib/core/Access.d.ts

@@ -1,5 +1,6 @@
 import { AccessControl } from '../';
 import { IAccessInfo } from '../core';
+import { Grants } from '../utils';
 /**
  *  Represents the inner `Access` class that helps build an access information
  *  to be granted or denied; and finally commits it to the underlying grants
@@ -27,7 +28,7 @@ declare class Access {
      *  @protected
      *  @type {Any}
      */
-    protected _grants: any;
+    protected _grants: Grants;
     /**
      *  Initializes a new instance of `Access`.
      *  @private

lib/core/Access.js

@@ -38,7 +38,7 @@ var Access = /** @class */ (function () {
          */
         this._ = {};
         this._ac = ac;
-        this._grants = ac._grants;
+        this._grants = ac.getGrants();
         this._.denied = denied;
         if (typeof roleOrInfo === 'string' || Array.isArray(roleOrInfo)) {
             this.role(roleOrInfo);
@@ -187,7 +187,7 @@ var Access = /** @class */ (function () {
      *  @returns {Access}
      */
     Access.prototype.lock = function () {
-        utils_1.utils.lockAC(this._ac);
+        this._ac.lock();
         return this;
     };
     /**

lib/core/IAccessInfo.d.ts

@@ -1,3 +1,4 @@
+import { Action, Possession } from "../enums";
 /**
  *  An interface that defines an access information to be granted or denied.
  *  When you start a method chain with `AccessControl#grant` or `AccessControl#deny`
@@ -30,16 +31,16 @@ interface IAccessInfo {
      *  for possible values.
      *  @type {String}
      */
-    action?: string;
+    action?: Action;
     /**
      *  Defines the possession of the resource(s) for the specified action.
      *  See {@link ?api=ac#AccessControl.Possession|`AccessControl.Possession` enumeration}
      *  for possible values.
      *  @type {String}
      */
-    possession?: string;
+    possession?: Possession;
     /**
-     *  Single or multiple roles for this access information.
+     *  Flag for denied access.
      *  @private
      *  @type {String|Array<String>}
      */

lib/core/IQueryInfo.d.ts

@@ -1,3 +1,4 @@
+import { Action, Possession } from "../enums";
 /**
  *  An interface that defines an access information to be queried.
  *  When you start a method chain with `AccessControl#can` method, you're
@@ -23,13 +24,13 @@ interface IQueryInfo {
      *  for possible values.
      *  @type {String}
      */
-    action?: string;
+    action?: Action;
     /**
      *  Defines the possession of the resource for the specified action.
      *  See {@link ?api=ac#AccessControl.Possession|`AccessControl.Possession` enumeration}
      *  for possible values.
      *  @type {String}
      */
-    possession?: string;
+    possession?: Possession;
 }
 export { IQueryInfo };

lib/core/Permission.d.ts

@@ -60,7 +60,7 @@ declare class Permission {
      *  @type {Array<String>}
      *  @readonly
      */
-    readonly roles: string[];
+    readonly roles: string | string[];
     /**
      *  Specifies the target resource for which the permission is queried for.
      *
@@ -92,16 +92,20 @@ declare class Permission {
      */
     readonly granted: boolean;
     /**
-     *  Filters the given data object (or array of objects) by the permission
-     *  attributes and returns this data with allowed attributes.
+     *  Filters the given data object by the permission attributes and returns
+     *  this data with allowed attributes.
      *
-     *  @param {Object|Array} data
-     *         Data object to be filtered. Either a single object or array
-     *         of objects.
+     *  @param {Object} data Data object to be filtered.
+     *  @returns {Object} The filtered data object.
+     */
+    filter<T>(data: T): Partial<T>;
+    /**
+     *  Filters the given array of objects by the permission attributes and
+     *  returns this data with allowed attributes.
      *
-     *  @returns {Object|Array}
-     *           The filtered data object.
+     *  @param {Array} data Data objects to be filtered.
+     *  @returns {Array} The filtered data objects.
      */
-    filter(data: any): any;
+    filter<T>(data: T[]): Partial<T>[];
 }
 export { Permission };

lib/core/Query.d.ts

@@ -1,4 +1,5 @@
 import { IQueryInfo, Permission } from '../core';
+import { Grants } from '../utils';
 /**
  *  Represents the inner `Query` class that helps build an access information
  *  for querying and checking permissions, from the underlying grants model.
@@ -20,7 +21,7 @@ declare class Query {
      *  @protected
      *  @type {Any}
      */
-    protected _grants: any;
+    protected _grants: Grants;
     /**
      *  Initializes a new instance of `Query`.
      *  @private
@@ -32,7 +33,7 @@ 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: Grants, roleOrInfo?: string | string[] | IQueryInfo);
     /**
      *  A chainer method that sets the role(s) for this `Query` instance.
      *  @param {String|Array<String>} roles