@zelgadis87/utils-core 4.0.0

package/src/time/TimeDuration.ts

@@ -0,0 +1,296 @@
+import Deferred, { ICancelablePromise } from "../async/Deferred.js";
+import { randomInterval } from "../random";
+import { TComparisonResult } from "../sorting/index.js";
+import { TIntervalHandle, TMaybe, TTimeoutHandle, TVoidFunction, ensureNonNegativeNumber, ensurePositiveNumber } from "../types";
+import { pad } from "../utils";
+import TimeBase from "./TimeBase";
+import TimeInstant from "./TimeInstant";
+import TimeUnit from "./TimeUnit";
+
+export class TimeDuration extends TimeBase<TimeDuration> {
+
+	protected constructor( value: number, unit: TimeUnit ) {
+		super( value, unit );
+		if ( value < 0 )
+			throw new Error( 'Duration cannot be less than 0' );
+	}
+
+	protected create( value: number, unit: TimeUnit ) {
+		return new TimeDuration( value, unit );
+	}
+
+	public addDuration( duration: TimeDuration ): TimeDuration {
+		return this.addUnits( duration.ms, TimeUnit.MILLISECONDS );
+	}
+
+	public removeDuration( duration: TimeDuration ): TimeDuration {
+		return this.removeUnits( duration.ms, TimeUnit.MILLISECONDS );
+	}
+
+	public override removeUnits( n: number, unit: TimeUnit ): TimeDuration {
+		const nn = Math.min( n, this.getUnit( unit ) ); // Avoid going negative.
+		return super.removeUnits( nn, unit );
+	}
+
+	/** @deprecated: Use multiplyBy instead **/
+	public multiply( times: number ) {
+		return this.multiplyBy( times );
+	}
+
+	public multiplyBy( times: number ): TimeDuration {
+		ensureNonNegativeNumber( times, "times" );
+		return TimeDuration.ms( this.ms * times );
+	}
+
+	public divideBy( times: number ): TimeDuration {
+		ensurePositiveNumber( times, "times" );
+		return TimeDuration.ms( this.ms / times );
+	}
+
+	/**
+	 * Returns the current duration in a human readable format, prioritizing the most significant unit of time and excluding the rest.
+	 * @todo[2023-06] Should allow more customization options
+	 * @todo[2023-06] By default should show the secondary unit only when actually needed (eg, 1h 20m & 3h, instead of 1h 20m & 3h 28m)
+	 * @todo[2023-06] Should not allow negative durations, as this is a duration and not an instant.
+	 * @returns the duration, with only the most significant units displayed as a human readable string, eg: 1d 20h, 10m 30s.
+	 */
+	public get formatted(): string {
+		const format = ( x: number, u1: string, y: number, u2: string ): string => `${x}${u1} ${pad( y.toString(), 2, '0' )}${u2}`;
+		const units = this.toUnits();
+
+		if ( units.days >= 1 )
+			return format( units.days, 'd', units.hours, 'h' );
+		else if ( units.hours >= 1 )
+			return format( units.hours, 'h', units.minutes, 'm' );
+		else if ( units.minutes >= 1 )
+			return format( units.minutes, 'm', units.seconds, 's' );
+		else if ( units.seconds >= 0 )
+			return units.seconds.toString() + 's';
+		else if ( units.seconds > -60 )
+			return 'A few moments ago';
+		else
+			return 'Some time ago';
+	}
+
+	/**
+	 * @deprecated[2023-06] this method makes no sense, as durations are positive by default.
+	 */
+	public absolute(): TimeDuration {
+		return this.ms < 0 ? new TimeDuration( -this.ms, TimeUnit.MILLISECONDS ) : this;
+	}
+
+	public interval( cb: () => unknown ): TIntervalHandle {
+		return setInterval( cb, this.ms );
+	}
+
+	public timeout( cb: () => unknown ): TTimeoutHandle {
+		return setTimeout( cb, this.ms );
+	}
+
+	
+	public promise(): ICancelablePromise<void> {
+		const deferred = new Deferred<void>;
+		if ( this.isEmpty() ) {
+			deferred.resolve();
+		} else {
+			this.timeout( () => deferred.resolve() );
+		}
+		return deferred.asCancelablePromise;
+	}
+
+	public delay( cb: () => unknown ): { cancel: TVoidFunction } {
+		const deferred = this.promise();
+		void deferred.then( () => {
+			cb();
+		}, _err => {
+			return; // Do nothing on cancelation ( err is always an instance of DeferredCanceledError )
+		} );
+		return { cancel: () => deferred.cancel() };
+	}
+
+	public debounce<T>( fn: ( t: T ) => void ) {
+		let handle: TMaybe<TTimeoutHandle> = null;
+		return ( t: T ) => {
+			if ( handle )
+				clearTimeout( handle );
+			handle = this.timeout( () => {
+				handle = null;
+				fn( t );
+			} );
+		}
+	}
+
+	public toDigitalClock(): string {
+		const units = this.toUnits();
+		// data.hours += data.days * 24; // roll over days as hours.
+		return pad( units.hours.toString(), 2, '0' ) + ':' + pad( units.minutes.toString(), 2, '0' ) + ':' + pad( units.seconds.toString(), 2, '0' );
+	}
+
+	public get asSeconds(): string {
+		if ( this.ms < 0 )
+			return "0";
+		if ( this.ms < 1000 )
+			return ( this.ms / 1000 ).toFixed( 1 );
+		return Math.floor( this.seconds ).toString();
+	}
+
+	public fromNow(): TimeInstant {
+		return TimeInstant.now().addDuration( this );
+	}
+
+	public differenceFrom( other: TimeDuration ): TimeDuration {
+		return new TimeDuration( Math.abs( this.ms - other.ms ), TimeUnit.MILLISECONDS );
+	}
+
+	/** @deprecated: Use fromNow instead **/
+	public addCurrentTime() {
+		return this.fromNow();
+	}
+
+	public isGreaterThan( other: TimeDuration ): boolean {
+		return this.ms > other.ms;
+	}
+
+	public isLessThan( other: TimeDuration ): boolean {
+		return this.ms < other.ms;
+	}
+
+	public compareTo( other: TimeDuration ): TComparisonResult {
+		if ( this.ms === other.ms ) {
+			return 0;
+		} else if ( this.isLessThan( other ) ) {
+			return -1;
+		} else {
+			return 1;
+		}
+	}
+
+	public atLeast( other: TimeDuration ): TimeDuration {
+		if ( !this.isLessThan( other ) ) {
+			return this;
+		} else {
+			return other;
+		}
+	}
+
+	public atMost( other: TimeDuration ): TimeDuration {
+		if ( !this.isGreaterThan( other ) ) {
+			return this;
+		} else {
+			return other;
+		}
+	}
+
+	public isEmpty(): boolean {
+		return this.ms <= 0;
+	}
+
+	public isNotEmpty(): boolean {
+		return this.ms > 0;
+	}
+
+	/**
+	 * This method is used to provide a better DX when inspecting a TimeInstant object in DevTools.
+	 */
+	protected get _duration() {
+		return this.formatted;
+	}
+
+	public override toString() {
+		return `${this.constructor.name}[${this.formatted}]`;
+	}
+
+	public static parseHumanTime( humanTime: string ): TimeDuration {
+		const match = humanTime.trim().match( /^(?:([0-9]+)d|)\s*(?:([0-9]+)h|)\s*(?:([0-9]+)m|)\s*(?:([0-9]+)s|)$/ );
+		if ( match ) {
+			const [ _, days, hours, minutes, seconds ] = match;
+			return new TimeDuration( TimeBase.toMs( { days: Number( days ?? 0 ), hours: Number( hours ?? 0 ), minutes: Number( minutes ?? 0 ), seconds: Number( seconds ?? 0 ) } ), TimeUnit.MILLISECONDS );
+		}
+		throw new Error( 'Failed to parse time: ' + humanTime );
+	}
+
+	public static compare( a: TimeDuration, b: TimeDuration ): TComparisonResult {
+		return a.compareTo( b );
+	}
+
+	public static ms = durationConstructor( TimeUnit.MILLISECONDS );
+	public static seconds = durationConstructor( TimeUnit.SECONDS );
+	public static minutes = durationConstructor( TimeUnit.MINUTES );
+	public static hours = durationConstructor( TimeUnit.HOURS );
+	public static days = durationConstructor( TimeUnit.DAYS );
+
+	public static shamefulUnref = ( ms: TAllowedTimeDuration ): number => {
+		if ( ms instanceof TimeDuration ) {
+			return ms.ms;
+		}
+		return ms;
+	}
+	public static shamefulRef = ( ms: TAllowedTimeDuration ): TimeDuration => {
+		if ( ms instanceof TimeDuration ) {
+			return ms;
+		}
+		if ( ms < 0 ) {
+			ms = 0;
+		}
+		return TimeDuration.ms( ms );
+	}
+
+	public static unref = ( ms: TValidTimeDuration ): TPredefinedTimeDuration => {
+		return TimeDuration.shamefulUnref( ms ) as TPredefinedTimeDuration;
+	}
+
+	public static ref = ( ms: TValidTimeDuration ): TimeDuration => {
+		return TimeDuration.shamefulRef( ms );
+	}
+
+	public static fromMs( ms: number ) {
+		return new TimeDuration( ms, TimeUnit.MILLISECONDS );
+	}
+
+	public static distanceFromNow( instant: TimeInstant ): TimeDuration {
+		return TimeDuration.distance( TimeInstant.now(), instant );
+	}
+
+	public static distance( instant1: TimeInstant, instant2: TimeInstant ): TimeDuration {
+		return instant1.distanceFrom( instant2 );
+	}
+
+	public static greatest( duration1: TimeDuration, duration2: TimeDuration ): TimeDuration {
+		return duration1.isGreaterThan( duration2 ) ? duration1 : duration2;
+	}
+
+	public static lowest( duration1: TimeDuration, duration2: TimeDuration ): TimeDuration {
+		return duration1.isLessThan( duration2 ) ? duration1 : duration2;
+	}
+
+	public static ZERO = new TimeDuration( 0, TimeUnit.MILLISECONDS );
+
+	public static fromJSON( ms: number ) {
+		return TimeDuration.ms( ms );
+	}
+
+}
+
+interface IDurationConstructor {
+	( a: number ): TimeDuration
+	/** @deprecated[2023-06] Use RandomTimeDuration instead */( a: number, b?: number ): TimeDuration
+}
+
+/** @deprecated[2023-06] Use RandomTimeDuration instead */
+function durationConstructor( unit: TimeUnit ): IDurationConstructor {
+	return ( a: number, b?: number ) => {
+		const aMs = unit.toMs( a );
+		const bMs = b ? unit.toMs( b ) : aMs;
+		return TimeDuration.fromMs( randomInterval( aMs, bMs ) );
+	}
+}
+
+export type TPredefinedTimeDuration = 0 | 50 | 100 | 150 | 200 | 250 | 300 | 500 | 1000 | 1500 | 2000 | 2500 | 5000;
+export type TValidTimeDuration = TimeDuration | TPredefinedTimeDuration;
+type TAllowedTimeDuration = TValidTimeDuration | number; // eslint-disable-line @typescript-eslint/no-redundant-type-constituents
+
+export function isAllowedTimeDuration( t: unknown ): t is TAllowedTimeDuration {
+	return ( typeof t === "number" && t > 0 ) || t instanceof TimeDuration;
+}
+
+export default TimeDuration;

package/src/time/TimeFrequency.ts

@@ -0,0 +1,28 @@
+import { TPositiveNumber } from "../types";
+import TimeDuration from "./TimeDuration";
+
+export default class TimeFrequency {
+
+	public constructor(
+		public readonly times: TPositiveNumber,
+		public readonly period: TimeDuration,
+	) { 
+		if ( isNaN( times ) || times <= 0 )
+			throw new Error();
+		if ( period.isEmpty() )
+			throw new Error();
+	}
+
+	public get frequency() {
+		return this.period.divideBy( this.times );
+	}
+
+	public static onceEvery( period: TimeDuration ) {
+		return new TimeFrequency( 1, period );
+	}
+
+	public static twiceEvery( period: TimeDuration ) {
+		return new TimeFrequency( 2, period );
+	}
+
+}