type NonEmpty = string | any[] | Record<string, unknown> | number | boolean;

interface PrimeString {
    /** Replace the file extension with `ext`. */
    changeExtension(ext: string): string;
    /** Return the string reversed. */
    reverse(): string;
    /** Convert the string to Title Case. */
    toTitleCase(): string;
    /** Split string into words. */
    words(): string[];
    /** Reverse slashes relative to `str`. */
    slashreverse(str: string): string;
    /** Convert slashes to Windows style. */
    slashwin(): string;
    /** Convert slashes to POSIX style. */
    slashlinux(): string;
    /** Trim whitespace from both ends. */
    strip(): string;
    /** Return true if contains any of the provided substrings. */
    containsAny(...arr: string[]): boolean;
    /** Create a URL/file-system safe slug. */
    toSlug(): string;
    /** Compare strings after stripping/normalizing. */
    stripCompare(other: string): boolean;
    /** Capitalize each word in the string. */
    toWordCapitalized(): string;
    /** Truncate to `length`, appending optional `suffix`. */
    truncate(length: number, suffix?: string): string;
    /** Return true if string contains valid JSON. */
    isJson(): boolean;
    /** Convert string to camelCase. */
    toCamelCase(): string;
    /** Parse JSON and return value or original on failure. */
    safeParseJson(): any;
    /** Parse JSON and return value or null on failure. */
    nullParseJson(): any | null;
    /** Compare two paths by filename only. */
    filenameCompare(otherPath: string): boolean;
    /** Return substring between optional start and stop markers. */
    substringFrom(startStr?: string, stopStr?: string): string;
    /** Escape HTML special characters. */
    escapeHTML(): string;
    /** Unescape HTML entities to characters. */
    unescapeHTML(): string;
    /** Humanize identifiers: split camelCase, replace dashes/underscores, capitalize sentences. */
    humanize(): string;
    /** Convert to underscore_case. */
    underscore(): string;
    /** True if trimmed string is empty. */
    isEmpty(): boolean;
    /** Count occurrences of substring; case sensitive by default. */
    countOccurrence(str2: string, caseSens?: boolean): number;
    /** True if string represents a number. */
    isNumber(): boolean;
    /** True if string represents a float. */
    isFloat(): boolean;
    /** True if string is alphanumeric. */
    isAlphaNumeric(): boolean;
    /** True if string is all lowercase (with letters present). */
    isLower(): boolean;
    /** True if string is all uppercase (with letters present). */
    isUpper(): boolean;
    /** Simple non-crypto hash (hex); optional truncate. */
    hashed(truncate?: number): string;
    /** Replace the last occurrence of search with replacement. */
    replaceLast(search: string | RegExp, replacement: string): string;
    /** Remove diacritics (latinize). */
    latinise(): string;
    /** Truncate with "..." to total width. */
    ellipsis(total: number): string;
    /** Extract a numeric value from the string. */
    toNumber(): number;
    /** Parse boolean from common truthy/falsey words. */
    toBoolean(): boolean;
    /** Assert this is a non-empty string; returns NonEmpty or false. */
    assertNonEmptyString(): (string & NonEmpty) | false;
    /** True if string is non-empty after trimming (type guard). */
    isNonEmty(): this is string & NonEmpty;
}
interface PrimeNumber {
    /** Assert number is between `min` and `max` (type guard style). */
    assertNrBetween(min?: number, max?: number): this is number;
    /** True if integer. */
    isInteger(): this is number;
    /** True if finite (not NaN/Infinity). */
    isFinite(): this is number;
    /** True if safe integer. */
    isSafeInteger(): this is number;
    /** True if > 0. */
    isPositive(): this is number;
    /** True if < 0. */
    isNegative(): this is number;
    /** True if >= 0. */
    isNonNegative(): this is number;
    /** Assert integer (throws on failure). */
    assertIsInteger(): asserts this is number;
    /** Assert finite (throws on failure). */
    assertIsFinite(): asserts this is number;
    /** Like `toFixed` but returns a number. */
    toFixedNumber(decimals?: number): number;
    /** Check if number is between min and max (inclusive). */
    between(min: number, max: number): boolean;
    /** Clamp the number between min and max. */
    clamp(min: number, max: number): number;
    /** Run `fn` `n` times with index. */
    times(fn: (i: number) => void): void;
    /** Return string with leading zeros to reach `length`. */
    toStringWithLeadingZeros(length: number): string;
    /** Convert seconds/number to a timecode string. */
    toTimeCode(): string;
    /** Calculate what percent this number is of total. */
    percentOf(total: number): number;
    /** Calculate what ratio this number is of total. */
    ratioOf(total: number): number;
}
interface PrimeArray<T> {
    /** Return first element or first n elements. */
    first(n?: number): T | T[];
    /** Return last element or last n elements. */
    last(n?: number): T | T[];
    /** Find an item where `key` equals `value`. */
    findByKey<K extends keyof T & string>(key: K, value: any): T | null;
    /** Group items using a mapping function. */
    groupBy(fn: (item: T) => string): Record<string, T[]>;
    /** Group items by a property key. */
    groupBy<K extends keyof T & string>(key: K): Record<string, T[]>;
    /** Sum numeric values at the given key. */
    sumByKey<K extends keyof T & string>(key: K): number;
    /** Parse item string fields where applicable. */
    autoParseKeys(): T[];
    /** Return array with duplicates removed. */
    unique(): T[];
    /** Return a shuffled copy of the array. */
    shuffle(): T[];
    /** Return item with highest value for key or null. */
    highestByKey<K extends keyof T & string>(key: K): T | null;
    /** Return item with lowest value for key or null. */
    lowestByKey<K extends keyof T & string>(key: K): T | null;
    /** Sort array by key; ascending by default. */
    sortByKey<K extends keyof T & string>(key: K, ascending?: boolean): T[];
    /** Sort array by key name (string) with optional order. */
    sortByKeyName<K extends keyof T & string>(key: K, ascending?: boolean): T[];
    /** Map array to values of the given key. */
    mapByKey<K extends keyof T & string>(key: K): Array<T[K]>;
    /** Sum numeric values at key across objects. */
    sumKey(key: string): number;
    /** Average numeric values at key across objects. */
    averageKey(key: string): number;
    /** Filter by a key using predicate. */
    filterKey(key: string, pred: (v: any) => boolean): T[];
    /** Unique objects by key or projection function. */
    distinct(keyOrFn: string | ((x: T) => any)): T[];
    /** Group-reduce objects by key or projection. */
    aggregate<R>(keyOrFn: string | ((x: T) => any), reducer: (acc: R, cur: T) => R, init: R): Record<string, R>;
    /** Sum numeric values by key (string). */
    sumBy(key: string): number;
    /** Average numeric values by key (string). */
    averageBy(key: string): number;
    /** Sum all numeric values in the array. */
    sum(): number;
    /** Average all numeric values in the array. */
    average(): number;
    /** Return index of the highest number in the array. */
    indexOfHighestNumber(): number;
    /** Return index of the lowest number in the array. */
    indexOfLowestNumber(): number;
    /** Return intersection with another array (items present in both). */
    intersect(other: T[]): T[];
    /** Return difference with another array (items present only in this). */
    difference(other: T[]): T[];
    /** Validate each item; replace invalids with null and keep valid items. */
    validateEach(validatorFn: (item: T) => boolean): (T | null)[];
    /** Remove null and undefined values, returning a narrowed array. */
    clearNil(): T[];
    /** Group-reduce objects by key or projection. */
    toTable(): Record<string, any[]>;
}
interface Pkit {
    (value: undefined): null;
    (value: null): boolean;
    (value: string): PrimeString;
    (value: number): PrimeNumber;
    <T>(value: T[]): PrimeArray<T>;
    (value: Record<string, any>): PrimeObject;
    <T>(value: T): {
        unwrap(): T;
    };
    math: MathUtils;
    path: PathShim;
}
interface PrimeObject {
    /** Type guard: is a plain object (not array). */
    isObject(): this is Record<string, any>;
    /** Assert object has provided keys. */
    assertHasKeys<K extends string>(...keys: K[]): asserts this is Record<string, any> & Record<K, unknown>;
    /** Cast after validation. */
    asType<T>(): T;
    /** True if all values are non-empty strings. */
    isNonEmty(): this is Record<string, any> & Record<string, NonEmpty>;
    /** Map: keys -> boolean flag if value is empty. */
    mapEmptyToFalseyKeyObje(): Record<string, Boolean>;
    /** Map: values -> boolean flag if value is empty. */
    mapEmptyToFalseyValueArray(): Record<string, Boolean>;
    /** Return a new object with keys sorted by `sorterFn`. */
    sortKeys(sorterFn?: ((a: string, b: string) => number) | null): Record<string, any>;
    /** Shallow structural equality by keys and types. */
    equals(other: Record<string, any>): boolean;
    /** Return object without specified keys. */
    omit(...keys: string[]): Record<string, any>;
    /** Return object containing only specified keys. */
    pick(...keys: string[]): Record<string, any>;
    /** Fill missing keys from source without overwriting existing. */
    complement(src: Record<string, any>): Record<string, any>;
    /** Remove empty string/null/undefined entries. */
    clean(): Record<string, any>;
    /** Ensure keys conform to schema; optional type coercion. */
    ensureSchema(schema: Record<string, any>, opts?: {
        coerce?: boolean;
    }): Record<string, any>;
    /** Filter object entries by predicate. */
    filterEntries(predicate: (k: string, v: any) => boolean): Record<string, any>;
    /** Merge with another object; control array merge strategy. */
    merge(other: Record<string, any>, opts?: {
        arrayStrategy?: "concat" | "replace" | "unique";
    }): Record<string, any>;
    /** Return a new object with keys sorted by `sorterFn`. */
    sortKeys(sorterFn?: ((a: string, b: string) => number) | null): Record<string, any>;
    /** Shallow structural equality by keys and types. */
    equals(other: Record<string, any>): boolean;
    /** Return object without specified keys. */
    omit(...keys: string[]): Record<string, any>;
    /** Return object containing only specified keys. */
    pick(...keys: string[]): Record<string, any>;
    /** Fill missing keys from source without overwriting existing. */
    complement(src: Record<string, any>): Record<string, any>;
    /** Remove empty string/null/undefined entries. */
    clean(): Record<string, any>;
    /** Ensure keys conform to schema; optional type coercion. */
    ensureSchema(schema: Record<string, any>, opts?: {
        coerce?: boolean;
    }): Record<string, any>;
    /** Filter object entries by predicate. */
    filterEntries(predicate: (k: string, v: any) => boolean): Record<string, any>;
    /** Merge with another object; control array merge strategy. */
    merge(other: Record<string, any>, opts?: {
        arrayStrategy?: "concat" | "replace" | "unique";
    }): Record<string, any>;
}
declare const pkit: Pkit;

declare function applyPrimitives(): void;

export { type Pkit, type PrimeArray, type PrimeNumber, type PrimeObject, type PrimeString, applyPrimitives, applyPrimitives as applyPrimitivesGlobally, pkit };