@augment-vir/common 30.0.0 → 30.0.2

package/dist/augments/object/diff.d.ts

@@ -2,21 +2,39 @@ import { PartialDeep } from 'type-fest';
 /**
  * Extract all nested object keys and values that are different between the two given objects.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function diffObjects<T0 extends Readonly<Record<PropertyKey, unknown>>, T1 extends Readonly<Record<PropertyKey, unknown>>>(object0: T0, object1: T1): [PartialDeep<T0>, PartialDeep<T1>] | [];
 /**
  * Extract all entries in the given arrays that are not equal.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function diffArrays<T0, T1>(array0: ReadonlyArray<T0>, array1: ReadonlyArray<T1>): [Array<T0>, Array<T1>] | [];
-/** Callback for checking equality between two values that can be of different types. */
+/**
+ * Callback for checking equality between two values that can be of different types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type AreEqualCallback<T0, T1> = (value0: T0, value1: T1) => boolean;
 /**
  * Simple diff check that is useful simply to return the same format as the other diff functions.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function diffBasic<T0, T1>(value0: T0, value1: T1, 
 /** A custom equality checker. Defaults to a strict equality check (`===`). */
@@ -24,6 +42,10 @@ areEqual?: AreEqualCallback<T0, T1>): [T0, T1] | [];
 /**
  * Diff any values. For diffing objects, use `diffObjects` to get better types.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function diffValues<T0, T1>(value0: T0, value1: T1): [T0, T1] | [];

package/dist/augments/object/diff.js

@@ -3,7 +3,11 @@ import { getObjectTypedKeys } from '@augment-vir/core';
 /**
  * Extract all nested object keys and values that are different between the two given objects.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function diffObjects(object0, object1) {
     const allObjectKeys = Array.from(new Set([
@@ -42,7 +46,11 @@ export function diffObjects(object0, object1) {
 /**
  * Extract all entries in the given arrays that are not equal.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function diffArrays(array0, array1) {
     const allArrayIndexes = Array.from(new Set([
@@ -78,7 +86,11 @@ export function diffArrays(array0, array1) {
 /**
  * Simple diff check that is useful simply to return the same format as the other diff functions.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function diffBasic(value0, value1, 
 /** A custom equality checker. Defaults to a strict equality check (`===`). */
@@ -117,7 +129,11 @@ const orderedValueDiffs = [
 /**
  * Diff any values. For diffing objects, use `diffObjects` to get better types.
  *
- * @returns An empty tuple if the values are equal.
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @returns An empty tuple if the values are equal. Otherwise, the first tuple entry contains the
+ *   changes in the first value, second entry contains the changes in the second value.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function diffValues(value0, value1) {
     let diffOutput = undefined;

package/dist/augments/object/empty.d.ts

@@ -1,3 +1,9 @@
 import { IsEmptyObject } from 'type-fest';
-/** Excludes empty objects from a union. */
+/**
+ * Excludes empty objects from a union.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type ExcludeEmpty<T> = IsEmptyObject<T> extends true ? never : T;

package/dist/augments/object/get-or-set.d.ts

@@ -1,31 +1,10 @@
 import { MaybePromise, type AnyObject } from '@augment-vir/core';
-/**
- * Get a value from a map or call the callback and return its result and store the result in the
- * map.
- *
- * @category Object:Common
- */
-export declare function getOrSetFromMap<MapKey extends object, MapValue>(map: WeakMap<MapKey, MapValue>, key: MapKey, createNewValueCallback: () => MapValue): MapValue;
-export declare function getOrSetFromMap<MapKey, MapValue>(map: Map<MapKey, MapValue>, key: MapKey, createNewValueCallback: () => MapValue): MapValue;
-/**
- * Given an object, tries to get the given key in that object. If the key is not in that object,
- * then the given `createCallback` is used to create a new value which is then stored in the given
- * object and returned. Automatically handles `createCallback` returning a promise, if it does.
- *
- * @category Object:Common
- * @example
- *
- * ```ts
- * // instead of doing this
- * if (!myObject[myKey]) {
- *     myObject[myKey] = {};
- * }
- * myObject[myKey]![nextKey] = 'some value';
- *
- * // do this
- * getOrSetInObject(myObject, myKey, () => {});
- * ```
- */
+export declare function getOrSetFromMap<MapKey extends object, MapValue>(map: WeakMap<MapKey, MapValue>, key: MapKey, createCallback: () => MapValue): MapValue;
+export declare function getOrSetFromMap<MapKey, MapValue>(map: Map<MapKey, MapValue>, key: MapKey, createCallback: () => MapValue): MapValue;
+export declare function getOrSetFromMap<MapKey extends object, MapValue>(map: WeakMap<MapKey, MapValue>, key: MapKey, createCallback: () => Promise<MapValue>): Promise<MapValue>;
+export declare function getOrSetFromMap<MapKey, MapValue>(map: Map<MapKey, MapValue>, key: MapKey, createCallback: () => Promise<MapValue>): Promise<MapValue>;
+export declare function getOrSetFromMap<MapKey extends object, MapValue>(map: WeakMap<MapKey, MapValue>, key: MapKey, createCallback: () => MaybePromise<MapValue>): MaybePromise<MapValue>;
+export declare function getOrSetFromMap<MapKey, MapValue>(map: Map<MapKey, MapValue>, key: MapKey, createCallback: () => MaybePromise<MapValue>): MaybePromise<MapValue>;
 export declare function getOrSet<OriginalObject extends AnyObject, Key extends keyof OriginalObject>(originalObject: OriginalObject, key: Key, createCallback: () => OriginalObject[Key]): Required<OriginalObject>[Key];
 export declare function getOrSet<OriginalObject extends AnyObject, Key extends keyof OriginalObject>(originalObject: OriginalObject, key: Key, createCallback: () => Promise<OriginalObject[Key]>): Promise<Required<OriginalObject>[Key]>;
 export declare function getOrSet<OriginalObject extends AnyObject, Key extends keyof OriginalObject>(originalObject: OriginalObject, key: Key, createCallback: () => MaybePromise<OriginalObject[Key]>): MaybePromise<Required<OriginalObject>[Key]>;

package/dist/augments/object/get-or-set.js

@@ -1,17 +1,79 @@
 import { check } from '@augment-vir/assert';
 import { ensureError } from '@augment-vir/core';
-export function getOrSetFromMap(map, key, createNewValueCallback) {
+/**
+ * Given an map, tries to get the given key in that map. If the key is not in that map, then the
+ * given `createCallback` is used to create a new value which is then stored in the given map and
+ * returned. Automatically handles an async `createCallback`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * // instead of doing this
+ * if (!myMap.get(myKey)) {
+ *     myMap.set(myKey, {});
+ * }
+ * myMap.get(myKey)![nextKey] = 'some value';
+ *
+ * // do this
+ * getOrSetInObject(myMap, myKey, () => {
+ *     return {};
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function getOrSetFromMap(map, key, createCallback) {
     const mapKey = key;
     if (map.has(mapKey)) {
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         return map.get(mapKey);
     }
     else {
-        const newValue = createNewValueCallback();
-        map.set(mapKey, newValue);
-        return newValue;
+        const createdValue = createCallback();
+        if (check.isPromise(createdValue)) {
+            return new Promise(async (resolve, reject) => {
+                try {
+                    const awaitedValue = await createdValue;
+                    map.set(mapKey, awaitedValue);
+                    resolve(awaitedValue);
+                }
+                catch (error) {
+                    reject(ensureError(error));
+                }
+            });
+        }
+        else {
+            map.set(mapKey, createdValue);
+            return createdValue;
+        }
     }
 }
+/**
+ * Given an object, tries to get the given key in that object. If the key is not in that object,
+ * then the given `createCallback` is used to create a new value which is then stored in the given
+ * object and returned. Automatically handles an async `createCallback`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * // instead of doing this
+ * if (!myObject[myKey]) {
+ *     myObject[myKey] = {};
+ * }
+ * myObject[myKey]![nextKey] = 'some value';
+ *
+ * // do this
+ * getOrSetInObject(myObject, myKey, () => {
+ *     return {};
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getOrSet(originalObject, key, createCallback) {
     if (key in originalObject) {
         return originalObject[key];

package/dist/augments/object/key-count.d.ts

@@ -2,6 +2,10 @@ import type { AnyObject } from '@augment-vir/core';
 /**
  * Counts the number of unique keys in an object type. Note that a key of just `string` will count
  * as 1.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type KeyCount<T extends AnyObject> = UnionToTuple<keyof T>['length'];
 /**

package/dist/augments/object/map-entries.js

@@ -2,6 +2,29 @@ import { check } from '@augment-vir/assert';
 import { ensureError } from '@augment-vir/core';
 import { filterMap } from '../array/filter.js';
 import { getObjectTypedEntries, typedObjectFromEntries } from './object-entries.js';
+/**
+ * Maps an object. The callback must return a key and value.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mapObject} from '@augment-vir/common';
+ *
+ * mapObject({a: 1, b: 2}, (key, value) => {
+ *     return {
+ *         key: `key-${key}`,
+ *         value: `value-${value}`,
+ *     };
+ * });
+ * // output is `{'key-a': 'value-1', 'key-b': 'value-2'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ * @see
+ * - {@link mapObjectValues}: the variant that only maps values.
+ */
 export function mapObject(originalObject, mapCallback) {
     try {
         let gotAPromise = false;

package/dist/augments/object/map-enum.d.ts

@@ -1,4 +1,11 @@
 import type { EnumBaseType, MaybePromise, Values } from '@augment-vir/core';
+/**
+ * Creates an object that maps all values of an enum to the provided `Values` type.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type EnumMap<Enum extends EnumBaseType, Value> = Values<Enum> extends PropertyKey ? Record<Values<Enum>, Value> : 'ERROR: invalid enum';
 export declare function mapEnumToObject<const Enum extends EnumBaseType, const Value>(enumInput: Enum, callback: (enumValue: Values<Enum>) => Promise<Value>): Promise<EnumMap<Enum, Value>>;
 export declare function mapEnumToObject<const Enum extends EnumBaseType, const Value>(enumInput: Enum, callback: (enumValue: Values<Enum>, wholeEnum: Enum) => Value): Value extends Promise<any> ? Promise<any> extends Value ? Promise<EnumMap<Enum, Awaited<Value>>> : MaybePromise<EnumMap<Enum, Awaited<Value>>> : EnumMap<Enum, Value>;

package/dist/augments/object/map-enum.js

@@ -1,4 +1,28 @@
 import { mapObject } from './map-entries.js';
+/**
+ * Maps all values of an enum as keys in an object where each value is the callback's output for
+ * that key.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mapEnumToObject} from '@augment-vir/common';
+ *
+ * enum MyEnum {
+ *     A = 'a',
+ *     B = 'b',
+ * }
+ *
+ * mapEnumToObject(MyEnum, (enumValue) => {
+ *     return `value-${enumValue}`;
+ * });
+ * // output is `{[MyEnum.A]: 'value-a', [MyEnum.B]: 'value-b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function mapEnumToObject(enumInput, callback) {
     return mapObject(enumInput, (enumKey, enumValue) => {
         const key = enumValue;

package/dist/augments/object/map-values.d.ts

@@ -1,23 +1,35 @@
-import { type Values } from '@augment-vir/core';
-export type InnerMappedValues<EntireInputGeneric extends object, MappedValueGeneric> = {
+type InnerMappedValues<EntireInputGeneric extends object, MappedValueGeneric> = {
     [MappedProp in keyof EntireInputGeneric]: MappedValueGeneric;
 };
-export type MappedValues<EntireInputGeneric extends object, MappedValueGeneric> = MappedValueGeneric extends PromiseLike<unknown> ? Promise<InnerMappedValues<EntireInputGeneric, Awaited<MappedValueGeneric>>> : InnerMappedValues<EntireInputGeneric, Awaited<MappedValueGeneric>>;
+type MappedValues<EntireInputGeneric extends object, MappedValueGeneric> = MappedValueGeneric extends PromiseLike<unknown> ? Promise<InnerMappedValues<EntireInputGeneric, Awaited<MappedValueGeneric>>> : InnerMappedValues<EntireInputGeneric, Awaited<MappedValueGeneric>>;
 /**
- * Map an object's keys to new values synchronously. This is different from plain mapObjectValues in
- * that this will not wrap the return value in a promise if any of the new object values are
- * promises. This function also requires currying in order to get the types correct. This allows you
- * to explicitly state the return type.
+ * Creates a new object with the same keys as the input object, but with values set to the result of
+ * `mapCallback` for each property. This is the same as {@link mapObjectValues} except that this
+ * preserves Promise values: it doesn't wrap them all in a single promise.
  *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function mapObjectValuesSync<EntireInputGeneric extends object, MappedValueGeneric>(inputObject: EntireInputGeneric, mapCallback: (inputKey: keyof EntireInputGeneric, keyValue: Required<EntireInputGeneric>[typeof inputKey], fullObject: EntireInputGeneric) => MappedValueGeneric): InnerMappedValues<EntireInputGeneric, MappedValueGeneric>;
+/**
+ * Creates a new object with the same keys as the input object, but with values set to the result of
+ * `mapCallback` for each property. Automatically handles an async `mapCallback`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
- * mapObjectValuesSync({objectToIterateOver: 'initial value'})(callback);
+ * import {mapObjectValues} from '@augment-vir/common';
+ *
+ * mapObjectValues({a: 1, b: 2}, (key, value) => {
+ *     return `key-${key} value-${value}`;
+ * });
+ * // output is `{a: 'key-a value-1', b: 'key-b value-2'}`
  * ```
- */
-export declare function mapObjectValuesSync<EntireInputGeneric extends object>(inputObject: EntireInputGeneric): <OutputObjectGeneric extends object>(mapCallback: (inputKey: keyof EntireInputGeneric, keyValue: Required<EntireInputGeneric>[typeof inputKey], fullObject: EntireInputGeneric) => never extends Values<OutputObjectGeneric> ? any : Values<OutputObjectGeneric>) => OutputObjectGeneric;
-/**
- * Creates a new object with the same properties as the input object, but with values set to the
- * result of mapCallback for each property.
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function mapObjectValues<EntireInputGeneric extends object, MappedValueGeneric>(inputObject: EntireInputGeneric, mapCallback: (inputKey: keyof EntireInputGeneric, keyValue: Required<EntireInputGeneric>[typeof inputKey], fullObject: EntireInputGeneric) => MappedValueGeneric): MappedValues<EntireInputGeneric, MappedValueGeneric>;
+export {};

package/dist/augments/object/map-values.js

@@ -1,31 +1,39 @@
 import { ensureError, getObjectTypedKeys } from '@augment-vir/core';
 /**
- * Map an object's keys to new values synchronously. This is different from plain mapObjectValues in
- * that this will not wrap the return value in a promise if any of the new object values are
- * promises. This function also requires currying in order to get the types correct. This allows you
- * to explicitly state the return type.
+ * Creates a new object with the same keys as the input object, but with values set to the result of
+ * `mapCallback` for each property. This is the same as {@link mapObjectValues} except that this
+ * preserves Promise values: it doesn't wrap them all in a single promise.
  *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function mapObjectValuesSync(inputObject, mapCallback) {
+    const mappedObject = getObjectTypedKeys(inputObject).reduce((accum, currentKey) => {
+        const mappedValue = mapCallback(currentKey, inputObject[currentKey], inputObject);
+        accum[currentKey] = mappedValue;
+        return accum;
+    }, {});
+    return mappedObject;
+}
+/**
+ * Creates a new object with the same keys as the input object, but with values set to the result of
+ * `mapCallback` for each property. Automatically handles an async `mapCallback`.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
- * mapObjectValuesSync({objectToIterateOver: 'initial value'})(callback);
+ * import {mapObjectValues} from '@augment-vir/common';
+ *
+ * mapObjectValues({a: 1, b: 2}, (key, value) => {
+ *     return `key-${key} value-${value}`;
+ * });
+ * // output is `{a: 'key-a value-1', b: 'key-b value-2'}`
  * ```
- */
-export function mapObjectValuesSync(inputObject) {
-    function innerMap(mapCallback) {
-        return getObjectTypedKeys(inputObject).reduce((accum, currentKey) => {
-            const mappedValue = mapCallback(currentKey, inputObject[currentKey], inputObject);
-            return {
-                ...accum,
-                [currentKey]: mappedValue,
-            };
-        }, {});
-    }
-    return innerMap;
-}
-/**
- * Creates a new object with the same properties as the input object, but with values set to the
- * result of mapCallback for each property.
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function mapObjectValues(inputObject, mapCallback) {
     let gotAPromise = false;

package/dist/augments/object/merge-deep.d.ts

@@ -4,6 +4,10 @@ import { PartialDeep } from 'type-fest';
  * undefined will be removed.
  *
  * Note that order matters! Each input object will overwrite the properties of the previous objects.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function mergeDeep<const T extends object>(...inputs: (Readonly<T> | Readonly<PartialDeep<T, {
     recurseIntoArrays: true;

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

@@ -4,6 +4,10 @@ import { check } from '@augment-vir/assert';
  * undefined will be removed.
  *
  * Note that order matters! Each input object will overwrite the properties of the previous objects.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function mergeDeep(...inputs) {
     if (!check.isLengthAtLeast(inputs, 1)) {

package/dist/augments/object/merge-defined-properties.d.ts

@@ -2,5 +2,18 @@ import type { AnyObject, PartialWithNullable } from '@augment-vir/core';
 /**
  * Merge all objects together but ignore any override values that are `undefined` or `null` or
  * missing. This only merges objects at the top level, it is not a deep merge.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mergeDefinedProperties} from '@augment-vir/common';
+ *
+ * mergeDefinedProperties({a: 'default', b: 'default'}, {a: 'override', b: undefined});
+ * // output is `{a: 'override', b: 'default'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function mergeDefinedProperties<const T extends AnyObject>(original: T, ...overrides: ReadonlyArray<PartialWithNullable<NoInfer<T>> | undefined>): T;

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

@@ -2,6 +2,19 @@ import { getObjectTypedEntries } from './object-entries.js';
 /**
  * Merge all objects together but ignore any override values that are `undefined` or `null` or
  * missing. This only merges objects at the top level, it is not a deep merge.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mergeDefinedProperties} from '@augment-vir/common';
+ *
+ * mergeDefinedProperties({a: 'default', b: 'default'}, {a: 'override', b: undefined});
+ * // output is `{a: 'override', b: 'default'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function mergeDefinedProperties(original, ...overrides) {
     const finalObject = { ...original };

package/dist/augments/object/merge-property-arrays.d.ts

@@ -1 +1,29 @@
+/**
+ * Merges all arrays by their property in the given objects.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mergePropertyArrays} from '@augment-vir/common';
+ *
+ * mergePropertyArrays(
+ *     {
+ *         a: [
+ *             'a',
+ *             'b',
+ *         ],
+ *     },
+ *     {
+ *         a: [
+ *             'c',
+ *             'd',
+ *         ],
+ *     },
+ * ); // output is `{a: ['a', 'b', 'c', 'd']}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function mergePropertyArrays<T extends Record<PropertyKey, unknown[]>>(...inputs: ReadonlyArray<Readonly<T>>): T;

package/dist/augments/object/merge-property-arrays.js

@@ -1,4 +1,32 @@
 import { getOrSet } from './get-or-set.js';
+/**
+ * Merges all arrays by their property in the given objects.
+ *
+ * @category Object : Merge
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {mergePropertyArrays} from '@augment-vir/common';
+ *
+ * mergePropertyArrays(
+ *     {
+ *         a: [
+ *             'a',
+ *             'b',
+ *         ],
+ *     },
+ *     {
+ *         a: [
+ *             'c',
+ *             'd',
+ *         ],
+ *     },
+ * ); // output is `{a: ['a', 'b', 'c', 'd']}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function mergePropertyArrays(...inputs) {
     const combined = {};
     inputs.forEach((input) => {

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

@@ -1,4 +1,31 @@
 import { CompleteRequire } from '@augment-vir/core';
+/**
+ * Gets an object's entries. This is the same as
+ * [`Object.entries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/entries)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getObjectTypedEntries<const ObjectGeneric>(input: ObjectGeneric): [keyof ObjectGeneric, CompleteRequire<ObjectGeneric>[keyof CompleteRequire<ObjectGeneric>]][];
+/**
+ * Create an object from an array of entries. This is the same as
+ * [`Object.fromEntries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function typedObjectFromEntries<const KeyType extends PropertyKey, const ValueType>(entries: ReadonlyArray<Readonly<[KeyType, ValueType]>>): Record<KeyType, ValueType>;
+/**
+ * Gets an object's entries and sorts them by their key values. This is the same as
+ * [`Object.entries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/entries)
+ * except that it has better TypeScript types and sorts the entries.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getEntriesSortedByKey<const ObjectGeneric>(input: ObjectGeneric): [keyof ObjectGeneric, CompleteRequire<ObjectGeneric>[keyof CompleteRequire<ObjectGeneric>]][];

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

@@ -1,13 +1,40 @@
 import { getObjectTypedKeys } from '@augment-vir/core';
+/**
+ * Gets an object's entries. This is the same as
+ * [`Object.entries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/entries)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getObjectTypedEntries(input) {
     return getObjectTypedKeys(input).map((key) => [
         key,
         input[key],
     ]);
 }
+/**
+ * Create an object from an array of entries. This is the same as
+ * [`Object.fromEntries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/fromEntries)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function typedObjectFromEntries(entries) {
     return Object.fromEntries(entries);
 }
+/**
+ * Gets an object's entries and sorts them by their key values. This is the same as
+ * [`Object.entries`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/entries)
+ * except that it has better TypeScript types and sorts the entries.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getEntriesSortedByKey(input) {
     return getObjectTypedEntries(input).sort((tupleA, tupleB) => String(tupleA[0]).localeCompare(String(tupleB[0])));
 }