@alttiri/util-js - npm Package Compare versions

Comparing version 1.13.1-20240725 to 1.14.0-20240821

package.json

 {
   "name": "@alttiri/util-js",
-  "version": "1.13.1-20240725",
+  "version": "1.14.0-20240821",
   "description": "Some util functions for personal use",
@@ -18,2 +18,3 @@ "homepage": "https://github.com/AlttiRi/util-js",
   "main": "index.js",
+  "typings": "index.d.ts",
   "files": [
@@ -25,3 +26,2 @@ "src/**/*.js",
   ],
-  "typings": "index.d.ts",
   "repository": {
@@ -49,5 +49,5 @@ "type": "git",
   "devDependencies": {
-    "@alttiri/util-node-js": "2.0.16-20240606",
+    "@alttiri/util-node-js": "2.1.1-20240725",
     "typescript": "5.5.4"
   }
 }

README.md

@@ -7,33 +7,186 @@ # util-js
 
-```ts
-declare function sleep(ms?: number): Promise<void>;
-```
+## *.d.ts
 
 ```ts
-declare function dateToDayDateString(dateValue?: Date | string | number, utc?: boolean): string;
-
-declare function dateToDayDateTimeString(dateValue?: Date | string | number, utc?: boolean): string;
-
-declare function formatDate(dateValue?: Date | string | number, pattern?: string, utc?: boolean): string;
+/** @deprecated */
+export { formatSizeWinLike as bytesToSizeWinLike };
+/**
+ * Formats bytes mostly like Windows does,
+ * but in some rare cases the result is different.
+ * Check the file with tests.
+ * @see format-size-win-like.test.js
+ * @param {number} bytes
+ * @return {string}
+ */
+export declare function formatSizeWinLike(bytes: number): string;
+/**
+ * @example
+ * 10.1005859375 -> "10.1"
+ * 9.99902343750 -> "9.99"
+ * 836.966796875 -> "836"
+ * 0.08   -> "0.08"
+ * 0.099  -> "0.09"
+ * 0.0099 -> "0"
+ * @param {number} number
+ * @return {string}
+ */
+export declare function toTruncPrecision3(number: number): string;
+/** @deprecated */
+export { formatNumber as tripleSizeGroups };
+/**
+ * Useful for file byte size formatting:
+ * 34456909 -> 34 456 909
+ * @param {number} num
+ * @return {string}
+ * */
+export declare function formatNumber(num: number): string;
+/**
+ * "Sun, 10 Jan 2021 22:22:22 GMT" -> "2021.01.10"
+ * @param {Date | string | number?} [dateValue]
+ * @param {boolean} [utc = true]
+ * @return {string}
+ */
+export declare function dateToDayDateString(dateValue?: Date | string | number, utc?: boolean): string;
+/**
+ * "Sun, 10 Jan 2021 22:22:22 GMT" -> "2021.01.10 22:22:22Z"
+ * @param {Date | string | number} [dateValue]
+ * @param {boolean?} [utc = true]
+ * @return {string}
+ */
+export declare function dateToDayDateTimeString(dateValue?: Date | string | number, utc?: boolean): string;
+/**
+ * "Sun, 10 Jan 2021 22:22:22 GMT" -> "2021.01.10 22:22:22"
+ * @param {Date | string | number} [dateValue]
+ * @return {string}
+ */
+export declare function localDate(dateValue?: number | string | Date): string;
+/**
+ * "Sun, 10 Jan 2021 22:22:22 GMT" -> "2021.01.10"
+ * @param {Date | string | number} [dateValue]
+ * @return {string}
+ */
+export declare function localDateTime(dateValue?: number | string | Date): string;
+/**
+ * Formats date. Supports: YY.YYYY.MM.DD HH:mm:SS.
+ * Default format: "YYYY.MM.DD".
+ * formatDate() -> "2022.01.07"
+ * @param {Date | string | number} [dateValue]
+ * @param {string}  [pattern = "YYYY.MM.DD"]
+ * @param {boolean} [utc = true]
+ * @return {string}
+ */
+export declare function formatDate(dateValue?: Date | string | number, pattern?: string, utc?: boolean): string;
+/** A classic `debounce` wrap function. */
+export declare function debounce<A extends any[]>(runnable: (...args: A) => unknown, ms?: number, scope?: any): (...args: A) => void;
+/** A classic `throttle` wrap function. */
+export declare function throttle<A extends any[]>(runnable: (...args: A) => any, time?: number, scope?: any): (...args: A) => void;
+/**
+ * Allows to run a function as a `throttled` one, run it without a delay (`runNow`), or `clear` the deferred callback.
+ *
+ * @example
+ * const {throttled, runNow, clear} = getThrottle(300, true);
+ *
+ * for (let i = 0; i < 100; i++) {
+ *     throttled(() => {
+ *         console.log(i);
+ *     });
+ *     await sleep(10);
+ * }
+ * runNow(); // run the last callback without delay
+ */
+export declare function getThrottle(ms?: number, runFirstImmediately?: boolean): {
+    throttled: (callback: Function, runNow?: boolean) => void;
+    runNow: (clearDelayed?: boolean) => any;
+    clear: () => void;
+};
+/**
+ * Sleeps `ms` milliseconds.
+ * If param is `undefined` it sleeps until the next macro-task.
+ * Note: With `0` real ms will be `4`+ ms.
+ * @param {number?} ms
+ * */
+export declare function sleep(ms?: number): Promise<void>;
+/**
+ * Interruptible `sleep`.
+ * If was interrupted resolves with the interrupt reason (`signal.reason`).
+ * @param {number} ms
+ * @param {AbortSignal} signal
+ */
+export declare function sleepEx(ms: number, signal: AbortSignal): Promise<void | any>;
+export declare function isString(value: unknown): value is string;
+export declare function isAnyString(value: unknown): value is (string | String);
+/**
+ * Java's `hashCode` like.
+ * @example
+ * hashString("Lorem Ipsum") === -488052133
+ * hashString("Qwerty") === -1862984904
+ * hashString("A") === 65
+ * hashString("👾👽💀") === -2019372252
+ * @param {string} str
+ * @return {number}
+ */
+export declare function hashString(str: string): number;
 ```
 
-```ts
-declare function formatSizeWinLike(bytes: number): string; // aka `bytesToSizeWinLike`
-```
+## *.d.ts (sync)
 
 ```ts
-declare class Semaphore {
-  constructor(max: number);
-  acquire(): Promise<void>;
-  release(): void;
+/**
+ * Use it when in one place you need to `enqueue()` some `value`, until `close()`.
+ * In other place you can iterate over this queue in for-await loop.
+ *
+ * `enqueue` does not add a value until there is a free space in the queue, you should `await` it.
+ * (`size` parameter of `constructor`).
+ *
+ * Use `close()` after you finished to `enqueue()` data.
+ */
+export declare class AsyncBufferQueue<T> {
+    private values;
+    private done;
+    private promise;
+    private resolve;
+    private semaphore;
+    constructor(size?: number);
+    close(): void;
+    enqueue(value: T): Promise<void>;
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
 }
-```
-
-```ts
-declare class CountLatch {
-  constructor(count?);
-  countDown(): void;
-  countUp(): void;
-  then(resolve: VoidFunc, reject: VoidFunc): Promise<void>
+export declare class CountLatch {
+    private count;
+    private promise;
+    private resolve;
+    /** @param {number} count = 0 */
+    constructor(count?: number);
+    countDown(): void;
+    countUp(): void;
+    /** Makes this object "Thenable" */
+    then(resolve: VoidFunc, reject: VoidFunc): Promise<void>;
 }
+export type Node<T> = {
+    value: T;
+    next: Node<T> | null;
+};
+/** "LinkedList" with `Array` interface */
+export declare class Queue<T> {
+    length: number;
+    private _last;
+    private _first;
+    constructor();
+    push(value: T): void;
+    shift(): T | undefined;
+}
+/** The most simple semaphore implementation. */
+export declare class Semaphore {
+    private readonly max;
+    private count;
+    private readonly resolveQueue;
+    /** @param {number} [max = 1] - by default, it works as a mutex. */
+    constructor(max?: number);
+    /** @return {Promise<unknown>} */
+    acquire(): Promise<unknown>;
+    /** @return {void} */
+    release(): void;
+}
+/** `resolve`/`reject` of `Promise` with no result. */
+export type VoidFunc = (value: void) => void;
 ```
@@ -40,0 +193,0 @@

No alert changes

Improved metrics

Total package byte prevSize

29779

increased by21.49%

Number of lines in readme file

253

increased by153%

No dependency changes