@oscarpalmer/atoms 0.75.0 → 0.76.0

package/src/js/query.ts

@@ -1,10 +1,10 @@
-import {isNullableOrWhitespace, isPlainObject} from '@/is';
-import type {ArrayOrPlainObject, PlainObject} from '@/models';
-import {join} from '@/string';
-import {setValue} from '@/value';
+import {isPlainObject} from '~/is';
+import type {ArrayOrPlainObject, PlainObject} from '~/models';
+import {join} from '~/string';
+import {setValue} from '~/value';
 
 /**
- * Converts a query string to a plain _(nested)_ object
+ * Convert a query string to a plain _(nested)_ object
  */
 export function fromQuery(query: string): PlainObject {
 	const parts = query.split('&');
@@ -15,10 +15,6 @@ export function fromQuery(query: string): PlainObject {
 	for (let index = 0; index < length; index += 1) {
 		const [key, value] = parts[index].split('=').map(decodeURIComponent);
 
-		if (isNullableOrWhitespace(key)) {
-			continue;
-		}
-
 		if (key.includes('.')) {
 			setValue(parameters, key, getValue(value));
 		} else {
@@ -86,7 +82,7 @@ function isDecodable(value: unknown): value is boolean | number | string {
 }
 
 /**
- * Converts a plain _(nested)_ object to a query string
+ * Convert a plain _(nested)_ object to a query string
  */
 export function toQuery(parameters: PlainObject): string {
 	return getParts(parameters, false)

package/src/js/queue.ts

@@ -13,7 +13,7 @@ if (globalThis._atomic_queued == null) {
 }
 
 /**
- * Queues a callback to be executed at the next best time
+ * Queue a callback to be executed at the next best time
  */
 export function queue(callback: () => void): void {
 	_atomic_queued.add(callback);

package/src/js/random.ts

@@ -1,14 +1,14 @@
-import {shuffle} from '@/array/shuffle';
+import {shuffle} from '~/array/shuffle';
 
 /**
- * Returns a random boolean
+ * Get a random boolean
  */
 export function getRandomBoolean(): boolean {
 	return Math.random() > 0.5;
 }
 
 /**
- * Returns a random string of characters with a specified length
+ * Get a random string of characters with a specified length
  * - `selection` defaults to all lowercase letters in the English alphabet
  */
 export function getRandomCharacters(
@@ -34,24 +34,14 @@ export function getRandomCharacters(
 }
 
 /**
- * Returns a random hexadecimal colour
+ * Get a random hexadecimal colour
  */
 export function getRandomColour(): string {
 	return `#${Array.from({length: 6}, getRandomHex).join('')}`;
 }
 
 /**
- * Returns a random date
- */
-export function getRandomDate(earliest?: Date, latest?: Date): Date {
-	const earliestTime = earliest?.getTime() ?? -8_640_000_000_000_000;
-	const latestTime = latest?.getTime() ?? 8_640_000_000_000_000;
-
-	return new Date(getRandomInteger(earliestTime, latestTime));
-}
-
-/**
- * Returns a random floating-point number
+ * Get a random floating-point number
  */
 export function getRandomFloat(min?: number, max?: number): number {
 	const minimum = min ?? Number.MIN_SAFE_INTEGER;
@@ -60,28 +50,28 @@ export function getRandomFloat(min?: number, max?: number): number {
 }
 
 /**
- * Returns a random hexadecimal character
+ * Get a random hexadecimal character
  */
 export function getRandomHex(): string {
 	return '0123456789ABCDEF'[getRandomInteger(0, 16)];
 }
 
 /**
- * Returns a random integer
+ * Get a random integer
  */
 export function getRandomInteger(min?: number, max?: number): number {
 	return Math.floor(getRandomFloat(min, max));
 }
 
 /**
- * Returns a random item from an array
+ * Get a random item from an array
  */
 export function getRandomItem<Value>(array: Value[]): Value {
 	return array[getRandomInteger(0, array.length)];
 }
 
 /**
- * - Returns an amount of random items from an array
+ * - Get an amount of random items from an array
  * - If `amount` is not specified, a shuffled array will be returned instead
  */
 export function getRandomItems<Value>(

package/src/js/sized.ts

@@ -1,4 +1,4 @@
-import {clamp} from '@/number';
+import {clamp} from '~/number';
 
 /**
  * A Map with a maximum size
@@ -6,85 +6,85 @@ import {clamp} from '@/number';
  * - Behaviour is similar to a _LRU_-cache, where the least recently used entries are removed
  */
 export class SizedMap<Key = unknown, Value = unknown> extends Map<Key, Value> {
-	private readonly maximumSize: number;
+		private readonly maximumSize: number;
 
-	/**
-	 * Is the Map full?
-	 */
-	get full() {
-		return this.size >= this.maximumSize;
-	}
-
-	/**
-	 * The maximum size of the Map
-	 */
-	get maximum() {
-		return this.maximumSize;
-	}
+		/**
+		 * Is the Map full?
+		 */
+		get full() {
+			return this.size >= this.maximumSize;
+		}
 
-	/**
-	 * Creates a new Map with entries and a maximum size _(2^20)_
-	 */
-	constructor(entries: Array<[Key, Value]>);
-
-	/**
-	 * Creates a new Map with a maximum size _(but clamped at 2^24)_
-	 */
-	constructor(maximum: number);
-
-	/**
-	 * Creates a new Map with _(optional)_ entries and a maximum size _(defaults to 2^20; clamped at 2^24)_
-	 */
-	constructor(entries?: Array<[Key, Value]>, maximum?: number);
-
-	constructor(entries?: Array<[Key, Value]> | number, maximum?: number) {
-		const maximumSize = getMaximum(
-			typeof entries === 'number'
-				? entries
-				: typeof maximum === 'number'
-					? maximum
-					: undefined,
-		);
+		/**
+		 * The maximum size of the Map
+		 */
+		get maximum() {
+			return this.maximumSize;
+		}
 
-		super(Array.isArray(entries) ? entries.slice(0, maximumSize) : undefined);
+		/**
+		 * Create a new Map with entries and a maximum size _(2^20)_
+		 */
+		constructor(entries: Array<[Key, Value]>);
+
+		/**
+		 * Create a new Map with a maximum size _(but clamped at 2^24)_
+		 */
+		constructor(maximum: number);
+
+		/**
+		 * Create a new Map with _(optional)_ entries and a maximum size _(defaults to 2^20; clamped at 2^24)_
+		 */
+		constructor(entries?: Array<[Key, Value]>, maximum?: number);
+
+		constructor(entries?: Array<[Key, Value]> | number, maximum?: number) {
+			const maximumSize = getMaximum(
+				typeof entries === 'number'
+					? entries
+					: typeof maximum === 'number'
+						? maximum
+						: undefined,
+			);
+
+			super(Array.isArray(entries) ? entries.slice(0, maximumSize) : undefined);
+
+			this.maximumSize = maximumSize;
+
+			if (Array.isArray(entries) && entries.length > maximumSize) {
+				for (let index = 0; index < maximumSize; index += 1) {
+					this.set(...entries[entries.length - maximumSize + index]);
+				}
+			}
+		}
 
-		this.maximumSize = maximumSize;
+		/**
+		 * @inheritdoc
+		 */
+		get(key: Key): Value | undefined {
+			const value = super.get(key);
 
-		if (Array.isArray(entries) && entries.length > maximumSize) {
-			for (let index = 0; index < maximumSize; index += 1) {
-				this.set(...entries[entries.length - maximumSize + index]);
+			if (value == null && !this.has(key)) {
+				return;
 			}
-		}
-	}
 
-	/**
-	 * @inheritdoc
-	 */
-	get(key: Key): Value | undefined {
-		const value = super.get(key);
+			this.set(key, value as Value);
 
-		if (value === undefined && !this.has(key)) {
-			return;
+			return value;
 		}
 
-		this.set(key, value as Value);
-
-		return value;
-	}
+		/**
+		 * @inheritdoc
+		 */
+		set(key: Key, value: Value): this {
+			if (this.has(key)) {
+				this.delete(key);
+			} else if (this.size >= this.maximumSize) {
+				this.delete(this.keys().next().value as Key);
+			}
 
-	/**
-	 * @inheritdoc
-	 */
-	set(key: Key, value: Value): this {
-		if (this.has(key)) {
-			this.delete(key);
-		} else if (this.size >= this.maximumSize) {
-			this.delete(this.keys().next().value as Key);
+			return super.set(key, value);
 		}
-
-		return super.set(key, value);
 	}
-}
 
 /**
  * A Set with a maximum size
@@ -92,104 +92,104 @@ export class SizedMap<Key = unknown, Value = unknown> extends Map<Key, Value> {
  * - Behaviour is similar to a _LRU_-cache, where the oldest values are removed
  */
 export class SizedSet<Value = unknown> extends Set<Value> {
-	private readonly maximumSize: number;
+		private readonly maximumSize: number;
 
-	/**
-	 * Is the Set full?
-	 */
-	get full() {
-		return this.size >= this.maximumSize;
-	}
+		/**
+		 * Is the Set full?
+		 */
+		get full() {
+			return this.size >= this.maximumSize;
+		}
 
-	/**
-	 * The maximum size of the Set
-	 */
-	get maximum() {
-		return this.maximumSize;
-	}
+		/**
+		 * The maximum size of the Set
+		 */
+		get maximum() {
+			return this.maximumSize;
+		}
 
-	/**
-	 * Creates a new Set with values and a maximum size _(2^20)_
-	 */
-	constructor(values: Value[]);
-
-	/**
-	 * Creates a new Set with a maximum size _(but clamped at 2^24)_
-	 */
-	constructor(maximum: number);
-
-	/**
-	 * Creates a new Set with _(optional)_ values and a maximum size _(defaults to 2^20; clamped at 2^24)_
-	 */
-	constructor(values?: Value[], maximum?: number);
-
-	constructor(values?: Value[] | number, maximum?: number) {
-		const maximumSize = getMaximum(
-			typeof values === 'number'
-				? values
-				: typeof maximum === 'number'
-					? maximum
+		/**
+		 * Create a new Set with values and a maximum size _(2^20)_
+		 */
+		constructor(values: Value[]);
+
+		/**
+		 * Create a new Set with a maximum size _(but clamped at 2^24)_
+		 */
+		constructor(maximum: number);
+
+		/**
+		 * Create a new Set with _(optional)_ values and a maximum size _(defaults to 2^20; clamped at 2^24)_
+		 */
+		constructor(values?: Value[], maximum?: number);
+
+		constructor(values?: Value[] | number, maximum?: number) {
+			const maximumSize = getMaximum(
+				typeof values === 'number'
+					? values
+					: typeof maximum === 'number'
+						? maximum
+						: undefined,
+			);
+
+			super(
+				Array.isArray(values) && values.length <= maximumSize
+					? values
 					: undefined,
-		);
+			);
 
-		super(
-			Array.isArray(values) && values.length <= maximumSize
-				? values
-				: undefined,
-		);
+			this.maximumSize = maximumSize;
 
-		this.maximumSize = maximumSize;
-
-		if (Array.isArray(values) && values.length > maximumSize) {
-			for (let index = 0; index < maximumSize; index += 1) {
-				this.add(values[values.length - maximumSize + index]);
+			if (Array.isArray(values) && values.length > maximumSize) {
+				for (let index = 0; index < maximumSize; index += 1) {
+					this.add(values[values.length - maximumSize + index]);
+				}
 			}
 		}
-	}
-
-	/**
-	 * @inheritdoc
-	 */
-	add(value: Value): this {
-		if (this.has(value)) {
-			this.delete(value);
-		} else if (this.size >= this.maximumSize) {
-			this.delete(this.values().next().value as Value);
-		}
 
-		return super.add(value);
-	}
+		/**
+		 * @inheritdoc
+		 */
+		add(value: Value): this {
+			if (this.has(value)) {
+				this.delete(value);
+			} else if (this.size >= this.maximumSize) {
+				this.delete(this.values().next().value as Value);
+			}
 
-	/**
-	 * Get a value from an index in the Set, if it exists
-	 * - Negative indices are counted from the end
-	 * - Optionally move the value to the end with `update`
-	 */
-	at(index: number, update?: boolean): Value | undefined {
-		const value = [...this.values()][index < 0 ? this.size + index : index];
-
-		if ((update ?? false) && this.has(value)) {
-			this.delete(value);
-			this.add(value);
+			return super.add(value);
 		}
 
-		return value;
-	}
+		/**
+		 * Get a value from an index in the Set, if it exists
+		 * - Negative indices are counted from the end
+		 * - Optionally move the value to the end with `update`
+		 */
+		at(index: number, update?: boolean): Value | undefined {
+			const value = [...this.values()][index < 0 ? this.size + index : index];
 
-	/**
-	 * Get a value from the Set, if it exists _(and move it to the end)_
-	 */
-	get(value: Value, update?: boolean): Value | undefined {
-		if (this.has(value)) {
-			if (update ?? false) {
+			if ((update ?? false) && this.has(value)) {
 				this.delete(value);
 				this.add(value);
 			}
 
 			return value;
 		}
+
+		/**
+		 * Get a value from the Set, if it exists _(and move it to the end)_
+		 */
+		get(value: Value, update?: boolean): Value | undefined {
+			if (this.has(value)) {
+				if (update ?? false) {
+					this.delete(value);
+					this.add(value);
+				}
+
+				return value;
+			}
+		}
 	}
-}
 
 function getMaximum(first?: unknown, second?: unknown): number {
 	const actual =

package/src/js/string/case.ts

@@ -1,4 +1,4 @@
-import {words} from '@/string/index';
+import {words} from '~/string/index';
 
 /**
  * Convert a string to camel case _(thisIsCamelCase)_

package/src/js/string/index.ts

@@ -1,4 +1,4 @@
-import {compact} from '@/array';
+import {compact} from '~/array';
 
 /**
  * Create a new UUID
@@ -34,7 +34,7 @@ export function getString(value: unknown): string {
 }
 
 /**
- * Joins an array into a string while ignoring empty values _(with an optional delimiter)_
+ * Join an array into a string while ignoring empty values _(with an optional delimiter)_
  */
 export function join(value: unknown[], delimiter?: string): string {
 	return compact(value)
@@ -44,7 +44,7 @@ export function join(value: unknown[], delimiter?: string): string {
 }
 
 /**
- * Parses a JSON string into its proper value _(or `undefined` if it fails)_
+ * Parse a JSON string into its proper value _(or `undefined` if it fails)_
  */
 export function parse(
 	value: string,
@@ -58,7 +58,7 @@ export function parse(
 }
 
 /**
- * Truncates a string to a specified length, when possible
+ * Truncate a string to a specified length, when possible
  * - Returned as-is if the string is already short enough
  * - A suffix may be appended to the truncated string, e.g., an ellipsis
  */
@@ -67,12 +67,18 @@ export function truncate(
 	length: number,
 	suffix?: string,
 ): string {
+	if (length <= 0) {
+		return '';
+	}
+
+	if (length >= value.length) {
+		return value;
+	}
+
 	const suffixLength = suffix?.length ?? 0;
 	const truncatedLength = length - suffixLength;
 
-	return value.length <= length
-		? value
-		: `${value.slice(0, truncatedLength)}${suffix ?? ''}`;
+	return `${value.slice(0, truncatedLength)}${suffix ?? ''}`;
 }
 
 /**

package/src/js/string/template.ts

@@ -1,6 +1,6 @@
-import type {PlainObject} from '@/models';
-import {getString} from '@/string/index';
-import {getValue} from '@/value/get';
+import type {PlainObject} from '~/models';
+import {getString} from '~/string/index';
+import {getValue} from '~/value/get';
 
 type Options = {
 	/**
@@ -13,6 +13,9 @@ type Options = {
 	pattern?: RegExp;
 };
 
+/**
+ * Render a string from a template with variables
+ */
 export function template(
 	value: string,
 	variables: PlainObject,

package/src/js/value/clone.ts

@@ -1,12 +1,8 @@
-import {isArrayOrPlainObject} from '@/is';
-import type {ArrayOrPlainObject, PlainObject} from '@/models';
-
-export function clone(fn: (...args: unknown[]) => unknown): null;
-
-export function clone<Value>(value: Value): Value;
+import {isArrayOrPlainObject} from '~/is';
+import type {ArrayOrPlainObject, GenericCallback, PlainObject} from '~/models';
 
 /**
- * Clones any kind of value _(deeply, if needed)_
+ * Clone any kind of value _(deeply, if needed)_
  */
 export function clone(value: unknown) {
 	switch (true) {

package/src/js/value/compare.ts

@@ -1,6 +1,6 @@
-import {max} from '@/math';
-import {getNumber} from '@/number';
-import {words, getString, join} from '@/string';
+import {max} from '~/math';
+import {getNumber} from '~/number';
+import {words, getString, join} from '~/string';
 
 /**
  * Compare two values _(for sorting purposes)_
@@ -62,8 +62,6 @@ export function compare(first: unknown, second: unknown): number {
 				// Same value on last part? let's not fall through to string comparison
 				return 0;
 			}
-
-			continue;
 		}
 
 		return firstNumber - secondNumber;

package/src/js/value/diff.ts

@@ -1,7 +1,7 @@
-import {isArrayOrPlainObject} from '@/is';
-import type {ArrayOrPlainObject, Key, PlainObject} from '@/models';
-import {join} from '@/string/index';
-import {equal} from '@/value/equal';
+import {isArrayOrPlainObject} from '~/is';
+import type {ArrayOrPlainObject, Key, PlainObject} from '~/models';
+import {join} from '~/string/index';
+import {equal} from '~/value/equal';
 
 export type DiffType = 'full' | 'none' | 'partial';
 

package/src/js/value/equal.ts

@@ -1,5 +1,5 @@
-import {isPlainObject} from '@/is';
-import type {ArrayOrPlainObject, PlainObject} from '@/models';
+import {isPlainObject} from '~/is';
+import type {ArrayOrPlainObject, PlainObject} from '~/models';
 
 /**
  * Are two strings equal? _(Case-sensitive by default)_

package/src/js/value/get.ts

@@ -1,6 +1,6 @@
-import {handleValue} from '@/internal/value-handle';
-import type {Get, Paths, PlainObject} from '@/models';
 import type {ToString} from 'type-fest/source/internal/string';
+import {handleValue} from '~/internal/value/handle';
+import type {Get, Paths, PlainObject} from '~/models';
 
 /**
  * - Get the value from an object using a known path
@@ -34,7 +34,7 @@ export function getValue(
 	const {length} = parts;
 
 	let index = 0;
-	let value = typeof data === 'object' ? (data ?? {}) : {};
+	let value: PlainObject = data;
 
 	while (index < length && value != null) {
 		value = handleValue(

package/src/js/value/index.ts

@@ -1,7 +1,7 @@
-import type {PlainObject} from '@/models';
+import type {PlainObject} from '~/models';
 
 /**
- * Creates a new object with only the specified keys
+ * Create a new object with only the specified keys
  */
 export function partial<Value extends PlainObject, Key extends keyof Value>(
 	value: Value,

package/src/js/value/merge.ts

@@ -1,5 +1,5 @@
-import {isArrayOrPlainObject} from '@/is';
-import type {ArrayOrPlainObject, PlainObject} from '@/models';
+import {isArrayOrPlainObject} from '~/is';
+import type {ArrayOrPlainObject, PlainObject} from '~/models';
 
 type MergeOptions = {
 	/**
@@ -10,7 +10,7 @@ type MergeOptions = {
 };
 
 /**
- * Merges multiple arrays or objects into a single one
+ * Merge multiple arrays or objects into a single one
  */
 export function merge<Model extends ArrayOrPlainObject>(
 	values: Model[],

package/src/js/value/set.ts

@@ -1,5 +1,5 @@
-import {handleValue} from '@/internal/value-handle';
-import type {Paths, PlainObject} from '@/models';
+import {handleValue} from '~/internal/value/handle';
+import type {Paths, PlainObject} from '~/models';
 
 /**
  * - Set the value in an object using a known path
@@ -38,8 +38,7 @@ export function setValue<Data extends PlainObject>(
 	const {length} = parts;
 	const lastIndex = length - 1;
 
-	let target: PlainObject =
-		typeof data === 'object' && data !== null ? data : {};
+	let target: PlainObject = data;
 
 	for (let index = 0; index < length; index += 1) {
 		const part = parts[index];