@sv443-network/coreutils/dist/lib/misc.d.ts

Cross-platform, general-purpose, JavaScript core library for Node, Deno and the browser. Intended to be used in conjunction with `@sv443-network/userutils` and `@sv443-network/djsutils`, but can be used independently as well.

/**
 * @module misc  
 * This module contains miscellaneous functions that don't fit in another category - [see the documentation for more info](https://github.com/Sv443-Network/UserUtils/blob/main/docs.md#misc)  
 */
import type { ListLike, Prettify, Stringifiable } from "./types.js";
/**
 * A ValueGen value is either its type, a promise that resolves to its type, or a function that returns its type, either synchronous or asynchronous.  
 * ValueGen allows for the utmost flexibility when applied to any type, as long as {@linkcode consumeGen()} is used to get the final value.  
 * @template TValueType The type of the value that the ValueGen should yield  
 */
export type ValueGen<TValueType> = TValueType | Promise<TValueType> | (() => TValueType | Promise<TValueType>);
/**
 * Turns a {@linkcode ValueGen} into its final value.  
 * @template TValueType The type of the value that the ValueGen should yield  
 */
export declare function consumeGen<TValueType>(valGen: ValueGen<TValueType>): Promise<TValueType>;
/**
 * A StringGen value is either a string, anything that can be converted to a string, or a function that returns one of the previous two, either synchronous or asynchronous, or a promise that returns a string.  
 * StringGen allows for the utmost flexibility when dealing with strings, as long as {@linkcode consumeStringGen()} is used to get the final string.  
 */
export type StringGen = ValueGen<Stringifiable>;
/**
 * Turns a {@linkcode StringGen} into its final string value.  
 * @template TStrUnion The union of strings that the StringGen should yield - this allows for finer type control compared to {@linkcode consumeGen()}  
 */
export declare function consumeStringGen<TStrUnion extends string>(strGen: StringGen): Promise<TStrUnion>;
/** Options for the `fetchAdvanced()` function */
export type FetchAdvancedOpts = Prettify<Partial<{
    /** Timeout in milliseconds after which the fetch call will be canceled with an AbortController signal */
    timeout: number;
}> & RequestInit>;
/** Calls the fetch API with special options like a timeout */
export declare function fetchAdvanced(input: string | RequestInfo | URL, options?: FetchAdvancedOpts): Promise<Response>;
/**
 * Returns the length of the given list-like object (anything with a numeric `length`, `size` or `count` property, like an array, Map or NodeList).  
 * If the object doesn't have any of these properties, it will return 0 by default.  
 * Set {@linkcode zeroOnInvalid} to false to return NaN instead of 0 if the object doesn't have any of the properties.  
 */
export declare function getListLength(listLike: ListLike, zeroOnInvalid?: boolean): number;
/**
 * Pauses async execution for the specified time in ms.  
 * If an `AbortSignal` is passed, the pause will be aborted when the signal is triggered.  
 * By default, this will resolve the promise, but you can set {@linkcode rejectOnAbort} to true to reject it instead.  
 */
export declare function pauseFor(time: number, signal?: AbortSignal, rejectOnAbort?: boolean): Promise<void>;
/**
 * Turns the passed object into a "pure" object without a prototype chain, meaning it won't have any default properties like `toString`, `__proto__`, `__defineGetter__`, etc.  
 * This makes the object immune to prototype pollution attacks and allows for cleaner object literals, at the cost of being harder to work with in some cases.  
 * It also effectively transforms a `Stringifiable` value into one that will throw a TypeError when stringified instead of defaulting to `[object Object]`  
 * If no object is passed, it will return an empty object without prototype chain.  
 */
export declare function pureObj<TObj extends object>(obj?: TObj): TObj;
/**
 * Works similarly to `setInterval()`, but the callback is also called immediately and can be aborted with an `AbortSignal`.  
 * Uses `setInterval()` internally, which might cause overlapping calls if the callback's synchronous execution takes longer than the given interval time.  
 * This function will prevent skewing the interval time, contrary to {@linkcode setImmediateTimeoutLoop()}.  
 * Returns a cleanup function that will stop the interval if called.  
 */
export declare function setImmediateInterval(callback: () => void | unknown, interval: number, signal?: AbortSignal): void;
/**
 * Works similarly to `setInterval()`, but the callback is also called immediately and can be aborted with an `AbortSignal`.  
 * Uses `setTimeout()` internally to avoid overlapping calls, though this will skew the given interval time by however long the callback takes to execute synchronously.  
 * Returns a cleanup function that will stop the interval if called.  
 */
export declare function setImmediateTimeoutLoop(callback: () => void | unknown | Promise<void | unknown>, interval: number, signal?: AbortSignal): void;
/**
 * Schedules an exit of the current process after the next event loop tick, in order to allow any pending operations like IO writes to complete.  
 * Works on both Node.js and Deno, but will not work in browser environments.  
 * @param code The exit code to use, defaults to 0 (success)  
 * @param timeout The time in milliseconds to wait before exiting, defaults to 0 (exit on the next event loop tick)  
 * @throws An error if no exit method is available (e.g. in browser environments)  
 */
export declare function scheduleExit(code?: number, timeout?: number): void;