@augment-vir/common 31.25.0 → 31.27.0

package/dist/augments/array/array-to-object.d.ts

@@ -1,16 +1,19 @@
 import { type MaybePromise } from '@augment-vir/core';
+import { type InverseBoolean } from '../type/boolean.js';
+import { type MakePartial } from '../type/partial.js';
 /**
  * Polyfill for `Object.groupBy`:
  * https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy
  *
  * @category Array
  * @category Object
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
- * import {arrayToObject} from '@augment-vir/common';
+ * import {groupArrayBy} from '@augment-vir/common';
  *
- * const result = arrayToObject(
+ * const result = groupArrayBy(
  *     [
  *         'a',
  *         'b',
@@ -19,17 +22,125 @@ import { type MaybePromise } from '@augment-vir/core';
  * );
  * // result is `{key-a: ['a'], key-b: ['b']}`
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function groupArrayBy<ElementType, NewKey extends PropertyKey, const UseRequired extends boolean | undefined = undefined>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => NewKey, options?: ArrayToObjectOptions<UseRequired>): MakePartial<Record<NewKey, ElementType[]>, InverseBoolean<UseRequired>>;
+/**
+ * Options for {@link groupArrayBy} and {@link arrayToObject}.
+ *
+ * @category Array
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function groupArrayBy<ElementType, NewKey extends PropertyKey>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => NewKey): Partial<Record<NewKey, ElementType[]>>;
-export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => Promise<{
+export type ArrayToObjectOptions<UseRequired extends boolean | undefined> = Partial<{
+    /**
+     * Set to `true` to make the object return type not use `Partial<>`.
+     *
+     * @default false
+     */
+    useRequired: UseRequired;
+}>;
+/**
+ * Similar to {@link groupArrayBy} but maps array entries to a single key and requires `key` _and_
+ * `value` outputs from the callback. The resulting object does not have an array of elements
+ * (unless the original array itself contains arrays). Automatically handles the case where the
+ * callback returns a promise.
+ *
+ * @category Array
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {arrayToObject} from '@augment-vir/common';
+ *
+ * const result = arrayToObject(
+ *     [
+ *         'a',
+ *         'b',
+ *     ],
+ *     (value) => {
+ *         return {key: `key-${value}`, value};
+ *     },
+ * );
+ * // result is `{key-a: 'a', key-b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue, const UseRequired extends boolean | undefined = undefined>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => Promise<{
     key: NewKey;
     value: NewValue;
-} | undefined>): Promise<Partial<Record<NewKey, NewValue>>>;
-export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => {
+} | undefined>, 
+/** Optional. */
+options?: ArrayToObjectOptions<UseRequired>): Promise<MakePartial<Record<NewKey, NewValue>, InverseBoolean<UseRequired>>>;
+/**
+ * Similar to {@link groupArrayBy} but maps array entries to a single key and requires `key` _and_
+ * `value` outputs from the callback. The resulting object does not have an array of elements
+ * (unless the original array itself contains arrays). Automatically handles the case where the
+ * callback returns a promise.
+ *
+ * @category Array
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {arrayToObject} from '@augment-vir/common';
+ *
+ * const result = arrayToObject(
+ *     [
+ *         'a',
+ *         'b',
+ *     ],
+ *     (value) => {
+ *         return {key: `key-${value}`, value};
+ *     },
+ * );
+ * // result is `{key-a: 'a', key-b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue, const UseRequired extends boolean | undefined = undefined>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => {
     key: NewKey;
     value: NewValue;
-} | undefined): Partial<Record<NewKey, NewValue>>;
-export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => MaybePromise<{
+} | undefined, 
+/** Optional. */
+options?: ArrayToObjectOptions<UseRequired>): MakePartial<Record<NewKey, NewValue>, InverseBoolean<UseRequired>>;
+/**
+ * Similar to {@link groupArrayBy} but maps array entries to a single key and requires `key` _and_
+ * `value` outputs from the callback. The resulting object does not have an array of elements
+ * (unless the original array itself contains arrays). Automatically handles the case where the
+ * callback returns a promise.
+ *
+ * @category Array
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {arrayToObject} from '@augment-vir/common';
+ *
+ * const result = arrayToObject(
+ *     [
+ *         'a',
+ *         'b',
+ *     ],
+ *     (value) => {
+ *         return {key: `key-${value}`, value};
+ *     },
+ * );
+ * // result is `{key-a: 'a', key-b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function arrayToObject<ElementType, NewKey extends PropertyKey, NewValue, const UseRequired extends boolean | undefined = undefined>(inputArray: ReadonlyArray<ElementType>, callback: (value: ElementType, index: number, originalArray: ReadonlyArray<ElementType>) => MaybePromise<{
     key: NewKey;
     value: NewValue;
-} | undefined>): MaybePromise<Partial<Record<NewKey, NewValue>>>;
+} | undefined>, 
+/** Optional. */
+options?: ArrayToObjectOptions<UseRequired>): MaybePromise<MakePartial<Record<NewKey, NewValue>, InverseBoolean<UseRequired>>>;

package/dist/augments/array/array-to-object.js

@@ -9,12 +9,13 @@ import { filterMap } from './filter.js';
  *
  * @category Array
  * @category Object
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
- * import {arrayToObject} from '@augment-vir/common';
+ * import {groupArrayBy} from '@augment-vir/common';
  *
- * const result = arrayToObject(
+ * const result = groupArrayBy(
  *     [
  *         'a',
  *         'b',
@@ -23,8 +24,12 @@ import { filterMap } from './filter.js';
  * );
  * // result is `{key-a: ['a'], key-b: ['b']}`
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export function groupArrayBy(inputArray, callback) {
+export function groupArrayBy(inputArray, callback, 
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+options = {}) {
     return inputArray.reduce((accum, entry, index, originalArray) => {
         const key = callback(entry, index, originalArray);
         const entryArray = getOrSet(accum, key, () => []);
@@ -60,7 +65,10 @@ export function groupArrayBy(inputArray, callback) {
  *
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export function arrayToObject(inputArray, callback) {
+export function arrayToObject(inputArray, callback, 
+/** Optional. */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+options = {}) {
     try {
         let gotAPromise = false;
         const mappedEntries = inputArray

package/dist/augments/array/extract-duplicates.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Finds all duplicates.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {extractDuplicates} from '@augment-vir/common';
+ *
+ * const result = extractDuplicates([
+ *     'a',
+ *     'b',
+ *     '',
+ *     'a',
+ * ]);
+ * // result is `{duplicates: ['a'], uniques: ['b', '']}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function extractDuplicates<T>(items: ReadonlyArray<T>, comparator?: (a: T, b: T) => boolean): {
+    duplicates: T[];
+    uniques: T[];
+};

package/dist/augments/array/extract-duplicates.js

@@ -0,0 +1,43 @@
+import { check } from '@augment-vir/assert';
+/**
+ * Finds all duplicates.
+ *
+ * @category Array
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {extractDuplicates} from '@augment-vir/common';
+ *
+ * const result = extractDuplicates([
+ *     'a',
+ *     'b',
+ *     '',
+ *     'a',
+ * ]);
+ * // result is `{duplicates: ['a'], uniques: ['b', '']}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function extractDuplicates(items, comparator = check.strictEquals) {
+    const duplicates = [];
+    const uniques = [];
+    items.forEach((item) => {
+        const duplicatesIndex = duplicates.findIndex((duplicateEntry) => comparator(duplicateEntry, item));
+        if (duplicatesIndex < 0) {
+            const uniquesIndex = uniques.findIndex((uniqueEntry) => comparator(uniqueEntry, item));
+            if (uniquesIndex < 0) {
+                uniques.push(item);
+            }
+            else {
+                uniques.splice(uniquesIndex, 1);
+                duplicates.push(item);
+            }
+        }
+    });
+    return {
+        duplicates,
+        uniques,
+    };
+}

package/dist/augments/object/object-sort.d.ts

@@ -1,2 +1,9 @@
 import { type AnyObject } from '@augment-vir/core';
-export declare function sortObject<const T extends AnyObject>(original: T): T;
+/**
+ * Creates as new sorted object copied from the the original given object.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function sortObject<const T extends AnyObject>(original: Readonly<T>): T;

package/dist/augments/object/object-sort.js

@@ -1,3 +1,10 @@
+/**
+ * Creates as new sorted object copied from the the original given object.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function sortObject(original) {
     return Object.fromEntries(Object.entries(original).sort((a, b) => a[0].localeCompare(b[0])));
 }

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

@@ -30,7 +30,10 @@ export class PromiseTimeoutError extends Error {
  * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function wrapPromiseInTimeout(duration, originalPromise, failureMessage) {
-    const milliseconds = convertDuration(duration, { milliseconds: true }).milliseconds;
+    const isInfinity = Object.values(duration).some((value) => value && check.isInfinite(value));
+    const milliseconds = isInfinity
+        ? Infinity
+        : convertDuration(duration, { milliseconds: true }).milliseconds;
     return new Promise(async (resolve, reject) => {
         const timeoutId = milliseconds === Infinity
             ? undefined

package/dist/augments/type/boolean.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Reverses a boolean (optionally `undefined`). `true` becomes `false`. `false` and `undefined`
+ * become `true`.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type InverseBoolean<Input extends boolean | undefined> = Input extends true ? false : true;

package/dist/augments/type/boolean.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/type/partial.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sets `T` as partial if `ShouldBePartial` is `true`. Otherwise, `T` is left alone.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type MakePartial<T extends object, ShouldBePartial extends boolean> = ShouldBePartial extends true ? Partial<T> : T;

package/dist/augments/type/partial.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './augments/array/awaited/awaited-filter.js';
 export * from './augments/array/awaited/awaited-for-each.js';
 export * from './augments/array/awaited/awaited-map.js';
 export * from './augments/array/create-array.js';
+export * from './augments/array/extract-duplicates.js';
 export * from './augments/array/filter.js';
 export * from './augments/array/remove-duplicates.js';
 export * from './augments/array/repeat-array.js';
@@ -84,7 +85,9 @@ export * from './augments/string/substring-index.js';
 export * from './augments/string/suffix.js';
 export * from './augments/string/white-space.js';
 export * from './augments/string/wrap-string.js';
+export * from './augments/type/boolean.js';
 export * from './augments/type/ensure-type.js';
+export * from './augments/type/partial.js';
 export * from './augments/type/readonly.js';
 export * from './augments/type/type-recursion.js';
 export * from './augments/type/union.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './augments/array/awaited/awaited-filter.js';
 export * from './augments/array/awaited/awaited-for-each.js';
 export * from './augments/array/awaited/awaited-map.js';
 export * from './augments/array/create-array.js';
+export * from './augments/array/extract-duplicates.js';
 export * from './augments/array/filter.js';
 export * from './augments/array/remove-duplicates.js';
 export * from './augments/array/repeat-array.js';
@@ -84,7 +85,9 @@ export * from './augments/string/substring-index.js';
 export * from './augments/string/suffix.js';
 export * from './augments/string/white-space.js';
 export * from './augments/string/wrap-string.js';
+export * from './augments/type/boolean.js';
 export * from './augments/type/ensure-type.js';
+export * from './augments/type/partial.js';
 export * from './augments/type/readonly.js';
 export * from './augments/type/type-recursion.js';
 export * from './augments/type/union.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "31.25.0",
+    "version": "31.27.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -40,9 +40,9 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.25.0",
-        "@augment-vir/core": "^31.25.0",
-        "@date-vir/duration": "^7.3.1",
+        "@augment-vir/assert": "^31.27.0",
+        "@augment-vir/core": "^31.27.0",
+        "@date-vir/duration": "^7.3.2",
         "ansi-styles": "^6.2.1",
         "deepcopy-esm": "^2.1.1",
         "json5": "^2.2.3",
@@ -55,7 +55,7 @@
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.1",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "concurrently": "^9.1.2",
+        "concurrently": "^9.2.0",
         "execute-in-browser": "^1.0.7",
         "istanbul-smart-text-reporter": "^1.1.5",
         "typescript": "^5.8.3"