### Create Root Union

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Initializes the rules engine by creating a root union. This is the starting point for defining your rule structure. It accepts a connector type ('and' or 'or').

```typescript
import { createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
```

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

### Rules Engine State Example

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Illustrates the JSON structure representing the state of the rules engine after various operations, including creating a root, adding rules, and adding unions.

```json
{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": []
}
```

```json
{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "82e96b0d-886e-4a2e-bf8c-f81b02ef11ce",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "type": "number",
      "field": "age",
      "operator": "greater_than",
      "value": 18
    }
  ]
}
```

```json
{
  "entity": "root_union",
  "id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "50158f7e-1d87-4ca8-aaca-ef1bbb41c9c2",
      "parent_id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "bob",
      "ignore_case": true
    },
    {
      "entity": "rule",
      "id": "5f6ac1d1-7ce7-40a5-a94c-5e4a47a45e28",
      "parent_id": "61dadd25-22a0-4e84-abe5-92fcfd6cac9e",
      "type": "string",
      "field": "name",
      "operator": "equals_to",
      "value": "alice",
      "ignore_case": true
    }
  ]
}
```

```json
{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "7c493486-409b-48df-bd66-7f4a16500c5e",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3abc4e64-d6c8-4303-9d07-b573a571f19a",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "a3995445-55ca-49b2-8381-3d6758750413",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}
```

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

### Basic Rules Engine Configuration and Execution

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Demonstrates how to initialize a rules engine, add rules and nested unions, and execute the engine with sample data. This example showcases the core functionality of the rules-engine-ts library.

```javascript
import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot, run } from 'rules-engine-ts';

// Create root union
const root = createRoot({ connector: 'and' });

// Add a rule to the root union
addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

// Add a union to the root union (creates a nested ruleset)
const union = addUnionToUnion(root, { connector: 'or' });

// Add nested rules to the nested union
addRulesToUnion(union, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);

// Run the rules engine
const pass = run(root, { age: 19, name: 'Bob' });
const fail = run(root, { age: 19, name: 'Carol' });

console.log(pass); // true
console.log(fail); // false
```

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

### Example Rule Engine State Structure

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Illustrates the internal JSON structure representing the rules engine's state, including nested unions and individual rules with their properties and operators.

```json
{
  "entity": "root_union",
  "id": "0d7428af-10e4-481b-84a7-056946bd4f12",
  "connector": "and",
  "rules": [
    {
      "entity": "rule",
      "id": "82e96b0d-886e-4a2e-bf8c-f81b02ef11ce",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "type": "number",
      "field": "age",
      "operator": "greater_than",
      "value": 18
    },
    {
      "entity": "union",
      "id": "7c493486-409b-48df-bd66-7f4a16500c5e",
      "parent_id": "0d7428af-10e4-481b-84a7-056946bd4f12",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3abc4e64-d6c8-4303-9d07-b573a571f19a",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "a3995445-55ca-49b2-8381-3d6758750413",
          "parent_id": "7c493486-409b-48df-bd66-7f4a16500c5e",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}
```

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

### Pre-composing Unions with Type Annotations

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Illustrates how to pre-compose a union of rules using the `NewUnion` type before adding it to the rules engine. This example shows dynamic connector assignment ('and' or 'or') based on a condition.

```TypeScript
import { NewUnion, addUnionToUnion, createRoot } from 'rules-engine-ts';

const userSelectsAnd = false;

const root = createRoot({ connector: 'and' });
const union: NewUnion = { connector: userSelectsAnd ? 'and' : 'or' };

const unionAfterAdding = addUnionToUnion(root, union);
console.log(unionAfterAdding);
```

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

### Add Multiple Unions to a Union (TypeScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Demonstrates how to add multiple unions to a parent union or root union using the `addUnionsToUnion` function. It shows the import, creation of a root, adding two 'or' unions, and then adding rules to each of these new unions. The example also includes the resulting JSON state of the rules engine.

```typescript
import { addRulesToUnion, addUnionsToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const unions = addUnionsToUnion(root, [{ connector: 'or' }, { connector: 'or' }]);
addRulesToUnion(unions[0], [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);
addRulesToUnion(unions[1], [
  { type: 'number', field: 'age', value: 18, operator: 'equals_to' },
  { type: 'number', field: 'age', value: 21, operator: 'equals_to' },
]);
```

```json
{
  "entity": "root_union",
  "id": "28a9ae06-594a-4520-8d73-2fd871804634",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
      "parent_id": "28a9ae06-594a-4520-8d73-2fd871804634",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "a8ecbafd-0a1a-4e9e-bb70-8bd11a62f274",
          "parent_id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "d4fd56bf-af82-4382-a1cb-93d80cb87ef4",
          "parent_id": "8e5e66dd-e86c-4f9e-acc7-7baa852fdfe8",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    },
    {
      "entity": "union",
      "id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
      "parent_id": "28a9ae06-594a-4520-8d73-2fd871804634",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "7ea03690-d9c4-4a3e-97eb-d927cf6845e8",
          "parent_id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
          "type": "number",
          "field": "age",
          "operator": "equals_to",
          "value": 18
        },
        {
          "entity": "rule",
          "id": "bb63d7da-b0dc-4d00-824c-4de09151c609",
          "parent_id": "5e5d7f00-d0f6-40d9-84b3-39600241a92f",
          "type": "number",
          "field": "age",
          "operator": "equals_to",
          "value": 21
        }
      ]
    }
  ]
}
```

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

### Rule Types and Operators in Rules Engine TS

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

This snippet outlines the different types of rules supported by Rules Engine TS and the operators available for each type. For example, 'string' type rules support operators like 'equals_to', 'contains', 'starts_with', and 'ends_with'.

```typescript
/**
 * Represents the different types of rules that can be evaluated.
 */
export enum RuleType {
  string = 'string',
  number = 'number',
  boolean = 'boolean',
  array_value = 'array_value',
  array_length = 'array_length',
  object_key = 'object_key',
  object_value = 'object_value',
  object_key_value = 'object_key_value',
  generic_comparison = 'generic_comparison',
  generic_type = 'generic_type',
}

/**
 * Defines the operators available for string type rules.
 */
export enum StringOperator {
  equals_to = 'equals_to',
  does_not_equal_to = 'does_not_equal_to',
  contains = 'contains',
  not_contains = 'not_contains',
  starts_with = 'starts_with',
  ends_with = 'ends_with',
}

// Other operator enums for number, boolean, etc. would follow a similar pattern.
```

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

### Add Rule or Union to a Union (TypeScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Illustrates how to add a single rule or union to an existing union or root union using the `addAnyToUnion` function. The example shows importing the function, creating a root, adding a new union, and then adding rules to that newly created union. The corresponding JSON state of the rules engine is also provided.

```typescript
import { addAnyToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const any = addAnyToUnion(root, { connector: 'or' });
if (any.entity === 'union') {
  addAnyToUnion(any, { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true });
  addAnyToUnion(any, { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true });
}
```

```json
{
  "entity": "root_union",
  "id": "825ef3d8-3151-4367-b751-1deae8b308c1",
  "connector": "and",
  "rules": [
    {
      "entity": "union",
      "id": "71b5296a-5358-4399-878d-f535c9f21faf",
      "parent_id": "825ef3d8-3151-4367-b751-1deae8b308c1",
      "connector": "or",
      "rules": [
        {
          "entity": "rule",
          "id": "3cd0463f-c5e7-4dd9-98b8-9e7cf79417b5",
          "parent_id": "71b5296a-5358-4399-878d-f535c9f21faf",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "f10e7cec-c737-4c2c-b137-d7ab0e26e045",
          "parent_id": "71b5296a-5358-4399-878d-f535c9f21faf",
          "type": "string",
          "field": "name",
          "operator": "equals_to",
          "value": "alice",
          "ignore_case": true
        }
      ]
    }
  ]
}
```

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

### Retrieving and Running Persisted Rules

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Shows how to load previously saved rules from a data source and execute them against a given data object using the rules engine.

```javascript
import { run } from 'rules-engine-ts';

const rules = getRulesFromDatabase();

const pass = run(rules, { user_display_name: 'alice', total_challenges: 0 });
const fail = run(rules, { user_display_name: 'bob', total_challenges: 0 });

if (pass) {
  // do something
}

if (fail) {
  //do somehting else
}
```

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

### Pre-composing Rules with Type Annotations

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Demonstrates how to create and add rules with specific type annotations (NewRule and NewNumberRule) to a rules engine. It shows the process of creating a root, defining rules with type safety, and adding them to the engine's union structure.

```TypeScript
import { NewNumberRule, NewRule, addRuleToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const wideTypingRule: NewRule = { type: 'number', field: 'age', operator: 'greater_than', value: 18 };
const narrowTypingRule: NewNumberRule = { type: 'number', field: 'age', operator: 'less_than', value: 30 };

const wideAfterAdding = addRuleToUnion(root, wideTypingRule);
const narrowAfterAdding = addRuleToUnion(root, narrowTypingRule);

console.log(wideAfterAdding);
console.log(narrowAfterAdding);
```

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

### Persisted Rules JSON Structure for UI Implementation

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Demonstrates a JSON structure for rules that can be persisted in a database, suitable for UI implementation and later retrieval for execution by the rules engine.

```json
{
  "entity": "root_union",
  "id": "598444ae-032c-4ae5-85da-644cf90ab920",
  "connector": "or",
  "rules": [
    {
      "entity": "rule",
      "id": "03fcb9b5-a3fe-4d63-97f3-dfce431c331d",
      "parent_id": "598444ae-032c-4ae5-85da-644cf90ab920",
      "type": "string",
      "field": "user_display_name",
      "operator": "equals_to",
      "value": "Alice",
      "ignore_case": true
    },
    {
      "id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
      "entity": "union",
      "connector": "and",
      "parent_id": "598444ae-032c-4ae5-85da-644cf90ab920",
      "rules": [
        {
          "entity": "rule",
          "id": "1821d9da-9f37-4689-a118-bf436ca37e89",
          "parent_id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
          "type": "string",
          "field": "user_display_name",
          "operator": "equals_to",
          "value": "Bob",
          "ignore_case": true
        },
        {
          "entity": "rule",
          "id": "c2a058ab-6005-44a4-94ae-b75736dce536",
          "parent_id": "d60639aa-8239-40c7-9cc3-ec89f8f8c58d",
          "type": "number",
          "field": "total_challenges",
          "operator": "greater_than_or_equal_to",
          "value": 5
        }
      ]
    }
  ]
}
```

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

### String Rule Specification

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Defines the properties for a rule where the value type is a string. Includes operators for comparison and an option to ignore case.

```apidoc
type = 'string'
field: string
operator: 'equals_to' | 'does_not_equal_to' | 'contains' | 'does_not_contain' | 'starts_with' | 'ends_with'
value: string
ignore_case?: boolean
```

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

### Union and Rule Structure in Rules Engine TS

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

This snippet illustrates the structure of a 'Union' in Rules Engine TS, which can contain multiple rules or other unions. It highlights the use of a 'connector' ('and' or 'or') to define the logical relationship between its elements.

```typescript
/**
 * Represents a logical grouping of rules or other unions.
 */
export interface Union {
  id: string;
  parentId?: string;
  connector: 'and' | 'or';
  rules: (Rule | Union)[];
}

/**
 * Represents a single rule to be evaluated.
 */
export interface Rule {
  id: string;
  parentId?: string;
  type: RuleType;
  operator: string; // Specific operator depends on RuleType
  value: any;
}

// Example of a root union structure:
interface RootUnion extends Union {
  parentId: undefined; // Root union has no parent
}

// Example usage:
const myRule: Rule = {
  id: 'rule-1',
  type: RuleType.string,
  operator: StringOperator.contains,
  value: 'example',
};

const myUnion: Union = {
  id: 'union-1',
  connector: 'and',
  rules: [myRule],
};

const rootUnion: RootUnion = {
  id: 'root-union',
  connector: 'or',
  rules: [myUnion],
};
```

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

### Number Rule Specification

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Defines the properties for a rule where the value type is a number. Includes various comparison operators.

```apidoc
type = 'number'
field: string
operator: 'equals_to' | 'does_not_equal_to' | 'greater_than' | 'greater_than_or_equal_to' | 'less_than' | 'less_than_or_equal_to'
value: number
```

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

### JSON Representation of Another Number Rule

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Shows the JSON structure for another 'number' type rule, similar to the previous one but with a different value and operator. This illustrates the flexibility in defining rule conditions.

```JSON
{
  "entity": "rule",
  "id": "46a36441-3f28-4dd7-8420-b1d584527a74",
  "parent_id": "6fa1aaa6-cfab-4647-a30c-a58af3e0a4d4",
  "type": "number",
  "field": "age",
  "operator": "less_than",
  "value": 30
}
```

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

### Run Rules Engine Evaluation (JavaScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Evaluates a set of rules against a given value. The value can be of any type. The function returns a boolean indicating whether the value passes the rules.

```javascript
import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot, run } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

const union = addUnionToUnion(root, { connector: 'or' });
addRulesToUnion(union, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);

const pass = run(root, { age: 19, name: 'Bob' });
const fail = run(root, { age: 19, name: 'Carol' });

console.log(pass); // true
console.log(fail); // false
```

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

### Generic Comparison

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Performs generic comparisons between a field and a value using various operators. Supports nested properties and array indexing.

```APIDOC
type = 'generic_comparison'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins[0].unknown_property`.
  operator: 'equals_to' | 'does_not_equal_to' | 'greater_than' | 'greater_than_or_equal_to' | 'less_than' | 'less_than_or_equal_to'
    - The operator to use.
  value: any
    - The value to compare against.
```

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

### JSON Representation of a Union

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Presents the JSON structure for a 'union' entity, including its ID, parent ID, connector type, and an empty array for rules. This represents a composite rule structure within the engine.

```JSON
{
  "entity": "union",
  "id": "d2ce2a4e-ec53-4a64-9677-e9051c634bd1",
  "parent_id": "8b32fdc4-8e92-424f-9c00-1204838759e0",
  "connector": "or",
  "rules": []
}
```

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

### Add Many Rules/Unions to Union (JavaScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Adds multiple rules or unions to an existing union or root union. This function mutates the input union. It returns the list of rules or unions that were added.

```javascript
import { addManyToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addManyToUnion(root, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
  { connector: 'or' },
]);
```

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

### Find Any Rule or Union by ID (JavaScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Searches for any rule or union within the rules engine structure using its unique ID. Returns the found item or undefined if not present.

```javascript
import { addRuleToUnion, addUnionToUnion, createRoot, findAnyById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundRule = findAnyById(root, rule.id);
console.log(foundRule === rule); // true

const foundUnion = findAnyById(root, union.id);
console.log(foundUnion === union); // true
```

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

### Generic Type Checking

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Checks the type or truthiness of a field. Supports a wide range of type checks and truthiness evaluations, including null, undefined, string, number, boolean, array, and object.

```APIDOC
type = 'generic_type'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins[0].unknown_property`.
  operator: 'is_truthy' | 'is_falsey' | 'is_null' | 'is_not_null' | 'is_undefined' | 'is_not_undefined' | 'is_string' | 'is_not_string' | 'is_number' | 'is_not_number' | 'is_boolean' | 'is_not_boolean' | 'is_array' | 'is_not_array' | 'is_object' | 'is_not_object'
    - The operator to use.
  value: any
    - The value to compare against.
```

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

### Find Rule by ID (JavaScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Searches for a specific rule within the rules engine structure using its unique ID. Returns the rule if found, otherwise returns undefined.

```javascript
import { addRuleToUnion, addUnionToUnion, createRoot, findRuleById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundRule = findRuleById(root, rule.id);
console.log(foundRule === rule); // true

const foundUnion = findRuleById(root, union.id);
console.log(foundUnion); // undefined
```

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

### JSON Representation of a Number Rule

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Provides the JSON structure for a 'number' type rule, specifying its entity, ID, parent ID, field, operator, and value. This format is used internally by the rules engine.

```JSON
{
  "entity": "rule",
  "id": "560f4e04-f786-4269-bbdd-704ad9793518",
  "parent_id": "6fa1aaa6-cfab-4647-a30c-a58af3e0a4d4",
  "type": "number",
  "field": "age",
  "operator": "greater_than",
  "value": 18
}
```

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

### Add Multiple Rules to Union

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Adds an array of rules to a specified union or the root union. Each rule receives a unique ID and a parent ID. This function mutates the parent union.

```typescript
import { addRulesToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addRulesToUnion(root, [
  { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true },
  { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true },
]);
```

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

### Find Union by ID (JavaScript)

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Searches for a specific union within the rules engine structure using its unique ID. Returns the union if found, otherwise returns undefined.

```javascript
import { addRuleToUnion, addUnionToUnion, createRoot, findUnionById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
const union = addUnionToUnion(root, { connector: 'or' });

const foundUnion = findUnionById(root, union.id);
console.log(foundUnion === union); // true;

const foundRule = findUnionById(root, rule.id);
console.log(foundRule); // undefined;
```

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

### Object Key-Value Comparison

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Evaluates if a specific key-value pair exists within an object, supporting nested properties. The operator can be 'contains' or 'does_not_contain'.

```APIDOC
type = 'object_key_value'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins`.
  operator: 'contains' | 'does_not_contain'
    - The operator to use.
  value: { key: string, value: any }
    - The value to compare against.
```

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

### Validate Ruleset Structure

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Validates the structure of a ruleset. Returns an object indicating validity and a reason for invalidity if applicable. This function is crucial for ensuring the integrity of your rulesets before execution.

```javascript
import { addRuleToUnion, createRoot, validate } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(validate(root));
// { isValid: true }

rule.type = 'string';

console.log(validate(root));
// {
//   isValid: false,
//   reason: 'Code: invalid_union ~ Path: rules[0] ~ Message: Invalid input'
// }
```

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

### Normalize Ruleset

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Normalizes a ruleset to ensure consistency. It removes invalid rules, empty unions, promotes single-rule unions, and updates parent IDs. This function mutates the input union, so cloning is recommended if the original state needs to be preserved.

```typescript
import { addRuleToUnion, addUnionToUnion, createRoot, normalize } from 'rules-engine-ts';

import { v4 as uuidv4 } from 'uuid';

const root = createRoot({ connector: 'or' });

const rule1 = addRuleToUnion(root, { field: 'name', operator: 'contains', type: 'string', value: 'bob' });
const union = addUnionToUnion(root, { connector: 'and' });
const rule2 = addRuleToUnion(union, { field: 'name', operator: 'contains', type: 'string', value: 'alice' });

rule1.parent_id = uuidv4();
rule2.type = 'number';
// @ts-expect-error
union.connector = 'invalid';

console.log(root); // Before normalization
normalize(root, {
  // Normalization options (optional)
  promote_single_rule_unions: true,
  remove_empty_unions: true,
  remove_failed_validations: true,
  update_parent_ids: true,
});
console.log(root); // After normalization
```

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

### Boolean Condition Type

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Evaluates boolean fields using 'is_true' or 'is_false' operators. Supports checking nested properties.

```APIDOC
BooleanCondition:
  type: 'boolean'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins[0].is_active`.
  operator: 'is_true' | 'is_false'
    - The operator to use.
```

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

### Object Key Condition Type

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Checks if an object field contains a specific key. Supports 'contains' and 'does_not_contain' operators.

```APIDOC
ObjectKeyCondition:
  type: 'object_key'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins[0]`.
  operator: 'contains' | 'does_not_contain'
    - The operator to use.
  value: string
    - The value to compare against.
```

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

### Array Length Condition Type

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Evaluates the length of an array field against a specified number. Supports comparison operators like 'equals_to', 'greater_than', etc.

```APIDOC
ArrayLengthCondition:
  type: 'array_length'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins`.
  operator: 'equals_to' | 'does_not_equal_to' | 'greater_than' | 'greater_than_or_equal_to' | 'less_than' | 'less_than_or_equal_to'
    - The operator to use.
  value: number
    - The value to compare against.
```

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

### Add Union to Union

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Nests a new union within an existing union or the root union. This allows for creating complex, hierarchical rule structures. The function mutates the parent union.

```typescript
import { addRuleToUnion, addRulesToUnion, addUnionToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

const union = addUnionToUnion(root, { connector: 'or' });
addRuleToUnion(union, { type: 'string', field: 'name', value: 'bob', operator: 'equals_to', ignore_case: true });
addRuleToUnion(union, { type: 'string', field: 'name', value: 'alice', operator: 'equals_to', ignore_case: true });
```

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

### Add Rule to Union

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Adds a single rule to a specified union or the root union. The function automatically assigns a unique ID and a parent ID to the new rule. It mutates the parent union.

```typescript
import { addRuleToUnion, createRoot } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });

addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });
```

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

### Update Rule by ID

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Updates a specific rule within a ruleset identified by its ID. The function returns the updated rule if found, otherwise undefined. Similar to normalization, this function mutates the input, so consider cloning for state preservation.

```javascript
import { addRuleToUnion, createRoot, updateRuleById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const rule = addRuleToUnion(root, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(root.rules[0]); // Before update
updateRuleById(root, rule.id, { type: 'number', field: 'age', operator: 'less_than', value: 30 });
console.log(root.rules[0]); // After update
```

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

### Object Value Condition Type

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Evaluates the values within an object field. Supports 'contains' and 'does_not_contain' operators for checking against any value type.

```APIDOC
ObjectValueCondition:
  type: 'object_value'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins`.
  operator: 'contains' | 'does_not_contain'
    - The operator to use.
  value: any
    - The value to compare against.
```

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

### Array Value Condition Type

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Checks for the presence or absence of values within an array field. Supports 'contains', 'does_not_contain', and 'contains_all' operators.

```APIDOC
ArrayValueCondition:
  type: 'array_value'
  field: string
    - The field to check. Supports nested properties, e.g. `users.admins`.
  operator: 'contains' | 'does_not_contain' | 'contains_all'
    - The operator to use.
  value: any
    - The value to compare against.
```

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

### Remove All by ID

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Removes all rules and unions matching a given ID from a ruleset. This function mutates the original ruleset object. It returns the modified ruleset.

```javascript
import { addRuleToUnion, addUnionToUnion, createRoot, removeAllById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const union = addUnionToUnion(root, { connector: 'or' });
const rule = addRuleToUnion(union, { type: 'number', field: 'age', operator: 'greater_than', value: 18 });

console.log(union.rules.length); // 1
removeAllById(root, rule.id);
console.log(union.rules.length); // 0
```

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

### Update Union by ID

Source: https://github.com/andrewvo89/rules-engine-ts/blob/main/README.md

Updates a union within the rules engine by its ID. This function mutates the original union object. It returns the updated union if found, otherwise undefined.

```javascript
import { addUnionToUnion, createRoot, updateUnionById } from 'rules-engine-ts';

const root = createRoot({ connector: 'and' });
const union = addUnionToUnion(root, { connector: 'and' });

console.log(root.rules[0]); // Before update
updateUnionById(root, union.id, { connector: 'or' });
console.log(root.rules[0]); // After update
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.