Logical Operators - Rule Engine JS

Overview

Logical operators let you combine multiple conditions together. Think of them like building blocks for complex rules.

and

All conditions must be true

or

At least one condition must be true

not

Reverses a condition

Architecture

Logical operators are implemented in the LogicalOperators class: Source Files:

Logical operators: src/operators/logical.js
Base operator: src/operators/base/BaseOperator.js
Unit tests: tests/unit/operators/logical.test.js

Key Features

Short-circuit evaluation - Stops checking as soon as result is known
Unlimited nesting - Combine operators inside each other
Works with any operator - Combine comparison, string, array operators, etc.
Clear error messages - Helpful feedback when something goes wrong

`and` - All Must Be True

All conditions must pass for the rule to pass. Like saying “I need this AND that AND those.”

Syntax

{ and: [condition1, condition2, ...] }

Parameters

array

required

Array of rule conditions (minimum 1 condition)

Returns

boolean - true only if all conditions are true

How It Works

✓ true  AND ✓ true  = ✓ true
✓ true  AND ✗ false = ✗ false
✗ false AND ✓ true  = ✗ false
✗ false AND ✗ false = ✗ false

Examples

Basic AND
Access Control
Nested AND
With Rule Helpers

import { createRuleEngine } from 'rule-engine-js';

const engine = createRuleEngine();
const user = {
  age: 28,
  role: 'admin',
  active: true
};

// All three conditions must be true
const rule = {
  and: [
    { gte: ['age', 18] },        // ✓ 28 >= 18
    { eq: ['role', 'admin'] },   // ✓ role is admin
    { eq: ['active', true] }     // ✓ active is true
  ]
};

engine.evaluateExpr(rule, user);
// Result: { success: true, value: true }

// If ANY condition fails, AND fails
const failRule = {
  and: [
    { gte: ['age', 18] },        // ✓ true
    { eq: ['role', 'guest'] }    // ✗ false (role is 'admin', not 'guest')
  ]
};

engine.evaluateExpr(failRule, user);
// Result: { success: true, value: false }

const user = {
  role: 'editor',
  department: 'sales',
  status: 'active',
  yearsOfService: 3
};

// User needs ALL of these to edit sales reports
const canEditSalesReports = {
  and: [
    { eq: ['role', 'editor'] },
    { eq: ['department', 'sales'] },
    { eq: ['status', 'active'] },
    { gte: ['yearsOfService', 2] }
  ]
};

engine.evaluateExpr(canEditSalesReports, user);
// Result: { success: true, value: true }

const order = {
  total: 150,
  paymentStatus: 'paid',
  shippingAddress: 'valid',
  itemsInStock: true
};

// Complex validation with nested AND
const canShipOrder = {
  and: [
    { gte: ['total', 100] },
    { eq: ['paymentStatus', 'paid'] },
    {
      and: [
        { eq: ['shippingAddress', 'valid'] },
        { eq: ['itemsInStock', true] }
      ]
    }
  ]
};

engine.evaluateExpr(canShipOrder, order);
// Result: { success: true, value: true }

import { createRuleHelpers } from 'rule-engine-js';

const rules = createRuleHelpers();
const user = { age: 25, email: 'user@company.com', verified: true };

// Cleaner syntax with helpers
const canAccess = rules.and(
  rules.gte('age', 18),
  rules.contains('email', '@company.com'),
  rules.eq('verified', true)
);

engine.evaluateExpr(canAccess, user);
// Result: { success: true, value: true }

Common Use Cases

User Permissions

// User needs specific role AND active status
const hasPermission = {
  and: [
    { eq: ['role', 'admin'] },
    { eq: ['status', 'active'] },
    { neq: ['banned', true] }
  ]
};

Form Validation

// All fields must be valid
const validForm = {
  and: [
    { isNotNull: ['username'] },
    { regex: ['email', '^[^@]+@[^@]+$'] },
    { gte: ['age', 18] },
    { eq: ['terms', true] }
  ]
};

Price Range

// Price must be within range
const validPrice = {
  and: [
    { gte: ['price', 10] },    // At least $10
    { lte: ['price', 100] }    // At most $100
  ]
};

Short-circuit: AND stops checking as soon as it finds a false condition, making it faster.

`or` - At Least One Must Be True

At least one condition must pass. Like saying “I need this OR that OR those.”

Syntax

{ or: [condition1, condition2, ...] }

Parameters

array

required

Array of rule conditions (minimum 1 condition)

Returns

boolean - true if any condition is true

How It Works

✓ true  OR ✓ true  = ✓ true
✓ true  OR ✗ false = ✓ true
✗ false OR ✓ true  = ✓ true
✗ false OR ✗ false = ✗ false

Examples

Basic OR
Multiple Payment Methods
Nested OR
With Rule Helpers

const user = {
  role: 'editor',
  isOwner: false,
  isModerator: false
};

// User needs at least ONE of these roles
const canEdit = {
  or: [
    { eq: ['role', 'admin'] },      // ✗ false
    { eq: ['role', 'editor'] },     // ✓ true (this one passes!)
    { eq: ['isOwner', true] },      // ✗ false
    { eq: ['isModerator', true] }   // ✗ false
  ]
};

engine.evaluateExpr(canEdit, user);
// Result: { success: true, value: true }

// All conditions must fail for OR to fail
const noAccess = {
  or: [
    { eq: ['role', 'admin'] },      // ✗ false
    { eq: ['isOwner', true] }       // ✗ false
  ]
};

engine.evaluateExpr(noAccess, user);
// Result: { success: true, value: false }

const payment = {
  creditCard: null,
  paypal: 'active',
  bankTransfer: null
};

// Accept any payment method
const hasPaymentMethod = {
  or: [
    { isNotNull: ['creditCard'] },
    { eq: ['paypal', 'active'] },
    { isNotNull: ['bankTransfer'] }
  ]
};

engine.evaluateExpr(hasPaymentMethod, payment);
// Result: { success: true, value: true }

const user = {
  subscription: 'free',
  trialActive: false,
  specialAccess: true
};

// Premium access through any method
const hasPremiumAccess = {
  or: [
    { eq: ['subscription', 'premium'] },
    { eq: ['subscription', 'pro'] },
    {
      or: [
        { eq: ['trialActive', true] },
        { eq: ['specialAccess', true] }
      ]
    }
  ]
};

engine.evaluateExpr(hasPremiumAccess, user);
// Result: { success: true, value: true }

const rules = createRuleHelpers();
const user = { role: 'viewer', vip: true };

// User can access if they have any of these
const canViewContent = rules.or(
  rules.eq('role', 'admin'),
  rules.eq('role', 'editor'),
  rules.eq('vip', true)
);

engine.evaluateExpr(canViewContent, user);
// Result: { success: true, value: true }

Common Use Cases

Role-Based Access

// Grant access to multiple roles
const canAccess = {
  or: [
    { eq: ['role', 'admin'] },
    { eq: ['role', 'moderator'] },
    { eq: ['role', 'editor'] }
  ]
};

Discount Eligibility

// Discount for students OR seniors OR members
const getsDiscount = {
  or: [
    { eq: ['isStudent', true] },
    { gte: ['age', 65] },
    { eq: ['membershipLevel', 'gold'] }
  ]
};

Search Filters

// Match any category
const matchesSearch = {
  or: [
    { contains: ['category', 'electronics'] },
    { contains: ['category', 'computers'] },
    { contains: ['category', 'phones'] }
  ]
};

Short-circuit: OR stops checking as soon as it finds a true condition, making it faster.

`not` - Reverse a Condition

Flips a condition - true becomes false, false becomes true. Like saying “NOT this.”

Syntax

{
  not: [condition];
}

Parameters

object

required

Single rule condition (exactly 1, no more, no less)

Returns

boolean - true if condition is false, false if condition is true

How It Works

NOT ✓ true  = ✗ false
NOT ✗ false = ✓ true

Examples

Basic NOT
Exclude Conditions
Combined with AND/OR
With Rule Helpers

const user = {
  name: 'John',
  banned: false,
  deleted: false
};

// User is NOT banned
const notBanned = {
  not: [
    { eq: ['banned', true] }  // false, so NOT false = true
  ]
};

engine.evaluateExpr(notBanned, user);
// Result: { success: true, value: true }

// User is NOT named Jane
const notJane = {
  not: [
    { eq: ['name', 'Jane'] }  // false, so NOT false = true
  ]
};

engine.evaluateExpr(notJane, user);
// Result: { success: true, value: true }

// User is NOT named John (this fails!)
const notJohn = {
  not: [
    { eq: ['name', 'John'] }  // true, so NOT true = false
  ]
};

engine.evaluateExpr(notJohn, user);
// Result: { success: true, value: false }

const user = {
  role: 'editor',
  email: 'user@company.com'
};

// NOT a guest
const notGuest = {
  not: [
    { eq: ['role', 'guest'] }
  ]
};

engine.evaluateExpr(notGuest, user);
// Result: { success: true, value: true }

// Email does NOT contain 'temp'
const notTempEmail = {
  not: [
    { contains: ['email', 'temp'] }
  ]
};

engine.evaluateExpr(notTempEmail, user);
// Result: { success: true, value: true }

const user = {
  age: 25,
  role: 'member',
  verified: true
};

// Adult (NOT a minor) AND verified
const validUser = {
  and: [
    {
      not: [
        { lt: ['age', 18] }  // NOT under 18
      ]
    },
    { eq: ['verified', true] }
  ]
};

engine.evaluateExpr(validUser, user);
// Result: { success: true, value: true }

// Has access but NOT as admin
const regularAccess = {
  and: [
    { eq: ['verified', true] },
    {
      not: [
        { eq: ['role', 'admin'] }
      ]
    }
  ]
};

engine.evaluateExpr(regularAccess, user);
// Result: { success: true, value: true }

const rules = createRuleHelpers();
const user = { status: 'active', role: 'viewer' };

// Active user who is NOT suspended
const canAccess = rules.and(
  rules.eq('status', 'active'),
  rules.not(
    rules.eq('status', 'suspended')
  )
);

engine.evaluateExpr(canAccess, user);
// Result: { success: true, value: true }

Common Use Cases

Exclude Banned Users

// User is NOT banned or deleted
const activeUser = {
  and: [
    { not: [{ eq: ['banned', true] }] },
    { not: [{ eq: ['deleted', true] }] }
  ]
};

Age Restrictions

// NOT a minor (under 18)
const isAdult = {
  not: [
    { lt: ['age', 18] }
  ]
};

Exclude Categories

// Show all products EXCEPT archived
const visibleProducts = {
  not: [
    { eq: ['status', 'archived'] }
  ]
};

NOT takes exactly one condition. Use { neq: [...] } for simple “not equal” checks.

Combining Operators

Mix AND, OR, and NOT to create complex logic:

Complex Examples

Premium Access
Shipping Eligibility
Content Moderation

const user = {
  subscription: 'basic',
  vipMember: false,
  trialActive: true,
  banned: false
};

// Premium access rules:
// (Premium subscriber OR VIP OR active trial) AND NOT banned
const hasPremiumAccess = {
  and: [
    {
      or: [
        { eq: ['subscription', 'premium'] },
        { eq: ['vipMember', true] },
        { eq: ['trialActive', true] }
      ]
    },
    {
      not: [
        { eq: ['banned', true] }
      ]
    }
  ]
};

engine.evaluateExpr(hasPremiumAccess, user);
// Result: { success: true, value: true }
// ✓ true because trial is active and not banned

const order = {
  total: 75,
  country: 'US',
  hasHazmat: false,
  weight: 5
};

// Can ship if:
// (Total >= $50 OR country is US) AND
// (NOT hazardous materials) AND
// (weight <= 10 lbs)
const canShip = {
  and: [
    {
      or: [
        { gte: ['total', 50] },
        { eq: ['country', 'US'] }
      ]
    },
    {
      not: [
        { eq: ['hasHazmat', true] }
      ]
    },
    { lte: ['weight', 10] }
  ]
};

engine.evaluateExpr(canShip, order);
// Result: { success: true, value: true }

const post = {
  authorRole: 'editor',
  status: 'draft',
  flagCount: 0,
  verified: true
};

// Post can be published if:
// (Admin OR Editor with verified status) AND
// (NOT flagged multiple times) AND
// (status is draft or pending)
const canPublish = {
  and: [
    {
      or: [
        { eq: ['authorRole', 'admin'] },
        {
          and: [
            { eq: ['authorRole', 'editor'] },
            { eq: ['verified', true] }
          ]
        }
      ]
    },
    {
      not: [
        { gte: ['flagCount', 3] }
      ]
    },
    {
      or: [
        { eq: ['status', 'draft'] },
        { eq: ['status', 'pending'] }
      ]
    }
  ]
};

engine.evaluateExpr(canPublish, post);
// Result: { success: true, value: true }

Error Handling

Common Errors

Empty AND/OR Array

// AND/OR need at least one condition
const result = engine.evaluateExpr({ and: [] }, {});

// Returns:
// {
//   success: false,
//   error: "AND operator requires at least one argument"
// }

NOT with Wrong Number of Arguments

// NOT needs exactly one condition
const result = engine.evaluateExpr(
  { not: [] },  // Missing condition
  {}
);

// Returns:
// {
//   success: false,
//   error: "NOT operator requires 1 arguments, got 0"
// }

// Also fails with multiple conditions
const result2 = engine.evaluateExpr(
  { not: [{ eq: ['a', 1] }, { eq: ['b', 2] }] },
  {}
);
// Error: NOT requires exactly 1 argument

Invalid Condition

// Nested condition has an error
const result = engine.evaluateExpr(
  {
    and: [
      { eq: ['valid', true] },
      { invalidOp: ['field'] }  // Unknown operator
    ]
  },
  { valid: true }
);

// Returns:
// {
//   success: false,
//   error: "Unknown operator: invalidOp"
// }

Tips for Debugging

// Break complex rules into smaller pieces
const isAdult = { gte: ['age', 18] };
const isActive = { eq: ['status', 'active'] };
const isPremium = { eq: ['tier', 'premium'] };

// Test each piece separately
console.log(engine.evaluateExpr(isAdult, user));
console.log(engine.evaluateExpr(isActive, user));
console.log(engine.evaluateExpr(isPremium, user));

// Then combine
const rule = {
  and: [isAdult, isActive, isPremium],
};
console.log(engine.evaluateExpr(rule, user));

Quick Reference

Operator Comparison

Operator	Needs	Returns True When	Example
`and`	All conditions true	All pass	User is adult AND verified
`or`	Any condition true	At least one passes	Admin OR moderator
`not`	Condition to reverse	Condition is false	NOT banned

Common Patterns

// Value between min and max
{
  and: [
    { gte: ['price', 10] },
    { lte: ['price', 100] }
  ]
}

// User has any of these roles
{
  or: [{ eq: ['role', 'admin'] }, { eq: ['role', 'editor'] }, { eq: ['role', 'moderator'] }];
}

// Active user (not banned/deleted)
{
  and: [
    { eq: ['status', 'active'] },
    { not: [{ eq: ['banned', true] }] },
    { not: [{ eq: ['deleted', true] }] },
  ];
}

Equality Operators

eq, neq

Numeric Operators

GT, GTE, LT, LTE

Array Operators

in, notIn

String Operators

contains, startsWith, endsWith

Special Operators

isNull, isNotNull, between

All Operators

Complete reference

API Reference

For complete API documentation:

​Overview

and

or

not

​Architecture

​Key Features

​and - All Must Be True

​Syntax

​Parameters

​Returns

​How It Works

​Examples

​Common Use Cases

​or - At Least One Must Be True

​Syntax

​Parameters

​Returns

​How It Works

​Examples

​Common Use Cases

​not - Reverse a Condition

​Syntax

​Parameters

​Returns

​How It Works

​Examples

​Common Use Cases

​Combining Operators

​Complex Examples

​Error Handling

​Common Errors

​Tips for Debugging

​Quick Reference

​Operator Comparison

​Common Patterns

​Related Operators

Equality Operators

Numeric Operators

Array Operators

String Operators

Special Operators

All Operators

​API Reference

Overview

Architecture

Key Features

`and` - All Must Be True

Syntax

Parameters

Returns

How It Works

Examples

Common Use Cases

`or` - At Least One Must Be True

Syntax

Parameters

Returns

How It Works

Examples

Common Use Cases

`not` - Reverse a Condition

Syntax

Parameters

Returns

How It Works

Examples

Common Use Cases

Combining Operators

Complex Examples

Error Handling

Common Errors

Tips for Debugging

Quick Reference

Operator Comparison

Common Patterns

Related Operators

API Reference