@seedcord/utils 0.3.8 → 0.4.0-next.0

package/dist/index.d.mts

@@ -0,0 +1,759 @@
+import { ILogger } from "@seedcord/types";
+import * as fs from "node:fs";
+
+//#region src/misc/assertNever.d.ts
+/**
+ * Exhaustiveness guard for discriminated unions. Place in the `default` branch of a `switch` over a
+ * union's discriminant: if a new variant is added without a matching case, the call fails to compile.
+ * Throws at runtime if reached with a value the types said was impossible.
+ */
+declare function assertNever(value: never): never;
+//#endregion
+//#region src/misc/directory.d.ts
+/**
+ * Determines if a directory entry is a TypeScript or JavaScript file.
+ *
+ * @param entry - The directory entry to check.
+ * @returns True if the entry is a file ending with .ts or .js.
+ */
+declare function isTsOrJsFile(entry: fs.Dirent): boolean;
+/**
+ * Recursively traverses through a directory, importing all .ts and .js files and applying a callback to each import.
+ *
+ * @param dir - The directory path to traverse.
+ * @param callback - A function that will be called for each imported module. It receives the full file path, the file's relative path, and the imported module as arguments.
+ * @returns A Promise that resolves when the traversal is complete.
+ */
+declare function traverseDirectory(dir: string, callback: (fullPath: string, relativePath: string, imported: Record<string, unknown>) => Promise<void> | void, logger: ILogger): Promise<void>;
+/**
+ * Options for formatting file paths.
+ */
+interface FormatFileOptions {
+  /**
+   * Whether to return only the directory part of the path. {@default false}
+   */
+  onlyDir?: boolean;
+  /**
+   * A prefix to prepend to the formatted path. {@default ./}
+   */
+  prefix?: string;
+}
+/**
+ * Formats a file path relative to the current working directory.
+ * @param filePath - The file path to format.
+ * @param options - Formatting options.
+ * @returns The formatted file path.
+ */
+declare function formatFilePath(filePath: string, options?: FormatFileOptions): string;
+//#endregion
+//#region src/misc/fyShuffle.d.ts
+/**
+ * Shuffles an array using the Fisher-Yates algorithm.
+ * This function creates a new array with the same elements in a random order,
+ * without modifying the original array.
+ *
+ * @typeParam TArray - The type of elements in the array
+ * @param items - The array to shuffle
+ * @returns A new array with the same elements in a random order
+ *
+ * @example
+ * ```typescript
+ * const numbers = [1, 2, 3, 4, 5];
+ * const shuffled = fyShuffle(numbers);
+ * // shuffled might be [3, 1, 5, 2, 4]
+ * // numbers is still [1, 2, 3, 4, 5]
+ * ```
+ */
+declare function fyShuffle<TArray>(items: TArray[]): TArray[];
+//#endregion
+//#region src/numbers/currentTime.d.ts
+/**
+ * Return current time in seconds
+ */
+declare function currentTime(): number;
+//#endregion
+//#region src/numbers/generateCode.d.ts
+/**
+ * Generates a random numeric code with the specified number of digits.
+ *
+ * @param digits - The number of digits for the generated code.
+ * @returns A random numeric code with the specified number of digits.
+ */
+declare function generateCode(digits: number): number;
+//#endregion
+//#region src/numbers/ordinal.d.ts
+/**
+ * Returns the ordinal suffix for a given number.
+ *
+ * @param n - The number to get the ordinal for
+ * @returns The number with its ordinal suffix
+ *
+ * @example
+ * ordinal(1); // "1st"
+ * ordinal(22); // "22nd"
+ * ordinal(13); // "13th"
+ */
+declare function ordinal(n: number): string;
+//#endregion
+//#region src/numbers/percentage.d.ts
+/**
+ * Takes two numbers and returns the percentage of the first number in the second number with two decimal places.
+ *
+ * @param num1 - The first number.
+ * @param num2 - The second number.
+ *
+ * @returns The percentage of the first number in the second number with two decimal places.
+ */
+declare function percentage(num1: number, num2: number): number;
+//#endregion
+//#region src/numbers/round.d.ts
+/**
+ * Rounds a number to a specified number of decimal places.
+ *
+ * @param num - The number to be rounded.
+ * @param precision - The number of decimal places to round to.
+ * @returns The rounded number.
+ */
+declare function round(num: number, precision: number): number;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/json-value.d.ts
+/**
+Matches any valid JSON primitive value.
+
+@category JSON
+*/
+type JsonPrimitive = string | number | boolean | null;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/union-to-intersection.d.ts
+/**
+Convert a union type to an intersection type.
+
+Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
+
+@example
+```
+import type {UnionToIntersection} from 'type-fest';
+
+type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};
+
+type Intersection = UnionToIntersection<Union>;
+//=> {the(): void} & {great(arg: string): void} & {escape: boolean}
+```
+
+@category Type
+*/
+type UnionToIntersection<Union> = (// `extends unknown` is always going to be the case and is used to convert the
+// `Union` into a [distributive conditional
+// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+Union extends unknown // The union type is used as the only argument to a function since the union
+// of function arguments is an intersection.
+? (distributedUnion: Union) => void // This won't happen.
+: never // Infer the `Intersection` type since TypeScript represents the positional
+// arguments of unions of functions as an intersection of the union.
+) extends ((mergedIntersection: infer Intersection) => void) // The `& Union` is to ensure result of `UnionToIntersection<A | B>` is always assignable to `A | B`
+? Intersection & Union : never;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/is-any.d.ts
+/**
+Returns a boolean for whether the given type is `any`.
+
+@link https://stackoverflow.com/a/49928360/1490091
+
+Useful in type utilities, such as disallowing `any`s to be passed to a function.
+
+@example
+```
+import type {IsAny} from 'type-fest';
+
+const typedObject = {a: 1, b: 2} as const;
+const anyObject: any = {a: 1, b: 2};
+
+function get<O extends (IsAny<O> extends true ? {} : Record<string, number>), K extends keyof O = keyof O>(object: O, key: K) {
+	return object[key];
+}
+
+const typedA = get(typedObject, 'a');
+//=> 1
+
+const anyA = get(anyObject, 'a');
+//=> any
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsAny<T> = 0 extends 1 & NoInfer<T> ? true : false;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/is-never.d.ts
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever, And} from 'type-fest';
+
+type A = IsNever<never>;
+//=> true
+
+type B = IsNever<any>;
+//=> false
+
+type C = IsNever<unknown>;
+//=> false
+
+type D = IsNever<never[]>;
+//=> false
+
+type E = IsNever<object>;
+//=> false
+
+type F = IsNever<string>;
+//=> false
+```
+
+@example
+```
+import type {IsNever} from 'type-fest';
+
+type IsTrue<T> = T extends true ? true : false;
+
+// When a distributive conditional is instantiated with `never`, the entire conditional results in `never`.
+type A = IsTrue<never>;
+//=> never
+
+// If you don't want that behaviour, you can explicitly add an `IsNever` check before the distributive conditional.
+type IsTrueFixed<T> =
+	IsNever<T> extends true ? false : T extends true ? true : false;
+
+type B = IsTrueFixed<never>;
+//=> false
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsNever<T> = [T] extends [never] ? true : false;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/if.d.ts
+/**
+An if-else-like type that resolves depending on whether the given `boolean` type is `true` or `false`.
+
+Use-cases:
+- You can use this in combination with `Is*` types to create an if-else-like experience. For example, `If<IsAny<any>, 'is any', 'not any'>`.
+
+Note:
+- Returns a union of if branch and else branch if the given type is `boolean` or `any`. For example, `If<boolean, 'Y', 'N'>` will return `'Y' | 'N'`.
+- Returns the else branch if the given type is `never`. For example, `If<never, 'Y', 'N'>` will return `'N'`.
+
+@example
+```
+import type {If} from 'type-fest';
+
+type A = If<true, 'yes', 'no'>;
+//=> 'yes'
+
+type B = If<false, 'yes', 'no'>;
+//=> 'no'
+
+type C = If<boolean, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type D = If<any, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type E = If<never, 'yes', 'no'>;
+//=> 'no'
+```
+
+@example
+```
+import type {If, IsAny, IsNever} from 'type-fest';
+
+type A = If<IsAny<unknown>, 'is any', 'not any'>;
+//=> 'not any'
+
+type B = If<IsNever<never>, 'is never', 'not never'>;
+//=> 'is never'
+```
+
+@example
+```
+import type {If, IsEqual} from 'type-fest';
+
+type IfEqual<T, U, IfBranch, ElseBranch> = If<IsEqual<T, U>, IfBranch, ElseBranch>;
+
+type A = IfEqual<string, string, 'equal', 'not equal'>;
+//=> 'equal'
+
+type B = IfEqual<string, number, 'equal', 'not equal'>;
+//=> 'not equal'
+```
+
+Note: Sometimes using the `If` type can make an implementation non–tail-recursive, which can impact performance. In such cases, it’s better to use a conditional directly. Refer to the following example:
+
+@example
+```
+import type {If, IsEqual, StringRepeat} from 'type-fest';
+
+type HundredZeroes = StringRepeat<'0', 100>;
+
+// The following implementation is not tail recursive
+type Includes<S extends string, Char extends string> =
+	S extends `${infer First}${infer Rest}`
+		? If<IsEqual<First, Char>,
+			'found',
+			Includes<Rest, Char>>
+		: 'not found';
+
+// Hence, instantiations with long strings will fail
+// @ts-expect-error
+type Fails = Includes<HundredZeroes, '1'>;
+//           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Error: Type instantiation is excessively deep and possibly infinite.
+
+// However, if we use a simple conditional instead of `If`, the implementation becomes tail-recursive
+type IncludesWithoutIf<S extends string, Char extends string> =
+	S extends `${infer First}${infer Rest}`
+		? IsEqual<First, Char> extends true
+			? 'found'
+			: IncludesWithoutIf<Rest, Char>
+		: 'not found';
+
+// Now, instantiations with long strings will work
+type Works = IncludesWithoutIf<HundredZeroes, '1'>;
+//=> 'not found'
+```
+
+@category Type Guard
+@category Utilities
+*/
+type If<Type extends boolean, IfBranch, ElseBranch> = IsNever<Type> extends true ? ElseBranch : Type extends true ? IfBranch : ElseBranch;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/unknown-array.d.ts
+/**
+Represents an array with `unknown` value.
+
+Use case: You want a type that all arrays can be assigned to, but you don't care about the value.
+
+@example
+```
+import type {UnknownArray} from 'type-fest';
+
+type IsArray<T> = T extends UnknownArray ? true : false;
+
+type A = IsArray<['foo']>;
+//=> true
+
+type B = IsArray<readonly number[]>;
+//=> true
+
+type C = IsArray<string>;
+//=> false
+```
+
+@category Type
+@category Array
+*/
+type UnknownArray = readonly unknown[];
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/internal/type.d.ts
+/**
+An if-else-like type that resolves depending on whether the given type is `any` or `never`.
+
+@example
+```
+// When `T` is a NOT `any` or `never` (like `string`) => Returns `IfNotAnyOrNever` branch
+type A = IfNotAnyOrNever<string, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'VALID'
+
+// When `T` is `any` => Returns `IfAny` branch
+type B = IfNotAnyOrNever<any, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'IS_ANY'
+
+// When `T` is `never` => Returns `IfNever` branch
+type C = IfNotAnyOrNever<never, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'IS_NEVER'
+```
+
+Note: Wrapping a tail-recursive type with `IfNotAnyOrNever` makes the implementation non-tail-recursive. To fix this, move the recursion into a helper type. Refer to the following example:
+
+@example
+```ts
+import type {StringRepeat} from 'type-fest';
+
+type NineHundredNinetyNineSpaces = StringRepeat<' ', 999>;
+
+// The following implementation is not tail recursive
+type TrimLeft<S extends string> = IfNotAnyOrNever<S, S extends ` ${infer R}` ? TrimLeft<R> : S>;
+
+// Hence, instantiations with long strings will fail
+// @ts-expect-error
+type T1 = TrimLeft<NineHundredNinetyNineSpaces>;
+//        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Error: Type instantiation is excessively deep and possibly infinite.
+
+// To fix this, move the recursion into a helper type
+type TrimLeftOptimised<S extends string> = IfNotAnyOrNever<S, _TrimLeftOptimised<S>>;
+
+type _TrimLeftOptimised<S extends string> = S extends ` ${infer R}` ? _TrimLeftOptimised<R> : S;
+
+type T2 = TrimLeftOptimised<NineHundredNinetyNineSpaces>;
+//=> ''
+```
+*/
+type IfNotAnyOrNever<T, IfNotAnyOrNever, IfAny = any, IfNever = never> = If<IsAny<T>, IfAny, If<IsNever<T>, IfNever, IfNotAnyOrNever>>;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/numeric.d.ts
+type _Numeric = number | bigint;
+type Zero = 0 | 0n;
+/**
+Matches the hidden `Infinity` type.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript.
+
+@see {@link NegativeInfinity}
+
+@category Numeric
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line no-loss-of-precision
+/**
+A negative `number`/`bigint` (`-∞ < x < 0`)
+
+Use-case: Validating and documenting parameters.
+
+@see {@link NegativeInteger}
+@see {@link NonNegative}
+
+@category Numeric
+*/
+type Negative<T extends _Numeric> = T extends Zero ? never : `${T}` extends `-${string}` ? T : never;
+/**
+Returns a boolean for whether the given number is a negative number.
+
+@see {@link Negative}
+
+@example
+```
+import type {IsNegative} from 'type-fest';
+
+type ShouldBeFalse = IsNegative<1>;
+type ShouldBeTrue = IsNegative<-1>;
+```
+
+@category Numeric
+*/
+type IsNegative<T extends _Numeric> = T extends Negative<T> ? true : false;
+//#endregion
+//#region ../../node_modules/.pnpm/type-fest@5.6.0/node_modules/type-fest/source/tuple-of.d.ts
+/**
+Create a tuple type of the specified length with elements of the specified type.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type RGB = TupleOf<3, number>;
+//=> [number, number, number]
+
+type Line = TupleOf<2, {x: number; y: number}>;
+//=> [{x: number; y: number}, {x: number; y: number}]
+
+type TicTacToeBoard = TupleOf<3, TupleOf<3, 'X' | 'O' | null>>;
+//=> [['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null], ['X' | 'O' | null, 'X' | 'O' | null, 'X' | 'O' | null]]
+```
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type Range<Start extends number, End extends number> = Exclude<keyof TupleOf<End>, keyof TupleOf<Start>>;
+
+type ZeroToFour = Range<0, 5>;
+//=> '0' | '1' | '2' | '3' | '4'
+
+type ThreeToEight = Range<3, 9>;
+//=> '5' | '3' | '4' | '6' | '7' | '8'
+```
+
+Note: If the specified length is the non-literal `number` type, the result will not be a tuple but a regular array.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type StringArray = TupleOf<number, string>;
+//=> string[]
+```
+
+Note: If the type for elements is not specified, it will default to `unknown`.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type UnknownTriplet = TupleOf<3>;
+//=> [unknown, unknown, unknown]
+```
+
+Note: If the specified length is negative, the result will be an empty tuple.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type EmptyTuple = TupleOf<-3, string>;
+//=> []
+```
+
+Note: If you need a readonly tuple, simply wrap this type with `Readonly`, for example, to create `readonly [number, number, number]` use `Readonly<TupleOf<3, number>>`.
+
+@category Array
+*/
+type TupleOf<Length extends number, Fill = unknown> = IfNotAnyOrNever<Length, _TupleOf<If<IsNegative<Length>, 0, Length>, Fill, []>, Fill[], []>;
+type _TupleOf<L extends number, Fill, Accumulator extends UnknownArray> = number extends L ? Fill[] : L extends Accumulator['length'] ? Accumulator : _TupleOf<L, Fill, [...Accumulator, Fill]>;
+//#endregion
+//#region src/numbers/roundToDenomination.d.ts
+interface RoundToDenomOptions {
+  /**
+   * Suffixes to use for each denomination level. Defaults to `['K', 'M', 'B', 'T', 'Q']`.
+   */
+  suffixes?: TupleOf<5, string>;
+  /** Number of decimal places to include in the rounded result. Defaults to `1`. */
+  precision?: number;
+}
+/**
+ * Rounds a number to a string representation with a denomination suffix.
+ * @param num - The number to round.
+ * @example
+ * ```ts
+ * roundToDenomination(1234); // "1.2K"
+ * roundToDenomination(10000, ['k', 'm', 'b', 't', 'q']); // "10k"
+ * roundToDenomination(12345678); // "12.3M"
+ * ```
+ * @returns The rounded number as a string with a denomination suffix.
+ */
+declare function roundToDenomination(num: number, opts?: RoundToDenomOptions): string;
+//#endregion
+//#region src/objects/filterCirculars.d.ts
+/**
+ * JSONify an arbitrary type while allowing any object position to be replaced
+ * by a circular marker. Optional keys stay optional.
+ */
+type JsonifyWithCirculars<BaseType, Marker extends string = '[Circular]'> = BaseType extends JsonPrimitive ? BaseType : BaseType extends bigint ? string : BaseType extends Date ? string : BaseType extends {
+  toJSON(): infer J;
+} ? unknown extends J ? JsonifyObject<BaseType, Marker> : JsonifyWithCirculars<J, Marker> : BaseType extends readonly (infer U)[] ? (JsonifyWithCirculars<U, Marker> | Marker)[] : BaseType extends Map<infer K, infer V> ? [JsonifyWithCirculars<K, Marker> | Marker, JsonifyWithCirculars<V, Marker> | Marker][] : BaseType extends Set<infer U2> ? (JsonifyWithCirculars<U2, Marker> | Marker)[] : BaseType extends ((...args: unknown[]) => unknown) ? never : BaseType extends object ? JsonifyObject<BaseType, Marker> : never;
+/**
+ * Helper to JSONify object types with circular markers.
+ *
+ * @internal
+ */
+type JsonifyObject<BaseType, Marker extends string> = { [K in keyof BaseType as K extends symbol ? never : BaseType[K] extends ((...args: unknown[]) => unknown) ? never : K]: JsonifyWithCirculars<Exclude<BaseType[K], undefined>, Marker> | Extract<BaseType[K], undefined> | Marker };
+/**
+ * Returned by {@link filterCirculars} when a value cannot be made JSON-safe. The original value is
+ * never returned on failure, because it would re-throw in the caller's own `JSON.stringify`.
+ */
+interface UnserializableValue {
+  '[unserializable]': string;
+}
+/**
+ * Configuration for {@link filterCirculars}.
+ */
+interface FilterCircularsOptions<Marker extends string = '[Circular]'> {
+  /** Optional {@link ILogger} used to log stringify or parse errors. */
+  logger?: ILogger;
+  /** Override the circular placeholder. Default is `[Circular]`. */
+  marker?: Marker;
+  /** Processing mode. `json` uses stringify and parse (might end up using a `toJSON()` if found). `decycle` builds a safe clone first. Default is `decycle`. */
+  mode?: 'json' | 'decycle';
+}
+/**
+ * Creates a clean, JSON safe copy of a value and replaces circular references with a marker.
+ *
+ * In `json` mode it behaves like stringify then parse with a replacer that handles cycles and BigInt.
+ * In `decycle` mode it first clones without using toJSON, then you can stringify the result later.
+ *
+ * @typeParam ObjType - Type of the input value.
+ * @typeParam Marker - Marker string used for circular references.
+ *
+ * @param value - The value to clone safely.
+ * @param options - Optional configuration.
+ *
+ * @returns A JSON safe structure with circular references replaced by the marker.
+ *
+ * @example
+ * ```ts
+ * interface Test {
+ *   name: string;
+ *   self?: Test;
+ * }
+ *
+ * const obj: Test = { name: 'seedcord' };
+ * obj.self = obj;
+ *
+ * const clean = filterCirculars(obj);
+ * //     ^? { name: string; self?: "[Circular]" | { ... } }
+ * console.log(clean.self); // "[Circular]"
+ * ```
+ */
+declare function filterCirculars<ObjType, Marker extends string = '[Circular]'>(value: ObjType, options?: FilterCircularsOptions<Marker>): JsonifyWithCirculars<ObjType, Marker> | UnserializableValue;
+//#endregion
+//#region src/objects/hasKeys.d.ts
+/**
+ * Extracts the type of a nested property, distributing over unions.
+ *
+ * @internal
+ */
+type DeepGet<Obj, Key extends string> = Obj extends unknown ? Key extends `${infer K}.${infer Rest}` ? K extends keyof Obj ? DeepGet<NonNullable<Obj[K]>, Rest> : never : Key extends keyof Obj ? Obj[Key] : never : never;
+/**
+ * Converts a dot-notation path string into a nested object type with a specific leaf value.
+ *
+ * @internal
+ */
+type PathToObj<Path extends string, Value> = Path extends `${infer Head}.${infer Tail}` ? { [K in Head]: PathToObj<Tail, Value> } : { [K in Path]: Value };
+/**
+ * Checks for the presence of nested keys in an object that's possibly a distributed union, narrowing the object type accordingly.
+ *
+ * Checks if an object has the specified nested keys and that their values are not null or undefined. If they are not, the object type is narrowed to reflect the presence of these keys with their respective types from the original distributed union object.
+ *
+ * @param obj - The object to check.
+ * @param keys - An array of dot-notation paths to check.
+ * @returns True if all keys exist and are non-null/defined, narrowing the object type.
+ *
+ * @example
+ * ```ts
+ * interface Test {
+ *   a?: {
+ *     b?: {
+ *       c?: string;
+ *     };
+ *   } | null;
+ *   x?: number | null;
+ * }
+ *
+ * const obj: Test = { a: { b: { c: 'hello' } }, x: 42 };
+ *
+ * if (hasKeys(obj, ['a.b.c', 'x'])) {
+ *   // Here, obj is narrowed to:
+ *   // {
+ *   //   a: { b: { c: string } };
+ *   //   x: number;
+ *   // }
+ *   console.log(obj.a.b.c.toUpperCase()); // Safe to access and use
+ *   console.log(obj.x.toFixed(2)); // Safe to access and use
+ * }
+ * ```
+ */
+declare function hasKeys<Obj extends object, Keys extends string>(obj: Obj, keys: Keys[]): obj is Obj & UnionToIntersection<Keys extends unknown ? PathToObj<Keys, UnionToIntersection<NonNullable<DeepGet<Obj, Keys>>>> : never>;
+//#endregion
+//#region src/objects/keepDefined.d.ts
+/**
+ * Copies only the keys whose values are defined.
+ *
+ * @typeParam TObject - the original object type you're pulling from
+ * @typeParam TKey - the keys to copy when defined
+ * @param source - the object to read values from
+ * @param keys - optional list of keys to include when present. If omitted, all keys are considered
+ *
+ * @example
+ * ```ts
+ * interface Config {
+ *   host?: string;
+ *   port?: number;
+ *   user?: string;
+ *   password?: string;
+ * }
+ *
+ * const config: Config = {
+ *   host: 'localhost',
+ *   port: undefined,
+ *   user: 'admin',
+ *   password: undefined
+ * };
+ *
+ * const definedConfig = keepDefined(config, 'host', 'port', 'user', 'password');
+ * // Result: { host: 'localhost', user: 'admin' }
+ * ```
+ */
+declare function keepDefined<TObject extends object, TKey extends keyof TObject>(source: TObject, ...keys: readonly TKey[]): Partial<Pick<TObject, TKey extends never ? keyof TObject : TKey>>;
+//#endregion
+//#region src/strings/capitalize.d.ts
+/**
+ * Returns the word with its first letter capitalized and the rest in lowercase.
+ * @param word - The word to be formatted.
+ * @returns The formatted word.
+ */
+declare function capitalize(word: string): string;
+//#endregion
+//#region src/strings/longestStringLength.d.ts
+/**
+ * Function takes an array of strings or numbers and returns the number of characters in the longest string/number
+ *
+ * @param arr - The array of strings or numbers
+ * @returns The length of the longest element when converted to string
+ */
+declare function longestStringLength(arr: (string | number)[]): number;
+//#endregion
+//#region src/strings/generateAsciiTable.d.ts
+/**
+ * Generates an ASCII table from the provided data.
+ *
+ * @param data - The data to be displayed in the table.
+ * @returns The generated ASCII table as a string.
+ */
+declare function generateAsciiTable(data: string[][]): string;
+//#endregion
+//#region src/strings/prettify.d.ts
+/**
+ * Options for the `prettify` function.
+ */
+interface PrettifyOptions {
+  capitalize?: boolean;
+}
+/**
+ * Converts a string from any common naming convention to human-readable format.
+ * Accepts camelCase, PascalCase, snake_case, and kebab-case input.
+ *
+ * @param key - The string to convert
+ * @param opts - Optional configuration
+ * @returns A space-separated, human-readable string
+ *
+ * @example
+ * prettify("camelCaseString") // "camel Case String"
+ * prettify("PascalCaseString") // "Pascal Case String"
+ * prettify("snake_case_string") // "snake case string"
+ * prettify("kebab-case-string") // "kebab case string"
+ * prettify("mixedCase_string-name") // "mixed Case string name"
+ */
+declare function prettify(key: string, opts?: PrettifyOptions): string;
+//#endregion
+//#region src/strings/prettyDifference.d.ts
+/**
+ * Calculates the difference between two numbers and formats it as a string with a '+' prefix for positive differences.
+ *
+ * @param numBefore - The initial number value
+ * @param numAfter - The final number value
+ * @returns A string representing the difference, with a '+' sign for positive differences
+ *
+ * @example
+ * // Returns "+5"
+ * prettyDifference(10, 15);
+ *
+ * @example
+ * // Returns "-3"
+ * prettyDifference(10, 7);
+ */
+declare function prettyDifference(numBefore: number, numAfter: number): string;
+//#endregion
+//#region src/index.d.ts
+/** Package version */
+declare const version: string;
+//#endregion
+export { DeepGet, FilterCircularsOptions, FormatFileOptions, JsonifyObject, JsonifyWithCirculars, PathToObj, PrettifyOptions, RoundToDenomOptions, UnserializableValue, assertNever, capitalize, currentTime, filterCirculars, formatFilePath, fyShuffle, generateAsciiTable, generateCode, hasKeys, isTsOrJsFile, keepDefined, longestStringLength, ordinal, percentage, prettify, prettyDifference, round, roundToDenomination, traverseDirectory, version };
+//# sourceMappingURL=index.d.mts.map