@augment-vir/common/dist/augments/array/array-to-object.d.ts

A collection of augments, helpers types, functions, and classes for any JavaScript environment.

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 {groupArrayBy} from '@augment-vir/common';
 *
 * const result = groupArrayBy(
 *     [
 *         'a',
 *         'b',
 *     ],
 *     (value) => `key-${value}`,
 * );
 * // 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 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>, 
/** 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, 
/** 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>, 
/** Optional. */
options?: ArrayToObjectOptions<UseRequired>): MaybePromise<MakePartial<Record<NewKey, NewValue>, InverseBoolean<UseRequired>>>;