@zelgadis87/utils-core 4.0.0

package/package.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json.schemastore.org/package",
+  "name": "@zelgadis87/utils-core",
+  "version": "4.0.0",
+  "author": "Zelgadis87",
+  "license": "ISC",
+  "private": false,
+  "files": [
+    "/src",
+    "/dist",
+    "/esbuild"
+  ],
+  "wireit": {
+    "build:ts": {
+      "command": "tsc --emitDeclarationOnly",
+      "clean": "if-file-deleted",
+      "files": [
+        "./src/**"
+      ],
+      "output": [
+        "./dist/**"
+      ]
+    },
+    "build:cjs": {
+      "command": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=cjs --outfile=esbuild/index.cjs",
+      "clean": "if-file-deleted",
+      "files": [
+        "./src/**"
+      ],
+      "output": [
+        "./esbuild/index.cjs"
+      ]
+    },
+    "build:esm": {
+      "command": "esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=esbuild/index.mjs",
+      "clean": "if-file-deleted",
+      "files": [
+        "./src/**"
+      ],
+      "output": [
+        "./esbuild/index.mjs"
+      ]
+    },
+    "build": {
+      "dependencies": [
+        "build:ts",
+        "build:cjs",
+        "build:esm"
+      ]
+    },
+    "test": {
+      "command": "vitest run --passWithNoTests",
+      "clean": true,
+      "files": [
+        "./src/**/*.ts",
+        "./test/**/*.spec.ts"
+      ],
+      "output": []
+    },
+    "test:coverage": {
+      "command": "vitest run --coverage --passWithNoTests",
+      "clean": true,
+      "files": [
+        "./src/**/*.ts",
+        "./test/**/*.spec.ts"
+      ],
+      "output": [
+        "./coverage/*.*"
+      ]
+    },
+    "lint:strict": {
+      "command": "eslint .",
+      "dependencies": [],
+      "clean": false,
+      "files": [
+        "./*.ts"
+      ],
+      "output": []
+    },
+    "check": {
+      "dependencies": [
+        "lint:strict",
+        "test"
+      ]
+    },
+    "version": {
+      "dependencies": [
+        "build",
+        "check"
+      ]
+    },
+    "version:major": {
+      "command": "pnpm version major",
+      "dependencies": [
+        "version"
+      ],
+      "clean": false,
+      "files": [],
+      "output": []
+    },
+    "version:minor": {
+      "command": "pnpm version minor",
+      "dependencies": [
+        "version"
+      ],
+      "clean": false,
+      "files": [],
+      "output": []
+    },
+    "version:patch": {
+      "command": "pnpm version patch",
+      "dependencies": [
+        "version"
+      ],
+      "clean": false,
+      "files": [],
+      "output": []
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./esbuild/index.mjs",
+      "require": "./esbuild/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin-ts": "2.6.0-beta.1",
+    "@typescript-eslint/eslint-plugin": "rc-v8",
+    "@typescript-eslint/parser": "rc-v8",
+    "@vitest/coverage-v8": "^2.0.4",
+    "@vitest/ui": "^2.0.4",
+    "esbuild": "^0.23.0",
+    "eslint": "^9.8.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.4",
+    "wireit": "^0.14.5"
+  },
+  "scripts": {
+    "clean": "rimraf .wireit dist esbuild coverage",
+    "build": "wireit",
+    "lint": "pnpm eslint .",
+    "lint:errors": "pnpm lint --quiet",
+    "lint:strict": "wireit",
+    "test": "wireit",
+    "test:watch": "vitest dev --passWithNoTests",
+    "test:ui": "vitest dev --ui --coverage --passWithNoTests",
+    "test:coverage": "wireit",
+    "check": "wireit",
+    "version:major": "wireit",
+    "version:minor": "wireit",
+    "version:patch": "wireit",
+    "create:major": "pnpm clean && pnpm version:major && pnpm publish",
+    "create:minor": "pnpm clean && pnpm version:minor && pnpm publish",
+    "create:patch": "pnpm clean && pnpm version:patch && pnpm publish"
+  }
+}

package/src/Lazy.ts

@@ -0,0 +1,77 @@
+
+import { ensureDefined } from "./types";
+
+/**
+ * Class that stores a value that is computationally/memory intensive to initialize.
+ * The initialization of the value is done once and only if required (lazy initialization).
+ * @author gtomberli
+ */
+export default class Lazy<T> {
+
+	private _value: T | undefined = undefined;
+	private _initialized: boolean = false;
+	private _generator: () => T;
+
+	private constructor( generator: () => T ) {
+		this._generator = ensureDefined( generator );
+	}
+
+	public get value(): T | undefined {
+		return this._value;
+	}
+
+	public getOrCreate(): T {
+		if ( !this._initialized ) {
+			this._value = this._generator();
+			this._initialized = true;
+		}
+		return this._value!;
+	}
+
+	public getOrThrow( errorMessage?: "Value not initialized" ): T {
+		if ( !this._initialized )
+			throw new Error( errorMessage );
+		return this._value!;
+	}
+
+	public or( t: T ): T {
+		if ( !this._initialized ) {
+			return t;
+		} else {
+			return this._value!;
+		}
+	}
+
+	public isPresent() {
+		return this._initialized;
+	}
+
+	public isEmpty() {
+		return !this._initialized;
+	}
+
+	public ifPresent( fn: (t: T) => void ): void {
+		if ( this.isPresent() ) {
+			fn( this._value! );
+		}
+	}
+
+	public ifEmpty( fn: () => void ): void {
+		if ( this.isEmpty() ) {
+			fn();
+		}
+	}
+
+	public apply( fnPresent: (t: T) => void, fnEmpty: () => void ): void {
+		if ( this.isPresent() ) {
+			fnPresent( this._value! );
+		} else {
+			fnEmpty( );
+		}
+	}
+
+	public static of<T>( generator: () => T ): Lazy<T> {
+		return new Lazy( generator );
+	}
+
+}

package/src/LazyAsync.ts

@@ -0,0 +1,100 @@
+import { ensureDefined } from "./types/nulls.js";
+
+export default class LazyAsync<T> {
+
+	private _promise: Promise<T> | undefined = undefined;
+	private _pending: boolean = false;
+	private _resolvedValue: T | undefined = undefined;
+	private _error: Error | undefined = undefined;
+	private _generator: () => Promise<T>;
+
+	private constructor( generator: () => Promise<T> ) {
+		this._generator = ensureDefined( generator );
+	}
+
+	public getOrCreate(): Promise<T> {
+		if ( this.isEmpty() ) {
+			this._pending = true;
+			this._promise = this._generator();
+			this._promise.then( value => {
+				this._pending = false;
+				this._resolvedValue = value;
+			}, err => {
+				this._pending = false;
+				this._error = err;
+			} );
+		}
+		return this._promise as Promise<T>;
+	}
+
+	public isPresent() {
+		return this._promise !== undefined;
+	}
+
+	public isEmpty() {
+		return this._promise === undefined;
+	}
+
+	public isPending() {
+		return this.isPresent() && this._pending === true;
+	}
+
+	public isReady() {
+		return this.isPresent() && this._pending === false;
+	}
+
+	public isResolved() {
+		return this.isReady() && this._error === undefined;
+	}
+	
+	public isError() {
+		return this.isReady() && this._error !== undefined;
+	}
+
+	public ifPresent( fn: ( t: Promise<T> ) => void ): void {
+		if ( this.isPresent() ) {
+			fn( this._promise! );
+		}
+	}
+
+	public ifEmpty( fn: () => void ): void {
+		if ( this.isEmpty() ) {
+			fn();
+		}
+	}
+
+	public ifPending( fn: ( t: Promise<T> ) => void ): void {
+		if ( this.isPending() ) {
+			fn( this._promise! );
+		}
+	}
+
+	public ifReady( fn: ( t: Promise<T> ) => void ): void {
+		if ( this.isReady() ) {
+			fn( this._promise! );
+		}
+	}
+
+	public ifResolved( fn: ( t: T ) => void ): void {
+		if ( this.isResolved() ) {
+			fn( this._resolvedValue! );
+		}
+	}
+
+	public ifError( fn: ( err: Error ) => void ): void {
+		if ( this.isError() ) {
+			fn( this._error! );
+		}
+	}
+
+	public getOrThrow( errorMessage?: "Value not initialized" ): Promise<T> | never {
+		if ( !this._promise )
+			throw new Error( errorMessage );
+		return this._promise;
+	}
+
+	public static of<T>( generator: () => Promise<T> ): LazyAsync<T> {
+		return new LazyAsync( generator );
+	}
+
+}

package/src/Logger.ts

@@ -0,0 +1,44 @@
+import TimeInstant from "./time/TimeInstant";
+import noop from "./utils/noop";
+
+const LEVELS = [ "log", "debug", "info", "warn", "error" ] as const;
+type TLogLevel = keyof Console & typeof LEVELS[ number ]
+
+const timestamp = () => TimeInstant.now().asTimeString();
+
+type TLoggerOpts = {
+	console: Console;
+	enabled: boolean;
+	minLevel: Uppercase<TLogLevel>;
+}
+
+export default class Logger {
+
+	private enabled: boolean = true;
+	private console: Console;
+	private minLevel: number;
+
+	public constructor(
+		public readonly name: string,
+		args?: Partial<TLoggerOpts>
+	) {
+		this.console = args?.console ?? globalThis.console;
+		this.enabled = args?.enabled ?? true;
+		this.minLevel = LEVELS.indexOf( ( args?.minLevel ?? "DEBUG" ).toLowerCase() as TLogLevel );
+	}
+
+	public get log() { return this.logWrap( 'log' ); }
+	public get debug() { return this.logWrap( 'debug' ); }
+	public get info() { return this.logWrap( 'info' ); }
+	public get warn() { return this.logWrap( 'warn' ); }
+	public get error() { return this.logWrap( 'error' ); }
+
+	private logWrap( methodName: TLogLevel ) {
+		if ( !this.console[ methodName ] )
+			throw new Error( 'Invalid method name: ' + methodName );
+		if ( !this.enabled || !this.console || LEVELS.indexOf( methodName ) < this.minLevel )
+			return noop;
+		return this.console[ methodName ].bind( this.console, timestamp(), methodName.toUpperCase(), this.name );
+	}
+
+}

package/src/Optional.ts

@@ -0,0 +1,172 @@
+import { TConsumer, TFunction, TPredicate, TProducer, TVoidFunction } from "./types/functions.js";
+import { isDefined, isNullOrUndefined } from "./types/nulls.js";
+
+export class Optional<T> implements TOptional<T> {
+
+	private _present: boolean;
+	private _value: T | undefined;
+
+	private constructor( t: T | null | undefined ) {
+		const defined = isDefined( t );
+		this._value = defined ? t : undefined;
+		this._present = defined;
+	}
+
+	public get rawValue() {
+		return this._value;
+	}
+
+	public get(): T | never {
+		if ( this.isEmpty() )
+			throw new ErrorGetEmptyOptional();
+		return this.rawValue as T;
+	}
+
+	public set(t: T) {
+		if ( isNullOrUndefined( t ) )
+			throw new ErrorSetEmptyOptional();
+		this._value = t;
+		this._present = true;
+	}
+
+	public clear() {
+		this._value = undefined;
+		this._present = false;
+	}
+
+	public isEmpty(): this is TEmptyOptional<T> {
+		return !this._present;
+	}
+	public isPresent(): this is TPresentOptional<T> {
+		return this._present;
+	}
+
+	public ifEmpty( callback: TVoidFunction ) {
+		if ( this.isEmpty() )
+			callback();
+	}
+	public ifPresent( callback: TConsumer<T> ) {
+		if ( this.isPresent() )
+			callback( this.rawValue );
+	}
+	public apply( callbackIfPresent: TConsumer<T>, callbackIfEmpty: TVoidFunction ) {
+		if ( this.isEmpty() ) {
+			callbackIfEmpty();
+		} else {
+			callbackIfPresent( this.rawValue! );
+		}
+	}
+
+	public orElse( newValue: T | null | undefined ) {
+		if ( this.isEmpty() )
+			return Optional.ofNullable( newValue );
+		return this as TPresentOptional<T>;
+	}
+	public orElseGet( produceValue: TProducer<T | null | undefined> ) {
+		if ( this.isEmpty() ) {
+			const newValue = produceValue();
+			return Optional.ofNullable( newValue );
+		}
+		return this as TPresentOptional<T>;
+	}
+	public orElseThrow( produceError: TProducer<Error> ) {
+		if ( this.isEmpty() )
+			throw produceError();
+		return this as TPresentOptional<T>;
+	}
+
+	public mapTo<R>( mapper: TFunction<T, R | null | undefined> ) {
+		return this.flatMapTo( t => Optional.ofNullable( mapper( t ) ) );
+	}
+	public flatMapTo<R>( mapper: TFunction<T, TOptional<R>> ) {
+		if ( this.isPresent() ) {
+			const newValue = mapper( this.rawValue );
+			return newValue;
+		}
+		return this as TEmptyOptional<T>;
+	}
+
+	public filter( predicate: TPredicate<T> ): this | TEmptyOptional<T> {
+		if ( this.isPresent() ) {
+			if ( predicate( this.rawValue ) ) {
+				return this;
+			} else {
+				return Optional.empty();
+			}
+		} else {
+			return this;
+		}
+	}
+
+	public static empty<T>(): TEmptyOptional<T> {
+		return new Optional( undefined ) as any;
+	}
+	public static of<T>( t: T ): TPresentOptional<T> {
+		if ( isNullOrUndefined( t ) )
+			throw new ErrorCannotInstantiatePresentOptionalWithEmptyValue();
+		return new Optional( t ) as any;
+	}
+	public static ofNullable<T>( t: T | null | undefined ): TOptional<T> {
+		return new Optional( t ) as any;
+	}
+
+}
+export default Optional;
+
+export type TOptional<T> = {
+	readonly rawValue: T | undefined;
+
+	/**
+	 * @returns the currently stored value, if any; throws {@link ErrorGetEmptyOptional} otherwise;
+	 */
+	get(): T | never;
+	/**
+	 * Places a new value inside this optional. Throws {@link ErrorSetEmptyOptional} if t is null or undefined.
+	 */
+	set(t: T): void;
+	/**
+	 * Clears the current value from this optional, if any.
+	 */
+	clear(): void;
+	isEmpty(): boolean;
+	isPresent(): boolean;
+
+	ifEmpty: ( callback: TVoidFunction ) => void;
+	ifPresent: ( callback: TConsumer<T> ) => void;
+	apply( callbackIfPresent: TConsumer<T>, callbackIfEmpty: TVoidFunction ): void;
+
+	orElse: ( ( newValue: T | null | undefined ) => TOptional<T> );
+	orElseGet: ( produceValue: TProducer<T | null | undefined> ) => TOptional<T>;
+	orElseThrow: ( produceError: TProducer<Error> ) => TPresentOptional<T>;
+
+	mapTo<R>( mapper: TFunction<T, R> ): TOptional<R>;
+	flatMapTo<R>( mapper: TFunction<T, TOptional<R>> ): TOptional<R>;
+
+	filter( predicate: TPredicate<T> ): TOptional<T>;
+}
+export type TEmptyOptional<T> = TOptional<T> & {
+	readonly rawValue: undefined;
+	isEmpty(): true;
+	isPresent(): false;
+}
+export type TPresentOptional<T> = TOptional<T> & {
+	readonly rawValue: T;
+	isEmpty(): false;
+	isPresent(): true;
+}
+
+export class ErrorGetEmptyOptional extends Error {
+	constructor() {
+		super( "Cannot retrieve a value from an EmptyOptional." );
+	}
+}
+export class ErrorSetEmptyOptional extends Error {
+	constructor() {
+		super( "Cannot set a null or undefined value." );
+	}
+}
+export class ErrorCannotInstantiatePresentOptionalWithEmptyValue extends Error {
+	constructor() {
+		super( "Cannot initialize a PresentOptional with a null or undefined value." );
+	}
+}

package/src/async/CancelableDeferred.ts

@@ -0,0 +1,36 @@
+import Deferred from "./Deferred.js";
+
+interface ICancelablePromise<T> extends Promise<T> {
+	cancel(): void;
+}
+
+/** @deprecated use CancelableDeferredV2 instead. */
+export default class CancelableDeferred<T = void> extends Deferred<T> implements ICancelablePromise<T> {
+
+	private _canceled: boolean;
+
+	public get canceled(): boolean { return this._canceled; }
+
+	constructor() {
+		super();
+		this._canceled = false;
+	}
+	
+	public cancel() {
+		this._canceled = true;
+	}
+
+	protected override createInternals() {
+		let resolveSelf: ( value: T ) => void, rejectSelf: ( reason: Error ) => void;
+		const promise = new Promise<T>( ( resolve, reject ) => {
+			resolveSelf = ( value: T ) => { if ( !this._canceled ) resolve( value ); }
+			rejectSelf = ( reason: Error ) => { if ( !this._canceled ) reject( reason ); };
+		} );
+		return {
+			promise,
+			resolve: resolveSelf!,
+			reject: rejectSelf!,
+		};
+	}
+
+}

package/src/async/Deferred.ts

@@ -0,0 +1,84 @@
+import { TFunction } from "../types/functions.js";
+
+type DeferredInternals<T> = {
+	promise: Promise<T>;
+	resolve: TFunction<T, void>;
+	reject: TFunction<Error, void>;
+}
+
+export interface ICancelablePromise<T> extends Promise<T> {
+	cancel(): void;
+}
+
+export class DeferredCanceledError extends Error { }
+
+export class Deferred<T = void> implements Promise<T>, ICancelablePromise<T> {
+
+	private _pending: boolean;
+	private readonly _internals: DeferredInternals<T>;
+
+	public get pending(): boolean { return this._pending; }
+	/** @deprecated: Use resolve, then and catch directly; use asPromise to return a promise type. */ public get promise(): Promise<T> { return this._internals.promise; }
+
+	constructor() {
+		this._pending = true;
+		this._internals = this.createInternals();
+	}
+
+	public resolve( val: T ): void {
+		if ( !this._pending ) throw new Error( 'Illegal state exception' );
+		this._pending = false;
+		this._internals.resolve( val );
+	}
+
+	public reject( reason: Error ): void {
+		if ( !this._pending ) throw new Error( 'Illegal state exception' );
+		this._pending = false;
+		this._internals.reject( reason );
+	}
+
+	public then<R = T, S = T>( onFulfilled: ( ( value: T ) => R | PromiseLike<R> ) | null | undefined, onRejected?: ( ( reason: Error ) => S | PromiseLike<S> ) | null | undefined ): Promise<R | S> {
+		return this._internals.promise.then( onFulfilled, onRejected );
+	}
+
+	public catch<R = T>( onRejected: ( ( reason: Error ) => R | PromiseLike<R> ) | null | undefined ): Promise<T | R> {
+		return this._internals.promise.catch( onRejected );
+	}
+
+	public finally( onfinally: ( () => void ) | null | undefined ): Promise<T> {
+		return this._internals.promise.finally( onfinally );
+	}
+
+	public cancel(): void {
+		if ( !this._pending ) throw new Error( 'Illegal state exception' );
+		this._internals.reject( new DeferredCanceledError( 'Execution aborted by the user' ) );
+	}
+
+	public get asPromise(): Promise<T> {
+		return this;
+	}
+
+	public get asCancelablePromise(): ICancelablePromise<T> {
+		return this;
+	}
+
+	protected createInternals() {
+		let resolveSelf: ( value: T ) => void, rejectSelf: ( reason: Error ) => void;
+		const promise = new Promise<T>( ( resolve, reject ) => {
+			resolveSelf = resolve;
+			rejectSelf = reject;
+		} );
+		return {
+			promise,
+			resolve: resolveSelf!,
+			reject: rejectSelf!,
+		};
+	}
+
+	get [ Symbol.toStringTag ]() {
+		return '[object Deferred]';
+	}
+
+}
+
+export default Deferred;