@oscarpalmer/atoms 0.186.2 → 0.187.0

package/dist/value/unsmush.d.mts

@@ -11,6 +11,7 @@ type KeysOfUnion<ObjectType> = keyof UnionToIntersection<ObjectType extends unkn
 type Unsmushed<Value extends PlainObject> = Simplify<Omit<{ [UnionKey in KeysOfUnion<Value>]: Value[UnionKey] }, `${string}.${string}`>>;
 /**
  * Unsmush a smushed object _(turning dot notation keys into nested keys)_
+ *
  * @param value Object to unsmush
  * @returns Unsmushed object with nested keys
  */

package/dist/value/unsmush.mjs

@@ -16,6 +16,7 @@ function getKeys(value) {
 }
 /**
 * Unsmush a smushed object _(turning dot notation keys into nested keys)_
+*
 * @param value Object to unsmush
 * @returns Unsmushed object with nested keys
 */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.186.2",
+	"version": "0.187.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -101,14 +101,14 @@
 			"types": "./dist/function/work.d.mts",
 			"default": "./dist/function/work.mjs"
 		},
+		"./herald": {
+			"types": "./dist/herald.d.mts",
+			"default": "./dist/herald.mjs"
+		},
 		"./is": {
 			"types": "./dist/is.d.mts",
 			"default": "./dist/is.mjs"
 		},
-		"./kalas": {
-			"types": "./dist/kalas.d.mts",
-			"default": "./dist/kalas.mjs"
-		},
 		"./logger": {
 			"types": "./dist/logger.d.mts",
 			"default": "./dist/logger.mjs"
@@ -232,6 +232,10 @@
 			"types": "./dist/value/diff.d.mts",
 			"default": "./dist/value/diff.mjs"
 		},
+		"./value/freeze": {
+			"types": "./dist/value/freeze.d.mts",
+			"default": "./dist/value/freeze.mjs"
+		},
 		"./value/equal": {
 			"types": "./dist/internal/value/equal.d.mts",
 			"default": "./dist/internal/value/equal.mjs"
@@ -253,8 +257,8 @@
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.63",
-		"@types/node": "^25.6",
+		"@oxlint/plugins": "^1.64",
+		"@types/node": "^25.7",
 		"@vitest/coverage-istanbul": "^4.1",
 		"eslint": "^10.3",
 		"jsdom": "^29.1",

package/src/array/filter.ts

@@ -6,7 +6,7 @@ import type {PlainObject} from '../models';
 /**
  * Get a filtered array of items that do not match the value
  *
- * Available as `exclude` and `filter.remove`
+ * _Available as `exclude` and `filter.remove`_
  *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
@@ -30,7 +30,7 @@ export function exclude<
 /**
  * Get a filtered array of items that do not match the value
  *
- * Available as `exclude` and `filter.remove`
+ * _Available as `exclude` and `filter.remove`_
  *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
@@ -55,7 +55,7 @@ export function exclude<Item extends PlainObject, ItemKey extends keyof Item>(
 /**
  * Get a filtered array of items that do not match the filter
  *
- * Available as `exclude` and `filter.remove`
+ * _Available as `exclude` and `filter.remove`_
  *
  * @param array Array to search in
  * @param filter Filter callback to match items
@@ -77,7 +77,7 @@ export function exclude<Item>(
 /**
  * Get a filtered array of items that do not match the given item
  *
- * Available as `exclude` and `filter.remove`
+ * _Available as `exclude` and `filter.remove`_
  *
  * @param array Array to search in
  * @param item Item to match against

package/src/array/find.ts

@@ -92,7 +92,7 @@ find.last = findLast;
 /**
  * Get the last item matching the given value
  *
- * Available as `findLast` and `find.last`
+ * _Available as `findLast` and `find.last`_
  *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
@@ -116,7 +116,7 @@ export function findLast<
 /**
  * Get the last item matching the given value by key
  *
- * Available as `findLast` and `find.last`
+ * _Available as `findLast` and `find.last`_
  *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
@@ -141,7 +141,7 @@ export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
 /**
  * Get the last item matching the filter
  *
- * Available as `findLast` and `find.last`
+ * _Available as `findLast` and `find.last`_
  *
  * @param array Array to search in
  * @param filter Filter callback to match items
@@ -163,7 +163,7 @@ export function findLast<Item>(
 /**
  * Get the last item matching the given value
  *
- * Available as `findLast` and `find.last`
+ * _Available as `findLast` and `find.last`_
  *
  * @param array Array to search in
  * @param value Value to match against

package/src/array/first.ts

@@ -93,7 +93,7 @@ first.default = firstOrDefault;
 /**
  * Get the first item matching the given value, or a default value if no match is found
  *
- * Available as `firstOrDefault` and `first.default`
+ * _Available as `firstOrDefault` and `first.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -119,7 +119,7 @@ export function firstOrDefault<
 /**
  * Get the first item matching the given value by key, or a default value if no match is found
  *
- * Available as `firstOrDefault` and `first.default`
+ * _Available as `firstOrDefault` and `first.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -147,7 +147,7 @@ export function firstOrDefault<Item extends PlainObject, ItemKey extends keyof I
 /**
  * Get the first item matching the filter, or a default value if no match is found
  *
- * Available as `firstOrDefault` and `first.default`
+ * _Available as `firstOrDefault` and `first.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -172,7 +172,7 @@ export function firstOrDefault<Item>(
 /**
  * Get the first item from an array, or a default value if the array is empty
  *
- * Available as `firstOrDefault` and `first.default`
+ * _Available as `firstOrDefault` and `first.default`_
  *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty

package/src/array/get.ts

@@ -20,6 +20,21 @@ export function getArray<Value extends PlainObject>(
 	indiced: true,
 ): Value[NumericalKeys<Value>][];
 
+/**
+ * Get an array from a map
+ *
+ * @param value Map to convert to an array
+ * @returns Array holding the entries of the map
+ *
+ * @example
+ * ```typescript
+ * getArray(
+ *   new Map([['a', 1], ['b', 2], ['c', 3]]),
+ * ); // => [['a', 1], ['b', 2], ['c', 3]]
+ * ```
+ */
+export function getArray<Key, Value>(map: Map<Key, Value>): [Key, Value][];
+
 /**
  * Get an array from an object
  *
@@ -32,7 +47,22 @@ export function getArray<Value extends PlainObject>(
  * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
  * ```
  */
-export function getArray<Value extends PlainObject>(value: Value): Value[keyof Value][];
+export function getArray<Value extends PlainObject>(
+	value: Value,
+): [keyof Value, Value[keyof Value]][];
+
+/**
+ * Get an array from a set
+ *
+ * @param value Set to convert to an array
+ * @returns Array holding the values of the set
+ *
+ * @example
+ * ```typescript
+ * getArray(new Set([123, 456, 789])); // => [123, 456, 789]
+ * ```
+ */
+export function getArray<Value>(set: Set<Value>): Value[];
 
 /**
  * Get an array from a value
@@ -65,7 +95,11 @@ export function getArray(value: unknown, indiced?: unknown): unknown[] {
 		return value;
 	}
 
-	if (value instanceof Map || value instanceof Set) {
+	if (value instanceof Map) {
+		return [...value.entries()];
+	}
+
+	if (value instanceof Set) {
 		return [...value.values()];
 	}
 
@@ -74,7 +108,7 @@ export function getArray(value: unknown, indiced?: unknown): unknown[] {
 	}
 
 	if (indiced !== true) {
-		return Object.values(value);
+		return Object.entries(value);
 	}
 
 	const keys = Object.keys(value);
@@ -84,9 +118,10 @@ export function getArray(value: unknown, indiced?: unknown): unknown[] {
 
 	for (let index = 0; index < length; index += 1) {
 		const key = keys[index];
+		const asNumber = Number.parseInt(key, 10);
 
-		if (!Number.isNaN(Number(key))) {
-			array.push(value[key]);
+		if (!Number.isNaN(asNumber)) {
+			array[asNumber] = (value as Record<string, unknown>)[key];
 		}
 	}
 

package/src/array/group-by.ts

@@ -187,7 +187,7 @@ groupBy.arrays = groupArraysBy;
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
@@ -219,7 +219,7 @@ export function groupArraysBy<
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
@@ -251,7 +251,7 @@ export function groupArraysBy<
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param key Key to use for grouping
@@ -283,7 +283,7 @@ export function groupArraysBy<
 /**
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param key Key to use for grouping
@@ -315,7 +315,7 @@ export function groupArraysBy<
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
@@ -340,7 +340,7 @@ export function groupArraysBy<
 /**
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
- * Available as `groupArraysBy` and `groupBy.arrays`
+ * _Available as `groupArraysBy` and `groupBy.arrays`_
  *
  * @param array Array to group
  * @param key Key to use for grouping

package/src/array/last.ts

@@ -91,7 +91,7 @@ last.default = lastOrDefault;
 /**
  * Get the last item matching the given value
  *
- * Available as `lastOrDefault` and `last.default`
+ * _Available as `lastOrDefault` and `last.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -117,7 +117,7 @@ export function lastOrDefault<
 /**
  * Get the last item matching the given value by key
  *
- * Available as `lastOrDefault` and `last.default`
+ * _Available as `lastOrDefault` and `last.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -145,7 +145,7 @@ export function lastOrDefault<Item extends PlainObject, ItemKey extends keyof It
 /**
  * Get the last item matching the filter
  *
- * Available as `lastOrDefault` and `last.default`
+ * _Available as `lastOrDefault` and `last.default`_
  *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
@@ -170,7 +170,7 @@ export function lastOrDefault<Item>(
 /**
  * Get the last item from an array
  *
- * Available as `lastOrDefault` and `last.default`
+ * _Available as `lastOrDefault` and `last.default`_
  *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty

package/src/array/match.ts

@@ -13,7 +13,8 @@ export type ArrayComparison = 'end' | 'inside' | 'invalid' | 'outside' | 'same'
 // #region Functions
 
 /**
- * Does the needle array end the haystack array?
+ * Is the needle array at the end of the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
  * @param callback Callback to get an item's value for matching
@@ -35,7 +36,7 @@ export function endsWithArray<Item>(
 ): boolean;
 
 /**
- * Does the needle array end the haystack array?
+ * Is the needle array at the end of the haystack array?
  *
  * @param haystack Haystack array
  * @param needle Needle array
@@ -58,7 +59,7 @@ export function endsWithArray<Item extends PlainObject>(
 ): boolean;
 
 /**
- * Does the needle array end the haystack array?
+ * Is the needle array at the end of the haystack array?
  *
  * @param haystack Haystack array
  * @param needle Needle array
@@ -343,7 +344,7 @@ export function indexOfArray(haystack: unknown[], needle: unknown[], key?: unkno
 }
 
 /**
- * Does the needle array start the haystack array?
+ * Is the needle array at the start of the haystack array?
  *
  * @param haystack Haystack array
  * @param needle Needle array
@@ -366,7 +367,7 @@ export function startsWithArray<Item>(
 ): boolean;
 
 /**
- * Does the needle array start the haystack array?
+ * Is the needle array at the start of the haystack array?
  *
  * @param haystack Haystack array
  * @param needle Needle array
@@ -389,7 +390,7 @@ export function startsWithArray<Item extends PlainObject>(
 ): boolean;
 
 /**
- * Does the needle array start the haystack array?
+ * Is the needle array at the start of the haystack array?
  *
  * @param haystack Haystack array
  * @param needle Needle array

package/src/array/move.ts

@@ -7,7 +7,7 @@ import {indexOfArray} from './match';
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
  *
- * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
  *
@@ -36,7 +36,7 @@ export function move<Item>(
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
  *
- * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
  *
@@ -65,7 +65,7 @@ export function move<Item extends PlainObject, ItemKey extends keyof Item>(
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
  *
- * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
+ * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
  *
@@ -145,7 +145,7 @@ move.toIndex = moveToIndex;
  *
  * If the from index is out of bounds, the array will be returned unchanged
  *
- * Available as `moveIndices` and `move.indices`
+ * _Available as `moveIndices` and `move.indices`_
  *
  * @param array Array to move within
  * @param from Index to move from
@@ -195,7 +195,7 @@ export function moveIndices<Item>(array: Item[], from: number, to: number): Item
  *
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
- * Available as `moveToIndex` and `move.toIndex`
+ * _Available as `moveToIndex` and `move.toIndex`_
  *
  * @example
  * ```typescript
@@ -224,7 +224,7 @@ export function moveToIndex<Item>(
  *
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
- * Available as `moveToIndex` and `move.toIndex`
+ * _Available as `moveToIndex` and `move.toIndex`_
  *
  * @param array Array to move within
  * @param value Item or items to move
@@ -253,7 +253,7 @@ export function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item
  *
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
- * Available as `moveToIndex` and `move.toIndex`
+ * _Available as `moveToIndex` and `move.toIndex`_
  *
  * @param array Array to move within
  * @param value Item or items to move

package/src/array/select.ts

@@ -153,6 +153,7 @@ export function select<
 
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterCallback Filter callback to match items
  * @param mapKey Key to get an item's value for mapping

package/src/array/slice.ts

@@ -173,7 +173,7 @@ function extract(
 }
 
 /**
- * Slice an array, returning a new array with a specified range of items
+ * Slice an array _(returning a new array with a specified range of items)_
  *
  * @param array Original array
  * @param start Start index _(inclusive)_
@@ -188,7 +188,7 @@ function extract(
 export function slice<Item>(array: Item[], start: number, end: number): Item[];
 
 /**
- * Slice an array, returning a new array with a specified number of items _(from the start)_
+ * Slice an array _(returning a new array with a specified number of items, from the start)_
  *
  * @param array Original array
  * @param count Maximum size of the new array
@@ -202,7 +202,7 @@ export function slice<Item>(array: Item[], start: number, end: number): Item[];
 export function slice<Item>(array: Item[], count: number): Item[];
 
 /**
- * Slice an array
+ * Slice an array _(returning a new array with all items)_
  *
  * @param array Array to slice
  * @returns Sliced array

package/src/array/sort.ts

@@ -149,7 +149,7 @@ function getComparisonSorter(callback: Function, modifier: number): InternalSort
 			simple: callback,
 		},
 		get: false,
-		identifier: String(callback),
+		identifier: callback.toString(),
 	};
 }
 
@@ -253,7 +253,7 @@ function getObjectSorter(obj: PlainObject, modifier: number): InternalSorter | u
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.getIndex`
+ * _Available as `getSortedIndex` and `sort.getIndex`_
  *
  * @param array Array to get the index from
  * @param item Item to get the index for
@@ -273,7 +273,7 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.getIndex`
+ * _Available as `getSortedIndex` and `sort.getIndex`_
  *
  * @param array Array to get the index from
  * @param item Item to get the index for
@@ -293,7 +293,7 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.getIndex`
+ * _Available as `getSortedIndex` and `sort.getIndex`_
  *
  * @param array Array to get the index from
  * @param item Item to get the index for
@@ -360,18 +360,20 @@ function getSorters(value: unknown, modifier: number): InternalSorter[] {
 }
 
 function getValueSorter(value: string | Function, modifier: number): InternalSorter {
+	const isFunction = typeof value === 'function';
+
 	return {
 		modifier,
 		get: true,
-		identifier: String(value),
-		value: typeof value === 'function' ? value : (item: unknown) => (item as PlainObject)[value],
+		identifier: isFunction ? value.toString() : value,
+		value: isFunction ? value : (item: unknown) => (item as PlainObject)[value],
 	};
 }
 
 /**
  * Initialize a sort handler with sorters _(and an optional default direction)_
  *
- * Available as `initializeSorter` and `sort.initialize`
+ * _Available as `initializeSorter` and `sort.initialize`_
  *
  * @param sorters Sorters to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -385,7 +387,7 @@ export function initializeSorter<Item>(
 /**
  * Initialize a sort handler with a sorter _(and an optional default direction)_
  *
- * Available as `initializeSorter` and `sort.initialize`
+ * _Available as `initializeSorter` and `sort.initialize`_
  *
  * @param sorter Sorter to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -399,7 +401,7 @@ export function initializeSorter<Item>(
 /**
  * Initialize a sort handler _(with an optional default direction)_
  *
- * Available as `initializeSorter` and `sort.initialize`
+ * _Available as `initializeSorter` and `sort.initialize`_
  *
  * @param descending Sort in descending order? _(defaults to `false`)_
  * @returns Sort handler
@@ -448,7 +450,7 @@ export function isSorted<Item>(
 /**
  * Is the array sorted?
  *
- * Available as `isSorted` and `sort.is`
+ * _Available as `isSorted` and `sort.is`_
  *
  * @param array Array to check
  * @param descending Sorted in descending order? _(defaults to `false`)_
@@ -534,6 +536,7 @@ export function sort<Item>(
 
 /**
  * Sort an array of items, using multiple sorters to sort by specific values
+ *
  * @param array Array to sort
  * @param sorters Sorters to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -547,6 +550,7 @@ export function sort<Item>(
 
 /**
  * Sort an array of items, using a single sorter to sort by a specific value
+ *
  * @param array Array to sort
  * @param sorter Sorter to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -556,6 +560,7 @@ export function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending?
 
 /**
  * Sort an array of items
+ *
  * @param array Array to sort
  * @param descending Sort in descending order? _(defaults to `false`)_
  * @returns Sorted array

package/src/array/swap.ts

@@ -270,7 +270,7 @@ function swapArrays(array: unknown[], from: unknown[], to: unknown[], key: unkno
  *
  * If either index is out of bounds, the array will be returned unchanged
  *
- * Available as `swapIndices` and `swap.indices`
+ * _Available as `swapIndices` and `swap.indices`_
  *
  * @param array Array of items to swap
  * @param first First index _(can be negative to count from the end)_