README.md

RuleKit 🎯

A powerful and flexible toolkit for building intelligent filtering, matching, and rule-based systems. RuleKit combines high-performance rule evaluation with smart interface generation and data analysis.

What is RuleKit?

RuleKit is a comprehensive toolkit that helps you build sophisticated filtering and matching systems. It's perfect for:

• 🛍️ E-commerce Filtering: Create smart product filters with automatic UI generation
• 🤝 Entity Matching: Match entities based on complex rule combinations
• 📊 Data Analysis: Automatically analyze data to suggest appropriate UI components
• 🎨 Interface Generation: Build dynamic interfaces based on data characteristics
• 🔍 Smart Search: Implement advanced search with type-safe rules
• 🎯 Business Rules: Define and evaluate complex business rules

Core Features

• 🎯 Type-Safe: Full TypeScript support with generic type inference
• 🚀 High Performance: 47K+ ops/sec for real-world scenarios
• 🔍 Smart Analysis: Automatic data analysis and component suggestion
• 🎨 Interface Agnostic: Flexible component system for any UI framework
• 📦 Zero Dependencies: Lightweight and efficient
• 🔒 Validation: Built-in schema validation
• 🔄 Batch Processing: Optimized for large datasets
• 📚 Well Documented: Clean, documented exports with proper versioning

Key Components

1. Rule Engine

The core engine that evaluates rules against entities with high performance:

const engine = new RuleEngine(schema);
const matches = engine.findMatchingFrom(entities, rules);

2. Data Analyzer

Automatically analyzes your data to suggest appropriate UI components:

const analyzer = new DataAnalyzer();
const analysis = analyzer.analyze(data);
// Get insights like data types, statistics, and suggested components

3. Interface Components

Type-safe, framework-agnostic components that can be used with any UI:

const component = {
	type: ComponentType.RANGE,
	identifier: 'price',
	value: 500,
	constraints: {
		min: 0,
		max: 1000,
		step: 1,
	},
};

4. Rule Converter

Convert UI components to rules and vice versa:

const converter = new RuleConverter();
const rule = converter.convertComponentsToRule(components);

Installation

# Using npm
npm install @phr3nzy/rulekit

# Using yarn
yarn add @phr3nzy/rulekit

# Using pnpm
pnpm add @phr3nzy/rulekit

Exports Overview

RuleKit provides a well-organized export structure:

// Core functionality
import { RuleEngine, AttributeType } from '@phr3nzy/rulekit';
import type { Entity, Rule, RuleSet } from '@phr3nzy/rulekit';

// Interface-agnostic components
import { ComponentType, InterfaceOperators } from '@phr3nzy/rulekit';
import type { Component, ComponentConstraints } from '@phr3nzy/rulekit';

// Data analysis
import { Analyzer, type DataStatistics } from '@phr3nzy/rulekit';

// Legacy v2 functionality (if needed)
import { v2 } from '@phr3nzy/rulekit';

Quick Start

import { AttributeType, RuleEngine, DataAnalyzer, RuleConverter } from '@phr3nzy/rulekit';

// 1. Define your data
const products = [
	{
		id: '1',
		name: 'Gaming Laptop',
		attributes: {
			category: 'electronics',
			price: 1299,
			tags: ['gaming', 'premium'],
			__validated: true,
		},
	},
	// ... more products
];

// 2. Analyze data to get smart component suggestions
const analyzer = new DataAnalyzer();
const analysis = analyzer.analyze(products.map(p => p.attributes));

// 3. Create type-safe components based on analysis
const priceAnalysis = analysis.price;
const component = {
	type: priceAnalysis.suggestedComponent.type, // RANGE
	identifier: 'price',
	value: 500,
	constraints: {
		min: priceAnalysis.statistics.numeric.min,
		max: priceAnalysis.statistics.numeric.max,
	},
};

// 4. Convert components to rules
const converter = new RuleConverter();
const rule = converter.convertComponentsToRule([{ field: 'price', component }]);

// 5. Find matches using the rule engine
const engine = new RuleEngine();
const matches = engine.findMatchingFrom(products, [rule]);

Check out our examples for more advanced usage!

Features

Type-Safe Schema Definition

import { AttributeType } from '@phr3nzy/rulekit';

type UserSchema = {
	role: {
		type: typeof AttributeType.ENUM;
		validation: {
			type: typeof AttributeType.ENUM;
			required: true;
			enum: ['admin', 'user', 'guest'];
		};
	};
	permissions: {
		type: typeof AttributeType.ARRAY;
		validation: {
			type: typeof AttributeType.ARRAY;
			arrayType: typeof AttributeType.STRING;
			required: true;
		};
	};
} & AttributeSchema;

Complex Rule Combinations

const rules: Rule<UserSchema>[] = [
	{
		or: [
			{
				attributes: {
					role: { eq: 'admin' },
				},
			},
			{
				and: [
					{
						attributes: {
							role: { eq: 'user' },
							permissions: { in: ['manage_content'] },
						},
					},
				],
			},
		],
	},
];

Array Matching

// Match if any array element matches
const rule = {
	attributes: {
		tags: { in: ['featured', 'new'] }, // Matches if tags contains any of these
	},
};

// Match specific array elements
const rule2 = {
	attributes: {
		permissions: { in: ['admin_panel'] }, // For array fields
		role: { eq: 'admin' }, // For non-array fields
	},
};

Batch Processing

// Engine automatically optimizes batch size based on rule complexity
const engine = new RuleEngine(schema, {
	maxBatchSize: 1000, // Optional: customize batch size
});

// Process large datasets efficiently
const matches = engine.findMatchingFrom(largeEntityList, rules);

Performance

• Real-world entity matching (100 entities): 47,603 ops/sec
• Simple rules (1000 entities): 936 ops/sec
• Complex rules (1000 entities): 260 ops/sec
• Large dataset (10000 entities): 87 ops/sec

Migration from v2

See the CHANGELOG.md for detailed migration guide.

License

MIT © phr3nzy