phr3nzy
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 components3. 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/rulekitExports 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';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
License
MIT © phr3nzy