@hyperfrontend/list-utils 0.0.4 → 0.1.0

package/index.cjs.js

@@ -1,126 +1,39 @@
 'use strict';
 
-/**
- * Safe copies of Object built-in methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/object
- */
-// Capture references at module initialization time
-const _Object = globalThis.Object;
-/**
- * (Safe copy) Prevents modification of existing property attributes and values,
- * and prevents the addition of new properties.
- */
-const freeze = _Object.freeze;
-
-const registeredClasses = [];
-
-/**
- * Safe copies of Array built-in static methods.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/array
- */
-// Capture references at module initialization time
-const _Array = globalThis.Array;
-/**
- * (Safe copy) Determines whether the passed value is an Array.
- */
-const isArray = _Array.isArray;
-/**
- * (Safe copy) Creates an array from an array-like or iterable object.
- */
-const from = _Array.from;
-
-/**
- * Returns the data type of the target.
- * Uses native `typeof` operator, however, makes distinction between `null`, `array`, and `object`.
- * Also, when classes are registered via `registerClass`, it checks if objects are instance of any known registered class.
- *
- * @param target - The target to get the data type of.
- * @returns The data type of the target.
- */
-const getType = (target) => {
-    if (target === null)
-        return 'null';
-    const nativeDataType = typeof target;
-    if (nativeDataType === 'object') {
-        if (isArray(target))
-            return 'array';
-        for (const registeredClass of registeredClasses) {
-            if (target instanceof registeredClass)
-                return registeredClass.name;
-        }
-    }
-    return nativeDataType;
-};
-
-/**
- * Safe copies of Error built-ins via factory functions.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides factory functions that use Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/error
- */
-// Capture references at module initialization time
-const _Error = globalThis.Error;
-const _Reflect$1 = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Error using the captured Error constructor.
- * Use this instead of `new Error()`.
- *
- * @param message - Optional error message.
- * @param options - Optional error options.
- * @returns A new Error instance.
- */
-const createError = (message, options) => _Reflect$1.construct(_Error, [message, options]);
-
-/**
- * Safe copies of Set built-in via factory function.
- *
- * Since constructors cannot be safely captured via Object.assign, this module
- * provides a factory function that uses Reflect.construct internally.
- *
- * These references are captured at module initialization time to protect against
- * prototype pollution attacks. Import only what you need for tree-shaking.
- *
- * @module @hyperfrontend/immutable-api-utils/built-in-copy/set
- */
-// Capture references at module initialization time
-const _Set = globalThis.Set;
-const _Reflect = globalThis.Reflect;
-/**
- * (Safe copy) Creates a new Set using the captured Set constructor.
- * Use this instead of `new Set()`.
- *
- * @param iterable - Optional iterable of values.
- * @returns A new Set instance.
- */
-const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
+const index_cjs_js$2 = require('./_dependencies/@hyperfrontend/data-utils/index.cjs.js');
+const index_cjs_js$4 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
+const index_cjs_js$3 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js');
+const index_cjs_js$1 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js');
+const index_cjs_js = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js');
 
 /**
  * Creates a FIFO (First-In-First-Out) list.
  *
  * @template T The type of elements in the list, must be an object.
  * @returns {FifoList<T>} A FIFO list with methods to manipulate and query the list.
+ * @example Creating and using FIFO queue
+ * ```typescript
+ * interface Task { id: number; name: string }
+ * const queue = createFifoList<Task>()
+ *
+ * queue.push({ id: 1, name: 'first' })
+ * queue.push({ id: 2, name: 'second' })
+ *
+ * queue.pull() // => { id: 1, name: 'first' }
+ * queue.pull() // => { id: 2, name: 'second' }
+ * queue.pull() // => undefined (the list is empty)
+ * ```
+ * @throws {Error} When the pushed item is a primitive rather than an object.
+ * @throws {Error} When the pushed item is already in the list. Use has() to check first if a duplicate is expected.
  */
 function createFifoList() {
-    const list = createSet();
+    const list = index_cjs_js.createSet();
     const push = (item) => {
-        if (getType(item) !== 'object') {
-            throw createError('A fifo list only non-primitive values');
+        if (index_cjs_js$2.getType(item) !== 'object') {
+            throw index_cjs_js$3.createError('A fifo list only supports non-primitive values');
         }
         if (list.has(item)) {
-            throw createError('Cannot a item that already exists');
+            throw index_cjs_js$3.createError('Cannot push an item that already exists in the list');
         }
         list.add(item);
     };
@@ -130,7 +43,7 @@ function createFifoList() {
         return value;
     };
     const map = (callback) => {
-        return from(list.values()).map(callback);
+        return index_cjs_js$4.from(list.values()).map(callback);
     };
     const forEach = (callback) => {
         list.forEach(callback);
@@ -149,7 +62,7 @@ function createFifoList() {
         size,
         clear,
     };
-    return freeze(result);
+    return index_cjs_js$1.freeze(result);
 }
 
 /**
@@ -157,24 +70,35 @@ function createFifoList() {
  *
  * @template T The type of elements in the list, must be an object.
  * @returns {LifoList<T>} A LIFO list with methods to manipulate and query the list.
+ * @example Creating and using LIFO stack
+ * ```typescript
+ * interface HistoryEntry { url: string; timestamp: number }
+ * const history = createLifoList<HistoryEntry>()
+ *
+ * history.push({ url: '/home', timestamp: 1 })
+ * history.push({ url: '/about', timestamp: 2 })
+ *
+ * history.pull() // => { url: '/about', timestamp: 2 }
+ * history.pull() // => { url: '/home', timestamp: 1 }
+ * ```
  */
 function createLifoList() {
-    const list = createSet();
+    const list = index_cjs_js.createSet();
     const push = (item) => {
-        if (getType(item) !== 'object') {
-            throw createError('A lifo list only supports non-primitive values');
+        if (index_cjs_js$2.getType(item) !== 'object') {
+            throw index_cjs_js$3.createError('A lifo list only supports non-primitive values');
         }
         list.add(item);
     };
     const pull = () => {
-        const lastItem = from(list).pop();
+        const lastItem = index_cjs_js$4.from(list).pop();
         if (lastItem) {
             list.delete(lastItem);
         }
         return lastItem;
     };
     const map = (callback) => {
-        return from(list).map(callback);
+        return index_cjs_js$4.from(list).map(callback);
     };
     const forEach = (callback) => {
         list.forEach(callback);
@@ -195,7 +119,7 @@ function createLifoList() {
         size,
         clear,
     };
-    return freeze(result);
+    return index_cjs_js$1.freeze(result);
 }
 
 /**
@@ -204,6 +128,14 @@ function createLifoList() {
  * @param start - The starting number of the range
  * @param end - The ending number of the range (inclusive)
  * @returns An array containing all numbers from start to end
+ * @example Generating number ranges
+ * ```typescript
+ * createRange(1, 5)
+ * // => [1, 2, 3, 4, 5]
+ *
+ * createRange(3, 3)
+ * // => [3]
+ * ```
  */
 function createRange(start, end) {
     const range = [];
@@ -218,10 +150,20 @@ function createRange(start, end) {
  *
  * @param values - The array of string values to cycle through
  * @returns A ValuePicker instance with current and next methods
+ * @example Cycling through values
+ * ```typescript
+ * const colorPicker = createValuePicker(['red', 'green', 'blue'])
+ *
+ * colorPicker.current() // => 'red'
+ * colorPicker.next()    // => 'red' (first call initializes)
+ * colorPicker.next()    // => 'green'
+ * colorPicker.next()    // => 'blue'
+ * colorPicker.next()    // => 'red' (cycles back)
+ * ```
  */
 function createValuePicker(values) {
     if (!values || !values.length) {
-        throw createError('Expected values not to be an empty list.');
+        throw index_cjs_js$3.createError('Expected values not to be an empty list.');
     }
     let index = -1;
     /**
@@ -251,7 +193,22 @@ function createValuePicker(values) {
     };
 }
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Retrieves the final key from a Map by converting keys to an array.
+ *
+ * @param map - The Map to extract the last key from
+ * @returns The key that was inserted last, or undefined if map is empty
+ * @example Getting last key from Map
+ * ```typescript
+ * const userRoles = new Map<string, string>()
+ * userRoles.set('alice', 'admin')
+ * userRoles.set('bob', 'editor')
+ * userRoles.set('charlie', 'viewer')
+ *
+ * getLastKeyInMap(userRoles) // => 'charlie'
+ * ```
+ */
 const getLastKeyInMap = (map) => {
     const items = [...map.keys()];
     return items[items.length - 1];
@@ -262,6 +219,11 @@ const getLastKeyInMap = (map) => {
  *
  * @param values - The array of strings to filter
  * @returns A new array containing only non-empty strings with content
+ * @example Filtering empty strings
+ * ```typescript
+ * nonEmptyStrings(['hello', '', '  ', 'world', null as unknown as string])
+ * // => ['hello', 'world']
+ * ```
  */
 function nonEmptyStrings(values) {
     return values.filter((value) => ![undefined, null, ''].includes(value) && value.trim() !== '');
@@ -272,9 +234,14 @@ function nonEmptyStrings(values) {
  *
  * @param values - The array of strings to deduplicate
  * @returns A new array containing only unique strings
+ * @example Deduplicating strings
+ * ```typescript
+ * uniqueStrings(['apple', 'banana', 'apple', 'cherry', 'banana'])
+ * // => ['apple', 'banana', 'cherry']
+ * ```
  */
 function uniqueStrings(values) {
-    return from(createSet(values));
+    return index_cjs_js$4.from(index_cjs_js.createSet(values));
 }
 
 exports.createFifoList = createFifoList;
@@ -284,4 +251,3 @@ exports.createValuePicker = createValuePicker;
 exports.getLastKeyInMap = getLastKeyInMap;
 exports.nonEmptyStrings = nonEmptyStrings;
 exports.uniqueStrings = uniqueStrings;
-//# sourceMappingURL=index.cjs.js.map

package/index.d.ts

@@ -1,8 +1,172 @@
-export * from './create-fifo-list';
-export * from './create-lifo-list';
-export * from './create-range';
-export * from './create-value-picker';
-export * from './get-last-key-in-map';
-export * from './non-empty-strings';
-export * from './unique-strings';
-//# sourceMappingURL=index.d.ts.map
+/**
+ * A FIFO (First-In-First-Out) list interface.
+ */
+interface FifoList<T extends object> {
+    /** Adds an item to the end of the list */
+    push(item: T): void;
+    /** Removes and returns the first item in the list, or undefined when the list is empty */
+    pull(): T | undefined;
+    /** Maps each item using the provided callback */
+    map<U>(callback: (item: T) => U): U[];
+    /** Iterates over each item in the list */
+    forEach(callback: (item: T) => void): void;
+    /** Removes a specific item from the list */
+    remove(item: T): boolean;
+    /** Checks if an item exists in the list */
+    has(item: T): boolean;
+    /** Returns the number of items in the list */
+    size(): number;
+    /** Removes all items from the list */
+    clear(): void;
+}
+/**
+ * Creates a FIFO (First-In-First-Out) list.
+ *
+ * @template T The type of elements in the list, must be an object.
+ * @returns {FifoList<T>} A FIFO list with methods to manipulate and query the list.
+ * @example Creating and using FIFO queue
+ * ```typescript
+ * interface Task { id: number; name: string }
+ * const queue = createFifoList<Task>()
+ *
+ * queue.push({ id: 1, name: 'first' })
+ * queue.push({ id: 2, name: 'second' })
+ *
+ * queue.pull() // => { id: 1, name: 'first' }
+ * queue.pull() // => { id: 2, name: 'second' }
+ * queue.pull() // => undefined (the list is empty)
+ * ```
+ * @throws {Error} When the pushed item is a primitive rather than an object.
+ * @throws {Error} When the pushed item is already in the list. Use has() to check first if a duplicate is expected.
+ */
+declare function createFifoList<T extends object>(): FifoList<T>;
+
+/**
+ * A LIFO (Last-In-First-Out) list interface.
+ */
+interface LifoList<T extends object> {
+    /** Adds an item to the list */
+    push(item: T): void;
+    /** Removes and returns the last item in the list */
+    pull(): T | undefined;
+    /** Maps each item using the provided callback */
+    map<U>(callback: (item: T) => U): U[];
+    /** Iterates over each item in the list */
+    forEach(callback: (item: T) => void): void;
+    /** Removes a specific item from the list */
+    remove(item: T): boolean;
+    /** Checks if an item exists in the list */
+    has(item: T): boolean;
+    /** Returns the number of items in the list */
+    size(): number;
+    /** Removes all items from the list */
+    clear(): void;
+}
+/**
+ * Creates a LIFO (Last-In-First-Out) list.
+ *
+ * @template T The type of elements in the list, must be an object.
+ * @returns {LifoList<T>} A LIFO list with methods to manipulate and query the list.
+ * @example Creating and using LIFO stack
+ * ```typescript
+ * interface HistoryEntry { url: string; timestamp: number }
+ * const history = createLifoList<HistoryEntry>()
+ *
+ * history.push({ url: '/home', timestamp: 1 })
+ * history.push({ url: '/about', timestamp: 2 })
+ *
+ * history.pull() // => { url: '/about', timestamp: 2 }
+ * history.pull() // => { url: '/home', timestamp: 1 }
+ * ```
+ */
+declare function createLifoList<T extends object>(): LifoList<T>;
+
+/**
+ * Interface for cycling through a list of values.
+ */
+interface ValuePicker {
+    /** Returns the current value without advancing. */
+    current: () => string;
+    /** Advances and returns the next value, cycling at end. */
+    next: () => string;
+}
+/**
+ * Creates a value picker that cycles through a list of string values.
+ *
+ * @param values - The array of string values to cycle through
+ * @returns A ValuePicker instance with current and next methods
+ * @example Cycling through values
+ * ```typescript
+ * const colorPicker = createValuePicker(['red', 'green', 'blue'])
+ *
+ * colorPicker.current() // => 'red'
+ * colorPicker.next()    // => 'red' (first call initializes)
+ * colorPicker.next()    // => 'green'
+ * colorPicker.next()    // => 'blue'
+ * colorPicker.next()    // => 'red' (cycles back)
+ * ```
+ */
+declare function createValuePicker(values: string[]): ValuePicker;
+
+/**
+ * Creates an array of numbers within a specified range (inclusive).
+ *
+ * @param start - The starting number of the range
+ * @param end - The ending number of the range (inclusive)
+ * @returns An array containing all numbers from start to end
+ * @example Generating number ranges
+ * ```typescript
+ * createRange(1, 5)
+ * // => [1, 2, 3, 4, 5]
+ *
+ * createRange(3, 3)
+ * // => [3]
+ * ```
+ */
+declare function createRange(start: number, end: number): number[];
+
+/**
+ * Retrieves the final key from a Map by converting keys to an array.
+ *
+ * @param map - The Map to extract the last key from
+ * @returns The key that was inserted last, or undefined if map is empty
+ * @example Getting last key from Map
+ * ```typescript
+ * const userRoles = new Map<string, string>()
+ * userRoles.set('alice', 'admin')
+ * userRoles.set('bob', 'editor')
+ * userRoles.set('charlie', 'viewer')
+ *
+ * getLastKeyInMap(userRoles) // => 'charlie'
+ * ```
+ */
+declare const getLastKeyInMap: <K = any>(map: Map<K, any>) => K;
+
+/**
+ * Filters out empty, null, undefined, and whitespace-only strings from an array.
+ *
+ * @param values - The array of strings to filter
+ * @returns A new array containing only non-empty strings with content
+ * @example Filtering empty strings
+ * ```typescript
+ * nonEmptyStrings(['hello', '', '  ', 'world', null as unknown as string])
+ * // => ['hello', 'world']
+ * ```
+ */
+declare function nonEmptyStrings(values: string[]): string[];
+
+/**
+ * Removes duplicate strings from an array, preserving insertion order.
+ *
+ * @param values - The array of strings to deduplicate
+ * @returns A new array containing only unique strings
+ * @example Deduplicating strings
+ * ```typescript
+ * uniqueStrings(['apple', 'banana', 'apple', 'cherry', 'banana'])
+ * // => ['apple', 'banana', 'cherry']
+ * ```
+ */
+declare function uniqueStrings(values: string[]): string[];
+
+export { createFifoList, createLifoList, createRange, createValuePicker, getLastKeyInMap, nonEmptyStrings, uniqueStrings };
+export type { FifoList, LifoList, ValuePicker };

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/utils/list/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAA;AAClC,cAAc,oBAAoB,CAAA;AAClC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,qBAAqB,CAAA;AACnC,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../../../libs/utils/list/src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,YAAY,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}