@hyperfrontend/list-utils 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,16 +1,24 @@
 # Changelog
 
-This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+All notable changes to this project will be documented in this file.
 
-## [0.0.4](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.3...lib-list-utils@0.0.4) (2026-03-08)
+## [0.0.5](https://github.com/AndrewRedican/hyperfrontend/compare/c8db08be8b183addd26caf81fdd17fb3693f296f...466c0388c4cd516b9c704214140b4df1004098e6) - 2026-06-23
 
-## [0.0.3](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.2...lib-list-utils@0.0.3) (2026-03-02)
+### Other
 
+- **@hyperfrontend/workspace:** remove lib-builder and tool-package as implicit dependencies for all lib projects
+
+## [0.0.4](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.3...lib-list-utils@0.0.4) - 2026-03-08
+
+
+## [0.0.3](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.2...lib-list-utils@0.0.3) - 2026-03-02
 
 ### Bug Fixes
 
-* **lib-list-utils:** correct package exports ([5966537](https://github.com/AndrewRedican/hyperfrontend/commit/5966537bda3addd6d3bc22bb7b2e9a5cfef7c247))
+- **lib-list-utils:** correct package exports ([5966537](https://github.com/AndrewRedican/hyperfrontend/commit/5966537bda3addd6d3bc22bb7b2e9a5cfef7c247))
+
+## [0.0.2](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.1...lib-list-utils@0.0.2) - 2026-02-26
+
 
-## [0.0.2](https://github.com/AndrewRedican/hyperfrontend/compare/lib-list-utils@0.0.1...lib-list-utils@0.0.2) (2026-02-26)
+## 0.0.1 - 2026-02-15
 
-## 0.0.1 (2026-02-15)

package/README.md

@@ -35,6 +35,8 @@
 
 Purpose-built collection utilities for queue management, filtering, and iteration patterns.
 
+• 👉 See [**documentation**](https://www.hyperfrontend.dev/docs/libraries/utils/list/)
+
 ## What is @hyperfrontend/list-utils?
 
 @hyperfrontend/list-utils provides specialized collection utilities focused on common programming patterns that native JavaScript arrays don't handle elegantly. Rather than replicating lodash, this library targets specific use cases: FIFO/LIFO queue management with object reference tracking, cyclical value iteration, and string array sanitization.
@@ -166,4 +168,4 @@ This library is part of the [hyperfrontend](https://github.com/AndrewRedican/hyp
 
 ## License
 
-MIT
+[MIT](https://github.com/AndrewRedican/hyperfrontend/blob/main/LICENSE.md)

package/_dependencies/@hyperfrontend/data-utils/index.cjs.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const { isArray } = require('../immutable-api-utils/built-in-copy/array/index.cjs.js');
+const { createError } = require('../immutable-api-utils/built-in-copy/error/index.cjs.js');
+const { freeze, keys: keys$1 } = require('../immutable-api-utils/built-in-copy/object/index.cjs.js');
+const { createMap } = require('../immutable-api-utils/built-in-copy/map/index.cjs.js');
+const { createDate } = require('../immutable-api-utils/built-in-copy/date/index.cjs.js');
+const { random, round } = require('../immutable-api-utils/built-in-copy/math/index.cjs.js');
+
+const isMarker = (text) => {
+    if (typeof text !== 'string' || !text.startsWith('__$'))
+        return false;
+    return /^__\$[0-9]+$/.test(text);
+};
+
+const registeredClasses = [];
+const registeredIterableClasses = [
+    {
+        classRef: Array,
+        instantiate: () => [],
+        getKeys: (target) => {
+            const keysArray = keys$1(target);
+            if (getConfig().detectCircularReferences) {
+                return keysArray.filter((key) => !isMarker(key));
+            }
+            return keysArray;
+        },
+        read: (target, key) => target[key],
+        write: (target, value, key) => (target[key] = value),
+        remove: (target, value) => target.splice(value, 1),
+    },
+    {
+        classRef: Object,
+        instantiate: () => ({}),
+        getKeys: (target) => {
+            const keysArray = keys$1(target);
+            if (getConfig().detectCircularReferences) {
+                return keysArray.filter((key) => !isMarker(key));
+            }
+            return keysArray;
+        },
+        read: (target, key) => target[key],
+        write: (target, value, key) => (target[key] = value),
+        remove: (target, value) => delete target[value],
+    },
+];
+let samePositionOfOwnProperties = false;
+let detectCircularReferences = false;
+const getConfig = () => ({
+    samePositionOfOwnProperties,
+    detectCircularReferences,
+});
+
+const getKeysFromIterable = (target, dataType) => {
+    if (dataType === 'array')
+        dataType = Array.name;
+    if (dataType === 'object')
+        dataType = Object.name;
+    const iterableClass = registeredIterableClasses.find(({ classRef }) => dataType === classRef.name);
+    if (iterableClass === undefined)
+        return [];
+    return iterableClass.getKeys(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;
+};
+
+const getIterableTypes = () => registeredIterableClasses.map(({ classRef }) => {
+    const name = classRef.name;
+    if (name === Object.name)
+        return 'object';
+    if (name === Array.name)
+        return 'array';
+    return name;
+});
+
+const isIterableType = (dataType) => getIterableTypes().includes(dataType);
+
+const isIterable = (target) => isIterableType(getType(target));
+
+const marker = () => {
+    const randomValue = round(random() * 10000000000000);
+    const sequential = createDate().getTime();
+    const unique = `${randomValue}${sequential}`;
+    const prefix = `__$`;
+    return `${prefix}${unique}`;
+};
+
+const referenceStack = () => {
+    const records = createMap();
+    const flag = marker();
+    const exists = (ref) => (isIterable(ref) ? flag in ref && records.has(ref[flag]) : false);
+    const add = (ref) => {
+        if (!isIterable(ref) || exists(ref))
+            return;
+        ref[flag] = Symbol();
+        records.set(ref[flag], [flag, ref, records.size]);
+    };
+    const lastSeen = (ref) => {
+        if (!isIterable(ref))
+            return null;
+        const record = records.get(ref[flag]);
+        return record ? record[2] - records.size : null;
+    };
+    const clear = () => (records.forEach(([key, ref]) => {
+        delete ref[key];
+    }),
+        records.clear());
+    return {
+        add: (ref) => add(ref),
+        exists: (ref) => exists(ref),
+        lastSeen: (ref) => lastSeen(ref),
+        clear: () => clear(),
+        get size() {
+            return records.size;
+        },
+    };
+};
+
+const errorMessage = (thing, type) => `Expected ${thing} to be ${type}.`;
+const nextIterationDetails = (path, key, value) => ({
+    nextPath: [...path, key],
+    nextValue: value[key],
+});
+const circularDependencyTraversal = (condition, callback, config, key, path, value, parent, state, stack, root = false) => {
+    if (stack.exists(value))
+        return state;
+    const ok = condition(config, key, value, path, parent);
+    if (config.exitEarly)
+        return state;
+    if (ok)
+        callback(key, value, path, state, parent);
+    stack.add(value);
+    const type = getType(value);
+    if (!isIterableType(type))
+        return state;
+    const keys = getKeysFromIterable(value, type);
+    keys.forEach((key) => {
+        const { nextPath, nextValue } = nextIterationDetails(path, key, value);
+        circularDependencyTraversal(condition, callback, config, key, nextPath, nextValue, value, state, stack);
+    });
+    if (root)
+        stack.clear();
+    return state;
+};
+const nonCircularDependencyTraversal = (condition, callback, config, key, path, value, parent, state) => {
+    const ok = condition(config, key, value, path, parent);
+    if (config.exitEarly)
+        return state;
+    if (ok)
+        callback(key, value, path, state, parent);
+    const type = getType(value);
+    if (!isIterableType(type))
+        return state;
+    const keys = getKeysFromIterable(value, type);
+    keys.forEach((key) => {
+        const { nextPath, nextValue } = nextIterationDetails(path, key, value);
+        nonCircularDependencyTraversal(condition, callback, config, key, nextPath, nextValue, value, state);
+    });
+    return state;
+};
+const traversal = (target, condition, callback, options, state) => {
+    if (typeof callback !== 'function')
+        throw createError(errorMessage('callback', 'a function'));
+    if (!(typeof options === 'object' && !isArray(options)))
+        throw createError(errorMessage('options', 'an object'));
+    if (!isArray(options.depth))
+        throw createError(errorMessage('options.depth', 'an array'));
+    const [startDepth, maxDepth] = options.depth;
+    if (startDepth !== void 0 && typeof startDepth !== 'number')
+        throw createError(errorMessage('options.depth.0', 'a number'));
+    if (maxDepth !== void 0) {
+        const maxDepthType = typeof maxDepth;
+        if (!['number', 'string'].includes(maxDepthType))
+            throw createError(errorMessage('options.depth.1', 'a number or a string'));
+        if (maxDepthType === 'string' && maxDepth !== '*')
+            throw createError("Only valid string value in options.depth.1 is '*'.");
+    }
+    const config = {
+        depth: freeze([options.depth[0] ?? 0, options.depth[1] ?? '*']),
+        exitEarly: false,
+    };
+    const initialArgs = [condition, callback, config, '', [], target, void 0, state];
+    if (getConfig().detectCircularReferences)
+        return circularDependencyTraversal(...initialArgs, referenceStack(), true);
+    return nonCircularDependencyTraversal(...initialArgs);
+};
+const createTraversal = (condition) => (target, callback, options, state) => traversal(target, condition, callback, options ?? { depth: [0, '*'] }, state ?? {});
+const condition = (config, key, value, path) => !(path.length < config.depth[0] || config.depth[1] < path.length);
+const traverseBetweenDepthRange = createTraversal(condition);
+exports.createTraversal = createTraversal;
+exports.getConfig = getConfig;
+exports.getIterableTypes = getIterableTypes;
+exports.getKeysFromIterable = getKeysFromIterable;
+exports.getType = getType;
+exports.isIterable = isIterable;
+exports.isIterableType = isIterableType;
+exports.isMarker = isMarker;
+exports.marker = marker;
+exports.referenceStack = referenceStack;
+exports.registeredClasses = registeredClasses;
+exports.registeredIterableClasses = registeredIterableClasses;

package/_dependencies/@hyperfrontend/data-utils/index.esm.js

@@ -0,0 +1,202 @@
+import { isArray } from '../immutable-api-utils/built-in-copy/array/index.esm.js';
+import { createError } from '../immutable-api-utils/built-in-copy/error/index.esm.js';
+import { keys, freeze } from '../immutable-api-utils/built-in-copy/object/index.esm.js';
+import { createMap } from '../immutable-api-utils/built-in-copy/map/index.esm.js';
+import { createDate } from '../immutable-api-utils/built-in-copy/date/index.esm.js';
+import { round, random } from '../immutable-api-utils/built-in-copy/math/index.esm.js';
+
+const isMarker = (text) => {
+    if (typeof text !== 'string' || !text.startsWith('__$'))
+        return false;
+    return /^__\$[0-9]+$/.test(text);
+};
+
+const registeredClasses = [];
+const registeredIterableClasses = [
+    {
+        classRef: Array,
+        instantiate: () => [],
+        getKeys: (target) => {
+            const keysArray = keys(target);
+            if (getConfig().detectCircularReferences) {
+                return keysArray.filter((key) => !isMarker(key));
+            }
+            return keysArray;
+        },
+        read: (target, key) => target[key],
+        write: (target, value, key) => (target[key] = value),
+        remove: (target, value) => target.splice(value, 1),
+    },
+    {
+        classRef: Object,
+        instantiate: () => ({}),
+        getKeys: (target) => {
+            const keysArray = keys(target);
+            if (getConfig().detectCircularReferences) {
+                return keysArray.filter((key) => !isMarker(key));
+            }
+            return keysArray;
+        },
+        read: (target, key) => target[key],
+        write: (target, value, key) => (target[key] = value),
+        remove: (target, value) => delete target[value],
+    },
+];
+let samePositionOfOwnProperties = false;
+let detectCircularReferences = false;
+const getConfig = () => ({
+    samePositionOfOwnProperties,
+    detectCircularReferences,
+});
+
+const getKeysFromIterable = (target, dataType) => {
+    if (dataType === 'array')
+        dataType = Array.name;
+    if (dataType === 'object')
+        dataType = Object.name;
+    const iterableClass = registeredIterableClasses.find(({ classRef }) => dataType === classRef.name);
+    if (iterableClass === undefined)
+        return [];
+    return iterableClass.getKeys(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;
+};
+
+const getIterableTypes = () => registeredIterableClasses.map(({ classRef }) => {
+    const name = classRef.name;
+    if (name === Object.name)
+        return 'object';
+    if (name === Array.name)
+        return 'array';
+    return name;
+});
+
+const isIterableType = (dataType) => getIterableTypes().includes(dataType);
+
+const isIterable = (target) => isIterableType(getType(target));
+
+const marker = () => {
+    const randomValue = round(random() * 10000000000000);
+    const sequential = createDate().getTime();
+    const unique = `${randomValue}${sequential}`;
+    const prefix = `__$`;
+    return `${prefix}${unique}`;
+};
+
+const referenceStack = () => {
+    const records = createMap();
+    const flag = marker();
+    const exists = (ref) => (isIterable(ref) ? flag in ref && records.has(ref[flag]) : false);
+    const add = (ref) => {
+        if (!isIterable(ref) || exists(ref))
+            return;
+        ref[flag] = Symbol();
+        records.set(ref[flag], [flag, ref, records.size]);
+    };
+    const lastSeen = (ref) => {
+        if (!isIterable(ref))
+            return null;
+        const record = records.get(ref[flag]);
+        return record ? record[2] - records.size : null;
+    };
+    const clear = () => (records.forEach(([key, ref]) => {
+        delete ref[key];
+    }),
+        records.clear());
+    return {
+        add: (ref) => add(ref),
+        exists: (ref) => exists(ref),
+        lastSeen: (ref) => lastSeen(ref),
+        clear: () => clear(),
+        get size() {
+            return records.size;
+        },
+    };
+};
+
+const errorMessage = (thing, type) => `Expected ${thing} to be ${type}.`;
+const nextIterationDetails = (path, key, value) => ({
+    nextPath: [...path, key],
+    nextValue: value[key],
+});
+const circularDependencyTraversal = (condition, callback, config, key, path, value, parent, state, stack, root = false) => {
+    if (stack.exists(value))
+        return state;
+    const ok = condition(config, key, value, path, parent);
+    if (config.exitEarly)
+        return state;
+    if (ok)
+        callback(key, value, path, state, parent);
+    stack.add(value);
+    const type = getType(value);
+    if (!isIterableType(type))
+        return state;
+    const keys = getKeysFromIterable(value, type);
+    keys.forEach((key) => {
+        const { nextPath, nextValue } = nextIterationDetails(path, key, value);
+        circularDependencyTraversal(condition, callback, config, key, nextPath, nextValue, value, state, stack);
+    });
+    if (root)
+        stack.clear();
+    return state;
+};
+const nonCircularDependencyTraversal = (condition, callback, config, key, path, value, parent, state) => {
+    const ok = condition(config, key, value, path, parent);
+    if (config.exitEarly)
+        return state;
+    if (ok)
+        callback(key, value, path, state, parent);
+    const type = getType(value);
+    if (!isIterableType(type))
+        return state;
+    const keys = getKeysFromIterable(value, type);
+    keys.forEach((key) => {
+        const { nextPath, nextValue } = nextIterationDetails(path, key, value);
+        nonCircularDependencyTraversal(condition, callback, config, key, nextPath, nextValue, value, state);
+    });
+    return state;
+};
+const traversal = (target, condition, callback, options, state) => {
+    if (typeof callback !== 'function')
+        throw createError(errorMessage('callback', 'a function'));
+    if (!(typeof options === 'object' && !isArray(options)))
+        throw createError(errorMessage('options', 'an object'));
+    if (!isArray(options.depth))
+        throw createError(errorMessage('options.depth', 'an array'));
+    const [startDepth, maxDepth] = options.depth;
+    if (startDepth !== void 0 && typeof startDepth !== 'number')
+        throw createError(errorMessage('options.depth.0', 'a number'));
+    if (maxDepth !== void 0) {
+        const maxDepthType = typeof maxDepth;
+        if (!['number', 'string'].includes(maxDepthType))
+            throw createError(errorMessage('options.depth.1', 'a number or a string'));
+        if (maxDepthType === 'string' && maxDepth !== '*')
+            throw createError("Only valid string value in options.depth.1 is '*'.");
+    }
+    const config = {
+        depth: freeze([options.depth[0] ?? 0, options.depth[1] ?? '*']),
+        exitEarly: false,
+    };
+    const initialArgs = [condition, callback, config, '', [], target, void 0, state];
+    if (getConfig().detectCircularReferences)
+        return circularDependencyTraversal(...initialArgs, referenceStack(), true);
+    return nonCircularDependencyTraversal(...initialArgs);
+};
+const createTraversal = (condition) => (target, callback, options, state) => traversal(target, condition, callback, options ?? { depth: [0, '*'] }, state ?? {});
+const condition = (config, key, value, path) => !(path.length < config.depth[0] || config.depth[1] < path.length);
+const traverseBetweenDepthRange = createTraversal(condition);
+
+export { createTraversal, getConfig, getIterableTypes, getKeysFromIterable, getType, isIterable, isIterableType, isMarker, marker, referenceStack, registeredClasses, registeredIterableClasses };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const _Array = globalThis.Array;
+const isArray = _Array.isArray;
+const from = _Array.from;
+exports.from = from;
+exports.isArray = isArray;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/array/index.esm.js

@@ -0,0 +1,5 @@
+const _Array = globalThis.Array;
+const isArray = _Array.isArray;
+const from = _Array.from;
+
+export { from, isArray };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.cjs.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+exports.createDate = createDate;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/date/index.esm.js

@@ -0,0 +1,7 @@
+const _Date = globalThis.Date;
+const _Reflect = globalThis.Reflect;
+function createDate(...args) {
+    return _Reflect.construct(_Date, args);
+}
+
+export { createDate };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+exports.createError = createError;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/error/index.esm.js

@@ -0,0 +1,5 @@
+const _Error = globalThis.Error;
+const _Reflect = globalThis.Reflect;
+const createError = (message, options) => _Reflect.construct(_Error, [message, options]);
+
+export { createError };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Map = globalThis.Map;
+const _Reflect = globalThis.Reflect;
+const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
+exports.createMap = createMap;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/map/index.esm.js

@@ -0,0 +1,5 @@
+const _Map = globalThis.Map;
+const _Reflect = globalThis.Reflect;
+const createMap = (iterable) => _Reflect.construct(_Map, iterable ? [iterable] : []);
+
+export { createMap };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const _Math = globalThis.Math;
+const round = _Math.round;
+const random = _Math.random;
+exports.random = random;
+exports.round = round;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/math/index.esm.js

@@ -0,0 +1,5 @@
+const _Math = globalThis.Math;
+const round = _Math.round;
+const random = _Math.random;
+
+export { random, round };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.cjs.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+const keys = _Object.keys;
+exports.freeze = freeze;
+exports.keys = keys;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/object/index.esm.js

@@ -0,0 +1,5 @@
+const _Object = globalThis.Object;
+const freeze = _Object.freeze;
+const keys = _Object.keys;
+
+export { freeze, keys };

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.cjs.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const _Set = globalThis.Set;
+const _Reflect = globalThis.Reflect;
+const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
+exports.createSet = createSet;

package/_dependencies/@hyperfrontend/immutable-api-utils/built-in-copy/set/index.esm.js

@@ -0,0 +1,5 @@
+const _Set = globalThis.Set;
+const _Reflect = globalThis.Reflect;
+const createSet = (iterable) => _Reflect.construct(_Set, iterable ? [iterable] : []);
+
+export { createSet };