@zelgadis87/utils-core 5.2.1 → 5.2.3

package/package.json

@@ -1,14 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.2.1",
+  "version": "5.2.3",
   "author": "Zelgadis87",
   "license": "ISC",
   "private": false,
   "files": [
     "/src",
     "/dist",
-    "/esbuild"
+    "/esbuild",
+    "*.md"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
@@ -19,17 +20,15 @@
     }
   },
   "devDependencies": {
-    "@stylistic/eslint-plugin-ts": "4.2.0",
-    "@typescript-eslint/eslint-plugin": "8.26.1",
-    "@typescript-eslint/parser": "8.26.1",
+    "@stylistic/eslint-plugin-ts": "4.4.1",
     "@vitest/coverage-v8": "3.2.4",
     "@vitest/ui": "3.2.4",
-    "esbuild": "0.25.8",
-    "eslint": "9.22.0",
-    "nx": "21.3.5",
+    "esbuild": "0.25.9",
+    "eslint": "9.35.0",
+    "nx": "21.5.2",
     "rimraf": "6.0.1",
     "typescript": "5.8.3",
-    "typescript-eslint": "8.26.1",
+    "typescript-eslint": "8.43.0",
     "vitest": "3.2.4"
   },
   "dependencies": {

package/src/sorting/Sorter.ts

@@ -149,7 +149,7 @@ const next = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFun
 			return compareNumbers( fns, transform as TFunction<T, number>, { direction: 'DESC', ...opts } );
 		},
 	} as const satisfies TSorterStepForNumbers<R, TSorter<T>>;
-	const retForStrings = {
+	const retForStringsV1 = {
 		...retAsUsing,
 		inLexographicalOrder( opts: { nullsFirst?: boolean } = {} ) {
 			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'ASC', ignoreCase: false, ...opts } );
@@ -163,6 +163,22 @@ const next = <T, R>( fns: ReadonlyArray<TComparisonFunction<T>>, transform: TFun
 		inReverseLexographicalOrderIgnoringCase( opts: { nullsFirst?: boolean } = {} ) {
 			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'DESC', ignoreCase: true, ...opts } );
 		},
+	} as const;
+	const retForStrings = {
+		...retAsUsing,
+		...retForStringsV1,
+		inLexicographicalOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'ASC', ignoreCase: false, ...opts } );
+		},
+		inLexicographicalOrderIgnoringCase( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'ASC', ignoreCase: true, ...opts } );
+		},
+		inReverseLexicographicalOrder( opts: { nullsFirst?: boolean } = {} ) {
+			return compareStrings( fns, transform as TFunction<T, string>, { direction: 'DESC', ignoreCase: false, ...opts } );
+		},
+		inReverseLexicographicalOrderIgnoringCase( 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,
@@ -317,10 +333,14 @@ type TSorterStepForNumbers<_T, 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;
+	/** @deprecated: Use inLexographicalOrder instead */ inLexographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	/** @deprecated: Use inLexographicalOrderIgnoringCase instead */ inLexographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
+	/** @deprecated: Use inReverseLexographicalOrder instead */ inReverseLexographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	/** @deprecated: Use inReverseLexographicalOrderIgnoringCase instead */ inReverseLexographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
+	inLexicographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	inLexicographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
+	inReverseLexicographicalOrder( opts?: { nullsFirst?: boolean } ): Ret;
+	inReverseLexicographicalOrderIgnoringCase( opts?: { nullsFirst?: boolean } ): Ret;
 };
 type TSorterStepForBooleans<_T, Ret> = {
 	truesFirst( opts?: { nullsFirst?: boolean } ): Ret;

package/src/utils/_index.ts

@@ -1,13 +1,14 @@
 
 export * from './arrays.js';
 export * from './booleans.js';
-export { TCssDeclarationRulesDictionary, TCssSelectorDeclarationRulesDictionary, cssDeclarationRulesDictionaryToCss, transformCssDictionary } from './css.js';
+export { cssDeclarationRulesDictionaryToCss, TCssDeclarationRulesDictionary, TCssSelectorDeclarationRulesDictionary, transformCssDictionary } from './css.js';
 export * from './empties.js';
 export * from './errors.js';
 export * from './functions.js';
 export * from './json.js';
 export * from './nulls.js';
 export * from './numbers.js';
+export * from './operations.js';
 export * from './primitives.js';
 export * from './promises.js';
 export * from './random.js';

package/src/utils/arrays/indexBy.ts

@@ -28,8 +28,12 @@ export function indexBySymbolWith<V>( arr: V[], getter: TFunction<V, symbol> ):
 function doIndexByWith<K extends string | number | symbol, V>( arr: V[], getter: TFunction<V, K> ): Record<K, V> {
 	return arr.reduce( ( dict, cur ) => {
 		const key = getter( cur );
-		if ( key !== null && key !== undefined )
+		if ( key !== null && key !== undefined ) {
+			if ( dict[ key ] ) {
+				throw new Error( `Multiple values indexed by same key "${ String( key ) }".` );
+			}
 			dict[ key ] = cur;
+		}
 		return dict;
 	}, {} as Record<K, V> );
 }

package/src/utils/arrays.ts

@@ -1,3 +1,4 @@
+import Optional, { type TOptional } from "../Optional.js";
 import type { TComparisonFunction } from "../sorting/_index.js";
 import type { TAccumulator, TBiPredicate, TPredicate, TTransformer } from "./functions.js";
 import { isNullOrUndefined, type TMaybe } from "./nulls.js";
@@ -171,3 +172,19 @@ export function shallowArrayEquals( a: unknown[], b: unknown[] ): boolean {
 	}
 	return true;
 }
+
+export function findInArray<T>( arr: T[], predicate: TPredicate<T> ): TOptional<T> {
+	return Optional.ofNullable( arr.find( predicate ) );
+}
+
+export function zip<T, R>( ts: T[], rs: R[] ): [ T, R ][] {
+	if ( ts.length !== rs.length )
+		throw new Error( `Arrays must have the same length. Got ${ts.length} and ${rs.length}` );
+	return ts.map( ( t, i ) => [ t, rs[ i ]! ] as [ T, R ] );
+}
+
+export function unzip<T, R>( arr: [ T, R ][] ): [ T[], R[] ] {
+	return arr.reduce( ( [ ts, rs ], [ t, r ] ) => {
+		return [ [ ...ts, t ], [ ...rs, r ] ];
+	}, [ [], [] ] as [ T[], R[] ] );
+}

package/src/utils/errors/withTryCatch.ts

@@ -1,8 +1,8 @@
-
 import { asError } from "../errors.js";
 import { identity, type TFunction, type TTransformer } from "../functions.js";
+import type { TAsyncOperationTuple, TOperationTuple } from "../operations.js";
 
-export function withTryCatch<R>( fn: TFunction<void, R>, errMapFn: TTransformer<Error, Error> = identity ): [ R, undefined ] | [ undefined, Error ] {
+export function withTryCatch<R>( fn: TFunction<void, R>, errMapFn: TTransformer<Error, Error> = identity ): TOperationTuple<R, Error> {
 	try {
 		return [ fn(), void 0 ] as const;
 	} catch ( e: unknown ) {
@@ -10,7 +10,7 @@ export function withTryCatch<R>( fn: TFunction<void, R>, errMapFn: TTransformer<
 	}
 }
 
-export async function withTryCatchAsync<R>( fn: TFunction<void, Promise<R>>, errMapFn: TTransformer<Error, Error> = identity ): Promise<[ R, undefined ] | [ undefined, Error ]> {
+export async function withTryCatchAsync<R>( fn: TFunction<void, Promise<R>>, errMapFn: TTransformer<Error, Error> = identity ): TAsyncOperationTuple<R, Error> {
 	try {
 		return [ await fn(), void 0 ] as const;
 	} catch ( e: unknown ) {

package/src/utils/errors.ts

@@ -39,3 +39,20 @@ export function getCauseStackFromError( error: Error ) {
 	return `\ncaused by: ${getStackFromError( asError( error.cause ) )}`
 }
 
+/**
+ * Throws an error if a switch discriminated union type does not cover all the expected cases.  
+ * Expected usage: `
+ * switch ( x.type ) { 
+ *   case "x": return doX();
+ *   case "y": return doY();
+ *   ...
+ *   default: throw new NonExhaustiveSwitchError( x satisfies never );
+ * }`
+ */
+export class NonExhaustiveSwitchError extends Error {
+
+	constructor( value: unknown ) {
+		super( "Expected switch to be exhaustive, got: " + value );
+	}
+
+}

package/src/utils/operations.ts

@@ -0,0 +1,24 @@
+
+export type TOperation<T, E extends Error = Error> = {
+	success: false;
+	error: E;
+} | {
+	success: true;
+	data: T;
+};
+
+export type TAsyncOperation<T, E extends Error = Error> = Promise<TOperation<T, E>>;
+
+export type TOperationTuple<T, E extends Error = Error> = [ T, undefined ] | [ undefined, E ];
+
+export type TAsyncOperationTuple<T, E extends Error = Error> = Promise<TOperationTuple<T, E>>;
+
+export type TValidation<T, E extends Error = Error> = {
+	success: false;
+	errors: E[];
+} | {
+	success: true;
+	data: T;
+};
+
+export type TAsyncValidation<T, E extends Error = Error> = Promise<TValidation<T, E>>;

package/src/utils/records.ts

@@ -58,3 +58,23 @@ export function shallowRecordEquals( a: Record<string, unknown>, b: Record<strin
 	}
 	return true;
 }
+
+/**
+ * A utility type that checks if any property in a record type `T` has the `never` type.
+ * This type evaluates to `true` if at least one property in `T` is of type `never`, and `false` otherwise.
+ * It's commonly used to create compile-time assertions that prevent unintended changes where properties might accidentally become `never` due to type mismatches.
+ *
+ * @example Advanced usage for type guards
+ * ```typescript
+ * type TMap = { a: string; b: number; c: boolean };
+ * type TJsonSerializable = string | number | boolean;
+ *
+ * type TFiltered = {
+ *   [K in keyof TMap]: TMap[K] extends TJsonSerializable ? TMap[K] : never;
+ * };
+ *
+ * // If TMap changes and some property becomes not serializable, TFiltered will have 'never' values
+ * const _guard: THasNever<TFiltered> = false; // Compile error if any property became 'never'
+ * ```
+ */
+export type THasNever<T> = { [ K in keyof T ]: [ T[ K ] ] extends [ never ] ? true : false }[ keyof T ] extends false ? false : true;