Feature rule error arguments (#471)

Author: Varagos

.github/workflows/ci.yml

@@ -51,4 +51,4 @@ jobs:
         working-directory: ./transpiler
         env:
           NODE_OPTIONS: '--max_old_space_size=4096'
-        run: npm run test-silent
+        run: yarn test:swc --silent

cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitloops/bitloops-language-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Bitloops Language CLI",
   "type": "module",
   "engines": {
@@ -83,7 +83,7 @@
   "author": "Bitloops S.A.",
   "license": "GPL-3.0",
   "dependencies": {
-    "@bitloops/bl-transpiler": "^0.6.5",
+    "@bitloops/bl-transpiler": "^0.6.11",
     "axios": "^1.1.3",
     "chalk": "5.0.1",
     "cli-progress": "^3.12.0",
@@ -100,4 +100,4 @@
   "volta": {
     "node": "16.13.0"
   }
-}
+}

cli/yarn.lock

@@ -290,10 +290,10 @@
   resolved "https://registry.yarnpkg.com/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz#75a2e8b51cb758a7553d6804a5932d7aace75c39"
   integrity sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==
 
-"@bitloops/bl-transpiler@^0.6.5":
-  version "0.6.5"
-  resolved "https://registry.yarnpkg.com/@bitloops/bl-transpiler/-/bl-transpiler-0.6.5.tgz#d49fdb72bf38349125d44f991b2c82b45ce210df"
-  integrity sha512-Z3QLLJL79HwPPrkYfy7UcxxeRMBtFAmA3FKRdvqaAz3HZRURpKwwkm5B0F2SMSFGxGossTGL4VitpGbKCtsK7A==
+"@bitloops/bl-transpiler@^0.6.11":
+  version "0.6.11"
+  resolved "https://registry.yarnpkg.com/@bitloops/bl-transpiler/-/bl-transpiler-0.6.11.tgz#6be3bf6bab6a7915539708a8b18c05d573417227"
+  integrity sha512-rE39fr4cupvIrkefxY3G0aZQ6eugZK0DXSLL8BOc6vHXNemCJ1Hi1+eDUqurlcv4Wh+AfzCjlaT6F/Xg0M/U2A==
   dependencies:
     antlr4 "4.11.0"
     lodash "^4.17.21"

documentation/docs/reference/rule.md

@@ -25,3 +25,67 @@ keywords:
 # Rule
 
 A Rule or a Business Rule is a language element which captures some business rules of the language. They are used inside the domain layer to enforce the invariants.
+It provides a structured way to encapsulate complex business conditions and exceptions, ensuring they are consistently enforced across the domain layer of your application.
+
+## Syntax
+
+Each Rule can throw a Domain Error when its associated condition is not satisfied. The Domain Error serves as an exception mechanism indicating a violation of business rules.
+
+For instance, let's consider the following Domain Error:
+
+```typescript
+DomainError InsufficientBalanceError(balance: float) {
+    message: `Insufficient balance: ${balance} in account`,
+    errorId: 'INSUFFICIENT_BALANCE`
+}
+```
+
+This error is thrown when an operation attempts to reduce an account's balance below zero.
+
+We define the corresponding Domain Rule, AccountCannotHaveNegativeBalanceRule, as shown below:
+
+We would declare the corresponding Domain Rule like this:
+
+```typescript
+Rule AccountCannotHaveNegativeBalanceRule(amount: float, balance: float) throws DomainErrors.InsufficientBalanceError {
+    const balanceUpdated = balance - amount;
+    isBrokenIf(balanceUpdated < 0, (balanceUpdated, amount));
+}
+```
+
+Here, the `AccountCannotHaveNegativeBalanceRule` Rule encapsulates the invariant that an account's balance cannot become negative. If the amount to be subtracted from the balance would result in a negative value, the `isBrokenIf` function throws the `InsufficientBalanceError` Domain Error.
+
+### Using isBrokenIf
+
+The `isBrokenIf` function is central to a Domain Rule definition. This function accepts two arguments:
+
+1. A boolean condition to be evaluated.
+2. The arguments to be passed to the Domain Error, in case the condition is evaluated to `true`.
+
+The second argument of `isBrokenIf` maps directly to the parameters of the Domain Error. In the `AccountCannotHaveNegativeBalanceRule` example above, `(balanceUpdated, amount)` are passed as the second argument, which are then utilized by the `InsufficientBalanceError`.
+
+```typescript
+isBrokenIf(balanceUpdated < 0, (balanceUpdated, amount));
+```
+
+In situations where the Domain Error does not expect any arguments, you can omit the second argument from `isBrokenIf`.
+
+For example, if we have a `GenericError` that doesn't expect any arguments:
+
+```typescript
+DomainError GenericError() {
+  message: `A generic error has occurred`,
+  errorId: 'GENERIC_ERROR`
+}
+```
+
+We could write a corresponding rule like this:
+
+```typescript
+Rule SomeGenericRule(parameter: string) throws DomainErrors.GenericError {
+  const someCondition = /_ evaluate some condition _/
+  isBrokenIf(someCondition);
+}
+```
+
+Here, the `isBrokenIf` function only requires the condition to be evaluated because `GenericError` doesn't take any additional arguments.

examples/todo/bl-source/iam/authentication/domain/rules/rules.bl

@@ -1,4 +1,4 @@
 Rule ValidEmailRule(email: string) throws DomainErrors.InvalidEmailError {
     const re = /\S+@\S+\.\S+/;
-    isBrokenIf(re.test(email) == false);
+    isBrokenIf(re.test(email) == false, (email));
 }

examples/todo/bl-source/marketing/marketing/domain/rules/rules.bl

@@ -1,8 +1,8 @@
 Rule CompletedTodosIsPositiveNumberRule(counter: int32) throws DomainErrors.InvalidTodosCounterError { 
-    isBrokenIf(counter < 0);
+    isBrokenIf(counter < 0, (counter));
 }
 
 Rule ValidEmailRule(email: string) throws DomainErrors.InvalidEmailDomainError {
     const re = /\S+@\S+\.\S+/;
-    isBrokenIf(re.test(email) == false);
+    isBrokenIf(re.test(email) == false, (email));
 }

examples/todo/bl-source/todo/todo/domain/errors/errors.bl

@@ -1,4 +1,4 @@
-DomainError TodoAlreadyCompletedError(completed: bool, id: string) { 
+DomainError TodoAlreadyCompletedError(id: string) { 
     message: `Todo ${id} is already completed`,
     errorId: 'e09ec42c-4d31-4f7c-b68a-b68a78-b68a655'
 }
@@ -8,7 +8,7 @@ DomainError TitleOutOfBoundsError(title: string) {
     errorId: 'a12ec42c-4d31-4f7c-b68a-b68a78-b68a655'
 }
 
-DomainError TodoAlreadyUncompletedError(completed: bool, id: string) { 
+DomainError TodoAlreadyUncompletedError(id: string) { 
     message: `Todo ${id} is already uncompleted`,
     errorId: '24225fc3-9137-4f2f-a35d-b86f6d4ad68e'
 }

examples/todo/bl-source/todo/todo/domain/rules/rules.bl

@@ -1,11 +1,11 @@
 Rule TitleOutOfBoundsRule(title: string) throws DomainErrors.TitleOutOfBoundsError { 
-    isBrokenIf(title.length > 150 OR title.length < 4);
+    isBrokenIf(title.length > 150 OR title.length < 4, (title));
 }
 
 Rule TodoAlreadyCompletedRule(completed: bool, todoId: string) throws DomainErrors.TodoAlreadyCompletedError { 
-    isBrokenIf(completed);
+    isBrokenIf(completed, (todoId));
 }
 
 Rule TodoAlreadyUncompletedRule(completed: bool, todoId: string) throws DomainErrors.TodoAlreadyUncompletedError { 
-    isBrokenIf(NOT completed);
+    isBrokenIf(NOT completed, (todoId));
 }

transpiler/__tests__/ast/core/builders/domainRuleBuilder.ts

@@ -5,6 +5,7 @@ import {
   TStatements,
   TExpression,
   TCondition,
+  TArgumentList,
 } from '../../../../src/types.js';
 
 export class DomainRuleBuilder implements IBuilder<TDomainRule> {
@@ -34,8 +35,11 @@ export class DomainRuleBuilder implements IBuilder<TDomainRule> {
     return this;
   }
 
-  public withIsBrokenIfCondition(condition: TExpression): DomainRuleBuilder {
-    this.isBrokenIfCondition = { condition };
+  public withIsBrokenIfCondition(
+    condition: TExpression,
+    errorArguments?: TArgumentList,
+  ): DomainRuleBuilder {
+    this.isBrokenIfCondition = { condition, ...errorArguments };
     return this;
   }
 

transpiler/__tests__/ast/core/mocks/domainRule.ts

@@ -22,6 +22,7 @@ import { DomainRuleBuilder } from '../builders/domainRuleBuilder.js';
 import { ParameterListBuilderDirector } from '../builders/parameterListBuilderDirector.js';
 import { ExpressionBuilderDirector } from '../builders/expressionDirector.js';
 import { ConstDeclarationBuilderDirector } from '../builders/statement/variableDeclarationDirector.js';
+import { ArgumentListBuilderDirector } from '../builders/argumentListBuilderDirector.js';
 
 type DomainRuleDeclarationTestCase = {
   description: string;
@@ -91,4 +92,38 @@ export const validDomainRuleStatementTestCases: DomainRuleDeclarationTestCase[]
       ])
       .build(),
   },
+  {
+    description: 'Domain rule with statement and different error arguments',
+    fileId: 'testFile.bl',
+    inputBLString: `Rule IsValidTitleRule(title: string) throws DomainErrors.InvalidTitleError {
+      const titleLength = title.length;
+      isBrokenIf (titleLength > 150 OR titleLength < 4, (titleLength, title));
+    }`,
+    domainRuleDeclaration: new DomainRuleBuilder()
+      .withIdentifier('IsValidTitleRule')
+      .withParameters(new ParameterListBuilderDirector().buildStringParams('title'))
+      .withThrowsError('DomainErrors.InvalidTitleError')
+      .withIsBrokenIfCondition(
+        new ExpressionBuilderDirector().buildLogicalOrExpression(
+          new ExpressionBuilderDirector().buildRelationalExpression(
+            new ExpressionBuilderDirector().buildIdentifierExpression('titleLength'),
+            new ExpressionBuilderDirector().buildInt32LiteralExpression(150),
+            '>',
+          ),
+          new ExpressionBuilderDirector().buildRelationalExpression(
+            new ExpressionBuilderDirector().buildIdentifierExpression('titleLength'),
+            new ExpressionBuilderDirector().buildInt32LiteralExpression(4),
+            '<',
+          ),
+        ),
+        new ArgumentListBuilderDirector().buildArgumentList(['titleLength', 'title']),
+      )
+      .withBodyStatements([
+        new ConstDeclarationBuilderDirector().buildConstDeclarationWithMemberDotExpression({
+          name: 'titleLength',
+          rightMembers: ['title', 'length'],
+        }),
+      ])
+      .build(),
+  },
 ];

transpiler/__tests__/end-to-end/mocks/entity-primitives/arrays/array-of-vo.output.mock.ts

@@ -7,7 +7,7 @@ import {
 import { StatusVO, TStatusVOPrimitives } from './status.value-object';
 import { RowEntity, TRowEntityPrimitives } from './row.entity';
 export type TDocumentEntityPrimitives = {
-  id: string;
+  id?: string;
   name: string;
   locations: TDocumentLocationVOPrimitives[];
   rows: TRowEntityPrimitives[];

transpiler/__tests__/end-to-end/mocks/entity-primitives/index.ts

@@ -19,4 +19,13 @@ export const ENTITY_PRIMITIVES_END_TO_END_TEST_CASES = [
       'transpiler/__tests__/end-to-end/mocks/entity-primitives/regular-vo-s/output.mock.ts',
     ),
   },
+  {
+    description: 'Test optional properties',
+    input: FileUtil.readFileString(
+      'transpiler/__tests__/end-to-end/mocks/entity-primitives/optional-properties/input.bl',
+    ),
+    output: FileUtil.readFileString(
+      'transpiler/__tests__/end-to-end/mocks/entity-primitives/optional-properties/output.mock.ts',
+    ),
+  },
 ];

transpiler/__tests__/end-to-end/mocks/entity-primitives/optional-properties/input.bl

@@ -0,0 +1,38 @@
+Props MoneyProps {
+    string currency;
+    AmountVO amount; 
+}
+
+ValueObject MoneyVO {
+    static create(props: MoneyProps): (OK(MoneyVO), Errors()) {
+    }
+}
+
+Props AmountProps {
+    int32 value;
+}
+ValueObject AmountVO {
+    static create(props: AmountProps): (OK(AmountVO), Errors()) {
+    }
+}
+
+Props AccountProps {
+    optional UUIDv4 id;
+    optional MoneyVO price;
+    optional RowEntity row;
+    optional RowEntity[] rows;
+}
+
+Root Entity AccountEntity {
+    static create(props: AccountProps): (OK(AccountEntity), Errors()) { }
+}
+
+// **** Row Entity ****
+Props RowProps {
+    optional UUIDv4 id;
+    string description;
+}
+
+Entity RowEntity {
+    static create(props: RowProps): (OK(RowEntity), Errors()) { }
+}

transpiler/__tests__/end-to-end/mocks/entity-primitives/optional-properties/output.mock.ts

@@ -0,0 +1,48 @@
+import { Domain, Either, ok } from '@bitloops/bl-boilerplate-core';
+import { AccountProps } from './account.props';
+import { MoneyVO, TMoneyVOPrimitives } from './money.value-object';
+import { RowEntity, TRowEntityPrimitives } from './row.entity';
+import { AmountVO } from './amount.value-object';
+export type TAccountEntityPrimitives = {
+  id?: string;
+  price?: TMoneyVOPrimitives;
+  row?: TRowEntityPrimitives;
+  rows?: TRowEntityPrimitives[];
+};
+export class AccountEntity extends Domain.Aggregate<AccountProps> {
+  private constructor(props: AccountProps) {
+    super(props, props.id);
+  }
+  public static create(props: AccountProps): Either<AccountEntity, never> {
+    return ok(new AccountEntity(props));
+  }
+  get id() {
+    return this._id;
+  }
+  get price(): MoneyVO {
+    return this.props.price;
+  }
+  get row(): RowEntity {
+    return this.props.row;
+  }
+  get rows(): RowEntity[] {
+    return this.props.rows;
+  }
+  public static fromPrimitives(data: TAccountEntityPrimitives): AccountEntity {
+    const AccountEntityProps = {
+      id: new Domain.UUIDv4(data.id) as Domain.UUIDv4,
+      price: data.price ? MoneyVO.fromPrimitives(data.price) : undefined,
+      row: data.row ? RowEntity.fromPrimitives(data.row) : undefined,
+      rows: data.rows ? data.rows.map((x) => RowEntity.fromPrimitives(x)) : undefined,
+    };
+    return new AccountEntity(AccountEntityProps);
+  }
+  public toPrimitives(): TAccountEntityPrimitives {
+    return {
+      id: this.id.toString(),
+      price: this.price?.toPrimitives(),
+      row: this.row?.toPrimitives(),
+      rows: this.rows?.map((x) => x.toPrimitives()),
+    };
+  }
+}

transpiler/__tests__/end-to-end/mocks/entity-primitives/regular-vo-s/output.mock.ts

@@ -4,7 +4,7 @@ import { MoneyVO, TMoneyVOPrimitives } from './money.value-object';
 import { RowEntity, TRowEntityPrimitives } from './row.entity';
 import { AmountVO } from './amount.value-object';
 export type TAccountEntityPrimitives = {
-  id: string;
+  id?: string;
   price: TMoneyVOPrimitives;
   row: TRowEntityPrimitives;
 };