@accelint/geo 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @accelint/geo
 
+## 0.6.0
+
+### Minor Changes
+
+- 58bc0db: Extends `createCoordinate` to accept numeric input formats in addition to strings
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -1,9 +1,241 @@
 # @accelint/geo
 
-A collection of JavaScript functions for working with coordinates and geospatial data.
+Geographic coordinate parsing, conversion, and formatting for multiple coordinate systems.
+
+## Features
+
+- **5 Coordinate Systems**: Parse and format coordinates in multiple notation systems
+  - Decimal Degrees (DD): `40.7128° N / 74.0060° W`
+  - Degrees Decimal Minutes (DDM): `40° 42.768' N / 74° 0.36' W`
+  - Degrees Minutes Seconds (DMS): `40° 42' 46.08" N / 74° 0' 21.6" W`
+  - Military Grid Reference System (MGRS): `18T WL 80000 00000`
+  - Universal Transverse Mercator (UTM): `18N 585628 4511644`
+
+- **Flexible Format Ordering**: Convert between LATLON and LONLAT formats
+- **Input Validation**: Detailed error messages for invalid coordinates
+- **Performance Optimized**: Immutable coordinate objects with intelligent caching
+- **Type Safe**: Full TypeScript support with complete type definitions
 
 ## Installation
 
 ```sh
 npm install @accelint/geo
 ```
+
+## Quick Start
+
+```typescript
+import { createCoordinate, coordinateSystems } from '@accelint/geo';
+
+// Create a coordinate parser for Decimal Degrees
+const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+const coord = create('40.7128 / -74.0060');
+
+// Or use numeric input
+const coord2 = create([40.7128, -74.0060]);
+
+// Access different formats
+coord.dd();    // '40.7128 N / 74.006 W'
+coord.ddm();   // '40 42.768 N / 74 0.36 W'
+coord.dms();   // '40 42 46.08 N / 74 0 21.6 W'
+coord.mgrs();  // '18T WL 80000 00000'
+coord.utm();   // '18N 585628 4511644'
+
+// Change format order
+coord.dms('LONLAT'); // '74 0 21.6 W / 40 42 46.08 N'
+```
+
+## Usage Examples
+
+### Parsing Different Coordinate Systems
+
+```typescript
+import { createCoordinate, coordinateSystems } from '@accelint/geo';
+
+// Parse Decimal Degrees
+const parseDD = createCoordinate(coordinateSystems.dd);
+const coordDD = parseDD('40.7128 / -74.0060');
+
+// Parse Degrees Minutes Seconds
+const parseDMS = createCoordinate(coordinateSystems.dms);
+const coordDMS = parseDMS('40° 42\' 46.08" N / 74° 0\' 21.6" W');
+
+// Parse UTM coordinates
+const parseUTM = createCoordinate(coordinateSystems.utm);
+const coordUTM = parseUTM('18N 585628 4511644');
+
+// Parse MGRS coordinates
+const parseMGRS = createCoordinate(coordinateSystems.mgrs);
+const coordMGRS = parseMGRS('18T WL 80000 00000');
+```
+
+### Numeric Input
+
+```typescript
+import { createCoordinate, coordinateSystems } from '@accelint/geo';
+import type { LatLonTuple, LonLatTuple } from '@accelint/geo';
+
+// Using typed tuple input (order follows format parameter)
+const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+const latlon: LatLonTuple = [40.7128, -74.0060];
+const coordTuple = create(latlon);
+
+// LONLAT order (GeoJSON convention)
+const createLonLat = createCoordinate(coordinateSystems.dd, 'LONLAT');
+const lonlat: LonLatTuple = [-74.0060, 40.7128];
+const coordLonLat = createLonLat(lonlat);
+
+// Using object input
+const coordObj = create({ lat: 40.7128, lon: -74.0060 });
+
+// Object aliases also work
+const coordAlt = create({ latitude: 40.7128, longitude: -74.0060 });
+```
+
+### Converting Between Formats
+
+```typescript
+const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+const coord = create('40.7128 / -74.0060');
+
+// Convert to different coordinate systems
+coord.dd();    // '40.7128 N / 74.006 W'
+coord.ddm();   // '40 42.768 N / 74 0.36 W'
+coord.dms();   // '40 42 46.08 N / 74 0 21.6 W'
+coord.mgrs();  // '18T WL 80000 00000'
+coord.utm();   // '18N 585628 4511644'
+
+// Change coordinate order (LATLON to LONLAT)
+coord.dd('LONLAT');  // '74.006 W / 40.7128 N'
+coord.dms('LONLAT'); // '74 0 21.6 W / 40 42 46.08 N'
+```
+
+### Error Handling
+
+```typescript
+const create = createCoordinate(coordinateSystems.dd);
+const coord = create('invalid input');
+
+if (!coord.valid) {
+  console.log(coord.errors);
+  // ['[ERROR] No input.']
+}
+
+// Access raw coordinate values
+if (coord.valid) {
+  console.log(coord.raw.LAT); // 40.7128
+  console.log(coord.raw.LON); // -74.0060
+}
+```
+
+## API Reference
+
+### `createCoordinate(system?, format?)`
+
+Creates a coordinate parser function.
+
+**Parameters:**
+
+- `system` (CoordinateSystem, optional): Coordinate system to use for parsing. Defaults to `coordinateSystems.dd`
+- `format` (Format, optional): Coordinate order format (`'LATLON'` or `'LONLAT'`). Defaults to `'LATLON'`
+
+**Returns:** Function that accepts a coordinate input and returns a Coordinate object
+
+**Input types:**
+
+- **String**: Coordinate string in the specified system's format (e.g., `'40.7128 / -74.0060'`)
+- **Tuple**: `LatLonTuple` or `LonLatTuple` — a `readonly [number, number]` with named elements, where order follows the `format` parameter (e.g., `[40.7128, -74.0060]` for LATLON)
+- **Object**: Object with lat/lon properties. Accepts case-insensitive keys:
+  - `lat` / `lon`
+  - `latitude` / `longitude`
+
+**Example:**
+
+```typescript
+const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+const coord = create('40.7128 / -74.0060');
+```
+
+### `coordinateSystems`
+
+Object containing available coordinate system implementations.
+
+**Properties:**
+
+- `dd` - Decimal Degrees system
+- `ddm` - Degrees Decimal Minutes system
+- `dms` - Degrees Minutes Seconds system
+- `mgrs` - Military Grid Reference System
+- `utm` - Universal Transverse Mercator system
+
+### Coordinate Object
+
+The object returned by calling the function from `createCoordinate()`.
+
+**Properties:**
+
+- `valid` (boolean): Whether the coordinate was successfully parsed
+- `errors` (string[]): Array of error messages (empty if valid)
+- `raw` (object): Raw coordinate values with `LAT` and `LON` properties
+
+**Methods:**
+
+- `dd(format?)`: Format as Decimal Degrees
+- `ddm(format?)`: Format as Degrees Decimal Minutes
+- `dms(format?)`: Format as Degrees Minutes Seconds
+- `mgrs(format?)`: Format as MGRS
+- `utm(format?)`: Format as UTM
+
+Each method accepts an optional `format` parameter (`'LATLON'` or `'LONLAT'`) to override the default format order.
+
+### TypeScript Types
+
+The package exports named tuple types for type-safe coordinate handling:
+
+- **`LatLonTuple`** — `readonly [latitude: number, longitude: number]` — tuple in lat/lon order
+- **`LonLatTuple`** — `readonly [longitude: number, latitude: number]` — tuple in lon/lat order (GeoJSON convention)
+- **`CoordinateTuple`** — `LatLonTuple | LonLatTuple` — union of both orderings
+- **`CoordinateObject`** — `Record<string, number>` — object with string keys (e.g., `{ lat, lon }`)
+- **`CoordinateInput`** — `string | CoordinateTuple | CoordinateObject` — all accepted input types
+
+Named tuple elements provide IDE hints for element order, preventing lat/lon mix-ups:
+
+```typescript
+import type { LatLonTuple, LonLatTuple } from '@accelint/geo';
+
+const latlon: LatLonTuple = [40.7128, -74.0060]; // [latitude, longitude]
+const lonlat: LonLatTuple = [-74.0060, 40.7128]; // [longitude, latitude]
+```
+
+## Coordinate System Formats
+
+### Decimal Degrees (DD)
+
+- Format: `±DD.DDDD°`
+- Example: `40.7128° N / 74.0060° W`
+
+### Degrees Decimal Minutes (DDM)
+
+- Format: `±DD° MM.MMMM'`
+- Example: `40° 42.768' N / 74° 0.36' W`
+
+### Degrees Minutes Seconds (DMS)
+
+- Format: `±DD° MM' SS.SSSS"`
+- Example: `40° 42' 46.08" N / 74° 0' 21.6" W`
+
+### Military Grid Reference System (MGRS)
+
+- Format: `ZZ[A-Z] [A-Z][A-Z] EEEEE NNNNN`
+- Example: `18T WL 80000 00000`
+
+### Universal Transverse Mercator (UTM)
+
+- Format: `ZZ[N|S] EEEEEE NNNNNNN`
+- Example: `18N 585628 4511644`
+
+## License
+
+Apache-2.0
+
+Copyright 2024-2026 Hypergiant Galactic Systems Inc.

package/catalog-info.yaml

@@ -15,7 +15,7 @@ metadata:
   annotations:
     backstage.io/edit-url: https://github.com/gohypergiant/standard-toolkit/blob/main/packages/geo/catalog-info.yaml
     backstage.io/techdocs-ref: dir:.
-    package/version: 0.5.1
+    package/version: 0.6.0
     github.com/project-slug: gohypergiant/standard-toolkit
   links:
     - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/geo

package/dist/cartesian.d.ts

@@ -14,8 +14,10 @@
  * pure function
  *
  * @example
+ * ```typescript
  * const result = cartesian([1, 2], ['a', 'b']);
  * // result: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+ * ```
  */
 declare function cartesian<T>(...all: T[][]): T[][];
 //#endregion

package/dist/cartesian.js

@@ -27,8 +27,10 @@
 * pure function
 *
 * @example
+* ```typescript
 * const result = cartesian([1, 2], ['a', 'b']);
 * // result: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]
+* ```
 */
 function cartesian(...all) {
 	return all.reduce((results, entries) => results.map((result) => entries.map((entry) => result.concat([entry]))).reduce((sub, res) => sub.concat(res), []), [[]]);

package/dist/cartesian.js.map

@@ -1 +1 @@
-{"version":3,"file":"cartesian.js","names":[],"sources":["../src/cartesian.ts"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Computes the Cartesian product of multiple arrays.\n *\n * @template T\n * the type of elements in the input arrays.\n * @param {...T[][]} all\n * a variadic number of arrays to compute the Cartesian product of.\n * @returns {T[][]}\n * An array containing all possible combinations of elements from the input\n * arrays, where each combination is represented as an array.\n *\n * @remarks\n * pure function\n *\n * @example\n * const result = cartesian([1, 2], ['a', 'b']);\n * // result: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]\n */\nexport function cartesian<T>(...all: T[][]): T[][] {\n  return all.reduce<T[][]>(\n    (results, entries) =>\n      results\n        .map((result) => entries.map((entry) => result.concat([entry])))\n        .reduce((sub, res) => sub.concat(res), []),\n    [[]],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,UAAa,GAAG,KAAmB;AACjD,QAAO,IAAI,QACR,SAAS,YACR,QACG,KAAK,WAAW,QAAQ,KAAK,UAAU,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAC/D,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC,EAC9C,CAAC,EAAE,CAAC,CACL"}
+{"version":3,"file":"cartesian.js","names":[],"sources":["../src/cartesian.ts"],"sourcesContent":["// __private-exports\n/*\n * Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n/**\n * Computes the Cartesian product of multiple arrays.\n *\n * @template T\n * the type of elements in the input arrays.\n * @param {...T[][]} all\n * a variadic number of arrays to compute the Cartesian product of.\n * @returns {T[][]}\n * An array containing all possible combinations of elements from the input\n * arrays, where each combination is represented as an array.\n *\n * @remarks\n * pure function\n *\n * @example\n * ```typescript\n * const result = cartesian([1, 2], ['a', 'b']);\n * // result: [[1, 'a'], [1, 'b'], [2, 'a'], [2, 'b']]\n * ```\n */\nexport function cartesian<T>(...all: T[][]): T[][] {\n  return all.reduce<T[][]>(\n    (results, entries) =>\n      results\n        .map((result) => entries.map((entry) => result.concat([entry])))\n        .reduce((sub, res) => sub.concat(res), []),\n    [[]],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,UAAa,GAAG,KAAmB;AACjD,QAAO,IAAI,QACR,SAAS,YACR,QACG,KAAK,WAAW,QAAQ,KAAK,UAAU,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAC/D,QAAQ,KAAK,QAAQ,IAAI,OAAO,IAAI,EAAE,EAAE,CAAC,EAC9C,CAAC,EAAE,CAAC,CACL"}

package/dist/coordinates/coordinate.d.ts

@@ -10,6 +10,7 @@
  * governing permissions and limitations under the License.
  */
 
+import { CoordinateInput, CoordinateInternalValue, CoordinateObject, CoordinateTuple, LatLonTuple, LonLatTuple } from "./latlon/internal/normalize.js";
 import { Format } from "./latlon/internal/index.js";
 import { CoordinateSystem } from "./latlon/internal/coordinate-system.js";
 
@@ -29,10 +30,6 @@ type Coordinate = {
   raw: CoordinateInternalValue;
   valid: boolean;
 };
-type CoordinateInternalValue = {
-  LAT: number;
-  LON: number;
-};
 /**
  * Output a string value of a coordinate using an available system. The
  * original value is preserved without conversion to an internal
@@ -46,6 +43,7 @@ type CoordinateInternalValue = {
  * pure function
  *
  * @example
+ * ```typescript
  * const create = createCoordinate(coordinateSystems.dd, 'LATLON')
  * const coord = create('89.765432109 / 123.456789012')
  *
@@ -56,8 +54,31 @@ type CoordinateInternalValue = {
  *
  * // change format to 'LONLAT'
  * coord.dms('LONLAT') === '123 27 24.4404432 E / 89 45 55.5555924 N'
+ * ```
  */
 type Formatter = (f?: Format) => string;
+/**
+ * Available coordinate systems for parsing, converting, and formatting geographic coordinates.
+ *
+ * Provides five coordinate notation systems:
+ * - dd: Decimal Degrees
+ * - ddm: Degrees Decimal Minutes
+ * - dms: Degrees Minutes Seconds
+ * - mgrs: Military Grid Reference System
+ * - utm: Universal Transverse Mercator
+ *
+ * @example
+ * ```typescript
+ * const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+ * const coord = create('40.7128 / -74.0060');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const createMGRS = createCoordinate(coordinateSystems.mgrs);
+ * const coord = createMGRS('18T WL 80000 00000');
+ * ```
+ */
 declare const coordinateSystems: Readonly<{
   readonly dd: CoordinateSystem;
   readonly ddm: CoordinateSystem;
@@ -71,16 +92,29 @@ declare const coordinateSystems: Readonly<{
  * used for validation and eventually for output as defaults if no alternatives
  * are provided.
  *
- * @param initSystem dd, ddm, dms, mgrs, or utm of coordinateSystems
+ * @param initSystem - Coordinate system to use for parsing (dd, ddm, dms, mgrs, or utm from coordinateSystems). Defaults to Decimal Degrees.
+ * @param initFormat - Coordinate format ordering (LATLON or LONLAT). Defaults to LATLON.
+ * @returns Function that accepts coordinate string and returns Coordinate object with formatters.
  *
  * @remarks
  * pure function
  *
  * @example
+ * ```typescript
  * const create = createCoordinate(coordinateSystems.dd, 'LATLON')
+ * const coord = create('40.7128 / -74.0060')
+ * coord.dd() // '40.7128 N / 74.006 W'
+ * coord.dms() // '40 42 46.08 N / 74 0 21.6 W'
+ * ```
+ *
+ * @example
+ * ```typescript
  * const create = createCoordinate(coordinateSystems.ddm, 'LONLAT')
+ * const coord = create('-74 0.36 / 40 42.768')
+ * coord.ddm('LATLON') // '40 42.768 N / 74 0.36 W'
+ * ```
  */
-declare function createCoordinate(initSystem?: CoordinateSystem, initFormat?: Format): (input: string) => Readonly<Coordinate>;
+declare function createCoordinate(initSystem?: CoordinateSystem, initFormat?: Format): (input: CoordinateInput) => Coordinate;
 //#endregion
-export { coordinateSystems, createCoordinate };
+export { type CoordinateInput, type CoordinateObject, type CoordinateTuple, type LatLonTuple, type LonLatTuple, coordinateSystems, createCoordinate };
 //# sourceMappingURL=coordinate.d.ts.map

package/dist/coordinates/coordinate.js

@@ -11,6 +11,8 @@
  */
 
 
+import { isCoordinateTuple, normalizeObjectToLatLon, tupleToLatLon } from "./latlon/internal/normalize.js";
+import { validateNumericCoordinate } from "./latlon/internal/validate.js";
 import { FORMATS_DEFAULT, SYMBOLS } from "./latlon/internal/index.js";
 import { systemDecimalDegrees } from "./latlon/decimal-degrees/system.js";
 import { systemDegreesDecimalMinutes } from "./latlon/degrees-decimal-minutes/system.js";
@@ -20,6 +22,28 @@ import { systemMGRS } from "./mgrs/system.js";
 import { systemUTM } from "./utm/system.js";
 
 //#region src/coordinates/coordinate.ts
+/**
+* Available coordinate systems for parsing, converting, and formatting geographic coordinates.
+*
+* Provides five coordinate notation systems:
+* - dd: Decimal Degrees
+* - ddm: Degrees Decimal Minutes
+* - dms: Degrees Minutes Seconds
+* - mgrs: Military Grid Reference System
+* - utm: Universal Transverse Mercator
+*
+* @example
+* ```typescript
+* const create = createCoordinate(coordinateSystems.dd, 'LATLON');
+* const coord = create('40.7128 / -74.0060');
+* ```
+*
+* @example
+* ```typescript
+* const createMGRS = createCoordinate(coordinateSystems.mgrs);
+* const coord = createMGRS('18T WL 80000 00000');
+* ```
+*/
 const coordinateSystems = Object.freeze({
 	dd: systemDecimalDegrees,
 	ddm: systemDegreesDecimalMinutes,
@@ -37,42 +61,108 @@ const freezeCoordinate = (errors, to, raw, valid) => Object.freeze({
 	raw,
 	valid
 });
+const errorCoordinate = (errors) => freezeCoordinate(errors, () => "", {}, false);
+const createFormatter = (raw, cachedValues, initSystem, initFormat) => (system = initSystem, format = initFormat) => {
+	let cache = cachedValues.get(system);
+	if (!cache?.[format]) {
+		if (!cache) {
+			cache = {};
+			cachedValues.set(system, cache);
+		}
+		cache[format] = system.toFormat(format, [raw[format.slice(0, 3)], raw[format.slice(3)]]);
+	}
+	return cache[format];
+};
 /**
 * Create a coordinate object enabling: lexing, parsing, validation, and
 * formatting in alternative systems and formats. The system and format will be
 * used for validation and eventually for output as defaults if no alternatives
 * are provided.
 *
-* @param initSystem dd, ddm, dms, mgrs, or utm of coordinateSystems
+* @param initSystem - Coordinate system to use for parsing (dd, ddm, dms, mgrs, or utm from coordinateSystems). Defaults to Decimal Degrees.
+* @param initFormat - Coordinate format ordering (LATLON or LONLAT). Defaults to LATLON.
+* @returns Function that accepts coordinate string and returns Coordinate object with formatters.
 *
 * @remarks
 * pure function
 *
 * @example
+* ```typescript
 * const create = createCoordinate(coordinateSystems.dd, 'LATLON')
+* const coord = create('40.7128 / -74.0060')
+* coord.dd() // '40.7128 N / 74.006 W'
+* coord.dms() // '40 42 46.08 N / 74 0 21.6 W'
+* ```
+*
+* @example
+* ```typescript
 * const create = createCoordinate(coordinateSystems.ddm, 'LONLAT')
+* const coord = create('-74 0.36 / 40 42.768')
+* coord.ddm('LATLON') // '40 42.768 N / 74 0.36 W'
+* ```
 */
 function createCoordinate(initSystem = coordinateSystems.dd, initFormat = FORMATS_DEFAULT) {
-	return (input) => {
+	function normalizeString(input) {
 		let tokens;
 		let errors;
 		try {
 			[tokens, errors] = initSystem.parse(initFormat, input);
 			if (errors.length) throw errors;
 		} catch (errors$1) {
-			return freezeCoordinate(errors$1, () => "", {}, false);
+			return {
+				valid: false,
+				errors: errors$1
+			};
+		}
+		const cachedValues = new Map([[initSystem, createCache(initFormat, initSystem === systemMGRS ? input : tokens.join(" "))]]);
+		const dividerIndex = tokens.indexOf(SYMBOLS.DIVIDER);
+		return {
+			valid: true,
+			raw: {
+				[initFormat.slice(0, 3)]: initSystem.toFloat(tokens.slice(0, dividerIndex)),
+				[initFormat.slice(3)]: initSystem.toFloat(tokens.slice(dividerIndex + 1))
+			},
+			cachedValues
+		};
+	}
+	function normalizeNumeric(lat, lon) {
+		const errors = validateNumericCoordinate(lat, lon);
+		if (errors.length) return {
+			valid: false,
+			errors
+		};
+		return {
+			valid: true,
+			raw: {
+				LAT: lat,
+				LON: lon
+			},
+			cachedValues: /* @__PURE__ */ new Map()
+		};
+	}
+	function normalize(input) {
+		if (typeof input === "string") return normalizeString(input);
+		if (isCoordinateTuple(input)) {
+			const { lat, lon } = tupleToLatLon(initFormat, input);
+			return normalizeNumeric(lat, lon);
 		}
-		const cachedValues = { [initSystem.name]: createCache(initFormat, initSystem.name === systemMGRS.name ? input : tokens.join(" ")) };
-		const raw = Object.fromEntries([[initFormat.slice(0, 3), initSystem.toFloat(tokens.slice(0, tokens.indexOf(SYMBOLS.DIVIDER)))], [initFormat.slice(3), initSystem.toFloat(tokens.slice(1 + tokens.indexOf(SYMBOLS.DIVIDER)))]]);
-		function to(system = initSystem, format = initFormat) {
-			const key = system.name;
-			if (!cachedValues[key]?.[format]) cachedValues[key] = {
-				...cachedValues[key],
-				[format]: system.toFormat(format, [format.slice(0, 3), format.slice(3)].map((key$1) => raw[key$1]))
+		if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+			const result = normalizeObjectToLatLon(input);
+			if (result === null) return {
+				valid: false,
+				errors: ["[ERROR] Invalid coordinate object; object must contain valid latitude and longitude properties."]
 			};
-			return cachedValues[key][format];
+			return normalizeNumeric(result.lat, result.lon);
 		}
-		return freezeCoordinate([], to, raw, true);
+		return {
+			valid: false,
+			errors: ["[ERROR] Invalid coordinate input; expected a string, [lat, lon] tuple, or { lat, lon } object."]
+		};
+	}
+	return (input) => {
+		const result = normalize(input);
+		if (!result.valid) return errorCoordinate(result.errors);
+		return freezeCoordinate([], createFormatter(result.raw, result.cachedValues, initSystem, initFormat), result.raw, true);
 	};
 }
 

package/dist/coordinates/coordinate.js.map

@@ -1 +1 @@
-{"version":3,"file":"coordinate.js","names":["tokens: Tokens","errors: Errors","errors","key"],"sources":["../../src/coordinates/coordinate.ts"],"sourcesContent":["/*\n * Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { systemDecimalDegrees } from './latlon/decimal-degrees/system';\nimport { systemDegreesDecimalMinutes } from './latlon/degrees-decimal-minutes/system';\nimport { systemDegreesMinutesSeconds } from './latlon/degrees-minutes-seconds/system';\nimport {\n  type Axes,\n  type Errors,\n  FORMATS_DEFAULT,\n  type Format,\n  SYMBOLS,\n} from './latlon/internal';\nimport {\n  type CoordinateCache,\n  createCache,\n} from './latlon/internal/create-cache';\nimport { systemMGRS } from './mgrs/system';\nimport { systemUTM } from './utm/system';\nimport type { CoordinateSystem } from './latlon/internal/coordinate-system';\nimport type { Tokens } from './latlon/internal/lexer';\n\ntype Coordinate = {\n  /** {@interitDoc Formatter} */\n  dd: Formatter;\n  /** {@interitDoc Formatter} */\n  ddm: Formatter;\n  /** {@interitDoc Formatter} */\n  dms: Formatter;\n  /** {@interitDoc Formatter} */\n  mgrs: Formatter;\n  /** {@interitDoc Formatter} */\n  utm: Formatter;\n  errors: string[];\n  raw: CoordinateInternalValue;\n  valid: boolean;\n};\n\n// biome-ignore lint/style/useNamingConvention: consistency with Axes type\ntype CoordinateInternalValue = { LAT: number; LON: number };\n\n/**\n * Output a string value of a coordinate using an available system. The\n * original value is preserved without conversion to an internal\n * representation - Decimal Degrees - to prevent the possibility of\n * rounding errors. All alternative values are computed from a common\n * internal value to reduce complexity.\n *\n * @link https://en.wikipedia.org/wiki/Coordinate_system\n *\n * @remarks\n * pure function\n *\n * @example\n * const create = createCoordinate(coordinateSystems.dd, 'LATLON')\n * const coord = create('89.765432109 / 123.456789012')\n *\n * // honors the instantiation format 'LATLON'\n * coord.dd() === '89.765432109 N / 123.456789012 E'\n * coord.ddm() === '89 45.92592654 N / 123 27.40734072 E'\n * coord.dms() === '89 45 55.5555924 N / 123 27 24.4404432 E'\n *\n * // change format to 'LONLAT'\n * coord.dms('LONLAT') === '123 27 24.4404432 E / 89 45 55.5555924 N'\n */\ntype Formatter = (f?: Format) => string;\n\ntype ToFloatArg = Parameters<CoordinateSystem['toFloat']>[0];\n\ntype OutputCache = Record<keyof typeof coordinateSystems, CoordinateCache>;\n\nexport const coordinateSystems = Object.freeze({\n  dd: systemDecimalDegrees,\n  ddm: systemDegreesDecimalMinutes,\n  dms: systemDegreesMinutesSeconds,\n  mgrs: systemMGRS,\n  utm: systemUTM,\n} as const);\n\nconst freezeCoordinate = (\n  errors: Coordinate['errors'],\n  to: (s?: CoordinateSystem, f?: Format) => string,\n  raw: CoordinateInternalValue,\n  valid: Coordinate['valid'],\n) =>\n  Object.freeze({\n    dd: (format?: Format) => to(systemDecimalDegrees, format),\n    ddm: (format?: Format) => to(systemDegreesDecimalMinutes, format),\n    dms: (format?: Format) => to(systemDegreesMinutesSeconds, format),\n    mgrs: (format?: Format) => to(systemMGRS, format),\n    utm: (format?: Format) => to(systemUTM, format),\n    errors,\n    raw,\n    valid,\n  } as Coordinate);\n\n/**\n * Create a coordinate object enabling: lexing, parsing, validation, and\n * formatting in alternative systems and formats. The system and format will be\n * used for validation and eventually for output as defaults if no alternatives\n * are provided.\n *\n * @param initSystem dd, ddm, dms, mgrs, or utm of coordinateSystems\n *\n * @remarks\n * pure function\n *\n * @example\n * const create = createCoordinate(coordinateSystems.dd, 'LATLON')\n * const create = createCoordinate(coordinateSystems.ddm, 'LONLAT')\n */\nexport function createCoordinate(\n  initSystem: CoordinateSystem = coordinateSystems.dd,\n  initFormat: Format = FORMATS_DEFAULT,\n) {\n  return (input: string) => {\n    let tokens: Tokens;\n    let errors: Errors;\n\n    try {\n      [tokens, errors] = initSystem.parse(initFormat, input);\n\n      if (errors.length) {\n        throw errors;\n      }\n    } catch (errors) {\n      return freezeCoordinate(\n        errors as Coordinate['errors'],\n        () => '',\n        {} as CoordinateInternalValue,\n        false,\n      );\n    }\n\n    // start with the original value for the original system in the original format\n    // other values will be computed as needed and cached per request\n    const cachedValues = {\n      [initSystem.name]: createCache(\n        initFormat,\n        // because mgrs doesn't have two formats: LATLON v LONLAT\n        initSystem.name === systemMGRS.name ? input : tokens.join(' '),\n      ),\n    } as OutputCache;\n\n    // Create the \"internal\" representation - Decimal Degrees - for\n    // consistency and ease of computation; all systems expect to\n    // start from a common starting point to reduce complexity.\n    const raw = Object.fromEntries([\n      [\n        initFormat.slice(0, 3),\n        initSystem.toFloat(\n          tokens.slice(0, tokens.indexOf(SYMBOLS.DIVIDER)) as ToFloatArg,\n        ),\n      ],\n      [\n        initFormat.slice(3),\n        initSystem.toFloat(\n          tokens.slice(1 + tokens.indexOf(SYMBOLS.DIVIDER)) as ToFloatArg,\n        ),\n      ],\n    ]) as CoordinateInternalValue;\n\n    function to(\n      system: CoordinateSystem = initSystem,\n      format: Format = initFormat,\n    ) {\n      const key = system.name as keyof typeof coordinateSystems;\n\n      if (!cachedValues[key]?.[format]) {\n        // cache \"miss\" - fill the missing value in the cache before returning it\n\n        // update the cache to include the newly computed value\n        cachedValues[key] = {\n          ...cachedValues[key],\n          // use the Format to build the object, correctly pairing the halves of\n          // the coordinate value with their labels\n          [format]: system.toFormat(\n            format,\n            ([format.slice(0, 3), format.slice(3)] as Axes[]).map(\n              (key) => raw[key],\n            ) as [number, number],\n          ),\n        };\n      }\n\n      return cachedValues[key][format];\n    }\n\n    return freezeCoordinate([] as Coordinate['errors'], to, raw, true);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAgFA,MAAa,oBAAoB,OAAO,OAAO;CAC7C,IAAI;CACJ,KAAK;CACL,KAAK;CACL,MAAM;CACN,KAAK;CACN,CAAU;AAEX,MAAM,oBACJ,QACA,IACA,KACA,UAEA,OAAO,OAAO;CACZ,KAAK,WAAoB,GAAG,sBAAsB,OAAO;CACzD,MAAM,WAAoB,GAAG,6BAA6B,OAAO;CACjE,MAAM,WAAoB,GAAG,6BAA6B,OAAO;CACjE,OAAO,WAAoB,GAAG,YAAY,OAAO;CACjD,MAAM,WAAoB,GAAG,WAAW,OAAO;CAC/C;CACA;CACA;CACD,CAAe;;;;;;;;;;;;;;;;AAiBlB,SAAgB,iBACd,aAA+B,kBAAkB,IACjD,aAAqB,iBACrB;AACA,SAAQ,UAAkB;EACxB,IAAIA;EACJ,IAAIC;AAEJ,MAAI;AACF,IAAC,QAAQ,UAAU,WAAW,MAAM,YAAY,MAAM;AAEtD,OAAI,OAAO,OACT,OAAM;WAEDC,UAAQ;AACf,UAAO,iBACLA,gBACM,IACN,EAAE,EACF,MACD;;EAKH,MAAM,eAAe,GAClB,WAAW,OAAO,YACjB,YAEA,WAAW,SAAS,WAAW,OAAO,QAAQ,OAAO,KAAK,IAAI,CAC/D,EACF;EAKD,MAAM,MAAM,OAAO,YAAY,CAC7B,CACE,WAAW,MAAM,GAAG,EAAE,EACtB,WAAW,QACT,OAAO,MAAM,GAAG,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CACjD,CACF,EACD,CACE,WAAW,MAAM,EAAE,EACnB,WAAW,QACT,OAAO,MAAM,IAAI,OAAO,QAAQ,QAAQ,QAAQ,CAAC,CAClD,CACF,CACF,CAAC;EAEF,SAAS,GACP,SAA2B,YAC3B,SAAiB,YACjB;GACA,MAAM,MAAM,OAAO;AAEnB,OAAI,CAAC,aAAa,OAAO,QAIvB,cAAa,OAAO;IAClB,GAAG,aAAa;KAGf,SAAS,OAAO,SACf,QACC,CAAC,OAAO,MAAM,GAAG,EAAE,EAAE,OAAO,MAAM,EAAE,CAAC,CAAY,KAC/C,UAAQ,IAAIC,OACd,CACF;IACF;AAGH,UAAO,aAAa,KAAK;;AAG3B,SAAO,iBAAiB,EAAE,EAA0B,IAAI,KAAK,KAAK"}
+{"version":3,"file":"coordinate.js","names":["tokens: Tokens","errors: Errors","errors","cachedValues: OutputCache"],"sources":["../../src/coordinates/coordinate.ts"],"sourcesContent":["/*\n * Copyright 2024 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nimport { systemDecimalDegrees } from './latlon/decimal-degrees/system';\nimport { systemDegreesDecimalMinutes } from './latlon/degrees-decimal-minutes/system';\nimport { systemDegreesMinutesSeconds } from './latlon/degrees-minutes-seconds/system';\nimport {\n  type Axes,\n  type CoordinateInput,\n  type CoordinateInternalValue,\n  type CoordinateObject,\n  type Errors,\n  FORMATS_DEFAULT,\n  type Format,\n  isCoordinateTuple,\n  normalizeObjectToLatLon,\n  SYMBOLS,\n  tupleToLatLon,\n  validateNumericCoordinate,\n} from './latlon/internal';\n\nexport type {\n  CoordinateInput,\n  CoordinateObject,\n  CoordinateTuple,\n  LatLonTuple,\n  LonLatTuple,\n} from './latlon/internal';\n\nimport {\n  type CoordinateCache,\n  createCache,\n} from './latlon/internal/create-cache';\nimport { systemMGRS } from './mgrs/system';\nimport { systemUTM } from './utm/system';\nimport type { CoordinateSystem } from './latlon/internal/coordinate-system';\nimport type { Tokens } from './latlon/internal/lexer';\n\ntype Coordinate = {\n  /** {@interitDoc Formatter} */\n  dd: Formatter;\n  /** {@interitDoc Formatter} */\n  ddm: Formatter;\n  /** {@interitDoc Formatter} */\n  dms: Formatter;\n  /** {@interitDoc Formatter} */\n  mgrs: Formatter;\n  /** {@interitDoc Formatter} */\n  utm: Formatter;\n  errors: string[];\n  raw: CoordinateInternalValue;\n  valid: boolean;\n};\n\n/**\n * Output a string value of a coordinate using an available system. The\n * original value is preserved without conversion to an internal\n * representation - Decimal Degrees - to prevent the possibility of\n * rounding errors. All alternative values are computed from a common\n * internal value to reduce complexity.\n *\n * @link https://en.wikipedia.org/wiki/Coordinate_system\n *\n * @remarks\n * pure function\n *\n * @example\n * ```typescript\n * const create = createCoordinate(coordinateSystems.dd, 'LATLON')\n * const coord = create('89.765432109 / 123.456789012')\n *\n * // honors the instantiation format 'LATLON'\n * coord.dd() === '89.765432109 N / 123.456789012 E'\n * coord.ddm() === '89 45.92592654 N / 123 27.40734072 E'\n * coord.dms() === '89 45 55.5555924 N / 123 27 24.4404432 E'\n *\n * // change format to 'LONLAT'\n * coord.dms('LONLAT') === '123 27 24.4404432 E / 89 45 55.5555924 N'\n * ```\n */\ntype Formatter = (f?: Format) => string;\n\ntype ToFloatArg = Parameters<CoordinateSystem['toFloat']>[0];\n\ntype OutputCache = Map<CoordinateSystem, CoordinateCache>;\n\n/**\n * Available coordinate systems for parsing, converting, and formatting geographic coordinates.\n *\n * Provides five coordinate notation systems:\n * - dd: Decimal Degrees\n * - ddm: Degrees Decimal Minutes\n * - dms: Degrees Minutes Seconds\n * - mgrs: Military Grid Reference System\n * - utm: Universal Transverse Mercator\n *\n * @example\n * ```typescript\n * const create = createCoordinate(coordinateSystems.dd, 'LATLON');\n * const coord = create('40.7128 / -74.0060');\n * ```\n *\n * @example\n * ```typescript\n * const createMGRS = createCoordinate(coordinateSystems.mgrs);\n * const coord = createMGRS('18T WL 80000 00000');\n * ```\n */\nexport const coordinateSystems = Object.freeze({\n  dd: systemDecimalDegrees,\n  ddm: systemDegreesDecimalMinutes,\n  dms: systemDegreesMinutesSeconds,\n  mgrs: systemMGRS,\n  utm: systemUTM,\n} as const);\n\nconst freezeCoordinate = (\n  errors: Coordinate['errors'],\n  to: (s?: CoordinateSystem, f?: Format) => string,\n  raw: CoordinateInternalValue,\n  valid: Coordinate['valid'],\n) =>\n  Object.freeze({\n    dd: (format?: Format) => to(systemDecimalDegrees, format),\n    ddm: (format?: Format) => to(systemDegreesDecimalMinutes, format),\n    dms: (format?: Format) => to(systemDegreesMinutesSeconds, format),\n    mgrs: (format?: Format) => to(systemMGRS, format),\n    utm: (format?: Format) => to(systemUTM, format),\n    errors,\n    raw,\n    valid,\n  } as Coordinate);\n\nconst errorCoordinate = (errors: string[]) =>\n  freezeCoordinate(errors, () => '', {} as CoordinateInternalValue, false);\n\nconst createFormatter =\n  (\n    raw: CoordinateInternalValue,\n    cachedValues: OutputCache,\n    initSystem: CoordinateSystem,\n    initFormat: Format,\n  ) =>\n  (system: CoordinateSystem = initSystem, format: Format = initFormat) => {\n    let cache = cachedValues.get(system);\n\n    if (!cache?.[format]) {\n      if (!cache) {\n        cache = {} as CoordinateCache;\n        cachedValues.set(system, cache);\n      }\n\n      cache[format] = system.toFormat(format, [\n        raw[format.slice(0, 3) as Axes],\n        raw[format.slice(3) as Axes],\n      ] as [number, number]);\n    }\n\n    return cache[format];\n  };\n\ntype NormalizedResult =\n  | { valid: true; raw: CoordinateInternalValue; cachedValues: OutputCache }\n  | { valid: false; errors: string[] };\n\n/**\n * Create a coordinate object enabling: lexing, parsing, validation, and\n * formatting in alternative systems and formats. The system and format will be\n * used for validation and eventually for output as defaults if no alternatives\n * are provided.\n *\n * @param initSystem - Coordinate system to use for parsing (dd, ddm, dms, mgrs, or utm from coordinateSystems). Defaults to Decimal Degrees.\n * @param initFormat - Coordinate format ordering (LATLON or LONLAT). Defaults to LATLON.\n * @returns Function that accepts coordinate string and returns Coordinate object with formatters.\n *\n * @remarks\n * pure function\n *\n * @example\n * ```typescript\n * const create = createCoordinate(coordinateSystems.dd, 'LATLON')\n * const coord = create('40.7128 / -74.0060')\n * coord.dd() // '40.7128 N / 74.006 W'\n * coord.dms() // '40 42 46.08 N / 74 0 21.6 W'\n * ```\n *\n * @example\n * ```typescript\n * const create = createCoordinate(coordinateSystems.ddm, 'LONLAT')\n * const coord = create('-74 0.36 / 40 42.768')\n * coord.ddm('LATLON') // '40 42.768 N / 74 0.36 W'\n * ```\n */\nexport function createCoordinate(\n  initSystem: CoordinateSystem = coordinateSystems.dd,\n  initFormat: Format = FORMATS_DEFAULT,\n) {\n  function normalizeString(input: string): NormalizedResult {\n    let tokens: Tokens;\n    let errors: Errors;\n\n    try {\n      [tokens, errors] = initSystem.parse(initFormat, input);\n\n      if (errors.length) {\n        throw errors;\n      }\n    } catch (errors) {\n      return { valid: false, errors: errors as string[] };\n    }\n\n    const cachedValues: OutputCache = new Map([\n      [\n        initSystem,\n        createCache(\n          initFormat,\n          initSystem === systemMGRS ? input : tokens.join(' '),\n        ),\n      ],\n    ]);\n\n    const dividerIndex = tokens.indexOf(SYMBOLS.DIVIDER);\n    const raw = {\n      [initFormat.slice(0, 3)]: initSystem.toFloat(\n        tokens.slice(0, dividerIndex) as ToFloatArg,\n      ),\n      [initFormat.slice(3)]: initSystem.toFloat(\n        tokens.slice(dividerIndex + 1) as ToFloatArg,\n      ),\n    } as CoordinateInternalValue;\n\n    return { valid: true, raw, cachedValues };\n  }\n\n  function normalizeNumeric(lat: number, lon: number): NormalizedResult {\n    const errors = validateNumericCoordinate(lat, lon);\n\n    if (errors.length) {\n      return { valid: false, errors };\n    }\n\n    return {\n      valid: true,\n      raw: { LAT: lat, LON: lon },\n      cachedValues: new Map(),\n    };\n  }\n\n  function normalize(input: CoordinateInput): NormalizedResult {\n    if (typeof input === 'string') {\n      return normalizeString(input);\n    }\n\n    if (isCoordinateTuple(input)) {\n      const { lat, lon } = tupleToLatLon(initFormat, input);\n      return normalizeNumeric(lat, lon);\n    }\n\n    if (typeof input === 'object' && input !== null && !Array.isArray(input)) {\n      const result = normalizeObjectToLatLon(input as CoordinateObject);\n\n      if (result === null) {\n        return {\n          valid: false,\n          errors: [\n            '[ERROR] Invalid coordinate object; object must contain valid latitude and longitude properties.',\n          ],\n        };\n      }\n\n      return normalizeNumeric(result.lat, result.lon);\n    }\n\n    return {\n      valid: false,\n      errors: [\n        '[ERROR] Invalid coordinate input; expected a string, [lat, lon] tuple, or { lat, lon } object.',\n      ],\n    };\n  }\n\n  return (input: CoordinateInput): Coordinate => {\n    const result = normalize(input);\n\n    if (!result.valid) {\n      return errorCoordinate(result.errors);\n    }\n\n    const to = createFormatter(\n      result.raw,\n      result.cachedValues,\n      initSystem,\n      initFormat,\n    );\n\n    return freezeCoordinate([], to, result.raw, true);\n  };\n}\n"],"mappings":"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"}

package/dist/coordinates/latlon/decimal-degrees/formatter.d.ts

@@ -13,6 +13,26 @@
 import { FormatOptions } from "../internal/format.js";
 
 //#region src/coordinates/latlon/decimal-degrees/formatter.d.ts
+
+/**
+ * Formats latitude/longitude coordinates in decimal degrees notation.
+ *
+ * @param coordinates - Tuple of [latitude, longitude] values.
+ * @param config - Optional formatting configuration.
+ * @returns Formatted coordinate string in decimal degrees format.
+ *
+ * @example
+ * ```typescript
+ * formatDecimalDegrees([37.7749, -122.4194]);
+ * // '37.774900° N, 122.419400° W'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * formatDecimalDegrees([37.7749, -122.4194], { separator: ' / ' });
+ * // '37.774900° N / 122.419400° W'
+ * ```
+ */
 declare const formatDecimalDegrees: (coordinates: [number, number], config?: FormatOptions) => string;
 //#endregion
 export { formatDecimalDegrees };

package/dist/coordinates/latlon/decimal-degrees/formatter.js

@@ -14,9 +14,47 @@
 import { createFormatter } from "../internal/format.js";
 
 //#region src/coordinates/latlon/decimal-degrees/formatter.ts
+/**
+* Converts a coordinate value to decimal degrees format.
+*
+* @param num - The coordinate value to format.
+* @param withOrdinal - Whether to use absolute value (when ordinal directions are shown separately).
+* @returns Formatted coordinate string with degree symbol and 6 decimal places.
+*
+* @example
+* ```typescript
+* toDecimalDegrees(45.123456);
+* // '45.123456°'
+* ```
+*
+* @example
+* ```typescript
+* toDecimalDegrees(-122.4194, true);
+* // '122.419400°'
+* ```
+*/
 const toDecimalDegrees = (num, withOrdinal) => {
 	return `${(withOrdinal ? Math.abs(num) : num).toFixed(6)}°`;
 };
+/**
+* Formats latitude/longitude coordinates in decimal degrees notation.
+*
+* @param coordinates - Tuple of [latitude, longitude] values.
+* @param config - Optional formatting configuration.
+* @returns Formatted coordinate string in decimal degrees format.
+*
+* @example
+* ```typescript
+* formatDecimalDegrees([37.7749, -122.4194]);
+* // '37.774900° N, 122.419400° W'
+* ```
+*
+* @example
+* ```typescript
+* formatDecimalDegrees([37.7749, -122.4194], { separator: ' / ' });
+* // '37.774900° N / 122.419400° W'
+* ```
+*/
 const formatDecimalDegrees = createFormatter(toDecimalDegrees);
 
 //#endregion