{"_id":"@besrabasant/schedulejs","_rev":"5-070e595f8ef0c3ed97ad93578d913829","name":"@besrabasant/schedulejs","dist-tags":{"latest":"0.0.5"},"versions":{"0.0.1":{"name":"@besrabasant/schedulejs","version":"0.0.1","_id":"@besrabasant/schedulejs@0.0.1","maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"dist":{"shasum":"4f1c0fd3bc9c0f027f4fd707413c021aab664334","tarball":"https://registry.npmjs.org/@besrabasant/schedulejs/-/schedulejs-0.0.1.tgz","fileCount":11,"integrity":"sha512-SEWeLGCSKOXz4SkUHSY2lswlCM+aCkY0zQ/gt+LiUJ8GQAMqncYzS4ssox7e1OPWSWJp8MXmkjyc4s1K92QnVg==","signatures":[{"sig":"MEQCIHu/xABMqGpRFyvjVLrCMJGken/4lmtwdTz1F9YHzp34AiAigip5T/9dcBeigIodYIO0ck7yn2Pqaoq4eEKayvLWLg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":17568},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","development":"./src/index.ts"},"./package.json":"./package.json"},"gitHead":"dd00b6eee473fe0652597373fb22c33c42f239fa","_npmUser":{"name":"besrabasant","email":"besrabasant@gmail.com"},"_npmVersion":"11.4.2","description":"This library was generated with [Nx](https://nx.dev).","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^4.0.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/schedulejs_0.0.1_1753205746408_0.5724098236839803","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@besrabasant/schedulejs","version":"0.0.2","_id":"@besrabasant/schedulejs@0.0.2","maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"dist":{"shasum":"24b024446a4791a86eb617780da1d02362b6c49c","tarball":"https://registry.npmjs.org/@besrabasant/schedulejs/-/schedulejs-0.0.2.tgz","fileCount":11,"integrity":"sha512-4QLc/JPOozSB0uA8hWomP5zOTGtv6OgU7kFLZ2FEwqBcP0+PeABx1fJsJJccn/fPBFRffOJH686JEZJr12MGXQ==","signatures":[{"sig":"MEUCIE4TAm15r2QLJOaMOBRd2MKMZmR7hHSle2bKJwCWBN4+AiEAmH3lKnDYlbpWyt4Kb81iURSasG5INdPdQA0Ae3HIckE=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21801},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","development":"./src/index.ts"},"./package.json":"./package.json"},"gitHead":"edf15b5659c9f3ea028b99e732665f93f5a8da30","_npmUser":{"name":"besrabasant","email":"besrabasant@gmail.com"},"_npmVersion":"11.4.2","description":"A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^4.0.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/schedulejs_0.0.2_1753206090558_0.7442590036181431","host":"s3://npm-registry-packages-npm-production"}},"0.0.3":{"name":"@besrabasant/schedulejs","version":"0.0.3","_id":"@besrabasant/schedulejs@0.0.3","maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"dist":{"shasum":"f0304483fe6eab198ba9882b4c53056faf2ac257","tarball":"https://registry.npmjs.org/@besrabasant/schedulejs/-/schedulejs-0.0.3.tgz","fileCount":11,"integrity":"sha512-912PENbnPEZjaLJWcAeAMdHnlbCJ2Lv5IS6HEvD/3yDgX5s3aLDtkc7HVgVA11vZVTCLjnVkWxFBYO4LdqGwlw==","signatures":[{"sig":"MEQCIFROPKWZ0PLTCJWHxQ37q8WVI/sjwu5mSQmIaAEYYmJJAiBbGorWbIObKl6QGhsR/0Mpahaiv0K3O0KB6ddW7wCPJQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21821},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","development":"./src/index.ts"},"./package.json":"./package.json"},"gitHead":"59b4dc04809b5e20af21a0f211ef0e166d874540","_npmUser":{"name":"besrabasant","email":"besrabasant@gmail.com"},"_npmVersion":"11.4.2","description":"A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^4.0.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/schedulejs_0.0.3_1753206332475_0.5238851065701688","host":"s3://npm-registry-packages-npm-production"}},"0.0.4":{"name":"@besrabasant/schedulejs","version":"0.0.4","_id":"@besrabasant/schedulejs@0.0.4","maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"dist":{"shasum":"0eeda67dfa7daec2855e7ff4b9dc89e604c8dbb1","tarball":"https://registry.npmjs.org/@besrabasant/schedulejs/-/schedulejs-0.0.4.tgz","fileCount":11,"integrity":"sha512-arhAZHYVOymgA6iu9Mhujt6MAjjeb4g2goLTR5cbtC/lXcMlsJM4QOm+sAMJYCePEv7isX67xppRaaDXYWLolA==","signatures":[{"sig":"MEUCIG1OewfWQA8Lr3rsHj4c6dE4UTjvD1i5G9JbfqztViJzAiEA610+KHir2ooYtDiU1g1QNsvmIYBkxZZOJ29YXfqNqA0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":21826},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js","development":"./src/index.ts"},"./package.json":"./package.json"},"gitHead":"7c6614cfcc76bfbe7ff4868b2b625699925b9e17","_npmUser":{"name":"besrabasant","email":"besrabasant@gmail.com"},"_npmVersion":"11.4.2","description":"A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).","directories":{},"_nodeVersion":"24.4.1","dependencies":{"zod":"^4.0.5"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/schedulejs_0.0.4_1753206507601_0.4186929573870366","host":"s3://npm-registry-packages-npm-production"}},"0.0.5":{"name":"@besrabasant/schedulejs","version":"0.0.5","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{"./package.json":"./package.json",".":{"development":"./src/index.ts","types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"dependencies":{"zod":"^4.0.5"},"_id":"@besrabasant/schedulejs@0.0.5","gitHead":"0fd11c55d00e93a02420c77530bc2cdf703b4e77","description":"A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).","_nodeVersion":"24.4.1","_npmVersion":"11.4.2","dist":{"integrity":"sha512-y4MqR06HJRu/j9grUX1TGaMSwXgRRE9wxjdzVUWS+CRuAKNvlzGZEIymtbTScUbffk78QxqTxwmuLe5E2Qenng==","shasum":"a466fc05bb1790607144aea8cb87b0b661a99f7a","tarball":"https://registry.npmjs.org/@besrabasant/schedulejs/-/schedulejs-0.0.5.tgz","fileCount":11,"unpackedSize":21816,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCh+9tVAcLFuuFbGJIeNvnUVYeAeAJkw/ZFwjTPDTkALQIhAON1MUYLJnxQ3ip026F3dFAZzoU+evdjNCCRLnDwqH7q"}]},"_npmUser":{"name":"besrabasant","email":"besrabasant@gmail.com"},"directories":{},"maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/schedulejs_0.0.5_1753206604850_0.09447459047910867"},"_hasShrinkwrap":false}},"time":{"created":"2025-07-22T17:35:46.274Z","modified":"2025-07-22T17:50:05.210Z","0.0.1":"2025-07-22T17:35:46.608Z","0.0.2":"2025-07-22T17:41:30.738Z","0.0.3":"2025-07-22T17:45:32.648Z","0.0.4":"2025-07-22T17:48:27.795Z","0.0.5":"2025-07-22T17:50:05.039Z"},"description":"A minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).","maintainers":[{"name":"besrabasant","email":"besrabasant@gmail.com"}],"readme":"# Schedulejs\n\nA minimal, extensible TypeScript library for abstract scheduling and timetabling, supporting strong validation, time clash prevention, and customizable constraints using [Zod](https://zod.dev/).\n\n- **Generic:** Model teachers, rooms, classes, or any resource as abstract types.\n- **Validates:** Prevents resource double-booking and assignment of items (e.g., subjects) to forbidden slots.\n- **Supports timeslots:** Prevents overlap based on start/end Unix timestamps.\n\n---\n\n## 📦 Installation\n\n```bash\nnpm install @besrabasant/schedulejs\n```\n## 🚦 Concepts & Mapping\n| Library Term | School Example  | Typical Meaning        |\n| ------------ | --------------- | ---------------------- |\n| Resource     | Teacher         | Who/what is scheduled  |\n| Item         | Subject/Course  | What to schedule       |\n| Slot         | Period/Timeslot | When to schedule       |\n| Assignment   | Schedule entry  | One scheduled instance |\n\n## 📝 Usage Example (School Timetable)\n```ts\nimport {\n  Resource, Item, Slot, Assignment,\n  validateEntities, generateSchedule, validateAssignments,\n} from \"@besrabasant/schedulejs\";\n\n// 1. Define your actors (teachers/resources, subjects/items, periods/slots)\nconst teachers: Resource[] = [\n  { id: \"T1\", name: \"Mr. Sharma\" },\n  { id: \"T2\", name: \"Ms. Verma\" }\n];\n\nconst subjects: Item[] = [\n  { id: \"MATH\", name: \"Mathematics\", forbiddenSlots: [\"P1\"] }, // Cannot be first period\n  { id: \"ENGL\", name: \"English\" }\n];\n\nconst periods: Slot[] = [\n  { id: \"P1\", label: \"Period 1\", startTimestamp: 1706100000, endTimestamp: 1706103600 },\n  { id: \"P2\", label: \"Period 2\", startTimestamp: 1706103600, endTimestamp: 1706107200 }\n];\n\n// 2. Validate input\nvalidateEntities({ resources: teachers, items: subjects, slots: periods });\n\n// 3. Generate a schedule (simple greedy solver, respects forbidden slots & time overlap)\nconst assignments: Assignment[] = generateSchedule({\n  resources: teachers,\n  items: subjects,\n  slots: periods\n});\nconsole.log(assignments);\n\n// 4. Validate custom assignments (throws on forbidden slots or teacher double-booking)\nvalidateAssignments(assignments, { items: subjects, slots: periods });\n```\n\n## ⚠️ Constraints Enforced\n- **No double-booking**: A resource (e.g., teacher) cannot be assigned to two items at the same time, including overlapping slots with `startTimestamp`/`endTimestamp`.\n\n- **Forbidden slots**: An item (e.g., subject) cannot be assigned to any slot in its forbiddenSlots list.\n\n- **Validation**: All input and assignments are validated via Zod schemas.\n\n## 🧪 Testing\nThe library is compatible with Vitest, Jest, or Node.js built-in test runner.\nSample test cases are included for:\n\n- Correct/incorrect input schemas\n- Double-booking prevention (including with time overlaps)\n- Forbidden slot constraint\n- Unassignable items\n\n## 🛠️ Extending\n- You can add more properties to any type (e.g., rooms, grade levels, capacities).\n- Write your own scheduler if you want more complex logic (multi-period, preferences, soft constraints).\n\n# 📖 Type Reference\n```ts\nexport type Resource = { id: string; name: string };\nexport type Item = { id: string; name: string; forbiddenSlots?: string[] };\nexport type Slot = {\n  id: string;\n  label: string;\n  startTimestamp?: number;      // unix timestamp (seconds)\n  endTimestamp?: number;   // unix timestamp (seconds)\n};\nexport type Assignment = { itemId: string; resourceId: string; slotId: string };\n```\n\n### 👩‍🏫 Example: Prevent Overlap for a Teacher\n```ts\n\nconst teachers: Resource[] = [\n  { id: \"T1\", name: \"Mr. Sharma\" }\n];\nconst subjects: Item[] = [\n  { id: \"MATH\", name: \"Mathematics\" },\n  { id: \"PHYS\", name: \"Physics\" }\n];\nconst periods: Slot[] = [\n  { id: \"P1\", label: \"Period 1\", startTimestamp: 1706100000, endTimestamp: 1706103600 },\n  { id: \"P2\", label: \"Period 2\", startTimestamp: 1706101800, endTimestamp: 1706105400 } // Overlaps with P1\n];\n\nconst assignments: Assignment[] = [\n  { itemId: \"MATH\", resourceId: \"T1\", slotId: \"P1\" },\n  { itemId: \"PHYS\", resourceId: \"T1\", slotId: \"P2\" } // Overlap!\n];\n\nvalidateAssignments(assignments, { items: subjects, slots: periods });\n// Throws: Resource T1 double-booked in overlapping slots P1 and P2\n```\n## 📝 License\nMIT\n\n## 🗒️ Notes\n- Timestamps are expected to be Unix seconds. If you use milliseconds, convert as needed.\n- For real-world school usage, simply treat:\n    - Teacher = Resource\n    - Subject = Item\n    - Period = Slot\n    - Schedule entry = Assignment\n\n","readmeFilename":"README.md"}