Schedulum Rule Engine

A rule-based employee scheduling engine for Node.js. Supports Time-based, Day-based, and Person-based scheduling constraints with priority ordering.

Designed for deterministic rule execution and clean extensibility.

Features

Time-based rules

must have

at least

at most

Day-based rules

must have

at least

at most

Person-based rules

must have

at least

at most

start with

end with

work with

Frequency support

Specific day ("MONDAY", "TUESDAY", etc.)

"every day"

Availability-aware scheduling

Shift merging support

Deterministic rule execution order

Installation npm install schedulum

Usage const { generateScheduleByRules } = require("schedulum");

const schedule = { employees: [ { employeeId: 1, schedules: [] }, { employeeId: 2, schedules: [] } ] };

const availabilities = { data: [ { employeeId: 1, dayOfWeek: "MONDAY", startTime: "07:00", endTime: "17:00" }, { employeeId: 2, dayOfWeek: "MONDAY", startTime: "07:00", endTime: "17:00" } ] };

const rules = [ { rulesType: "Person-based", condition: "work with", ruleSlot: { type: "employeeId", value: 1 }, conditionSlot: { type: "employeeId", value: 2 }, frequency: "MONDAY" } ];

const result = generateScheduleByRules(schedule, availabilities, rules);

console.log(result);

Rule Structure

Each rule follows this schema:

{ rulesType: "Time-based" | "Day-based" | "Person-based", condition: string, ruleSlot: object, conditionSlot: object, frequency: "every day" | "MONDAY" | ... }

Time-based Rule Example

Ensure at least 3 employees between 07:00–08:00 on Monday:

{ rulesType: "Time-based", condition: "at least", ruleSlot: { startTime: "07:00", endTime: "08:00" }, conditionSlot: { type: "quantity", value: 3 }, frequency: "MONDAY" }

Person-based Rule Examples Start With

Employee 1 starts at the same time as Employee 2:

{ rulesType: "Person-based", condition: "start with", ruleSlot: { type: "employeeId", value: 1 }, conditionSlot: { type: "employeeId", value: 2 }, frequency: "every day" }

End With

Employee 1 ends at the same time as Employee 2.

Work With

Employee 1’s shift exactly matches Employee 2’s shift.

Rule Execution Order

Rules are applied in the following sequence:

Time-based rules

Day-based rules

Person-based rules

This ensures structural constraints are applied before dependency-based alignment rules.

Engine Assumptions

Employees must be available for assigned shifts.

Maximum daily shift length is enforced (default 8 hours if implemented).

Shifts are merged when overlapping.

Rules are processed in defined priority order (Rule #1 highest).

Project Structure (Suggested) /src ├── timeBasedRules.js ├── dayBasedRules.js ├── personBasedRules.js ├── utils.js └── index.js

Extending the Engine

To add a new rule:

Implement it inside the appropriate rules file.

Register it in the rule dispatcher.

Define a new condition string.

The dispatcher uses rulesType and condition to route execution.

License

MIT