@zelgadis87/utils-core 5.2.1 → 5.2.2

package/package.json

@@ -1,14 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@zelgadis87/utils-core",
-  "version": "5.2.1",
+  "version": "5.2.2",
   "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/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/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;