@briza/illogical 1.4.3 → 1.5.2

package/readme.md

@@ -2,7 +2,7 @@
 
 A micro conditional javascript engine used to parse the raw logical and comparison expressions, evaluate the expression in the given data context, and provide access to a text form of the given expressions.
 
-> Revision: May 17, 2021.
+> Revision: February 1, 2022.
 
 ## About
 
@@ -178,7 +178,7 @@ evaluable.toString()
 ### Simplify
 
 Simplifies an expression with a given context. This is useful when you already have some of
-the properties of context and wants to try to eveluate the expression.
+the properties of context and wants to try to evaluate the expression.
 
 **Example**
 
@@ -192,8 +192,8 @@ Values not found in the context will cause the parent operand not to be evaluate
 as part of the simplified expression.
 
 In some situations we might want to evaluate the expression even if referred value is not
-present. You can provide a list of keys that will be evaluated even if they are not present
-in the context.
+present. You can provide a list of keys that will be strictly evaluated even if they are not
+present in the context.
 
 **Example**
 
@@ -201,10 +201,24 @@ in the context.
 engine.simplify(
   ['AND', ['==', '$a', 10], ['==', '$b', 20]],
   { a: 10 },
-  ['b'] // '$b' will be evaluted to undefined.
+  ['b'] // '$b' will be evaluated to undefined.
 ) // false
 ```
 
+Alternatively we might want to do the opposite and strictly evaluate the expression for all referred
+values not present in the context except for a specified list of optional keys.
+
+**Example**
+
+```js
+engine.simplify(
+  ['OR', ['==', '$a', 10], ['==', '$b', 20], ['==', '$c', 20]],
+  { c: 10 },
+  undefined,
+  ['b'] // except for '$b' everything not in context will be evaluated to undefined.
+) // ['==', '$b', 20]
+```
+
 ## Working with Expressions
 
 ### Evaluation Data Context
@@ -311,7 +325,7 @@ Simple value types: string, number, boolean.
 
 #### Reference
 
-The reference operand's value is resolved from the [Evaluation Data Context](#evaluation-data-context), where the the operands name is used as key in the context.
+The reference operand value is resolved from the [Evaluation Data Context](#evaluation-data-context), where the the operands name is used as key in the context.
 
 The reference operand must be prefixed with `$` symbol, e.g.: `$name`. This might be customized via [Reference Predicate Parser Option](#reference-predicate).
 
@@ -676,7 +690,7 @@ A function used to transform the operand into the reference annotation stripped
 referenceTransform: (operand: string) => string
 ```
 
-> **Default reference transform:**  
+> **Default reference transform:**
 > It removes the `$` symbol at the begging of the operand name.
 
 #### Operator Mapping

package/types/common/evaluable.d.ts

@@ -1,57 +1,57 @@
-/**
- * Common module.
- * @module illogical/common
- */
-import { Input } from '../parser';
-import { Options } from '../parser/options';
-/**
- * Valid types for context members
- */
-declare type ContextValue = Record<string, unknown> | string | number | boolean | null | undefined | ContextValue[];
-/**
- * Evaluation Context
- * Holds references used during the evaluation process.
- * Format: key: value.
- */
-export interface Context {
-    [k: string]: ContextValue;
-}
-/**
- * Evaluation result
- */
-export declare type Result = undefined | null | string | number | boolean | Array<Result>;
-export declare enum EvaluableType {
-    Operand = "Operand",
-    Expression = "Expression"
-}
-/**
- * Evaluable
- */
-export interface Evaluable {
-    type: EvaluableType;
-    /**
-     * Evaluate in the given context.
-     * @param {Context} ctx
-     * @return {Result}
-     */
-    evaluate(ctx: Context): Result;
-    /**
-     * Simplifies this Evaluable when possible.
-     *
-     * @param {Context} ctx context for the evaluation
-     * @param {string[]} ignoreKeys keys to be considered present even if their not present in the context
-     * @returns {Result | Evaluable} simplified value or itself
-     */
-    simplify(ctx: Context, ignoreKeys: string[]): Result | Evaluable;
-    /**
-     * Serializes the Evaluable to its input format.
-     *
-     * @param {Options} options parser options
-     */
-    serialize(options: Options): Input;
-    /**
-     * Get the strict representation of the evaluable expression.
-     */
-    toString(): string;
-}
-export {};
+import { Input } from '../parser';
+import { Options } from '../parser/options';
+/**
+ * Valid types for context members
+ */
+declare type ContextValue = Record<string, unknown> | string | number | boolean | null | undefined | ContextValue[];
+/**
+ * Evaluation Context
+ * Holds references used during the evaluation process.
+ * Format: key: value.
+ */
+export interface Context {
+    [k: string]: ContextValue;
+}
+/**
+ * Evaluation result
+ */
+export declare type Result = undefined | null | string | number | boolean | Array<Result>;
+export declare enum EvaluableType {
+    Operand = "Operand",
+    Expression = "Expression"
+}
+/**
+ * Evaluable
+ */
+export interface Evaluable {
+    type: EvaluableType;
+    /**
+     * Evaluate in the given context.
+     * @param {Context} ctx
+     * @return {Result}
+     */
+    evaluate(ctx: Context): Result;
+    /**
+     * Simplifies this Evaluable when possible.
+     *
+     * @param {Context} ctx context for the evaluation
+     * @param {string[]} strictKeys keys to be considered present even if they are not present in the context
+     * @param {string[]} optionalKeys keys to be considered not present unless they are in the context or in
+     *  `strictKeys`; when `strictKeys` is `undefined` and `optionalKeys` is an array, every key that is not in
+     *  `optionalKeys` is considered to be present and thus will be evaluated
+     * @returns {Result | Evaluable} simplified value or itself
+     */
+    simplify(ctx: Context, strictKeys?: string[], optionalKeys?: string[]): Result | Evaluable;
+    /**
+     * Serializes the Evaluable to its input format.
+     *
+     * @param {Options} options parser options
+     */
+    serialize(options: Options): Input;
+    /**
+     * Get the strict representation of the evaluable expression.
+     */
+    toString(): string;
+}
+export declare type SimplifyArgs = Parameters<Evaluable['simplify']>;
+export {};

package/types/common/type-check.d.ts

@@ -1,32 +1,28 @@
-/**
- * Common module.
- * @module illogical/common
- */
-import { Evaluable, Result } from './evaluable';
-/**
- * Is number predicate.
- * @param value Tested value.
- */
-export declare function isNumber(value: Result): value is number;
-/**
- * Is string type predicate.
- * @param value Tested value.
- */
-export declare function isString(value: Result): value is string;
-/**
- * Is Object
- * @param value tested value result of the test
- */
-export declare function isObject(value: unknown): value is Record<string, unknown>;
-/**
- * Is Boolean predicate.
- * @param value tested value.
- * @return result of the test
- */
-export declare function isBoolean(value: unknown): value is boolean;
-/**
- * Check if a value is a an Evaluable
- * @param {Result | Evaluable} value value to check if is Evaluable
- * @returns {Evaluable}
- */
-export declare function isEvaluable(value: Result | Evaluable): value is Evaluable;
+import { Evaluable, Result } from './evaluable';
+/**
+ * Is number predicate.
+ * @param value Tested value.
+ */
+export declare function isNumber(value: Result): value is number;
+/**
+ * Is string type predicate.
+ * @param value Tested value.
+ */
+export declare function isString(value: Result): value is string;
+/**
+ * Is Object
+ * @param value tested value result of the test
+ */
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Is Boolean predicate.
+ * @param value tested value.
+ * @return result of the test
+ */
+export declare function isBoolean(value: unknown): value is boolean;
+/**
+ * Check if a value is a an Evaluable
+ * @param {Result | Evaluable} value value to check if is Evaluable
+ * @returns {Evaluable}
+ */
+export declare function isEvaluable(value: Result | Evaluable): value is Evaluable;

package/types/common/util.d.ts

@@ -1,11 +1,11 @@
-import { Result } from './evaluable';
-/**
- * Convert a value to number if possible, otherwise return undefined
- * @param value value to be converted to number
- */
-export declare const toNumber: (value: Result) => number | undefined;
-/**
- * Convert a value to string if possible, otherwise return undefined
- * @param value value to be converted to string
- */
-export declare const toString: (value: Result) => string | undefined;
+import { Result } from './evaluable';
+/**
+ * Convert a value to number if possible, otherwise return undefined
+ * @param value value to be converted to number
+ */
+export declare const toNumber: (value: Result) => number | undefined;
+/**
+ * Convert a value to string if possible, otherwise return undefined
+ * @param value value to be converted to string
+ */
+export declare const toString: (value: Result) => string | undefined;

package/types/expression/comparison/eq.d.ts

@@ -1,22 +1,18 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * Equal comparison expression
- */
-export declare class Equal extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * Equal comparison expression
+ */
+export declare class Equal extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+}

package/types/expression/comparison/ge.d.ts

@@ -1,22 +1,18 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * Greater than or equal comparison expression
- */
-export declare class GreaterThanOrEqual extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * Greater than or equal comparison expression
+ */
+export declare class GreaterThanOrEqual extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+}

package/types/expression/comparison/gt.d.ts

@@ -1,22 +1,18 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * Greater than comparison expression
- */
-export declare class GreaterThan extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * Greater than comparison expression
+ */
+export declare class GreaterThan extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+}

package/types/expression/comparison/in.d.ts

@@ -1,27 +1,23 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * In comparison expression
- */
-export declare class In extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-    /**
-     * Get the strict representation of the expression.
-     * @return {string}
-     */
-    toString(): string;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * In comparison expression
+ */
+export declare class In extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+    /**
+     * Get the strict representation of the expression.
+     * @return {string}
+     */
+    toString(): string;
+}

package/types/expression/comparison/index.d.ts

@@ -1,49 +1,45 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Context, Evaluable, EvaluableType, Result } from '../../common/evaluable';
-import { Operand } from '../../operand';
-import { ExpressionInput } from '../../parser';
-import { Options } from '../../parser/options';
-/**
- * Abstract comparison expression
- */
-export declare abstract class Comparison implements Evaluable {
-    protected readonly operator: string;
-    protected readonly operatorSymbol: symbol;
-    protected readonly left: Operand;
-    protected readonly right: Operand;
-    type: EvaluableType;
-    /**
-     * @constructor
-     * @param {string} operator String representation of the operator.
-     * @param {Operand} left Left operand.
-     * @param {Operand} right Right operand.
-     */
-    constructor(operator: string, operatorSymbol: symbol, left: Operand, right: Operand);
-    /**
-     * {@link Evaluable.evaluate}
-     */
-    evaluate(ctx: Context): Result;
-    /**
-     * Get the strict representation of the expression.
-     * @return {string}
-     */
-    toString(): string;
-    /**
-     * Compares left and right operands evaluated values.
-     * @param {Result} left left operand result value
-     * @param {Result} right right operand result value
-     * @returns {boolean}
-     */
-    abstract comparison(left: Result, right: Result): boolean;
-    /**
-     * {@link Evaluable.simplify}
-     */
-    simplify(...args: [Context, string[]]): Result | Evaluable;
-    /**
-     * {@link Evaluable.serialize}
-     */
-    serialize(options: Options): ExpressionInput;
-}
+import { Context, Evaluable, EvaluableType, Result, SimplifyArgs } from '../../common/evaluable';
+import { Operand } from '../../operand';
+import { ExpressionInput } from '../../parser';
+import { Options } from '../../parser/options';
+/**
+ * Abstract comparison expression
+ */
+export declare abstract class Comparison implements Evaluable {
+    protected readonly operator: string;
+    protected readonly operatorSymbol: symbol;
+    protected readonly left: Operand;
+    protected readonly right: Operand;
+    type: EvaluableType;
+    /**
+     * @constructor
+     * @param {string} operator String representation of the operator.
+     * @param {Operand} left Left operand.
+     * @param {Operand} right Right operand.
+     */
+    constructor(operator: string, operatorSymbol: symbol, left: Operand, right: Operand);
+    /**
+     * {@link Evaluable.evaluate}
+     */
+    evaluate(ctx: Context): Result;
+    /**
+     * Get the strict representation of the expression.
+     * @return {string}
+     */
+    toString(): string;
+    /**
+     * Compares left and right operands evaluated values.
+     * @param {Result} left left operand result value
+     * @param {Result} right right operand result value
+     * @returns {boolean}
+     */
+    abstract comparison(left: Result, right: Result): boolean;
+    /**
+     * {@link Evaluable.simplify}
+     */
+    simplify(...args: SimplifyArgs): Result | Evaluable;
+    /**
+     * {@link Evaluable.serialize}
+     */
+    serialize(options: Options): ExpressionInput;
+}

package/types/expression/comparison/le.d.ts

@@ -1,22 +1,18 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * Less than or equal comparison expression
- */
-export declare class LessThanOrEqual extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * Less than or equal comparison expression
+ */
+export declare class LessThanOrEqual extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+}

package/types/expression/comparison/lt.d.ts

@@ -1,22 +1,18 @@
-/**
- * Comparison expression module.
- * @module illogical/expression/comparison
- */
-import { Evaluable, Result } from '../../common/evaluable';
-import { Comparison } from '../comparison';
-export declare const OPERATOR: unique symbol;
-/**
- * Less than comparison expression
- */
-export declare class LessThan extends Comparison {
-    /**
-     * @constructor
-     * @param {Evaluable} left Left operand.
-     * @param {Evaluable} right Right operand.
-     */
-    constructor(...args: Evaluable[]);
-    /**
-     * {@link Comparison.comparison}
-     */
-    comparison(left: Result, right: Result): boolean;
-}
+import { Evaluable, Result } from '../../common/evaluable';
+import { Comparison } from '../comparison';
+export declare const OPERATOR: unique symbol;
+/**
+ * Less than comparison expression
+ */
+export declare class LessThan extends Comparison {
+    /**
+     * @constructor
+     * @param {Evaluable} left Left operand.
+     * @param {Evaluable} right Right operand.
+     */
+    constructor(...args: Evaluable[]);
+    /**
+     * {@link Comparison.comparison}
+     */
+    comparison(left: Result, right: Result): boolean;
+}