@alessiofrittoli/react-hooks 4.1.1 → 4.2.0

package/dist/misc/queue/utils.d.ts

@@ -0,0 +1,104 @@
+import { g as QueuedItems, U as UUID, d as QueueItem, f as QueuedItem, e as QueueItems } from '../../types-Cx6f9FS1.js';
+import '@alessiofrittoli/math-utils';
+
+/**
+ * Adds a UUID to the given item.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param item	The item to add a UUID to.
+ * @returns		A new item with the same properties as the input item plus a UUID.
+ *
+ * @example
+ * ```ts
+ * const item       = { foo: 'bar' }
+ * const newItem    = addItemUUID( item )
+ * // Returns: { foo: 'bar', uuid: 'XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX' }
+ * ```
+ */
+declare const addItemUUID: <T extends object = object>(item: QueueItem<T> | QueuedItem<T>) => QueuedItem<T>;
+/**
+ * Adds a UUID to one or more items.
+ *
+ * If a single item is provided, it is normalized to an array and returned as
+ * a one-element list with generated UUIDs.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param items	A single item or an array of items where UUIDs are added to.
+ * @returns		An array of items with a UUID on each item.
+ *
+ * @example
+ * ```ts
+ * const result = addItemsUUID( [ { foo: 'bar' } ] )
+ * // Returns: [ { foo: 'bar', uuid: '...' } ]
+ * ```
+ */
+declare const addItemsUUID: <T extends object = object>(items: QueueItem<T> | QueuedItem<T> | QueueItems<T> | QueuedItems<T>) => QueuedItems<T>;
+/**
+ * Adds a UUID to the given item only when it does not already define one.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param item	The item to normalize with a UUID.
+ * @returns		A new item with a guaranteed UUID.
+ *
+ * @example
+ * ```ts
+ * const result = maybeAddItemUUID( { foo: 'bar' } )
+ * // Returns: { foo: 'bar', uuid: '...' }
+ * ```
+ */
+declare const maybeAddItemUUID: <T extends object = object>(item: QueueItem<T> | QueuedItem<T>) => QueuedItem<T>;
+/**
+ * Adds UUIDs to one or more items, preserving existing UUIDs when present.
+ *
+ * If a single item is provided, it is normalized to an array and returned as
+ * a one-element list.
+ *
+ * @template T	The type of the given item, must extend object.
+ * @param items	A single item or an array of items to normalize with UUIDs.
+ * @returns		An array of items with UUIDs on each item.
+ *
+ * @example
+ * ```ts
+ * const result = maybeAddItemsUUID( [ { foo: 'bar' }, { foo: 'baz', uuid: '1' } ] )
+ * // Returns: [ { foo: 'bar', uuid: '...' }, { foo: 'baz', uuid: '1' } ]
+ * ```
+ */
+declare const maybeAddItemsUUID: <T extends object = object>(items: QueueItem<T> | QueuedItem<T> | (QueueItem<T> | QueuedItem<T>)[]) => QueuedItems<T>;
+/**
+ * Finds the index of the item matching the given UUID.
+ *
+ * @param items	The queue items to search in.
+ * @param uuid	The UUID to match.
+ * @returns		The matching index, or `-1` when the UUID is missing or not found.
+ */
+declare const findIndexByUUID: (items: QueuedItems, uuid?: UUID) => number;
+interface GetEffectiveQueueOptions<T extends object = object> {
+    /**
+     * The main queue.
+     *
+     */
+    queue: QueuedItems<T>;
+    /**
+     * The custom queue.
+     *
+     */
+    customQueue: QueuedItems<T>;
+    /**
+     * The UUID after which the custom items are inserted.
+     *
+     */
+    uuid?: UUID;
+}
+/**
+ * Returns the queue with `customQueue` inserted after the item identified by `uuid`.
+ *
+ * If `uuid` is not provided, the original queue is returned unchanged. If `uuid`
+ * is provided but not found, `customQueue` is appended to the end of `queue`.
+ *
+ * @template T		The type of the queue items, must extend object.
+ * @param options	An object defining required parameters. See {@link GetEffectiveQueueOptions}.
+ * @returns			The effective queue.
+ */
+declare const getEffectiveQueue: <T extends object = object>(options: GetEffectiveQueueOptions<T>) => QueuedItems<T>;
+
+export { type GetEffectiveQueueOptions, addItemUUID, addItemsUUID, findIndexByUUID, getEffectiveQueue, maybeAddItemUUID, maybeAddItemsUUID };

package/dist/misc/queue/utils.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});var _chunkSV2TCLLEjs = require('../../chunk-SV2TCLLE.js');exports.addItemUUID = _chunkSV2TCLLEjs.a; exports.addItemsUUID = _chunkSV2TCLLEjs.b; exports.findIndexByUUID = _chunkSV2TCLLEjs.e; exports.getEffectiveQueue = _chunkSV2TCLLEjs.f; exports.maybeAddItemUUID = _chunkSV2TCLLEjs.c; exports.maybeAddItemsUUID = _chunkSV2TCLLEjs.d;

package/dist/misc/queue/utils.mjs

@@ -0,0 +1 @@
+import{a,b,c,d,e,f}from"../../chunk-OXQJOVCZ.mjs";export{a as addItemUUID,b as addItemsUUID,e as findIndexByUUID,f as getEffectiveQueue,c as maybeAddItemUUID,d as maybeAddItemsUUID};

package/dist/types-Cx6f9FS1.d.mts

@@ -0,0 +1,83 @@
+import { UUID as UUID$1 } from '@alessiofrittoli/math-utils';
+
+/**
+ * UUID type alias used by queue items.
+ *
+ */
+type UUID = UUID$1;
+/**
+ * Queue item with an optional UUID.
+ *
+ */
+type QueueItem<T extends object = object> = T & {
+    /**
+     * Optional item UUID.
+     *
+     */
+    uuid?: UUID;
+};
+/**
+ * List of queued items.
+ *
+ */
+type QueueItems<T extends object = object> = QueueItem<T>[];
+/**
+ * Queue item with a required UUID.
+ *
+ */
+type QueuedItem<T extends object = object> = QueueItem<T> & {
+    /**
+     * Item UUID.
+     *
+     */
+    uuid: UUID;
+};
+/**
+ * List of queued items.
+ *
+ */
+type QueuedItems<T extends object = object> = QueuedItem<T>[];
+/**
+ * Item shape accepted when enqueuing, with an optional UUID.
+ *
+ */
+type OptionalQueuedItem<T extends object = object> = Omit<T, 'uuid'> & Pick<QueueItem<Omit<T, 'uuid'>>, 'uuid'>;
+/**
+ * List of items accepted when enqueuing.
+ *
+ */
+type OptionalQueuedItems<T extends object = object> = OptionalQueuedItem<T>[];
+/**
+ * Defines the queue.
+ *
+ */
+interface Queue<T extends object = object> {
+    /**
+     * The queue items.
+     *
+     */
+    items: QueuedItems<T>;
+}
+/**
+ * Extracts the queued items type from a queue.
+ *
+ */
+type QueuedItemsType<T extends Queue = Queue> = T['items'];
+/**
+ * Extracts the queued item type from a queue.
+ *
+ */
+type QueuedItemType<T extends Queue = Queue> = QueuedItemsType<T>[number];
+/**
+ * Queue shape used when creating a new queue with optional item UUIDs.
+ *
+ */
+type NewQueue<T extends Queue = Queue> = Omit<T, 'items'> & {
+    /**
+     * The queue items.
+     *
+     */
+    items: OptionalQueuedItems<QueuedItemType<T>>;
+};
+
+export type { NewQueue as N, OptionalQueuedItem as O, Queue as Q, UUID as U, QueuedItemType as a, QueuedItemsType as b, OptionalQueuedItems as c, QueueItem as d, QueueItems as e, QueuedItem as f, QueuedItems as g };

package/dist/types-Cx6f9FS1.d.ts

@@ -0,0 +1,83 @@
+import { UUID as UUID$1 } from '@alessiofrittoli/math-utils';
+
+/**
+ * UUID type alias used by queue items.
+ *
+ */
+type UUID = UUID$1;
+/**
+ * Queue item with an optional UUID.
+ *
+ */
+type QueueItem<T extends object = object> = T & {
+    /**
+     * Optional item UUID.
+     *
+     */
+    uuid?: UUID;
+};
+/**
+ * List of queued items.
+ *
+ */
+type QueueItems<T extends object = object> = QueueItem<T>[];
+/**
+ * Queue item with a required UUID.
+ *
+ */
+type QueuedItem<T extends object = object> = QueueItem<T> & {
+    /**
+     * Item UUID.
+     *
+     */
+    uuid: UUID;
+};
+/**
+ * List of queued items.
+ *
+ */
+type QueuedItems<T extends object = object> = QueuedItem<T>[];
+/**
+ * Item shape accepted when enqueuing, with an optional UUID.
+ *
+ */
+type OptionalQueuedItem<T extends object = object> = Omit<T, 'uuid'> & Pick<QueueItem<Omit<T, 'uuid'>>, 'uuid'>;
+/**
+ * List of items accepted when enqueuing.
+ *
+ */
+type OptionalQueuedItems<T extends object = object> = OptionalQueuedItem<T>[];
+/**
+ * Defines the queue.
+ *
+ */
+interface Queue<T extends object = object> {
+    /**
+     * The queue items.
+     *
+     */
+    items: QueuedItems<T>;
+}
+/**
+ * Extracts the queued items type from a queue.
+ *
+ */
+type QueuedItemsType<T extends Queue = Queue> = T['items'];
+/**
+ * Extracts the queued item type from a queue.
+ *
+ */
+type QueuedItemType<T extends Queue = Queue> = QueuedItemsType<T>[number];
+/**
+ * Queue shape used when creating a new queue with optional item UUIDs.
+ *
+ */
+type NewQueue<T extends Queue = Queue> = Omit<T, 'items'> & {
+    /**
+     * The queue items.
+     *
+     */
+    items: OptionalQueuedItems<QueuedItemType<T>>;
+};
+
+export type { NewQueue as N, OptionalQueuedItem as O, Queue as Q, UUID as U, QueuedItemType as a, QueuedItemsType as b, OptionalQueuedItems as c, QueueItem as d, QueueItems as e, QueuedItem as f, QueuedItems as g };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@alessiofrittoli/react-hooks",
-	"version": "4.1.1",
+	"version": "4.2.0",
 	"description": "TypeScript React utility Hooks",
 	"author": {
 		"name": "Alessio Frittoli",
@@ -44,6 +44,26 @@
 				"default": "./dist/index.js"
 			}
 		},
+		"./queue": {
+			"import": {
+				"types": "./dist/misc/queue/index.d.mts",
+				"default": "./dist/misc/queue/index.mjs"
+			},
+			"require": {
+				"types": "./dist/misc/queue/index.d.ts",
+				"default": "./dist/misc/queue/index.js"
+			}
+		},
+		"./queue/utils": {
+			"import": {
+				"types": "./dist/misc/queue/utils.d.mts",
+				"default": "./dist/misc/queue/utils.mjs"
+			},
+			"require": {
+				"types": "./dist/misc/queue/utils.d.ts",
+				"default": "./dist/misc/queue/utils.js"
+			}
+		},
 		"./eslint": {
 			"import": {
 				"types": "./dist/eslint.d.mts",
@@ -96,39 +116,39 @@
 	"devDependencies": {
 		"@alessiofrittoli/event-emitter": "^1.6.0",
 		"@alessiofrittoli/node-scripts": "^3.3.0",
-		"@eslint/compat": "^2.0.2",
-		"@eslint/eslintrc": "^3.3.4",
+		"@eslint/compat": "^2.0.3",
+		"@eslint/eslintrc": "^3.3.5",
 		"@eslint/js": "^10.0.1",
-		"@jest/globals": "^30.2.0",
+		"@jest/globals": "^30.3.0",
 		"@testing-library/dom": "^10.4.1",
 		"@testing-library/jest-dom": "^6.9.1",
 		"@testing-library/react": "^16.3.2",
 		"@testing-library/user-event": "^14.6.1",
 		"@types/jest": "^30.0.0",
-		"@types/node": "^25.3.3",
+		"@types/node": "^25.5.0",
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
 		"concurrently": "^9.2.1",
 		"cross-env": "^10.1.0",
 		"dotenv": "^17.3.1",
-		"eslint": "^10.0.2",
+		"eslint": "^10.0.3",
 		"eslint-plugin-react": "^7.37.5",
 		"eslint-plugin-react-hooks": "^7.0.1",
 		"globals": "^17.4.0",
 		"http-server": "^14.1.1",
-		"jest": "^30.2.0",
-		"jest-environment-jsdom": "^30.2.0",
+		"jest": "^30.3.0",
+		"jest-environment-jsdom": "^30.3.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",
 		"ts-jest": "^29.4.6",
 		"ts-node": "^10.9.2",
 		"tsup": "^8.5.1",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.56.1"
+		"typescript-eslint": "^8.57.0"
 	},
 	"dependencies": {
 		"@alessiofrittoli/math-utils": "^2.0.0",
 		"@alessiofrittoli/type-utils": "^1.9.0",
-		"@alessiofrittoli/web-utils": "^2.1.0"
+		"@alessiofrittoli/web-utils": "^2.3.0"
 	}
 }