CoordinateFormat 

A simple and flexible TypeScript library to format decimal latitude/longitude coordinates into degrees/minutes/seconds (DMS) and other coordinate formats.

Install

``bash
npm install coordinate-format
`

Usage

`typescript
import { CoordinateFormat } from "coordinate-format";

const formatter = new CoordinateFormat();
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7.721′ E" "35° 16.920′ S"
`

API

$3

`typescript
const formatter = new CoordinateFormat(format, options);
`

Parameters:

- format (optional, default: "minutes"): A format string or alias
- options (optional):
- precision: Number of decimal places (default: 3)
- labels: Custom labels for degrees, minutes, seconds, and directions

$3

| Alias | Output | Example |
| ----------- | ------------------------------------------ | ------------------------------------- |
| "seconds" | Full DMS with direction (default) | 35° 16′ 55.200″ N 149° 7′ 43.262″ E |
| "minutes" | Degrees and decimal minutes with direction | 35° 16.920′ N 149° 7.721′ E |
| "degrees" | Decimal degrees with direction | 35.282° N 149.129° E |

$3

You can create custom format strings using the following tokens:

| Token | Output | Example |
| ----- | ----------------------------------------------- | ------------------ |
| D | Integer degrees | 35 |
| DD | Integer degrees with symbol | 35° |
| d | Decimal degrees | 35.282 |
| dd | Decimal degrees with symbol | 35.282° |
| M | Integer minutes | 16 |
| MM | Integer minutes with symbol | 16′ |
| m | Decimal minutes | 16.920 |
| mm | Decimal minutes with symbol | 16.920′ |
| s | Decimal seconds | 55.200 |
| ss | Decimal seconds with symbol | 55.200″ |
| X | Direction (N/S for latitude, E/W for longitude) | N, S, E, W |
| - | Negative sign (for negative values) | - |

$3

#### format(longitude, latitude) or format([longitude, latitude])

Formats a coordinate pair and returns [longitudeString, latitudeString].

`typescript
const formatter = new CoordinateFormat("minutes");

// Arguments form
const [lon, lat] = formatter.format(149.128684, -35.282);

// Array form
const [lon, lat] = formatter.format([149.128684, -35.282]);
`

#### longitude(value)

Formats a single longitude value.

`typescript
const formatter = new CoordinateFormat("degrees");
console.log(formatter.longitude(149.128684)); // "149.129° E"
`

#### latitude(value)

Formats a single latitude value.

`typescript
const formatter = new CoordinateFormat("degrees");
console.log(formatter.latitude(-35.282)); // "35.282° S"
`

#### parse(longitudeString, latitudeString)

Parses formatted coordinate strings back into decimal degree numbers. Returns [longitude, latitude] or null if parsing fails.

`typescript
const formatter = new CoordinateFormat("minutes");
const coords = formatter.parse("149° 7.721′ E", "35° 16.920′ S");
// coords: [149.128683, -35.282]
`

The parse method supports all formats that can be generated by the format method:

`typescript
// Parse DMS (seconds format)
formatter.parse("149° 7′ 43.262″ E", "35° 16′ 55.200″ S");

// Parse decimal degrees
formatter.parse("149.129° E", "35.282° S");

// Parse with negative signs
formatter.parse("-149 7 43.262", "-35 16 55.200");
`

Examples

$3

`typescript
import { CoordinateFormat } from "coordinate-format";

const formatter = new CoordinateFormat();
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7.721′ E" "35° 16.920′ S"
`

$3

`typescript
const formatter = new CoordinateFormat("-D M s");
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149 7 43.262" "-35 16 55.200"
`

$3

`typescript
const formatter = new CoordinateFormat("seconds", { precision: 0 });
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149° 7′ 43″ E" "35° 16′ 55″ S"
`

$3

`typescript
const formatter = new CoordinateFormat("DD MM ss X", {
labels: {
latitude: ["Norte", "Sur"],
longitude: ["Este", "Oeste"],
degrees: "d",
minutes: "m",
seconds: "s",
},
});
const [lon, lat] = formatter.format(149.128684, -35.282);
console.log(lon, lat); // "149d 7m 43.262s Este" "35d 16m 55.200s Sur"
`

$3

`typescript
const formatter = new CoordinateFormat("minutes");

// Parse formatted strings back to decimal
const coords = formatter.parse("149° 7.721′ E", "35° 16.920′ S");
console.log(coords); // [149.128683, -35.282]

// Round-trip formatting and parsing
const [lonStr, latStr] = formatter.format(149.128684, -35.282);
const [lon, lat] = formatter.parse(lonStr, latStr)!;
console.log(lon, lat); // 149.128684, -35.282
``

License

This project is licensed under the MIT License. It is a fork of formatcoords by @nerik.