@timkit/conditions

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: '[e-mail]',
  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
!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