@magda/typescript-common 1.1.0-alpha.2 → 1.1.0-alpha.3

package/dist/OpaCompileResponseParser.d.ts

@@ -0,0 +1,480 @@
+export declare type RegoValue = string | boolean | number | Array<any> | Object;
+export interface RegoRuleOptions {
+    name: string;
+    fullName: string;
+    isDefault: boolean;
+    value: RegoValue;
+    expressions: RegoExp[];
+    isCompleteEvaluated?: boolean;
+    parser: OpaCompileResponseParser;
+}
+/**
+ * @class RegoRule
+ * @export
+ *
+ * RegoRule represents [Rule](https://www.openpolicyagent.org/docs/latest/how-do-i-write-policies/#rules) concept in Rego language.
+ * - A simple rule is made up of Rule head, Rule value & Rule body
+ * - The Rule value defines the final result of the rule if the rule is matched (i.e. all expressions in rule body are true)
+ * - If you didn't sepcify the rule value, it will be assume as boolean value `true`
+ * - The rule body is made up of one of more rego expressions (see @class RegoExp) and each of the expression is made up of terms (see @class RegoTerm)
+ * - The rule is considered as matched if all expressions in rule body are `true`
+ * You can opt to define a `default` rule. A default rule has no rule body and will only considered as matched if all other rules are not matched.
+ */
+export declare class RegoRule {
+    /**
+     * the local name of the rule. i.e. doesn't include full package path
+     * e.g. `allow`
+     *
+     * @type {string}
+     * @memberof RegoRule
+     */
+    name: string;
+    /**
+     * Full name of the rule. Includes fulle package path
+     * e.g. `data.object.content.allowRead`
+     *
+     * @type {string}
+     * @memberof RegoRule
+     */
+    fullName: string;
+    /**
+     * Whether a rule is a default Rule
+     * Its value only be used if any other residual rules are not matched (or no other residual rules)
+     *
+     * @type {boolean}
+     * @memberof RegoRule
+     */
+    isDefault: boolean;
+    /**
+     * Rule value. Rule value is this value if all expression in rule body are true
+     * It can be any type. e.g. can be object or array etc. But a simple policy normally outputs a boolean true or false
+     *
+     * @type {RegoValue}
+     * @memberof RegoRule
+     */
+    value: RegoValue;
+    /**
+     * All Rego expressions in this rule's rule body. @see RegoExp
+     *
+     * @type {RegoExp[]}
+     * @memberof RegoRule
+     */
+    expressions: RegoExp[];
+    /**
+     * If the rule is matched or not
+     * Default to undefined
+     * Its value is only set when `isCompleteEvaluated` is true
+     *
+     * @type {boolean}
+     * @memberof RegoRule
+     */
+    isMatched?: boolean;
+    /**
+     * If the rule is fully evaluate
+     * Default to false
+     *
+     * @type {boolean}
+     * @memberof RegoRule
+     */
+    isCompleteEvaluated: boolean;
+    /**
+     * Reference to OpaParser
+     *
+     * @private
+     * @type {OpaCompileResponseParser}
+     * @memberof RegoRule
+     */
+    private parser;
+    constructor(options: RegoRuleOptions);
+    clone(options?: Partial<RegoRuleOptions>): RegoRule;
+    /**
+     * Re-evaluate this rule
+     * If fully evaluated, this.isCompleteEvaluated will be set to true
+     *
+     * @returns
+     * @memberof RegoRule
+     */
+    evaluate(): this;
+    /**
+     * Generate Human Readable string of this rule
+     * If it's fully evaluated, the output will be true or false (or actual rule value)
+     * Otherwise, will generate expressions concate with `AND`
+     *
+     * @returns {string}
+     * @memberof RegoRule
+     */
+    toHumanReadableString(): string;
+    /**
+     * Create RegoRule from Opa response data
+     *
+     * @static
+     * @param {*} r
+     * @param {string} packageName
+     * @param {OpaCompileResponseParser} parser
+     * @returns {RegoRule}
+     * @memberof RegoRule
+     */
+    static parseFromData(r: any, packageName: string, parser: OpaCompileResponseParser): RegoRule;
+    static createExpressionsFromRuleBodyData(data: any, parser: OpaCompileResponseParser): RegoExp[];
+    static randomRuleName(prefix: string): string;
+    static createFromValue(val: RegoValue, parser: OpaCompileResponseParser): RegoRule;
+}
+export interface RegoRefPart {
+    type: string;
+    value: string;
+}
+export declare const RegoOperators: {
+    [k: string]: string;
+};
+export declare type RegoTermValue = RegoRef | RegoValue;
+/**
+ * RegoTerm represent the basic elements that creates an expressions.
+ * e.g. An expression `a > 4` is made up of 3 terms
+ * - Reference Term: `a`
+ * - Operator Term `>`
+ * - Value Term: `4`
+ *
+ * @export
+ * @class RegoTerm
+ */
+export declare class RegoTerm {
+    type: string;
+    value: RegoTermValue;
+    private parser;
+    constructor(type: string, value: RegoTermValue, parser: OpaCompileResponseParser);
+    clone(): RegoTerm;
+    /**
+     * If it's a reference term, return its full string representation
+     *
+     * @returns
+     * @memberof RegoTerm
+     */
+    asString(): number | Object;
+    /**
+     * If it's a reference term. A operator is an Reference term as well
+     *
+     * @returns {boolean}
+     * @memberof RegoTerm
+     */
+    isRef(): boolean;
+    /**
+     * Return RegoRef instance if this term is a RegoRef.
+     *
+     * @returns {RegoRef}
+     * @memberof RegoTerm
+     */
+    getRef(): RegoRef;
+    /**
+     * If the term is a reference and it contains any collection lookup
+     * e.g.
+     * - objectA.propB.collectionC[_]
+     * - objectA.propB.collectionC[_].ABC[_].name
+     * - objectA.propB.collectionC[_].id
+     *
+     * @returns {boolean}
+     * @memberof RegoTerm
+     */
+    hasCollectionLookup(): boolean;
+    /**
+     * The term is not only a Reference but a reference contains simple collection lookup
+     * i.e. only contains one collection lookup and the whole ref ends with the only collection lookup
+     * e.g. objectA.propB.collectionC[_]
+     * Note: objectA.propB.collectionC[_].name is not a simple collection lookup as it resolve to single value (`name` property)
+     * rather than a collection
+     *
+     * @returns {boolean}
+     * @memberof RegoTerm
+     */
+    isSimpleCollectionLookup(): boolean;
+    /**
+     *
+     *
+     * @returns {boolean}
+     * @memberof RegoTerm
+     */
+    isResolveAsCollectionValue(): boolean;
+    /**
+     * If it's a reference term, return its full string representation
+     * Otherwise, throw exception
+     *
+     * @param {string[]} [removalPrefixs=[]]
+     * @returns {string}
+     * @memberof RegoTerm
+     */
+    fullRefString(removalPrefixs?: string[]): string;
+    /**
+     * If it's a reference term, return its string representation (not include ending [_])
+     * Otherwise, throw exception
+     *
+     * @param {string[]} [removalPrefixs=[]]
+     * @returns {string}
+     * @memberof RegoTerm
+     */
+    refString(removalPrefixs?: string[]): string;
+    /**
+     * Return term as operator string e.g. `=`, `>=` etc.
+     *
+     * @returns {string}
+     * @memberof RegoTerm
+     */
+    asOperator(): string;
+    /**
+     * If it's a operator term
+     *
+     * @returns {boolean}
+     * @memberof RegoTerm
+     */
+    isOperator(): boolean;
+    /**
+     * Tried to determine the value of the term
+     *
+     * @returns {RegoValue}
+     * @memberof RegoTerm
+     */
+    getValue(): RegoValue;
+    static parseFromData(data: any, parser: OpaCompileResponseParser): RegoTerm;
+}
+/**
+ * Represents Rego expression
+ *
+ * @export
+ * @class RegoExp
+ */
+export declare class RegoExp {
+    /**
+     * All RegoTerms belongs to this expression
+     *
+     * @type {RegoTerm[]}
+     * @memberof RegoExp
+     */
+    terms: RegoTerm[];
+    /**
+     * Whether this expression is a negative expression
+     * i.e. it's final evaluation result should be `false` if result is `true`
+     *
+     * @type {boolean}
+     * @memberof RegoExp
+     */
+    isNegated: boolean;
+    /**
+     * If it's complete evaluated
+     *
+     * @type {boolean}
+     * @memberof RegoExp
+     */
+    isCompleteEvaluated: boolean;
+    /**
+     * The value of the expression
+     *
+     * @type {RegoValue}
+     * @memberof RegoExp
+     */
+    value: RegoValue;
+    /**
+     * Ref to Opa Parser
+     *
+     * @private
+     * @type {OpaCompileResponseParser}
+     * @memberof RegoExp
+     */
+    private parser;
+    constructor(terms: RegoTerm[], isNegated: boolean, isCompleteEvaluated: boolean, value: RegoValue, parser: OpaCompileResponseParser);
+    clone(): RegoExp;
+    /**
+     * For debug usage, print terms as easy to ready short string
+     *
+     * @returns
+     * @memberof RegoExp
+     */
+    termsAsString(): (number | Object)[];
+    /**
+     * Output human readable string
+     *
+     * @returns {string}
+     * @memberof RegoExp
+     */
+    toHumanReadableString(): string;
+    /**
+     * Try to determins its value
+     *
+     * @returns
+     * @memberof RegoExp
+     */
+    getValue(): number | Object;
+    isMatch(): boolean;
+    /**
+     * Convert operator term to string and put rest operands into an array.
+     * And then return a [Operator, Operands] structure
+     *
+     * @returns {[string, RegoTerm[]]}
+     * @memberof RegoExp
+     */
+    toOperatorOperandsArray(): [string, RegoTerm[]];
+    /**
+     * Try to evaluate the expression
+     *
+     * @returns
+     * @memberof RegoExp
+     */
+    evaluate(): this;
+    static parseFromData(expData: any, parser: OpaCompileResponseParser): RegoExp;
+}
+/**
+ * Represents a special Rego Term type: reference term
+ * You shouldn't use this class directly
+ *
+ * @export
+ * @class RegoRef
+ */
+export declare class RegoRef {
+    parts: RegoRefPart[];
+    constructor(parts: RegoRefPart[]);
+    clone(): RegoRef;
+    static parseFromData(data: any): RegoRef;
+    static convertToFullRefString(parts: RegoRefPart[]): string;
+    removeAllPrefixs(str: string, removalPrefixs?: string[]): string;
+    fullRefString(removalPrefixs?: string[]): string;
+    refString(removalPrefixs?: string[]): string;
+    asCollectionRefs(removalPrefixs?: string[]): string[];
+    isOperator(): boolean;
+    hasCollectionLookup(): boolean;
+    isSimpleCollectionLookup(): boolean;
+    isResolveAsCollectionValue(): boolean;
+    asOperator(): string;
+}
+export interface CompleteRuleResult {
+    fullName: string;
+    name: string;
+    value: RegoValue;
+    isCompleteEvaluated: boolean;
+    residualRules?: RegoRule[];
+}
+export declare function value2String(value: RegoValue): string;
+/**
+ * OPA result Parser
+ *
+ * @export
+ * @class OpaCompileResponseParser
+ */
+export default class OpaCompileResponseParser {
+    /**
+     * If a warning is produced during the parsing
+     *
+     * @type {boolean}
+     * @memberof OpaCompileResponseParser
+     */
+    hasWarns: boolean;
+    /**
+     * Any warnings produced during the parsing
+     *
+     * @type {string[]}
+     * @memberof OpaCompileResponseParser
+     */
+    warns: string[];
+    private data;
+    /**
+     * Inital Rules parsed from result
+     * Only for debug purpose
+     *
+     * @type {RegoRule[]}
+     * @memberof OpaCompileResponseParser
+     */
+    originalRules: RegoRule[];
+    /**
+     * Parsed, compressed & evaluated rules
+     *
+     * @type {RegoRule[]}
+     * @memberof OpaCompileResponseParser
+     */
+    rules: RegoRule[];
+    queries: RegoExp[];
+    /**
+     * A cache of all resolved rule result
+     *
+     * @type {{
+     *         [fullName: string]: CompleteRuleResult;
+     *     }}
+     * @memberof OpaCompileResponseParser
+     */
+    completeRuleResults: {
+        [fullName: string]: CompleteRuleResult;
+    };
+    /**
+     * The pseudo query rule name
+     * The parser will assign a random pseudo rule name to the query expressions you submit.
+     *
+     * @type {string}
+     * @memberof OpaCompileResponseParser
+     */
+    readonly pseudoQueryRuleName: string;
+    private setQueryRuleResult;
+    /**
+     * Parse OPA result Response
+     *
+     * @param {*} json
+     * @returns {RegoRule[]}
+     * @memberof OpaCompileResponseParser
+     */
+    parse(json: any): RegoRule[];
+    /**
+     * Tried to merge rules outcome so that the ref value can be established easier
+     * After this step, any rules doesn't involve unknown should be merged to one value
+     * This will help to generate more concise query later.
+     * `CompleteRule` rule involves no `unknowns`
+     *
+     * Only for internal usage
+     *
+     * @private
+     * @memberof OpaCompileResponseParser
+     */
+    private calculateCompleteRuleResult;
+    /**
+     * Only for internal usage
+     *
+     * @returns
+     * @private
+     * @memberof OpaCompileResponseParser
+     */
+    private reduceDependencies;
+    /**
+     * Call to evaluate a rule
+     *
+     * @param {string} fullName
+     * @returns {CompleteRuleResult}
+     * @memberof OpaCompileResponseParser
+     */
+    evaluateRule(fullName: string): CompleteRuleResult | null;
+    /**
+     * Shortcut to evalute query result directly
+     *
+     * @returns {CompleteRuleResult}
+     * @memberof OpaCompileResponseParser
+     */
+    evaluate(): CompleteRuleResult;
+    /**
+     * evaluate a rule and returned as human readable string
+     *
+     * @param {string} fullName
+     * @returns {string}
+     * @memberof OpaCompileResponseParser
+     */
+    evaluateRuleAsHumanReadableString(fullName: string): string;
+    /**
+     * Shortcut to evalute query result directly and returned as human readable string
+     *
+     * @returns {string}
+     * @memberof OpaCompileResponseParser
+     */
+    evaluateAsHumanReadableString(): string;
+    /**
+     * Only for internal usage
+     *
+     * @param {RegoRule} rule
+     * @returns {CompleteRuleResult}
+     * @private
+     * @memberof OpaCompileResponseParser
+     */
+    private createCompleteRuleResult;
+    reportWarns(msg: string): void;
+}
+export declare function unknown2Ref(unknown: string): string;