@oscarpalmer/atoms 0.77.0 → 0.77.2

package/src/js/array/to-record.ts

@@ -1,5 +1,5 @@
 import {groupValues} from '~/array/group-by';
-import type {KeyedValue, PlainObject, Key as SimpleKey} from '~/models';
+import type {Key, KeyedValue, PlainObject} from '~/models';
 
 /**
  * Create a record from an array of items _(using their indices as keys)_
@@ -9,143 +9,147 @@ export function toRecord<Item>(array: Item[]): Record<number, Item>;
 /**
  * Create a record from an array of items using a specific key
  */
-export function toRecord<Item, Key extends keyof Item>(
+export function toRecord<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
-): Record<KeyedValue<Item, Key>, Item>;
+	key: ItemKey,
+): Record<KeyedValue<Item, ItemKey>, Item>;
 
 /**
  * Create a record from an array of items using a specific key, and grouping them into arrays
  */
-export function toRecord<Item, Key extends keyof Item>(
+export function toRecord<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
+	key: ItemKey,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Item[]>;
+): Record<KeyedValue<Item, ItemKey>, Item[]>;
 
 /**
  * Create a record from an array of items using a specific key
  */
 export function toRecord<
 	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
->(array: Item[], key: Key): Record<ReturnType<Key>, Item>;
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], key: ItemKey): Record<ReturnType<ItemKey>, Item>;
 
 /**
  * Create a record from an array of items using a specific key, and grouping them into arrays
  */
 export function toRecord<
 	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
->(array: Item[], key: Key, arrays: true): Record<ReturnType<Key>, Item[]>;
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(
+	array: Item[],
+	key: ItemKey,
+	arrays: true,
+): Record<ReturnType<ItemKey>, Item[]>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function toRecord<
-	Item,
-	Key extends keyof Item,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<KeyedValue<Item, ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function toRecord<
-	Item,
-	Key extends keyof Item,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+): Record<KeyedValue<Item, ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function toRecord<
-	Item,
-	Key extends keyof Item,
-	Value extends (item: Item, index: number, array: Item[]) => unknown,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<KeyedValue<Item, ItemKey>, ReturnType<ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function toRecord<
-	Item,
-	Key extends keyof Item,
-	Value extends (item: Item, index: number, array: Item[]) => unknown,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+): Record<KeyedValue<Item, ItemKey>, Array<ReturnType<ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function toRecord<
-	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<ReturnType<Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<ReturnType<ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function toRecord<
-	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+): Record<ReturnType<ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function toRecord<
 	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
-	Value extends (item: Item, index: number, array: Item[]) => unknown,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<ReturnType<Key>, ReturnType<Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<ReturnType<ItemKey>, ReturnType<ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function toRecord<
 	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
-	Value extends (item: Item, index: number, array: Item[]) => unknown,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
+): Record<ReturnType<ItemKey>, Array<ReturnType<ItemValue>>>;
 
 export function toRecord(
 	array: unknown[],

package/src/js/array/unique.ts

@@ -1,5 +1,5 @@
 import {findValues} from '~/internal/array/find';
-import type {Key as SimpleKey} from '~/models';
+import type {Key, PlainObject} from '~/models';
 
 /**
  * Get an array of unique items
@@ -10,9 +10,9 @@ export function unique<Item>(array: Item[]): Item[];
  * - Get an array of unique items
  * - Use `key` to find a comparison value for an item
  */
-export function unique<Item, Key extends keyof Item>(
+export function unique<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
+	key: ItemKey,
 ): Item[];
 
 /**
@@ -20,9 +20,9 @@ export function unique<Item, Key extends keyof Item>(
  * - Use `key` to find a comparison value for an item
  */
 export function unique<
-	Item,
-	Key extends (item: Item, index: number, array: Item[]) => SimpleKey,
->(array: Item[], key: Key): Item[];
+		Item,
+		ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	>(array: Item[], key: ItemKey): Item[];
 
 export function unique(array: unknown[], key?: unknown): unknown[] {
 	return findValues('unique', array, [key, undefined]);

package/src/js/internal/value/handle.ts

@@ -1,8 +1,8 @@
-import type {PlainObject} from '~/models';
+import type {ArrayOrPlainObject, PlainObject} from '~/models';
 
 function findKey(
 	needle: string,
-	haystack: PlainObject,
+	haystack: ArrayOrPlainObject,
 	ignoreCase: boolean,
 ): string {
 	if (!ignoreCase) {
@@ -17,7 +17,7 @@ function findKey(
 }
 
 export function handleValue(
-	data: PlainObject,
+	data: ArrayOrPlainObject,
 	path: string,
 	value: unknown,
 	get: boolean,
@@ -31,9 +31,9 @@ export function handleValue(
 		const key = findKey(path, data, ignoreCase);
 
 		if (get) {
-			return data[key];
+			return data[key as never];
 		}
 
-		data[key] = value;
+		(data as PlainObject)[key] = value;
 	}
 }

package/src/js/value/clone.ts

@@ -4,6 +4,8 @@ import type {ArrayOrPlainObject, GenericCallback, PlainObject} from '~/models';
 /**
  * Clone any kind of value _(deeply, if needed)_
  */
+export function clone<Value>(value: Value): Value;
+
 export function clone(value: unknown) {
 	switch (true) {
 		case value == null:
@@ -60,7 +62,7 @@ function cloneArrayBuffer(value: ArrayBuffer): ArrayBuffer {
 }
 
 function cloneDataView(value: DataView): DataView {
-	const buffer = cloneArrayBuffer(value.buffer);
+	const buffer = cloneArrayBuffer(value.buffer as ArrayBuffer);
 
 	return new DataView(buffer, value.byteOffset, value.byteLength);
 }

package/src/js/value/equal.ts

@@ -75,7 +75,10 @@ function equalArrayBuffer(first: ArrayBuffer, second: ArrayBuffer): boolean {
 
 function equalDataView(first: DataView, second: DataView): boolean {
 	return first.byteOffset === second.byteOffset
-		? equalArrayBuffer(first.buffer, second.buffer)
+		? equalArrayBuffer(
+				first.buffer as ArrayBuffer,
+				second.buffer as ArrayBuffer,
+			)
 		: false;
 }
 

package/src/js/value/get.ts

@@ -1,16 +1,16 @@
 import type {ToString} from 'type-fest/source/internal/string';
 import {handleValue} from '~/internal/value/handle';
-import type {Get, Paths, PlainObject} from '~/models';
+import type {ArrayOrPlainObject, Get, Paths} from '~/models';
 
 /**
  * - Get the value from an object using a known path
  * - You can retrieve a nested value by using dot notation, e.g., `foo.bar.baz`
  * - Returns `undefined` if the value is not found
  */
-export function getValue<Data extends PlainObject, Path extends Paths<Data>>(
-	data: Data,
-	path: Path,
-): Get<Data, ToString<Path>>;
+export function getValue<
+	Data extends ArrayOrPlainObject,
+	Path extends Paths<Data>,
+>(data: Data, path: Path): Get<Data, ToString<Path>>;
 
 /**
  * - Get the value from an object using an unknown path
@@ -18,14 +18,14 @@ export function getValue<Data extends PlainObject, Path extends Paths<Data>>(
  * - If `ignoreCase` is `true`, path matching will be case-insensitive
  * - Returns `undefined` if the value is not found
  */
-export function getValue<Data extends PlainObject>(
+export function getValue<Data extends ArrayOrPlainObject>(
 	data: Data,
 	path: string,
 	ignoreCase?: boolean,
 ): unknown;
 
 export function getValue(
-	data: PlainObject,
+	data: ArrayOrPlainObject,
 	path: string,
 	ignoreCase?: boolean,
 ): unknown {
@@ -34,7 +34,7 @@ export function getValue(
 	const {length} = parts;
 
 	let index = 0;
-	let value: PlainObject = data;
+	let value: ArrayOrPlainObject = data;
 
 	while (index < length && value != null) {
 		value = handleValue(
@@ -43,7 +43,7 @@ export function getValue(
 			null,
 			true,
 			shouldIgnoreCase,
-		) as PlainObject;
+		) as ArrayOrPlainObject;
 	}
 
 	return value as never;

package/src/js/value/set.ts

@@ -1,5 +1,5 @@
 import {handleValue} from '~/internal/value/handle';
-import type {Paths, PlainObject} from '~/models';
+import type {ArrayOrPlainObject, Paths, PlainObject} from '~/models';
 
 /**
  * - Set the value in an object using a known path
@@ -7,11 +7,10 @@ import type {Paths, PlainObject} from '~/models';
  * - If a part of the path does not exist, it will be created, either as an array or a generic object, depending on the path
  * - Returns the original object
  */
-export function setValue<Data extends PlainObject, Path extends Paths<Data>>(
-	data: Data,
-	path: Path,
-	value: unknown,
-): Data;
+export function setValue<
+	Data extends ArrayOrPlainObject,
+	Path extends Paths<Data>,
+>(data: Data, path: Path, value: unknown): Data;
 
 /**
  * - Set the value in an object using an unknown path
@@ -20,14 +19,14 @@ export function setValue<Data extends PlainObject, Path extends Paths<Data>>(
  * - If `ignoreCase` is `true`, path matching will be case-insensitive
  * - Returns the original object
  */
-export function setValue<Data extends PlainObject>(
+export function setValue<Data extends ArrayOrPlainObject>(
 	data: Data,
 	path: string,
 	value: unknown,
 	ignoreCase?: boolean,
 ): Data;
 
-export function setValue<Data extends PlainObject>(
+export function setValue<Data extends ArrayOrPlainObject>(
 	data: Data,
 	path: string,
 	value: unknown,
@@ -38,7 +37,7 @@ export function setValue<Data extends PlainObject>(
 	const {length} = parts;
 	const lastIndex = length - 1;
 
-	let target: PlainObject = data;
+	let target: ArrayOrPlainObject = data;
 
 	for (let index = 0; index < length; index += 1) {
 		const part = parts[index];
@@ -54,10 +53,10 @@ export function setValue<Data extends PlainObject>(
 		if (typeof next !== 'object' || next === null) {
 			next = {};
 
-			target[part] = next;
+			(target as PlainObject)[part] = next;
 		}
 
-		target = next as PlainObject;
+		target = next as ArrayOrPlainObject;
 	}
 
 	return data;

package/types/array/count.d.cts

@@ -1,6 +1,38 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+Represents an object with `unknown` value. You probably want this instead of `{}`.
+
+Use case: You have an object whose keys and values are unknown to you.
+
+@example
+```
+import type {UnknownRecord} from 'type-fest';
+
+function toJson(object: UnknownRecord) {
+	return JSON.stringify(object);
+}
+
+toJson({hello: 'world'});
+//=> '{"hello":"world"}'
+
+function isObject(value: unknown): value is UnknownRecord {
+	return typeof value === 'object' && value !== null;
+}
+
+isObject({hello: 'world'});
+//=> true
+
+isObject('hello');
+//=> false
+```
+
+@category Type
+@category Object
+*/
+export type UnknownRecord = Record<PropertyKey, unknown>;
 export type Key = number | string;
+export type PlainObject = UnknownRecord;
 /**
  * Get the number of items _(count)_ that match the given value
  */
@@ -12,10 +44,10 @@ export declare function count<Item>(array: Item[], matches: (item: Item, index:
 /**
  * Get the number of items _(count)_ that match the given value
  */
-export declare function count<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): number;
+export declare function count<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): number;
 /**
  * Get the number of items _(count)_ that match the given value
  */
-export declare function count<Item, Key extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: Key, value: ReturnType<Key>): number;
+export declare function count<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): number;
 
 export {};

package/types/array/count.d.ts

@@ -1,4 +1,4 @@
-import type { Key as SimpleKey } from '~/models';
+import type { Key, PlainObject } from '~/models';
 /**
  * Get the number of items _(count)_ that match the given value
  */
@@ -10,8 +10,8 @@ export declare function count<Item>(array: Item[], matches: (item: Item, index:
 /**
  * Get the number of items _(count)_ that match the given value
  */
-export declare function count<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): number;
+export declare function count<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): number;
 /**
  * Get the number of items _(count)_ that match the given value
  */
-export declare function count<Item, Key extends (item: Item, index: number, array: Item[]) => SimpleKey>(array: Item[], key: Key, value: ReturnType<Key>): number;
+export declare function count<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): number;

package/types/array/exists.d.cts

@@ -1,6 +1,38 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+Represents an object with `unknown` value. You probably want this instead of `{}`.
+
+Use case: You have an object whose keys and values are unknown to you.
+
+@example
+```
+import type {UnknownRecord} from 'type-fest';
+
+function toJson(object: UnknownRecord) {
+	return JSON.stringify(object);
+}
+
+toJson({hello: 'world'});
+//=> '{"hello":"world"}'
+
+function isObject(value: unknown): value is UnknownRecord {
+	return typeof value === 'object' && value !== null;
+}
+
+isObject({hello: 'world'});
+//=> true
+
+isObject('hello');
+//=> false
+```
+
+@category Type
+@category Object
+*/
+export type UnknownRecord = Record<PropertyKey, unknown>;
 export type Key = number | string;
+export type PlainObject = UnknownRecord;
 /**
  * Does the value exist in array?
  */
@@ -13,11 +45,11 @@ export declare function exists<Item>(array: Item[], matches: (item: Item, index:
  * - Does the value exist in array?
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function exists<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): boolean;
+export declare function exists<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): boolean;
 /**
  * - Does the value exist in array?
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function exists<Item, Key extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: Key, value: ReturnType<Key>): boolean;
+export declare function exists<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): boolean;
 
 export {};

package/types/array/exists.d.ts

@@ -1,4 +1,4 @@
-import type { Key as SimpleKey } from '~/models';
+import type { Key, PlainObject } from '~/models';
 /**
  * Does the value exist in array?
  */
@@ -11,9 +11,9 @@ export declare function exists<Item>(array: Item[], matches: (item: Item, index:
  * - Does the value exist in array?
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function exists<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): boolean;
+export declare function exists<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): boolean;
 /**
  * - Does the value exist in array?
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function exists<Item, Key extends (item: Item, index: number, array: Item[]) => SimpleKey>(array: Item[], key: Key, value: ReturnType<Key>): boolean;
+export declare function exists<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): boolean;

package/types/array/filter.d.cts

@@ -1,6 +1,38 @@
 // Generated by dts-bundle-generator v9.5.1
 
+/**
+Represents an object with `unknown` value. You probably want this instead of `{}`.
+
+Use case: You have an object whose keys and values are unknown to you.
+
+@example
+```
+import type {UnknownRecord} from 'type-fest';
+
+function toJson(object: UnknownRecord) {
+	return JSON.stringify(object);
+}
+
+toJson({hello: 'world'});
+//=> '{"hello":"world"}'
+
+function isObject(value: unknown): value is UnknownRecord {
+	return typeof value === 'object' && value !== null;
+}
+
+isObject({hello: 'world'});
+//=> true
+
+isObject('hello');
+//=> false
+```
+
+@category Type
+@category Object
+*/
+export type UnknownRecord = Record<PropertyKey, unknown>;
 export type Key = number | string;
+export type PlainObject = UnknownRecord;
 /**
  * Get a filtered array of items matching `value`
  */
@@ -13,11 +45,11 @@ export declare function filter<Item>(array: Item[], matches: (item: Item, index:
  * - Get a filtered array of items
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function filter<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): Item[];
+export declare function filter<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
 /**
  * - Get a filtered array of items
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function filter<Item, Key extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: Key, value: ReturnType<Key>): Item[];
+export declare function filter<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): Item[];
 
 export {};

package/types/array/filter.d.ts

@@ -1,4 +1,4 @@
-import type { Key as SimpleKey } from '~/models';
+import type { Key, PlainObject } from '~/models';
 /**
  * Get a filtered array of items matching `value`
  */
@@ -11,9 +11,9 @@ export declare function filter<Item>(array: Item[], matches: (item: Item, index:
  * - Get a filtered array of items
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function filter<Item, Key extends keyof Item>(array: Item[], key: Key, value: Item[Key]): Item[];
+export declare function filter<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
 /**
  * - Get a filtered array of items
  * - Use `key` to find a comparison value to match with `value`
  */
-export declare function filter<Item, Key extends (item: Item, index: number, array: Item[]) => SimpleKey>(array: Item[], key: Key, value: ReturnType<Key>): Item[];
+export declare function filter<Item, ItemKey extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): Item[];