@budsbox/lib-es 2.2.0 → 3.0.0

package/dist/object.js

@@ -1,47 +1,86 @@
+/**
+ * Object utility functions for selecting, omitting, filtering, reducing, and
+ * strongly-typing common object operations.
+ *
+ * @module
+ * @importTarget ./object
+ */
 import { isNotNil } from '#guards';
 export function pick(source, ...keys) {
     return keys.reduce((acc, key) => Object.hasOwn(source, key) ? { ...acc, [key]: source[key] } : acc, {});
 }
+/**
+ * A strict version of {@link pick} that restricts keys to those present in `TSource`.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to pick.
+ * @returns A new object with the picked properties.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam Keys - The type of the keys to pick, restricted to keys of `TSource`.
+ */
 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)));
 }
+/**
+ * A strict version of {@link omit} that restricts keys to those present in `TSource`.
+ *
+ * @param source - The source object.
+ * @param keys - The property keys to omit.
+ * @returns A new object without the omitted properties.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TKey - The type of the keys to omit, restricted to keys of `TSource`.
+ */
 export const omitStrict = omit;
-export function filterBy(obj, filter) {
+export function filter(obj, test) {
     const newObj = {};
     for (const key in obj) {
         if (!Object.hasOwn(obj, key)) {
             break;
         }
         const value = obj[key];
-        if (filter(value, key, obj)) {
+        if (test(value, key, obj)) {
             newObj[key] = value;
         }
     }
     return newObj;
 }
+/**
+ * Returns a new object with all `null` or `undefined` properties removed using {@link filter} and {@link isNotNil}.
+ *
+ * @param object - The object to strip of nils.
+ * @returns A new object without nil properties.
+ * @typeParam T - The type of the source object.
+ */
 export function omitNils(object) {
-    return filterBy(object, isNotNil);
+    return filter(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;
+/**
+ * Transforms the values of an object using the provided callback function.
+ *
+ * @param object - The source object whose values are to be transformed.
+ * @param callback - A function that is called for each key-value pair in the source object.
+ * It receives the value, key, and the original object as arguments and returns the transformed value.
+ * @returns A new object with the same keys as the source object but with values transformed by the callback function.
+ * @typeParam TSource - The type of the source object.
+ * @typeParam TValue - The type of the transformed values in the resulting object.
+ */
+export const map = (object, callback) => {
+    return reduce(object, (acc, value, key, obj) => {
+        acc[key] = callback(value, key, obj);
+        return acc;
+    }, {});
+};
+export function reduce(source, callback, initialValue) {
+    return Object.entries(source).reduce((acc, [key, value]) => callback(acc, value, key, source), initialValue);
 }
+/**
+ * Returns an array of a given object's own enumerable string-keyed property [key, value] pairs, typed as {@link EntryUnion}.
+ *
+ * @param source - The object whose entries are to be returned.
+ * @returns An array of entry tuples.
+ * @typeParam T - The type of the source object.
+ */
+export const entries = (source) => Object.entries(source);
 //# sourceMappingURL=object.js.map

package/dist/set.d.ts

@@ -0,0 +1,70 @@
+/**
+ * This module provides set utility functions for common operations like union, intersection, difference, etc.
+ *
+ * @module
+ * @importTarget ./set
+ */
+import type { IterableElement } from 'type-fest';
+import type { AnyReadableSet, AnySet, ArrayItemsIntersection, Nil } from '@budsbox/lib-types';
+/**
+ * Computes the union of multiple sets and returns a new set containing all unique elements.
+ *
+ * @param sets - A collection of sets to be unified.
+ * @returns A new set containing all unique elements present in any of the input sets.
+ * @typeParam TSets - An array of sets whose elements extend the type `UnknownSet`.
+ */
+export declare const union: <TSets extends readonly AnyReadableSet[]>(...sets: TSets) => Set<IterableElement<IterableElement<TSets>>>;
+/**
+ * Computes the intersection of multiple sets, returning a new set containing only the elements
+ * that are present in all the provided sets.
+ *
+ * @param sets - A variable number of sets to compute the intersection from.
+ * @returns A new set containing the elements that are common to all provided sets.
+ * @typeParam TSets - A tuple of sets, where each set contains elements of any type.
+ * The resulting set contains elements that are a union of all possible intersections
+ * of the provided sets' elements.
+ */
+export declare const intersection: <TSets extends readonly AnyReadableSet[]>(...sets: TSets) => Set<ArrayItemsIntersection<ItemsOfSetsArray<TSets>>>;
+/**
+ * A read-only implementation of the `Set` interface. This class allows for creating immutable sets,
+ * providing the same methods as a standard `Set`, but without mutation capabilities.
+ *
+ * @typeParam T - The type of elements stored in the set.
+ */
+export declare class ROSet<T> extends Set<T> implements ReadonlySet<T> {
+    /**
+     * Constructs a new instance of the class.
+     *
+     * @param input - An iterable object that contains elements of type `T` to initialize the set,
+     * or `Nil` to create an empty set.
+     * @typeParam T - The type of the elements in the set.
+     */
+    constructor(input?: Iterable<T> | Nil);
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @param value - The value to add to set.
+     * @returns This method does not return a value.
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    add(value: T): never;
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @param value - The value to remove from set.
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    delete(value: T): never;
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    clear(): never;
+}
+type ItemsOfSetsArray<TSets extends readonly AnyReadableSet[]> = TSets extends readonly [infer TSet, ...infer TRest] ? [
+    TSet extends Set<infer T> ? T : never,
+    ...(TRest extends readonly AnySet[] ? ItemsOfSetsArray<TRest> : [])
+] : TSets extends readonly [] ? [] : TSets extends ReadonlyArray<Set<infer T>> ? T[] : never;
+export {};
+//# sourceMappingURL=set.d.ts.map

package/dist/set.js

@@ -0,0 +1,116 @@
+/**
+ * This module provides set utility functions for common operations like union, intersection, difference, etc.
+ *
+ * @module
+ * @importTarget ./set
+ */
+/**
+ * Computes the union of multiple sets and returns a new set containing all unique elements.
+ *
+ * @param sets - A collection of sets to be unified.
+ * @returns A new set containing all unique elements present in any of the input sets.
+ * @typeParam TSets - An array of sets whose elements extend the type `UnknownSet`.
+ */
+export const union = (...sets) => {
+    const unionSet = new Set();
+    for (const set of sets) {
+        for (const element of set) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            unionSet.add(element);
+        }
+    }
+    return unionSet;
+};
+/**
+ * Computes the intersection of multiple sets, returning a new set containing only the elements
+ * that are present in all the provided sets.
+ *
+ * @param sets - A variable number of sets to compute the intersection from.
+ * @returns A new set containing the elements that are common to all provided sets.
+ * @typeParam TSets - A tuple of sets, where each set contains elements of any type.
+ * The resulting set contains elements that are a union of all possible intersections
+ * of the provided sets' elements.
+ */
+export const intersection = (...sets) => {
+    const { length } = sets;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const counters = new Map();
+    for (const set of sets) {
+        for (const element of set) {
+            const count = counters.get(element) ?? 0;
+            counters.set(element, count + 1);
+        }
+    }
+    const intersectionSet = new Set();
+    for (const [element, count] of counters) {
+        if (count === length) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            intersectionSet.add(element);
+        }
+    }
+    return intersectionSet;
+};
+/**
+ * A read-only implementation of the `Set` interface. This class allows for creating immutable sets,
+ * providing the same methods as a standard `Set`, but without mutation capabilities.
+ *
+ * @typeParam T - The type of elements stored in the set.
+ */
+export class ROSet extends Set {
+    /**
+     * Constructs a new instance of the class.
+     *
+     * @param input - An iterable object that contains elements of type `T` to initialize the set,
+     * or `Nil` to create an empty set.
+     * @typeParam T - The type of the elements in the set.
+     */
+    constructor(input) {
+        super(input);
+        createdSets.add(this);
+    }
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @param value - The value to add to set.
+     * @returns This method does not return a value.
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    add(value) {
+        if (createdSets.has(this)) {
+            throw new TypeError(`Cannot add value ${String(value)}: set is read-only`);
+        }
+        return super.add(value);
+    }
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @param value - The value to remove from set.
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    delete(value) {
+        throw new TypeError(`Cannot delete value ${String(value)}: set is read-only`);
+    }
+    /**
+     * Throws a `TypeError` exception because set is read-only.
+     *
+     * @throws {@link !TypeError} Indeed: set is read-only.
+     */
+    clear() {
+        throw new TypeError('Cannot clear set: set is read-only');
+    }
+}
+const createdSets = new WeakSet();
+/*
+ * It seems a bit hacky, but I plan to use it as an actual implementation for the `ReadonlySet` type,
+ * so I guess it's reasonable.
+ */
+[
+    [ROSet, 'name'],
+    [ROSet.prototype, Symbol.toStringTag],
+].forEach(([obj, prop]) => {
+    Object.defineProperty(obj, prop, {
+        value: 'ReadonlySet',
+        configurable: true,
+    });
+});
+//# sourceMappingURL=set.js.map

package/dist/string.d.ts

@@ -1,13 +1,27 @@
+/**
+ * This module provides string utility functions for common operations like case conversion, trimming, splitting, etc.
+ *
+ * @module
+ * @importTarget ./string
+ * @showCategories
+ * @categoryDescription Package Name
+ * This category contains functions for manipulating and formatting names of packages.
+ * @categoryDescription Casing
+ * This category contains functions for converting strings to different casing formats.
+ * @categoryDescription Paths
+ * This category contains functions for manipulating and formatting paths.
+ */
 import type { CamelCase, DelimiterCase, KebabCase, PascalCase, SnakeCase } from 'type-fest';
-import type { Maybe, Nil, Undef } from '@budsbox/lib-types';
-import type { ParsedPackageName } from './types.js';
-export type { ParsedPackageName };
+import type { Nil, Undef } from '@budsbox/lib-types';
+import type { PackageNameFormatOptions, ParsedPackageName } from './types.js';
+export type { PackageNameFormatOptions, 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.
  * @returns An object containing the parsed scope and name of the package. The scope will be `null` if no scope is present.
+ * @category Package Name
  */
 export declare function parsePackageName(packageName: string, clean?: boolean): Required<ParsedPackageName>;
 /**
@@ -15,6 +29,7 @@ export declare function parsePackageName(packageName: string, clean?: boolean):
  *
  * @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.
+ * @category Package Name
  */
 export declare function serializePackageName(parsedPackageName: Readonly<ParsedPackageName>): string;
 /**
@@ -23,8 +38,9 @@ export declare function serializePackageName(parsedPackageName: Readonly<ParsedP
  * @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.
  * @returns The string representation of the package name if valid, or an empty string if `allowNil` is true and the input is Nil.
+ * @category Package Name
  */
-export declare function serializePackageName(parsedPackageName: Readonly<ParsedPackageName> | Nil, allowNil: true): string;
+export declare function serializePackageName(parsedPackageName: Nil | Readonly<ParsedPackageName>, 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.
@@ -35,40 +51,13 @@ export declare function serializePackageName(parsedPackageName: Readonly<ParsedP
  *                  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.
+ * @typeParam TParsed - Controls the return type: when `true`, returns `ParsedPackageName`; when `false` (default), returns `string`.
+ * @category Package Name
  */
 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.
  *
@@ -81,14 +70,16 @@ export interface PackageNameFormatOptions {
  * @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.
+ * @category Package Name
  */
-export declare function formatPackageName(base: string, { root, parent, relCwd, pathDelimiter, nameDelimiter, excludePathChunks, }?: Readonly<PackageNameFormatOptions>): string;
+export declare function formatPackageName(base: string, options?: Readonly<PackageNameFormatOptions>): string;
 /**
  * Converts the provided value to a string representation suitable for debugging purposes.
  *
  * @param value - The value to be converted to its string representation. Can be of any type.
  * @returns A string representation of the input value.
  * If the value cannot be serialized using JSON.stringify, it falls back to using String conversion.
+ * @deprecated Use `formatDebugValue` from `@budsbox/lib-es/guards` instead.
  */
 export declare function debugString(value: unknown): string;
 /**
@@ -107,8 +98,9 @@ export declare function clampWS(str: string): string;
  * @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 serialized, and null/undefined values are ignored.
  * @returns The combined path as a single string, with proper slash formatting.
+ * @category Paths
  */
-export declare function joinPath(...parts: ReadonlyArray<string | number | boolean | null | undefined>): string;
+export declare function joinPath(...parts: ReadonlyArray<boolean | number | string | 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.
@@ -117,6 +109,7 @@ export declare function joinPath(...parts: ReadonlyArray<string | number | boole
  * @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.
+ * @category Paths
  */
 export declare function splitPath(path: string, keepEmptyChunks?: boolean): string[];
 /**
@@ -124,6 +117,8 @@ export declare function splitPath(path: string, keepEmptyChunks?: boolean): stri
  *
  * @param str - The string to be converted to camelCase.
  * @returns The input string transformed into camelCase.
+ * @typeParam T - The input string type; used to derive the resulting `CamelCase<T>` type.
+ * @category Casing
  */
 export declare function camelCase<T extends string>(str: T): CamelCase<T>;
 /**
@@ -131,6 +126,8 @@ export declare function camelCase<T extends string>(str: T): CamelCase<T>;
  *
  * @param str - The string to be transformed into PascalCase.
  * @returns The transformed string in PascalCase format.
+ * @typeParam T - The input string type; used to derive the resulting `PascalCase<T>` type.
+ * @category Casing
  */
 export declare function pascalCase<T extends string>(str: T): PascalCase<T>;
 /**
@@ -139,6 +136,9 @@ export declare function pascalCase<T extends string>(str: T): PascalCase<T>;
  * @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.
+ * @typeParam T - The input string type; used to derive the resulting `DelimiterCase<T, D>` type.
+ * @typeParam D - The delimiter string type used to separate words in the result.
+ * @category Casing
  */
 export declare function delimCase<T extends string, D extends string>(name: T, delimiter: D): DelimiterCase<T, D>;
 /**
@@ -146,6 +146,8 @@ export declare function delimCase<T extends string, D extends string>(name: T, d
  *
  * @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.
+ * @typeParam T - The input string type; used to derive the resulting `KebabCase<T>` type.
+ * @category Casing
  */
 export declare function kebabCase<T extends string>(name: T): KebabCase<T>;
 /**
@@ -153,6 +155,30 @@ export declare function kebabCase<T extends string>(name: T): KebabCase<T>;
  *
  * @param name - The string to be converted to snake_case.
  * @returns The converted string in snake_case format.
+ * @typeParam T - The input string type; used to derive the resulting `SnakeCase<T>` type.
+ * @category Casing
  */
 export declare function snakeCase<T extends string>(name: T): SnakeCase<T>;
+/**
+ * Joins an array of strings into a single formatted string using the specified conjunction.
+ *
+ * @param items - An array of strings to be joined. If the array is empty, an empty string is returned.
+ * @param conjunction - A word or phrase (`and` or `or`) to be used as the conjunction between the last two items.
+ * @returns A formatted string where the items are separated by commas and the conjunction is added before the final item.
+ */
+export declare function joinWithConjunction(items: readonly string[], conjunction: string): string;
+/**
+ * Constructs a dot-notation or bracket-notation string representation
+ * for accessing nested properties of an object based on the provided keys.
+ *
+ * @internal
+ * @param sourceName - The base name of the object or source from which properties are being accessed.
+ * @param keys - A variadic list of property keys representing the nested path.
+ * Each key will be used to generate the accessor string.
+ * @returns A string representing the accessor path in dot-notation for valid identifiers
+ * or bracket-notation for non-identifier keys.
+ * @remarks This function considers "valid" for identifiers only alphanumeric characters,
+ * underscores, and dollar signs.
+ */
+export declare function formatPropAccessor(sourceName: string, ...keys: readonly PropertyKey[]): string;
 //# sourceMappingURL=string.d.ts.map