feat: add getMeasureKind() function for validating inputs

Co-authored-by: Jonah Snider <jonah@jonahsnider.com>

docs/convert.api.md

@@ -54,6 +54,12 @@ export type Energy = UnitsByMeasure<MeasureKind.Energy>;
 // @public
 export type Force = UnitsByMeasure<MeasureKind.Force>;
 
+// @public
+export function getMeasureKind<U extends Unit>(unit: U): _MeasureKindByUnit<U>;
+
+// @public
+export function getMeasureKind(unit: string): MeasureKind | undefined;
+
 // @public
 export type Length = UnitsByMeasure<MeasureKind.Length>;
 

package.json

@@ -89,12 +89,12 @@
 		},
 		{
 			"gzip": true,
-			"limit": "6.91 KB",
+			"limit": "6.93 KB",
 			"path": "./dist/index.js"
 		},
 		{
 			"brotli": true,
-			"limit": "5.27 KB",
+			"limit": "5.30 KB",
 			"path": "./dist/index.mjs"
 		},
 		{

src/converters/get-measure-kind.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from 'vitest';
+import { MeasureKind } from '../conversions/types';
+import { getMeasureKind } from './get-measure-kind';
+
+describe('get measure kind', () => {
+	test('returns measure kind for valid units', () => {
+		expect(getMeasureKind('m')).toBe(MeasureKind.Length);
+		expect(getMeasureKind('s')).toBe(MeasureKind.Time);
+		expect(getMeasureKind('kg')).toBe(MeasureKind.Mass);
+	});
+
+	test('returns undefined on invalid units', () => {
+		expect(getMeasureKind('invalid')).toBeUndefined();
+		expect(getMeasureKind('__proto__')).toBeUndefined();
+	});
+});

src/converters/get-measure-kind.ts

@@ -0,0 +1,50 @@
+import type { MeasureKind } from '../conversions/types';
+import { unitsObject } from '../generated/parse-unit';
+import type { MeasureKindByUnit, Unit } from '../types/units';
+
+/**
+ * Get the {@link MeasureKind} associated with a unit.
+ *
+ * @example
+ * ```ts
+ * getMeasure('m'); // MeasureKind.Length
+ * ```
+ * @example
+ * ```ts
+ * getMeasure('invalid'); // undefined
+ * ```
+ *
+ * @param unit - The unit you want to get the measure kind of
+ * @returns The {@link MeasureKind} corresponding to this unit of measure, or `undefined` if the unit is invalid
+ *
+ * @public
+ */
+export function getMeasureKind<U extends Unit>(unit: U): MeasureKindByUnit<U>;
+/**
+ * Get the {@link MeasureKind} associated with a unit.
+ *
+ * @example
+ * ```ts
+ * getMeasure('m'); // MeasureKind.Length
+ * ```
+ * @example
+ * ```ts
+ * getMeasure('invalid'); // undefined
+ * ```
+ *
+ * @param unit - The unit you want to get the measure kind of
+ * @returns The {@link MeasureKind} corresponding to this unit of measure, or `undefined` if the unit is invalid
+ *
+ * @public
+ */
+export function getMeasureKind(unit: string): MeasureKind | undefined;
+export function getMeasureKind<U extends Unit>(unit: U): MeasureKindByUnit<U> | undefined {
+	const unitObject = unitsObject[unit];
+
+	if (unitObject) {
+		return unitObject[0] as MeasureKindByUnit<U>;
+	}
+
+	// Needed to appease tsc
+	return;
+}

src/index.ts

@@ -3,6 +3,7 @@ export type { BestKind, MeasureKind } from './conversions/types';
 export { convertMany } from './converters/convert-many';
 // biome-ignore lint/style/noDefaultExport: This is a default export we want
 export { convert, convert as default } from './converters/convert';
+export { getMeasureKind } from './converters/get-measure-kind';
 export { ms } from './converters/ms';
 export type { UnitsByMeasure as _UnitsByMeasureRaw } from './generated/types';
 export type { BestConversion, Converter } from './types/converter';