From b535868897176be45adcd498d2234dc43ad59d26 Mon Sep 17 00:00:00 2001
From: Brendan Chen <me@bchen.dev>
Date: Mon, 10 Nov 2025 14:33:00 -0800
Subject: [PATCH] Add a method to check whether a shuttle has arrived at a stop

---
 src/entities/ShuttleRepositoryEntities.ts     | 12 ++++
 .../ShuttleRepositoryEntities.test.ts         | 65 +++++++++++++++++++
 2 files changed, 77 insertions(+)
 create mode 100644 src/entities/__tests__/ShuttleRepositoryEntities.test.ts

diff --git a/src/entities/ShuttleRepositoryEntities.ts b/src/entities/ShuttleRepositoryEntities.ts
index 608bda6..73d2090 100644
--- a/src/entities/ShuttleRepositoryEntities.ts
+++ b/src/entities/ShuttleRepositoryEntities.ts
@@ -37,3 +37,15 @@ export interface IOrderedStop extends IEntityWithTimestamp {
   systemId: string;
 }
 
+/**
+ * Checks if a shuttle has arrived at a stop based on coordinate proximity.
+ * Uses a threshold of 0.001 degrees (~111 meters at the equator).
+ */
+export function shuttleHasArrivedAtStop(shuttle: IShuttle, stop: IStop) {
+  const isWithinLatitudeRange = shuttle.coordinates.latitude > stop.coordinates.latitude - 0.001
+    && shuttle.coordinates.latitude < stop.coordinates.latitude + 0.001;
+  const isWithinLongitudeRange = shuttle.coordinates.longitude > stop.coordinates.longitude - 0.001
+    && shuttle.coordinates.longitude < stop.coordinates.longitude + 0.001
+  return isWithinLatitudeRange && isWithinLongitudeRange;
+}
+
diff --git a/src/entities/__tests__/ShuttleRepositoryEntities.test.ts b/src/entities/__tests__/ShuttleRepositoryEntities.test.ts
new file mode 100644
index 0000000..084b933
--- /dev/null
+++ b/src/entities/__tests__/ShuttleRepositoryEntities.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, it } from "@jest/globals";
+import { shuttleHasArrivedAtStop, IShuttle, IStop } from "../ShuttleRepositoryEntities";
+
+describe("shuttleHasArrivedAtStop", () => {
+  const baseStop: IStop = {
+    id: "stop1",
+    name: "Test Stop",
+    systemId: "263",
+    coordinates: {
+      latitude: 33.7963,
+      longitude: -117.8540,
+    },
+    updatedTime: new Date(),
+  };
+
+  const createShuttle = (latitude: number, longitude: number): IShuttle => ({
+    id: "shuttle1",
+    name: "Test Shuttle",
+    routeId: "route1",
+    systemId: "263",
+    coordinates: { latitude, longitude },
+    orientationInDegrees: 0,
+    updatedTime: new Date(),
+  });
+
+  it("returns false when shuttle is above latitude range", () => {
+    const shuttle = createShuttle(
+      baseStop.coordinates.latitude + 0.0011,
+      baseStop.coordinates.longitude
+    );
+    expect(shuttleHasArrivedAtStop(shuttle, baseStop)).toBe(false);
+  });
+
+  it("returns false when shuttle is below latitude range", () => {
+    const shuttle = createShuttle(
+      baseStop.coordinates.latitude - 0.0011,
+      baseStop.coordinates.longitude
+    );
+    expect(shuttleHasArrivedAtStop(shuttle, baseStop)).toBe(false);
+  });
+
+  it("returns false when shuttle is to left of longitude range", () => {
+    const shuttle = createShuttle(
+      baseStop.coordinates.latitude,
+      baseStop.coordinates.longitude - 0.0011
+    );
+    expect(shuttleHasArrivedAtStop(shuttle, baseStop)).toBe(false);
+  });
+
+  it("returns false when shuttle is to right of longitude range", () => {
+    const shuttle = createShuttle(
+      baseStop.coordinates.latitude,
+      baseStop.coordinates.longitude + 0.0011
+    );
+    expect(shuttleHasArrivedAtStop(shuttle, baseStop)).toBe(false);
+  });
+
+  it("returns true when shuttle is in the range", () => {
+    const shuttle = createShuttle(
+      baseStop.coordinates.latitude + 0.0005,
+      baseStop.coordinates.longitude - 0.0005
+    );
+    expect(shuttleHasArrivedAtStop(shuttle, baseStop)).toBe(true);
+  });
+});