@budsbox/lib-es 1.0.0

package/README.md

@@ -0,0 +1 @@
+# @budsbox/lib-es

package/dist/array.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+export declare function ensureArray<T>(value: T | readonly T[]): readonly T[];
+export declare function ensureArray<T>(value: T | T[]): T[];
+/**
+ * Removes duplicate elements from the provided array while preserving the order of the first occurrence of each element.
+ *
+ * @param items - The array of items from which duplicates should be removed.
+ *                The array is expected to be read-only and can contain elements of any type.
+ * @returns A new array containing only the unique elements from the input array, in the order of their first occurrence.
+ */
+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.
+ */
+export declare function union<T>(...arrays: ReadonlyArray<T | readonly T[]>): T[];
+/**
+ * Computes the intersection of multiple arrays, returning an array that contains
+ * all elements that are present in every input array.
+ *
+ * @param arrays - A variadic parameter allowing multiple arrays or single elements.
+ * 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[];
+/**
+ * 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.
+ */
+export declare function diff<T>(source: readonly T[], ...excludes: ReadonlyArray<readonly T[]>): T[];
+//# sourceMappingURL=array.d.ts.map

package/dist/array.js

@@ -0,0 +1,54 @@
+export function ensureArray(value) {
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Removes duplicate elements from the provided array while preserving the order of the first occurrence of each element.
+ *
+ * @param items - The array of items from which duplicates should be removed.
+ *                The array is expected to be read-only and can contain elements of any type.
+ * @returns A new array containing only the unique elements from the input array, in the order of their first occurrence.
+ */
+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.
+ */
+export function union(...arrays) {
+    return dedupe(arrays.flatMap((v) => v));
+}
+/**
+ * Computes the intersection of multiple arrays, returning an array that contains
+ * all elements that are present in every input array.
+ *
+ * @param arrays - A variadic parameter allowing multiple arrays or single elements.
+ * Each array or element will be checked for intersection.
+ * @returns An array containing elements that are present in all input arrays.
+ */
+export function intersection(...arrays) {
+    const { length } = arrays;
+    const counters = new Map();
+    for (const array of arrays) {
+        for (const item of ensureArray(array)) {
+            const count = counters.get(item) ?? 0;
+            counters.set(item, count + 1);
+        }
+    }
+    return [...counters]
+        .filter(([, count]) => count === length)
+        .map(([item]) => item);
+}
+/**
+ * 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.
+ */
+export function diff(source, ...excludes) {
+    const set = new Set(excludes.flatMap((v) => v));
+    return source.filter((v) => !set.has(v));
+}
+//# sourceMappingURL=array.js.map

package/dist/guards.d.ts

@@ -0,0 +1,145 @@
+import type { Def, Nil, NonNil, Undef } from '@budsbox/lib-types';
+/**
+ * Checks if the provided value is `undefined`.
+ *
+ * @param value - The value to check for `undefined`.
+ * @return `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.
+ */
+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`.
+ */
+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.
+ */
+export declare function isNotNil<T>(value: T): value is NonNil<T>;
+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.
+ */
+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`.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function isObject(value: unknown): value is object;
+/**
+ * Checks if the provided value is a record.
+ *
+ * A record is considered an object where the keys are property keys,
+ * and the values can be any type. The function also checks whether
+ * empty records are allowed based on the specified flag.
+ *
+ * @param value - The value to check.
+ * @param allowEmpty - Determines whether empty records are allowed.
+ * @return 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.
+ * @param value - The value to check.
+ * @return 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.
+ * @param value - The value to be checked.
+ * @return 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.
+ */
+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.
+ */
+export declare function isFunction(value: unknown): value is CallableFunction;
+/**
+ * Determines if the provided value is a string.
+ *
+ * @param value - The value to check.
+ * @return 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.
+ */
+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.
+ */
+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.
+ *
+ * @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.
+ */
+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;
+};
+//# sourceMappingURL=guards.d.ts.map

package/dist/guards.js

@@ -0,0 +1,135 @@
+/**
+ * Checks if the provided value is `undefined`.
+ *
+ * @param value - The value to check for `undefined`.
+ * @return `true` if the value is `undefined`, otherwise `false`.
+ */
+export function isUndef(value) {
+    return value === undefined;
+}
+/**
+ * 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.
+ */
+export function isDef(value) {
+    return value !== undefined;
+}
+/**
+ * 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`.
+ */
+export function isNil(value) {
+    return value == null;
+}
+export function isNotNil(value) {
+    return !isNil(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.
+ */
+export function isTrue(value) {
+    return value === 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`.
+ */
+export function isFalse(value) {
+    return value === 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.
+ */
+export function isTruly(value) {
+    return Boolean(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.
+ */
+export function isFalsy(value) {
+    return !isTruly(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.
+ */
+export function isObject(value) {
+    return value != null && typeof value === 'object';
+}
+/**
+ * Checks if the provided value is a record.
+ *
+ * A record is considered an object where the keys are property keys,
+ * and the values can be any type. The function also checks whether
+ * empty records are allowed based on the specified flag.
+ *
+ * @param value - The value to check.
+ * @param allowEmpty - Determines whether empty records are allowed.
+ * @return A boolean indicating whether the value is a record.
+ */
+export function isRecord(value, allowEmpty = false) {
+    return isObject(value) && (allowEmpty || Object.keys(value).length > 0);
+}
+export function isArray(value) {
+    return Array.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.
+ */
+export function isFunction(value) {
+    return typeof value === 'function';
+}
+/**
+ * Determines if the provided value is a string.
+ *
+ * @param value - The value to check.
+ * @return True if the value is a string, otherwise false.
+ */
+export function isString(value) {
+    return typeof value === '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.
+ */
+export function isNumber(value) {
+    return typeof value === 'number' && !Number.isNaN(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.
+ */
+export function isBoolean(value) {
+    return typeof value === 'boolean';
+}
+export function hasProp(source, prop, test) {
+    return (isNotNil(source) &&
+        Object.hasOwn(source, prop) &&
+        (!isFunction(test) || test(source[prop])));
+}
+//# sourceMappingURL=guards.js.map

package/dist/logical.d.ts

@@ -0,0 +1,51 @@
+import type { OnFalseParam, OnTrueParam, TestParam } 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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
+ * // result1 is 'Greater'
+ *
+ * const result2 = fif(3, (n) => n > 5, (n) => `Above ${n}`, (n) => `Below ${n}`);
+ * // 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;
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function fifs<TrueType, FalseType = undefined>(condition: boolean, onTrue: OnTrueParam<boolean, typeof isTrue, TrueType>, onFalse?: OnFalseParam<boolean, typeof isTrue, FalseType>): TrueType | FalseType;
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function sure<ValueType, TrueType, FalseType = undefined>(value: ValueType, onTrue: OnTrueParam<ValueType, typeof isNotNil, TrueType>, onFalse?: OnFalseParam<ValueType, typeof isNotNil, FalseType>): TrueType | FalseType;
+//# sourceMappingURL=logical.d.ts.map

package/dist/logical.js

@@ -0,0 +1,64 @@
+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.
+ *
+ * @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
+ *
+ * @example
+ * ```ts
+ * const result1 = fif(10, (n) => n > 5, 'Greater', 'Smaller');
+ * // result1 is 'Greater'
+ *
+ * const result2 = fif(3, (n) => n > 5, (n) => `Above ${n}`, (n) => `Below ${n}`);
+ * // result2 is 'Below 3'
+ * ```
+ */
+export function fif(value, test, onTrue, onFalse) {
+    if (test(value)) {
+        return isFunction(onTrue) ?
+            onTrue(value)
+            : onTrue;
+    }
+    if (isFunction(onFalse)) {
+        return onFalse(value);
+    }
+    return onFalse;
+}
+/**
+ * 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.
+ *
+ * @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.
+ */
+export function fifs(condition, onTrue, onFalse) {
+    return fif(condition, isTrue, onTrue, onFalse);
+}
+/**
+ * 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.
+ *
+ * @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.
+ */
+export function sure(value, onTrue, onFalse) {
+    return fif(value, isNotNil, onTrue, onFalse);
+}
+//# sourceMappingURL=logical.js.map

package/dist/object.d.ts

@@ -0,0 +1,21 @@
+import type { ConditionalExcept } from 'type-fest';
+import type { OmitNilProps, Value } from '@budsbox/lib-types/object';
+export declare function pick<T extends object, Keys extends PropertyKey = keyof T>(source: T, ...keys: readonly Keys[]): Pick<T, Keys & keyof T>;
+export declare const pickStrict: <T extends object, Keys extends keyof T = keyof T>(source: T, ...keys: readonly Keys[]) => Pick<T, Keys>;
+export declare function omit<T extends object, K extends PropertyKey>(source: T, ...keys: readonly K[]): Omit<T, K>;
+export declare const omitStrict: <TSource extends object, TKey extends keyof TSource>(source: TSource, ...keys: readonly TKey[]) => Omit<TSource, TKey>;
+export declare function filterBy<T, K extends string, R extends T>(value: Partial<Record<K, T>>, test: (value: T) => value is R): ConditionalExcept<Record<K, T>, R>;
+export declare function filterBy<T, K extends string, R extends T>(value: Partial<Record<K, T>> | Record<K, T>, test: (value: T) => value is R): ConditionalExcept<Record<K, T>, R>;
+export declare function filterBy<V extends object>(obj: V, filter: (value: V[keyof V], key: keyof V, obj: V) => boolean): Partial<V>;
+export declare function omitNils<T extends object>(object: T): OmitNilProps<T>;
+export declare function reduce<U>(obj: Readonly<Record<string, unknown>>, callback: (previousValue: U, currentValue: Value<typeof obj>, currentKey: keyof typeof obj, object: typeof obj) => U, initialValue: Partial<U>): U;
+/**
+ * Returns the first key of the given object.
+ * Useful when working with objects that have only one key.
+ *
+ * @param value
+ */
+export declare function getKey<T extends string>(value: Record<T, unknown>): T;
+export declare function getKey<T extends string>(value: Partial<Record<T, unknown>>): T | undefined;
+export declare function getKey<T extends object>(value: T): keyof T;
+//# sourceMappingURL=object.d.ts.map

package/dist/object.js

@@ -0,0 +1,47 @@
+import { isNotNil } from '#guards';
+export function pick(source, ...keys) {
+    return keys.reduce((acc, key) => Object.hasOwn(source, key) ? { ...acc, [key]: source[key] } : acc, {});
+}
+export const pickStrict = pick;
+export function omit(source, ...keys) {
+    const keySet = new Set(keys);
+    return Object.fromEntries(Object.entries(source).filter(([key]) => !keySet.has(key)));
+}
+export const omitStrict = omit;
+export function filterBy(obj, filter) {
+    const newObj = {};
+    for (const key in obj) {
+        if (!Object.hasOwn(obj, key)) {
+            break;
+        }
+        const value = obj[key];
+        if (filter(value, key, obj)) {
+            newObj[key] = value;
+        }
+    }
+    return newObj;
+}
+export function omitNils(object) {
+    return filterBy(object, isNotNil);
+}
+export function reduce(obj, callback, initialValue) {
+    return Object.entries(obj).reduce((acc, [key, value]) => callback(acc, value, key, obj), initialValue);
+}
+export function getKey(value) {
+    for (const key in value) {
+        if (Object.hasOwn(value, key)) {
+            return key;
+        }
+        else {
+            /*
+             Modern JS interpreters in the for..in loop
+              first traverse the object's own properties,
+              and then the inherited ones. Therefore, you can end the loop
+              if the own property has never been encountered
+             */
+            break;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=object.js.map

package/dist/string.d.ts

@@ -0,0 +1,88 @@
+import type { CamelCase, DelimiterCase, KebabCase, PascalCase, SnakeCase } from 'type-fest';
+import type { Nil } from '@budsbox/lib-types';
+import type { ParsedPackageName } from './types.js';
+export type { ParsedPackageName };
+/**
+ * Parses a package name string to extract its scope and name.
+ *
+ * @param packageName - The full name of the package, potentially including a scope.
+ * @param clean - A flag indicating whether to return a cleaned version (i.e., without a leading `@` and trailing `/`) of the scope. Defaults to false.
+ * @return An object containing the parsed scope and name of the package. The scope will be `null` if no scope is present.
+ */
+export declare function parsePackageName(packageName: string, clean?: boolean): Required<ParsedPackageName>;
+/**
+ * Converts a ParsedPackageName object into its string representation.
+ *
+ * @param parsedPackageName - An object representing the parsed package name with fields such as `scope` and `name`.
+ * @returns The string representation of the package name, including the scope if it exists.
+ */
+export declare function stringifyPackageName(parsedPackageName: Readonly<ParsedPackageName>): string;
+/**
+ * Converts a parsed package name object or a Nil value into a string representation.
+ *
+ * @param parsedPackageName - A parsed package name object of type `ParsedPackageName` or a Nil value.
+ * @param allowNil - A boolean flag specifying whether Nil values are allowed for conversion.
+ * @return 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 stringifyPackageName(parsedPackageName: Readonly<ParsedPackageName> | Nil, allowNil: true): string;
+/**
+ * Returns the string representation of the given value.
+ * Useful for debugging purposes.
+ *
+ * @param value
+ */
+export declare function debugString(value: unknown): string;
+/**
+ * Trims leading and trailing whitespace from the input string and collapses
+ * multiple consecutive whitespace characters into a single space.
+ *
+ * @param str - The input string to be processed.
+ * @returns The processed string with trimmed and normalized whitespace.
+ */
+export declare function clampWS(str: string): string;
+/**
+ * Joins multiple parts of a path into a single string.
+ * It ensures that there are no duplicate slashes between the parts
+ * and trims leading/trailing slashes where necessary.
+ *
+ * @param parts - An array of path parts to join. Each part can be a string, number, boolean, null, or undefined. Non-string values will be stringified, and null/undefined values are ignored.
+ * @returns The combined path as a single string, with proper slash formatting.
+ */
+export declare function joinPath(...parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+/**
+ * Transforms a given string into camelCase format.
+ *
+ * @param str - The string to be converted to camelCase.
+ * @returns The input string transformed into camelCase.
+ */
+export declare function camelCase<T extends string>(str: T): CamelCase<T>;
+/**
+ * Converts a given string to PascalCase format.
+ *
+ * @param str - The string to be transformed into PascalCase.
+ * @returns The transformed string in PascalCase format.
+ */
+export declare function pascalCase<T extends string>(str: T): PascalCase<T>;
+/**
+ * Converts a given string to a delimited case using the specified delimiter.
+ *
+ * @param name - The input string that will be converted to the delimited case.
+ * @param delimiter - The character or string to use as a delimiter in the transformed output.
+ * @returns The input string transformed into the delimited case format using the given delimiter.
+ */
+export declare function delimCase<T extends string, D extends string>(name: T, delimiter: D): DelimiterCase<T, D>;
+/**
+ * Converts a given string to kebab-case format.
+ *
+ * @param name - The string input to be converted to kebab-case. The input should be a string type.
+ * @returns The transformed string in kebab-case format.
+ */
+export declare function kebabCase<T extends string>(name: T): KebabCase<T>;
+/**
+ * Converts a given string to snake_case format.
+ *
+ * @param name - The string to be converted to snake_case.
+ * @returns The converted string in snake_case format.
+ */
+export declare function snakeCase<T extends string>(name: T): SnakeCase<T>;
+//# sourceMappingURL=string.d.ts.map

package/dist/string.js

@@ -0,0 +1,82 @@
+import { isNil, isNotNil, isString } from '#guards';
+/**
+ * Parses a package name string to extract its scope and name.
+ *
+ * @param packageName - The full name of the package, potentially including a scope.
+ * @param clean - A flag indicating whether to return a cleaned version (i.e., without a leading `@` and trailing `/`) of the scope. Defaults to false.
+ * @return An object containing the parsed scope and name of the package. The scope will be `null` if no scope is present.
+ */
+export function parsePackageName(packageName, clean = false) {
+    const [scope, cleanScope] = /^@([^/]+)\//.exec(packageName) ?? [null, null];
+    return {
+        scope: clean ? cleanScope : scope,
+        name: packageName.replace(scope ?? '', ''),
+    };
+}
+export function stringifyPackageName(parsedPackageName, allowNil = false) {
+    if (!allowNil && isNil(parsedPackageName)) {
+        throw new TypeError('Expected a non-nil value');
+    }
+    const { scope, name } = parsedPackageName ?? { scope: null, name: '' };
+    return isString(scope) ?
+        [scope.replace(/^@?([^]+)\/?$/, '@$1'), name].join('/')
+        : name;
+}
+/**
+ * Returns the string representation of the given value.
+ * Useful for debugging purposes.
+ *
+ * @param value
+ */
+export function debugString(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * Trims leading and trailing whitespace from the input string and collapses
+ * multiple consecutive whitespace characters into a single space.
+ *
+ * @param str - The input string to be processed.
+ * @returns The processed string with trimmed and normalized whitespace.
+ */
+export function clampWS(str) {
+    return str.trim().replace(/\s+/g, ' ');
+}
+/**
+ * Joins multiple parts of a path into a single string.
+ * It ensures that there are no duplicate slashes between the parts
+ * and trims leading/trailing slashes where necessary.
+ *
+ * @param parts - An array of path parts to join. Each part can be a string, number, boolean, null, or undefined. Non-string values will be stringified, and null/undefined values are ignored.
+ * @returns The combined path as a single string, with proper slash formatting.
+ */
+export function joinPath(...parts) {
+    return parts
+        .filter(isNotNil)
+        .reduce((acc, part) => acc.length === 0 ?
+        String(part)
+        : `${acc.replace(/\/+$/, '')}/${String(part).replace(/^\/+/, '')}`, '');
+}
+export function camelCase(name) {
+    return clampWS(name).replace(/[-_\s]+([^-_\s])/g, (_, suffix) => suffix.toUpperCase());
+}
+export function pascalCase(name) {
+    return camelCase(name).replace(/^./, (c) => c.toUpperCase());
+}
+export function delimCase(name, delimiter = '-') {
+    return clampWS(name)
+        .replace(/(.)([A-Z])/g, `$1${delimiter}$2`)
+        .replace(/[-_\s]+/g, delimiter)
+        .toLowerCase();
+}
+export function kebabCase(name) {
+    return delimCase(name, '-');
+}
+export function snakeCase(name) {
+    return delimCase(name, '_');
+}
+//# sourceMappingURL=string.js.map

package/dist/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+export type FValue<A, T> = T | ((value: A) => T);
+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>;
+export interface ParsedPackageName {
+    scope?: string | null;
+    name: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

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

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@budsbox/lib-es",
+  "version": "1.0.0",
+  "homepage": "https://gitlab.com/budsbox/fe/seed",
+  "bugs": {
+    "url": "https://gitlab.com/budsbox/fe/seed/-/issues"
+  },
+  "repository": "gitlab:budsbox/fe/seed",
+  "license": "MIT",
+  "author": "Konstantin Kutsyllo <trikadin@pm.me>",
+  "type": "module",
+  "imports": {
+    "#package.json": "./package.json",
+    "#array": {
+      "import": {
+        "default": "./dist/array.js",
+        "types": "./dist/array.d.ts"
+      }
+    },
+    "#object": {
+      "import": {
+        "default": "./dist/object.js",
+        "types": "./dist/object.d.ts"
+      }
+    },
+    "#string": {
+      "import": {
+        "default": "./dist/string.js",
+        "types": "./dist/string.d.ts"
+      }
+    },
+    "#guards": {
+      "import": {
+        "default": "./dist/guards.js",
+        "types": "./dist/guards.d.ts"
+      }
+    },
+    "#logical": {
+      "import": {
+        "default": "./dist/logical.js",
+        "types": "./dist/logical.d.ts"
+      }
+    }
+  },
+  "exports": {
+    "./array": {
+      "import": {
+        "default": "./dist/array.js",
+        "types": "./dist/array.d.ts"
+      }
+    },
+    "./object": {
+      "import": {
+        "default": "./dist/object.js",
+        "types": "./dist/object.d.ts"
+      }
+    },
+    "./string": {
+      "import": {
+        "default": "./dist/string.js",
+        "types": "./dist/string.d.ts"
+      }
+    },
+    "./guards": {
+      "import": {
+        "default": "./dist/guards.js",
+        "types": "./dist/guards.d.ts"
+      }
+    },
+    "./logical": {
+      "import": {
+        "default": "./dist/logical.js",
+        "types": "./dist/logical.d.ts"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.js"
+  ],
+  "scripts": {
+    "name": "echo $npm_package_name",
+    "prepack": "yarn p:ts:prepack"
+  },
+  "dependencies": {
+    "@budsbox/lib-types": "^1.0.0",
+    "tslib": "^2.8.1",
+    "type-fest": "^4.32.0"
+  },
+  "devDependencies": {
+    "@budsbox/eslint": "^1.0.0",
+    "@budsbox/eslint_presets-lib": "^1.0.0",
+    "@budsbox/eslint_presets-tools": "^1.0.0",
+    "@budsbox/tsconfigs": "^4.0.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",
+    "eslint-import-resolver-typescript": "^4.3.4",
+    "eslint-plugin-import-x": "^4.11.1",
+    "eslint-plugin-jsdoc": "^50.6.17",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-refresh": "^0.4.20",
+    "globals": "^16.1.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.32.1"
+  },
+  "packageManager": "yarn@4.9.2"
+}