@hyperfrontend/list-utils 0.0.5 → 0.1.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.0](https://github.com/AndrewRedican/hyperfrontend/compare/5f116abb8ba6355dfb283fa03b7481e5eb029480...cc16961a470190848f71a7cce41f7377bc4511a4) - 2026-08-25
+
+### Breaking Changes
+
+- **BREAKING** type fifo pull as T | undefined, reword throws
+
+### Bug Fixes
+
+- **BREAKING** type fifo pull as T | undefined, reword throws
+
 ## [0.0.5](https://github.com/AndrewRedican/hyperfrontend/compare/c8db08be8b183addd26caf81fdd17fb3693f296f...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
 ### Other

package/README.md

@@ -36,6 +36,7 @@
 Purpose-built collection utilities for queue management, filtering, and iteration patterns.
 
 • 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/utils/list/)
+• 👉 See [**guides & tutorials**](https://www.hyperfrontend.dev/docs/guides/?package=%40hyperfrontend%2Flist-utils)
 
 ## What is @hyperfrontend/list-utils?
 
@@ -60,11 +61,11 @@ Queue implementations return frozen objects to prevent external mutation while u
 
 ### Prevents Queue Bugs in Event-Driven Systems
 
-Native arrays don't enforce uniqueness, making it easy to accidentally register the same event handler, task, or subscription multiple times. FIFO/LIFO lists automatically reject duplicates based on reference equality, eliminating a common source of memory leaks and duplicate processing in event loops, job queues, and observer patterns.
+Native arrays don't enforce uniqueness, making it easy to accidentally register the same event handler, task, or subscription multiple times. Both list kinds reject duplicates based on reference equality, eliminating a common source of memory leaks and duplicate processing in event loops, job queues, and observer patterns. A FIFO list throws on a duplicate push; a LIFO list ignores it.
 
 ### Simplifies Round-Robin and Cyclical Patterns
 
-The value picker solves the boilerplate problem of cycling through options (load balancer endpoints, color schemes, retry strategies). No manual index tracking or modulo math—just call `next()`. Particularly useful for testing scenarios where you need predictable value rotation.
+The value picker solves the boilerplate problem of cycling through options (load balancer endpoints, color schemes, retry strategies). No manual index tracking or modulo math, just call `next()`. Particularly useful for testing scenarios where you need predictable value rotation.
 
 ### Type-Safe String Sanitization
 
@@ -89,7 +90,7 @@ import { createFifoList, createValuePicker, nonEmptyStrings, uniqueStrings } fro
 const taskQueue = createFifoList<{ id: string; execute: () => void }>()
 taskQueue.push({ id: 'task1', execute: () => console.log('Task 1') })
 taskQueue.push({ id: 'task2', execute: () => console.log('Task 2') })
-const nextTask = taskQueue.pull() // Gets task1 (first in)
+const nextTask = taskQueue.pull() // Gets task1 (first in), or undefined once the queue is drained
 
 // Round-robin value picker
 const colorPicker = createValuePicker(['red', 'blue', 'green'])

package/SECURITY.md

@@ -1,5 +1,28 @@
 # Security Policy
 
+## The Security Model
+
+Before reporting or reviewing, read the model this project is built on:
+**[Security Model](https://www.hyperfrontend.dev/docs/core-concepts/security)**. It is the canonical
+statement of what hyperfrontend defends against and what it does not, and it is the reference every
+other security claim in these docs points back to. In short:
+
+- **The named adversary is co-resident script**: an analytics snippet, tag manager, compromised
+  dependency, or unknown page that embeds a feature URL. A host that deliberately installs a feature
+  is trusting it, the way it trusts any dependency; the controls exist to bound a trusted
+  feature's bad day, not to treat its authors as hostile.
+- **Origin checks authenticate rooms, not speakers.** Once arbitrary script runs inside a page, no
+  message check distinguishes it from the application. Threats inside a page need Content Security
+  Policy, Trusted Types, dependency provenance, and server-side authorisation. That is a different
+  treatment, deliberately outside this model.
+- **Three parties carry the security of an integration.** The browser enforces document isolation
+  and the frame's capability attributes; the protocol enforces the relationship (pinned
+  counterparts, gated handshake, validated payloads, versioned contracts, an optional encrypted
+  envelope); and **you** decide authorisation: `frame-ancestors`, backend checks, HTTPS, the
+  envelope you choose, and the containment posture you set.
+
+A vulnerability report is most useful when it names which of those three the issue defeats.
+
 ## Reporting a Vulnerability
 
 We take the security of hyperfrontend seriously. If you discover a security vulnerability, please help us protect our users by following responsible disclosure practices.
@@ -58,14 +81,30 @@ Thank you for helping keep hyperfrontend and its users safe!
 
 ## Security Best Practices
 
-When using hyperfrontend in your applications:
-
-1. **Keep Dependencies Updated**: Regularly update to the latest version to receive security patches
-2. **Content Security Policy**: Implement appropriate CSP headers when embedding features
-3. **Input Validation**: Validate and sanitize all data passed between features
-4. **Origin Verification**: Always verify the origin of messages in cross-frame communication
-5. **Authentication**: Implement proper authentication and authorization for sensitive features
-6. **HTTPS**: Always serve hyperfrontend features over HTTPS in production
+These are the decisions the SDK cannot make for you. Everything the protocol already enforces —
+origin pinning, window binding, instance identity, the gated handshake, payload validation on both
+ends — is on by default and is not something you should be re-implementing by hand.
+
+1. **Restrict who may embed the feature.** Send
+   `Content-Security-Policy: frame-ancestors <hosts>` on the response that serves the feature
+   document. Origin pinning keeps a conversation consistent; only `frame-ancestors` decides whether
+   a page was ever allowed to frame you.
+2. **Authorise on the server.** A message that crossed the boundary is not an authorised operation.
+   Protected work needs credentials the feature's own backend validates.
+3. **Choose the envelope deliberately.** `v2` with a pre-shared key is the confidentiality control;
+   `v1` is time-window obfuscation and buys deterrence only. Provision and rotate the `v2` key
+   yourself; a key is never baked into a built artifact. A handshake that cannot agree on an
+   encrypted transport falls back to plaintext; where that would be unacceptable, drive
+   `@hyperfrontend/nexus` directly and set `security.mode: 'fail-closed'` on the channel so the
+   connection is denied instead.
+4. **Declare schemas and a contract version.** Actions without a schema pass unvalidated, and a side
+   without a version always passes the compatibility gate. Both are how drift is caught early.
+5. **Grant capability narrowly.** Delegate only the Permissions-Policy features the integration
+   needs, and price a `sandbox` posture against what the product actually requires.
+6. **Serve everything over HTTPS**, host and feature alike.
+7. **Keep dependencies updated** on both sides of the boundary, and pair that with the page-integrity
+   controls this model deliberately leaves to you: Content Security Policy, Trusted Types,
+   Subresource Integrity, and dependency provenance.
 
 ## Security Updates
 
@@ -73,10 +112,6 @@ Security updates will be released as patch versions and documented in the [CHANG
 
 ## Supported Versions
 
-We currently provide security updates for:
-
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.0.x   | :white_check_mark: |
-
-As the project matures, we will update this table to reflect our long-term support policy.
+Security updates are provided for the latest published version of each `@hyperfrontend/*` package.
+Older releases receive no backports. A long-term support policy will replace this section once the
+packages settle on a stable release cadence.

package/bundle/index.iife.js

@@ -1,86 +1,19 @@
 var HyperfrontendListUtils = (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';
@@ -96,48 +29,18 @@ var HyperfrontendListUtils = (function (exports) {
         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' }
-     * ```
-     */
     function createFifoList() {
         const list = createSet();
         const push = (item) => {
             if (getType(item) !== 'object') {
-                throw createError('A fifo list only non-primitive values');
+                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);
         };
@@ -169,23 +72,6 @@ var HyperfrontendListUtils = (function (exports) {
         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 }
-     * ```
-     */
     function createLifoList() {
         const list = createSet();
         const push = (item) => {
@@ -226,21 +112,6 @@ var HyperfrontendListUtils = (function (exports) {
         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) {
@@ -249,42 +120,16 @@ var HyperfrontendListUtils = (function (exports) {
         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();
@@ -297,53 +142,15 @@ var HyperfrontendListUtils = (function (exports) {
         };
     }
 
-    /* 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.iife.min.js

@@ -1 +1 @@
-var HyperfrontendListUtils=function(e){"use strict";const t=globalThis.Array,r=t.isArray,n=t.from,o=globalThis.Error,i=globalThis.Reflect,l=(e,t)=>i.construct(o,[e,t]),s=globalThis.Object.freeze,a=[],u=e=>{if(null===e)return"null";const t=typeof e;if("object"===t){if(r(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]:[]);return e.createFifoList=function(){const e=h();return s({push:t=>{if("object"!==u(t))throw l("A fifo list only non-primitive values");if(e.has(t))throw l("Cannot a item that already exists");e.add(t)},pull:()=>{const t=e.values().next().value;return e.delete(t),t},map:t=>n(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 s({push:t=>{if("object"!==u(t))throw l("A lifo list only supports non-primitive values");e.add(t)},pull:()=>{const t=n(e).pop();return t&&e.delete(t),t},map:t=>n(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 r=[];for(let n=e;n<=t;n+=1)r.push(n);return r},e.createValuePicker=function(e){if(!e||!e.length)throw l("Expected values not to be an empty list.");let t=-1;function r(){return t<0&&(t=0),e[t]}return{current:r,next:function(){return t<0?r():(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 n(h(e))},e}({});
+var HyperfrontendListUtils=function(e){"use strict";const t=globalThis.Array,r=t.isArray,n=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(r(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]:[]);return e.createFifoList=function(){const e=h();return l({push:t=>{if("object"!==u(t))throw s("A fifo list only supports non-primitive values");if(e.has(t))throw s("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:t=>n(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=n(e).pop();return t&&e.delete(t),t},map:t=>n(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 r=[];for(let n=e;n<=t;n+=1)r.push(n);return r},e.createValuePicker=function(e){if(!e||!e.length)throw s("Expected values not to be an empty list.");let t=-1;function r(){return t<0&&(t=0),e[t]}return{current:r,next:function(){return t<0?r():(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 n(h(e))},e}({});

package/bundle/index.umd.js

@@ -4,86 +4,19 @@
     (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';
@@ -99,48 +32,18 @@
         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' }
-     * ```
-     */
     function createFifoList() {
         const list = createSet();
         const push = (item) => {
             if (getType(item) !== 'object') {
-                throw createError('A fifo list only non-primitive values');
+                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,23 +75,6 @@
         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 }
-     * ```
-     */
     function createLifoList() {
         const list = createSet();
         const push = (item) => {
@@ -229,21 +115,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 +123,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 +145,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,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 supports non-primitive values");if(e.has(t))throw s("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: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))}});

package/index.cjs.js

@@ -21,16 +21,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');
+            throw index_cjs_js$3.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$3.createError('Cannot push an item that already exists in the list');
         }
         list.add(item);
     };

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

@@ -19,16 +19,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');
+            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);
     };

package/package.json

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