JsonRules Engine

https://github.com/xe4me/json-rules
Admin
A rule engine for JavaScript & TypeScript that allows defining and evaluating business logic using...
Tokens:3,694
Snippets:15
Trust Score:5.8
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Quick Start: Evaluate a Rule

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Demonstrates how to import the JsonRules engine, define a simple rule with conditions, and evaluate it against user data. This example shows a basic use case for checking age and country.

```typescript
import { JsonRules, Rule } from "@ivandt/json-rules";

// Define a rule
const rule: Rule = {
  conditions: {
    all: [
      { field: "age", operator: "is greater than or equal", value: 18 },
      { field: "country", operator: "is equal", value: "US" }
    ]
  }
};

// Evaluate against data
const user = { age: 25, country: "US" };
const result = await JsonRules.evaluate(rule, user);
console.log(result); // true
```

--------------------------------

### Install JsonRules Engine

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Installs the JsonRules engine using npm. This is the primary method for adding the library to your project.

```bash
npm install @ivandt/json-rules
```

--------------------------------

### Template Variables Example

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Demonstrates the use of template variables within rule conditions. The values for 'startDate' and 'maxBudget' would be provided during the evaluation process, allowing for dynamic rule creation.

```typescript
const dynamicRule: Rule = {
  conditions: {
    all: [
      { field: "endDate", operator: "is after", value: "{startDate}" },
      { field: "price", operator: "is less than", value: "{maxBudget}" }
    ]
  }
};
```

--------------------------------

### Basic Rule Example

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Demonstrates a simple rule evaluation. The rule checks if a user's age is 21 or greater and if their country is either 'US' or 'CA'. The example shows how to define the rule and the user data, and then evaluate it using `JsonRules.evaluate`.

```typescript
const rule: Rule = {
  conditions: {
    all: [
      { field: "age", operator: "is greater than or equal", value: 21 },
      { field: "country", operator: "in", value: ["US", "CA"] }
    ]
  }
};

const user = { age: 25, country: "US" };
const result = await JsonRules.evaluate(rule, user); // true
```

--------------------------------

### Validation Operators Example

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Shows how to use specific validation operators for fields like email, phone, and website. The 'is valid email' operator checks email format, 'is valid phone' checks phone number format with locale support, and 'is URL' validates URL format with protocol options.

```typescript
const validationRule: Rule = {
  conditions: {
    all: [
      { field: "email", operator: "is valid email", value: null },
      { field: "phone", operator: "is valid phone", value: { locale: "us" } },
      { field: "website", operator: "is URL", value: { protocols: ["https"] } }
    ]
  }
};
```

--------------------------------

### Complex Conditions Example

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Illustrates a rule with nested conditions using 'any' and 'all' operators. This rule evaluates to true if either the user is a 'premium' member with over 365 days of account age, OR if they have spent over 1000 and made a purchase after January 1, 2024.

```typescript
const complexRule: Rule = {
  conditions: {
    any: [
      {
        all: [
          { field: "membershipTier", operator: "is equal", value: "premium" },
          { field: "accountAge", operator: "is greater than", value: 365 }
        ]
      },
      {
        all: [
          { field: "totalSpent", operator: "is greater than", value: 1000 },
          { field: "lastPurchase", operator: "is after", value: new Date('2024-01-01') }
        ]
      }
    ]
  }
};
```

--------------------------------

### Condition Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Describes the logical operators ('all', 'any', 'none') used to combine multiple constraints within a rule. 'all' acts as AND, 'any' as OR, and 'none' as NOT.

```typescript
{
  field: string,
           // Property path (supports dot notation)
  operator: string,
           // Comparison operator
  value: any
             // Expected value or template reference
}
```

--------------------------------

### Pattern Matching Operators (Regex)

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for validating strings against regular expression patterns, with support for custom flags.

```json
{
  "field": "email",
  "operator": "matches",
  "value": { "regex": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$" }
}
```

```json
{
  "field": "username",
  "operator": "not matches",
  "value": { "regex": "^(admin|root)$", "flags": "i" }
}
```

--------------------------------

### String Operation Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for performing substring checks, prefix/suffix matching, and checking for the presence of any specified substrings within a string.

```json
{
  "field": "email",
  "operator": "contains",
  "value": "@company.com"
}
```

```json
{
  "field": "message",
  "operator": "not contains",
  "value": "spam"
}
```

```json
{
  "field": "title",
  "operator": "contains any",
  "value": ["urgent", "critical"]
}
```

```json
{
  "field": "content",
  "operator": "not contains any",
  "value": ["spam", "scam"]
}
```

```json
{
  "field": "productCode",
  "operator": "starts with",
  "value": "PRD-"
}
```

```json
{
  "field": "filename",
  "operator": "ends with",
  "value": ".pdf"
}
```

--------------------------------

### Phone Number Validation Import

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Explains how to import specific locale validators for phone number validation. Users need to import the desired locale modules before using the 'is valid phone' operator.

```typescript
// Import specific locales
import "@ivandt/json-rules/validators/phone/us";
import "@ivandt/json-rules/validators/phone/gb";
import "@ivandt/json-rules/validators/phone/de";

const rule: Rule = {
  conditions: {
    all: [
      { field: "phone", operator: "is valid phone", value: { locale: "us" } }
    ]
  }
};
```

--------------------------------

### Data Validation Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for validating common data formats like email, phone numbers, URLs, UUIDs, and more, with optional configuration for specific formats.

```json
{
  "field": "email",
  "operator": "is valid email"
}
```

```json
{
  "field": "phone",
  "operator": "is valid phone",
  "value": { "locale": "us" }
}
```

```json
{
  "field": "website",
  "operator": "is URL",
  "value": { "requireTld": false }
}
```

```json
{
  "field": "id",
  "operator": "is UUID",
  "value": { "version": 4 }
}
```

```json
{
  "field": "barcode",
  "operator": "is EAN"
}
```

```json
{
  "field": "deviceId",
  "operator": "is IMEI",
  "value": { "allowHyphens": true }
}
```

```json
{
  "field": "distance",
  "operator": "is unit",
  "value": "length"
}
```

```json
{
  "field": "country",
  "operator": "is country",
  "value": { "format": "iso2" }
}
```

```json
{
  "field": "domain",
  "operator": "is domain",
  "value": { "requireTld": true }
}
```

--------------------------------

### Basic Rule Structure

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Defines the fundamental structure of a rule, including conditions and an optional default value. Conditions can be a single condition or an array of conditions.

```typescript
interface Rule {
  conditions: Condition | Condition[];
  default?: any;
}
```

--------------------------------

### Math & Number Validation Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for validating numerical properties such as even/odd, positive/negative, and checking for empty values.

```json
{
  "field": "quantity",
  "operator": "is even"
}
```

```json
{
  "field": "productId",
  "operator": "is odd"
}
```

```json
{
  "field": "balance",
  "operator": "is positive"
}
```

```json
{
  "field": "adjustment",
  "operator": "is negative"
}
```

```json
{
  "field": "optionalField",
  "operator": "is empty"
}
```

```json
{
  "field": "requiredField",
  "operator": "is not empty"
}
```

--------------------------------

### Date Operation Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for comparing dates, checking if a date falls before, after, on, or on/before a specified date.

```json
{
  "field": "expiry",
  "operator": "is before",
  "value": "2024-12-31"
}
```

```json
{
  "field": "startDate",
  "operator": "is after",
  "value": "2024-01-01"
}
```

```json
{
  "field": "deadline",
  "operator": "is on or before",
  "value": new Date()
}
```

```json
{
  "field": "validFrom",
  "operator": "is on or after",
  "value": new Date()
}
```

--------------------------------

### Collection & Array Operators

Source: https://github.com/xe4me/json-rules/blob/main/README.md

Operators for checking value existence within arrays or if array fields contain specific values.

```json
{
  "field": "country",
  "operator": "in",
  "value": ["US", "CA", "UK"]
}
```

```json
{
  "field": "status",
  "operator": "not in",
  "value": ["banned", "suspended"]
}
```

```json
{
  "field": "skills",
  "operator": "array contains",
  "value": "javascript"
}
```

```json
{
  "field": "permissions",
  "operator": "array no contains",
  "value": "admin"
}
```
Tokens:
Raw