@augment-vir/common 31.25.0 → 31.26.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/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/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

@@ -84,7 +84,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

@@ -84,7 +84,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.26.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -40,8 +40,8 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.25.0",
-        "@augment-vir/core": "^31.25.0",
+        "@augment-vir/assert": "^31.26.0",
+        "@augment-vir/core": "^31.26.0",
         "@date-vir/duration": "^7.3.1",
         "ansi-styles": "^6.2.1",
         "deepcopy-esm": "^2.1.1",