@oscarpalmer/atoms 0.71.0 → 0.72.0

package/src/js/sized.ts

@@ -0,0 +1,203 @@
+import {clamp} from './number';
+
+/**
+ * A Map with a maximum size
+ * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
+ * - 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;
+
+	/**
+	 * Is the Map full?
+	 */
+	get full() {
+		return this.size >= this.maximumSize;
+	}
+
+	/**
+	 * The maximum size of the Map
+	 */
+	get maximum() {
+		return 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,
+		);
+
+		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]);
+			}
+		}
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	get(key: Key): Value | undefined {
+		const value = super.get(key);
+
+		if (value === undefined && !this.has(key)) {
+			return;
+		}
+
+		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);
+		}
+
+		return super.set(key, value);
+	}
+}
+
+/**
+ * A Set with a maximum size
+ * - Maximum size defaults to _2^20_; any provided size will be clamped at _2^24_
+ * - 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;
+
+	/**
+	 * Is the Set full?
+	 */
+	get full() {
+		return this.size >= 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
+					: undefined,
+		);
+
+		super(
+			Array.isArray(values) && values.length <= maximumSize
+				? values
+				: undefined,
+		);
+
+		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]);
+			}
+		}
+	}
+
+	/**
+	 * @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);
+	}
+
+	/**
+	 * 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 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 =
+		(typeof first === 'number'
+			? first
+			: typeof second === 'number'
+				? second
+				: undefined) ?? 2 ** 20;
+
+	return clamp(actual, 1, 2 ** 24);
+}

package/src/js/string/index.ts

@@ -85,4 +85,3 @@ export function words(value: string): string[] {
 
 export * from './case';
 export * from './template';
-

package/src/js/string/template.ts

@@ -1,5 +1,6 @@
 import type {PlainObject} from '../models';
 import {getValue} from '../value';
+import {getString} from './index';
 
 type Options = {
 	/**
@@ -35,7 +36,7 @@ export function template(
 			return '';
 		}
 
-		values[key] = String(value);
+		values[key] = getString(value);
 
 		return values[key];
 	});

package/src/js/value/compare.ts

@@ -0,0 +1,85 @@
+import {max} from '../math';
+import {getNumber} from '../number';
+import {words, getString, join} from '../string';
+
+/**
+ * Compare two values _(for sorting purposes)_
+ */
+export function compare(first: unknown, second: unknown): number {
+	const firstParts = getParts(first);
+	const secondParts = getParts(second);
+	const length = max([firstParts.length, secondParts.length]);
+	const lastIndex = length - 1;
+
+	for (let index = 0; index < length; index += 1) {
+		const firstPart = firstParts[index];
+		const secondPart = secondParts[index];
+
+		if (firstPart === secondPart) {
+			if (index === lastIndex) {
+				return 0;
+			}
+
+			continue;
+		}
+
+		if (
+			firstPart == null ||
+			(typeof firstPart === 'string' && firstPart.length === 0)
+		) {
+			return -1;
+		}
+
+		if (
+			secondPart == null ||
+			(typeof secondPart === 'string' && secondPart.length === 0)
+		) {
+			return 1;
+		}
+
+		const firstNumber = getNumber(firstPart);
+		const secondNumber = getNumber(secondPart);
+
+		const firstIsNaN = Number.isNaN(firstNumber);
+		const secondIsNaN = Number.isNaN(secondNumber);
+
+		if (firstIsNaN || secondIsNaN) {
+			if (firstIsNaN && secondIsNaN) {
+				return getString(firstPart).localeCompare(getString(secondPart));
+			}
+
+			if (firstIsNaN) {
+				return 1;
+			}
+
+			if (secondIsNaN) {
+				return -1;
+			}
+		}
+
+		if (firstNumber === secondNumber) {
+			if (index === lastIndex) {
+				// Same value on last part? let's not fall through to string comparison
+				return 0;
+			}
+
+			continue;
+		}
+
+		return firstNumber - secondNumber;
+	}
+
+	return join(firstParts).localeCompare(join(secondParts));
+}
+
+function getParts(value: unknown): unknown[] {
+	if (value == null) {
+		return [''];
+	}
+
+	if (Array.isArray(value)) {
+		return value;
+	}
+
+	return typeof value === 'object' ? [value] : words(getString(value));
+}

package/src/js/value/index.ts

@@ -4,22 +4,23 @@ import type {PlainObject} from '../models';
  * Creates a new object with only the specified keys
  */
 export function partial<Value extends PlainObject, Key extends keyof Value>(
-		value: Value,
-		keys: Key[],
-	): Pick<Value, Key> {
-		const result = {} as Pick<Value, Key>;
-		const {length} = keys;
+	value: Value,
+	keys: Key[],
+): Pick<Value, Key> {
+	const result = {} as Pick<Value, Key>;
+	const {length} = keys;
 
-		for (let index = 0; index < length; index += 1) {
-			const key = keys[index];
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
 
-			result[key] = value[key];
-		}
-
-		return result;
+		result[key] = value[key];
 	}
 
+	return result;
+}
+
 export * from './clone';
+export * from './compare';
 export * from './diff';
 export * from './equal';
 export * from './get';
@@ -27,4 +28,3 @@ export * from './merge';
 export * from './set';
 export * from './smush';
 export * from './unsmush';
-

package/src/js/value/set.ts

@@ -38,7 +38,6 @@ export function setValue<Data extends PlainObject>(
 	const {length} = parts;
 	const lastIndex = length - 1;
 
-	let previous: PlainObject | undefined;
 	let target: PlainObject =
 		typeof data === 'object' && data !== null ? data : {};
 
@@ -59,7 +58,6 @@ export function setValue<Data extends PlainObject>(
 			target[part] = next;
 		}
 
-		previous = target;
 		target = next as PlainObject;
 	}
 

package/types/emitter.d.ts

@@ -67,6 +67,7 @@ declare class Subscription<Value> {
      * Is the subscription closed?
      */
     get closed(): boolean;
+    destroy(): void;
     /**
      * Unsubscribes from the observable
      */

package/types/function.d.ts

@@ -16,6 +16,10 @@ declare class Memoised<Callback extends GenericCallback> {
      * Deletes a result from the cache
      */
     delete(key: Parameters<Callback>[0]): boolean;
+    /**
+     * Destroys the instance, clearing its cache and removing its callback
+     */
+    destroy(): void;
     /**
      * Retrieves the result from the cache if it exists, or `undefined` otherwise
      */