@phr3nzy/rulekit
Version:
A powerful and flexible toolkit for building rule-based matching and filtering systems
249 lines (195 loc) • 6.3 kB
Markdown
# 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.
[](https://badge.fury.io/js/@phr3nzy%2Frulekit)
[](https://codecov.io/gh/phr3nzy/rulekit)
[](https://opensource.org/licenses/MIT)
## 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:
```typescript
const engine = new RuleEngine(schema);
const matches = engine.findMatchingFrom(entities, rules);
```
### 2. Data Analyzer
Automatically analyzes your data to suggest appropriate UI components:
```typescript
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:
```typescript
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:
```typescript
const converter = new RuleConverter();
const rule = converter.convertComponentsToRule(components);
```
## Installation
```bash
# 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:
```typescript
// 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
```typescript
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](./examples) for more advanced usage!
## Features
### Type-Safe Schema Definition
```typescript
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
```typescript
const rules: Rule<UserSchema>[] = [
{
or: [
{
attributes: {
role: { eq: 'admin' },
},
},
{
and: [
{
attributes: {
role: { eq: 'user' },
permissions: { in: ['manage_content'] },
},
},
],
},
],
},
];
```
### Array Matching
```typescript
// 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
```typescript
// 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](https://github.com/phr3nzy)