@oscarpalmer/atoms 0.183.0 → 0.184.0

package/dist/index.mjs

@@ -2946,6 +2946,8 @@ function getNormalizeOptions(input) {
 }
 /**
 * Initialize a string normalizer
+*
+* Available as `initializeNormalizer` and `normalize.initialize`
 * @param options Normalization options
 * @returns Normalizer function
 */
@@ -3313,6 +3315,42 @@ const DIFF_FULL = "full";
 const DIFF_NONE = "none";
 const DIFF_PARTIAL = "partial";
 //#endregion
+//#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
 //#region src/internal/value/partial.ts
 function partial(value, providedKeys, omit) {
 	if (typeof value !== "object" || value === null) return {};
@@ -3351,6 +3389,11 @@ function pick(value, keys) {
 }
 //#endregion
 //#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;
@@ -3434,6 +3477,19 @@ function unsmush(value) {
 }
 //#endregion
 //#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,
@@ -3456,6 +3512,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`
@@ -3469,6 +3537,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;
@@ -3495,6 +3564,42 @@ function mergeValues(values, options, validate, prefix) {
 	return actual.length > 1 ? mergeObjects(actual, options, prefix) : actual[0] ?? {};
 }
 //#endregion
+//#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
 //#region src/beacon.ts
 var Beacon = class {
 	#options;
@@ -4837,11 +4942,161 @@ const TYPES = new Set([
 ]);
 //#endregion
 //#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;
@@ -4893,8 +5148,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;
 	}
@@ -4922,6 +5178,7 @@ var Queue = class {
 			parameters,
 			promise,
 			abort: aborter,
+			key: this.#key,
 			reject: rejector,
 			resolve: resolver,
 			signal: abortSignal
@@ -4990,7 +5247,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;
@@ -5037,17 +5297,30 @@ function handleResult$1(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
 //#region src/random.ts
 /**
@@ -5249,4 +5522,4 @@ var SizedSet = class extends Set {
 	}
 };
 //#endregion
-export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, QueueError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, asyncAttempt, asyncDebounce, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncThrottle, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, filter, find, findLast, first, firstOrDefault, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isSorted, isTypedArray, join, kalas, kebabCase, last, lastIndexOf, lastOrDefault, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assign, asyncAttempt, asyncDebounce, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncThrottle, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, filter, find, findLast, first, firstOrDefault, flatten, floor, flow, freeze, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeAssigner, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, initializeTransformer, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isSorted, isTypedArray, join, kalas, kebabCase, keyedQueue, last, lastIndexOf, lastOrDefault, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, transform, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/queue.d.mts

@@ -1,6 +1,96 @@
 import { GenericAsyncCallback, GenericCallback } from "./models.mjs";
 
 //#region src/queue.d.ts
+declare class KeyedQueue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
+  #private;
+  /**
+   * Is any queue active?
+   */
+  get active(): string[];
+  /**
+   * Does the queue automatically start when the first item is added?
+   */
+  get autostart(): boolean;
+  /**
+   * Maximum number of runners to process the queue concurrently
+   */
+  get concurrency(): number;
+  /**
+   * Are all queues empty?
+   */
+  get empty(): string[];
+  /**
+   * Are all queues full?
+   */
+  get full(): string[];
+  /**
+   * Number of items in all queues
+   */
+  get items(): Record<string, number>;
+  /**
+   * Keys of all queues
+   */
+  get keys(): string[];
+  /**
+   * Maximum number of items allowed in the queue
+   */
+  get maximum(): number;
+  /**
+   * Are all queues paused?
+   */
+  get paused(): string[];
+  /**
+   * Number of queues
+   */
+  get queues(): number;
+  constructor(callback: GenericAsyncCallback, options: Required<QueueOptions>);
+  /**
+   * 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: string, parameters: Tail<CallbackParameters>, signal?: AbortSignal): Queued<CallbackResult>;
+  /**
+   * 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?: string): void;
+  /**
+   * 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: string): Queue<Tail<CallbackParameters>, CallbackResult> | undefined;
+  /**
+   * 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?: string): void;
+  /**
+   * Remove a specific item for a specific key
+   * @param key Key to remove the item for
+   * @param id ID of the item to remove
+   */
+  remove(key: string, id: number): void;
+  /**
+   * Remove a queue and its items for a specific key
+   *
+   * _(To remove all items for a specific key, use `clear()` instead)_
+   * @param key Key to remove the queue for
+   */
+  remove(key: string): void;
+  /**
+   * Remove all queues and their items
+   */
+  remove(): void;
+  /**
+   * 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?: string): void;
+}
 declare class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
   #private;
   /**
@@ -35,7 +125,7 @@ declare class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>,
    * Number of items in the queue
    */
   get size(): number;
-  constructor(callback: GenericAsyncCallback, options: Required<QueueOptions>);
+  constructor(callback: GenericAsyncCallback, options: Required<QueueOptions>, key?: string);
   /**
    * Add an item to the queue
    * @param parameters Parameters to use when item runs
@@ -101,13 +191,15 @@ type QueuedResult<Value> = {
    */
   value: Value;
 };
+type Tail<Values extends any[]> = Values extends [infer _, ...infer Rest] ? Rest : never;
+declare function keyedQueue<Callback extends GenericAsyncCallback>(callback: Callback, options?: QueueOptions): KeyedQueue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
 /**
  * Create a queue for an asynchronous callback function
  * @param callback Callback function for queued items
  * @param options Queue options
  * @returns Queue instance
  */
-declare function queue<Callback extends GenericAsyncCallback>(callback: Callback, options?: QueueOptions): Queue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
+declare function queue<Callback extends (key: string, ...parameters: any[]) => Promise<void>>(callback: Callback, options?: QueueOptions): Queue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
 /**
  * Create a queue for an asynchronous callback function
  * @param callback Callback function for queued items
@@ -115,5 +207,8 @@ declare function queue<Callback extends GenericAsyncCallback>(callback: Callback
  * @returns Queue instance
  */
 declare function queue<Callback extends GenericCallback>(callback: Callback, options?: QueueOptions): Queue<Parameters<Callback>, ReturnType<Callback>>;
+declare namespace queue {
+  var keyed: typeof keyedQueue;
+}
 //#endregion
-export { type Queue, QueueError, type QueueOptions, type Queued, type QueuedResult, queue };
+export { type KeyedQueue, type Queue, type QueueError, type QueueOptions, type Queued, type QueuedResult, keyedQueue, queue };