https://github.com/phun-ky/cardinal
A set of JavaScript functions that gives you the cardinal direction based on degrees
https://github.com/phun-ky/cardinal
cardinal cardinal-direction cardinal-directions cartesian compass degree degrees direction
Last synced: about 2 months ago
JSON representation
A set of JavaScript functions that gives you the cardinal direction based on degrees
- Host: GitHub
- URL: https://github.com/phun-ky/cardinal
- Owner: phun-ky
- License: mit
- Created: 2025-05-02T20:18:54.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-06-24T07:00:04.000Z (10 months ago)
- Last Synced: 2025-06-24T07:00:06.896Z (10 months ago)
- Topics: cardinal, cardinal-direction, cardinal-directions, cartesian, compass, degree, degrees, direction
- Language: TypeScript
- Homepage:
- Size: 1.08 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# @phun-ky/cardinal
[](http://commitizen.github.io/cz-cli/) [](http://makeapullrequest.com) [](http://semver.org/spec/v2.0.0.html)       [](https://codecov.io/gh/phun-ky/cardinal) [](https://github.com/phun-ky/cardinal/actions/workflows/check.yml)
## About
A set of JavaScript functions that gives you the cardinal direction based on degrees.
## Table of Contents
- [@phun-ky/cardinal](#phun-kycardinal)
- [About](#about)
- [Installation](#installation)
- [Usage](#usage)
- [API](#api)
- [cardinalDirection()](#cardinaldirection)
- [Parameters](#parameters)
- [Returns](#returns)
- [Throws](#throws)
- [Throws](#throws-1)
- [Example](#example)
- [cardinalDirectionCrude()](#cardinaldirectioncrude)
- [Parameters](#parameters-1)
- [Returns](#returns-1)
- [Throws](#throws-2)
- [Throws](#throws-3)
- [Example](#example-1)
- [cardinalDirectionDetailed()](#cardinaldirectiondetailed)
- [Parameters](#parameters-2)
- [Returns](#returns-2)
- [Throws](#throws-4)
- [Throws](#throws-5)
- [Example](#example-2)
- [Contributing](#contributing)
- [License](#license)
- [Changelog](#changelog)
- [Sponsor me](#sponsor-me)
- [Attributions](#attributions)
## Installation
```shell-session
npm i --save @phun-ky/cardinal
```
## Usage
With the default function:
```ts
import { cardinalDirection } from '@phun-ky/cardinal';
const direction = cardinalDirection(45);
console.log(direction); // south-east
```
Or with the crude function:
```ts
import { cardinalDirectionCrude } from '@phun-ky/cardinal';
const direction = cardinalDirectionCrude(45);
console.log(direction); // south
```
Or with the detailed function:
```ts
import { cardinalDirectionDetailed } from '@phun-ky/cardinal';
const direction = cardinalDirectionDetailed(56.25);
console.log(direction); // south-south-east
```
## API
### cardinalDirection()
```ts
function cardinalDirection(degrees): CardinalDirectionType;
```
Defined in: [main.ts:93](https://github.com/phun-ky/cardinal/blob/main/src/main.ts#L93)
Returns the 8-point cardinal direction based on degrees.
Note: 0 degrees is EAST, increasing clockwise.
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | --------------------- |
| `degrees` | `number` | The angle in degrees. |
#### Returns
[`CardinalDirectionType`](#cardinaldirectiontype)
- The 8-point cardinal direction.
#### Throws
Parameter cannot exceed 360.
#### Throws
Parameter cannot be lower than 0.
#### Example
```ts
const direction = cardinalDirection(135); // "south"
```
---
### cardinalDirectionCrude()
```ts
function cardinalDirectionCrude(degrees): CardinalDirectionCrudeType;
```
Defined in: [main.ts:127](https://github.com/phun-ky/cardinal/blob/main/src/main.ts#L127)
Returns the crude 4-point cardinal direction based on degrees.
Note: 0 degrees is EAST, increasing clockwise.
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | --------------------- |
| `degrees` | `number` | The angle in degrees. |
#### Returns
[`CardinalDirectionCrudeType`](#cardinaldirectioncrudetype)
- The 4-point cardinal direction.
#### Throws
Parameter cannot exceed 360.
#### Throws
Parameter cannot be lower than 0.
#### Example
```ts
const direction = cardinalDirectionCrude(200); // "west"
```
---
### cardinalDirectionDetailed()
```ts
function cardinalDirectionDetailed(degrees): CardinalDirectionDetailedType;
```
Defined in: [main.ts:49](https://github.com/phun-ky/cardinal/blob/main/src/main.ts#L49)
Returns the detailed 16-point cardinal direction based on degrees.
Note: 0 degrees is EAST, increasing clockwise.
#### Parameters
| Parameter | Type | Description |
| --------- | -------- | --------------------- |
| `degrees` | `number` | The angle in degrees. |
#### Returns
[`CardinalDirectionDetailedType`](#cardinaldirectiondetailedtype)
- The 16-point cardinal direction.
#### Throws
Parameter cannot exceed 360.
#### Throws
Parameter cannot be lower than 0.
#### Example
```ts
const direction = cardinalDirectionDetailed(101.25); // "south-south-east"
```
## Contributing
Want to contribute? Please read the [CONTRIBUTING.md](https://github.com/phun-ky/cardinal/blob/main/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](https://github.com/phun-ky/cardinal/blob/main/CODE_OF_CONDUCT.md)
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/phun-ky/cardinal/blob/main/LICENSE) file for details.
## Changelog
See the [CHANGELOG.md](https://github.com/phun-ky/cardinal/blob/main/CHANGELOG.md) for details on the latest updates.
## Sponsor me
I'm an Open Source evangelist, creating stuff that does not exist yet to help get rid of secondary activities and to enhance systems already in place, be it documentation or web sites.
The sponsorship is an unique opportunity to alleviate more hours for me to maintain my projects, create new ones and contribute to the large community we're all part of :)
[Support me on GitHub Sponsors](https://github.com/sponsors/phun-ky).
p.s. **Ukraine is still under brutal Russian invasion. A lot of Ukrainian people are hurt, without shelter and need help**. You can help in various ways, for instance, directly helping refugees, spreading awareness, putting pressure on your local government or companies. You can also support Ukraine by donating e.g. to [Red Cross](https://www.icrc.org/en/donate/ukraine), [Ukraine humanitarian organisation](https://savelife.in.ua/en/donate-en/#donate-army-card-weekly) or [donate Ambulances for Ukraine](https://www.gofundme.com/f/help-to-save-the-lives-of-civilians-in-a-war-zone).
## Attributions
Compass by Justicon from Noun Project (CC BY 3.0)