@hyperfrontend/list-utils 0.0.5 → 0.1.1

package/bundle/index.umd.js

@@ -4,143 +4,29 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.HyperfrontendListUtils = {}));
 })(this, (function (exports) { 'use strict';
 
-    /**
-     * 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
-     */
     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;
 
-    /**
-     * 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
-     */
     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.
-     *
-     * @example Creating Error instances
-     * ```typescript
-     * const error = createError('Operation failed')
-     * // With cause for error chaining
-     * const wrapped = createError('Request failed', { cause: originalError })
-     * ```
-     */
     const createError = (message, options) => _Reflect$1.construct(_Error, [message, options]);
 
-    /**
-     * 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
-     */
     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 = [];
-
-    /**
-     * 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.
-     *
-     * @example Determining data types
-     * ```typescript
-     * getType([1, 2]) // 'array'
-     * getType({ a: 1 }) // 'object'
-     * getType(null) // 'null'
-     * ```
-     */
-    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 Set factory for protected set construction.
-     *
-     * @module @hyperfrontend/immutable-api-utils/built-in-copy/set
-     */
-    /* eslint-disable workspace/lib-require-jsdoc-example */
     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] : []);
 
-    /**
-     * 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' }
-     * ```
-     */
+    const isNonPrimitive$1 = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
     function createFifoList() {
         const list = createSet();
         const push = (item) => {
-            if (getType(item) !== 'object') {
-                throw createError('A fifo list only non-primitive values');
+            if (!isNonPrimitive$1(item)) {
+                throw createError('A fifo list only supports non-primitive values');
             }
             if (list.has(item)) {
-                throw createError('Cannot a item that already exists');
+                throw createError('Cannot push an item that already exists in the list');
             }
             list.add(item);
         };
@@ -172,27 +58,11 @@
         return freeze(result);
     }
 
-    /**
-     * 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 }
-     * ```
-     */
+    const isNonPrimitive = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
     function createLifoList() {
         const list = createSet();
         const push = (item) => {
-            if (getType(item) !== 'object') {
+            if (!isNonPrimitive(item)) {
                 throw createError('A lifo list only supports non-primitive values');
             }
             list.add(item);
@@ -229,21 +99,6 @@
         return freeze(result);
     }
 
-    /**
-     * 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]
-     * ```
-     */
     function createRange(start, end) {
         const range = [];
         for (let i = start; i <= end; i += 1) {
@@ -252,42 +107,16 @@
         return range;
     }
 
-    /**
-     * 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)
-     * ```
-     */
     function createValuePicker(values) {
         if (!values || !values.length) {
             throw createError('Expected values not to be an empty list.');
         }
         let index = -1;
-        /**
-         * Returns the current value without advancing the picker.
-         *
-         * @returns The current value in the list
-         */
         function current() {
             if (index < 0)
                 index = 0;
             return values[index];
         }
-        /**
-         * Advances to and returns the next value, cycling back to the start when reaching the end.
-         *
-         * @returns The next value in the list
-         */
         function next() {
             if (index < 0)
                 return current();
@@ -300,53 +129,15 @@
         };
     }
 
-    /* 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];
     };
 
-    /**
-     * 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']
-     * ```
-     */
     function nonEmptyStrings(values) {
         return values.filter((value) => ![undefined, null, ''].includes(value) && value.trim() !== '');
     }
 
-    /**
-     * 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']
-     * ```
-     */
     function uniqueStrings(values) {
         return from(createSet(values));
     }

package/bundle/index.umd.min.js

@@ -1 +1 @@
-!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).HyperfrontendListUtils={})}(this,function(e){"use strict";const t=globalThis.Array,n=t.isArray,r=t.from,o=globalThis.Error,i=globalThis.Reflect,s=(e,t)=>i.construct(o,[e,t]),l=globalThis.Object.freeze,a=[],u=e=>{if(null===e)return"null";const t=typeof e;if("object"===t){if(n(e))return"array";for(const t of a)if(e instanceof t)return t.name}return t},c=globalThis.Set,f=globalThis.Reflect,h=e=>f.construct(c,e?[e]:[]);e.createFifoList=function(){const e=h();return l({push:t=>{if("object"!==u(t))throw s("A fifo list only non-primitive values");if(e.has(t))throw s("Cannot a item that already exists");e.add(t)},pull:()=>{const t=e.values().next().value;return e.delete(t),t},map:t=>r(e.values()).map(t),forEach:t=>{e.forEach(t)},remove:t=>e.delete(t),has:t=>e.has(t),size:()=>e.size,clear:()=>e.clear()})},e.createLifoList=function(){const e=h();return l({push:t=>{if("object"!==u(t))throw s("A lifo list only supports non-primitive values");e.add(t)},pull:()=>{const t=r(e).pop();return t&&e.delete(t),t},map:t=>r(e).map(t),forEach:t=>{e.forEach(t)},remove:t=>e.delete(t),has:t=>e.has(t),size:()=>e.size,clear:()=>{e.clear()}})},e.createRange=function(e,t){const n=[];for(let r=e;r<=t;r+=1)n.push(r);return n},e.createValuePicker=function(e){if(!e||!e.length)throw s("Expected values not to be an empty list.");let t=-1;function n(){return t<0&&(t=0),e[t]}return{current:n,next:function(){return t<0?n():(t=++t<e.length?t:0,e[t])}}},e.getLastKeyInMap=e=>{const t=[...e.keys()];return t[t.length-1]},e.nonEmptyStrings=function(e){return e.filter(e=>![void 0,null,""].includes(e)&&""!==e.trim())},e.uniqueStrings=function(e){return r(h(e))}});
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?t(exports):"function"==typeof define&&define.amd?define(["exports"],t):t((e="undefined"!=typeof globalThis?globalThis:e||self).HyperfrontendListUtils={})}(this,function(e){"use strict";const t=globalThis.Array.from,n=globalThis.Error,o=globalThis.Reflect,r=(e,t)=>o.construct(n,[e,t]),i=globalThis.Object.freeze,l=globalThis.Set,s=globalThis.Reflect,u=e=>s.construct(l,e?[e]:[]);e.createFifoList=function(){const e=u();return i({push:t=>{if(("object"!=typeof(n=t)||null===n)&&"function"!=typeof n)throw r("A fifo list only supports non-primitive values");var n;if(e.has(t))throw r("Cannot push an item that already exists in the list");e.add(t)},pull:()=>{const t=e.values().next().value;return e.delete(t),t},map:n=>t(e.values()).map(n),forEach:t=>{e.forEach(t)},remove:t=>e.delete(t),has:t=>e.has(t),size:()=>e.size,clear:()=>e.clear()})},e.createLifoList=function(){const e=u();return i({push:t=>{if(("object"!=typeof(n=t)||null===n)&&"function"!=typeof n)throw r("A lifo list only supports non-primitive values");var n;e.add(t)},pull:()=>{const n=t(e).pop();return n&&e.delete(n),n},map:n=>t(e).map(n),forEach:t=>{e.forEach(t)},remove:t=>e.delete(t),has:t=>e.has(t),size:()=>e.size,clear:()=>{e.clear()}})},e.createRange=function(e,t){const n=[];for(let o=e;o<=t;o+=1)n.push(o);return n},e.createValuePicker=function(e){if(!e||!e.length)throw r("Expected values not to be an empty list.");let t=-1;function n(){return t<0&&(t=0),e[t]}return{current:n,next:function(){return t<0?n():(t=++t<e.length?t:0,e[t])}}},e.getLastKeyInMap=e=>{const t=[...e.keys()];return t[t.length-1]},e.nonEmptyStrings=function(e){return e.filter(e=>![void 0,null,""].includes(e)&&""!==e.trim())},e.uniqueStrings=function(e){return t(u(e))}});

package/index.cjs.js

@@ -1,11 +1,17 @@
 'use strict';
 
-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$3 = require('./_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js');
+const index_cjs_js$2 = 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');
 
+/**
+ * Reports whether a value is a non-primitive, the only kind of value these lists accept.
+ *
+ * @param value - The value a caller tried to push.
+ * @returns True when the value is a non-null object or a function.
+ */
+const isNonPrimitive$1 = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
 /**
  * Creates a FIFO (First-In-First-Out) list.
  *
@@ -21,16 +27,19 @@ const index_cjs_js = require('./_dependencies/@hyperfrontend/immutable-api-utils
  *
  * 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 = index_cjs_js.createSet();
     const push = (item) => {
-        if (index_cjs_js$2.getType(item) !== 'object') {
-            throw index_cjs_js$3.createError('A fifo list only non-primitive values');
+        if (!isNonPrimitive$1(item)) {
+            throw index_cjs_js$2.createError('A fifo list only supports non-primitive values');
         }
         if (list.has(item)) {
-            throw index_cjs_js$3.createError('Cannot a item that already exists');
+            throw index_cjs_js$2.createError('Cannot push an item that already exists in the list');
         }
         list.add(item);
     };
@@ -40,7 +49,7 @@ function createFifoList() {
         return value;
     };
     const map = (callback) => {
-        return index_cjs_js$4.from(list.values()).map(callback);
+        return index_cjs_js$3.from(list.values()).map(callback);
     };
     const forEach = (callback) => {
         list.forEach(callback);
@@ -62,6 +71,13 @@ function createFifoList() {
     return index_cjs_js$1.freeze(result);
 }
 
+/**
+ * Reports whether a value is a non-primitive, the only kind of value these lists accept.
+ *
+ * @param value - The value a caller tried to push.
+ * @returns True when the value is a non-null object or a function.
+ */
+const isNonPrimitive = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
 /**
  * Creates a LIFO (Last-In-First-Out) list.
  *
@@ -82,20 +98,20 @@ function createFifoList() {
 function createLifoList() {
     const list = index_cjs_js.createSet();
     const push = (item) => {
-        if (index_cjs_js$2.getType(item) !== 'object') {
-            throw index_cjs_js$3.createError('A lifo list only supports non-primitive values');
+        if (!isNonPrimitive(item)) {
+            throw index_cjs_js$2.createError('A lifo list only supports non-primitive values');
         }
         list.add(item);
     };
     const pull = () => {
-        const lastItem = index_cjs_js$4.from(list).pop();
+        const lastItem = index_cjs_js$3.from(list).pop();
         if (lastItem) {
             list.delete(lastItem);
         }
         return lastItem;
     };
     const map = (callback) => {
-        return index_cjs_js$4.from(list).map(callback);
+        return index_cjs_js$3.from(list).map(callback);
     };
     const forEach = (callback) => {
         list.forEach(callback);
@@ -160,7 +176,7 @@ function createRange(start, end) {
  */
 function createValuePicker(values) {
     if (!values || !values.length) {
-        throw index_cjs_js$3.createError('Expected values not to be an empty list.');
+        throw index_cjs_js$2.createError('Expected values not to be an empty list.');
     }
     let index = -1;
     /**
@@ -238,7 +254,7 @@ function nonEmptyStrings(values) {
  * ```
  */
 function uniqueStrings(values) {
-    return index_cjs_js$4.from(index_cjs_js.createSet(values));
+    return index_cjs_js$3.from(index_cjs_js.createSet(values));
 }
 
 exports.createFifoList = createFifoList;

package/index.d.ts

@@ -4,8 +4,8 @@
 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 */
-    pull(): T;
+    /** 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 */
@@ -34,7 +34,10 @@ interface FifoList<T extends object> {
  *
  * 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>;
 

package/index.esm.js

@@ -1,9 +1,15 @@
-import { getType } from './_dependencies/@hyperfrontend/data-utils/index.esm.js';
 import { from } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js';
 import { createError } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js';
 import { freeze } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js';
 import { createSet } from './_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js';
 
+/**
+ * Reports whether a value is a non-primitive, the only kind of value these lists accept.
+ *
+ * @param value - The value a caller tried to push.
+ * @returns True when the value is a non-null object or a function.
+ */
+const isNonPrimitive$1 = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
 /**
  * Creates a FIFO (First-In-First-Out) list.
  *
@@ -19,16 +25,19 @@ import { createSet } from './_dependencies/@hyperfrontend/immutable-api-utils/bu
  *
  * 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 push = (item) => {
-        if (getType(item) !== 'object') {
-            throw createError('A fifo list only non-primitive values');
+        if (!isNonPrimitive$1(item)) {
+            throw createError('A fifo list only supports non-primitive values');
         }
         if (list.has(item)) {
-            throw createError('Cannot a item that already exists');
+            throw createError('Cannot push an item that already exists in the list');
         }
         list.add(item);
     };
@@ -60,6 +69,13 @@ function createFifoList() {
     return freeze(result);
 }
 
+/**
+ * Reports whether a value is a non-primitive, the only kind of value these lists accept.
+ *
+ * @param value - The value a caller tried to push.
+ * @returns True when the value is a non-null object or a function.
+ */
+const isNonPrimitive = (value) => (typeof value === 'object' && value !== null) || typeof value === 'function';
 /**
  * Creates a LIFO (Last-In-First-Out) list.
  *
@@ -80,7 +96,7 @@ function createFifoList() {
 function createLifoList() {
     const list = createSet();
     const push = (item) => {
-        if (getType(item) !== 'object') {
+        if (!isNonPrimitive(item)) {
             throw createError('A lifo list only supports non-primitive values');
         }
         list.add(item);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfrontend/list-utils",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "Purpose-built collection utilities for queue management, filtering, and iteration patterns.",
   "license": "MIT",
   "sideEffects": false,