@augment-vir/common 31.67.0 → 31.68.0

package/dist/augments/array/array-pagination.js

@@ -24,7 +24,9 @@
  * ```
  */
 export function getArrayPage(originalArray, options) {
-    const chunks = chunkArray(originalArray, { chunkSize: options.countPerPage });
+    const chunks = chunkArray(originalArray, {
+        chunkSize: options.countPerPage,
+    });
     return chunks[options.getPage];
 }
 /**

package/dist/augments/array/repeat-array.js

@@ -21,5 +21,7 @@
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function repeatArray(repeatCount, array) {
-    return Array.from({ length: repeatCount }, () => [...array]).flat();
+    return Array.from({
+        length: repeatCount,
+    }, () => [...array]).flat();
 }

package/dist/augments/array/shuffle-array.js

@@ -10,7 +10,10 @@ import { randomString } from '../random/random-string.js';
 export function shuffleArray(input) {
     return input
         .map((value) => {
-        return { value, sort: randomString() };
+        return {
+            value,
+            sort: randomString(),
+        };
     })
         .sort((a, b) => a.sort.localeCompare(b.sort))
         .map(({ value }) => value);

package/dist/augments/function/debounce.js

@@ -107,6 +107,9 @@ export class Debounce {
             }, this.debounceDuration.milliseconds);
         }
         this.nextCallTimestamp =
-            now + convertDuration(this.debounceDuration, { milliseconds: true }).milliseconds;
+            now +
+                convertDuration(this.debounceDuration, {
+                    milliseconds: true,
+                }).milliseconds;
     }
 }

package/dist/augments/function/execution-duration.js

@@ -25,7 +25,9 @@ export function measureExecutionDuration(callback) {
             try {
                 await result;
                 const endTime = Date.now();
-                resolve({ milliseconds: endTime - startTime });
+                resolve({
+                    milliseconds: endTime - startTime,
+                });
             }
             catch (caught) {
                 reject(ensureError(caught));

package/dist/augments/interval/blocking-interval.js

@@ -20,7 +20,9 @@ export function createBlockingInterval(callback, interval) {
         finally {
             isExecuting = false;
         }
-    }, convertDuration(interval, { milliseconds: true }).milliseconds);
+    }, convertDuration(interval, {
+        milliseconds: true,
+    }).milliseconds);
     return {
         intervalId,
         clearInterval() {

package/dist/augments/log/log-colors.js

@@ -117,7 +117,10 @@ export const defaultLogColorConfig = {
         colors: [logColors.normalWeight],
         logType: LogOutputType.Standard,
     },
-    [LogColorKey.Plain]: { colors: [], logType: LogOutputType.Standard },
+    [LogColorKey.Plain]: {
+        colors: [],
+        logType: LogOutputType.Standard,
+    },
     [LogColorKey.Reset]: {
         colors: [logColors.reset],
         logType: LogOutputType.Standard,

package/dist/augments/log/log-countdown.js

@@ -9,7 +9,9 @@ import { log } from './log.js';
  */
 export async function logCountdown(start, logCallback = log.warning) {
     logCallback(String(start));
-    await wait({ seconds: 1.5 });
+    await wait({
+        seconds: 1.5,
+    });
     if (start) {
         return await logCountdown(start - 1, logCallback);
     }

package/dist/augments/log/log-string.js

@@ -28,7 +28,10 @@ async function createToLogString() {
                         ? ''
                         : options.colorConfig[LogColorKey.Reset].colors.join(''),
                 ].join('');
-                return { text, css: undefined };
+                return {
+                    text,
+                    css: undefined,
+                };
             };
         },
         /**
@@ -60,7 +63,10 @@ async function createToLogString() {
                         ? ''
                         : options.colorConfig[LogColorKey.Reset].colors.join(''),
                 ].join('');
-                return { text, css };
+                return {
+                    text,
+                    css,
+                };
             };
         },
         /* node:coverage enable  */

package/dist/augments/log/log.js

@@ -24,11 +24,17 @@ isRuntimeEnv(RuntimeEnv.Node)
     : /* node:coverage enable  */
         {
             [LogOutputType.Error]({ text, css }) {
-                console.error(addPrefix({ value: text, prefix: '%c' }), css);
+                console.error(addPrefix({
+                    value: text,
+                    prefix: '%c',
+                }), css);
             },
             [LogOutputType.Standard]({ text, css }) {
                 // eslint-disable-next-line no-console
-                console.log(addPrefix({ value: text, prefix: '%c' }), css);
+                console.log(addPrefix({
+                    value: text,
+                    prefix: '%c',
+                }), css);
             },
         };
 /**
@@ -81,5 +87,8 @@ export function createArrayLogger(options) {
             logs.stdout.push(text);
         },
     }, options);
-    return { log, logs };
+    return {
+        log,
+        logs,
+    };
 }

package/dist/augments/number/truncate-number.js

@@ -158,10 +158,13 @@ export function truncateNumber(originalValue, { customSuffixes = defaultTruncati
     // handle edge cases
     if (isNaN(inputNumber) || inputNumber === Infinity) {
         return String(inputNumber);
+        // handle too big or too small edge cases
     }
-    // handle too big or too small edge cases
-    if (requiresScientificNotation(inputNumber)) {
-        return truncateScientificNotation({ input: inputNumber, maxLength });
+    else if (requiresScientificNotation(inputNumber)) {
+        return truncateScientificNotation({
+            input: inputNumber,
+            maxLength,
+        });
     }
     const numberAsString = String(inputNumber);
     const smallResult = handleSmallNumbers(numberAsString, maxLength);

package/dist/augments/object/constructor-instance-map.d.ts

@@ -0,0 +1,36 @@
+import { type AnyObject } from '@augment-vir/core';
+import { type AbstractConstructor, type Constructor } from 'type-fest';
+/**
+ * Map all ancestor constructors of an object to a set of objects.
+ *
+ * @category Internal
+ */
+export declare class ConstructorInstanceMap {
+    /**
+     * The top most constructor to allow in the map. If this constructor is ever reached, the
+     * recursive mapping stops.
+     */
+    protected readonly topMostConstructor?: Function | undefined;
+    /** A map of constructors to their added instances. */
+    readonly map: Map<Function, Set<AnyObject>>;
+    readonly isDestroyed: boolean;
+    constructor(
+    /**
+     * The top most constructor to allow in the map. If this constructor is ever reached, the
+     * recursive mapping stops.
+     */
+    topMostConstructor?: Function | undefined);
+    /**
+     * Add a new instance, mapping each of its ancestor constructors to it inside
+     * {@link ConstructorInstanceMap.map}.
+     */
+    add(instance: AnyObject): void;
+    /** Gets all added instances of the given constructor. */
+    getInstances<T>(constructor: AbstractConstructor<T> | Constructor<T>): Set<T>;
+    /** Remove an instance, removing it from all mappings inside {@link ConstructorInstanceMap.map}. */
+    remove(instance: AnyObject): void;
+    /** Recursively map all ancestor prototypes to the given instance. */
+    protected traverseConstructors(instance: AnyObject, prototype: any, operation: 'add' | 'remove'): void;
+    /** Clean up the internal map. */
+    destroy(): void;
+}

package/dist/augments/object/constructor-instance-map.js

@@ -0,0 +1,77 @@
+/* eslint-disable @typescript-eslint/no-unsafe-function-type */
+import { makeWritable } from '../type/writable.js';
+import { getOrSetFromMap } from './get-or-set.js';
+/**
+ * Map all ancestor constructors of an object to a set of objects.
+ *
+ * @category Internal
+ */
+export class ConstructorInstanceMap {
+    topMostConstructor;
+    /** A map of constructors to their added instances. */
+    map = new Map();
+    isDestroyed = false;
+    constructor(
+    /**
+     * The top most constructor to allow in the map. If this constructor is ever reached, the
+     * recursive mapping stops.
+     */
+    topMostConstructor) {
+        this.topMostConstructor = topMostConstructor;
+    }
+    /**
+     * Add a new instance, mapping each of its ancestor constructors to it inside
+     * {@link ConstructorInstanceMap.map}.
+     */
+    add(instance) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on destroyed ConstructorMap.');
+        }
+        this.traverseConstructors(instance, Object.getPrototypeOf(instance), 'add');
+    }
+    /** Gets all added instances of the given constructor. */
+    getInstances(constructor) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on destroyed ConstructorMap.');
+        }
+        return getOrSetFromMap(this.map, constructor, () => new Set());
+    }
+    /** Remove an instance, removing it from all mappings inside {@link ConstructorInstanceMap.map}. */
+    remove(instance) {
+        if (this.isDestroyed) {
+            throw new Error('Cannot operate on destroyed ConstructorMap.');
+        }
+        this.traverseConstructors(instance, Object.getPrototypeOf(instance), 'remove');
+    }
+    /** Recursively map all ancestor prototypes to the given instance. */
+    traverseConstructors(instance, prototype, operation) {
+        const constructor = prototype.constructor;
+        if (!constructor ||
+            constructor === Function ||
+            constructor === Object ||
+            constructor === this.topMostConstructor) {
+            /** Stop recursing into constructors. */
+            return;
+        }
+        if (operation === 'add') {
+            const set = getOrSetFromMap(this.map, constructor, () => new Set());
+            set.add(instance);
+        }
+        else {
+            const set = this.map.get(constructor);
+            if (set) {
+                set.delete(instance);
+            }
+        }
+        this.traverseConstructors(instance, Object.getPrototypeOf(prototype), operation);
+    }
+    /** Clean up the internal map. */
+    destroy() {
+        if (this.isDestroyed) {
+            return;
+        }
+        makeWritable(this).isDestroyed = true;
+        this.map.clear();
+        delete this.map;
+    }
+}

package/dist/augments/object/merge-deep.js

@@ -14,7 +14,7 @@ export function mergeDeep(...inputs) {
         // nothing to merge if no inputs
         return {};
     }
-    if (inputs.length === 1) {
+    else if (inputs.length === 1) {
         // nothing to merge if only one input
         return inputs[0];
     }
@@ -28,7 +28,9 @@ export function mergeDeep(...inputs) {
         }
         else if (!check.isObject(result)) {
             /** If result isn't an object then we need to make it into one. */
-            result = { ...individualInput };
+            result = {
+                ...individualInput,
+            };
         }
         Object.entries(individualInput).forEach(([key, value,]) => {
             if (!mergeProps[key]) {

package/dist/augments/object/merge-defined-properties.js

@@ -17,7 +17,9 @@ import { getObjectTypedEntries } from './object-entries.js';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function mergeDefinedProperties(original, ...overrides) {
-    const finalObject = { ...original };
+    const finalObject = {
+        ...original,
+    };
     overrides.forEach((entry) => {
         if (!entry) {
             return;

package/dist/augments/path/esm-path.js

@@ -23,7 +23,10 @@ import { removeSuffix } from '../string/suffix.js';
  */
 export function getEsmPath(importMeta) {
     const filePath = new URL('', importMeta.url).pathname;
-    const dirPath = removeSuffix({ value: new URL('.', importMeta.url).pathname, suffix: '/' });
+    const dirPath = removeSuffix({
+        value: new URL('.', importMeta.url).pathname,
+        suffix: '/',
+    });
     return {
         filePath,
         dirPath,

package/dist/augments/path/sanitize-path.js

@@ -1,5 +1,4 @@
 /* eslint-disable unicorn/prefer-code-point */
-/* eslint-disable sonarjs/no-control-regex */
 /* eslint-disable no-control-regex */
 import { getByteLength } from '../string/length.js';
 import { safeSplit } from '../string/split.js';
@@ -90,7 +89,6 @@ function truncate(string, byteLength) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         segment = string[i];
         if (isHighSurrogate(codePoint) && isLowSurrogate(string.charCodeAt(i + 1))) {
-            // eslint-disable-next-line sonarjs/updated-loop-counter
             i += 1;
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
             segment += string[i];

package/dist/augments/path/universal-path.js

@@ -23,7 +23,10 @@ export function replaceExtension({ newExtension, path, }) {
     return [
         dirname,
         basename,
-        addPrefix({ value: newExtension, prefix: '.' }),
+        addPrefix({
+            value: newExtension,
+            prefix: '.',
+        }),
         tail,
     ].join('');
 }
@@ -54,10 +57,12 @@ export function hasExtension(path) {
  * @category Package : @augment-vir/common
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-/* node:coverage ignore next 3: cannot test both on a single system. */
+/* node:coverage ignore next 5: cannot test both on a single system. */
 export const defaultSep = isRuntimeEnv(RuntimeEnv.Web)
     ? '/'
-    : await wrapInTry(async () => (await import('node:path')).sep, { fallbackValue: '/' });
+    : await wrapInTry(async () => (await import('node:path')).sep, {
+        fallbackValue: '/',
+    });
 /**
  * Extracts a path's extension, amongst other things, from the given path, without relying on
  * Node.js built-in packages (this works in a browser).

package/dist/augments/promise/promise-queue.js

@@ -99,10 +99,14 @@ export class PromiseQueue extends ListenTarget {
         this.currentlyAwaiting = item;
         item.original()
             .then((result) => {
-            this.handleItemSettle({ resolution: result });
+            this.handleItemSettle({
+                resolution: result,
+            });
         })
             .catch((error) => {
-            this.handleItemSettle({ rejection: error });
+            this.handleItemSettle({
+                rejection: error,
+            });
         });
         return true;
     }

package/dist/augments/promise/timed-promise.js

@@ -14,7 +14,9 @@ export class PromiseTimeoutError extends Error {
     constructor(duration, failureMessage) {
         super([
             failureMessage,
-            `Promised timed out after ${convertDuration(duration, { milliseconds: true }).milliseconds} ms.`,
+            `Promised timed out after ${convertDuration(duration, {
+                milliseconds: true,
+            }).milliseconds} ms.`,
         ]
             .filter(check.isTruthy)
             .join(': '));
@@ -33,7 +35,9 @@ export function wrapPromiseInTimeout(duration, originalPromise, failureMessage)
     const isInfinity = Object.values(duration).some((value) => value && check.isInfinite(value));
     const milliseconds = isInfinity
         ? Infinity
-        : convertDuration(duration, { milliseconds: true }).milliseconds;
+        : convertDuration(duration, {
+            milliseconds: true,
+        }).milliseconds;
     return new Promise(async (resolve, reject) => {
         const timeoutId = milliseconds === Infinity
             ? undefined

package/dist/augments/random/random-boolean.js

@@ -24,7 +24,10 @@ import { randomInteger } from './random-integer.js';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomBoolean(percentLikelyToBeTrue = 50) {
-    return (randomInteger({ min: 0, max: 99 }) <
+    return (randomInteger({
+        min: 0,
+        max: 99,
+    }) <
         clamp(Math.floor(percentLikelyToBeTrue), {
             min: 0,
             max: 100,

package/dist/augments/random/random-integer.js

@@ -10,7 +10,10 @@ import { ensureMinMax } from '@augment-vir/core';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomInteger({ min: rawMin, max: rawMax }) {
-    const { min, max } = ensureMinMax({ min: Math.floor(rawMin), max: Math.floor(rawMax) });
+    const { min, max } = ensureMinMax({
+        min: Math.floor(rawMin),
+        max: Math.floor(rawMax),
+    });
     const range = max - min + 1;
     const bitsNeeded = Math.ceil(Math.log2(range));
     const neededBytes = Math.ceil(bitsNeeded / 8);

package/dist/augments/string/casing/kebab-and-camel.js

@@ -40,8 +40,12 @@ export function camelCaseToKebabCase(rawCamelCase) {
         .reduce((accum, currentLetter, index, originalString) => {
         const previousLetter = index > 0 ? originalString[index - 1] || '' : '';
         const nextLetter = index < originalString.length - 1 ? originalString[index + 1] || '' : '';
-        const possibleWordBoundary = isCase(previousLetter, StringCase.Lower, { rejectNoCaseCharacters: true }) ||
-            isCase(nextLetter, StringCase.Lower, { rejectNoCaseCharacters: true });
+        const possibleWordBoundary = isCase(previousLetter, StringCase.Lower, {
+            rejectNoCaseCharacters: true,
+        }) ||
+            isCase(nextLetter, StringCase.Lower, {
+                rejectNoCaseCharacters: true,
+            });
         if (currentLetter === currentLetter.toLowerCase() ||
             index === 0 ||
             !possibleWordBoundary) {

package/dist/augments/string/split.js

@@ -24,7 +24,9 @@ export function splitIncludeSplit(original, splitDelimiter, { caseSensitive }) {
         caseSensitive,
         includeLength: true,
     });
-    const splitter = setRegExpCaseSensitivity(splitDelimiter, { caseSensitive });
+    const splitter = setRegExpCaseSensitivity(splitDelimiter, {
+        caseSensitive,
+    });
     const splits = original.split(splitter);
     return splits.reduce((accum, current, index) => {
         // this will be undefined on the last index

package/dist/augments/string/substring-index.js

@@ -9,7 +9,9 @@ import { addRegExpFlags, setRegExpCaseSensitivity } from '@augment-vir/core';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function findSubstringIndexes({ searchIn, searchFor, caseSensitive, includeLength, }) {
-    const searchRegExp = addRegExpFlags(setRegExpCaseSensitivity(searchFor, { caseSensitive }), 'g');
+    const searchRegExp = addRegExpFlags(setRegExpCaseSensitivity(searchFor, {
+        caseSensitive,
+    }), 'g');
     const indexes = [];
     const indexesAndLengths = [];
     searchIn.replace(searchRegExp, (...matchResults) => {
@@ -29,7 +31,10 @@ export function findSubstringIndexes({ searchIn, searchFor, caseSensitive, inclu
         if (typeof regExpMatch !== 'string') {
             throw new TypeError(`regExpMatch should've been a string but was ${typeof regExpMatch}!`);
         }
-        indexesAndLengths.push({ index: matchIndex, length: regExpMatch.length });
+        indexesAndLengths.push({
+            index: matchIndex,
+            length: regExpMatch.length,
+        });
         indexes.push(matchIndex);
         const originalMatch = matchResults[0];
         // this is used as a type safety catch and cannot actually be triggered on purpose

package/dist/augments/string/suffix.js

@@ -23,7 +23,10 @@ export const pxSuffix = 'px';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function addPx(input) {
-    return addSuffix({ value: input, suffix: pxSuffix });
+    return addSuffix({
+        value: input,
+        suffix: pxSuffix,
+    });
 }
 /**
  * Removes the `'px'` suffix from a string if it exists.
@@ -34,7 +37,10 @@ export function addPx(input) {
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function removePx(input) {
-    return toEnsuredNumber(removeSuffix({ value: input, suffix: pxSuffix }));
+    return toEnsuredNumber(removeSuffix({
+        value: input,
+        suffix: pxSuffix,
+    }));
 }
 /**
  * Adds the `'%'` suffix to a string if it does not already exist.
@@ -44,7 +50,10 @@ export function removePx(input) {
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function addPercent(input) {
-    return addSuffix({ value: input, suffix: percentSuffix });
+    return addSuffix({
+        value: input,
+        suffix: percentSuffix,
+    });
 }
 /**
  * Removes the `'%'` suffix from a string if it exists.
@@ -55,7 +64,10 @@ export function addPercent(input) {
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function removePercent(input) {
-    return toEnsuredNumber(removeSuffix({ value: input, suffix: percentSuffix }));
+    return toEnsuredNumber(removeSuffix({
+        value: input,
+        suffix: percentSuffix,
+    }));
 }
 /**
  * Adds a suffix to a string if it does not already exist.

package/dist/augments/string/wrap-string.js

@@ -16,5 +16,11 @@ import { addSuffix } from './suffix.js';
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function wrapString({ value, wrapper }) {
-    return addPrefix({ value: addSuffix({ value, suffix: wrapper }), prefix: wrapper });
+    return addPrefix({
+        value: addSuffix({
+            value,
+            suffix: wrapper,
+        }),
+        prefix: wrapper,
+    });
 }

package/dist/index.d.ts

@@ -45,6 +45,7 @@ export * from './augments/number/round.js';
 export * from './augments/number/scientific.js';
 export * from './augments/number/truncate-number.js';
 export * from './augments/number/wrap-number.js';
+export * from './augments/object/constructor-instance-map.js';
 export * from './augments/object/deep-copy.js';
 export * from './augments/object/deep-value.js';
 export * from './augments/object/diff.js';

package/dist/index.js

@@ -45,6 +45,7 @@ export * from './augments/number/round.js';
 export * from './augments/number/scientific.js';
 export * from './augments/number/truncate-number.js';
 export * from './augments/number/wrap-number.js';
+export * from './augments/object/constructor-instance-map.js';
 export * from './augments/object/deep-copy.js';
 export * from './augments/object/deep-value.js';
 export * from './augments/object/diff.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "31.67.0",
+    "version": "31.68.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -40,14 +40,14 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.67.0",
-        "@augment-vir/core": "^31.67.0",
-        "@date-vir/duration": "^8.1.1",
+        "@augment-vir/assert": "^31.68.0",
+        "@augment-vir/core": "^31.68.0",
+        "@date-vir/duration": "^8.2.0",
         "ansi-styles": "^6.2.3",
         "deepcopy-esm": "^2.1.1",
         "json5": "^2.2.3",
         "type-fest": "^5.4.4",
-        "typed-event-target": "^4.1.0"
+        "typed-event-target": "^4.2.0"
     },
     "devDependencies": {
         "@web/dev-server-esbuild": "^1.0.5",