breaking: align useGeolocation API with Web API (#189)

svecosystem · Dec 20, 2024 · e60f73b · e60f73b
1 parent 64b688d
commit e60f73b
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 37 deletions.
diff --git a/.changeset/three-cups-watch.md b/.changeset/three-cups-watch.md
@@ -0,0 +1,5 @@
+---
+"runed": minor
+---
+
+breaking: Align `useGeolocation` API with the Geolocation Web API
diff --git a/packages/runed/src/lib/utilities/useGeolocation/useGeolocation.svelte.ts b/packages/runed/src/lib/utilities/useGeolocation/useGeolocation.svelte.ts
@@ -14,12 +14,31 @@ export type UseGeolocationOptions = Partial<PositionOptions> & {
 	immediate?: boolean;
 } & ConfigurableNavigator;
 
+type WritableGeolocationPosition = WritableProperties<
+	Omit<GeolocationPosition, "toJSON" | "coords">
+> & {
+	coords: WritableProperties<Omit<GeolocationPosition["coords"], "toJSON">>;
+};
+
+export type UseGeolocationPosition = Omit<GeolocationPosition, "toJSON" | "coords"> & {
+	coords: Omit<GeolocationPosition["coords"], "toJSON">;
+};
+
+export type UseGeolocationReturn = {
+	readonly isSupported: boolean;
+	readonly position: UseGeolocationPosition;
+	readonly error: GeolocationPositionError | null;
+	readonly isPaused: boolean;
+	resume: () => void;
+	pause: () => void;
+};
+
 /**
  * Reactive access to the browser's [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API).
  *
  * @see https://runed.dev/docs/utilities/use-geolocation
  */
-export function useGeolocation(options: UseGeolocationOptions = {}) {
+export function useGeolocation(options: UseGeolocationOptions = {}): UseGeolocationReturn {
 	const {
 		enableHighAccuracy = true,
 		maximumAge = 30000,
@@ -30,28 +49,31 @@ export function useGeolocation(options: UseGeolocationOptions = {}) {
 
 	const isSupported = Boolean(navigator);
 
-	let locatedAt = $state<number | null>(null);
 	let error = $state.raw<GeolocationPositionError | null>(null);
-	let coords = $state<WritableProperties<Omit<GeolocationPosition["coords"], "toJSON">>>({
-		accuracy: 0,
-		latitude: Number.POSITIVE_INFINITY,
-		longitude: Number.POSITIVE_INFINITY,
-		altitude: null,
-		altitudeAccuracy: null,
-		heading: null,
-		speed: null,
+	let position = $state<WritableGeolocationPosition>({
+		timestamp: 0,
+		coords: {
+			accuracy: 0,
+			latitude: Number.POSITIVE_INFINITY,
+			longitude: Number.POSITIVE_INFINITY,
+			altitude: null,
+			altitudeAccuracy: null,
+			heading: null,
+			speed: null,
+		},
 	});
 	let isPaused = $state(false);
 
-	function updatePosition(position: GeolocationPosition) {
-		locatedAt = position.timestamp;
-		coords.accuracy = position.coords.accuracy;
-		coords.altitude = position.coords.altitude;
-		coords.altitudeAccuracy = position.coords.altitudeAccuracy;
-		coords.heading = position.coords.heading;
-		coords.latitude = position.coords.latitude;
-		coords.longitude = position.coords.longitude;
-		coords.speed = position.coords.speed;
+	function updatePosition(_position: GeolocationPosition) {
+		error = null;
+		position.timestamp = _position.timestamp;
+		position.coords.accuracy = _position.coords.accuracy;
+		position.coords.altitude = _position.coords.altitude;
+		position.coords.altitudeAccuracy = _position.coords.altitudeAccuracy;
+		position.coords.heading = _position.coords.heading;
+		position.coords.latitude = _position.coords.latitude;
+		position.coords.longitude = _position.coords.longitude;
+		position.coords.speed = _position.coords.speed;
 	}
 
 	let watcher: number;
@@ -82,12 +104,7 @@ export function useGeolocation(options: UseGeolocationOptions = {}) {
 		get isSupported() {
 			return isSupported;
 		},
-		get coords() {
-			return coords;
-		},
-		get locatedAt() {
-			return locatedAt;
-		},
+		position,
 		get error() {
 			return error;
 		},
@@ -98,5 +115,3 @@ export function useGeolocation(options: UseGeolocationOptions = {}) {
 		pause,
 	};
 }
-
-export type useGeolocationReturn = ReturnType<typeof useGeolocation>;
diff --git a/sites/docs/src/content/utilities/use-geolocation.md b/sites/docs/src/content/utilities/use-geolocation.md
@@ -24,8 +24,8 @@ import Demo from '$lib/components/demos/use-geolocation.svelte';
 	const location = useGeolocation();
 </script>
 
-<pre>Coords: {JSON.stringify(location.coords, null, 2)}</pre>
-<pre>Located at: {location.locatedAt}</pre>
+<pre>Coords: {JSON.stringify(location.position.coords, null, 2)}</pre>
+<pre>Located at: {location.position.timestamp}</pre>
 <pre>Error: {JSON.stringify(location.error, null, 2)}</pre>
 <pre>Is Supported: {location.isSupported}</pre>
 <button onclick={location.pause} disabled={location.isPaused}>Pause</button>
@@ -47,15 +47,10 @@ type UseGeolocationOptions = Partial<PositionOptions> & {
 
 type UseGeolocationReturn = {
 	readonly isSupported: boolean;
-	readonly coords: Omit<GeolocationPosition["coords"], "toJSON">;
-	readonly locatedAt: number | null;
+	readonly position: Omit<GeolocationPosition, "toJSON">;
 	readonly error: GeolocationPositionError | null;
 	readonly isPaused: boolean;
 	pause: () => void;
 	resume: () => void;
 };
 ```
-
-```
-
-```
diff --git a/sites/docs/src/lib/components/demos/use-geolocation.svelte b/sites/docs/src/lib/components/demos/use-geolocation.svelte
@@ -6,8 +6,8 @@
 </script>
 
 <DemoContainer class="flex flex-col gap-1">
-	<pre>Coords: {JSON.stringify(location.coords, null, 2)}</pre>
-	<pre>Located at: {location.locatedAt}</pre>
+	<pre>Coords: {JSON.stringify(location.position.coords, null, 2)}</pre>
+	<pre>Located at: {location.position.timestamp}</pre>
 	<pre>Error: {JSON.stringify(location.error, null, 2)}</pre>
 	<pre>Is Supported: {location.isSupported}</pre>
 	<div class="mt-4 flex items-center gap-2">