feat: support "m" as an alias for minutes

Closes #659

Author: jonahsnider

docs/api.md

@@ -29,7 +29,7 @@ export type BestUnits<T extends BestKind = BestKind> = BestUnits_2[T];
 export type BestUnitsForMeasure<M extends MeasureKind, K extends BestKind = BestKind> = BestUnitsForUnit<UnitsByMeasure<M>, K>;
 
 // @public
-export type BestUnitsForUnit<U extends Unit, K extends BestKind = BestKind> = U & BestUnits<K>;
+export type BestUnitsForUnit<U extends Unit, K extends BestKind = BestKind> = (Time | Length extends U ? Exclude<U, Time> : Time | 'm' extends U ? Exclude<U, 'm'> : U) & BestUnits<K>;
 
 // @public
 function convert<Q extends number | bigint, U extends Unit>(quantity: Q, from: U): Converter<Q, MeasuresByUnit<U>>;
@@ -99,7 +99,7 @@ export type _MeasureKindByUnit<T extends Unit> = {
 }[MeasureKind];
 
 // @public
-export type MeasuresByUnit<T extends Unit> = UnitsByMeasure<_MeasureKindByUnit<T>>;
+export type MeasuresByUnit<T extends Unit> = UnitsByMeasure<_MeasureKindByUnit<T>> | (T extends 'm' ? Time : never) | (T extends Time ? 'm' : never);
 
 // Warning: (ae-incompatible-release-tags) The symbol "ms" is marked as @public, but its signature references "_LiteralToPrimitive" which is marked as @internal
 //

package.json

@@ -77,22 +77,22 @@
 	"size-limit": [
 		{
 			"brotli": true,
-			"limit": "5.42 KB",
+			"limit": "5.46 KB",
 			"path": "./dist/index.js"
 		},
 		{
 			"gzip": true,
-			"limit": "6.83 KB",
+			"limit": "6.88 KB",
 			"path": "./dist/index.js"
 		},
 		{
 			"brotli": true,
-			"limit": "5.20 KB",
+			"limit": "5.22 KB",
 			"path": "./dist/index.mjs"
 		},
 		{
 			"gzip": true,
-			"limit": "6.59 KB",
+			"limit": "6.64 KB",
 			"path": "./dist/index.mjs"
 		}
 	]

src/converters/conversions/time.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect } from 'vitest';
+import { assertConversions } from '../../../test/assert-conversion';
+import type { Length, Time } from '../../types/units';
+import { convert } from '../convert';
+
+describe('special case for m', () => {
+	assertConversions([{ from: [1, 'm'], to: [1, 'm'] }]);
+
+	assertConversions([{ from: [1, 'm'], to: [60, 's'] }]);
+	assertConversions([{ from: [60, 's'], to: [1, 'm'] }]);
+	assertConversions([{ from: [1, 'm'], to: [1 / 1000, 'km'] }]);
+
+	// Compilation tests
+	convert(1, 'm').to('s');
+	convert(60, 's').to('m');
+
+	const best1m: `${number}${Length}` = convert(1, 'm').to('best').toString();
+	const best60s: `${number}${Time}` = convert(1, 'min').to('best').toString();
+
+	expect(best1m).toBe('1m');
+	expect(best60s).toBe('60s');
+});

src/converters/convert.ts

@@ -1,21 +1,33 @@
-import type { BestKind } from '../conversions/types';
+import { type BestKind, type MeasureKind } from '../conversions/types';
 import { bestUnits } from '../generated/best-units';
 import { differences, unitsObject } from '../generated/parse-unit';
 import type { BestConversion, Converter } from '../types/converter';
 import type { BestUnitsForUnit, MeasuresByUnit, Unit } from '../types/units';
 import type { LiteralToPrimitive } from '../types/utils';
 
+// Importing MeasureKind will cause the entire enum to be included in the output, which increases bundle size
+// This workaround allows me to just hardcode the value, but ensures it doesn't become inaccurate if the enum changes
+const MeasureKindTime: MeasureKind.Time = 10;
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: No easy way to reduce complexity
 function convertTo<Q extends number | bigint>(from: string, quantity: Q, to: string): LiteralToPrimitive<Q> {
-	const parsedTo = unitsObject[to as Unit];
+	let parsedTo = unitsObject[to as Unit];
 
 	if (!parsedTo) {
 		throw new RangeError(`${to} is not a valid unit`);
 	}
 
-	const parsedFrom = unitsObject[from as Unit];
+	let parsedFrom = unitsObject[from as Unit];
 
 	if (parsedFrom[0] !== parsedTo[0]) {
-		throw new RangeError(`Cannot convert between different measures: ${from} and ${to}`);
+		if (parsedFrom[0] === MeasureKindTime && to === 'm') {
+			// Going from time to meters, you meant to do minutes
+			parsedTo = unitsObject.min;
+		} else if (from === 'm' && parsedTo[0] === MeasureKindTime) {
+			parsedFrom = unitsObject.min;
+		} else {
+			throw new RangeError(`Cannot convert between different measures: ${from} and ${to}`);
+		}
 	}
 
 	const fromRatio = parsedFrom[1];

src/converters/ms.test.ts

@@ -5,6 +5,7 @@ describe('conversions', () => {
 	describe('duration string to ms', () => {
 		test.each([
 			['1s', 1000],
+			['1m', 60_000],
 			['1d', 86_400_000],
 			['1d 24h', 86_400_000 * 2],
 		])('%p -> %p', (from, to) => {

src/types/units.ts

@@ -19,7 +19,12 @@ export type MeasureKindByUnit<T extends Unit> = {
  * A type that gives all the units compatible with the same measure as a given unit.
  * @public
  */
-export type MeasuresByUnit<T extends Unit> = UnitsByMeasure<MeasureKindByUnit<T>>;
+export type MeasuresByUnit<T extends Unit> =
+	| UnitsByMeasure<MeasureKindByUnit<T>>
+	// Special case for converting from 'm' (alias for minutes) to time
+	| (T extends 'm' ? Time : never)
+	// Special case for converting from time to 'm' (alias for minutes)
+	| (T extends Time ? 'm' : never);
 
 /**
  * A supported unit you can convert.
@@ -46,7 +51,19 @@ export type BestUnitsForMeasure<M extends MeasureKind, K extends BestKind = Best
  * Get the best units for a given unit.
  * @public
  */
-export type BestUnitsForUnit<U extends Unit, K extends BestKind = BestKind> = U & BestUnits<K>;
+// We have special logic related to the 'm' unit, where it is injected in some cases
+// Or when Time is injected if you are converting from 'm'
+// We need to undo that logic here, otherwise the best units will be incorrect for 'm' or Time
+// Cases:
+// 1. U = Time | Length, output should be U - Time
+// 2. U = Time | 'm', output should be U - 'm'
+// 3. U = something else, output should be U (no transformation)
+export type BestUnitsForUnit<U extends Unit, K extends BestKind = BestKind> = (Time | Length extends U
+	? Exclude<U, Time>
+	: Time | 'm' extends U
+		? Exclude<U, 'm'>
+		: U) &
+	BestUnits<K>;
 
 /**
  * Valid angle units.