diff --git a/docs/convert.api.md b/docs/convert.api.md index efd2a48d..ee28c8d4 100644 --- a/docs/convert.api.md +++ b/docs/convert.api.md @@ -54,6 +54,12 @@ export type Energy = UnitsByMeasure; // @public export type Force = UnitsByMeasure; +// @public +export function getMeasureKind(unit: U): _MeasureKindByUnit; + +// @public +export function getMeasureKind(unit: string): MeasureKind | undefined; + // @public export type Length = UnitsByMeasure; diff --git a/package.json b/package.json index 01b1071b..9a216ad1 100644 --- a/package.json +++ b/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" }, { diff --git a/src/converters/get-measure-kind.test.ts b/src/converters/get-measure-kind.test.ts new file mode 100644 index 00000000..7835b1a4 --- /dev/null +++ b/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(); + }); +}); diff --git a/src/converters/get-measure-kind.ts b/src/converters/get-measure-kind.ts new file mode 100644 index 00000000..247f8b19 --- /dev/null +++ b/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(unit: U): MeasureKindByUnit; +/** + * 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(unit: U): MeasureKindByUnit | undefined { + const unitObject = unitsObject[unit]; + + if (unitObject) { + return unitObject[0] as MeasureKindByUnit; + } + + // Needed to appease tsc + return; +} diff --git a/src/index.ts b/src/index.ts index 587f4c8a..83165de4 100644 --- a/src/index.ts +++ b/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';