list-toolkit 2.2.6 → 2.3.0

package/src/list-utils.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Validate that a circular DLL is well-formed (every next/prev pair is consistent).
+ * @param list - Head node of the circular list (must have `nextName` and `prevName`).
+ * @returns `true` if the list is valid.
+ */
+export function isValidList(list: object): boolean;
+
+/**
+ * Validate that a circular SLL is well-formed (every next link is truthy and loops back).
+ * @param list - Head node of the circular list (must have `nextName`).
+ * @returns `true` if the list is valid.
+ */
+export function isValidSList(list: object): boolean;
+
+/**
+ * Push values to the front of a list one by one.
+ * @param list - List with a `pushFront` method.
+ * @param values - Iterable of values to push.
+ * @returns The list.
+ */
+export function pushValuesFront<L extends object>(list: L, values: Iterable<any>): L;
+
+/**
+ * Push values to the back of a list one by one.
+ * @param list - List with a `pushBack` method.
+ * @param values - Iterable of values to push.
+ * @returns The list.
+ */
+export function pushValuesBack<L extends object>(list: L, values: Iterable<any>): L;
+
+/**
+ * Append values to the front of a list, using `appendFront` if compatible, otherwise `pushFront`.
+ * @param list - List with `pushFront` and optionally `appendFront`.
+ * @param values - Iterable or compatible list of values.
+ * @returns The list.
+ */
+export function appendValuesFront<L extends object>(list: L, values: Iterable<any>): L;
+
+/**
+ * Append values to the back of a list, using `appendBack` if compatible, otherwise `pushBack`.
+ * @param list - List with `pushBack` and optionally `appendBack`.
+ * @param values - Iterable or compatible list of values.
+ * @returns The list.
+ */
+export function appendValuesBack<L extends object>(list: L, values: Iterable<any>): L;
+
+/**
+ * Add values before a pointer position one by one.
+ * @param ptr - Pointer with an `addBefore` method.
+ * @param values - Iterable of values to add.
+ * @returns The pointer.
+ */
+export function addValuesBefore<P extends object>(ptr: P, values: Iterable<any>): P;
+
+/**
+ * Add values after a pointer position one by one.
+ * @param ptr - Pointer with an `addAfter` method.
+ * @param values - Iterable of values to add.
+ * @returns The pointer.
+ */
+export function addValuesAfter<P extends object>(ptr: P, values: Iterable<any>): P;
+
+/**
+ * Insert values before a pointer, using `insertBefore` if compatible, otherwise `addBefore`.
+ * @param ptr - Pointer with `addBefore` and optionally `insertBefore`.
+ * @param values - Iterable of values to insert.
+ * @returns The pointer.
+ */
+export function insertValuesBefore<P extends object>(ptr: P, values: Iterable<any>): P;
+
+/**
+ * Insert values after a pointer, using `insertAfter` if compatible, otherwise `addAfter`.
+ * @param ptr - Pointer with `addAfter` and optionally `insertAfter`.
+ * @param values - Iterable of values to insert.
+ * @returns The pointer.
+ */
+export function insertValuesAfter<P extends object>(ptr: P, values: Iterable<any>): P;
+
+/**
+ * Find the first node matching a condition.
+ * @param list - List with a `getNodeIterator` method.
+ * @param condition - Predicate receiving each node.
+ * @returns The matching node, or `null`.
+ */
+export function findNodeBy<T extends object>(list: object, condition: (node: T) => boolean): T | null;
+
+/**
+ * Find the first pointer whose node matches a condition.
+ * @param list - List with a `getPtrIterator` method.
+ * @param condition - Predicate receiving each node.
+ * @returns The matching pointer, or `null`.
+ */
+export function findPtrBy(list: object, condition: (node: object) => boolean): object | null;
+
+/**
+ * Remove the first node matching a condition.
+ * @param list - List with a `getPtrIterator` method.
+ * @param condition - Predicate receiving each node.
+ * @returns The removed node, or `null`.
+ */
+export function removeNodeBy(list: object, condition: (node: object) => boolean): object | null;
+
+/** Adapter returned by {@link backPusher}. */
+export interface PusherAdapter {
+  /** Next link property name. */
+  nextName: string;
+  /** Previous link property name. */
+  prevName: string;
+  /** Push a node to the back and return it. */
+  pushBackNode(node: object): object;
+  /** Release the accumulated list. */
+  releaseList(): object;
+}
+
+/** Adapter returned by {@link frontPusher}. */
+export interface FrontPusherAdapter {
+  /** Next link property name. */
+  nextName: string;
+  /** Previous link property name. */
+  prevName: string;
+  /** Push a node to the front and return it. */
+  pushFrontNode(node: object): object;
+  /** Release the accumulated list. */
+  releaseList(): object;
+}
+
+/**
+ * Create an adapter that accumulates nodes pushed to the back.
+ * @param ExtListClass - External list constructor.
+ * @param options - Link property names.
+ * @returns A pusher adapter.
+ */
+export function backPusher(ExtListClass: new (...args: any[]) => any, options?: object): PusherAdapter;
+
+/**
+ * Create an adapter that accumulates nodes pushed to the front.
+ * @param ExtListClass - External list constructor.
+ * @param options - Link property names.
+ * @returns A pusher adapter.
+ */
+export function frontPusher(ExtListClass: new (...args: any[]) => any, options?: object): FrontPusherAdapter;

package/src/list-utils.js

@@ -1,5 +1,8 @@
-'use strict';
-
+/**
+ * Validate that a circular DLL is well-formed (every next/prev pair is consistent).
+ * @param {object} list - Head node of the circular list (must have `nextName` and `prevName`).
+ * @returns {boolean} `true` if the list is valid.
+ */
 export const isValidList = list => {
   let current = list;
   do {
@@ -10,6 +13,11 @@ export const isValidList = list => {
   return true;
 };
 
+/**
+ * Validate that a circular SLL is well-formed (every next link is truthy and loops back).
+ * @param {object} list - Head node of the circular list (must have `nextName`).
+ * @returns {boolean} `true` if the list is valid.
+ */
 export const isValidSList = list => {
   let current = list;
   do {
@@ -20,6 +28,12 @@ export const isValidSList = list => {
   return true;
 };
 
+/**
+ * Push values to the front of a list one by one.
+ * @param {object} list - List with a `pushFront` method.
+ * @param {Iterable} values - Iterable of values to push.
+ * @returns {object} The list.
+ */
 export const pushValuesFront = (list, values) => {
   for (const value of values) {
     list.pushFront(value);
@@ -27,6 +41,12 @@ export const pushValuesFront = (list, values) => {
   return list;
 };
 
+/**
+ * Push values to the back of a list one by one.
+ * @param {object} list - List with a `pushBack` method.
+ * @param {Iterable} values - Iterable of values to push.
+ * @returns {object} The list.
+ */
 export const pushValuesBack = (list, values) => {
   for (const value of values) {
     list.pushBack(value);
@@ -34,6 +54,12 @@ export const pushValuesBack = (list, values) => {
   return list;
 };
 
+/**
+ * Append values to the front of a list, using `appendFront` if compatible, otherwise `pushFront`.
+ * @param {object} list - List with `pushFront` and optionally `appendFront`.
+ * @param {Iterable} values - Iterable or compatible list of values.
+ * @returns {object} The list.
+ */
 export const appendValuesFront = (list, values) => {
   if (typeof list.appendFront == 'function' && list.isCompatible(values)) {
     list.appendFront(values);
@@ -46,6 +72,12 @@ export const appendValuesFront = (list, values) => {
   return list;
 };
 
+/**
+ * Append values to the back of a list, using `appendBack` if compatible, otherwise `pushBack`.
+ * @param {object} list - List with `pushBack` and optionally `appendBack`.
+ * @param {Iterable} values - Iterable or compatible list of values.
+ * @returns {object} The list.
+ */
 export const appendValuesBack = (list, values) => {
   if (typeof list.appendBack == 'function' && list.isCompatible(values)) {
     list.appendBack(values);
@@ -54,6 +86,12 @@ export const appendValuesBack = (list, values) => {
   return pushValuesBack(list, values);
 };
 
+/**
+ * Add values before a pointer position one by one.
+ * @param {object} ptr - Pointer with an `addBefore` method.
+ * @param {Iterable} values - Iterable of values to add.
+ * @returns {object} The pointer.
+ */
 export const addValuesBefore = (ptr, values) => {
   for (const value of values) {
     ptr.addBefore(value);
@@ -61,6 +99,12 @@ export const addValuesBefore = (ptr, values) => {
   return ptr;
 };
 
+/**
+ * Add values after a pointer position one by one.
+ * @param {object} ptr - Pointer with an `addAfter` method.
+ * @param {Iterable} values - Iterable of values to add.
+ * @returns {object} The pointer.
+ */
 export const addValuesAfter = (ptr, values) => {
   for (const value of values) {
     ptr.addAfter(value);
@@ -68,6 +112,12 @@ export const addValuesAfter = (ptr, values) => {
   return ptr;
 };
 
+/**
+ * Insert values before a pointer, using `insertBefore` if compatible, otherwise `addBefore`.
+ * @param {object} ptr - Pointer with `addBefore` and optionally `insertBefore`.
+ * @param {Iterable} values - Iterable of values to insert.
+ * @returns {object} The pointer.
+ */
 export const insertValuesBefore = (ptr, values) => {
   if (typeof ptr.insertBefore == 'function' && ptr.list.isCompatible(values)) {
     ptr.insertBefore(ptr.list.makeFrom(values));
@@ -76,6 +126,12 @@ export const insertValuesBefore = (ptr, values) => {
   return addValuesBefore(ptr, values);
 };
 
+/**
+ * Insert values after a pointer, using `insertAfter` if compatible, otherwise `addAfter`.
+ * @param {object} ptr - Pointer with `addAfter` and optionally `insertAfter`.
+ * @param {Iterable} values - Iterable of values to insert.
+ * @returns {object} The pointer.
+ */
 export const insertValuesAfter = (ptr, values) => {
   if (typeof ptr.insertAfter == 'function' && ptr.list.isCompatible(values)) {
     ptr.insertAfter(ptr.list.makeFrom(values));
@@ -88,6 +144,12 @@ export const insertValuesAfter = (ptr, values) => {
   return ptr;
 };
 
+/**
+ * Find the first node matching a condition.
+ * @param {object} list - List with a `getNodeIterator` method.
+ * @param {Function} condition - Predicate receiving each node.
+ * @returns {object|null} The matching node, or `null`.
+ */
 export const findNodeBy = (list, condition) => {
   for (const node of list.getNodeIterator()) {
     if (condition(node)) return node;
@@ -95,6 +157,12 @@ export const findNodeBy = (list, condition) => {
   return null;
 };
 
+/**
+ * Find the first pointer whose node matches a condition.
+ * @param {object} list - List with a `getPtrIterator` method.
+ * @param {Function} condition - Predicate receiving each node.
+ * @returns {object|null} The matching pointer, or `null`.
+ */
 export const findPtrBy = (list, condition) => {
   for (const ptr of list.getPtrIterator()) {
     if (condition(ptr.node)) return ptr;
@@ -102,6 +170,12 @@ export const findPtrBy = (list, condition) => {
   return null;
 };
 
+/**
+ * Remove the first node matching a condition.
+ * @param {object} list - List with a `getPtrIterator` method.
+ * @param {Function} condition - Predicate receiving each node.
+ * @returns {object|null} The removed node, or `null`.
+ */
 export const removeNodeBy = (list, condition) => {
   for (const ptr of list.getPtrIterator()) {
     if (condition(ptr.node)) return ptr.removeCurrent();
@@ -109,6 +183,12 @@ export const removeNodeBy = (list, condition) => {
   return null;
 };
 
+/**
+ * Create an adapter that accumulates nodes pushed to the back.
+ * @param {Function} ExtListClass - External list constructor.
+ * @param {object} [options] - Link property names.
+ * @returns {{nextName: string, prevName: string, pushBackNode: Function, releaseList: Function}} A pusher adapter.
+ */
 export const backPusher = (ExtListClass, options) => {
   const list = new ExtListClass(null, options),
     adapter = {
@@ -126,6 +206,12 @@ export const backPusher = (ExtListClass, options) => {
   return adapter;
 };
 
+/**
+ * Create an adapter that accumulates nodes pushed to the front.
+ * @param {Function} ExtListClass - External list constructor.
+ * @param {object} [options] - Link property names.
+ * @returns {{nextName: string, prevName: string, pushFrontNode: Function, releaseList: Function}} A pusher adapter.
+ */
 export const frontPusher = (ExtListClass, options) => {
   const list = new ExtListClass(null, options),
     adapter = {
@@ -134,7 +220,7 @@ export const frontPusher = (ExtListClass, options) => {
 
       pushFrontNode: node => list.addNodeAfter(node).node,
 
-      releaseList: () => this.make(list.detach())
+      releaseList: () => list.make(list.detach())
     };
   return adapter;
 };

package/src/list.d.ts

@@ -0,0 +1,3 @@
+export * from './list/core.js';
+import List from './list/core.js';
+export default List;

package/src/list.js

@@ -1,5 +1,3 @@
-'use strict';
-
 export * from './list/core.js';
 import List from './list/core.js';
 

package/src/meta-utils.d.ts

@@ -0,0 +1,212 @@
+/**
+ * Capitalize the first letter of a string.
+ * @param name - Input string.
+ * @returns The capitalized string.
+ */
+export function capitalize(name: string): string;
+
+/**
+ * Convert an array of name parts to camelCase.
+ * @param names - Name parts.
+ * @returns The camelCase string.
+ */
+export function toCamelCase(names: string[]): string;
+
+/**
+ * Split a camelCase string into parts.
+ * @param name - camelCase string.
+ * @returns Array of name parts.
+ */
+export function fromCamelCase(name: string): string[];
+
+/**
+ * Convert an array of name parts to PascalCase.
+ * @param names - Name parts.
+ * @returns The PascalCase string.
+ */
+export function toPascalCase(names: string[]): string;
+
+/**
+ * Split a PascalCase string into parts.
+ * @param name - PascalCase string.
+ * @returns Array of name parts.
+ */
+export function fromPascalCase(name: string): string[];
+
+/**
+ * Convert an array of name parts to ALL_CAPS_SNAKE_CASE.
+ * @param names - Name parts.
+ * @returns The ALL_CAPS_SNAKE_CASE string.
+ */
+export function toAllCapsSnakeCase(names: string[]): string;
+
+/**
+ * Convert an array of name parts to snake_case.
+ * @param names - Name parts.
+ * @returns The snake_case string.
+ */
+export function toSnakeCase(names: string[]): string;
+
+/**
+ * Split a snake_case string into parts.
+ * @param name - snake_case string.
+ * @returns Array of name parts.
+ */
+export function fromSnakeCase(name: string): string[];
+
+/**
+ * Convert an array of name parts to kebab-case.
+ * @param names - Name parts.
+ * @returns The kebab-case string.
+ */
+export function toKebabCase(names: string[]): string;
+
+/**
+ * Split a kebab-case string into parts.
+ * @param name - kebab-case string.
+ * @returns Array of name parts.
+ */
+export function fromKebabCase(name: string): string[];
+
+/** Default property descriptor: configurable and enumerable. */
+export const defaultDescriptor: PropertyDescriptor;
+
+/**
+ * Create a property descriptor from a getter function.
+ * @param getter - Getter function.
+ * @param defaultDescriptor - Base descriptor to extend.
+ * @returns A property descriptor with `get`.
+ */
+export function fromGetter(getter: (() => any) | undefined, defaultDescriptor?: PropertyDescriptor): PropertyDescriptor;
+
+/**
+ * Create a property descriptor from a setter function.
+ * @param setter - Setter function.
+ * @param defaultDescriptor - Base descriptor to extend.
+ * @returns A property descriptor with `set`.
+ */
+export function fromSetter(setter: ((v: any) => void) | undefined, defaultDescriptor?: PropertyDescriptor): PropertyDescriptor;
+
+/**
+ * Create a property descriptor from getter and setter functions.
+ * @param getter - Getter function.
+ * @param setter - Setter function.
+ * @param defaultDescriptor - Base descriptor to extend.
+ * @returns A property descriptor with `get` and/or `set`.
+ */
+export function fromAccessors(
+  getter: (() => any) | undefined,
+  setter: ((v: any) => void) | undefined,
+  defaultDescriptor?: PropertyDescriptor
+): PropertyDescriptor;
+
+/**
+ * Define a property descriptor on a target for one or more names.
+ * @param target - Object to define properties on.
+ * @param names - Comma-separated string, array, or single name/symbol.
+ * @param descriptor - Property descriptor to apply.
+ * @param force - If `true`, overwrite existing own properties.
+ * @returns The target object.
+ */
+export function addDescriptor(target: object, names: string | PropertyKey[], descriptor: PropertyDescriptor | undefined, force?: boolean): object;
+
+/**
+ * Define multiple property descriptors on a target.
+ * @param target - Object to define properties on.
+ * @param dict - Map of comma-separated names to descriptors.
+ * @param force - If `true`, overwrite existing own properties.
+ */
+export function addDescriptors(target: object, dict: Record<string, PropertyDescriptor>, force?: boolean): void;
+
+/**
+ * Define an accessor (getter/setter) on a target.
+ * @param target - Object to define the accessor on.
+ * @param names - Comma-separated string, array, or single name/symbol.
+ * @param getter - Getter function.
+ * @param setter - Setter function.
+ * @param force - If `true`, overwrite existing own properties.
+ * @returns The target object.
+ */
+export function addAccessor(
+  target: object,
+  names: string | PropertyKey[],
+  getter: (() => any) | undefined,
+  setter: ((v: any) => void) | undefined,
+  force?: boolean
+): object;
+
+/**
+ * Define multiple getter-based descriptors on a target.
+ * @param target - Object to define getters on.
+ * @param dict - Map of comma-separated names to getter functions.
+ * @param force - If `true`, overwrite existing own properties.
+ */
+export function addGetters(target: object, dict: Record<string, () => any>, force?: boolean): void;
+
+/**
+ * Copy property descriptors from a source to a target.
+ * @param target - Destination object.
+ * @param source - Source object.
+ * @param names - Names to copy (string, symbol, array, or alias map).
+ * @param force - If `true`, overwrite existing own properties.
+ * @returns The target object.
+ */
+export function copyDescriptors(
+  target: object,
+  source: object,
+  names: string | symbol | PropertyKey[] | Record<string, string | PropertyKey[]>,
+  force?: boolean
+): object;
+
+/**
+ * Create an alias for an existing property.
+ * @param object - Object owning the property.
+ * @param name - Original property name.
+ * @param aliases - Comma-separated alias names or array.
+ * @param force - If `true`, overwrite existing own properties.
+ * @returns The object.
+ */
+export function addAlias(object: object, name: PropertyKey, aliases: string | PropertyKey[], force?: boolean): object;
+
+/**
+ * Create multiple aliases from a dictionary.
+ * @param object - Object owning the properties.
+ * @param dict - Map of original names to comma-separated alias strings.
+ * @param force - If `true`, overwrite existing own properties.
+ * @returns The object.
+ */
+export function addAliases(object: object, dict: Record<string, string>, force?: boolean): object;
+
+/**
+ * Ensure an iterator object has a `[Symbol.iterator]` method.
+ * @param iterator - Iterator to augment.
+ * @returns The augmented iterator.
+ */
+export function augmentIterator<T>(iterator: Iterator<T>): IterableIterator<T>;
+
+/**
+ * Normalize an iterator, using `Iterator.from` when available.
+ * @param iterator - Iterator to normalize.
+ * @returns An iterable iterator.
+ */
+export function normalizeIterator<T>(iterator: Iterator<T>): IterableIterator<T>;
+
+/**
+ * Map over an iterator, producing a new iterable.
+ * @param iterator - Source iterable iterator.
+ * @param callbackFn - Mapping function receiving value and index.
+ * @returns An iterable of mapped values.
+ */
+export function mapIterator<T, U>(iterator: Iterable<T>, callbackFn: (value: T, index: number) => U): Iterable<U>;
+
+/** Map of `typeof` results that can have properties set on them. */
+export const canHaveProps: Record<string, number>;
+
+/**
+ * Copy option keys from a pattern and optional sources onto a target.
+ * @param target - Target object (created if falsy).
+ * @param pattern - Object defining which keys to copy and their defaults.
+ * @param sources - Additional source objects to override values from.
+ * @returns The target object.
+ */
+export function copyOptions<T extends object>(target: T | null | undefined, pattern: T, ...sources: Array<Partial<T> | null | undefined>): T;