Schedulejs

A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using Zod.

• Generic: Model teachers, rooms, classes, or any resource as abstract types.
• Validates: Prevents resource double-booking and assignment of items (e.g., subjects) to forbidden slots.
• Supports timeslots: Prevents overlap based on start/end Unix timestamps.

📦 Installation

npm install @besrabasant/schedulejs

🚦 Concepts & Mapping

| Library Term | School Example | Typical Meaning | | ------------ | --------------- | ---------------------- | | Resource | Teacher | Who/what is scheduled | | Item | Subject/Course | What to schedule | | Slot | Period/Timeslot | When to schedule | | Assignment | Schedule entry | One scheduled instance |

📝 Usage Example (School Timetable)

import {
  Resource, Item, Slot, Assignment,
  validateEntities, generateSchedule, validateAssignments,
} from "@besrabasant/schedulejs";

// 1. Define your actors (teachers/resources, subjects/items, periods/slots)
const teachers: Resource[] = [
  { id: "T1", name: "Mr. Sharma" },
  { id: "T2", name: "Ms. Verma" }
];

const subjects: Item[] = [
  { id: "MATH", name: "Mathematics", forbiddenSlots: ["P1"] }, // Cannot be first period
  { id: "ENGL", name: "English" }
];

const periods: Slot[] = [
  { id: "P1", label: "Period 1", startTimestamp: 1706100000, endTimestamp: 1706103600 },
  { id: "P2", label: "Period 2", startTimestamp: 1706103600, endTimestamp: 1706107200 }
];

// 2. Validate input
validateEntities({ resources: teachers, items: subjects, slots: periods });

// 3. Generate a schedule (simple greedy solver, respects forbidden slots & time overlap)
const assignments: Assignment[] = generateSchedule({
  resources: teachers,
  items: subjects,
  slots: periods
});
console.log(assignments);

// 4. Validate custom assignments (throws on forbidden slots or teacher double-booking)
validateAssignments(assignments, { items: subjects, slots: periods });

⚠️ Constraints Enforced

• No double-booking: A resource (e.g., teacher) cannot be assigned to two items at the same time, including overlapping slots with startTimestamp/endTimestamp.

• Forbidden slots: An item (e.g., subject) cannot be assigned to any slot in its forbiddenSlots list.

• Validation: All input and assignments are validated via Zod schemas.

🧪 Testing

The library is compatible with Vitest, Jest, or Node.js built-in test runner. Sample test cases are included for:

• Correct/incorrect input schemas
• Double-booking prevention (including with time overlaps)
• Forbidden slot constraint
• Unassignable items

🛠️ Extending

• You can add more properties to any type (e.g., rooms, grade levels, capacities).
• Write your own scheduler if you want more complex logic (multi-period, preferences, soft constraints).

📖 Type Reference

export type Resource = { id: string; name: string };
export type Item = { id: string; name: string; forbiddenSlots?: string[] };
export type Slot = {
  id: string;
  label: string;
  startTimestamp?: number;      // unix timestamp (seconds)
  endTimestamp?: number;   // unix timestamp (seconds)
};
export type Assignment = { itemId: string; resourceId: string; slotId: string };

👩‍🏫 Example: Prevent Overlap for a Teacher

const teachers: Resource[] = [
  { id: "T1", name: "Mr. Sharma" }
];
const subjects: Item[] = [
  { id: "MATH", name: "Mathematics" },
  { id: "PHYS", name: "Physics" }
];
const periods: Slot[] = [
  { id: "P1", label: "Period 1", startTimestamp: 1706100000, endTimestamp: 1706103600 },
  { id: "P2", label: "Period 2", startTimestamp: 1706101800, endTimestamp: 1706105400 } // Overlaps with P1
];

const assignments: Assignment[] = [
  { itemId: "MATH", resourceId: "T1", slotId: "P1" },
  { itemId: "PHYS", resourceId: "T1", slotId: "P2" } // Overlap!
];

validateAssignments(assignments, { items: subjects, slots: periods });
// Throws: Resource T1 double-booked in overlapping slots P1 and P2

📝 License

MIT

🗒️ Notes

• Timestamps are expected to be Unix seconds. If you use milliseconds, convert as needed.
• For real-world school usage, simply treat:
  • Teacher = Resource
  • Subject = Item
  • Period = Slot
  • Schedule entry = Assignment