feat: add debugger

.github/workflows/test.yml

@@ -6,7 +6,7 @@ jobs:
   build:
     runs-on: ubuntu-latest
     permissions:
-      pages: write
+      contents: write
     steps:
       - name: Check out repository
         uses: actions/checkout@v4

README.md

@@ -26,34 +26,6 @@ pnpm install @getspectra/spectra-js
 
 ## Usage
 
-```ts
-import {
-  Policy,
-  Spectra,
-  parseDependences,
-  ResourceInterface,
-  DataInterface,
- } from '@getspectra/spectra-js';
-
-function loadDataFromDatabase(resources: ResourceInterface): DataInterface {
-  return {
-    'user.id': 2,
-  };
-}
-
-const policy = new Policy({
-  applyFilter: ['user.id', '=', 2],
-  permissions: ['EDIT_FILE'],
-  effect: 'DENY',
-});
-
-const dataDependencies = parseDependences(policy.getApplyFilter());
-const resources = loadDataFromDatabase(dataDependencies);
-const result = Spectra.validate([policy], resources);
-
-console.info(result); // false
-```
-
 See [exapmle](./example/) for more usage.
 
 ## License

example/basic-usage.ts

@@ -1,40 +1,26 @@
-import {
-  BinaryExpression,
-  Policy,
-  Spectra,
-  parseDependences,
-  ResourceInterface,
-  DataInterface,
-} from '../src';
+import { BinaryExpression, Policy, Spectra, DataLoaderFunction } from '../src';
+
+const loadDataFromDatabase: DataLoaderFunction = () => {
+  return {
+    'user.id': 1,
+    'user.name': 'Amiya',
+    'file.name': 'file.txt',
+  };
+};
 
 const ALL_POLICIES = [
   new Policy({
-    applyFilter: new BinaryExpression('user.id', '=', 1),
     permissions: ['EDIT_FILE'],
     effect: 'ALLOW',
+    filter: new BinaryExpression('user.id', '=', 1),
   }),
   new Policy({
-    applyFilter: new BinaryExpression('user.id', '=', 2),
     permissions: ['EDIT_FILE'],
     effect: 'DENY',
+    filter: new BinaryExpression('user.id', '=', 2),
   }),
 ];
 
-const resourcesToLoad = ALL_POLICIES.reduce((memo, p) => {
-  const dataDependencies = parseDependences(p.getApplyFilter());
-  return Object.assign(memo, dataDependencies);
-}, {} as ResourceInterface);
-
-function loadDataFromDatabase(resources: ResourceInterface): DataInterface {
-  return {
-    'user.id': 1,
-    'user.name': 'Amiya',
-    'file.name': 'file.txt',
-  };
-}
-
-const resources = loadDataFromDatabase(resourcesToLoad);
-
-const result = Spectra.validate(ALL_POLICIES, resources);
+const result = Spectra.validate(ALL_POLICIES, loadDataFromDatabase, 'EDIT_FILE');
 
 console.info(result); // true

package.json

@@ -36,6 +36,6 @@
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "@getspectra/spectra-typings": "^0.0.5"
+    "@getspectra/spectra-typings": "^0.0.6"
   }
 }

src/debugger/debugger.ts

@@ -0,0 +1,16 @@
+import {
+  ExpressionDebugReport,
+  ExpressionInterface,
+  DebuggerOptions,
+  DataType,
+} from '@/types';
+
+export class Debugger {
+  public static debug(
+    data: DataType,
+    expression: ExpressionInterface,
+    options: DebuggerOptions
+  ): ExpressionDebugReport {
+    return expression.debug(data, options);
+  }
+}

src/debugger/index.ts

@@ -0,0 +1 @@
+export * from './debugger';

src/evaluator/evaluator.ts

@@ -0,0 +1,7 @@
+import { ExpressionInterface, DataType } from '@/types';
+
+export class Evaluator {
+  public static evaluate(data: DataType, filter: ExpressionInterface): boolean {
+    return filter.evaluate(data);
+  }
+}

src/evaluator/index.ts

@@ -0,0 +1 @@
+export * from './evaluator';

src/expressions/and.ts

@@ -1,5 +1,11 @@
 import { AndExpressionDefinition, FieldName } from '@getspectra/spectra-typings';
-import { ExpressionInterface } from '@/types';
+import {
+  DataType,
+  DebuggerOptions,
+  ExpressionInterface,
+  LogicExpressionDebugReport,
+  LogicOperationName,
+} from '@/types';
 
 export class AndExpression implements ExpressionInterface {
   private expressions: Array<ExpressionInterface>;
@@ -8,14 +14,8 @@ export class AndExpression implements ExpressionInterface {
     this.expressions = expressions;
   }
 
-  public getOperation(): string {
-    return 'AND';
-  }
-
-  public getExpression(): AndExpressionDefinition {
-    return {
-      and: this.expressions.map((expression) => expression.getExpression()),
-    };
+  public getName(): string {
+    return LogicOperationName.AND;
   }
 
   public getFields(): Array<FieldName> {
@@ -24,11 +24,25 @@ export class AndExpression implements ExpressionInterface {
     }, [] as Array<FieldName>);
   }
 
-  public evaluate(data: object): boolean {
-    return this.expressions.every((expression) => expression.evaluate(data));
+  public getDefinition(): AndExpressionDefinition {
+    return {
+      and: this.expressions.map((expression) => expression.getDefinition()),
+    };
   }
 
   public jsonSerialize(): string {
-    return JSON.stringify(this.getExpression());
+    return JSON.stringify(this.getDefinition());
+  }
+
+  public evaluate(data: DataType): boolean {
+    return this.expressions.every((expression) => expression.evaluate(data));
+  }
+
+  public debug(data: DataType, options: DebuggerOptions): LogicExpressionDebugReport {
+    return {
+      name: this.getName(),
+      value: this.evaluate(data),
+      expressions: this.expressions.map((expression) => expression.debug(data, options)),
+    };
   }
 }

src/expressions/binary.ts

@@ -4,8 +4,14 @@ import {
   FieldValue,
   Operation,
 } from '@getspectra/spectra-typings';
-import { ExpressionInterface, DataInterface } from '@/types';
-import { compareValue, getValueFromKey, isArgumentRef } from '@/utils';
+import {
+  ExpressionInterface,
+  DataType,
+  OperationName,
+  ExpressionDebugReport,
+  DebuggerOptions,
+} from '@/types';
+import { compareValue, getValueFromKey, isRefValue } from '@/utils';
 
 export class BinaryExpression implements ExpressionInterface {
   private left: FieldName;
@@ -18,31 +24,75 @@ export class BinaryExpression implements ExpressionInterface {
     this.operation = operation;
   }
 
-  public getOperation(): string {
-    return this.operation;
-  }
-
-  public getExpression(): BinaryExpressionDefinition {
-    return [this.left, this.operation, this.right];
+  public getName(): string {
+    return OperationName[this.operation];
   }
 
   public getFields(): Array<FieldName> {
     const fields = [this.left];
 
-    if (isArgumentRef(this.right)) {
+    if (isRefValue(this.right)) {
       fields.push(this.right.ref);
     }
 
     return fields;
   }
 
+  public getDefinition(): BinaryExpressionDefinition {
+    return [this.left, this.operation, this.right];
+  }
+
   public jsonSerialize(): string {
-    return JSON.stringify(this.getExpression());
+    return JSON.stringify(this.getDefinition());
   }
 
-  public evaluate(data: DataInterface): boolean {
-    const leftValue = getValueFromKey(data, this.left);
-    const rightValue = getValueFromKey(data, this.right);
-    return compareValue(leftValue, this.operation, rightValue);
+  public getValue(data: DataType) {
+    return {
+      left: {
+        name: this.left,
+        value: getValueFromKey(data, this.left),
+      },
+      right: isRefValue(this.right)
+        ? {
+            name: this.right.ref,
+            value: getValueFromKey(data, this.right.ref),
+          }
+        : {
+            name: null,
+            value: this.right,
+          },
+    };
+  }
+
+  public evaluate(data: DataType): boolean {
+    const { left, right } = this.getValue(data);
+    return compareValue(left.value, this.operation, right.value);
+  }
+
+  public debug(data: DataType, options: DebuggerOptions): ExpressionDebugReport {
+    const { left, right } = this.getValue(data);
+
+    let value: boolean;
+    if (
+      options.strict &&
+      isRefValue(this.right) &&
+      left.value === null &&
+      right.value === null
+    ) {
+      value = false;
+      console.warn(
+        '[spectra] strict mode: left and right are null, expression is false.'
+      );
+    } else {
+      value = compareValue(left.value, this.operation, right.value);
+    }
+
+    return {
+      name: this.getName(),
+      value,
+      left,
+      right,
+      operation: this.operation,
+    };
   }
 }

src/expressions/not.ts

@@ -1,5 +1,11 @@
 import { FieldName, NotExpressionDefinition } from '@getspectra/spectra-typings';
-import { ExpressionInterface } from '@/types';
+import {
+  DataType,
+  DebuggerOptions,
+  ExpressionInterface,
+  LogicExpressionDebugReport,
+  LogicOperationName,
+} from '@/types';
 
 export class NotExpression implements ExpressionInterface {
   private expression: ExpressionInterface;
@@ -8,25 +14,37 @@ export class NotExpression implements ExpressionInterface {
     this.expression = expression;
   }
 
-  public getOperation(): string {
-    return 'NOT';
+  public getName(): string {
+    return LogicOperationName.NOT;
   }
 
-  public getExpression(): NotExpressionDefinition {
+  public getFields(): Array<FieldName> {
+    return this.expression.getFields();
+  }
+
+  public getExpressons(): Array<ExpressionInterface> {
+    return [this.expression];
+  }
+
+  public getDefinition(): NotExpressionDefinition {
     return {
-      not: this.expression.getExpression(),
+      not: this.expression.getDefinition(),
     };
   }
 
-  public getFields(): Array<FieldName> {
-    return this.expression.getFields();
+  public jsonSerialize(): string {
+    return JSON.stringify(this.getDefinition());
   }
 
-  public evaluate(data: object): boolean {
+  public evaluate(data: DataType): boolean {
     return !this.expression.evaluate(data);
   }
 
-  public jsonSerialize(): string {
-    return JSON.stringify(this.getExpression());
+  public debug(data: DataType, options: DebuggerOptions): LogicExpressionDebugReport {
+    return {
+      name: this.getName(),
+      value: this.evaluate(data),
+      expressions: [this.expression.debug(data, options)],
+    };
   }
 }