aric/qibla
1
0
Fork 0
mirror of https://github.com/acamarata/qibla.git synced 2026-07-02 20:00:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

style: apply prettier formatting to wiki files and wiki-sync workflow

Browse source
This commit is contained in:
Aric Camarata 2026-03-08 16:51:28 -04:00
parent f6f22f87e1
commit 200f661944
3 changed files with 53 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/wiki-sync.yml vendored
View file

@ -3,7 +3,7 @@ name: Sync Wiki
on: on:
push: push:
branches: [main] branches: [main]
paths: ['.wiki/**'] paths: [".wiki/**"]
permissions: permissions:
contents: write contents: write

82
.wiki/API-Reference.md
View file

@ -16,9 +16,9 @@ where φ₁, λ₁ is the observer and φ₂, λ₂ is the Ka'bah.
**Parameters:** **Parameters:**
| Name | Type | Description | | Name | Type | Description |
| ----- | -------- | ------------------------------------------ | | ----- | -------- | ---------------------------------------------------------------- |
| `lat` | `number` | Observer latitude in decimal degrees. Valid range: −90 to 90. | | `lat` | `number` | Observer latitude in decimal degrees. Valid range: −90 to 90. |
| `lng` | `number` | Observer longitude in decimal degrees. Valid range: −180 to 180. | | `lng` | `number` | Observer longitude in decimal degrees. Valid range: −180 to 180. |
**Returns:** `number` — Bearing in degrees clockwise from true north. Range: [0, 360). **Returns:** `number` — Bearing in degrees clockwise from true north. Range: [0, 360).
@ -26,11 +26,11 @@ where φ₁, λ₁ is the observer and φ₂, λ₂ is the Ka'bah.
**Throws:** `RangeError` if either coordinate is out of bounds. **Throws:** `RangeError` if either coordinate is out of bounds.
```typescript ```typescript
import { qiblaAngle } from '@acamarata/qibla'; import { qiblaAngle } from "@acamarata/qibla";
qiblaAngle(40.7128, -74.006); // ~58.48 (New York → Mecca) qiblaAngle(40.7128, -74.006); // ~58.48 (New York → Mecca)
qiblaAngle(51.5074, -0.1278); // ~119.0 (London → Mecca) qiblaAngle(51.5074, -0.1278); // ~119.0 (London → Mecca)
qiblaAngle(35.6762, 139.6503); // ~293.3 (Tokyo → Mecca) qiblaAngle(35.6762, 139.6503); // ~293.3 (Tokyo → Mecca)
``` ```
--- ---
@ -43,19 +43,19 @@ Maps the bearing to one of eight 45° sectors, selecting the nearest cardinal or
**Parameters:** **Parameters:**
| Name | Type | Description | | Name | Type | Description |
| --------- | -------- | ---------------------------- | | --------- | -------- | --------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360). | | `bearing` | `number` | Bearing in degrees (0–360). |
**Returns:** `CompassAbbr` — One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`. **Returns:** `CompassAbbr` — One of: `N`, `NE`, `E`, `SE`, `S`, `SW`, `W`, `NW`.
```typescript ```typescript
import { compassDir } from '@acamarata/qibla'; import { compassDir } from "@acamarata/qibla";
compassDir(0); // "N" compassDir(0); // "N"
compassDir(45); // "NE" compassDir(45); // "NE"
compassDir(58.5); // "NE" compassDir(58.5); // "NE"
compassDir(270); // "W" compassDir(270); // "W"
``` ```
--- ---
@ -66,14 +66,14 @@ Returns the full compass direction name for a bearing.
**Parameters:** **Parameters:**
| Name | Type | Description | | Name | Type | Description |
| --------- | -------- | ---------------------------- | | --------- | -------- | --------------------------- |
| `bearing` | `number` | Bearing in degrees (0–360). | | `bearing` | `number` | Bearing in degrees (0–360). |
**Returns:** `CompassName` — One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`. **Returns:** `CompassName` — One of: `North`, `Northeast`, `East`, `Southeast`, `South`, `Southwest`, `West`, `Northwest`.
```typescript ```typescript
import { compassName } from '@acamarata/qibla'; import { compassName } from "@acamarata/qibla";
compassName(58.5); // "Northeast" compassName(58.5); // "Northeast"
``` ```
@ -88,11 +88,11 @@ Useful for drawing the Qibla direction line on a map. Returns `steps + 1` points
**Parameters:** **Parameters:**
| Name | Type | Default | Description | | Name | Type | Default | Description |
| ------- | -------- | ------- | ------------------------------------------------ | | ------- | -------- | ------- | ---------------------------------------------------- |
| `lat` | `number` | — | Observer latitude in decimal degrees (−90 to 90). | | `lat` | `number` | — | Observer latitude in decimal degrees (−90 to 90). |
| `lng` | `number` | — | Observer longitude in decimal degrees (−180 to 180). | | `lng` | `number` | — | Observer longitude in decimal degrees (−180 to 180). |
| `steps` | `number` | `120` | Number of segments. Result has `steps + 1` points. | | `steps` | `number` | `120` | Number of segments. Result has `steps + 1` points. |
**Returns:** `[number, number][]` — Array of `[latitude, longitude]` pairs in degrees. **Returns:** `[number, number][]` — Array of `[latitude, longitude]` pairs in degrees.
@ -101,7 +101,7 @@ Useful for drawing the Qibla direction line on a map. Returns `steps + 1` points
Special case: if the observer is at the Ka'bah (distance = 0), returns `[[lat, lng]]`. Special case: if the observer is at the Ka'bah (distance = 0), returns `[[lat, lng]]`.
```typescript ```typescript
import { qiblaGreatCircle } from '@acamarata/qibla'; import { qiblaGreatCircle } from "@acamarata/qibla";
const path = qiblaGreatCircle(40.7128, -74.006); // 121 points const path = qiblaGreatCircle(40.7128, -74.006); // 121 points
// path[0] ≈ [40.7128, -74.006] (New York) // path[0] ≈ [40.7128, -74.006] (New York)
@ -118,17 +118,17 @@ Uses the haversine formula with a spherical Earth (R = 6,371 km, WGS-84 volumetr
**Parameters:** **Parameters:**
| Name | Type | Description | | Name | Type | Description |
| ------ | -------- | ------------------------------------- | | ------ | -------- | ------------------------------------------ |
| `lat1` | `number` | First point latitude in decimal degrees. | | `lat1` | `number` | First point latitude in decimal degrees. |
| `lng1` | `number` | First point longitude in decimal degrees. | | `lng1` | `number` | First point longitude in decimal degrees. |
| `lat2` | `number` | Second point latitude in decimal degrees. | | `lat2` | `number` | Second point latitude in decimal degrees. |
| `lng2` | `number` | Second point longitude in decimal degrees. | | `lng2` | `number` | Second point longitude in decimal degrees. |
**Returns:** `number` — Distance in kilometers. **Returns:** `number` — Distance in kilometers.
```typescript ```typescript
import { distanceKm, KAABA_LAT, KAABA_LNG } from '@acamarata/qibla'; import { distanceKm, KAABA_LAT, KAABA_LNG } from "@acamarata/qibla";
distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); // ~9,634 km distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); // ~9,634 km
``` ```
@ -137,14 +137,14 @@ distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); // ~9,634 km
## Constants ## Constants
| Constant | Value | Description | | Constant | Value | Description |
| ----------------- | ----------- | --------------------------------------------------- | | ----------------- | ----------- | ------------------------------------------------ |
| `KAABA_LAT` | `21.422511` | Ka'bah center latitude in decimal degrees north. | | `KAABA_LAT` | `21.422511` | Ka'bah center latitude in decimal degrees north. |
| `KAABA_LNG` | `39.82615` | Ka'bah center longitude in decimal degrees east. | | `KAABA_LNG` | `39.82615` | Ka'bah center longitude in decimal degrees east. |
| `EARTH_RADIUS_KM` | `6371` | WGS-84 volumetric mean radius in kilometers. | | `EARTH_RADIUS_KM` | `6371` | WGS-84 volumetric mean radius in kilometers. |
```typescript ```typescript
import { KAABA_LAT, KAABA_LNG, EARTH_RADIUS_KM } from '@acamarata/qibla'; import { KAABA_LAT, KAABA_LNG, EARTH_RADIUS_KM } from "@acamarata/qibla";
``` ```
--- ---
@ -154,15 +154,21 @@ import { KAABA_LAT, KAABA_LNG, EARTH_RADIUS_KM } from '@acamarata/qibla';
### `CompassAbbr` ### `CompassAbbr`
```typescript ```typescript
type CompassAbbr = 'N' | 'NE' | 'E' | 'SE' | 'S' | 'SW' | 'W' | 'NW'; type CompassAbbr = "N" | "NE" | "E" | "SE" | "S" | "SW" | "W" | "NW";
``` ```
### `CompassName` ### `CompassName`
```typescript ```typescript
type CompassName = type CompassName =
| 'North' | 'Northeast' | 'East' | 'Southeast' | "North"
| 'South' | 'Southwest' | 'West' | 'Northwest'; | "Northeast"
| "East"
| "Southeast"
| "South"
| "Southwest"
| "West"
| "Northwest";
``` ```
--- ---

10
.wiki/Home.md
View file

@ -24,10 +24,16 @@ npm install @acamarata/qibla
``` ```
```typescript ```typescript
import { qiblaAngle, compassDir, distanceKm, KAABA_LAT, KAABA_LNG } from '@acamarata/qibla'; import {
qiblaAngle,
compassDir,
distanceKm,
KAABA_LAT,
KAABA_LNG,
} from "@acamarata/qibla";
const bearing = qiblaAngle(40.7128, -74.006); // New York const bearing = qiblaAngle(40.7128, -74.006); // New York
console.log(bearing); // ~58.48 console.log(bearing); // ~58.48
console.log(compassDir(bearing)); // "NE" console.log(compassDir(bearing)); // "NE"
const km = distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG); const km = distanceKm(40.7128, -74.006, KAABA_LAT, KAABA_LNG);