Package Exports

@timkit/conditions
@timkit/conditions/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@timkit/conditions) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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: 'john.doe@example.com',
  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