@budsbox/lib-es 2.0.0 → 2.2.0

package/dist/array.d.ts

@@ -1,12 +1,22 @@
+import type { TupleN } from '@budsbox/lib-types';
+import type { FValue } from './types.js';
 /**
  * Ensures that the provided value is returned as an array. If the value is already an array,
  * it is returned as-is. If the value is not an array, it is wrapped in a new array.
  *
  * @param value - The value to be checked and converted into an array if necessary.
- * @return An array containing the original value or the original array if it was already an array.
+ * @returns An array containing the original value or the original array if it was already an array.
  */
-export declare function ensureArray<T>(value: T | readonly T[]): readonly T[];
 export declare function ensureArray<T>(value: T | T[]): T[];
+export declare function ensureArray<T>(value: readonly T[] | T): readonly T[];
+/**
+ * Creates an array of a fixed length with all elements initialized to the specified value.
+ *
+ * @param n - The length of the array to create.
+ * @param value - The value to fill the array with. Defaults to `null`.
+ * @returns A tuple of the specified length with all elements set to the given value.
+ */
+export declare function nArray<N extends number, T = null>(n: N, value?: FValue<number, T>): TupleN<N, T>;
 /**
  * Removes duplicate elements from the provided array while preserving the order of the first occurrence of each element.
  *
@@ -19,9 +29,9 @@ export declare const dedupe: <T>(items: readonly T[]) => T[];
  * Creates an array of unique values from the combined elements of the input arrays.
  *
  * @param arrays - The arrays to be merged and deduplicated.
- * @return An array containing unique elements from all input arrays.
+ * @returns An array containing unique elements from all input arrays.
  */
-export declare function union<T>(...arrays: ReadonlyArray<T | readonly T[]>): T[];
+export declare function union<T>(...arrays: ReadonlyArray<readonly T[] | T>): T[];
 /**
  * Computes the intersection of multiple arrays, returning an array that contains
  * all elements that are present in every input array.
@@ -30,14 +40,14 @@ export declare function union<T>(...arrays: ReadonlyArray<T | readonly T[]>): T[
  * Each array or element will be checked for intersection.
  * @returns An array containing elements that are present in all input arrays.
  */
-export declare function intersection<T>(...arrays: ReadonlyArray<T | readonly T[]>): T[];
+export declare function intersection<T>(...arrays: ReadonlyArray<readonly T[] | T>): T[];
 /**
  * Computes the difference between a source array and one or more arrays of exclusions.
  * Returns a new array containing elements from the source array that are not present in any of the exclusion arrays.
  *
- * @param source The source array to compare against.
- * @param excludes Arrays containing elements to be excluded from the source array.
- * @return A new array containing elements from the source array that are not in the exclusion arrays.
+ * @param source - The source array to compare against.
+ * @param excludes - Arrays containing elements to be excluded from the source array.
+ * @returns A new array containing elements from the source array that are not in the exclusion arrays.
  */
 export declare function diff<T>(source: readonly T[], ...excludes: ReadonlyArray<readonly T[]>): T[];
 //# sourceMappingURL=array.d.ts.map

package/dist/array.js

@@ -1,6 +1,18 @@
+import { isFunction } from '#guards';
 export function ensureArray(value) {
     return Array.isArray(value) ? value : [value];
 }
+export function nArray(n, value = null) {
+    // eslint-disable-next-line jsdoc/require-jsdoc
+    if (isFunction(value)) {
+        const newArray = new Array(n);
+        for (let i = 0; i < newArray.length; i++) {
+            newArray[i] = value(i);
+        }
+        return newArray;
+    }
+    return new Array(n).fill(value);
+}
 /**
  * Removes duplicate elements from the provided array while preserving the order of the first occurrence of each element.
  *
@@ -13,7 +25,7 @@ export const dedupe = (items) => Array.from(new Set(items));
  * Creates an array of unique values from the combined elements of the input arrays.
  *
  * @param arrays - The arrays to be merged and deduplicated.
- * @return An array containing unique elements from all input arrays.
+ * @returns An array containing unique elements from all input arrays.
  */
 export function union(...arrays) {
     return dedupe(arrays.flatMap((v) => v));
@@ -43,9 +55,9 @@ export function intersection(...arrays) {
  * Computes the difference between a source array and one or more arrays of exclusions.
  * Returns a new array containing elements from the source array that are not present in any of the exclusion arrays.
  *
- * @param source The source array to compare against.
- * @param excludes Arrays containing elements to be excluded from the source array.
- * @return A new array containing elements from the source array that are not in the exclusion arrays.
+ * @param source - The source array to compare against.
+ * @param excludes - Arrays containing elements to be excluded from the source array.
+ * @returns A new array containing elements from the source array that are not in the exclusion arrays.
  */
 export function diff(source, ...excludes) {
     const set = new Set(excludes.flatMap((v) => v));

package/dist/class-name.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=class-name.d.ts.map

package/dist/class-name.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=class-name.js.map

package/dist/guards.d.ts

@@ -1,67 +1,74 @@
 import type { Def, Nil, NonNil, Undef } from '@budsbox/lib-types';
+import type { Predicate, TypeGuard } from './types.js';
 /**
  * Checks if the provided value is `undefined`.
  *
  * @param value - The value to check for `undefined`.
- * @return `true` if the value is `undefined`, otherwise `false`.
+ * @returns `true` if the value is `undefined`, otherwise `false`.
  */
 export declare function isUndef(value: unknown): value is Undef;
 /**
  * Checks if a given value is defined (not `undefined`).
  *
  * @param value - The value to check.
- * @return Whether the value is defined.
+ * @returns Whether the value is defined.
  */
 export declare function isDef<U>(value: U): value is Def<U>;
 /**
  * Checks if the provided value is `null` or `undefined`.
  *
  * @param value - The value to be checked.
- * @return Returns `true` if the value is `null` or `undefined`, otherwise `false`.
+ * @returns Returns `true` if the value is `null` or `undefined`, otherwise `false`.
  */
 export declare function isNil(value: unknown): value is Nil;
 /**
  * Checks if the provided value is not null or undefined.
  *
  * @param value - The value to be checked.
- * @return Returns true if the value is not null or undefined; otherwise, false.
+ * @returns Returns true if the value is not null or undefined; otherwise, false.
  */
 export declare function isNotNil<T>(value: T): value is NonNil<T>;
+/**
+ * Checks if the provided value is not null or undefined.
+ *
+ * @param value - The value to be checked.
+ * @returns Returns true if the value is not null or undefined; otherwise, false.
+ */
 export declare function isNotNil(value: unknown): value is NonNil;
 /**
  * Checks if the provided value is strictly equal to true.
  *
  * @param value - The value to check.
- * @return Returns true if the value is strictly true, otherwise false.
+ * @returns Returns true if the value is strictly true, otherwise false.
  */
 export declare function isTrue(value: unknown): value is true;
 /**
  * Determines if the provided value is strictly `false`.
  *
  * @param value - The value to be checked.
- * @return Returns `true` if the value is `false`, otherwise returns `false`.
+ * @returns Returns `true` if the value is `false`, otherwise returns `false`.
  */
 export declare function isFalse(value: unknown): value is false;
 /**
  * Determines if the given value is truly, i.e., converts to true when used in a boolean context.
  *
  * @param value - The value to be tested for truthiness.
- * @return Returns true if the value is truthy, false otherwise.
+ * @returns Returns true if the value is truthy, false otherwise.
  */
 export declare function isTruly(value: unknown): boolean;
 /**
  * Determines if a given value is falsy.
  * A value is considered falsy if it evaluates to false when coerced to a boolean.
  *
- * @param value The value to be tested.
- * @return True if the value is falsy, otherwise false.
+ * @param value - The value to be tested.
+ * @returns True if the value is falsy, otherwise false.
  */
 export declare function isFalsy(value: unknown): boolean;
 /**
  * Checks if the given value is an object.
  *
  * @param value - The value to check.
- * @return True if the value is an object, false otherwise.
+ * @returns True if the value is an object, false otherwise.
  */
 export declare function isObject(value: unknown): value is object;
 /**
@@ -73,73 +80,116 @@ export declare function isObject(value: unknown): value is object;
  *
  * @param value - The value to check.
  * @param allowEmpty - Determines whether empty records are allowed.
- * @return A boolean indicating whether the value is a record.
+ * @returns A boolean indicating whether the value is a record.
  */
 export declare function isRecord(value: unknown, allowEmpty?: boolean): value is Record<PropertyKey, unknown>;
 /**
  * Checks if the given value is an array.
  *
- * @template T - Type of the value to be checked.
+ * @typeParam T - Type of the value to be checked.
  * @param value - The value to check.
- * @return True if the value is an array, otherwise false.
+ * @returns True if the value is an array, otherwise false.
  */
 export declare function isArray<T>(value: T | readonly T[]): value is readonly T[];
 /**
  * Checks if the provided value is an array.
  *
- * @template T - type of the value to be checked.
+ * @typeParam T - type of the value to be checked.
  * @param value - The value to be checked.
- * @return True if the value is an array, otherwise false.
+ * @returns True if the value is an array, otherwise false.
  */
 export declare function isArray<T>(value: T | T[]): value is T[];
 /**
  * Checks if the given value is an array.
  *
  * @param value - The value to be checked.
- * @return Returns true if the value is an array, otherwise false.
+ * @returns Returns true if the value is an array, otherwise false.
  */
 export declare function isArray(value: unknown): value is unknown[];
 /**
  * Determines if the provided value is of type Function.
  *
  * @param value - The value to be checked.
- * @return True if the value is a function; otherwise, false.
+ * @returns True if the value is a function; otherwise, false.
  */
-export declare function isFunction(value: unknown): value is CallableFunction;
+export declare function isFunction<TFn extends CallableFunction = CallableFunction>(value: unknown): value is TFn;
 /**
  * Determines if the provided value is a string.
  *
  * @param value - The value to check.
- * @return True if the value is a string, otherwise false.
+ * @returns True if the value is a string, otherwise false.
  */
 export declare function isString(value: unknown): value is string;
 /**
  * Checks if the provided value is a number and not NaN.
  *
  * @param value - The value to be checked.
- * @return Returns true if the value is a number and not NaN, otherwise false.
+ * @returns Returns true if the value is a number and not NaN, otherwise false.
  */
 export declare function isNumber(value: unknown): value is number;
 /**
  * Checks if the given value is of type boolean.
  *
  * @param value - The value to check.
- * @return A boolean indicating whether the value is a boolean or not.
+ * @returns A boolean indicating whether the value is a boolean or not.
  */
 export declare function isBoolean(value: unknown): value is boolean;
-export declare function hasProp(source: Nil, prop: PropertyKey, test?: (propValue: unknown) => boolean): false;
 /**
- * Checks if the given source has the specified property.
+ * Determines if a given property exists on a source object and optionally
+ * evaluates it with a provided predicate function.
+ *
+ * @param source - The object to check for the property existence. Can be `null` or `undefined`.
+ * @param prop - The property key to check on the source.
+ * @param test - Optional predicate function used to evaluate the property's value.
+ * @returns Returns `false` since the source is `null` or `undefined` in this function signature.
+ */
+export declare function hasProp(source: Nil, prop: PropertyKey, test?: Predicate<unknown>): false;
+/**
+ * Checks if a given property exists on the provided object.
+ *
+ * @param source - The object to check for the property.
+ * @param prop - The property key to check for existence on the object.
+ * @returns A boolean indicating whether the property exists on the object.
+ */
+export declare function hasProp<TKey extends PropertyKey>(source: NonNil, prop: TKey): source is Record<TKey, unknown>;
+/**
+ * Checks if the given object has a specific property that meets the criteria
+ * defined by a type guard function.
+ *
+ * @param source - The object to check for the property.
+ * @param prop - The key of the property to check for in the object.
+ * @param test - A type guard function that tests the property value against a type.
+ * @returns Returns `true` if the object has the specified property and the value passes
+ * the type guard, otherwise returns `false`.
+ */
+export declare function hasProp<TValue extends NonNil, TKey extends keyof TValue, TNarrowed extends TValue[TKey]>(source: TValue, prop: TKey, test: TypeGuard<Required<TValue>[TKey], TNarrowed>): source is TValue & Record<TKey, TNarrowed>;
+/**
+ * Checks if the given `source` object has a property specified by `prop` and verifies
+ * that the value of the property satisfies the condition defined by the `test` function.
+ *
+ * @param source - The object to be checked for the specified property.
+ * @param prop - The key of the property to check for existence in the `source`.
+ * @param test - A type guard function used to validate the type of the property's value.
+ * @returns A boolean indicating whether the `source` has the specified property and the value
+ * satisfies the type guard test.
+ */
+export declare function hasProp<TKey extends PropertyKey, TNarrowed>(source: unknown, prop: TKey, test: TypeGuard<unknown, TNarrowed>): source is Record<TKey, TNarrowed>;
+/**
+ * Checks if a given property exists on a source object and satisfies a specified test condition.
+ *
+ * @param source - The source object to check for the property.
+ * @param prop - The property key to check in the source object.
+ * @param test - A predicate function to test the value of the specified property.
+ * @returns True if the property exists on the source object and the test predicate returns true; otherwise, false.
+ */
+export declare function hasProp<TValue extends NonNil, TKey extends keyof TValue>(source: TValue, prop: TKey, test: Predicate<Required<TValue>[TKey]>): boolean;
+/**
+ * Checks if a given property exists on the specified source object and optionally validates it using a predicate function.
  *
- * @param source - The source to check for the property.
- * @param prop - The property to check for existence.
- * @return True if the source is an object and contains the property.
+ * @param source - The object on which the property check is performed.
+ * @param prop - The property key to check for existence in the source object.
+ * @param test - An optional predicate function to validate the property value.
+ * @returns Returns true if the property exists on the source object and the predicate (if provided) evaluates to true; otherwise, false.
  */
-export declare function hasProp<T, Key extends PropertyKey>(source: Record<PropertyKey, T>, prop: Key): source is Record<Key, T>;
-export declare function hasProp<Key extends PropertyKey>(source: unknown, prop: Key): source is Record<Key, unknown>;
-export declare function hasProp<T, Narrowed extends T, Key extends PropertyKey>(source: Record<PropertyKey, T>, prop: Key, test: (propValue: T) => propValue is Narrowed): source is Record<Key, Narrowed>;
-export declare function hasProp<T, Narrowed, Key extends PropertyKey>(source: Record<PropertyKey, T>, prop: Key, test: (propValue: unknown) => propValue is Narrowed): source is Record<Key, T & Narrowed>;
-export declare function hasProp<Key extends PropertyKey, T>(source: unknown, prop: Key, test: (propValue: unknown) => propValue is T): source is {
-    [K in Key]: T;
-};
+export declare function hasProp(source: unknown, prop: PropertyKey, test?: Predicate<unknown>): boolean;
 //# sourceMappingURL=guards.d.ts.map

package/dist/guards.js

@@ -2,7 +2,7 @@
  * Checks if the provided value is `undefined`.
  *
  * @param value - The value to check for `undefined`.
- * @return `true` if the value is `undefined`, otherwise `false`.
+ * @returns `true` if the value is `undefined`, otherwise `false`.
  */
 export function isUndef(value) {
     return value === undefined;
@@ -11,7 +11,7 @@ export function isUndef(value) {
  * Checks if a given value is defined (not `undefined`).
  *
  * @param value - The value to be checked.
- * @return Returns true if the value is defined, otherwise false.
+ * @returns Returns true if the value is defined, otherwise false.
  */
 export function isDef(value) {
     return value !== undefined;
@@ -20,7 +20,7 @@ export function isDef(value) {
  * Checks if the provided value is `null` or `undefined`.
  *
  * @param value - The value to be checked.
- * @return Returns `true` if the value is `null` or `undefined`, otherwise `false`.
+ * @returns Returns `true` if the value is `null` or `undefined`, otherwise `false`.
  */
 export function isNil(value) {
     return value == null;
@@ -32,7 +32,7 @@ export function isNotNil(value) {
  * Checks if the provided value is strictly equal to true.
  *
  * @param value - The value to check.
- * @return Returns true if the value is strictly true, otherwise false.
+ * @returns Returns true if the value is strictly true, otherwise false.
  */
 export function isTrue(value) {
     return value === true;
@@ -41,7 +41,7 @@ export function isTrue(value) {
  * Determines if the provided value is strictly `false`.
  *
  * @param value - The value to be checked.
- * @return Returns `true` if the value is `false`, otherwise returns `false`.
+ * @returns Returns `true` if the value is `false`, otherwise returns `false`.
  */
 export function isFalse(value) {
     return value === false;
@@ -50,7 +50,7 @@ export function isFalse(value) {
  * Determines if the given value is truly, i.e., converts to true when used in a boolean context.
  *
  * @param value - The value to be tested for truthiness.
- * @return Returns true if the value is truthy, false otherwise.
+ * @returns Returns true if the value is truthy, false otherwise.
  */
 export function isTruly(value) {
     return Boolean(value);
@@ -59,8 +59,8 @@ export function isTruly(value) {
  * Determines if a given value is falsy.
  * A value is considered falsy if it evaluates to false when coerced to a boolean.
  *
- * @param value The value to be tested.
- * @return True if the value is falsy, otherwise false.
+ * @param value - The value to be tested.
+ * @returns True if the value is falsy, otherwise false.
  */
 export function isFalsy(value) {
     return !isTruly(value);
@@ -69,7 +69,7 @@ export function isFalsy(value) {
  * Checks if the given value is an object.
  *
  * @param value - The value to check.
- * @return True if the value is an object, false otherwise.
+ * @returns True if the value is an object, false otherwise.
  */
 export function isObject(value) {
     return value != null && typeof value === 'object';
@@ -83,7 +83,7 @@ export function isObject(value) {
  *
  * @param value - The value to check.
  * @param allowEmpty - Determines whether empty records are allowed.
- * @return A boolean indicating whether the value is a record.
+ * @returns A boolean indicating whether the value is a record.
  */
 export function isRecord(value, allowEmpty = false) {
     return isObject(value) && (allowEmpty || Object.keys(value).length > 0);
@@ -95,8 +95,9 @@ export function isArray(value) {
  * Determines if the provided value is of type Function.
  *
  * @param value - The value to be checked.
- * @return True if the value is a function; otherwise, false.
+ * @returns True if the value is a function; otherwise, false.
  */
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
 export function isFunction(value) {
     return typeof value === 'function';
 }
@@ -104,7 +105,7 @@ export function isFunction(value) {
  * Determines if the provided value is a string.
  *
  * @param value - The value to check.
- * @return True if the value is a string, otherwise false.
+ * @returns True if the value is a string, otherwise false.
  */
 export function isString(value) {
     return typeof value === 'string';
@@ -113,7 +114,7 @@ export function isString(value) {
  * Checks if the provided value is a number and not NaN.
  *
  * @param value - The value to be checked.
- * @return Returns true if the value is a number and not NaN, otherwise false.
+ * @returns Returns true if the value is a number and not NaN, otherwise false.
  */
 export function isNumber(value) {
     return typeof value === 'number' && !Number.isNaN(value);
@@ -122,7 +123,7 @@ export function isNumber(value) {
  * Checks if the given value is of type boolean.
  *
  * @param value - The value to check.
- * @return A boolean indicating whether the value is a boolean or not.
+ * @returns A boolean indicating whether the value is a boolean or not.
  */
 export function isBoolean(value) {
     return typeof value === 'boolean';

package/dist/logical.d.ts

@@ -1,19 +1,19 @@
-import type { OnFalseParam, OnTrueParam, TestParam } from './types.js';
+import type { FValueFalse, FValueTrue, TestFn } from './types.js';
 import { isNotNil, isTrue } from '#guards';
 /**
  * Functional If
  *
- * Evaluates a value with a given test and returns a value (or executes a function and returns it's result) based on the result.
- *
- * @typeParam TrueType - The type of the value or the return type of the function if the test's result is true.
- * @typeParam FalseType - The type of the value or the return type of the function if the test's result is true, defaults to undefined.
+ * Evaluates a value with a given test and returns a value (or executes a function and returns its result) based on the result.
  *
+ * @typeParam TValue - The type of the value to be tested.
+ * @typeParam TTestFn - The type of the test function that takes the value as a parameter and returns a boolean.
+ * @typeParam TTrue - The type of the value or the return type of the function if the test's result is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if the test's result is true.
  * @param value - The value to test against the provided test function.
  * @param test - A function to evaluate the provided value.
  * @param onTrue - A function or value to execute or return if the test evaluates to true.
  * @param onFalse - A function or value to execute or return if the test evaluates to false.
- * @return The value or the result of the function based on the test result
- *
+ * @returns The value or the result of the function based on the test result
  * @example
  * ```ts
  * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
@@ -23,29 +23,31 @@ import { isNotNil, isTrue } from '#guards';
  * // result2 is 'Below 3'
  * ```
  */
-export declare function fif<ValueType, TestParamType extends TestParam<ValueType>, TrueType, FalseType = undefined>(value: ValueType, test: TestParamType, onTrue: OnTrueParam<ValueType, TestParamType, TrueType>, onFalse?: OnFalseParam<ValueType, TestParamType, FalseType>): TrueType | FalseType;
+export declare function fif<TValue, TTestFn extends TestFn<TValue>, TTrue, TFalse = undefined>(value: TValue, test: TTestFn, onTrue: FValueTrue<TValue, TTestFn, TTrue>, onFalse?: FValueFalse<TValue, TTestFn, TFalse>): TTrue | TFalse;
 /**
  * Functional If (Static)
  *
  * Evaluates a condition and returns a value or executes a function based on the result.
  *
- * @typeParam TrueType - The type of the value or the return type of the function if the condition is true.
- * @typeParam FalseType - The type of the value or the return type of the function if the condition is false, defaults to null.
- *
+ * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  * @param condition - The condition to evaluate.
  * @param onTrue - The value or function to return/execute if the condition is true. If it's a function, it receives `true` as an argument.
  * @param onFalse - The value or function to return/execute if the condition is false. If it's a function, it receives `false` as an argument.
- * @return The value or the result of the function based on the evaluated condition.
+ * @returns The value or the result of the function based on the evaluated condition.
  */
-export declare function fifs<TrueType, FalseType = undefined>(condition: boolean, onTrue: OnTrueParam<boolean, typeof isTrue, TrueType>, onFalse?: OnFalseParam<boolean, typeof isTrue, FalseType>): TrueType | FalseType;
+export declare function fifs<TTrue, TFalse = undefined>(condition: boolean, onTrue: FValueTrue<boolean, typeof isTrue, TTrue>, onFalse?: FValueFalse<boolean, typeof isTrue, TFalse>): TTrue | TFalse;
 /**
- * Ensures that the provided value is not null or undefined,
+ * Ensures that the provided value is not null or undefined
  * and returns a value (or executes a function and returns it's result) based on the result.
  *
+ * @typeParam TValue - The type of the value to be checked.
+ * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
+ * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  * @param value - The value to be checked.
  * @param onTrue - Callback function to be executed if the value is not null or undefined.
  * @param onFalse - (Optional) Callback function to be executed if the value is null or undefined.
- * @return The result of the appropriate callback function based on the evaluation of the value.
+ * @returns The result of the appropriate callback function based on the evaluation of the value.
  */
-export declare function sure<ValueType, TrueType, FalseType = undefined>(value: ValueType, onTrue: OnTrueParam<ValueType, typeof isNotNil, TrueType>, onFalse?: OnFalseParam<ValueType, typeof isNotNil, FalseType>): TrueType | FalseType;
+export declare function sure<TValue, TTrue, TFalse = undefined>(value: TValue, onTrue: FValueTrue<TValue, typeof isNotNil, TTrue>, onFalse?: FValueFalse<TValue, typeof isNotNil, TFalse>): TTrue | TFalse;
 //# sourceMappingURL=logical.d.ts.map

package/dist/logical.js

@@ -2,17 +2,17 @@ import { isFunction, isNotNil, isTrue } from '#guards';
 /**
  * Functional If
  *
- * Evaluates a value with a given test and returns a value (or executes a function and returns it's result) based on the result.
- *
- * @typeParam TrueType - The type of the value or the return type of the function if the test's result is true.
- * @typeParam FalseType - The type of the value or the return type of the function if the test's result is true, defaults to undefined.
+ * Evaluates a value with a given test and returns a value (or executes a function and returns its result) based on the result.
  *
+ * @typeParam TValue - The type of the value to be tested.
+ * @typeParam TTestFn - The type of the test function that takes the value as a parameter and returns a boolean.
+ * @typeParam TTrue - The type of the value or the return type of the function if the test's result is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if the test's result is true.
  * @param value - The value to test against the provided test function.
  * @param test - A function to evaluate the provided value.
  * @param onTrue - A function or value to execute or return if the test evaluates to true.
  * @param onFalse - A function or value to execute or return if the test evaluates to false.
- * @return The value or the result of the function based on the test result
- *
+ * @returns The value or the result of the function based on the test result
  * @example
  * ```ts
  * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
@@ -38,25 +38,27 @@ export function fif(value, test, onTrue, onFalse) {
  *
  * Evaluates a condition and returns a value or executes a function based on the result.
  *
- * @typeParam TrueType - The type of the value or the return type of the function if the condition is true.
- * @typeParam FalseType - The type of the value or the return type of the function if the condition is false, defaults to null.
- *
+ * @typeParam TTrue - The type of the value or the return type of the function if the condition is true.
+ * @typeParam TFalse - The type of the value or the return type of the function if condition is true.
  * @param condition - The condition to evaluate.
  * @param onTrue - The value or function to return/execute if the condition is true. If it's a function, it receives `true` as an argument.
  * @param onFalse - The value or function to return/execute if the condition is false. If it's a function, it receives `false` as an argument.
- * @return The value or the result of the function based on the evaluated condition.
+ * @returns The value or the result of the function based on the evaluated condition.
  */
 export function fifs(condition, onTrue, onFalse) {
     return fif(condition, isTrue, onTrue, onFalse);
 }
 /**
- * Ensures that the provided value is not null or undefined,
+ * Ensures that the provided value is not null or undefined
  * and returns a value (or executes a function and returns it's result) based on the result.
  *
+ * @typeParam TValue - The type of the value to be checked.
+ * @typeParam TTrue - The type of the value or the return type of the function if the value is not null or undefined.
+ * @typeParam TFalse - The type of the value or the return type of the function if the value is null or undefined.
  * @param value - The value to be checked.
  * @param onTrue - Callback function to be executed if the value is not null or undefined.
  * @param onFalse - (Optional) Callback function to be executed if the value is null or undefined.
- * @return The result of the appropriate callback function based on the evaluation of the value.
+ * @returns The result of the appropriate callback function based on the evaluation of the value.
  */
 export function sure(value, onTrue, onFalse) {
     return fif(value, isNotNil, onTrue, onFalse);

package/dist/random.d.ts

@@ -0,0 +1,19 @@
+import type { RNG } from './types.js';
+export type { RNG };
+/**
+ * Generates a hash value for the given string using the FNV-1a hashing algorithm.
+ *
+ * @param seed - The input string to hash.
+ * @returns The 32-bit unsigned integer hash of the input string.
+ */
+export declare function fnv1aHash(seed: string): number;
+/**
+ * Generates a pseudo-random number generator (PRNG) based on the Mulberry32 algorithm.
+ *
+ * @param seed - The seed for the random number generator. It can be a string or a numeric value.
+ * If a string is provided, it will be hashed into a numeric value before use.
+ * @returns An object containing the seed and a `next` function that produces the next pseudo-random
+ * number in the sequence as a floating-point value in the range [0, 1).
+ */
+export declare function mulberry32(seed: string | number): RNG;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.js

@@ -0,0 +1,35 @@
+import { isString } from '#guards';
+/**
+ * Generates a hash value for the given string using the FNV-1a hashing algorithm.
+ *
+ * @param seed - The input string to hash.
+ * @returns The 32-bit unsigned integer hash of the input string.
+ */
+export function fnv1aHash(seed) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < seed.length; i += 1) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return h >>> 0;
+}
+/**
+ * Generates a pseudo-random number generator (PRNG) based on the Mulberry32 algorithm.
+ *
+ * @param seed - The seed for the random number generator. It can be a string or a numeric value.
+ * If a string is provided, it will be hashed into a numeric value before use.
+ * @returns An object containing the seed and a `next` function that produces the next pseudo-random
+ * number in the sequence as a floating-point value in the range [0, 1).
+ */
+export function mulberry32(seed) {
+    seed = isString(seed) ? fnv1aHash(seed) : seed;
+    let t = seed >>> 0;
+    const next = () => {
+        t += 0x6d2b79f5;
+        let x = Math.imul(t ^ (t >>> 15), 1 | t);
+        x ^= x + Math.imul(x ^ (x >>> 7), 61 | x);
+        return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
+    };
+    return { seed, next };
+}
+//# sourceMappingURL=random.js.map

package/dist/string.d.ts

@@ -1,5 +1,5 @@
 import type { CamelCase, DelimiterCase, KebabCase, PascalCase, SnakeCase } from 'type-fest';
-import type { Nil } from '@budsbox/lib-types';
+import type { Maybe, Nil, Undef } from '@budsbox/lib-types';
 import type { ParsedPackageName } from './types.js';
 export type { ParsedPackageName };
 /**
@@ -25,6 +25,64 @@ export declare function serializePackageName(parsedPackageName: Readonly<ParsedP
  * @returns The string representation of the package name if valid, or an empty string if `allowNil` is true and the input is Nil.
  */
 export declare function serializePackageName(parsedPackageName: Readonly<ParsedPackageName> | Nil, allowNil: true): string;
+/**
+ * Resolves the package name based on the provided identifier and options.
+ * Can return either a string representing the package name or a parsed package name object.
+ *
+ * @param ident - The package identifier, either as a string or a parsed package name object.
+ * @param options - Optional settings to modify the resolution behavior.
+ *                  Includes an optional `baseScope` to use as a default scope and a `parsed` flag
+ *                  to indicate whether the result should be returned as a parsed package name object.
+ * @returns The resolved package name as a string if `parsed` is false or not specified,
+ *         or as a `ParsedPackageName` object if `parsed` is true.
+ */
+export declare function resolvePackageName<TParsed extends boolean = false>(ident: string | Readonly<ParsedPackageName>, options?: Readonly<{
+    baseScope?: Undef<string>;
+    parsed?: TParsed;
+}>): TParsed extends true ? ParsedPackageName : string;
+/**
+ * Options for formatting the package name
+ */
+export interface PackageNameFormatOptions {
+    /**
+     * The root identifier for the package.
+     */
+    root?: Maybe<string>;
+    /**
+     * The parent package name.
+     */
+    parent?: Maybe<string>;
+    /**
+     * The path to the package, relative to its parent.
+     */
+    relCwd?: Undef<string>;
+    /**
+     * The delimiter used to separate path chunks.
+     */
+    pathDelimiter?: Undef<string>;
+    /**
+     * The delimiter used to separate parents name from the base name of the package.
+     */
+    nameDelimiter?: Undef<string>;
+    /**
+     * Array of path chunks to be excluded when constructing the path.
+     */
+    excludePathChunks?: Undef<readonly string[]>;
+}
+/**
+ * Formats a package name by combining the base name with processed parent and directory path details.
+ *
+ * @param base - The base name of the package, without the scope or any prefixes.
+ * @param options - An object providing configuration options for formatting the package name.
+ * @param options.root - The root identifier for the package. Defaults to `null`.
+ * @param options.parent - The parent package name. Defaults to the value of `root`.
+ * @param options.relCwd - The path to the package, relative to its parent. Defaults to an empty string.
+ * @param options.pathDelimiter - The delimiter used to separate path chunks. Defaults to `'-'`.
+ * @param options.nameDelimiter - The delimiter used to separate parents name from the base name of the package. Defaults to `'_'`.
+ * @param options.excludePathChunks - Array of path chunks to be excluded when constructing the path. Defaults to `['packages']`.
+ * @returns The formatted package name as a string.
+ */
+export declare function formatPackageName(base: string, { root, parent, relCwd, pathDelimiter, nameDelimiter, excludePathChunks, }?: Readonly<PackageNameFormatOptions>): string;
 /**
  * Converts the provided value to a string representation suitable for debugging purposes.
  *
@@ -51,6 +109,16 @@ export declare function clampWS(str: string): string;
  * @returns The combined path as a single string, with proper slash formatting.
  */
 export declare function joinPath(...parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+/**
+ * Splits a given Unix-like path into an array of its components based on the "/" delimiter.
+ * Optionally keeps empty chunks in the result.
+ *
+ * @param path - The file path to be split into an array of components.
+ * @param keepEmptyChunks - A boolean indicating whether empty strings (resulting from consecutive delimiters)
+ * should be preserved in the output array. Defaults to `false`.
+ * @returns An array of strings representing the components of the path.
+ */
+export declare function splitPath(path: string, keepEmptyChunks?: boolean): string[];
 /**
  * Transforms a given string into camelCase format.
  *

package/dist/string.js

@@ -1,4 +1,4 @@
-import { isNil, isNotNil } from './guards.js';
+import { isNil, isNotNil, isString } from './guards.js';
 /**
  * Parses a package name string to extract its scope and name.
  *
@@ -20,6 +20,43 @@ export function serializePackageName(parsedPackageName, allowNil = false) {
     const { scope, name } = parsedPackageName ?? { scope: null, name: '' };
     return joinPath(scope?.replace(/^@?/, '@'), name);
 }
+export function resolvePackageName(ident, { baseScope, parsed = false, } = {}) {
+    const { scope, name } = isString(ident) ? parsePackageName(ident) : ident;
+    const parsedIdent = {
+        scope: scope ?? baseScope ?? null,
+        name,
+    };
+    return parsed ? parsedIdent : serializePackageName(parsedIdent);
+}
+/**
+ * Formats a package name by combining the base name with processed parent and directory path details.
+ *
+ * @param base - The base name of the package, without the scope or any prefixes.
+ * @param options - An object providing configuration options for formatting the package name.
+ * @param options.root - The root identifier for the package. Defaults to `null`.
+ * @param options.parent - The parent package name. Defaults to the value of `root`.
+ * @param options.relCwd - The path to the package, relative to its parent. Defaults to an empty string.
+ * @param options.pathDelimiter - The delimiter used to separate path chunks. Defaults to `'-'`.
+ * @param options.nameDelimiter - The delimiter used to separate parents name from the base name of the package. Defaults to `'_'`.
+ * @param options.excludePathChunks - Array of path chunks to be excluded when constructing the path. Defaults to `['packages']`.
+ * @returns The formatted package name as a string.
+ */
+export function formatPackageName(base, { root = null, parent = root, relCwd = '', pathDelimiter = '-', nameDelimiter = '_', excludePathChunks = ['packages'], } = {}) {
+    const topLevel = parent === root;
+    const exclude = new Set(excludePathChunks);
+    const pathChunks = splitPath(relCwd).filter((chunk) => !exclude.has(chunk));
+    if (pathChunks.at(-1) === base) {
+        pathChunks.pop();
+    }
+    const { scope, name: parentName } = parsePackageName(parent ?? '');
+    return serializePackageName({
+        scope,
+        name: [
+            ...(topLevel ? [] : [parentName]),
+            [...pathChunks, base].join(pathDelimiter),
+        ].join(nameDelimiter),
+    });
+}
 /**
  * Converts the provided value to a string representation suitable for debugging purposes.
  *
@@ -61,6 +98,19 @@ export function joinPath(...parts) {
         String(part)
         : `${acc.replace(/\/+$/, '')}/${String(part).replace(/^\/+/, '')}`, '');
 }
+/**
+ * Splits a given Unix-like path into an array of its components based on the "/" delimiter.
+ * Optionally keeps empty chunks in the result.
+ *
+ * @param path - The file path to be split into an array of components.
+ * @param keepEmptyChunks - A boolean indicating whether empty strings (resulting from consecutive delimiters)
+ * should be preserved in the output array. Defaults to `false`.
+ * @returns An array of strings representing the components of the path.
+ */
+export function splitPath(path, keepEmptyChunks = false) {
+    const splitted = path.split(/\/+/);
+    return keepEmptyChunks ? splitted : (splitted.filter((chunk) => chunk.length > 0));
+}
 export function camelCase(name) {
     return clampWS(name).replace(/[-_\s]+([^-_\s])/g, (_, suffix) => suffix.toUpperCase());
 }

package/dist/types.d.ts

@@ -2,18 +2,104 @@
  * The `FValue` type represents a union type that can be either a value of type `T` or a function
  * that takes a parameter of type `A` and returns a value of type `T`.
  *
- * @template A - The type of the parameter for the function.
- * @template T - The type of the value or the return type of the function.
+ * @typeParam A - The type of the parameter for the function.
+ * @typeParam T - The type of the value or the return type of the function.
  */
 export type FValue<A, T> = T | ((value: A) => T);
+/**
+ * A type representing a type guard function that determines if a given value of type `T`
+ * conforms to a more specific type `V`, where `V` is a subtype of `T`.
+ *
+ * This function should be implemented to return `true` if the provided value matches
+ * the more specific type `V`, and `false` otherwise. By using a type guard, TypeScript can
+ * narrow the type of variable within the scope of a condition.
+ *
+ * @typeParam T - The broader type against which the value will be checked.
+ * @typeParam V - The narrowed type that `T` is tested against. V must extend T.
+ * @param value - The value of type `T` to be tested against the narrowed type `V`.
+ * @returns A boolean value indicating whether the input value is of type `V`.
+ */
 export type TypeGuard<T, V extends T> = (value: T) => value is V;
-export type TestFn<T> = (value: T) => boolean;
-export type TestParam<ValueType = any, NarrowedType extends ValueType = ValueType> = TypeGuard<ValueType, NarrowedType> | TestFn<ValueType>;
-export type TestResultType<ValueType, TestType extends TestParam, BranchType extends boolean> = TestType extends TypeGuard<unknown, infer NarrowedType> ? BranchType extends true ? Extract<ValueType, NarrowedType> : Exclude<ValueType, NarrowedType> : TestType extends TestFn<infer OriginalType> ? OriginalType : never;
-export type OnTrueParam<ValueType, TestType extends TestParam, ReturnType> = FValue<TestResultType<ValueType, TestType, true>, ReturnType>;
-export type OnFalseParam<ValueType, TestType extends TestParam, ReturnType> = FValue<TestResultType<ValueType, TestType, false>, ReturnType>;
+/**
+ * A type definition for a function that performs a boolean test on a given value.
+ *
+ * This generic type accepts a parameter `T`, which represents the type of the input
+ * that the function will evaluate. The function returns a boolean indicating the
+ * result of the test.
+ *
+ * @typeParam T - The type of the input value that the function will evaluate.
+ * @param value - The input value to test.
+ * @returns A boolean indicating the result of the test.
+ */
+export type Predicate<T> = (value: T) => boolean;
+/**
+ * Represents a type that can either be a `TypeGuard` or a `TestFn`.
+ *
+ * `TestParam` is a utility type that allows defining parameters used in testing or
+ * type-checking procedures. It accommodates both type guard functions and test
+ * functions for more comprehensive type handling.
+ *
+ * @typeParam TValue - The base type to be tested or narrowed. Defaults to `any`.
+ * @typeParam TNarrowed - A subtype of `ValueType` that represents the narrowed type.
+ *                          Defaults to `ValueType`.
+ */
+export type TestFn<TValue = any, TNarrowed extends TValue = TValue> = Predicate<TValue> | TypeGuard<TValue, TNarrowed>;
+/**
+ * Represents a type that evaluates to a specific result based on the provided test conditions.
+ *
+ * @typeParam TValue - The type of value being tested.
+ * @typeParam TTestFn - The type of test being applied. This could be a type guard or a test function.
+ * @typeParam TBranch - A boolean that determines the branch type. If true, the resulting type will
+ * focus on the narrowed type; otherwise, it excludes the narrowed type.
+ *
+ * The type resolves based on the following rules:
+ * 1. If `TestType` is a type guard:
+ *    - If `BranchType` is `true`, the resulting type includes only the portion of `ValueType` that
+ *      conforms to the narrowed type.
+ *    - If `BranchType` is `false`, the resulting type excludes the portion of `ValueType` that
+ *      conforms to the narrowed type.
+ * 2. If `TestType` is a test function, the resulting type will be the original type inferred by
+ *    the test function.
+ * 3. If neither condition applies, the resulting type will be `never`.
+ */
+export type TestFnResult<TValue, TTestFn extends TestFn, TBranch extends boolean> = TTestFn extends TypeGuard<unknown, infer TNarrowed> ? TBranch extends true ? Extract<TValue, TNarrowed> : Exclude<TValue, TNarrowed> : TTestFn extends Predicate<infer TOriginal> ? TOriginal : never;
+/**
+ * A type definition that represents a resolved value when a certain test condition is true.
+ *
+ * @typeParam ValueType - Represents the type of the input value being tested.
+ * @typeParam TestType - Extends the `TestParam` type and defines the parameters for the test condition.
+ * @typeParam ReturnType - Specifies the type of the resulting value after the test condition is satisfied.
+ *
+ * This type combines the test result with a return type, capturing the transformed value
+ * or operation result when the test evaluates to `true`.
+ */
+export type FValueTrue<TValue, TTestFn extends TestFn, TResult> = FValue<TestFnResult<TValue, TTestFn, true>, TResult>;
+/**
+ * Represents a type that maps a test result to a specific return type when the test evaluates to false.
+ *
+ * This type is a utility that processes the result of a test operation (`TestResultType`)
+ * when the provided test condition evaluates as false, associating it with a specific return type (`ReturnType`).
+ *
+ * @typeParam ValueType - The type of the primary value being tested.
+ * @typeParam TestType - A type extending `TestParam` representing the condition being tested.
+ * @typeParam ReturnType - The type of the result or output when the test condition evaluates to false.
+ */
+export type FValueFalse<TValue, TTestFn extends TestFn, TResult> = FValue<TestFnResult<TValue, TTestFn, false>, TResult>;
+/**
+ * Represents a parsed Node.js (npm) package name split into its optional scope and the bare name.
+ */
 export interface ParsedPackageName {
+    /**
+     * The scope part of the package name (organization/user), with or without the leading "@" and trail "/".
+     * If the package is unscoped, this will be `null` or `undefined`.
+     *
+     * @example "scope" for "@scope/pkg", or "undefined" for "pkg"
+     */
     scope?: string | null;
+    /**
+     * The unscoped package name (the segment after the scope or the whole name if unscoped).
+     * For "@scope/pkg", this is "pkg"; for "pkg", this is "pkg".
+     */
     name: string;
 }
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@budsbox/lib-es",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "homepage": "https://gitlab.com/budsbox/fe/seed",
   "bugs": {
     "url": "https://gitlab.com/budsbox/fe/seed/-/issues"
@@ -124,18 +124,18 @@
     "prepack": "yarn p:ts:prepack"
   },
   "dependencies": {
-    "@budsbox/lib-types": "^1.0.0",
+    "@budsbox/lib-types": "^1.1.0",
+    "@types/node": "^22.15.2",
     "tslib": "^2.8.1",
     "type-fest": "^4.32.0"
   },
   "devDependencies": {
-    "@budsbox/eslint": "^1.0.3",
-    "@budsbox/eslint_presets-lib": "^1.0.2",
-    "@budsbox/eslint_presets-tools": "^1.0.2",
-    "@budsbox/tsconfigs": "^4.1.0",
+    "@budsbox/eslint": "^1.2.0",
+    "@budsbox/eslint_presets-lib": "^1.0.3",
+    "@budsbox/eslint_presets-tools": "^1.0.3",
+    "@budsbox/tsconfigs": "^4.3.0",
     "@eslint/js": "^9.26.0",
     "@types/eslint": "^9.6.1",
-    "@types/node": "^22.15.2",
     "@typescript-eslint/parser": "^8.32.1",
     "eslint": "^9.26.0",
     "eslint-config-prettier": "^10.1.5",