@accelint/geo 0.5.1 → 0.6.0

package/dist/coordinates/latlon/degrees-decimal-minutes/system.d.ts

@@ -13,6 +13,38 @@
 import { CoordinateSystem } from "../internal/coordinate-system.js";
 
 //#region src/coordinates/latlon/degrees-decimal-minutes/system.d.ts
+
+/**
+ * Degrees Decimal Minutes coordinate system implementation.
+ *
+ * Provides parsing, conversion, and formatting for coordinates in degrees decimal minutes notation.
+ * Coordinates are expressed as integer degrees and decimal minutes (e.g., 37° 46.4940' N).
+ *
+ * @property name - Human-readable name of the coordinate system.
+ * @property parse - Parses degrees decimal minutes coordinate strings.
+ * @property toFloat - Converts parsed coordinate components to floating point numbers.
+ * @property toFormat - Formats numeric coordinates back to degrees decimal minutes string.
+ *
+ * @example
+ * ```typescript
+ * // Parse a coordinate string
+ * const [coords, errors] = systemDegreesDecimalMinutes.parse('37° 46.4940' N / 122° 25.1640' W', 'LATLON');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Convert to float
+ * const lat = systemDegreesDecimalMinutes.toFloat(['37', '46.4940', 'N']);
+ * // 37.7749
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Format to string
+ * const formatted = systemDegreesDecimalMinutes.toFormat('LATLON', [37.7749, -122.4194]);
+ * // '37 46.494 N / 122 25.164 W'
+ * ```
+ */
 declare const systemDegreesDecimalMinutes: CoordinateSystem;
 //#endregion
 export { systemDegreesDecimalMinutes };

package/dist/coordinates/latlon/degrees-decimal-minutes/system.js

@@ -15,6 +15,37 @@ import { BEARINGS, SYMBOLS, SYMBOL_PATTERNS } from "../internal/index.js";
 import { parseDegreesDecimalMinutes } from "./parser.js";
 
 //#region src/coordinates/latlon/degrees-decimal-minutes/system.ts
+/**
+* Degrees Decimal Minutes coordinate system implementation.
+*
+* Provides parsing, conversion, and formatting for coordinates in degrees decimal minutes notation.
+* Coordinates are expressed as integer degrees and decimal minutes (e.g., 37° 46.4940' N).
+*
+* @property name - Human-readable name of the coordinate system.
+* @property parse - Parses degrees decimal minutes coordinate strings.
+* @property toFloat - Converts parsed coordinate components to floating point numbers.
+* @property toFormat - Formats numeric coordinates back to degrees decimal minutes string.
+*
+* @example
+* ```typescript
+* // Parse a coordinate string
+* const [coords, errors] = systemDegreesDecimalMinutes.parse('37° 46.4940' N / 122° 25.1640' W', 'LATLON');
+* ```
+*
+* @example
+* ```typescript
+* // Convert to float
+* const lat = systemDegreesDecimalMinutes.toFloat(['37', '46.4940', 'N']);
+* // 37.7749
+* ```
+*
+* @example
+* ```typescript
+* // Format to string
+* const formatted = systemDegreesDecimalMinutes.toFormat('LATLON', [37.7749, -122.4194]);
+* // '37 46.494 N / 122 25.164 W'
+* ```
+*/
 const systemDegreesDecimalMinutes = {
 	name: "Degrees Decimal Minutes",
 	parse: parseDegreesDecimalMinutes,

package/dist/coordinates/latlon/degrees-decimal-minutes/system.js.map

@@ -1 +1 @@
-{"version":3,"file":"system.js","names":["systemDegreesDecimalMinutes: CoordinateSystem"],"sources":["../../../../src/coordinates/latlon/degrees-decimal-minutes/system.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\nimport {\n  BEARINGS,\n  type Compass,\n  type Format,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { parseDegreesDecimalMinutes } from './parser';\nimport type { CoordinateSystem } from '../internal/coordinate-system';\n\nexport const systemDegreesDecimalMinutes: CoordinateSystem = {\n  name: 'Degrees Decimal Minutes',\n\n  parse: parseDegreesDecimalMinutes,\n\n  toFloat(arg) {\n    const [degrees, minutes, bear] = arg as [string, string, Compass];\n\n    return Number.parseFloat(\n      (\n        (Number.parseFloat(degrees) + Number.parseFloat(minutes) / 60) *\n        (SYMBOL_PATTERNS.NEGATIVE_BEARINGS.test(bear) ? -1 : 1)\n      ).toFixed(9),\n    );\n  },\n\n  toFormat(format: Format, [left, right]: [number, number]) {\n    return [left, right]\n      .map((num, index) => {\n        const abs = Math.abs(num);\n        const deg = Math.floor(abs);\n        const min = Number.parseFloat(((abs - deg) * 60).toFixed(10));\n\n        return `${deg} ${min} ${BEARINGS[format][index as 0 | 1][+(num < 0)]}`;\n      })\n      .join(` ${SYMBOLS.DIVIDER} `);\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAuBA,MAAaA,8BAAgD;CAC3D,MAAM;CAEN,OAAO;CAEP,QAAQ,KAAK;EACX,MAAM,CAAC,SAAS,SAAS,QAAQ;AAEjC,SAAO,OAAO,aAET,OAAO,WAAW,QAAQ,GAAG,OAAO,WAAW,QAAQ,GAAG,OAC1D,gBAAgB,kBAAkB,KAAK,KAAK,GAAG,KAAK,IACrD,QAAQ,EAAE,CACb;;CAGH,SAAS,QAAgB,CAAC,MAAM,QAA0B;AACxD,SAAO,CAAC,MAAM,MAAM,CACjB,KAAK,KAAK,UAAU;GACnB,MAAM,MAAM,KAAK,IAAI,IAAI;GACzB,MAAM,MAAM,KAAK,MAAM,IAAI;AAG3B,UAAO,GAAG,IAAI,GAFF,OAAO,aAAa,MAAM,OAAO,IAAI,QAAQ,GAAG,CAAC,CAExC,GAAG,SAAS,QAAQ,OAAgB,EAAE,MAAM;IACjE,CACD,KAAK,IAAI,QAAQ,QAAQ,GAAG;;CAElC"}
+{"version":3,"file":"system.js","names":["systemDegreesDecimalMinutes: CoordinateSystem"],"sources":["../../../../src/coordinates/latlon/degrees-decimal-minutes/system.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\nimport {\n  BEARINGS,\n  type Compass,\n  type Format,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { parseDegreesDecimalMinutes } from './parser';\nimport type { CoordinateSystem } from '../internal/coordinate-system';\n\n/**\n * Degrees Decimal Minutes coordinate system implementation.\n *\n * Provides parsing, conversion, and formatting for coordinates in degrees decimal minutes notation.\n * Coordinates are expressed as integer degrees and decimal minutes (e.g., 37° 46.4940' N).\n *\n * @property name - Human-readable name of the coordinate system.\n * @property parse - Parses degrees decimal minutes coordinate strings.\n * @property toFloat - Converts parsed coordinate components to floating point numbers.\n * @property toFormat - Formats numeric coordinates back to degrees decimal minutes string.\n *\n * @example\n * ```typescript\n * // Parse a coordinate string\n * const [coords, errors] = systemDegreesDecimalMinutes.parse('37° 46.4940' N / 122° 25.1640' W', 'LATLON');\n * ```\n *\n * @example\n * ```typescript\n * // Convert to float\n * const lat = systemDegreesDecimalMinutes.toFloat(['37', '46.4940', 'N']);\n * // 37.7749\n * ```\n *\n * @example\n * ```typescript\n * // Format to string\n * const formatted = systemDegreesDecimalMinutes.toFormat('LATLON', [37.7749, -122.4194]);\n * // '37 46.494 N / 122 25.164 W'\n * ```\n */\nexport const systemDegreesDecimalMinutes: CoordinateSystem = {\n  name: 'Degrees Decimal Minutes',\n\n  parse: parseDegreesDecimalMinutes,\n\n  toFloat(arg) {\n    const [degrees, minutes, bear] = arg as [string, string, Compass];\n\n    return Number.parseFloat(\n      (\n        (Number.parseFloat(degrees) + Number.parseFloat(minutes) / 60) *\n        (SYMBOL_PATTERNS.NEGATIVE_BEARINGS.test(bear) ? -1 : 1)\n      ).toFixed(9),\n    );\n  },\n\n  toFormat(format: Format, [left, right]: [number, number]) {\n    return [left, right]\n      .map((num, index) => {\n        const abs = Math.abs(num);\n        const deg = Math.floor(abs);\n        const min = Number.parseFloat(((abs - deg) * 60).toFixed(10));\n\n        return `${deg} ${min} ${BEARINGS[format][index as 0 | 1][+(num < 0)]}`;\n      })\n      .join(` ${SYMBOLS.DIVIDER} `);\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAaA,8BAAgD;CAC3D,MAAM;CAEN,OAAO;CAEP,QAAQ,KAAK;EACX,MAAM,CAAC,SAAS,SAAS,QAAQ;AAEjC,SAAO,OAAO,aAET,OAAO,WAAW,QAAQ,GAAG,OAAO,WAAW,QAAQ,GAAG,OAC1D,gBAAgB,kBAAkB,KAAK,KAAK,GAAG,KAAK,IACrD,QAAQ,EAAE,CACb;;CAGH,SAAS,QAAgB,CAAC,MAAM,QAA0B;AACxD,SAAO,CAAC,MAAM,MAAM,CACjB,KAAK,KAAK,UAAU;GACnB,MAAM,MAAM,KAAK,IAAI,IAAI;GACzB,MAAM,MAAM,KAAK,MAAM,IAAI;AAG3B,UAAO,GAAG,IAAI,GAFF,OAAO,aAAa,MAAM,OAAO,IAAI,QAAQ,GAAG,CAAC,CAExC,GAAG,SAAS,QAAQ,OAAgB,EAAE,MAAM;IACjE,CACD,KAAK,IAAI,QAAQ,QAAQ,GAAG;;CAElC"}

package/dist/coordinates/latlon/degrees-minutes-seconds/formatter.d.ts

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

package/dist/coordinates/latlon/degrees-minutes-seconds/formatter.js

@@ -14,12 +14,49 @@
 import { createFormatter } from "../internal/format.js";
 
 //#region src/coordinates/latlon/degrees-minutes-seconds/formatter.ts
+/**
+* Converts a coordinate value to degrees minutes seconds format.
+*
+* @param num - The coordinate value to format.
+* @returns Formatted coordinate string with degrees, minutes, and seconds (e.g., "45° 30' 15.23″").
+*
+* @example
+* ```typescript
+* toDegreesMinutesSeconds(45.5042);
+* // '45° 30' 15.12″'
+* ```
+*
+* @example
+* ```typescript
+* toDegreesMinutesSeconds(-122.4194);
+* // '122° 25' 9.84″'
+* ```
+*/
 const toDegreesMinutesSeconds = (num) => {
 	const degrees = Math.floor(Math.abs(num));
 	const minutesFull = (Math.abs(num) - degrees) * 60;
 	const minutes = Math.floor(minutesFull);
 	return `${degrees}° ${minutes}' ${((minutesFull - minutes) * 60).toFixed(2)}″`;
 };
+/**
+* Formats latitude/longitude coordinates in degrees minutes seconds notation.
+*
+* @param coordinates - Tuple of [latitude, longitude] values.
+* @param config - Optional formatting configuration.
+* @returns Formatted coordinate string in degrees minutes seconds format.
+*
+* @example
+* ```typescript
+* formatDegreesMinutesSeconds([37.7749, -122.4194]);
+* // '37° 46' 29.64″ N, 122° 25' 9.84″ W'
+* ```
+*
+* @example
+* ```typescript
+* formatDegreesMinutesSeconds([37.7749, -122.4194], { separator: ' / ' });
+* // '37° 46' 29.64″ N / 122° 25' 9.84″ W'
+* ```
+*/
 const formatDegreesMinutesSeconds = createFormatter(toDegreesMinutesSeconds);
 
 //#endregion

package/dist/coordinates/latlon/degrees-minutes-seconds/formatter.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatter.js","names":[],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/formatter.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createFormatter } from '../internal/format';\n\nconst toDegreesMinutesSeconds = (num: number): string => {\n  const degrees = Math.floor(Math.abs(num));\n  const minutesFull = (Math.abs(num) - degrees) * 60;\n  const minutes = Math.floor(minutesFull);\n  const seconds = ((minutesFull - minutes) * 60).toFixed(2);\n\n  return `${degrees}° ${minutes}' ${seconds}″`;\n};\n\nexport const formatDegreesMinutesSeconds = createFormatter(\n  toDegreesMinutesSeconds,\n);\n"],"mappings":";;;;;;;;;;;;;;;;AAcA,MAAM,2BAA2B,QAAwB;CACvD,MAAM,UAAU,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC;CACzC,MAAM,eAAe,KAAK,IAAI,IAAI,GAAG,WAAW;CAChD,MAAM,UAAU,KAAK,MAAM,YAAY;AAGvC,QAAO,GAAG,QAAQ,IAAI,QAAQ,MAFZ,cAAc,WAAW,IAAI,QAAQ,EAAE,CAEf;;AAG5C,MAAa,8BAA8B,gBACzC,wBACD"}
+{"version":3,"file":"formatter.js","names":[],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/formatter.ts"],"sourcesContent":["/*\n * Copyright 2025 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 { createFormatter } from '../internal/format';\n\n/**\n * Converts a coordinate value to degrees minutes seconds format.\n *\n * @param num - The coordinate value to format.\n * @returns Formatted coordinate string with degrees, minutes, and seconds (e.g., \"45° 30' 15.23″\").\n *\n * @example\n * ```typescript\n * toDegreesMinutesSeconds(45.5042);\n * // '45° 30' 15.12″'\n * ```\n *\n * @example\n * ```typescript\n * toDegreesMinutesSeconds(-122.4194);\n * // '122° 25' 9.84″'\n * ```\n */\nconst toDegreesMinutesSeconds = (num: number): string => {\n  const degrees = Math.floor(Math.abs(num));\n  const minutesFull = (Math.abs(num) - degrees) * 60;\n  const minutes = Math.floor(minutesFull);\n  const seconds = ((minutesFull - minutes) * 60).toFixed(2);\n\n  return `${degrees}° ${minutes}' ${seconds}″`;\n};\n\n/**\n * Formats latitude/longitude coordinates in degrees minutes seconds notation.\n *\n * @param coordinates - Tuple of [latitude, longitude] values.\n * @param config - Optional formatting configuration.\n * @returns Formatted coordinate string in degrees minutes seconds format.\n *\n * @example\n * ```typescript\n * formatDegreesMinutesSeconds([37.7749, -122.4194]);\n * // '37° 46' 29.64″ N, 122° 25' 9.84″ W'\n * ```\n *\n * @example\n * ```typescript\n * formatDegreesMinutesSeconds([37.7749, -122.4194], { separator: ' / ' });\n * // '37° 46' 29.64″ N / 122° 25' 9.84″ W'\n * ```\n */\nexport const formatDegreesMinutesSeconds = createFormatter(\n  toDegreesMinutesSeconds,\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAM,2BAA2B,QAAwB;CACvD,MAAM,UAAU,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC;CACzC,MAAM,eAAe,KAAK,IAAI,IAAI,GAAG,WAAW;CAChD,MAAM,UAAU,KAAK,MAAM,YAAY;AAGvC,QAAO,GAAG,QAAQ,IAAI,QAAQ,MAFZ,cAAc,WAAW,IAAI,QAAQ,EAAE,CAEf;;;;;;;;;;;;;;;;;;;;;AAsB5C,MAAa,8BAA8B,gBACzC,wBACD"}

package/dist/coordinates/latlon/degrees-minutes-seconds/parser.d.ts

@@ -14,8 +14,80 @@ import { Format } from "../internal/index.js";
 import { ParseResults } from "../internal/parse.js";
 
 //#region src/coordinates/latlon/degrees-minutes-seconds/parser.d.ts
-/** Parse a Degrees Minutes Seconds coordinate. */
+type DegreesMinutesSeconds = {
+  bear: string;
+  deg: string;
+  min: string;
+  sec: string;
+};
+/**
+ * Creates an error identification function for degrees minutes seconds coordinates.
+ *
+ * Validates that degree values are integers, minutes are in range 0-59,
+ * seconds are in range 0-59.999..., and all components are properly formatted.
+ *
+ * @param format - The coordinate format (LATLON or LONLAT).
+ * @returns Function that validates coordinate components and returns parse results.
+ *
+ * @example
+ * ```typescript
+ * const validator = identifyErrors('LATLON');
+ * const result = validator({ deg: '91', min: '0', sec: '0', bear: 'N' }, 0);
+ * // [[], ['Degrees value (91) exceeds max value (90).']]
+ * ```
+ */
+declare function identifyErrors(format: Format): (arg: DegreesMinutesSeconds | undefined, i: number) => ParseResults;
+/**
+ * Identifies and organizes coordinate components from parsed tokens.
+ *
+ * Separates bearing indicators (N/S/E/W), degree values, minute values, and second values from tokens.
+ * Uses symbol patterns to identify component types and positional logic as fallback.
+ *
+ * @param half - Array of tokens representing one coordinate component.
+ * @returns Object with `bear`, `deg`, `min`, and `sec` properties, or undefined if invalid.
+ *
+ * @example
+ * ```typescript
+ * identifyPieces(['45', '30', '15.23', 'N']);
+ * // { bear: 'N', deg: '45', min: '30', sec: '15.23' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * identifyPieces(['122°', '25'', '9.84″', 'W']);
+ * // { bear: 'W', deg: '122', min: '25', sec: '9.84' }
+ * ```
+ */
+declare function identifyPieces(half: string[]): {
+  bear: string;
+  deg: string;
+  min: string;
+  sec: string;
+} | undefined;
+/**
+ * Parses a Degrees Minutes Seconds coordinate string.
+ *
+ * Accepts coordinates in degrees minutes seconds format with bearing indicators.
+ * Validates that degrees are integers, minutes are in range 0-59,
+ * seconds are in range 0-59.999..., and all components are properly formatted.
+ *
+ * @param input - Raw coordinate string to parse.
+ * @param format - Expected format (LATLON or LONLAT).
+ * @returns Parsed coordinate values or errors.
+ *
+ * @example
+ * ```typescript
+ * parseDegreesMinutesSeconds('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');
+ * // [[37.7749, -122.4194], []]
+ * ```
+ *
+ * @example
+ * ```typescript
+ * parseDegreesMinutesSeconds('45 30 15.23 N, 122 25 9.84 W');
+ * // [[45.504231, -122.419400], []]
+ * ```
+ */
 declare const parseDegreesMinutesSeconds: (format: Format, input: string) => ParseResults;
 //#endregion
-export { parseDegreesMinutesSeconds };
+export { identifyErrors as _identifyErrors, identifyPieces as _identifyPieces, parseDegreesMinutesSeconds };
 //# sourceMappingURL=parser.d.ts.map

package/dist/coordinates/latlon/degrees-minutes-seconds/parser.js

@@ -19,7 +19,9 @@ import { inRange } from "../internal/in-range.js";
 //#region src/coordinates/latlon/degrees-minutes-seconds/parser.ts
 const checks = {
 	deg: (deg, limit) => {
-		if (Number.parseFloat(deg) > limit) return `Degrees value (${deg}) exceeds max value (${limit}).`;
+		const num = Number.parseFloat(deg);
+		if (Number.isNaN(num)) return `Degrees value (${deg}) is not a valid number.`;
+		if (num > limit) return `Degrees value (${deg}) exceeds max value (${limit}).`;
 		if (/\./.test(deg)) return `Degrees value (${deg}) must not include decimal value.`;
 	},
 	min: (min) => inRange("Minutes", min, 59),
@@ -29,6 +31,22 @@ const formats = {
 	LATLON: fromTemplate(PARTIAL_PATTERNS, `degLat min secDec NS ${SYMBOLS.DIVIDER} degLon min secDec EW`),
 	LONLAT: fromTemplate(PARTIAL_PATTERNS, `degLon min secDec EW ${SYMBOLS.DIVIDER} degLat min secDec NS`)
 };
+/**
+* Creates an error identification function for degrees minutes seconds coordinates.
+*
+* Validates that degree values are integers, minutes are in range 0-59,
+* seconds are in range 0-59.999..., and all components are properly formatted.
+*
+* @param format - The coordinate format (LATLON or LONLAT).
+* @returns Function that validates coordinate components and returns parse results.
+*
+* @example
+* ```typescript
+* const validator = identifyErrors('LATLON');
+* const result = validator({ deg: '91', min: '0', sec: '0', bear: 'N' }, 0);
+* // [[], ['Degrees value (91) exceeds max value (90).']]
+* ```
+*/
 function identifyErrors(format) {
 	return (arg, i) => {
 		if (!arg) return [[], ["Invalid coordinate value."]];
@@ -56,6 +74,27 @@ function identifyErrors(format) {
 		], []];
 	};
 }
+/**
+* Identifies and organizes coordinate components from parsed tokens.
+*
+* Separates bearing indicators (N/S/E/W), degree values, minute values, and second values from tokens.
+* Uses symbol patterns to identify component types and positional logic as fallback.
+*
+* @param half - Array of tokens representing one coordinate component.
+* @returns Object with `bear`, `deg`, `min`, and `sec` properties, or undefined if invalid.
+*
+* @example
+* ```typescript
+* identifyPieces(['45', '30', '15.23', 'N']);
+* // { bear: 'N', deg: '45', min: '30', sec: '15.23' }
+* ```
+*
+* @example
+* ```typescript
+* identifyPieces(['122°', '25'', '9.84″', 'W']);
+* // { bear: 'W', deg: '122', min: '25', sec: '9.84' }
+* ```
+*/
 function identifyPieces(half) {
 	if (half.length < 1 || half.length > 4) return;
 	const asString = half.join(" ");
@@ -72,18 +111,42 @@ function identifyPieces(half) {
 	];
 	const test = (r, b, v) => r.test(v) || r.test(asString) && b;
 	return half.reduce((acc, token, i, { length }) => {
+		if (!acc) return;
 		if (test(SYMBOL_PATTERNS.NSEW, i === length - 1, token)) acc.bear ||= token;
 		else if (test(SYMBOL_PATTERNS.DEGREES, i === 0, token)) acc.deg ||= token;
 		else if (test(SYMBOL_PATTERNS.MINUTES, i === 1, token)) acc.min ||= token;
 		else if (test(SYMBOL_PATTERNS.SECONDS, i === 2, token)) acc.sec ||= token;
 		else {
 			const key = keys.find((k) => !acc[k]);
+			if (!key) return;
 			acc[key] = token;
 		}
 		return acc;
 	}, places);
 }
-/** Parse a Degrees Minutes Seconds coordinate. */
+/**
+* Parses a Degrees Minutes Seconds coordinate string.
+*
+* Accepts coordinates in degrees minutes seconds format with bearing indicators.
+* Validates that degrees are integers, minutes are in range 0-59,
+* seconds are in range 0-59.999..., and all components are properly formatted.
+*
+* @param input - Raw coordinate string to parse.
+* @param format - Expected format (LATLON or LONLAT).
+* @returns Parsed coordinate values or errors.
+*
+* @example
+* ```typescript
+* parseDegreesMinutesSeconds('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');
+* // [[37.7749, -122.4194], []]
+* ```
+*
+* @example
+* ```typescript
+* parseDegreesMinutesSeconds('45 30 15.23 N, 122 25 9.84 W');
+* // [[45.504231, -122.419400], []]
+* ```
+*/
 const parseDegreesMinutesSeconds = createParser({
 	formats,
 	identifyErrors,
@@ -91,5 +154,5 @@ const parseDegreesMinutesSeconds = createParser({
 });
 
 //#endregion
-export { parseDegreesMinutesSeconds };
+export { identifyErrors as _identifyErrors, identifyPieces as _identifyPieces, parseDegreesMinutesSeconds };
 //# sourceMappingURL=parser.js.map

package/dist/coordinates/latlon/degrees-minutes-seconds/parser.js.map

@@ -1 +1 @@
-{"version":3,"file":"parser.js","names":["Patterning.fromTemplate","isNegative: 0 | 1"],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/parser.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 * as Patterning from '@/patterning';\nimport {\n  BEARINGS,\n  type Format,\n  LIMITS,\n  PARTIAL_PATTERNS,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { inRange } from '../internal/in-range';\nimport { createParser } from '../internal/parse-format';\nimport type { ParseResults } from '../internal/parse';\n\ntype DegreesMinutesSeconds = {\n  bear: string;\n  deg: string;\n  min: string;\n  sec: string;\n};\n\nconst checks = {\n  deg: (deg: string, limit: number) => {\n    if (Number.parseFloat(deg) > limit) {\n      return `Degrees value (${deg}) exceeds max value (${limit}).`;\n    }\n\n    if (/\\./.test(deg)) {\n      return `Degrees value (${deg}) must not include decimal value.`;\n    }\n  },\n  min: (min: string) => inRange('Minutes', min, 59),\n  sec: (sec: string) => inRange('Seconds', sec, 59.999999999),\n};\n\nconst formats = {\n  LATLON: Patterning.fromTemplate(\n    PARTIAL_PATTERNS,\n    `degLat min secDec NS ${SYMBOLS.DIVIDER} degLon min secDec EW`,\n  ),\n  LONLAT: Patterning.fromTemplate(\n    PARTIAL_PATTERNS,\n    `degLon min secDec EW ${SYMBOLS.DIVIDER} degLat min secDec NS`,\n  ),\n};\n\nfunction identifyErrors(format: Format) {\n  return (arg: DegreesMinutesSeconds | undefined, i: number) => {\n    if (!arg) {\n      return [[], ['Invalid coordinate value.']] as ParseResults;\n    }\n\n    let { bear, deg, min, sec } = arg;\n\n    deg ??= '0';\n    // NOTE: need `||=` not `??=` because empty-string is not nullish\n    min ||= '0';\n    sec ||= '0';\n\n    let isNegative: 0 | 1 = SYMBOL_PATTERNS.NEGATIVE_SIGN.test(deg) ? 1 : 0;\n    const bearingOptions = BEARINGS[format][i] as [string, string];\n\n    if (!bear || isNegative) {\n      bear = bearingOptions[isNegative];\n      deg = Math.abs(Number.parseFloat(deg)).toString();\n      isNegative = 0;\n    }\n\n    const errors = [\n      ...[checks.deg(deg, LIMITS[format][i] ?? 0)],\n      ...[checks.min(min)],\n      ...[checks.sec(sec)],\n    ].filter(Boolean);\n\n    return (\n      errors.length ? [[], errors] : [[deg, min, sec, bear], []]\n    ) as ParseResults;\n  };\n}\n\nfunction identifyPieces(half: string[]) {\n  if (half.length < 1 || half.length > 4) {\n    return;\n  }\n\n  const asString = half.join(' ');\n  const places = { bear: '', deg: '', min: '', sec: '' };\n  const keys = ['deg', 'min', 'sec'] as (keyof typeof places)[];\n  const test = (r: RegExp, b: boolean, v: string) =>\n    r.test(v) || (r.test(asString) && b);\n\n  return half.reduce((acc, token, i, { length }) => {\n    if (test(SYMBOL_PATTERNS.NSEW, i === length - 1, token)) {\n      acc.bear ||= token;\n    } else if (test(SYMBOL_PATTERNS.DEGREES, i === 0, token)) {\n      acc.deg ||= token;\n    } else if (test(SYMBOL_PATTERNS.MINUTES, i === 1, token)) {\n      acc.min ||= token;\n    } else if (test(SYMBOL_PATTERNS.SECONDS, i === 2, token)) {\n      acc.sec ||= token;\n    } else {\n      const key = keys.find((k) => !acc[k]);\n\n      acc[key as keyof typeof acc] = token;\n    }\n\n    return acc;\n  }, places);\n}\n\n/** Parse a Degrees Minutes Seconds coordinate. */\nexport const parseDegreesMinutesSeconds = createParser<DegreesMinutesSeconds>({\n  formats,\n  identifyErrors,\n  identifyPieces,\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAgCA,MAAM,SAAS;CACb,MAAM,KAAa,UAAkB;AACnC,MAAI,OAAO,WAAW,IAAI,GAAG,MAC3B,QAAO,kBAAkB,IAAI,uBAAuB,MAAM;AAG5D,MAAI,KAAK,KAAK,IAAI,CAChB,QAAO,kBAAkB,IAAI;;CAGjC,MAAM,QAAgB,QAAQ,WAAW,KAAK,GAAG;CACjD,MAAM,QAAgB,QAAQ,WAAW,KAAK,aAAa;CAC5D;AAED,MAAM,UAAU;CACd,QAAQA,aACN,kBACA,wBAAwB,QAAQ,QAAQ,uBACzC;CACD,QAAQA,aACN,kBACA,wBAAwB,QAAQ,QAAQ,uBACzC;CACF;AAED,SAAS,eAAe,QAAgB;AACtC,SAAQ,KAAwC,MAAc;AAC5D,MAAI,CAAC,IACH,QAAO,CAAC,EAAE,EAAE,CAAC,4BAA4B,CAAC;EAG5C,IAAI,EAAE,MAAM,KAAK,KAAK,QAAQ;AAE9B,UAAQ;AAER,UAAQ;AACR,UAAQ;EAER,IAAIC,aAAoB,gBAAgB,cAAc,KAAK,IAAI,GAAG,IAAI;EACtE,MAAM,iBAAiB,SAAS,QAAQ;AAExC,MAAI,CAAC,QAAQ,YAAY;AACvB,UAAO,eAAe;AACtB,SAAM,KAAK,IAAI,OAAO,WAAW,IAAI,CAAC,CAAC,UAAU;AACjD,gBAAa;;EAGf,MAAM,SAAS;GACb,GAAG,CAAC,OAAO,IAAI,KAAK,OAAO,QAAQ,MAAM,EAAE,CAAC;GAC5C,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;GACpB,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;GACrB,CAAC,OAAO,QAAQ;AAEjB,SACE,OAAO,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC;GAAC;GAAK;GAAK;GAAK;GAAK,EAAE,EAAE,CAAC;;;AAKhE,SAAS,eAAe,MAAgB;AACtC,KAAI,KAAK,SAAS,KAAK,KAAK,SAAS,EACnC;CAGF,MAAM,WAAW,KAAK,KAAK,IAAI;CAC/B,MAAM,SAAS;EAAE,MAAM;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI;CACtD,MAAM,OAAO;EAAC;EAAO;EAAO;EAAM;CAClC,MAAM,QAAQ,GAAW,GAAY,MACnC,EAAE,KAAK,EAAE,IAAK,EAAE,KAAK,SAAS,IAAI;AAEpC,QAAO,KAAK,QAAQ,KAAK,OAAO,GAAG,EAAE,aAAa;AAChD,MAAI,KAAK,gBAAgB,MAAM,MAAM,SAAS,GAAG,MAAM,CACrD,KAAI,SAAS;WACJ,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;WACH,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;WACH,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;OACP;GACL,MAAM,MAAM,KAAK,MAAM,MAAM,CAAC,IAAI,GAAG;AAErC,OAAI,OAA2B;;AAGjC,SAAO;IACN,OAAO;;;AAIZ,MAAa,6BAA6B,aAAoC;CAC5E;CACA;CACA;CACD,CAAC"}
+{"version":3,"file":"parser.js","names":["Patterning.fromTemplate","isNegative: 0 | 1"],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/parser.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 * as Patterning from '@/patterning';\nimport {\n  BEARINGS,\n  type Format,\n  LIMITS,\n  PARTIAL_PATTERNS,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { inRange } from '../internal/in-range';\nimport { createParser } from '../internal/parse-format';\nimport type { ParseResults } from '../internal/parse';\n\ntype DegreesMinutesSeconds = {\n  bear: string;\n  deg: string;\n  min: string;\n  sec: string;\n};\n\nconst checks = {\n  deg: (deg: string, limit: number) => {\n    const num = Number.parseFloat(deg);\n    if (Number.isNaN(num)) {\n      return `Degrees value (${deg}) is not a valid number.`;\n    }\n    if (num > limit) {\n      return `Degrees value (${deg}) exceeds max value (${limit}).`;\n    }\n\n    if (/\\./.test(deg)) {\n      return `Degrees value (${deg}) must not include decimal value.`;\n    }\n  },\n  min: (min: string) => inRange('Minutes', min, 59),\n  sec: (sec: string) => inRange('Seconds', sec, 59.999999999),\n};\n\nconst formats = {\n  LATLON: Patterning.fromTemplate(\n    PARTIAL_PATTERNS,\n    `degLat min secDec NS ${SYMBOLS.DIVIDER} degLon min secDec EW`,\n  ),\n  LONLAT: Patterning.fromTemplate(\n    PARTIAL_PATTERNS,\n    `degLon min secDec EW ${SYMBOLS.DIVIDER} degLat min secDec NS`,\n  ),\n};\n\n/**\n * Creates an error identification function for degrees minutes seconds coordinates.\n *\n * Validates that degree values are integers, minutes are in range 0-59,\n * seconds are in range 0-59.999..., and all components are properly formatted.\n *\n * @param format - The coordinate format (LATLON or LONLAT).\n * @returns Function that validates coordinate components and returns parse results.\n *\n * @example\n * ```typescript\n * const validator = identifyErrors('LATLON');\n * const result = validator({ deg: '91', min: '0', sec: '0', bear: 'N' }, 0);\n * // [[], ['Degrees value (91) exceeds max value (90).']]\n * ```\n */\nfunction identifyErrors(format: Format) {\n  return (arg: DegreesMinutesSeconds | undefined, i: number) => {\n    if (!arg) {\n      return [[], ['Invalid coordinate value.']] as ParseResults;\n    }\n\n    let { bear, deg, min, sec } = arg;\n\n    deg ??= '0';\n    // NOTE: need `||=` not `??=` because empty-string is not nullish\n    min ||= '0';\n    sec ||= '0';\n\n    let isNegative: 0 | 1 = SYMBOL_PATTERNS.NEGATIVE_SIGN.test(deg) ? 1 : 0;\n    const bearingOptions = BEARINGS[format][i] as [string, string];\n\n    if (!bear || isNegative) {\n      bear = bearingOptions[isNegative];\n      deg = Math.abs(Number.parseFloat(deg)).toString();\n      isNegative = 0;\n    }\n\n    const errors = [\n      ...[checks.deg(deg, LIMITS[format][i] ?? 0)],\n      ...[checks.min(min)],\n      ...[checks.sec(sec)],\n    ].filter(Boolean);\n\n    return (\n      errors.length ? [[], errors] : [[deg, min, sec, bear], []]\n    ) as ParseResults;\n  };\n}\n\n/**\n * Identifies and organizes coordinate components from parsed tokens.\n *\n * Separates bearing indicators (N/S/E/W), degree values, minute values, and second values from tokens.\n * Uses symbol patterns to identify component types and positional logic as fallback.\n *\n * @param half - Array of tokens representing one coordinate component.\n * @returns Object with `bear`, `deg`, `min`, and `sec` properties, or undefined if invalid.\n *\n * @example\n * ```typescript\n * identifyPieces(['45', '30', '15.23', 'N']);\n * // { bear: 'N', deg: '45', min: '30', sec: '15.23' }\n * ```\n *\n * @example\n * ```typescript\n * identifyPieces(['122°', '25'', '9.84″', 'W']);\n * // { bear: 'W', deg: '122', min: '25', sec: '9.84' }\n * ```\n */\nfunction identifyPieces(half: string[]) {\n  if (half.length < 1 || half.length > 4) {\n    return;\n  }\n\n  const asString = half.join(' ');\n  const places = { bear: '', deg: '', min: '', sec: '' };\n  const keys = ['deg', 'min', 'sec'] as (keyof typeof places)[];\n  const test = (r: RegExp, b: boolean, v: string) =>\n    r.test(v) || (r.test(asString) && b);\n\n  return half.reduce<typeof places | undefined>((acc, token, i, { length }) => {\n    if (!acc) {\n      return undefined;\n    }\n    if (test(SYMBOL_PATTERNS.NSEW, i === length - 1, token)) {\n      acc.bear ||= token;\n    } else if (test(SYMBOL_PATTERNS.DEGREES, i === 0, token)) {\n      acc.deg ||= token;\n    } else if (test(SYMBOL_PATTERNS.MINUTES, i === 1, token)) {\n      acc.min ||= token;\n    } else if (test(SYMBOL_PATTERNS.SECONDS, i === 2, token)) {\n      acc.sec ||= token;\n    } else {\n      const key = keys.find((k) => !acc[k]);\n      if (!key) {\n        return undefined;\n      }\n      acc[key] = token;\n    }\n\n    return acc;\n  }, places);\n}\n\n/**\n * Parses a Degrees Minutes Seconds coordinate string.\n *\n * Accepts coordinates in degrees minutes seconds format with bearing indicators.\n * Validates that degrees are integers, minutes are in range 0-59,\n * seconds are in range 0-59.999..., and all components are properly formatted.\n *\n * @param input - Raw coordinate string to parse.\n * @param format - Expected format (LATLON or LONLAT).\n * @returns Parsed coordinate values or errors.\n *\n * @example\n * ```typescript\n * parseDegreesMinutesSeconds('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');\n * // [[37.7749, -122.4194], []]\n * ```\n *\n * @example\n * ```typescript\n * parseDegreesMinutesSeconds('45 30 15.23 N, 122 25 9.84 W');\n * // [[45.504231, -122.419400], []]\n * ```\n */\nexport const parseDegreesMinutesSeconds = createParser<DegreesMinutesSeconds>({\n  formats,\n  identifyErrors,\n  identifyPieces,\n});\n\nexport { identifyErrors as _identifyErrors, identifyPieces as _identifyPieces };\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAgCA,MAAM,SAAS;CACb,MAAM,KAAa,UAAkB;EACnC,MAAM,MAAM,OAAO,WAAW,IAAI;AAClC,MAAI,OAAO,MAAM,IAAI,CACnB,QAAO,kBAAkB,IAAI;AAE/B,MAAI,MAAM,MACR,QAAO,kBAAkB,IAAI,uBAAuB,MAAM;AAG5D,MAAI,KAAK,KAAK,IAAI,CAChB,QAAO,kBAAkB,IAAI;;CAGjC,MAAM,QAAgB,QAAQ,WAAW,KAAK,GAAG;CACjD,MAAM,QAAgB,QAAQ,WAAW,KAAK,aAAa;CAC5D;AAED,MAAM,UAAU;CACd,QAAQA,aACN,kBACA,wBAAwB,QAAQ,QAAQ,uBACzC;CACD,QAAQA,aACN,kBACA,wBAAwB,QAAQ,QAAQ,uBACzC;CACF;;;;;;;;;;;;;;;;;AAkBD,SAAS,eAAe,QAAgB;AACtC,SAAQ,KAAwC,MAAc;AAC5D,MAAI,CAAC,IACH,QAAO,CAAC,EAAE,EAAE,CAAC,4BAA4B,CAAC;EAG5C,IAAI,EAAE,MAAM,KAAK,KAAK,QAAQ;AAE9B,UAAQ;AAER,UAAQ;AACR,UAAQ;EAER,IAAIC,aAAoB,gBAAgB,cAAc,KAAK,IAAI,GAAG,IAAI;EACtE,MAAM,iBAAiB,SAAS,QAAQ;AAExC,MAAI,CAAC,QAAQ,YAAY;AACvB,UAAO,eAAe;AACtB,SAAM,KAAK,IAAI,OAAO,WAAW,IAAI,CAAC,CAAC,UAAU;AACjD,gBAAa;;EAGf,MAAM,SAAS;GACb,GAAG,CAAC,OAAO,IAAI,KAAK,OAAO,QAAQ,MAAM,EAAE,CAAC;GAC5C,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;GACpB,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC;GACrB,CAAC,OAAO,QAAQ;AAEjB,SACE,OAAO,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,CAAC;GAAC;GAAK;GAAK;GAAK;GAAK,EAAE,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;AA0BhE,SAAS,eAAe,MAAgB;AACtC,KAAI,KAAK,SAAS,KAAK,KAAK,SAAS,EACnC;CAGF,MAAM,WAAW,KAAK,KAAK,IAAI;CAC/B,MAAM,SAAS;EAAE,MAAM;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI;CACtD,MAAM,OAAO;EAAC;EAAO;EAAO;EAAM;CAClC,MAAM,QAAQ,GAAW,GAAY,MACnC,EAAE,KAAK,EAAE,IAAK,EAAE,KAAK,SAAS,IAAI;AAEpC,QAAO,KAAK,QAAmC,KAAK,OAAO,GAAG,EAAE,aAAa;AAC3E,MAAI,CAAC,IACH;AAEF,MAAI,KAAK,gBAAgB,MAAM,MAAM,SAAS,GAAG,MAAM,CACrD,KAAI,SAAS;WACJ,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;WACH,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;WACH,KAAK,gBAAgB,SAAS,MAAM,GAAG,MAAM,CACtD,KAAI,QAAQ;OACP;GACL,MAAM,MAAM,KAAK,MAAM,MAAM,CAAC,IAAI,GAAG;AACrC,OAAI,CAAC,IACH;AAEF,OAAI,OAAO;;AAGb,SAAO;IACN,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;AA0BZ,MAAa,6BAA6B,aAAoC;CAC5E;CACA;CACA;CACD,CAAC"}

package/dist/coordinates/latlon/degrees-minutes-seconds/system.d.ts

@@ -13,6 +13,38 @@
 import { CoordinateSystem } from "../internal/coordinate-system.js";
 
 //#region src/coordinates/latlon/degrees-minutes-seconds/system.d.ts
+
+/**
+ * Degrees Minutes Seconds coordinate system implementation.
+ *
+ * Provides parsing, conversion, and formatting for coordinates in degrees minutes seconds notation.
+ * Coordinates are expressed as integer degrees, integer minutes, and decimal seconds (e.g., 37° 46' 29.64″ N).
+ *
+ * @property name - Human-readable name of the coordinate system.
+ * @property parse - Parses degrees minutes seconds coordinate strings.
+ * @property toFloat - Converts parsed coordinate components to floating point numbers.
+ * @property toFormat - Formats numeric coordinates back to degrees minutes seconds string.
+ *
+ * @example
+ * ```typescript
+ * // Parse a coordinate string
+ * const [coords, errors] = systemDegreesMinutesSeconds.parse('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Convert to float
+ * const lat = systemDegreesMinutesSeconds.toFloat(['37', '46', '29.64', 'N']);
+ * // 37.7749
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Format to string
+ * const formatted = systemDegreesMinutesSeconds.toFormat('LATLON', [37.7749, -122.4194]);
+ * // '37 46 29.64 N / 122 25 9.84 W'
+ * ```
+ */
 declare const systemDegreesMinutesSeconds: CoordinateSystem;
 //#endregion
 export { systemDegreesMinutesSeconds };

package/dist/coordinates/latlon/degrees-minutes-seconds/system.js

@@ -15,6 +15,37 @@ import { BEARINGS, SYMBOLS, SYMBOL_PATTERNS } from "../internal/index.js";
 import { parseDegreesMinutesSeconds } from "./parser.js";
 
 //#region src/coordinates/latlon/degrees-minutes-seconds/system.ts
+/**
+* Degrees Minutes Seconds coordinate system implementation.
+*
+* Provides parsing, conversion, and formatting for coordinates in degrees minutes seconds notation.
+* Coordinates are expressed as integer degrees, integer minutes, and decimal seconds (e.g., 37° 46' 29.64″ N).
+*
+* @property name - Human-readable name of the coordinate system.
+* @property parse - Parses degrees minutes seconds coordinate strings.
+* @property toFloat - Converts parsed coordinate components to floating point numbers.
+* @property toFormat - Formats numeric coordinates back to degrees minutes seconds string.
+*
+* @example
+* ```typescript
+* // Parse a coordinate string
+* const [coords, errors] = systemDegreesMinutesSeconds.parse('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');
+* ```
+*
+* @example
+* ```typescript
+* // Convert to float
+* const lat = systemDegreesMinutesSeconds.toFloat(['37', '46', '29.64', 'N']);
+* // 37.7749
+* ```
+*
+* @example
+* ```typescript
+* // Format to string
+* const formatted = systemDegreesMinutesSeconds.toFormat('LATLON', [37.7749, -122.4194]);
+* // '37 46 29.64 N / 122 25 9.84 W'
+* ```
+*/
 const systemDegreesMinutesSeconds = {
 	name: "Degrees Minutes Seconds",
 	parse: parseDegreesMinutesSeconds,

package/dist/coordinates/latlon/degrees-minutes-seconds/system.js.map

@@ -1 +1 @@
-{"version":3,"file":"system.js","names":["systemDegreesMinutesSeconds: CoordinateSystem"],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/system.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\nimport {\n  BEARINGS,\n  type Compass,\n  type Format,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { parseDegreesMinutesSeconds } from './parser';\nimport type { CoordinateSystem } from '../internal/coordinate-system';\n\nexport const systemDegreesMinutesSeconds: CoordinateSystem = {\n  name: 'Degrees Minutes Seconds',\n\n  parse: parseDegreesMinutesSeconds,\n\n  toFloat(arg) {\n    const [degrees, minutes, seconds, bear] = arg as [\n      string,\n      string,\n      string,\n      Compass,\n    ];\n\n    return Number.parseFloat(\n      (\n        (Number.parseFloat(degrees) +\n          Number.parseFloat(minutes) / 60 +\n          Number.parseFloat(seconds) / 3600) *\n        (SYMBOL_PATTERNS.NEGATIVE_BEARINGS.test(bear) ? -1 : 1)\n      ).toFixed(9),\n    );\n  },\n\n  toFormat(format: Format, [left, right]: [number, number]) {\n    return [left, right]\n      .map((num, index) => {\n        const abs = Math.abs(num);\n        const deg = Math.floor(abs);\n        const rem = (abs - deg) * 60;\n        const min = Math.floor(rem);\n        const sec = Number.parseFloat(((rem - min) * 60).toFixed(10));\n\n        return `${deg} ${min} ${sec} ${BEARINGS[format][index as 0 | 1][+(num < 0)]}`;\n      })\n      .join(` ${SYMBOLS.DIVIDER} `);\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;AAuBA,MAAaA,8BAAgD;CAC3D,MAAM;CAEN,OAAO;CAEP,QAAQ,KAAK;EACX,MAAM,CAAC,SAAS,SAAS,SAAS,QAAQ;AAO1C,SAAO,OAAO,aAET,OAAO,WAAW,QAAQ,GACzB,OAAO,WAAW,QAAQ,GAAG,KAC7B,OAAO,WAAW,QAAQ,GAAG,SAC9B,gBAAgB,kBAAkB,KAAK,KAAK,GAAG,KAAK,IACrD,QAAQ,EAAE,CACb;;CAGH,SAAS,QAAgB,CAAC,MAAM,QAA0B;AACxD,SAAO,CAAC,MAAM,MAAM,CACjB,KAAK,KAAK,UAAU;GACnB,MAAM,MAAM,KAAK,IAAI,IAAI;GACzB,MAAM,MAAM,KAAK,MAAM,IAAI;GAC3B,MAAM,OAAO,MAAM,OAAO;GAC1B,MAAM,MAAM,KAAK,MAAM,IAAI;AAG3B,UAAO,GAAG,IAAI,GAAG,IAAI,GAFT,OAAO,aAAa,MAAM,OAAO,IAAI,QAAQ,GAAG,CAAC,CAEjC,GAAG,SAAS,QAAQ,OAAgB,EAAE,MAAM;IACxE,CACD,KAAK,IAAI,QAAQ,QAAQ,GAAG;;CAElC"}
+{"version":3,"file":"system.js","names":["systemDegreesMinutesSeconds: CoordinateSystem"],"sources":["../../../../src/coordinates/latlon/degrees-minutes-seconds/system.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\nimport {\n  BEARINGS,\n  type Compass,\n  type Format,\n  SYMBOL_PATTERNS,\n  SYMBOLS,\n} from '../internal';\nimport { parseDegreesMinutesSeconds } from './parser';\nimport type { CoordinateSystem } from '../internal/coordinate-system';\n\n/**\n * Degrees Minutes Seconds coordinate system implementation.\n *\n * Provides parsing, conversion, and formatting for coordinates in degrees minutes seconds notation.\n * Coordinates are expressed as integer degrees, integer minutes, and decimal seconds (e.g., 37° 46' 29.64″ N).\n *\n * @property name - Human-readable name of the coordinate system.\n * @property parse - Parses degrees minutes seconds coordinate strings.\n * @property toFloat - Converts parsed coordinate components to floating point numbers.\n * @property toFormat - Formats numeric coordinates back to degrees minutes seconds string.\n *\n * @example\n * ```typescript\n * // Parse a coordinate string\n * const [coords, errors] = systemDegreesMinutesSeconds.parse('37° 46' 29.64″ N / 122° 25' 9.84″ W', 'LATLON');\n * ```\n *\n * @example\n * ```typescript\n * // Convert to float\n * const lat = systemDegreesMinutesSeconds.toFloat(['37', '46', '29.64', 'N']);\n * // 37.7749\n * ```\n *\n * @example\n * ```typescript\n * // Format to string\n * const formatted = systemDegreesMinutesSeconds.toFormat('LATLON', [37.7749, -122.4194]);\n * // '37 46 29.64 N / 122 25 9.84 W'\n * ```\n */\nexport const systemDegreesMinutesSeconds: CoordinateSystem = {\n  name: 'Degrees Minutes Seconds',\n\n  parse: parseDegreesMinutesSeconds,\n\n  toFloat(arg) {\n    const [degrees, minutes, seconds, bear] = arg as [\n      string,\n      string,\n      string,\n      Compass,\n    ];\n\n    return Number.parseFloat(\n      (\n        (Number.parseFloat(degrees) +\n          Number.parseFloat(minutes) / 60 +\n          Number.parseFloat(seconds) / 3600) *\n        (SYMBOL_PATTERNS.NEGATIVE_BEARINGS.test(bear) ? -1 : 1)\n      ).toFixed(9),\n    );\n  },\n\n  toFormat(format: Format, [left, right]: [number, number]) {\n    return [left, right]\n      .map((num, index) => {\n        const abs = Math.abs(num);\n        const deg = Math.floor(abs);\n        const rem = (abs - deg) * 60;\n        const min = Math.floor(rem);\n        const sec = Number.parseFloat(((rem - min) * 60).toFixed(10));\n\n        return `${deg} ${min} ${sec} ${BEARINGS[format][index as 0 | 1][+(num < 0)]}`;\n      })\n      .join(` ${SYMBOLS.DIVIDER} `);\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAaA,8BAAgD;CAC3D,MAAM;CAEN,OAAO;CAEP,QAAQ,KAAK;EACX,MAAM,CAAC,SAAS,SAAS,SAAS,QAAQ;AAO1C,SAAO,OAAO,aAET,OAAO,WAAW,QAAQ,GACzB,OAAO,WAAW,QAAQ,GAAG,KAC7B,OAAO,WAAW,QAAQ,GAAG,SAC9B,gBAAgB,kBAAkB,KAAK,KAAK,GAAG,KAAK,IACrD,QAAQ,EAAE,CACb;;CAGH,SAAS,QAAgB,CAAC,MAAM,QAA0B;AACxD,SAAO,CAAC,MAAM,MAAM,CACjB,KAAK,KAAK,UAAU;GACnB,MAAM,MAAM,KAAK,IAAI,IAAI;GACzB,MAAM,MAAM,KAAK,MAAM,IAAI;GAC3B,MAAM,OAAO,MAAM,OAAO;GAC1B,MAAM,MAAM,KAAK,MAAM,IAAI;AAG3B,UAAO,GAAG,IAAI,GAAG,IAAI,GAFT,OAAO,aAAa,MAAM,OAAO,IAAI,QAAQ,GAAG,CAAC,CAEjC,GAAG,SAAS,QAAQ,OAAgB,EAAE,MAAM;IACxE,CACD,KAAK,IAAI,QAAQ,QAAQ,GAAG;;CAElC"}

package/dist/coordinates/latlon/internal/coordinate-system.d.ts

@@ -14,6 +14,28 @@ import { Compass, Format } from "./index.js";
 import { ParseResults } from "./parse.js";
 
 //#region src/coordinates/latlon/internal/coordinate-system.d.ts
+
+/**
+ * Coordinate system interface for parsing, converting, and formatting geographic coordinates.
+ *
+ * Defines the contract for coordinate notation systems (Decimal Degrees, Degrees Decimal Minutes,
+ * Degrees Minutes Seconds) to parse, convert to float, and format coordinate values.
+ *
+ * @property name - Human-readable name of the coordinate system.
+ * @property parse - Parses a coordinate string into validated tokens or error messages.
+ * @property toFloat - Converts parsed coordinate components (degrees, minutes, seconds, bearing) to a float.
+ * @property toFormat - Formats numeric coordinate pair back to string representation.
+ *
+ * @example
+ * ```typescript
+ * const system: CoordinateSystem = {
+ *   name: 'Decimal Degrees',
+ *   parse: (format, input) => parseDecimalDegrees(input, format),
+ *   toFloat: ([deg, bear]) => Number.parseFloat(deg) * (bear === 'S' || bear === 'W' ? -1 : 1),
+ *   toFormat: (format, [lat, lon]) => `${Math.abs(lat)}° ${lat >= 0 ? 'N' : 'S'} / ${Math.abs(lon)}° ${lon >= 0 ? 'E' : 'W'}`
+ * };
+ * ```
+ */
 type CoordinateSystem = {
   name: string;
   parse: (format: Format, input: string) => ParseResults;

package/dist/coordinates/latlon/internal/create-cache.d.ts

@@ -19,7 +19,23 @@ type CoordinateCache = Record<Format, string>;
  * conversions are only ever done once and only "one-direction-ally". The
  * "one-direction" concept is to avoid the problem of encountering rounding
  * errors when converting between multiple formats.
- * */
+ *
+ * @param format - The coordinate format (LATLON or LONLAT) for the provided value.
+ * @param value - The formatted coordinate string to cache.
+ * @returns Cache object with both LATLON and LONLAT format strings.
+ *
+ * @example
+ * ```typescript
+ * createCache('LATLON', '37.7749 N / 122.4194 W');
+ * // { LATLON: '37.7749 N / 122.4194 W', LONLAT: '122.4194 W / 37.7749 N' }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * createCache('LONLAT', '122° W / 37° N');
+ * // { LONLAT: '122° W / 37° N', LATLON: '37° N / 122° W' }
+ * ```
+ */
 declare function createCache(format: Format, value: string): CoordinateCache;
 //#endregion
 export { CoordinateCache, createCache };

package/dist/coordinates/latlon/internal/create-cache.js

@@ -11,7 +11,7 @@
  */
 
 
-import { FORMATS, SYMBOLS } from "./index.js";
+import { SYMBOLS } from "./index.js";
 
 //#region src/coordinates/latlon/internal/create-cache.ts
 const DIVIDER = ` ${SYMBOLS.DIVIDER} `;
@@ -20,9 +20,25 @@ const DIVIDER = ` ${SYMBOLS.DIVIDER} `;
 * conversions are only ever done once and only "one-direction-ally". The
 * "one-direction" concept is to avoid the problem of encountering rounding
 * errors when converting between multiple formats.
-* */
+*
+* @param format - The coordinate format (LATLON or LONLAT) for the provided value.
+* @param value - The formatted coordinate string to cache.
+* @returns Cache object with both LATLON and LONLAT format strings.
+*
+* @example
+* ```typescript
+* createCache('LATLON', '37.7749 N / 122.4194 W');
+* // { LATLON: '37.7749 N / 122.4194 W', LONLAT: '122.4194 W / 37.7749 N' }
+* ```
+*
+* @example
+* ```typescript
+* createCache('LONLAT', '122° W / 37° N');
+* // { LONLAT: '122° W / 37° N', LATLON: '37° N / 122° W' }
+* ```
+*/
 function createCache(format, value) {
-	const [alternate] = FORMATS.filter((o) => o !== format);
+	const alternate = format === "LATLON" ? "LONLAT" : "LATLON";
 	return {
 		[format]: value,
 		[alternate]: value.includes(SYMBOLS.DIVIDER) ? value.split(DIVIDER).reverse().join(DIVIDER).trim() : value

package/dist/coordinates/latlon/internal/create-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-cache.js","names":[],"sources":["../../../../src/coordinates/latlon/internal/create-cache.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\nimport { FORMATS, type Format, SYMBOLS } from '.';\n\nexport type CoordinateCache = Record<Format, string>;\n\nconst DIVIDER = ` ${SYMBOLS.DIVIDER} `;\n\n/**\n * Create, and initialize, a cache object for coordinate conversions so that\n * conversions are only ever done once and only \"one-direction-ally\". The\n * \"one-direction\" concept is to avoid the problem of encountering rounding\n * errors when converting between multiple formats.\n * */\nexport function createCache(format: Format, value: string) {\n  const [alternate] = FORMATS.filter((o) => o !== format) as [Format];\n\n  return {\n    [format]: value,\n    [alternate]: value.includes(SYMBOLS.DIVIDER)\n      ? value.split(DIVIDER).reverse().join(DIVIDER).trim()\n      : value,\n  } as CoordinateCache;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,UAAU,IAAI,QAAQ,QAAQ;;;;;;;AAQpC,SAAgB,YAAY,QAAgB,OAAe;CACzD,MAAM,CAAC,aAAa,QAAQ,QAAQ,MAAM,MAAM,OAAO;AAEvD,QAAO;GACJ,SAAS;GACT,YAAY,MAAM,SAAS,QAAQ,QAAQ,GACxC,MAAM,MAAM,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,MAAM,GACnD;EACL"}
+{"version":3,"file":"create-cache.js","names":["alternate: Format"],"sources":["../../../../src/coordinates/latlon/internal/create-cache.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\nimport { type Format, SYMBOLS } from '.';\n\nexport type CoordinateCache = Record<Format, string>;\n\nconst DIVIDER = ` ${SYMBOLS.DIVIDER} `;\n\n/**\n * Create, and initialize, a cache object for coordinate conversions so that\n * conversions are only ever done once and only \"one-direction-ally\". The\n * \"one-direction\" concept is to avoid the problem of encountering rounding\n * errors when converting between multiple formats.\n *\n * @param format - The coordinate format (LATLON or LONLAT) for the provided value.\n * @param value - The formatted coordinate string to cache.\n * @returns Cache object with both LATLON and LONLAT format strings.\n *\n * @example\n * ```typescript\n * createCache('LATLON', '37.7749 N / 122.4194 W');\n * // { LATLON: '37.7749 N / 122.4194 W', LONLAT: '122.4194 W / 37.7749 N' }\n * ```\n *\n * @example\n * ```typescript\n * createCache('LONLAT', '122° W / 37° N');\n * // { LONLAT: '122° W / 37° N', LATLON: '37° N / 122° W' }\n * ```\n */\nexport function createCache(format: Format, value: string) {\n  const alternate: Format = format === 'LATLON' ? 'LONLAT' : 'LATLON';\n\n  return {\n    [format]: value,\n    [alternate]: value.includes(SYMBOLS.DIVIDER)\n      ? value.split(DIVIDER).reverse().join(DIVIDER).trim()\n      : value,\n  } as CoordinateCache;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,UAAU,IAAI,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;AAwBpC,SAAgB,YAAY,QAAgB,OAAe;CACzD,MAAMA,YAAoB,WAAW,WAAW,WAAW;AAE3D,QAAO;GACJ,SAAS;GACT,YAAY,MAAM,SAAS,QAAQ,QAAQ,GACxC,MAAM,MAAM,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,MAAM,GACnD;EACL"}

package/dist/coordinates/latlon/internal/exhaustive-errors.d.ts

@@ -2,6 +2,21 @@
 /**
  * A collection of input strings each with exactly one error in a unique
  * position for each format (LATLON and LONLAT) in each system (DD, DDM, DMS).
+ *
+ * Used for comprehensive error validation testing. Each entry contains coordinate
+ * strings with systematic errors across different notation systems.
+ *
+ * @example
+ * ```typescript
+ * EXHAUSTIVE_ERRORS.DD.LATLON;
+ * // Array of decimal degrees strings with errors like '91 N / 179 E'
+ * ```
+ *
+ * @example
+ * ```typescript
+ * EXHAUSTIVE_ERRORS.DMS.LONLAT;
+ * // Array of degrees-minutes-seconds strings with errors
+ * ```
  */
 declare const EXHAUSTIVE_ERRORS: {
   [k: string]: any;