@cripty2001/utils 0.0.37 → 0.0.38

package/dist/index.d.ts

@@ -10,23 +10,75 @@ export type ExactlyOne<T> = {
     [K in keyof T]: Pick<T, K> & Partial<Record<Exclude<keyof T, K>, never>>;
 }[keyof T];
 export type AllRequired<T> = T extends ExactlyOne<infer U> ? ExactlyOne<Required<U>> : never;
+/**
+ * Generate a random string from the given alphabeth.
+ * @param _alphabeth The alphabeth to draw characters from
+ * @param length The length of the string to generate
+ * @returns The generated string
+ */
 export declare function getRandom(_alphabeth: string, length: number): string;
+/**
+ * Generate a random, url safe, id string, with 3 bits of entropy per character.
+ * @param length The length of the id to generate
+ * @returns The generated id
+ */
 export declare function getRandomId(length?: number): string;
+/**
+ * Generate a random one time password (OTP).
+ * @param length The length of the OTP to generate
+ * @param char Allow for characters to be inserted in the otp
+ * @returns The generated otp
+ */
 export declare function getRandomOtp(length?: number, char?: boolean): string;
+/**
+ * Pause the execution for the given number of milliseconds.
+ * @param ms The number of milliseconds to sleep
+ */
 export declare function sleep(ms: number): Promise<void>;
 export declare function parseHash(fields: string[]): URLSearchParams;
-export declare function loop(cb: () => Promise<void>, interval: number, onError?: (e: any) => Promise<void>): Promise<void>;
+/**
+ * Start an infinite loop executing an async callback spaced by at least the given interval.
+ * The loop ignores errors (the next execution is not affected), but an optional error callback can be provided to handle them.
+ * The error callback can return true to stop the loop. An error in the error callback will be logged, but the loop will continue.
+ *
+ * @param cb The (async) callback to execute
+ * @param interval The minimum interval between two executions, in milliseconds. The execution may be scheduled later, but not earlier.
+ * @param onError The error callback. Return true to stop the loop.
+ */
+export declare function loop(cb: () => Promise<void>, interval: number, onError?: (e: any) => Promise<boolean>): Promise<void>;
 /**
  * Float aware deep equality check between two values.
  */
 export declare function isEqual(a: any, b: any): boolean;
 export declare function arrayStep(from: number, to: number, step: number): number[];
+/**
+ * Copy the given text to clipboard.
+ * @param text The text to copy to clipboard
+ */
 export declare function copyToClipboard(text: string): void;
+/**
+ * Download data as a file.
+ * @param data The data to download
+ * @param filename The filename to use
+ * @param mimeType The mime type of the data
+ */
 export declare function download(data: string | Blob, filename: string, mimeType?: string): void;
 export declare function stableLog(obj: any, message?: string): void;
 export declare function parseQuery(query: string | Record<string, any> | URLSearchParams, fields: string[]): {
     extracted: URLSearchParams;
     left: URLSearchParams;
 };
+/**
+ * Generate a random int between min and max, inclusive.
+ * @param min The minimum allowed number
+ * @param max The maximum allowed number
+ * @returns The generated random int
+ */
 export declare function randBetween(min: number, max: number): number;
+/**
+ * Get an environment variable, throwing if it is not defined and no default value is provided.
+ * @param key The environment variable key
+ * @param defaultValue The default value to use if the environment variable is not defined
+ * @returns The environment variable value, or the default value if provided
+ */
 export declare function getEnv(key: string, defaultValue?: string): string;

package/dist/index.js

@@ -15,6 +15,12 @@ exports.parseQuery = parseQuery;
 exports.randBetween = randBetween;
 exports.getEnv = getEnv;
 const lodash_1 = require("lodash");
+/**
+ * Generate a random string from the given alphabeth.
+ * @param _alphabeth The alphabeth to draw characters from
+ * @param length The length of the string to generate
+ * @returns The generated string
+ */
 function getRandom(_alphabeth, length) {
     const alphabeth = _alphabeth.split("");
     const toReturn = [];
@@ -23,14 +29,29 @@ function getRandom(_alphabeth, length) {
     }
     return toReturn.join("");
 }
+/**
+ * Generate a random, url safe, id string, with 3 bits of entropy per character.
+ * @param length The length of the id to generate
+ * @returns The generated id
+ */
 function getRandomId(length = 20) {
     const ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_";
     return getRandom(ALPHABET, length);
 }
+/**
+ * Generate a random one time password (OTP).
+ * @param length The length of the OTP to generate
+ * @param char Allow for characters to be inserted in the otp
+ * @returns The generated otp
+ */
 function getRandomOtp(length = 6, char = false) {
     const ALPHABET = "0123456789" + (char ? "ABCDEFGHIJKLMNOPQRSTUVWXYZ" : "");
     return getRandom(ALPHABET, length);
 }
+/**
+ * Pause the execution for the given number of milliseconds.
+ * @param ms The number of milliseconds to sleep
+ */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -53,13 +74,28 @@ function parseHash(fields) {
     // Returning extracted fields
     return toReturn;
 }
-async function loop(cb, interval, onError = async (e) => { console.error(e); }) {
+/**
+ * Start an infinite loop executing an async callback spaced by at least the given interval.
+ * The loop ignores errors (the next execution is not affected), but an optional error callback can be provided to handle them.
+ * The error callback can return true to stop the loop. An error in the error callback will be logged, but the loop will continue.
+ *
+ * @param cb The (async) callback to execute
+ * @param interval The minimum interval between two executions, in milliseconds. The execution may be scheduled later, but not earlier.
+ * @param onError The error callback. Return true to stop the loop.
+ */
+async function loop(cb, interval, onError = async (e) => { console.error(e); return false; }) {
     while (true) {
         try {
             await cb();
         }
         catch (e) {
-            await onError(e);
+            const stop = await onError(e)
+                .catch((e) => {
+                console.error("Error in loop error handler:", e);
+                return false;
+            });
+            if (stop)
+                break;
         }
         finally {
             await sleep(interval);
@@ -85,9 +121,19 @@ function arrayStep(from, to, step) {
     }
     return result;
 }
+/**
+ * Copy the given text to clipboard.
+ * @param text The text to copy to clipboard
+ */
 function copyToClipboard(text) {
     navigator.clipboard.writeText(text);
 }
+/**
+ * Download data as a file.
+ * @param data The data to download
+ * @param filename The filename to use
+ * @param mimeType The mime type of the data
+ */
 function download(data, filename, mimeType = 'application/octet-stream') {
     const blob = data instanceof Blob ? data : new Blob([data], { type: mimeType });
     const url = URL.createObjectURL(blob);
@@ -132,9 +178,21 @@ function parseQuery(query, fields) {
         left: data
     };
 }
+/**
+ * Generate a random int between min and max, inclusive.
+ * @param min The minimum allowed number
+ * @param max The maximum allowed number
+ * @returns The generated random int
+ */
 function randBetween(min, max) {
     return Math.floor(Math.random() * (max - min + 1)) + min;
 }
+/**
+ * Get an environment variable, throwing if it is not defined and no default value is provided.
+ * @param key The environment variable key
+ * @param defaultValue The default value to use if the environment variable is not defined
+ * @returns The environment variable value, or the default value if provided
+ */
 function getEnv(key, defaultValue) {
     const value = process.env[key] ?? defaultValue;
     if (value === undefined)

package/dist/react-whispr.d.ts

@@ -31,7 +31,17 @@ export declare function useWhispr<T>(data: T | Whispr<T>): Whispr<T>;
  * @param cb The callback to call on value change
  */
 export declare function useOnWhispr<T>(w: Whispr<T>, cb: (value: T) => void): void;
+/**
+ * Return a reactive current timestamp (ms), updated at the given interval.
+ * @param refresh The refresh interval
+ * @returns The current timestamp
+ */
 export declare function useCurrentTimestamp(refresh?: number): number;
+/**
+ * Debounce a reactive value, deep checking for equality, and stopping updates until the value changes.
+ * @param value The value to debounce
+ * @returns The debounced value
+ */
 export declare function useDebounced<T>(value: T): T;
 /**
  *

package/dist/react-whispr.js

@@ -66,6 +66,11 @@ function useOnWhispr(w, cb) {
         return () => unsub();
     }, [w, cb]);
 }
+/**
+ * Return a reactive current timestamp (ms), updated at the given interval.
+ * @param refresh The refresh interval
+ * @returns The current timestamp
+ */
 function useCurrentTimestamp(refresh = 1000) {
     const [currTs, setCurrTs] = (0, react_1.useState)(Date.now());
     (0, react_1.useEffect)(() => {
@@ -74,6 +79,11 @@ function useCurrentTimestamp(refresh = 1000) {
     }, [setCurrTs]);
     return currTs;
 }
+/**
+ * Debounce a reactive value, deep checking for equality, and stopping updates until the value changes.
+ * @param value The value to debounce
+ * @returns The debounced value
+ */
 function useDebounced(value) {
     const lastEmitted = (0, react_1.useRef)(value);
     const [debounced, setDebounced] = (0, react_1.useState)(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cripty2001/utils",
-  "version": "0.0.37",
+  "version": "0.0.38",
   "description": "Internal Set of utils. If you need them use them, otherwise go to the next package ;)",
   "homepage": "https://github.com/cripty2001/utils#readme",
   "bugs": {