refactor(simulator): clean up EventQueue implementation and add TS types

[SouparnaChatterjee]

Fixes #<issue_number_if_any>

Summary of Changes

This PR refactors the EventQueue module inside the simulator to improve clarity, maintainability, performance predictability, and TypeScript safety — while preserving all existing simulator behavior.

---

✅ 1. Code Cleanup & Structure

• Removed redundant paths and duplicate logic.

• Simplified event insertion, reordering, and popping.

• Modernized function names and aligned method responsibilities.

• Clearer internal semantics compared to the previous tightly coupled design.

---

✅ 2. Strong TypeScript Typing

• Added explicit interfaces for queue items and internal metadata.

• Removed multiple any usages.

• Stronger type guarantees when scheduling, updating, or popping events.

• Improves safety for future simulator features.

---

✅ 3. Helper Utilities

• Introduced internal helper functions to reduce repetition.

• Clearer separation between:

  • queue manipulation, and

  • simulation event properties.

---

🧪 4. Added Tests

• Introduced initial Vitest suite to validate core queue behavior.

• Ensures:

  • correct ordering,

  • correct reordering on time update,

  • proper handling of duplicates/in-queue updates.

---

⏱️ Time & Space Complexity Analysis

Before Refactor

Operation	Previous Complexity
Insert event	O(n)
Update event time	O(n) (two passes: up + down)
Pop event	O(1) but with costly shifts
Maintaining order	O(n)

Key Performance Improvement:
Time updates now use directional repositioning — improving efficiency and reducing unnecessary operations.

---

Why This Refactor Was Needed

• The earlier implementation mixed concerns and lacked clear typing.

• Duplicate logic made changes risky and debugging harder.

• Performance costs were inconsistent due to linear operations.

• This refactor establishes a modern, type-safe, maintainable foundation for future simulator engine enhancements.

---

Screenshots

No UI changes — this PR modifies internal simulator logic only.

---

Note

Please ensure Allow edits from maintainers is enabled.

[netlify[bot]]

✅ Deploy Preview for circuitverse ready!

Name	Link
🔨 Latest commit	3d42f7feb57b2294db0d4c97052faefd3ad88250
🔍 Latest deploy log	https://app.netlify.com/projects/circuitverse/deploys/691b2313f0ab49000853c495
😎 Deploy Preview	https://deploy-preview-678--circuitverse.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
Lighthouse	1 paths audited Performance: 47 (🟢 up 3 from production) Accessibility: 73 (no change from production) Best Practices: 92 (no change from production) SEO: 82 (no change from production) PWA: - View the detailed breakdown and full score reports

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai[bot]]

Walkthrough

Adds a cross-platform Node.js multi-version build script (build.js) and updates package.json to invoke it (removing build.sh), and refactors src/simulator/src/eventQueue.ts from an array/index-based queue to a private min-heap implementation with a QueueObject type and updated queue operations and time semantics.

Changes

Cohort / File(s)	Summary
Build system build.js, build.sh, package.json	Adds build.js (Node.js) as a cross-platform replacement for the removed build.sh; package.json build script changed from bash build.sh to node build.js. build.js reads version.json, iterates versions, runs per-version npx vite build --config vite.config.<version>.ts with inherited stdio, logs progress, exits non‑zero on failure, and prints a final success message on completion.
EventQueue refactor src/simulator/src/eventQueue.ts	Replaces array/index-based queue with a private min-heap; introduces/exported QueueObject type; implements heap-backed operations (add, addImmediate, pop, isEmpty, reset) and heap utilities (swap, heapifyUp, heapifyDown); centralizes time management and maintains inQueue flags and capacity checks.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

• Areas needing extra attention:
  • Heap invariants and correctness of heapifyUp / heapifyDown / swap.
  • Time computation and assignment in add(obj, delay) and interactions with propagationDelay.
  • Correct maintenance of inQueue flags and capacity handling on insertions.
  • pop() behavior when heap is empty and synchronization of the queue time with popped events.
  • Call sites that previously relied on array/index semantics of EventQueue.

Suggested labels

GSOC'24

Suggested reviewers

• JoshVarga
• Arnabdaz

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The PR title directly addresses the main change: refactoring EventQueue with cleaner implementation and TypeScript types. However, the PR also includes unrelated build system changes (replacing build.sh with build.js and updating package.json), which are significant but not mentioned in the title.	The title should reflect all major changes. Consider: 'refactor(simulator): clean up EventQueue, add TS types, and migrate build to Node.js' or split into separate PRs for build and EventQueue changes.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}