nhb-toolbox 4.20.32 → 4.20.40

package/CHANGELOG.md

@@ -6,6 +6,10 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.20.40] - 2025-09-18
+
+- **Added** new **utility types**: `DeepPartialAll`, `Join`,`Split` along with `ValidArray`, `List` and _more_.
+
 ## [4.20.32] - 2025-09-17
 
 - **Renamed** `isPastParticiple()` method to `isParticiple()` in `Verbalizer/verbalizer`.

package/dist/dts/types/index.d.ts

@@ -38,17 +38,17 @@ export type NonNullishPrimitiveKey<T> = {
 /** Falsy primitive type  */
 export type FalsyPrimitive = false | 0 | '' | null | undefined;
 /** A generic class constructor */
-export type Constructor = new (...args: any[]) => unknown;
+export type Constructor = new (...args: any) => any;
 /** Generic function type */
-export type GenericFn = (...args: unknown[]) => unknown;
+export type GenericFn = (...args: any) => any;
 /** Generic function type that returns `void` */
-export type VoidFunction = (...args: any[]) => void;
+export type VoidFunction = (...args: any) => void;
 /** Debounced function type after certain delay */
 export type DelayedFn<T extends VoidFunction> = (...args: Parameters<T>) => void;
 /** Throttled function type after specific delay */
 export type ThrottledFn<T extends VoidFunction> = (...args: Parameters<T>) => void;
 /** Asynchronous function type */
-export type AsyncFunction<T> = (...args: unknown[]) => Promise<T>;
+export type AsyncFunction<T> = (...args: any) => Promise<T>;
 /** Advanced types to exclude from counting as object key */
 export type AdvancedTypes = Array<unknown> | File | FileList | Chronos | DateLike | Blob | Date | RegExp | WeakMap<WeakKey, unknown> | WeakSet<WeakKey> | Map<unknown, unknown> | Set<unknown> | Function | GenericFn | VoidFunction | AsyncFunction<unknown> | Promise<unknown> | Error | EvalError | RangeError | ReferenceError | SyntaxError | TypeError | URIError | bigint | symbol;
 /** Helper to detect if a type has methods */
@@ -76,4 +76,61 @@ export interface ClassDetails {
 }
 /** Literal type for `partial` and `required` */
 export type PartialOrRequired = 'partial' | 'required';
+/**
+ * - Utility type to assert that a given type condition evaluates to `true`.
+ *
+ * @remarks
+ * - This type is mainly used in **type-level tests** to enforce that a condition (usually produced by {@link Equal}) is satisfied.
+ * - If the condition is not `true`, TypeScript will raise an error at compile time.
+ *
+ * @example
+ * // Passes ✅
+ * type Test1 = Expect<true>;
+ *
+ * // Fails ❌ - will cause a type error
+ * type Test2 = Expect<false>;
+ */
+export type Expect<T extends true> = T;
+/**
+ * * Utility type that checks whether two types `X` and `Y` are strictly equal.
+ *
+ * @remarks
+ * - This type uses conditional types and generic inference tricks to compare whether two types are identical.
+ * - It resolves to `true` if `X` and `Y` are the same type, otherwise `false`.
+ *
+ * _Typically used together with {@link Expect} for type-level assertions in tests._
+ *
+ * @example
+ * type Test1 = Equal<string, string>; // true
+ * type Test2 = Equal<string, number>; // false
+ *
+ * // Example with Expect
+ * type Check = Expect<Equal<'a', 'a'>>; // ✅ Compiles
+ * type Fail  = Expect<Equal<'a', 'b'>>; // ❌ Type error
+ */
+export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * * Ensures that an array has **at least one element**.
+ *
+ * @remarks
+ * - This type enforces non-empty arrays by requiring the first element `T`, followed by zero or more additional `T`s.
+ *
+ * @example
+ * type NonEmpty = ValidArray<number>; 	// [number, ...number[]]
+ * const arr1: NonEmpty = [1];       	// ✅ OK
+ * const arr2: NonEmpty = [];        	// ❌ Error (empty array not allowed)
+ */
+export type ValidArray<T> = [T, ...Array<T>];
+/**
+ * * A readonly array of elements of type `T`.
+ *
+ * @remarks
+ * - Shorthand for `ReadonlyArray<T>`. Used to represent immutable lists.
+ *
+ * @example
+ * type Numbers = List<number>;	// readonly number[]
+ * const arr: Numbers = [1, 2, 3];	// ✅ OK
+ * arr.push(4);                   	// ❌ Error (readonly)
+ */
+export type List<T = any> = ReadonlyArray<T>;
 export {};

package/dist/dts/utils/types.d.ts

@@ -1,5 +1,5 @@
 import type { GenericObject, NestedPrimitiveKey } from '../object/types';
-import type { AdvancedTypes, Numeric } from '../types/index';
+import type { AdvancedTypes, List, NormalPrimitive, Numeric } from '../types/index';
 /** Options to initialize Paginator */
 export interface PaginatorOptions {
     /** The total number of items. */
@@ -72,7 +72,11 @@ export type ValueOf<T> = T[keyof T];
  */
 export type KeysOfUnion<T> = T extends T ? keyof T : never;
 /**
- * * Recursively makes all properties in an object type optional.
+ * * Recursively makes all potential standard js object properties optional.
+ *
+ * @remarks
+ * - It excludes complex types like `Array`, `Map`, `File`, `Date`, `Chronos` etc. from being recursively partial.
+ * - Please, refer to {@link AdvancedTypes} to learn more about these complex types.
  *
  * @example
  * type Config = { a: string; nested: { b: number } };
@@ -82,6 +86,17 @@ export type KeysOfUnion<T> = T extends T ? keyof T : never;
 export type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends AdvancedTypes ? T[K] : T[K] extends object ? DeepPartial<T[K]> : T[K];
 };
+/**
+ * * Recursively makes all properties in any object or array type optional.
+ *
+ * @example
+ * type Config = { a: string; nested: { b: number } };
+ * type PartialConfig = DeepPartial<Config>;
+ * // { a?: string; nested?: { b?: number } }
+ */
+export type DeepPartialAll<T> = T extends Array<infer El> ? Array<DeepPartialAll<El>> : {
+    [K in keyof T]?: DeepPartialAll<T[K]>;
+};
 /**
  * * Removes `readonly` modifiers from all properties of an object type.
  *
@@ -444,4 +459,67 @@ export type RequireExactly<T extends GenericObject, N extends number> = {
  * const s4: OneOrTwo = {};                                 		// ❌ (0 keys)
  */
 export type RequireBetween<T extends GenericObject, Min extends number, Max extends number, C extends unknown[] = BuildTuple<Max>, Acc extends unknown[] = BuildTuple<Min>> = RequireExactly<T, Acc['length']> | (Acc['length'] extends Max ? never : RequireBetween<T, Min, Max, C, [...Acc, unknown]>);
+/**
+ * * Cast one type to another while preserving compatibility.
+ *
+ * @remarks
+ * - Ensures that `A1` extends `A2`. If not, falls back to `A2`.
+ * - Useful for enforcing constraints on generics or parameters.
+ *
+ * @param A1 - Type to check.
+ * @param A2 - Type to cast to.
+ * @returns `A1` if it extends `A2`, otherwise `A2`.
+ *
+ * @example
+ * type T0 = Cast<'42', string>; // '42'
+ * type T1 = Cast<'42', number>; // number
+ * type T2 = Cast<42, number>;   // 42
+ */
+export type Cast<A1, A2> = A1 extends A2 ? A1 : A2;
+/**
+ * * Remove the last element of a list (array).
+ *
+ * @remarks Produces a new tuple/list type with the last element removed.
+ *
+ * @example
+ * type T0 = Pop<[1, 2, 3]>;    // [1, 2]
+ * type T1 = Pop<[]>;           // []
+ * type T2 = Pop<['a']>;        // []
+ */
+export type Pop<L extends List> = L extends readonly [...infer El, any] | readonly [...infer El, any?] ? El : L;
+type __Split<S extends string, D extends string, T extends string[] = []> = S extends `${infer BS}${D}${infer AS}` ? __Split<AS, D, [...T, BS]> : [...T, S];
+type _Split<S extends string, D extends string = ''> = D extends '' ? Pop<__Split<S, D>> : __Split<S, D>;
+/**
+ * ✂️ Split a string literal by a given delimiter into a list of strings.
+ *
+ * @remarks
+ * Produces a tuple of substrings by splitting `S` at each occurrence of `D`.
+ *
+ * @param S - String literal to split.
+ * @param D - Delimiter to split on (default: empty string, i.e., character split).
+ * @returns A list of string literals.
+ *
+ * @example
+ * type T0 = Split<'a,b,c', ','>; // ['a', 'b', 'c']
+ * type T1 = Split<'hello', ''>;  // ['h', 'e', 'l', 'l', 'o']
+ * type T2 = Split<'foo-bar', '-'>; // ['foo', 'bar']
+ */
+export type Split<S extends string, D extends string = ''> = _Split<S, D> extends infer X ? Cast<X, string[]> : never;
+type _Join<T extends List, D extends string> = T extends [] ? '' : T extends [NormalPrimitive] ? `${T[0]}` : T extends [NormalPrimitive, ...infer R] ? `${T[0]}${D}${_Join<R, D>}` : string;
+/**
+ * * Join a list of string/number/boolean literals into a single string.
+ *
+ * @remarks
+ * Concatenates elements of `T` into a single string, separated by delimiter `D`.
+ *
+ * @param T - List of string/number/boolean literals.
+ * @param D - Delimiter to insert between elements (default: space `" "`).
+ * @returns A concatenated string literal.
+ *
+ * @example
+ * type T0 = Join<['a', 'b', 'c'], ','>; // "a,b,c"
+ * type T1 = Join<['2025', '09', '18'], '-'>; // "2025-09-18"
+ * type T2 = Join<['hello', 'world']>; // "hello world"
+ */
+export type Join<T extends List<NormalPrimitive>, D extends string = ' '> = _Join<T, D> extends infer X ? Cast<X, string> : never;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.20.32",
+  "version": "4.20.40",
   "description": "A versatile collection of smart, efficient, and reusable utility functions and classes for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",