@zelgadis87/utils-core 4.0.0

package/src/sorting/Sorter.ts

@@ -0,0 +1,357 @@
+import { TBiFunction, TConditionalParameterOptions, TFunction, TKeysOfType, TPositiveNumber, TReadableArray, isDefined, isNullOrUndefined } from "../types";
+import { identity } from "../utils/constant.js";
+import { TComparisonDirection, TComparisonFunction, TComparisonResult, TStrictComparisonResult } from "./types.js";
+
+type TCompareValuesOptions = {
+	nullsFirst: boolean;
+};
+type TCompareFunctionOptions = {
+	nullsFirst: boolean;
+	direction: TComparisonDirection;
+};
+
+const defaultCompareValuesOptions = {
+	nullsFirst: false,
+} as const satisfies Partial<TCompareValuesOptions>;
+const defaultCompareFunctionOptions: TCompareFunctionOptions = {
+	...defaultCompareValuesOptions,
+	direction: 'ASC',
+} as const satisfies Partial<TCompareFunctionOptions>;
+
+const naturalOrderComparison = <V>( a: V, b: V ) => a < b ? -1 : 1;
+
+function compareValues<V>( a: V, b: V, cmp: TBiFunction<V, V, TComparisonResult>, { nullsFirst }: TCompareValuesOptions ): TComparisonResult {
+	if ( a === b )
+		return 0;
+
+	const nullA = isNullOrUndefined( a );
+	const nullB = isNullOrUndefined( b );
+	if ( nullA && nullB )
+		return 0;
+	if ( nullA !== nullB )
+		return ( nullA === nullsFirst ) ? -1 : 1;
+
+	// A & B are defined and are different.
+	return cmp( a, b );
+}
+
+function compareFunction<T, V>( fn: TFunction<T, V>, cmp: TBiFunction<V, V, TStrictComparisonResult>, { nullsFirst, direction }: TCompareFunctionOptions ): TComparisonFunction<T> {
+	return ( a: T, b: T ) => applyDirection( compareValues<V>( fn( a ), fn( b ), cmp, { nullsFirst } ), direction );
+}
+
+function applyDirection( res: TComparisonResult, direction: TComparisonDirection ): TComparisonResult {
+	return res * ( direction === 'ASC' ? 1 : -1 ) as TComparisonResult
+}
+
+function combine<T, R, S>( f: TFunction<T, R>, g: TFunction<R, S> ): TFunction<T, S> {
+	return ( t: T ) => g( f( t ) );
+}
+
+function reverse<T>( fn: TComparisonFunction<T> ): TComparisonFunction<T> {
+	return ( a: T, b: T ) => fn( a, b ) * -1 as TComparisonResult;
+}
+
+const chain = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, cmpFn: TComparisonFunction<T> ): TSorter<T> => {
+	return doCreateWithFunctions( [...fns, cmpFn] );
+}
+
+const transformAndChain = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, cmpFn: TComparisonFunction<R> ): TSorter<T> => {
+	const fn: TComparisonFunction<T> = ( a: T, b: T ) => cmpFn( transform( a ), transform( b ) );
+	return chain( fns, fn );
+}
+const compareStrings = <T, R extends string>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, options: TConditionalParameterOptions<TStringComparisonOptions, typeof defaultStringComparisonOptions> = {} ) => {
+	const { nullsFirst, direction, ignoreCase } = { ...defaultStringComparisonOptions, ...options };
+	if ( ignoreCase )
+		transform = combine<T, R, R>( transform, t => t.toLowerCase() as R );
+	return chain( fns, compareFunction( transform, naturalOrderComparison, { nullsFirst, direction } ) );
+};
+const compareNumbers = <T, R extends number>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, options: TConditionalParameterOptions<TNumberComparisonOptions, typeof defaultNumberComparisonOptions> = {} ) => {
+	const { nullsFirst, direction } = { ...defaultNumberComparisonOptions, ...options };
+	return chain( fns, compareFunction( transform, naturalOrderComparison, { nullsFirst, direction } ) );
+};
+const compareDates = <T, R extends Date>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, options: TConditionalParameterOptions<TDateComparisonOptions, typeof defaultDateComparisonOptions> = {} ) => {
+	const { nullsFirst, direction } = { ...defaultDateComparisonOptions, ...options };
+	return chain( fns, compareFunction( transform, naturalOrderComparison, { nullsFirst, direction } ) );
+};
+const compareBooleans = <T, R extends boolean>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, options: TConditionalParameterOptions<TBooleanComparisonOptions, typeof defaultBooleanComparisonOptions> ) => {
+	const { nullsFirst, truesFirst } = { ...defaultBooleanComparisonOptions, ...options };
+	return chain( fns, compareFunction( transform, naturalOrderComparison, { nullsFirst, direction: truesFirst ? 'DESC' : 'ASC' } ) );
+};
+const prioritizeSet = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, set: ReadonlyArray<R>, reversed = false ) => {
+	return compareBooleans( fns, ( t: T ) => {
+		const r = transform( t );
+		return isDefined( r ) && set.includes( r );
+	}, { truesFirst: !reversed, nullsFirst: false } );
+}
+const prioritizeArray = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R>, arr: ReadonlyArray<R>, reversed = false ) => {
+	return compareNumbers( fns, ( t: T ) => {
+		const r = transform( t );
+		if ( !isDefined( r ) ) return Number.MAX_VALUE;
+		const indexOf = arr.indexOf( r );
+		return indexOf === -1 ? Number.MAX_VALUE : indexOf;
+	}, { direction: reversed ? 'DESC' : 'ASC', nullsFirst: false } );
+}
+
+const next = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFunction<T, R> ): TSorterStepFull<R, TSorter<T>> => {
+	const using = <X>( transformToX: TFunction<R, X> ) => {
+		return next( fns, combine( transform, transformToX ) ) satisfies TSorterStepFull<X, TSorter<T>> as any;
+	};
+	const retAsChainable = {
+		chain( chain: TComparable<R> ) {
+			return transformAndChain( fns, transform, chain.compare );
+		},
+	} as const satisfies TSorterStepForChainables<R, TSorter<T>>;
+	const retAsUsing = {
+		using,
+	} as const satisfies TSorterStepForUsing<R, TSorter<T>>;
+	const retAsPrioritizable = {
+		prioritizing( arr: Array<R>, _options: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> = {} ) {
+			return prioritizeArray( fns, transform, arr );
+		},
+		deprioritizing( arr: Array<R>, _options: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> = {} ) {
+			return prioritizeArray( fns, transform, arr, true );
+		},
+		prioritizingWithEqualWeight( arr: Array<R>, _options: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> = {} ) {
+			return prioritizeSet( fns, transform, arr );
+		},
+		deprioritizingWithEqualWeight( arr: Array<R>, _options: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> = {} ) {
+			return prioritizeSet( fns, transform, arr, true );
+		},
+	} as const satisfies TSorterStepForPrioritizable<any, TSorter<T>>;
+	const retForRecords = {
+		...retAsUsing,
+		usingStrings: field => using( t => t[field] ),
+		usingNumbers: field => using( t => t[field] ),
+		usingBooleans: field => using( t => t[field] ),
+		usingDates: field => using( t => t[field] ),
+	} as const satisfies TSorterStepForRecords<R, TSorter<T>>;
+	const retForNumbers = {
+		...retAsUsing,
+		inAscendingOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareNumbers( fns, transform as TFunction<T, number>, { direction: 'ASC', ...opts } );
+		},
+		inDescendingOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareNumbers( fns, transform as TFunction<T, number>, { direction: 'DESC', ...opts } );
+		},
+	} as const satisfies TSorterStepForNumbers<R, TSorter<T>>;
+	const retForStrings = {
+		...retAsUsing,
+		inLexographicalOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'ASC', ignoreCase: false, ...opts } );
+		},
+		inLexographicalOrderIgnoringCase( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'ASC', ignoreCase: true, ...opts } );
+		},
+		inReverseLexographicalOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'DESC', ignoreCase: false, ...opts } );
+		},
+		inReverseLexographicalOrderIgnoringCase( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'DESC', ignoreCase: true, ...opts } );
+		},
+	} as const satisfies TSorterStepForStrings<R, TSorter<T>>;
+	const retForBooleans = {
+		...retAsUsing,
+		truesFirst( opts: { nullsFirst?: boolean } = {} ) {
+			return compareBooleans( fns, transform as TFunction<T, boolean>, { truesFirst: true, ...opts } );
+		},
+		falsesFirst( opts: { nullsFirst?: boolean } = {} ) {
+			return compareBooleans( fns, transform as TFunction<T, boolean>, { truesFirst: false, ...opts } );
+		},
+	} as const satisfies TSorterStepForBooleans<R, TSorter<T>>;
+	const retForDates = {
+		...retAsUsing,
+		mostAncientFirst( opts: { nullsFirst?: boolean } = {} ) {
+			return compareDates( fns, transform as TFunction<T, Date>, { direction: 'ASC', ...opts } );
+		},
+		mostRecentFirst( opts: { nullsFirst?: boolean } = {} ) {
+			return compareDates( fns, transform as TFunction<T, Date>, { direction: 'DESC', ...opts } );
+		},
+	} as const satisfies TSorterStepForDates<R, TSorter<T>>;
+	return {
+		...retAsPrioritizable,
+		...retAsChainable,
+		...retForRecords,
+		...retForNumbers,
+		...retForStrings,
+		...retForBooleans,
+		...retForDates,
+	} as const satisfies TSorterStepFull<R, TSorter<T>>;
+};
+
+const createComparisonFunction = <T>( fns: ReadonlyArray<TComparisonFunction<T>> ): TComparisonFunction<T> => {
+	return ( a: T, b: T ) => {
+		let cmp: TComparisonResult = 0, i: number = 0;
+		while ( i < fns.length && cmp === 0 ) {
+			cmp = fns[i++]( a, b );
+		}
+		return cmp;
+	}
+};
+
+const compare = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, a: T, b: T ): TComparisonResult => {
+	return createComparisonFunction( fns )( a, b );
+};
+
+const sort = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, arr: TReadableArray<T> ): Array<T> => {
+	const comparisonFn = createComparisonFunction( fns );
+	return [...arr].sort( comparisonFn );
+};
+
+const top = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, arr: TReadableArray<T>, n: TPositiveNumber ): Array<T> => {
+	return sort( fns, arr ).slice( 0, Math.max( 0, n ) );
+};
+
+const bottom = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, arr: TReadableArray<T>, n: TPositiveNumber ): Array<T> => {
+	return sort( fns, arr ).slice( -Math.max( 0, n ) ).reverse();
+};
+
+const first = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, arr: TReadableArray<T> ): T | null => {
+	return arr.length ? top( fns, arr, 1 )[0] : null;
+};
+
+const last = <T>( fns: ReadonlyArray<TComparisonFunction<T>>, arr: TReadableArray<T> ): T | null => {
+	return arr.length ? bottom( fns, arr, 1 )[0] : null;
+};
+
+function doCreateEmpty<T>(): TSorterStarter<T> {
+	// If we have no comparison functions, return an object that only has chain methods.
+	return next( [], x => x ) satisfies TSorterStepFull<T, TSorter<T>> as unknown as TSorterStarter<T>;
+}
+
+function doCreateWithFunctions<T>( fns: ReadonlyArray<TComparisonFunction<T>> ): TSorter<T> {
+	// If we have some comparison functions, return an object that has chain methods and ending methods.
+	return {
+		get then() {
+			return next( fns, identity ) satisfies TSorterStepFull<T, TSorter<T>> as any;
+		},
+		reversed() {
+			return doCreateWithFunctions( [...fns.map( reverse )] );
+		},
+		compare: ( a: T, b: T ) => {
+			return compare( fns, a, b )
+		},
+		sort: ( arr: TReadableArray<T> ): Array<T> => {
+			return sort( fns, arr );
+		},
+		top: ( arr: TReadableArray<T>, n: TPositiveNumber ): Array<T> => {
+			return top( fns, arr, n );
+		},
+		bottom: ( arr: TReadableArray<T>, n: TPositiveNumber ): Array<T> => {
+			return bottom( fns, arr, n );
+		},
+		first: ( arr: TReadableArray<T> ): T | null => {
+			return first( fns, arr );
+		},
+		last: ( arr: TReadableArray<T> ): T | null => {
+			return last( fns, arr );
+		},
+	} as const satisfies TSorter<T>;
+}
+
+type TComparable<T> = { compare: TComparisonFunction<T> };
+
+export type TSorter<T> = {
+	get then(): TSorterStep<T, TSorter<T>>;
+	reversed: () => TSorter<T>;
+
+	compare: TComparisonFunction<T>;
+	sort: ( arr: TReadableArray<T> ) => Array<T>;
+	top: ( arr: TReadableArray<T>, n: TPositiveNumber ) => Array<T>;
+	bottom: ( arr: TReadableArray<T>, n: TPositiveNumber ) => Array<T>;
+	first: ( arr: TReadableArray<T> ) => T | null;
+	last: ( arr: TReadableArray<T> ) => T | null;
+}
+
+type TSorterStepForRecords<T, Ret> = {
+	usingStrings: ( field: TKeysOfType<T, string> ) => TSorterStep<string, Ret>;
+	usingNumbers: ( field: TKeysOfType<T, number> ) => TSorterStep<number, Ret>;
+	usingBooleans: ( field: TKeysOfType<T, boolean> ) => TSorterStep<boolean, Ret>;
+	usingDates: ( field: TKeysOfType<T, Date> ) => TSorterStep<Date, Ret>;
+};
+type TSorterStepForNumbers<_T, Ret> = {
+	inAscendingOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	inDescendingOrder( opts?: { nullsFirst?: boolean } ): Ret;
+};
+type TSorterStepForStrings<_T, Ret> = {
+	inLexographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	inLexographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
+	inReverseLexographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	inReverseLexographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
+};
+type TSorterStepForBooleans<_T, Ret> = {
+	truesFirst( opts?: { nullsFirst?: boolean } ): Ret;
+	falsesFirst( opts?: { nullsFirst?: boolean } ): Ret;
+};
+type TSorterStepForDates<_T, Ret> = {
+	mostAncientFirst( opts?: { nullsFirst?: boolean } ): Ret;
+	mostRecentFirst( opts?: { nullsFirst?: boolean } ): Ret;
+};
+type TSorterStepForChainables<T, Ret> = {
+	chain: ( chain: TComparable<T> ) => Ret;
+};
+type TSorterStepForUsing<T, Ret> = {
+	using: <X>( transform: TFunction<T, X> ) => TSorterStep<X, Ret>;
+};
+type TSorterStepForPrioritizable<T extends string | number, Ret> = {
+	prioritizing( arr: T[], options?: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> ): Ret;
+	deprioritizing( arr: Array<T>, options?: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> ): Ret;
+	prioritizingWithEqualWeight( arr: T[], options?: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> ): Ret;
+	deprioritizingWithEqualWeight( arr: Array<T>, options?: TConditionalParameterOptions<TPrioritizeOptions, typeof defaultPrioritizeOptions> ): Ret;
+};
+type TSorterStep<T, Ret> = {}
+	& ( T extends Record<string | number | symbol, unknown> ? TSorterStepForRecords<T, Ret> : {} )
+	& ( T extends number ? TSorterStepForNumbers<T, Ret> : {} )
+	& ( T extends string ? TSorterStepForStrings<T, Ret> : {} )
+	& ( T extends boolean ? TSorterStepForBooleans<T, Ret> : {} )
+	& ( T extends Date ? TSorterStepForDates<T, Ret> : {} )
+	& ( T extends string ? TSorterStepForPrioritizable<string, Ret> : {} ) // Allowing all types of strings here is needed because literal types extending strings create compilation problems with method signatures (T[] where T = 'A' | 'B' becomes 'A'[] & 'B'[])
+	& ( T extends number ? TSorterStepForPrioritizable<number, Ret> : {} ) // Allowing all types of numbers here is needed because literal types extending numbers create compilation problems with method signatures (T[] where T = 1 | 2 becomes 1[] & 2[])
+	& TSorterStepForChainables<T, Ret>
+	& TSorterStepForUsing<T, Ret>
+	;
+type TSorterStepFull<T, Ret> = TSorterStepForRecords<T, Ret>
+	& TSorterStepForNumbers<T, Ret>
+	& TSorterStepForStrings<T, Ret>
+	& TSorterStepForBooleans<T, Ret>
+	& TSorterStepForDates<T, Ret>
+	& TSorterStepForChainables<T, Ret>
+	& TSorterStepForUsing<T, Ret>
+	;
+type TSorterStarter<T> = TSorterStep<T, TSorter<T>>;
+export type TSorterBuilder<T> = ( builder: TSorterStarter<T> ) => TSorter<T>;
+
+type TStringComparisonOptions = TCompareFunctionOptions & { ignoreCase: boolean };
+const defaultStringComparisonOptions = { ...defaultCompareFunctionOptions, ignoreCase: false } as const satisfies Partial<TStringComparisonOptions>;
+
+type TNumberComparisonOptions = TCompareFunctionOptions;
+const defaultNumberComparisonOptions = { ...defaultCompareFunctionOptions } as const satisfies Partial<TNumberComparisonOptions>;
+
+type TDateComparisonOptions = TCompareFunctionOptions;
+const defaultDateComparisonOptions = { ...defaultCompareFunctionOptions } as const satisfies Partial<TDateComparisonOptions>;
+
+type TBooleanComparisonOptions = TCompareValuesOptions & { truesFirst: boolean };
+const defaultBooleanComparisonOptions = { ...defaultCompareValuesOptions } as const satisfies Partial<TBooleanComparisonOptions>;
+
+type TPrioritizeOptions = {};
+const defaultPrioritizeOptions = {} as const satisfies Partial<TPrioritizeOptions>;
+
+/** 
+ * @deprecated[2023-10-19]: Use {@link Sorter.createFor} instead.
+ **/
+export function createSorterFor<T>() {
+	return doCreateEmpty<T>();
+}
+
+export const Sorter = {
+	createFor: <T>() => doCreateEmpty<T>(),
+	sort: <T>( arr: TReadableArray<T>, builder: TSorterBuilder<T> ) => builder( doCreateEmpty() ).sort( arr ),
+	top: <T>( arr: TReadableArray<T>, n: TPositiveNumber, builder: TSorterBuilder<T> ) => builder( doCreateEmpty() ).top( arr, n ),
+	bottom: <T>( arr: TReadableArray<T>, n: TPositiveNumber, builder: TSorterBuilder<T> ) => builder( doCreateEmpty() ).bottom( arr, n ),
+	first: <T>( arr: TReadableArray<T>, builder: TSorterBuilder<T> ) => builder( doCreateEmpty() ).first( arr ),
+	last: <T>( arr: TReadableArray<T>, builder: TSorterBuilder<T> ) => builder( doCreateEmpty() ).last( arr ),
+};
+/** 
+ * @deprecated[2023-11-01]: Use {@link Sorter} instead.
+ **/
+export const Sorting = Sorter;
+export default Sorter;

package/src/sorting/index.ts

@@ -0,0 +1,5 @@
+
+export * from './types.js';
+export { default as ComparisonChain } from './ComparisonChain.js';
+export * from './Sorter.js';
+export * from './types.js';

package/src/sorting/types.ts

@@ -0,0 +1,7 @@
+import { TBiFunction } from "../types/functions.js";
+
+
+export type TComparisonResult = -1 | 0 | 1;
+export type TStrictComparisonResult = -1 | 1;
+export type TComparisonFunction<T> = TBiFunction<T, T, TComparisonResult>;
+export type TComparisonDirection = 'ASC' | 'DESC';

package/src/time/RandomTimeDuration.ts

@@ -0,0 +1,21 @@
+import randomInterval from "../random/randomInterval.js";
+import TimeDuration from "./TimeDuration.js";
+import TimeUnit from "./TimeUnit.js";
+
+function randomize( unit: TimeUnit ) {
+	return ( a: number, b: number ) => {
+		return TimeDuration.fromMs( randomInterval( unit.toMs( a ), unit.toMs( b ) ) );
+	}
+}
+
+export default class RandomTimeDuration {
+
+	private constructor() {}
+
+	public static ms = randomize( TimeUnit.MILLISECONDS );
+	public static seconds = randomize( TimeUnit.SECONDS );
+	public static minutes = randomize( TimeUnit.MINUTES );
+	public static hours = randomize( TimeUnit.HOURS );
+	public static days = randomize( TimeUnit.DAYS );
+
+}

package/src/time/TimeBase.ts

@@ -0,0 +1,113 @@
+import TimeUnit from "./TimeUnit";
+
+export default abstract class TimeBase<T> {
+
+	private readonly _ms: number;
+
+	protected constructor(
+		value: number,
+		unit: TimeUnit
+	) {
+		this._ms = unit.toMs( value );
+	}
+
+	protected abstract create( value: number, unit: TimeUnit ): T;
+
+	public get ms(): number {
+		return this._ms / TimeUnit.MILLISECONDS.multiplier;
+	}
+
+	public get seconds(): number {
+		return this._ms / TimeUnit.SECONDS.multiplier;
+	}
+
+	public get minutes(): number {
+		return this._ms / TimeUnit.MINUTES.multiplier;
+	}
+
+	public get hours(): number {
+		return this._ms / TimeUnit.HOURS.multiplier;
+	}
+
+	public get days(): number {
+		return this._ms / TimeUnit.DAYS.multiplier;
+	}
+
+	public addMs( milliseconds: number ): T {
+		return this.addUnits( milliseconds, TimeUnit.MILLISECONDS );
+	}
+
+	public addSeconds( seconds: number ): T {
+		return this.addUnits( seconds, TimeUnit.SECONDS );
+	}
+
+	public addMinutes( minutes: number ): T {
+		return this.addUnits( minutes, TimeUnit.MINUTES );
+	}
+
+	public addHours( hours: number ): T {
+		return this.addUnits( hours, TimeUnit.HOURS );
+	}
+
+	public addDays( days: number ): T {
+		return this.addUnits( days, TimeUnit.DAYS );
+	}
+
+	public removeDays( days: number ): T {
+		return this.removeUnits( days, TimeUnit.DAYS );
+	}
+
+	public addUnits( n: number, unit: TimeUnit ): T {
+		return this.create( this._ms + unit.toMs( n ), TimeUnit.MILLISECONDS );
+	}
+
+	public removeMs( milliseconds: number ): T {
+		return this.addUnits( -milliseconds, TimeUnit.MILLISECONDS );
+	}
+
+	public removeSeconds( seconds: number ): T {
+		return this.addUnits( -seconds, TimeUnit.SECONDS );
+	}
+
+	public removeMinutes( minutes: number ): T {
+		return this.addUnits( -minutes, TimeUnit.MINUTES );
+	}
+
+	public removeHours( hours: number ): T {
+		return this.addUnits( -hours, TimeUnit.HOURS );
+	}
+
+	public removeUnits( n: number, unit: TimeUnit ): T {
+		return this.addUnits( -n, unit );
+	}
+
+	public getUnit( unit: TimeUnit ): number {
+		return this._ms / unit.multiplier;
+	}
+
+	protected toUnits(): { days: number, hours: number, minutes: number, seconds: number } {
+		return {
+			days: Math.floor( ( this._ms / TimeUnit.DAYS.multiplier ) ),
+			hours: Math.floor( ( this._ms / TimeUnit.HOURS.multiplier ) % 24 ),
+			minutes: Math.floor( ( this._ms / TimeUnit.MINUTES.multiplier ) % 60 ),
+			seconds: Math.floor( ( this._ms / TimeUnit.SECONDS.multiplier ) % 60 ),
+		};
+	}
+
+	protected static toMs( units: { days?: number, hours?: number, minutes?: number, seconds?: number, ms?: number } ): number {
+		if ( !units )
+			throw new Error( 'Invalid units given' );
+		let ms = 0
+		ms += units.ms ?? 0 * TimeUnit.MILLISECONDS.multiplier;
+		ms += ( units.seconds ?? 0 ) * TimeUnit.SECONDS.multiplier;
+		ms += ( units.minutes ?? 0 ) * TimeUnit.MINUTES.multiplier;
+		ms += ( units.hours ?? 0 ) * TimeUnit.HOURS.multiplier;
+		ms += ( units.days ?? 0 ) * TimeUnit.DAYS.multiplier;
+		return ms;
+	}
+
+	public toJSON() {
+		return this._ms;
+	}
+
+}