@ndn/util - npm Package Compare versions

Comparing version 0.0.20240113 to 0.0.20240630

lib/closers_browser.js

@@ -1,11 +0,47 @@
-/** A list of objects that can be closed or destroyed. */
+import "./polyfill_browser.js";
+export var Closer;
+(function (Closer) {
+    /** Close or dispose an object. */
+    function close(c) {
+        for (const key of ["close", Symbol.dispose, Symbol.asyncDispose]) {
+            if (typeof c?.[key] === "function") {
+                return c[key]();
+            }
+        }
+    }
+    Closer.close = close;
+    /** Convert a closable object to AsyncDisposable. */
+    function asAsyncDisposable(c) {
+        if (typeof c[Symbol.asyncDispose] === "function") {
+            return c;
+        }
+        return {
+            async [Symbol.asyncDispose]() {
+                await close(c);
+            },
+        };
+    }
+    Closer.asAsyncDisposable = asAsyncDisposable;
+})(Closer || (Closer = {}));
+/** A list of objects that can be closed or disposed. */
 export class Closers extends Array {
-    /** Close all objects in reverse order and clear the list. */
+    /**
+     * Close all objects and clear the list.
+     *
+     * @remarks
+     * All objects added to this array are closed, in the reversed order as they appear in the array.
+     * This is a synchronous function, so that any AsyncDisposable objects in the array would have its
+     * asyncDispose method is called but not awaited.
+     * This array is cleared and can be reused.
+     */
     close = () => {
         for (let i = this.length - 1; i >= 0; --i) {
-            this[i].close();
+            void Closer.close(this[i]);
         }
         this.splice(0, Infinity);
     };
-    /** Schedule a timeout or interval to be canceled via .close(). */
+    [Symbol.dispose]() {
+        this.close();
+    }
+    /** Schedule a timeout or interval to be canceled upon close. */
     addTimeout(t) {
@@ -22,1 +58,13 @@ this.push({ close: () => clearTimeout(t) });
 }
+/**
+ * Acquire a semaphore for unlocking via Disposable.
+ * @param semaphore - Semaphore or Mutex from `wait-your-turn` package.
+ */
+export async function lock(semaphore) {
+    const release = await semaphore.acquire();
+    return {
+        [Symbol.dispose]() {
+            release();
+        },
+    };
+}

lib/closers_node.js

@@ -1,11 +0,47 @@
-/** A list of objects that can be closed or destroyed. */
+import "./polyfill_node.js";
+export var Closer;
+(function (Closer) {
+    /** Close or dispose an object. */
+    function close(c) {
+        for (const key of ["close", Symbol.dispose, Symbol.asyncDispose]) {
+            if (typeof c?.[key] === "function") {
+                return c[key]();
+            }
+        }
+    }
+    Closer.close = close;
+    /** Convert a closable object to AsyncDisposable. */
+    function asAsyncDisposable(c) {
+        if (typeof c[Symbol.asyncDispose] === "function") {
+            return c;
+        }
+        return {
+            async [Symbol.asyncDispose]() {
+                await close(c);
+            },
+        };
+    }
+    Closer.asAsyncDisposable = asAsyncDisposable;
+})(Closer || (Closer = {}));
+/** A list of objects that can be closed or disposed. */
 export class Closers extends Array {
-    /** Close all objects in reverse order and clear the list. */
+    /**
+     * Close all objects and clear the list.
+     *
+     * @remarks
+     * All objects added to this array are closed, in the reversed order as they appear in the array.
+     * This is a synchronous function, so that any AsyncDisposable objects in the array would have its
+     * asyncDispose method is called but not awaited.
+     * This array is cleared and can be reused.
+     */
     close = () => {
         for (let i = this.length - 1; i >= 0; --i) {
-            this[i].close();
+            void Closer.close(this[i]);
         }
         this.splice(0, Infinity);
     };
-    /** Schedule a timeout or interval to be canceled via .close(). */
+    [Symbol.dispose]() {
+        this.close();
+    }
+    /** Schedule a timeout or interval to be canceled upon close. */
     addTimeout(t) {
@@ -22,1 +58,13 @@ this.push({ close: () => clearTimeout(t) });
 }
+/**
+ * Acquire a semaphore for unlocking via Disposable.
+ * @param semaphore - Semaphore or Mutex from `wait-your-turn` package.
+ */
+export async function lock(semaphore) {
+    const release = await semaphore.acquire();
+    return {
+        [Symbol.dispose]() {
+            release();
+        },
+    };
+}

lib/closers.d.ts

@@ -1,10 +0,27 @@
-/// <reference types="node" />
+import "./polyfill_node.js";
+import type { Promisable } from "type-fest";
+import type { Semaphore } from "wait-your-turn";
 export interface Closer {
     close: () => void;
 }
-/** A list of objects that can be closed or destroyed. */
-export declare class Closers extends Array {
-    /** Close all objects in reverse order and clear the list. */
-    close: () => void;
-    /** Schedule a timeout or interval to be canceled via .close(). */
+export declare namespace Closer {
+    /** Close or dispose an object. */
+    function close(c: any): Promisable<void>;
+    /** Convert a closable object to AsyncDisposable. */
+    function asAsyncDisposable(c: Closer | Disposable | AsyncDisposable): AsyncDisposable;
+}
+/** A list of objects that can be closed or disposed. */
+export declare class Closers extends Array<Closer | Disposable | AsyncDisposable> implements Disposable {
+    /**
+     * Close all objects and clear the list.
+     *
+     * @remarks
+     * All objects added to this array are closed, in the reversed order as they appear in the array.
+     * This is a synchronous function, so that any AsyncDisposable objects in the array would have its
+     * asyncDispose method is called but not awaited.
+     * This array is cleared and can be reused.
+     */
+    readonly close: () => void;
+    [Symbol.dispose](): void;
+    /** Schedule a timeout or interval to be canceled upon close. */
     addTimeout<T extends NodeJS.Timeout | number>(t: T): T;
@@ -14,1 +31,6 @@ /** Wait for close. */
 }
+/**
+ * Acquire a semaphore for unlocking via Disposable.
+ * @param semaphore - Semaphore or Mutex from `wait-your-turn` package.
+ */
+export declare function lock(semaphore: Pick<Semaphore, "acquire">): Promise<Disposable>;

lib/crypto_browser.js

 import { crypto, timingSafeEqual as platformTimingSafeEqual } from "./platform_browser.js";
 /** Timing-safe equality comparison. */
 export function timingSafeEqual(a, b) {
-    if (a.byteLength !== b.byteLength) {
-        return false;
-    }
-    return platformTimingSafeEqual(a, b);
+    return a.byteLength === b.byteLength && platformTimingSafeEqual(a, b);
 }
-/** SHA256 digest. */
+/** Compute SHA256 digest. */
 export async function sha256(input) {
@@ -11,0 +8,0 @@ const digest = await crypto.subtle.digest("SHA-256", input);

lib/crypto_node.js

 import { crypto, timingSafeEqual as platformTimingSafeEqual } from "./platform_node.js";
 /** Timing-safe equality comparison. */
 export function timingSafeEqual(a, b) {
-    if (a.byteLength !== b.byteLength) {
-        return false;
-    }
-    return platformTimingSafeEqual(a, b);
+    return a.byteLength === b.byteLength && platformTimingSafeEqual(a, b);
 }
-/** SHA256 digest. */
+/** Compute SHA256 digest. */
 export async function sha256(input) {
@@ -11,0 +8,0 @@ const digest = await crypto.subtle.digest("SHA-256", input);

lib/crypto.d.ts

 /** Timing-safe equality comparison. */
 export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;
-/** SHA256 digest. */
+/** Compute SHA256 digest. */
 export declare function sha256(input: Uint8Array): Promise<Uint8Array>;

lib/event_browser.js

@@ -1,10 +0,10 @@
-import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
-export { CustomEvent } from "./platform_browser.js";
+import assert from "tiny-invariant";
 /**
  * Keep records on whether an event listener has been added.
- * This may allow EventTarget subclass to skip certain event generation code paths.
- * Tracking is imprecise: it does not consider 'once' and 'removeEventListener'.
- * @param target EventTarget to override.
- * @returns map from event type to whether listeners may exist.
+ * @param target - EventTarget to override.
+ * @returns Map from event type to whether listeners may exist.
+ *
+ * @remarks
+ * This may allow `EventTarget` subclass to skip certain event generation code paths.
+ * Tracking is imprecise: it does not consider `once()` and `removeEventListener()`.
  */
@@ -11,0 +11,0 @@ export function trackEventListener(target) {

lib/event_node.js

@@ -1,10 +0,10 @@
-import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
-export { CustomEvent } from "./platform_node.js";
+import assert from "tiny-invariant";
 /**
  * Keep records on whether an event listener has been added.
- * This may allow EventTarget subclass to skip certain event generation code paths.
- * Tracking is imprecise: it does not consider 'once' and 'removeEventListener'.
- * @param target EventTarget to override.
- * @returns map from event type to whether listeners may exist.
+ * @param target - EventTarget to override.
+ * @returns Map from event type to whether listeners may exist.
+ *
+ * @remarks
+ * This may allow `EventTarget` subclass to skip certain event generation code paths.
+ * Tracking is imprecise: it does not consider `once()` and `removeEventListener()`.
  */
@@ -11,0 +11,0 @@ export function trackEventListener(target) {

lib/event.d.ts

@@ -1,9 +0,10 @@
-export { CustomEvent } from "./platform_node.js";
 /**
  * Keep records on whether an event listener has been added.
- * This may allow EventTarget subclass to skip certain event generation code paths.
- * Tracking is imprecise: it does not consider 'once' and 'removeEventListener'.
- * @param target EventTarget to override.
- * @returns map from event type to whether listeners may exist.
+ * @param target - EventTarget to override.
+ * @returns Map from event type to whether listeners may exist.
+ *
+ * @remarks
+ * This may allow `EventTarget` subclass to skip certain event generation code paths.
+ * Tracking is imprecise: it does not consider `once()` and `removeEventListener()`.
  */
 export declare function trackEventListener(target: EventTarget): Record<string, boolean>;

lib/iter_browser.js

 import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
-/** Yield all values from an iterable but catch any error. */
+import _cjsDefaultImport0 from "event-iterator"; const EventIterator = __importDefault(_cjsDefaultImport0).default;
+import assert from "tiny-invariant";
+/**
+ * Create an iterable that you can push values into.
+ * @typeParam T - Value type.
+ * @returns AsyncIterable with push method.
+ *
+ * @remarks
+ * Inspired by {@link https://www.npmjs.com/package/it-pushable | it-pushable} but implemented on
+ * top of {@link https://www.npmjs.com/package/event-iterator | event-iterator} library.
+ */
+export function pushable() {
+    let q;
+    const ei = new EventIterator((queue) => { q = queue; }, { highWaterMark: Infinity });
+    const it = ei[Symbol.asyncIterator]();
+    assert(!!q);
+    return {
+        [Symbol.asyncIterator]: () => it,
+        push: q.push,
+        stop: q.stop,
+        fail: q.fail,
+    };
+}
+/**
+ * Yield all values from an iterable but catch any error.
+ * @param iterable - Input iterable.
+ * @param onError - Callback to receive errors thrown by the iterable.
+ * @returns Iterable that does not throw errors.
+ */
 export async function* safeIter(iterable, onError) {
@@ -13,4 +40,6 @@ try {
 /**
- * Map and flatten once.
- * This differs from flatMap in streaming-iterables, which recursively flattens the result.
+ * Perform flatMap on an (async) iterable, but flatten at most once.
+ * @remarks
+ * flatMap of streaming-iterables recursively flattens the result.
+ * This function flattens at most once.
  */
@@ -17,0 +46,0 @@ export async function* flatMapOnce(f, iterable) {

lib/iter_node.js

 import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
-/** Yield all values from an iterable but catch any error. */
+import _cjsDefaultImport0 from "event-iterator"; const EventIterator = __importDefault(_cjsDefaultImport0).default;
+import assert from "tiny-invariant";
+/**
+ * Create an iterable that you can push values into.
+ * @typeParam T - Value type.
+ * @returns AsyncIterable with push method.
+ *
+ * @remarks
+ * Inspired by {@link https://www.npmjs.com/package/it-pushable | it-pushable} but implemented on
+ * top of {@link https://www.npmjs.com/package/event-iterator | event-iterator} library.
+ */
+export function pushable() {
+    let q;
+    const ei = new EventIterator((queue) => { q = queue; }, { highWaterMark: Infinity });
+    const it = ei[Symbol.asyncIterator]();
+    assert(!!q);
+    return {
+        [Symbol.asyncIterator]: () => it,
+        push: q.push,
+        stop: q.stop,
+        fail: q.fail,
+    };
+}
+/**
+ * Yield all values from an iterable but catch any error.
+ * @param iterable - Input iterable.
+ * @param onError - Callback to receive errors thrown by the iterable.
+ * @returns Iterable that does not throw errors.
+ */
 export async function* safeIter(iterable, onError) {
@@ -13,4 +40,6 @@ try {
 /**
- * Map and flatten once.
- * This differs from flatMap in streaming-iterables, which recursively flattens the result.
+ * Perform flatMap on an (async) iterable, but flatten at most once.
+ * @remarks
+ * flatMap of streaming-iterables recursively flattens the result.
+ * This function flattens at most once.
  */
@@ -17,0 +46,0 @@ export async function* flatMapOnce(f, iterable) {

lib/iter.d.ts

 import type { AnyIterable } from "streaming-iterables";
-/** Yield all values from an iterable but catch any error. */
+/** An iterable that you can push values into. */
+export interface Pushable<T> extends AsyncIterable<T> {
+    /** Push a value. */
+    push: (value: T) => void;
+    /** End the iterable normally. */
+    stop: () => void;
+    /** End the iterable abnormally. */
+    fail: (err: Error) => void;
+}
+/**
+ * Create an iterable that you can push values into.
+ * @typeParam T - Value type.
+ * @returns AsyncIterable with push method.
+ *
+ * @remarks
+ * Inspired by {@link https://www.npmjs.com/package/it-pushable | it-pushable} but implemented on
+ * top of {@link https://www.npmjs.com/package/event-iterator | event-iterator} library.
+ */
+export declare function pushable<T>(): Pushable<T>;
+/**
+ * Yield all values from an iterable but catch any error.
+ * @param iterable - Input iterable.
+ * @param onError - Callback to receive errors thrown by the iterable.
+ * @returns Iterable that does not throw errors.
+ */
 export declare function safeIter<T>(iterable: AnyIterable<T>, onError?: (err?: unknown) => void): AsyncIterableIterator<T>;
 /**
- * Map and flatten once.
- * This differs from flatMap in streaming-iterables, which recursively flattens the result.
+ * Perform flatMap on an (async) iterable, but flatten at most once.
+ * @remarks
+ * flatMap of streaming-iterables recursively flattens the result.
+ * This function flattens at most once.
  */
@@ -8,0 +34,0 @@ export declare function flatMapOnce<T, R>(f: (item: T) => AnyIterable<R>, iterable: AnyIterable<T>): AsyncIterable<R>;

lib/key-map_browser.js

 /**
  * Map that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -13,3 +12,3 @@ export class KeyMap {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -40,7 +39,6 @@ constructor(keyOf) {
  * MultiMap that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -50,3 +48,3 @@ export class KeyMultiMap {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -89,3 +87,3 @@ constructor(keyOf) {
      * No-op if key-value does not exist.
-     * @returns count(key) after the operation.
+     * @returns `count(key)` after the operation.
      */
@@ -126,6 +124,5 @@ remove(key, value) {
  * MultiSet that transforms keys.
- *
- * K: input key type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -135,3 +132,3 @@ export class KeyMultiSet {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -153,3 +150,3 @@ constructor(keyOf) {
      * Add a key.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -165,3 +162,3 @@ add(key) {
      * No-op if key does not exist.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -168,0 +165,0 @@ remove(key) {

lib/key-map_node.js

 /**
  * Map that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -13,3 +12,3 @@ export class KeyMap {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -40,7 +39,6 @@ constructor(keyOf) {
  * MultiMap that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -50,3 +48,3 @@ export class KeyMultiMap {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -89,3 +87,3 @@ constructor(keyOf) {
      * No-op if key-value does not exist.
-     * @returns count(key) after the operation.
+     * @returns `count(key)` after the operation.
      */
@@ -126,6 +124,5 @@ remove(key, value) {
  * MultiSet that transforms keys.
- *
- * K: input key type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -135,3 +132,3 @@ export class KeyMultiSet {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -153,3 +150,3 @@ constructor(keyOf) {
      * Add a key.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -165,3 +162,3 @@ add(key) {
      * No-op if key does not exist.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -168,0 +165,0 @@ remove(key) {

lib/key-map.d.ts

 /**
  * Map that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
-export declare class KeyMap<K, V, I, L = K> {
+export declare class KeyMap<K, V, I, L = K> implements Iterable<[key: K, value: V]> {
     private readonly keyOf;
     /**
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -26,12 +25,11 @@ constructor(keyOf: (key: K | L) => I);
  * MultiMap that transforms keys.
- *
- * K: input key type.
- * V: value type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam V - Value type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
-export declare class KeyMultiMap<K, V, I, L = K> {
+export declare class KeyMultiMap<K, V, I, L = K> implements Iterable<[key: K, value: V]> {
     /**
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -58,3 +56,3 @@ constructor(keyOf: (key: K | L) => I);
      * No-op if key-value does not exist.
-     * @returns count(key) after the operation.
+     * @returns `count(key)` after the operation.
      */
@@ -73,6 +71,5 @@ remove(key: K | L, value: V): number;
  * MultiSet that transforms keys.
- *
- * K: input key type.
- * I: indexable key type.
- * L: lookup key type.
+ * @typeParam K - Input key type.
+ * @typeParam I - Indexable key type.
+ * @typeParam L - Lookup key type.
  */
@@ -82,3 +79,3 @@ export declare class KeyMultiSet<K, I, L = K> {
      * Constructor.
-     * @param keyOf function to transform input key to indexable key.
+     * @param keyOf - Function to transform input key to indexable key.
      */
@@ -96,3 +93,3 @@ constructor(keyOf: (key: K | L) => I);
      * Add a key.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -103,3 +100,3 @@ add(key: K): number;
      * No-op if key does not exist.
-     * @returns number of occurrences after the operation.
+     * @returns Number of occurrences after the operation.
      */
@@ -106,0 +103,0 @@ remove(key: K): number;

lib/mod_browser.js

@@ -1,3 +0,3 @@
-import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
+import "./polyfill_browser.js";
+import assert from "tiny-invariant";
 export { assert };
@@ -4,0 +4,0 @@ export { console, concatBuffers, crypto, delay } from "./platform_browser.js";

lib/mod_node.js

@@ -1,3 +0,3 @@
-import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
+import "./polyfill_node.js";
+import assert from "tiny-invariant";
 export { assert };
@@ -4,0 +4,0 @@ export { console, concatBuffers, crypto, delay } from "./platform_node.js";

lib/mod.d.ts

@@ -1,2 +0,3 @@
-import assert from "minimalistic-assert";
+import "./polyfill_node.js";
+import assert from "tiny-invariant";
 export { assert };
@@ -3,0 +4,0 @@ export { console, concatBuffers, crypto, delay } from "./platform_node.js";

lib/number.d.ts

@@ -1,6 +0,30 @@
-/** Error if n is not an integer within [0,MAX_SAFE_INTEGER] range. */
+/**
+ * Ensure n is an integer within `[0,MAX_SAFE_INTEGER]` range.
+ * @param n - Input number.
+ * @param typeName - Description of the number type.
+ *
+ * @throws RangeError
+ * Thrown if n is out of valid range.
+ */
 export declare function constrain(n: number, typeName: string): number;
-/** Error if n is not an integer within [0,max] range. */
+/**
+ * Ensure n is an integer within `[0,max]` range.
+ * @param n - Input number.
+ * @param typeName - Description of the number type.
+ * @param max - Maximum allowed value (inclusive).
+ *
+ * @throws RangeError
+ * Thrown if n is out of valid range.
+ */
 export declare function constrain(n: number, typeName: string, max: number): number;
-/** Error if n is not an integer within [min,max] range. */
+/**
+ * Ensure n is an integer within `[min,max]` range.
+ * @param n - Input number.
+ * @param typeName - Description of the number type.
+ * @param min - Minimum allowed value (inclusive).
+ * @param max - Maximum allowed value (inclusive).
+ *
+ * @throws RangeError
+ * Thrown if n is out of valid range.
+ */
 export declare function constrain(n: number, typeName: string, min: number, max: number): number;

lib/platform_browser.d.ts

 export declare function concatBuffers(list: readonly Uint8Array[], totalLength?: number): Uint8Array;
 export declare const console: Console;
 export declare const crypto: Crypto;
-export declare const CustomEvent: {
-    new <T>(type: string, eventInitDict?: CustomEventInit<T> | undefined): CustomEvent<T>;
-    prototype: CustomEvent<any>;
-};
 export declare function delay<T = void>(after: number, value?: T): Promise<T>;
 export declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;

lib/platform_browser.js

@@ -1,3 +0,2 @@
-import { __importDefault, __importStar } from "tslib";
-import _cjsDefaultImport0 from "minimalistic-assert"; const assert = __importDefault(_cjsDefaultImport0).default;
+import assert from "tiny-invariant";
 export function concatBuffers(list, totalLength) {
@@ -11,3 +10,3 @@ totalLength ??= list.reduce((l, { byteLength }) => l + byteLength, 0);
     }
-    assert.equal(offset, totalLength);
+    assert(offset === totalLength);
     return c;
@@ -27,3 +26,2 @@ }
 }
-export const CustomEvent = globalThis.CustomEvent;
 export function delay(after, value) {
@@ -30,0 +28,0 @@ return new Promise((resolve) => setTimeout(resolve, after, value));

lib/platform_node.d.ts

@@ -1,2 +0,1 @@
-/// <reference types="node" />
 import { timingSafeEqual } from "node:crypto";
@@ -10,5 +9,3 @@ export { timingSafeEqual };
 export declare const crypto: Crypto;
-/** CustomEvent object. */
-export declare const CustomEvent: typeof globalThis["CustomEvent"];
 /** Make a Promise that resolves after specified duration. */
 export declare const delay: <T = void>(after: number, value?: T) => Promise<T>;

lib/platform_node.js

@@ -13,12 +13,3 @@ import { Console } from "node:console";
 export const crypto = webcrypto;
-class CustomEventPonyfill extends Event {
-    constructor(type, options) {
-        super(type, options);
-        this.detail = options?.detail;
-    }
-    detail;
-}
-/** CustomEvent object. */
-export const CustomEvent = globalThis.CustomEvent ?? CustomEventPonyfill;
 /** Make a Promise that resolves after specified duration. */
 export const delay = setTimeoutPromise;

lib/string_browser.js

@@ -25,4 +25,7 @@ const INT2HEX = {};
  * Convert hexadecimal string to byte array.
+ * @param s - Input hexadecimal string (case insensitive).
  *
- * If the input is not a valid hexadecimal string, result will be incorrect.
+ * @remarks
+ * The input is expected to be valid hexadecimal string.
+ * If the input is invalid, the output would be wrong, but no error would be thrown.
  */
@@ -29,0 +32,0 @@ export function fromHex(s) {

lib/string_node.js

@@ -25,4 +25,7 @@ const INT2HEX = {};
  * Convert hexadecimal string to byte array.
+ * @param s - Input hexadecimal string (case insensitive).
  *
- * If the input is not a valid hexadecimal string, result will be incorrect.
+ * @remarks
+ * The input is expected to be valid hexadecimal string.
+ * If the input is invalid, the output would be wrong, but no error would be thrown.
  */
@@ -29,0 +32,0 @@ export function fromHex(s) {

lib/string.d.ts

@@ -9,4 +9,7 @@ /** Convert byte array to upper-case hexadecimal string. */
  * Convert hexadecimal string to byte array.
+ * @param s - Input hexadecimal string (case insensitive).
  *
- * If the input is not a valid hexadecimal string, result will be incorrect.
+ * @remarks
+ * The input is expected to be valid hexadecimal string.
+ * If the input is invalid, the output would be wrong, but no error would be thrown.
  */
@@ -13,0 +16,0 @@ export declare function fromHex(s: string): Uint8Array;

lib/timer_browser.js

 /**
  * Create a random jitter generator function.
- * @param r jitter factor around 1.
- * @param x median value.
- * @returns jitter generator function.
+ * @param r - Jitter factor around 1.
+ * @param x - Median value.
+ * @returns Jitter generator function.
  *
- * randomJitter(0.1, 2) generates random values within [1.8, 2.2].
+ * @remarks
+ * Each time the returned jitter generator function is called, it returns a number within
+ * `[x*(1-r), x*(1+r)]` range. For example, `randomJitter(0.1, 2)` creates a jitter generator
+ * function that returns random values within `[1.8, 2.2]` range.
  */
 export function randomJitter(r, x = 1) {
     r = Math.max(0, Math.min(r, 1));
+    if (r === 0) {
+        return () => x;
+    }
     const min = 1 - r;
@@ -12,0 +18,0 @@ const distance = 2 * r;

lib/timer_node.js

 /**
  * Create a random jitter generator function.
- * @param r jitter factor around 1.
- * @param x median value.
- * @returns jitter generator function.
+ * @param r - Jitter factor around 1.
+ * @param x - Median value.
+ * @returns Jitter generator function.
  *
- * randomJitter(0.1, 2) generates random values within [1.8, 2.2].
+ * @remarks
+ * Each time the returned jitter generator function is called, it returns a number within
+ * `[x*(1-r), x*(1+r)]` range. For example, `randomJitter(0.1, 2)` creates a jitter generator
+ * function that returns random values within `[1.8, 2.2]` range.
  */
 export function randomJitter(r, x = 1) {
     r = Math.max(0, Math.min(r, 1));
+    if (r === 0) {
+        return () => x;
+    }
     const min = 1 - r;
@@ -12,0 +18,0 @@ const distance = 2 * r;

lib/timer.d.ts

 /**
  * Create a random jitter generator function.
- * @param r jitter factor around 1.
- * @param x median value.
- * @returns jitter generator function.
+ * @param r - Jitter factor around 1.
+ * @param x - Median value.
+ * @returns Jitter generator function.
  *
- * randomJitter(0.1, 2) generates random values within [1.8, 2.2].
+ * @remarks
+ * Each time the returned jitter generator function is called, it returns a number within
+ * `[x*(1-r), x*(1+r)]` range. For example, `randomJitter(0.1, 2)` creates a jitter generator
+ * function that returns random values within `[1.8, 2.2]` range.
  */
 export declare function randomJitter(r: number, x?: number): () => number;

package.json

 {
   "name": "@ndn/util",
-  "version": "0.0.20240113",
+  "version": "0.0.20240630",
   "description": "NDNts: general utilities",
@@ -17,3 +17,5 @@ "keywords": [
   "module": "lib/mod_browser.js",
-  "sideEffects": false,
+  "sideEffects": [
+    "**/polyfill*"
+  ],
   "homepage": "https://yoursunny.com/p/NDNts/",
@@ -23,14 +25,17 @@ "repository": {
     "url": "https://github.com/yoursunny/NDNts.git",
-    "directory": "packages/util"
+    "directory": "pkg/util"
   },
   "dependencies": {
-    "@types/minimalistic-assert": "^1.0.3",
-    "minimalistic-assert": "^1.0.1",
+    "@shigen/polyfill-symbol-dispose": "^1.0.1",
+    "event-iterator": "^2.0.0",
     "streaming-iterables": "^8.0.1",
-    "tslib": "^2.6.2"
+    "tiny-invariant": "^1.3.3",
+    "tslib": "^2.6.3",
+    "type-fest": "^4.20.1",
+    "wait-your-turn": "^1.0.1"
   },
   "engines": {
-    "node": "^18.18.0 || ^20.0.0 || ^21.0.0"
+    "node": "^20.12.0 || ^22.0.0"
   },
   "types": "lib/mod.d.ts"
 }

No alert changes

Improved metrics

Total package byte prevSize

42885

increased by21.82%

Number of package files

44

increased by10%

Lines of code

1302

increased by20.67%

Worsened metrics

Dependency count

7

increased by75%

Dependency changes

• + Added@shigen/polyfill-symbol-dispose@^1.0.1

• + Addedevent-iterator@^2.0.0

• + Addedtiny-invariant@^1.3.3

• + Addedtype-fest@^4.20.1

• + Addedwait-your-turn@^1.0.1

• + Added@shigen/polyfill-symbol-dispose@1.0.1(transitive)

• + Addedevent-iterator@2.0.0(transitive)

• + Addedtiny-invariant@1.3.3(transitive)

• + Addedtype-fest@4.33.0(transitive)

• + Addedwait-your-turn@1.0.1(transitive)

• - Removed@types/minimalistic-assert@^1.0.3

• - Removedminimalistic-assert@^1.0.1

• - Removed@types/minimalistic-assert@1.0.3(transitive)

• - Removedminimalistic-assert@1.0.1(transitive)

• Updatedtslib@^2.6.3