conditions

A flexible and powerful condition checker for TypeScript that allows evaluating complex conditions against objects.

Installation

Install the package using npm:

npm install @timkit/conditions

Or using yarn:

yarn add @timkit/conditions

Usage

import { checkConditions } from '@timkit/conditions';

const user = {
  name: 'John Doe',
  age: 30,
  email: '[email protected]',
  address: {
    city: 'New York',
    state: 'NY'
  },
  tags: ['developer', 'javascript', 'typescript'],
  active: true
};

// Simple condition
const isUser30YearsOld = checkConditions(user, ['age == 30']); // true

// Negated condition
const isUserNot40YearsOld = checkConditions(user, ['age != 40']); // true 
const isUserNotJane = checkConditions(user, ['name !contains Jane']); // true

// Multiple conditions with OR logic (default)
const isActiveOrOver25 = checkConditions(user, [
  'active == true',
  'age > 25'
]); // true (both conditions are true)

// AND conditions (nested array)
const isActiveAndOver25 = checkConditions(user, [
  ['active == true', 'age > 25']
]); // true (both conditions are true)

// Complex nested conditions (AND and OR combined)
// (active == true AND age > 25) OR (name contains Smith AND city == Chicago)
const complexCondition = checkConditions(user, [
  ['active == true', 'age > 25'],
  ['name contains Smith', 'address.city == Chicago']
]); // true (first condition group is true)

Supported Operators

| Operator | Description | Example | |----------|-------------|---------| | = | Equality | 'age = 30' | | == | Equality | 'age == 30' | | > | Greater than | 'age > 25' | | < | Less than | 'age < 35' | | >= | Greater than or equal | 'age >= 30' | | <= | Less than or equal | 'age <= 30' | | contains | String contains or array includes | 'name contains John', 'tags contains typescript' | | matches | String matches regex pattern | 'email matches .*@example\\.com' | | in | Value is in list | 'age in (25, 30, 35)' | | isBlank | Field is empty, null, or undefined | 'address.zipcode isBlank' | | isEmail | Field is a valid email address | 'email isEmail' | | isUrl | Field is a valid URL | 'website isUrl' | | isBool | Field is a boolean | 'active isBool' | | isNumber | Field is a number | 'age isNumber' | | isInteger | Field is an integer | 'count isInteger' | | isFloat | Field is a floating-point number | 'price isFloat' | | isDate | Field is a valid date | 'birthdate isDate' | | isTime | Field is a valid time (HH:MM, HH:MM:SS) | 'meetingTime isTime' | | isDateTime | Field is a valid date and time | 'createdAt isDateTime' | | isRequired | Field is not empty, null, or undefined | 'name isRequired' | | isBetween | Number is between min and max (inclusive) | 'age isBetween 25, 30' | | startsWith | String starts with a substring | 'name startsWith John' | | endsWith | String ends with a substring | 'email endsWith example.com' | | isArray | Field is an array | 'tags isArray' | | isObject | Field is an object | 'address isObject' | | is | Combined validation (see below) | 'age is required|number|min:18|max:100' | | !operator | Negation of most operators | 'name !contains Smith', 'age !in (40, 50)', 'email !isEmail' |

Negating Conditions

You can negate most operators by prefixing them with an exclamation mark (!). This reverses the result of the operator.

const user = { name: 'John Doe', age: 30, tags: ['a', 'b'], emptyField: '' };

// Standard contains
checkConditions(user, ['name contains John']); // true
// Negated contains
checkConditions(user, ['name !contains Jane']); // true

// Standard isBlank
checkConditions(user, ['emptyField isBlank']); // true
// Negated isBlank
checkConditions(user, ['name !isBlank']); // true

// Negation with lists
checkConditions(user, ['age !in (40, 50, 60)']); // true
checkConditions(user, ['age !in (20, 30, 40)']); // false

// Negation with type checks
checkConditions(user, ['name !isNumber']); // true
checkConditions(user, ['age !isNumber']); // false

// Negation works within AND/OR blocks
// (name !contains Jane) AND (age == 30)
checkConditions(user, [['name !contains Jane', 'age == 30']]); // true

Combined Validation with 'is' operator

The is operator allows you to apply multiple validation rules to a field in a single condition. Rules are separated by the pipe character (|).

// Check if age is required, a number, minimum 18, and maximum 100
checkConditions(user, ['age is required|number|min:18|max:100']);

// Check if email is required and a valid email format
checkConditions(user, ['email is required|email']);

// Check if a string has specific length constraints
checkConditions(user, ['username is required|string|minLength:3|maxLength:20']);

Supported Validations in 'is' operator

| Validation | Description | Example | |------------|-------------|---------| | required | Field is not empty, null, or undefined | required | | string | Field is a string | string | | number | Field is a number | number | | integer | Field is an integer | integer | | float | Field is a floating-point number | float | | bool | Field is a boolean | bool | | email | Field is a valid email | email | | url | Field is a valid URL | url | | date | Field is a valid date | date | | time | Field is a valid time | time | | dateTime | Field is a valid date and time | dateTime | | array | Field is an array | array | | object | Field is an object | object | | min:value | Number is greater than or equal to value | min:18 | | max:value | Number is less than or equal to value | max:100 | | minLength:value | String or array has minimum length | minLength:5 | | maxLength:value | String or array has maximum length | maxLength:20 | | pattern:regex | String matches regex pattern | pattern:^[a-z0-9_]+$ | | startsWith:value | String starts with substring | startsWith:http | | endsWith:value | String ends with substring | endsWith:.com | | contains:value | String contains substring | contains:example |

Logic Operations

• OR Logic: By default, top-level conditions are combined with OR logic

  // name == John OR age == 30
  ['name == John', 'age == 30']

• AND Logic: Nest conditions in an array for AND logic

  // name == John AND age == 30
  [['name == John', 'age == 30']]

• Complex Logic: Combine AND and OR

  // (name == John AND age == 30) OR (email contains example AND active == true)
  [
    ['name == John', 'age == 30'],
    ['email contains example', 'active == true']
  ]

Accessing Nested Properties

You can access nested properties using dot notation:

// Check a nested property
checkConditions(user, ['address.city == New York']); // true

Running Tests

npm test