@oscarpalmer/atoms 0.183.0 → 0.184.0

package/dist/queue.mjs

@@ -1,9 +1,159 @@
 //#region src/queue.ts
+var KeyedQueue = class {
+	#callback;
+	#options;
+	#queues = /* @__PURE__ */ new Map();
+	/**
+	* Is any queue active?
+	*/
+	get active() {
+		return this.#getStatus(STATUS_ACTIVE);
+	}
+	/**
+	* Does the queue automatically start when the first item is added?
+	*/
+	get autostart() {
+		return this.#options.autostart;
+	}
+	/**
+	* Maximum number of runners to process the queue concurrently
+	*/
+	get concurrency() {
+		return this.#options.concurrency;
+	}
+	/**
+	* Are all queues empty?
+	*/
+	get empty() {
+		return this.#getStatus(STATUS_EMPTY);
+	}
+	/**
+	* Are all queues full?
+	*/
+	get full() {
+		return this.#getStatus(STATUS_FULL);
+	}
+	/**
+	* Number of items in all queues
+	*/
+	get items() {
+		const size = {};
+		const queues = this.#queues.entries();
+		for (const [key, queue] of queues) size[key] = queue.size;
+		return size;
+	}
+	/**
+	* Keys of all queues
+	*/
+	get keys() {
+		return [...this.#queues.keys()];
+	}
+	/**
+	* Maximum number of items allowed in the queue
+	*/
+	get maximum() {
+		return this.#options.maximum;
+	}
+	/**
+	* Are all queues paused?
+	*/
+	get paused() {
+		return this.#getStatus(STATUS_PAUSED);
+	}
+	/**
+	* Number of queues
+	*/
+	get queues() {
+		return this.#queues.size;
+	}
+	constructor(callback, options) {
+		this.#callback = callback;
+		this.#options = options;
+	}
+	/**
+	* Queue an item for a specific key
+	* @param key Key to queue the item for
+	* @param parameters Parameters to use when item runs
+	* @param signal Optional signal to abort the item
+	* @returns Queued item
+	*/
+	add(key, parameters, signal) {
+		return this.#getQueue(key, true).add(parameters, signal);
+	}
+	/**
+	* Clear all items for a specific key _(or all items for all keys, if no key is provided)_
+	* @param key Optional key to clear the queue for
+	*/
+	clear(key) {
+		this.#handleQueues(HANDLE_CLEAR, key);
+	}
+	/**
+	* Get the queue for a specific key
+	* @param key Key to get the queue for
+	* @returns Queue for the key, or `undefined` if it doesn't exist
+	*/
+	get(key) {
+		return this.#getQueue(key);
+	}
+	/**
+	* Pause the queue for a specific key _(or all queues, if no key is provided)_
+	* @param key Optional key to pause the queue for
+	*/
+	pause(key) {
+		this.#handleQueues(HANDLE_PAUSE, key);
+	}
+	remove(key, id) {
+		if (key == null) {
+			this.#handleQueues(HANDLE_CLEAR);
+			this.#queues.clear();
+			return;
+		}
+		const queue = this.#getQueue(key);
+		if (queue == null) return;
+		if (typeof id === "number") {
+			queue.remove(id);
+			return;
+		}
+		queue.clear();
+		this.#queues.delete(key);
+	}
+	/**
+	* Resume the queue for a specific key _(or all queues, if no key is provided)_
+	* @param key Optional key to resume the queue for
+	*/
+	resume(key) {
+		this.#handleQueues(HANDLE_RESUME, key);
+	}
+	#getQueue(key, add) {
+		if (typeof key !== "string" || key.trim().length === 0) throw new TypeError(MESSAGE_KEY);
+		let queue = this.#queues.get(key);
+		if (queue == null && add === true) {
+			queue = new Queue(this.#callback, this.#options, key);
+			this.#queues.set(key, queue);
+		}
+		return queue;
+	}
+	#getStatus(status) {
+		const queues = this.#queues.entries();
+		const result = [];
+		for (const [key, queue] of queues) if (queue[status]) result.push(key);
+		return result;
+	}
+	#handleQueues(type, key) {
+		if (typeof key === "string") {
+			this.#getQueue(key)?.[type]();
+			return;
+		}
+		const queues = this.#queues.values();
+		for (const queue of queues) queue[type]();
+	}
+};
 var Queue = class {
 	#callback;
 	#handled = [];
 	#id = 0;
 	#items = [];
+	#key;
 	#options;
 	#paused;
 	#runners = 0;
@@ -55,8 +205,9 @@ var Queue = class {
 	get size() {
 		return this.#items.length;
 	}
-	constructor(callback, options) {
+	constructor(callback, options, key) {
 		this.#callback = callback;
+		this.#key = key;
 		this.#options = options;
 		this.#paused = !options.autostart;
 	}
@@ -84,6 +235,7 @@ var Queue = class {
 			parameters,
 			promise,
 			abort: aborter,
+			key: this.#key,
 			reject: rejector,
 			resolve: resolver,
 			signal: abortSignal
@@ -152,7 +304,10 @@ var Queue = class {
 			let error = false;
 			let result;
 			try {
-				if (!(item.signal?.aborted ?? false)) result = await this.#callback(...item.parameters);
+				if (!(item.signal?.aborted ?? false)) {
+					const parameters = item.key == null ? item.parameters : [item.key, ...item.parameters];
+					result = await this.#callback(...parameters);
+				}
 			} catch (thrown) {
 				error = true;
 				result = thrown;
@@ -199,16 +354,29 @@ function handleResult(item, error, result, finished) {
 		value: result
 	});
 }
+function keyedQueue(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_CALLBACK);
+	return new KeyedQueue(callback, getOptions(options));
+}
 function queue(callback, options) {
 	if (typeof callback !== "function") throw new TypeError(MESSAGE_CALLBACK);
 	return new Queue(callback, getOptions(options));
 }
+queue.keyed = keyedQueue;
 const ERROR_NAME = "QueueError";
 const EVENT_NAME = "abort";
 const EVENT_OPTIONS = { once: true };
+const HANDLE_CLEAR = "clear";
+const HANDLE_PAUSE = "pause";
+const HANDLE_RESUME = "resume";
 const MESSAGE_CALLBACK = "A Queue requires a callback function";
 const MESSAGE_CLEAR = "Queue was cleared";
+const MESSAGE_KEY = "Key must be a non-empty string";
 const MESSAGE_MAXIMUM = "Queue has reached its maximum size";
 const MESSAGE_REMOVE = "Item removed from queue";
+const STATUS_ACTIVE = "active";
+const STATUS_EMPTY = "empty";
+const STATUS_FULL = "full";
+const STATUS_PAUSED = "paused";
 //#endregion
-export { QueueError, queue };
+export { keyedQueue, queue };

package/dist/string/normalize.d.mts

@@ -45,6 +45,8 @@ type Normalizer = {
 declare function deburr(value: string): string;
 /**
  * Initialize a string normalizer
+ *
+ * Available as `initializeNormalizer` and `normalize.initialize`
  * @param options Normalization options
  * @returns Normalizer function
  */

package/dist/string/normalize.mjs

@@ -28,6 +28,8 @@ function getNormalizeOptions(input) {
 }
 /**
 * Initialize a string normalizer
+*
+* Available as `initializeNormalizer` and `normalize.initialize`
 * @param options Normalization options
 * @returns Normalizer function
 */

package/dist/value/freeze.d.mts

@@ -0,0 +1,35 @@
+import { ArrayOrPlainObject, GenericCallback, PlainObject } from "../models.mjs";
+
+//#region src/value/freeze.d.ts
+/**
+ * A frozen value with readonly properties _(going as deep as possible)_
+ */
+type Frozen<Value extends ArrayOrPlainObject> = { readonly [Key in keyof Value]: Value[Key] extends ArrayOrPlainObject ? Frozen<Value[Key]> : Value[Key] };
+/**
+ * Freeze an array and all its indices recursively
+ * @param array Array to freeze
+ * @returns Frozen array
+ */
+declare function freeze<Item>(array: Item[]): Frozen<Item[]>;
+/**
+ * Freeze a callback
+ * @param callback Function to freeze
+ * @returns Frozen function
+ */
+declare function freeze<Fn extends GenericCallback>(fn: Fn): Readonly<Fn>;
+/**
+ * Freeze an object and all its properties recursively
+ * @param object Object to freeze
+ * @returns Frozen object
+ */
+declare function freeze<Value extends PlainObject>(object: Value): Frozen<Value>;
+/**
+ * Freeze any value, if possible
+ *
+ * _(Only arrays, functions, and plain objects are freezable)_
+ * @param value Value to freeze
+ * @returns Frozen value
+ */
+declare function freeze<Value>(value: Value): Value;
+//#endregion
+export { Frozen, freeze };

package/dist/value/freeze.mjs

@@ -0,0 +1,38 @@
+import { isPlainObject } from "../internal/is.mjs";
+//#region src/value/freeze.ts
+function freeze(value) {
+	return freezeValue(value, /* @__PURE__ */ new WeakSet());
+}
+function freezeArray(array, references) {
+	references.add(array);
+	const { length } = array;
+	for (let index = 0; index < length; index += 1) {
+		const value = array[index];
+		if (!references.has(value)) array[index] = freezeValue(array[index], references);
+	}
+	return Object.freeze(array);
+}
+function freezeFunction(fn, references) {
+	references.add(fn);
+	return Object.freeze(fn);
+}
+function freezeObject(object, references) {
+	references.add(object);
+	const keys = Object.keys(object);
+	const { length } = keys;
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+		if (!references.has(object[key])) object[key] = freezeValue(object[key], references);
+	}
+	return Object.freeze(object);
+}
+function freezeValue(value, references) {
+	switch (true) {
+		case typeof value === "function": return freezeFunction(value, references);
+		case Array.isArray(value): return freezeArray(value, references);
+		case isPlainObject(value): return freezeObject(value, references);
+		default: return value;
+	}
+}
+//#endregion
+export { freeze };

package/dist/value/index.d.mts

@@ -1,6 +1,7 @@
+import { Frozen, freeze } from "./freeze.mjs";
 import { omit } from "./omit.mjs";
 import { pick } from "./pick.mjs";
 import { Shaken, shake } from "./shake.mjs";
 import { Smushed, smush } from "./smush.mjs";
 import { Unsmushed, unsmush } from "./unsmush.mjs";
-export { type Shaken, type Smushed, type Unsmushed, omit, pick, shake, smush, unsmush };
+export { type Frozen, type Shaken, type Smushed, type Unsmushed, freeze, omit, pick, shake, smush, unsmush };

package/dist/value/index.mjs

@@ -1,6 +1,7 @@
+import { freeze } from "./freeze.mjs";
 import { omit } from "./omit.mjs";
 import { pick } from "./pick.mjs";
 import { shake } from "./shake.mjs";
 import { smush } from "./smush.mjs";
 import { unsmush } from "./unsmush.mjs";
-export { omit, pick, shake, smush, unsmush };
+export { freeze, omit, pick, shake, smush, unsmush };

package/dist/value/merge.d.mts

@@ -1,6 +1,17 @@
 import { ArrayOrPlainObject, NestedPartial } from "../models.mjs";
 
 //#region src/value/merge.d.ts
+/**
+ * Options for assigning values
+ */
+type AssignOptions = Omit<MergeOptions, 'assignValues'>;
+/**
+ * Assign values from multiple arrays or objects to the first one
+ * @param to Value to assign to
+ * @param from Values to assign
+ * @returns Assigned value
+ */
+type Assigner<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (to: NestedPartial<Model>, from: NestedPartial<Model>[]) => Model;
 /**
  * Options for merging values
  */
@@ -40,6 +51,25 @@ type MergeOptions = {
  * @returns Merged value
  */
 type Merger<Model extends ArrayOrPlainObject = ArrayOrPlainObject> = (values: NestedPartial<Model>[]) => Model;
+/**
+ * Assign values from multiple arrays or objects to the first one
+ * @param to Value to assign to
+ * @param from Values to assign
+ * @param options Assigning options
+ * @returns Assigned value
+ */
+declare function assign<Model extends ArrayOrPlainObject>(to: NestedPartial<Model>, from: NestedPartial<Model>[], options?: AssignOptions): Model;
+declare namespace assign {
+  var initialize: typeof initializeAssigner;
+}
+/**
+ * Create an assigner with predefined options
+ *
+ * Available as `initializeAssigner` and `assign.initialize`
+ * @param options Assigning options
+ * @returns Assigner function
+ */
+declare function initializeAssigner<Model extends ArrayOrPlainObject>(options?: AssignOptions): Assigner<Model>;
 /**
  * Create a merger with predefined options
  *
@@ -63,7 +93,8 @@ declare function merge<Model extends ArrayOrPlainObject>(values: NestedPartial<M
  */
 declare function merge(values: NestedPartial<ArrayOrPlainObject>[], options?: MergeOptions): ArrayOrPlainObject;
 declare namespace merge {
+  var assign: typeof assign;
   var initialize: typeof initializeMerger;
 }
 //#endregion
-export { MergeOptions, Merger, initializeMerger, merge };
+export { AssignOptions, Assigner, MergeOptions, Merger, assign, initializeAssigner, initializeMerger, merge };

package/dist/value/merge.mjs

@@ -1,6 +1,19 @@
 import { isArrayOrPlainObject } from "../internal/is.mjs";
 import { join } from "../internal/string.mjs";
 //#region src/value/merge.ts
+/**
+* Assign values from multiple arrays or objects to the first one
+* @param to Value to assign to
+* @param from Values to assign
+* @param options Assigning options
+* @returns Assigned value
+*/
+function assign(to, from, options) {
+	const actual = getMergeOptions(options);
+	actual.assignValues = true;
+	return mergeValues([to, ...from], actual, true);
+}
+assign.initialize = initializeAssigner;
 function getMergeOptions(options) {
 	const actual = {
 		assignValues: false,
@@ -23,6 +36,18 @@ function handleMerge(values, options) {
 	return !Array.isArray(values) || values.length === 0 ? {} : mergeValues(values, options, true);
 }
 /**
+* Create an assigner with predefined options
+*
+* Available as `initializeAssigner` and `assign.initialize`
+* @param options Assigning options
+* @returns Assigner function
+*/
+function initializeAssigner(options) {
+	const actual = getMergeOptions(options);
+	actual.assignValues = true;
+	return ((to, from) => mergeValues([to, ...from], actual, true));
+}
+/**
 * Create a merger with predefined options
 *
 * Available as `initializeMerger` and `merge.initialize`
@@ -36,6 +61,7 @@ function initializeMerger(options) {
 function merge(values, options) {
 	return handleMerge(values, getMergeOptions(options));
 }
+merge.assign = assign;
 merge.initialize = initializeMerger;
 function mergeObjects(values, options, prefix) {
 	const { length } = values;
@@ -62,4 +88,4 @@ function mergeValues(values, options, validate, prefix) {
 	return actual.length > 1 ? mergeObjects(actual, options, prefix) : actual[0] ?? {};
 }
 //#endregion
-export { initializeMerger, merge };
+export { assign, initializeAssigner, initializeMerger, merge };

package/dist/value/shake.d.mts

@@ -2,6 +2,11 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/value/shake.d.ts
 type Shaken<Value extends PlainObject> = { [Key in keyof Value]: Value[Key] extends undefined ? never : Value[Key] };
+/**
+ * Shake an object, removing all keys with `undefined` values
+ * @param value Object to shake
+ * @returns Shaken object
+ */
 declare function shake<Value extends PlainObject>(value: Value): Shaken<Value>;
 //#endregion
 export { Shaken, shake };

package/dist/value/shake.mjs

@@ -1,5 +1,10 @@
 import { isNonPlainObject } from "../internal/is.mjs";
 //#region src/value/shake.ts
+/**
+* Shake an object, removing all keys with `undefined` values
+* @param value Object to shake
+* @returns Shaken object
+*/
 function shake(value) {
 	const shaken = {};
 	if (isNonPlainObject(value)) return shaken;

package/dist/value/transform.d.mts

@@ -0,0 +1,43 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/value/transform.d.ts
+type TransformCallback<Value extends PlainObject, Key extends keyof Value> = (key: Key, value: Value[Key]) => Value[Key];
+type TransformCallbacks<Value extends PlainObject> = Partial<{ [Key in keyof Value]: (value: Value[Key]) => Value[Key] }>;
+type Transformer<Value extends PlainObject> = {
+  (value: Value): Value;
+};
+/**
+ * Initialize a transformer for an object with a transformer function
+ *
+ * Available as `initializeTransformer` and `transform.initialize`
+ * @param transform Transformer function
+ * @returns Transformer
+ */
+declare function initializeTransformer<Value extends PlainObject>(transform: TransformCallback<Value, keyof Value>): Transformer<Value>;
+/**
+ * Initialize a transformer for an object with transformer functions
+ *
+ * Available as `initializeTransformer` and `transform.initialize`
+ * @param transformers Keyed transformer functions
+ * @return Transformer
+ */
+declare function initializeTransformer<Value extends PlainObject>(transformers: TransformCallbacks<Value>): Transformer<Value>;
+/**
+ * Transform and objects properties using a transformer functior
+ * @param value Object to transform
+ * @param transform Transformer function
+ * @returns Transformed object
+ */
+declare function transform<Value extends PlainObject, Key extends keyof Value>(value: Value, transform: TransformCallback<Value, Key>): Value;
+/**
+ * Transform and objects properties using a transformer object
+ * @param value Object to transform
+ * @param transformers Keyed transformer functions
+ * @returns Transformed object
+ */
+declare function transform<Value extends PlainObject>(value: Value, transformers: TransformCallbacks<Value>): Value;
+declare namespace transform {
+  var initialize: typeof initializeTransformer;
+}
+//#endregion
+export { Transformer, initializeTransformer, transform };

package/dist/value/transform.mjs

@@ -0,0 +1,38 @@
+import { isNonPlainObject } from "../internal/is.mjs";
+//#region src/value/transform.ts
+function getTransformer(input) {
+	if (typeof input === "function") return input;
+	if (isNonPlainObject(input)) return;
+	const keys = Object.keys(input);
+	const { length } = keys;
+	const transformer = {};
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+		const value = input[key];
+		if (typeof value === "function") transformer[key] = value;
+	}
+	if (Object.keys(transformer).length > 0) return transformer;
+}
+function initializeTransformer(transform) {
+	const transformer = getTransformer(transform);
+	return (value) => transformValue(value, transformer);
+}
+function transform(value, transform) {
+	return transformValue(value, getTransformer(transform));
+}
+transform.initialize = initializeTransformer;
+function transformValue(value, transformer) {
+	if (isNonPlainObject(value)) return {};
+	if (transformer == null) return value;
+	const keys = Object.keys(value);
+	const { length } = keys;
+	for (let index = 0; index < length; index += 1) {
+		const key = keys[index];
+		const val = value[key];
+		if (typeof transformer === "function") value[key] = transformer(key, val);
+		else value[key] = transformer[key]?.(val) ?? val;
+	}
+	return value;
+}
+//#endregion
+export { initializeTransformer, transform };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.183.0",
+	"version": "0.184.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",

package/plugin/index.js

@@ -30,8 +30,10 @@ export const miscPlugins = [
 	tryCatchPlugin,
 	getPlugin('number', 'getNumber', new Set(['Number']), true, true),
 	getPlugin('promise', 'promises', new Set(['all', 'allSettled']), true),
+	getPlugin('value', 'assign', new Set(['assign']), true),
 	getPlugin('value', 'clone', new Set(['structuredClone']), true, true),
 	getPlugin('value', 'equal', new Set(['is']), true),
+	getPlugin('value', 'freeze', new Set(['freeze']), true),
 ];
 
 export const stringPlugins = [

package/plugin/rules.js

@@ -11,8 +11,9 @@ const rules = {
 	'@oscarpalmer/atoms/array.slice': 'warn',
 	'@oscarpalmer/atoms/array.sort': 'warn',
 	'@oscarpalmer/atoms/array.splice': 'warn',
-	'@oscarpalmer/atoms/array.times': 'warn',
+	// '@oscarpalmer/atoms/array.times': 'warn',
 	'@oscarpalmer/atoms/attempt': 'warn',
+	'@oscarpalmer/atoms/math.ceil': 'warn',
 	'@oscarpalmer/atoms/math.floor': 'warn',
 	'@oscarpalmer/atoms/math.max': 'warn',
 	'@oscarpalmer/atoms/math.min': 'warn',
@@ -25,8 +26,10 @@ const rules = {
 	'@oscarpalmer/atoms/string.lowerCase': 'warn',
 	'@oscarpalmer/atoms/string.startsWith': 'warn',
 	'@oscarpalmer/atoms/string.upperCase': 'warn',
+	'@oscarpalmer/atoms/value.assign': 'warn',
 	'@oscarpalmer/atoms/value.clone': 'warn',
 	'@oscarpalmer/atoms/value.equal': 'warn',
+	'@oscarpalmer/atoms/value.freeze': 'warn',
 };
 
 export default rules;

package/src/array/sort.ts

@@ -493,6 +493,19 @@ function isSortedArray(array: unknown[], sorters: InternalSorter[]): boolean {
 	return true;
 }
 
+/**
+ * Sort an array of items using a comparison callback
+ * @param array Array to sort
+ * @param comparator Comparator to use for sorting
+ * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
+ * @returns Sorted array
+ */
+export function sort<Item>(
+	array: Item[],
+	comparator: (first: Item, second: Item) => number,
+	descending?: boolean,
+): Item[];
+
 /**
  * Sort an array of items, using multiple sorters to sort by specific values
  * @param array Array to sort
@@ -507,7 +520,7 @@ export function sort<Item>(
 ): Item[];
 
 /**
- * Sort an array of items, using multiple sorters to sort by specific values
+ * 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)_

package/src/index.ts

@@ -39,6 +39,7 @@ export * from './value/collection';
 export * from './value/diff';
 export * from './value/index';
 export * from './value/merge';
+export * from './value/transform';
 
 export * from './beacon';
 export * from './color';