list-toolkit 2.2.5 → 2.3.0

package/src/meta-utils.js

@@ -1,32 +1,107 @@
+/**
+ * Capitalize the first letter of a string.
+ * @param {string} name - Input string.
+ * @returns {string} The capitalized string.
+ */
 export const capitalize = name => (name ? name[0].toUpperCase() + name.substring(1).toLowerCase() : name);
 
+/**
+ * Convert an array of name parts to camelCase.
+ * @param {string[]} names - Name parts.
+ * @returns {string} The camelCase string.
+ */
 export const toCamelCase = names => names.map((name, index) => (index ? capitalize(name) : name.toLowerCase())).join('');
+
+/**
+ * Split a camelCase string into parts.
+ * @param {string} name - camelCase string.
+ * @returns {string[]} Array of name parts.
+ */
 export const fromCamelCase = name => name.split(/(?=[A-Z])/g);
 
+/**
+ * Convert an array of name parts to PascalCase.
+ * @param {string[]} names - Name parts.
+ * @returns {string} The PascalCase string.
+ */
 export const toPascalCase = names => names.map(name => capitalize(name)).join('');
+
+/**
+ * Split a PascalCase string into parts.
+ * @param {string} name - PascalCase string.
+ * @returns {string[]} Array of name parts.
+ */
 export const fromPascalCase = name => name.split(/(?=[A-Z])/g);
 
+/**
+ * Convert an array of name parts to ALL_CAPS_SNAKE_CASE.
+ * @param {string[]} names - Name parts.
+ * @returns {string} The ALL_CAPS_SNAKE_CASE string.
+ */
 export const toAllCapsSnakeCase = names => names.map(name => name.toUpperCase()).join('_');
+
+/**
+ * Convert an array of name parts to snake_case.
+ * @param {string[]} names - Name parts.
+ * @returns {string} The snake_case string.
+ */
 export const toSnakeCase = names => names.map(name => name.toLowerCase()).join('_');
+
+/**
+ * Split a snake_case string into parts.
+ * @param {string} name - snake_case string.
+ * @returns {string[]} Array of name parts.
+ */
 export const fromSnakeCase = name => name.split('_');
 
+/**
+ * Convert an array of name parts to kebab-case.
+ * @param {string[]} names - Name parts.
+ * @returns {string} The kebab-case string.
+ */
 export const toKebabCase = names => names.map(name => name.toLowerCase()).join('-');
+
+/**
+ * Split a kebab-case string into parts.
+ * @param {string} name - kebab-case string.
+ * @returns {string[]} Array of name parts.
+ */
 export const fromKebabCase = name => name.split('-');
 
+/** @type {PropertyDescriptor} Default property descriptor: configurable and enumerable. */
 export const defaultDescriptor = {configurable: true, enumerable: true};
 
+/**
+ * Create a property descriptor from a getter function.
+ * @param {Function} [getter] - Getter function.
+ * @param {PropertyDescriptor} [defaultDescriptor] - Base descriptor to extend.
+ * @returns {PropertyDescriptor} A property descriptor with `get`.
+ */
 export const fromGetter = (getter, defaultDescriptor = defaultDescriptor) => {
   const descriptor = {...defaultDescriptor};
   if (typeof getter == 'function') descriptor.get = getter;
   return descriptor;
 };
 
+/**
+ * Create a property descriptor from a setter function.
+ * @param {Function} [setter] - Setter function.
+ * @param {PropertyDescriptor} [defaultDescriptor] - Base descriptor to extend.
+ * @returns {PropertyDescriptor} A property descriptor with `set`.
+ */
 export const fromSetter = (setter, defaultDescriptor = defaultDescriptor) => {
   const descriptor = {...defaultDescriptor};
   if (typeof setter == 'function') descriptor.set = setter;
   return descriptor;
 };
 
+/**
+ * Create a property descriptor from getter and setter functions.
+ * @param {Function} [getter] - Getter function.
+ * @param {Function} [setter] - Setter function.
+ * @param {PropertyDescriptor} [defaultDescriptor] - Base descriptor to extend.
+ * @returns {PropertyDescriptor} A property descriptor with `get` and/or `set`.
+ */
 export const fromAccessors = (getter, setter, defaultDescriptor = defaultDescriptor) => {
   const descriptor = {...defaultDescriptor};
   if (typeof getter == 'function') descriptor.get = getter;
@@ -34,6 +109,14 @@ export const fromAccessors = (getter, setter, defaultDescriptor = defaultDescrip
   return descriptor;
 };
 
+/**
+ * Define a property descriptor on a target for one or more names.
+ * @param {object} target - Object to define properties on.
+ * @param {string|PropertyKey[]} names - Comma-separated string, array, or single name/symbol.
+ * @param {PropertyDescriptor} [descriptor] - Property descriptor to apply.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ * @returns {object} The target object.
+ */
 export const addDescriptor = (target, names, descriptor, force) => {
   if (!descriptor) return target;
   if (typeof names == 'string') names = names.trim().split(/\s*,\s*/);
@@ -45,6 +128,12 @@ export const addDescriptor = (target, names, descriptor, force) => {
   return target;
 };
 
+/**
+ * Define multiple property descriptors on a target.
+ * @param {object} target - Object to define properties on.
+ * @param {Object<string, PropertyDescriptor>} dict - Map of comma-separated names to descriptors.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ */
 export const addDescriptors = (target, dict, force) => {
   for (const [names, descriptor] of Object.entries(dict)) {
     addDescriptor(target, names, descriptor, force);
@@ -56,19 +145,42 @@ export const addDescriptors = (target, dict, force) => {
   }
 };
 
+/**
+ * Define an accessor (getter/setter) on a target.
+ * @param {object} target - Object to define the accessor on.
+ * @param {string|PropertyKey[]} names - Comma-separated string, array, or single name/symbol.
+ * @param {Function} [getter] - Getter function.
+ * @param {Function} [setter] - Setter function.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ * @returns {object} The target object.
+ */
 export const addAccessor = (target, names, getter, setter, force) => addDescriptor(target, names, fromAccessors(getter, setter), force);
 
+/**
+ * Define multiple getter-based descriptors on a target.
+ * @param {object} target - Object to define getters on.
+ * @param {Object<string, Function>} dict - Map of comma-separated names to getter functions.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ */
 export const addGetters = (target, dict, force) => {
   for (const [names, getter] of Object.entries(dict)) {
     addDescriptor(target, names, fromGetter(getter), force);
   }
   for (const symbol of Object.getOwnPropertySymbols(dict)) {
-    const descriptor = Object.getOwnPropertyDescriptor(source, symbol);
+    const descriptor = Object.getOwnPropertyDescriptor(dict, symbol);
     if (!descriptor || !descriptor.enumerable) continue;
     addDescriptor(target, [symbol], fromGetter(dict[symbol]), force);
   }
 };
 
+/**
+ * Copy property descriptors from a source to a target.
+ * @param {object} target - Destination object.
+ * @param {object} source - Source object.
+ * @param {string|symbol|PropertyKey[]|Object<string, string|PropertyKey[]>} names - Names to copy (string, symbol, array, or alias map).
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ * @returns {object} The target object.
+ */
 export const copyDescriptors = (target, source, names, force) => {
   switch (typeof names) {
     case 'string':
@@ -95,10 +207,30 @@ export const copyDescriptors = (target, source, names, force) => {
   return target;
 };
 
+/**
+ * Create an alias for an existing property.
+ * @param {object} object - Object owning the property.
+ * @param {PropertyKey} name - Original property name.
+ * @param {string|PropertyKey[]} aliases - Comma-separated alias names or array.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ * @returns {object} The object.
+ */
 export const addAlias = (object, name, aliases, force) => addDescriptor(object, aliases, Object.getOwnPropertyDescriptor(object, name), force);
 
+/**
+ * Create multiple aliases from a dictionary.
+ * @param {object} object - Object owning the properties.
+ * @param {Object<string, string>} dict - Map of original names to comma-separated alias strings.
+ * @param {boolean} [force] - If `true`, overwrite existing own properties.
+ * @returns {object} The object.
+ */
 export const addAliases = (object, dict, force) => copyDescriptors(object, object, dict, force);
 
+/**
+ * Ensure an iterator object has a `[Symbol.iterator]` method.
+ * @param {Iterator} iterator - Iterator to augment.
+ * @returns {IterableIterator} The augmented iterator.
+ */
 export const augmentIterator = iterator => {
   if (!iterator.hasOwnProperty(Symbol.iterator)) {
     iterator[Symbol.iterator] = function () {
@@ -108,12 +240,23 @@ export const augmentIterator = iterator => {
   return iterator;
 };
 
+/**
+ * Normalize an iterator, using `Iterator.from` when available.
+ * @param {Iterator} iterator - Iterator to normalize.
+ * @returns {IterableIterator} An iterable iterator.
+ */
 let normalizeIterator = augmentIterator;
 if (typeof globalThis.Iterator?.from == 'function') {
   normalizeIterator = iterator => Iterator.from(iterator);
 }
 export {normalizeIterator};
 
+/**
+ * Map over an iterator, producing a new iterable.
+ * @param {Iterable} iterator - Source iterable.
+ * @param {Function} callbackFn - Mapping function receiving value and index.
+ * @returns {Iterable} An iterable of mapped values.
+ */
 export const mapIterator = (iterator, callbackFn) => {
   if (typeof iterator?.map == 'function') return iterator.map(callbackFn);
   return {
@@ -131,8 +274,16 @@ export const mapIterator = (iterator, callbackFn) => {
   };
 };
 
+/** @type {Object<string, number>} Map of `typeof` results that can have properties set on them. */
 export const canHaveProps = {object: 1, function: 1};
 
+/**
+ * Copy option keys from a pattern and optional sources onto a target.
+ * @param {object} target - Target object (created if falsy).
+ * @param {object} pattern - Object defining which keys to copy and their defaults.
+ * @param {...object} sources - Additional source objects to override values from.
+ * @returns {object} The target object.
+ */
 export const copyOptions = (target, pattern, ...sources) => {
   target = target || {};
   const keys = Object.keys(pattern);

package/src/nt-utils.d.ts

@@ -0,0 +1,91 @@
+/** Options for null-terminated list utilities. */
+export interface NTOptions {
+  /** Property name for the next link (default `'next'`). */
+  nextName?: string;
+}
+
+/** Options for null-terminated DLL utilities. */
+export interface NTDllOptions extends NTOptions {
+  /** Property name for the previous link (default `'prev'`). */
+  prevName?: string;
+}
+
+/** A head/tail pair returned by conversion functions. */
+export interface NTListResult<T extends object> {
+  /** First node. */
+  head: T;
+  /** Last node. */
+  tail: T;
+}
+
+/**
+ * Check whether a linked structure is a valid null-terminated list.
+ * @param head - First node, or `null` for an empty list.
+ * @param options - Link property names.
+ * @returns `true` if the list is null-terminated (not circular).
+ */
+export function isNTList<T extends object>(head: T | null, options?: NTOptions): boolean;
+
+/**
+ * Find the tail of a null-terminated list by following next links.
+ * @param head - First node, or `null`.
+ * @param options - Link property names.
+ * @returns The tail node, or `null` if empty or circular.
+ */
+export function getNTListTail<T extends object>(head: T | null, options?: NTOptions): T | null;
+
+/**
+ * Find the head of a null-terminated list by following prev links.
+ * @param node - Any node in the list, or `null`.
+ * @param options - Link property names (uses `prevName`).
+ * @returns The head node, or `null` if empty or circular.
+ */
+export function getNTListHead<T extends object>(node: T | null, options?: { prevName?: string }): T | null;
+
+/**
+ * Count the number of nodes in a null-terminated list.
+ * @param head - First node, or `null`.
+ * @param options - Link property names.
+ * @returns The node count.
+ */
+export function getNTListLength<T extends object>(head: T | null, options?: NTOptions): number;
+
+/**
+ * Convert a null-terminated DLL into a circular DLL.
+ * @param node - Any node in the null-terminated list, or `null`.
+ * @param options - Link property names.
+ * @returns Head/tail pair, or `null` if empty.
+ */
+export function makeListFromNTList<T extends object>(node: T | null, options?: NTDllOptions): NTListResult<T> | null;
+
+/**
+ * Convert a null-terminated SLL into a circular SLL.
+ * @param head - First node, or `null`.
+ * @param options - Link property names.
+ * @returns Head/tail pair, or `null` if empty.
+ */
+export function makeSListFromNTList<T extends object>(head: T | null, options?: NTOptions): NTListResult<T> | null;
+
+/**
+ * Convert a circular DLL into a null-terminated DLL.
+ * @param head - Head of the circular list, or `null`.
+ * @param options - Link property names.
+ * @returns Head/tail pair, or `null` if empty.
+ */
+export function makeNTListFromList<T extends object>(head: T | null, options?: NTDllOptions): NTListResult<T> | null;
+
+/**
+ * Convert a circular SLL into a null-terminated SLL (fast: head becomes second node).
+ * @param head - Head of the circular list, or `null`.
+ * @param options - Link property names.
+ * @returns Head/tail pair, or `null` if empty.
+ */
+export function makeNTListFromSListFast<T extends object>(head: T | null, options?: NTOptions): NTListResult<T> | null;
+
+/**
+ * Convert a circular SLL into a null-terminated SLL (traverses to find the tail).
+ * @param head - Head of the circular list, or `null`.
+ * @param options - Link property names.
+ * @returns Head/tail pair, or `null` if empty.
+ */
+export function makeNTListFromSList<T extends object>(head: T | null, options?: NTOptions): NTListResult<T> | null;

package/src/nt-utils.js

@@ -1,7 +1,10 @@
-'use strict';
-
-// utilities for working with null-terminated lists
-
+/**
+ * Check whether a linked structure is a valid null-terminated list.
+ * @param {object|null} head - First node, or `null` for an empty list.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {boolean} `true` if the list is null-terminated (not circular).
+ */
 export const isNTList = (head, {nextName = 'next'} = {}) => {
   if (head === null) return true;
   let current = head;
@@ -14,6 +17,13 @@ export const isNTList = (head, {nextName = 'next'} = {}) => {
   return false;
 };
 
+/**
+ * Find the tail of a null-terminated list by following next links.
+ * @param {object|null} head - First node, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {object|null} The tail node, or `null` if empty or circular.
+ */
 export const getNTListTail = (head, {nextName = 'next'} = {}) => {
   if (head === null) return null;
   let current = head;
@@ -25,8 +35,22 @@ export const getNTListTail = (head, {nextName = 'next'} = {}) => {
   return null;
 };
 
+/**
+ * Find the head of a null-terminated list by following prev links.
+ * @param {object|null} node - Any node in the list, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.prevName='prev'] - Property name for the previous link.
+ * @returns {object|null} The head node, or `null` if empty or circular.
+ */
 export const getNTListHead = (node, {prevName = 'prev'} = {}) => getNTListTail(node, {nextName: prevName});
 
+/**
+ * Count the number of nodes in a null-terminated list.
+ * @param {object|null} head - First node, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {number} The node count.
+ */
 export const getNTListLength = (head, {nextName = 'next'} = {}) => {
   if (head === null) return 0;
   let current = head;
@@ -40,6 +64,14 @@ export const getNTListLength = (head, {nextName = 'next'} = {}) => {
   return length;
 };
 
+/**
+ * Convert a null-terminated DLL into a circular DLL.
+ * @param {object|null} node - Any node in the null-terminated list, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @param {string} [options.prevName='prev'] - Property name for the previous link.
+ * @returns {{head: object, tail: object}|null} Head/tail pair, or `null` if empty.
+ */
 export const makeListFromNTList = (node, {nextName = 'next', prevName = 'prev'} = {}) => {
   if (node === null) return null;
   const head = getNTListHead(node, {prevName}),
@@ -49,6 +81,13 @@ export const makeListFromNTList = (node, {nextName = 'next', prevName = 'prev'}
   return {head, tail};
 };
 
+/**
+ * Convert a null-terminated SLL into a circular SLL.
+ * @param {object|null} head - First node, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {{head: object, tail: object}|null} Head/tail pair, or `null` if empty.
+ */
 export const makeSListFromNTList = (head, {nextName = 'next'} = {}) => {
   if (head === null) return null;
   const tail = getNTListTail(head, {nextName});
@@ -56,6 +95,14 @@ export const makeSListFromNTList = (head, {nextName = 'next'} = {}) => {
   return {head, tail};
 };
 
+/**
+ * Convert a circular DLL into a null-terminated DLL.
+ * @param {object|null} head - Head of the circular list, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @param {string} [options.prevName='prev'] - Property name for the previous link.
+ * @returns {{head: object, tail: object}|null} Head/tail pair, or `null` if empty.
+ */
 export const makeNTListFromList = (head, {nextName = 'next', prevName = 'prev'} = {}) => {
   if (head === null) return null;
   const tail = head[prevName];
@@ -64,6 +111,13 @@ export const makeNTListFromList = (head, {nextName = 'next', prevName = 'prev'}
   return {head, tail};
 };
 
+/**
+ * Convert a circular SLL into a null-terminated SLL (fast: head becomes second node).
+ * @param {object|null} head - Head of the circular list, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {{head: object, tail: object}|null} Head/tail pair, or `null` if empty.
+ */
 export const makeNTListFromSListFast = (head, {nextName = 'next'} = {}) => {
   if (head === null) return null;
   const tail = head;
@@ -72,6 +126,13 @@ export const makeNTListFromSListFast = (head, {nextName = 'next'} = {}) => {
   return {head, tail};
 };
 
+/**
+ * Convert a circular SLL into a null-terminated SLL (traverses to find the tail).
+ * @param {object|null} head - Head of the circular list, or `null`.
+ * @param {object} [options] - Link property names.
+ * @param {string} [options.nextName='next'] - Property name for the next link.
+ * @returns {{head: object, tail: object}|null} Head/tail pair, or `null` if empty.
+ */
 export const makeNTListFromSList = (head, {nextName = 'next'} = {}) => {
   if (head === null) return null;
   let tail = head;

package/src/queue.d.ts

@@ -0,0 +1,74 @@
+/** FIFO queue backed by a value list. */
+export class Queue<V = unknown> {
+  /** Number of elements in the queue. */
+  size: number;
+
+  /**
+   * @param underlyingList - Optional pre-existing value list to use.
+   */
+  constructor(underlyingList?: object);
+
+  /** Whether the queue has no elements. */
+  get isEmpty(): boolean;
+
+  /** The front element without removing it, or `undefined` if empty. */
+  get top(): V | undefined;
+
+  /** Alias for {@link top}. */
+  peek(): V | undefined;
+
+  /**
+   * Add a value to the back of the queue.
+   * @param value - Value to enqueue.
+   * @returns `this` for chaining.
+   */
+  add(value: V): this;
+
+  /** Alias for {@link add}. */
+  push(value: V): this;
+
+  /** Alias for {@link add}. */
+  pushBack(value: V): this;
+
+  /** Alias for {@link add}. */
+  enqueue(value: V): this;
+
+  /**
+   * Remove and return the front value.
+   * @returns The front value, or `undefined` if empty.
+   */
+  remove(): V | undefined;
+
+  /** Alias for {@link remove}. */
+  pop(): V | undefined;
+
+  /** Alias for {@link remove}. */
+  popFront(): V | undefined;
+
+  /** Alias for {@link remove}. */
+  dequeue(): V | undefined;
+
+  /**
+   * Add multiple values to the back of the queue.
+   * @param values - Iterable of values.
+   * @returns `this` for chaining.
+   */
+  addValues(values: Iterable<V>): this;
+
+  /**
+   * Remove all elements.
+   * @returns `this` for chaining.
+   */
+  clear(): this;
+
+  /** Iterate over values from front to back. */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Iterate over values from back to front.
+   * @returns An iterable iterator.
+   */
+  getReverseIterator(): IterableIterator<V>;
+}
+
+export default Queue;

package/src/queue.js

@@ -1,28 +1,40 @@
-'use strict';
-
 import ValueList from './value-list.js';
 import {addAliases} from './meta-utils.js';
 import {pushValuesBack} from './list-utils.js';
 
+/** FIFO queue backed by a value list. */
 export class Queue {
+  /** @param {object} [underlyingList] - Backing list instance (default: new ValueList). */
   constructor(underlyingList = new ValueList()) {
     this.list = underlyingList;
     this.size = this.list.getLength();
   }
+  /** Whether the queue has no elements. */
   get isEmpty() {
     return this.list.isEmpty;
   }
+  /** The front element without removing it, or `undefined` if empty. */
   get top() {
     return this.list.isEmpty ? undefined : this.list.front.value;
   }
+  /** Alias for {@link Queue#top|top}. */
   peek() {
     return this.list.isEmpty ? undefined : this.list.front.value;
   }
+  /**
+   * Add a value to the back of the queue.
+   * @param {*} value - Value to enqueue.
+   * @returns {Queue} `this` for chaining.
+   */
   add(value) {
     this.list.pushBack(value);
     ++this.size;
     return this;
   }
+  /**
+   * Remove and return the front value.
+   * @returns {*} The dequeued value, or `undefined` if empty.
+   */
   remove() {
     if (!this.list.isEmpty) {
       --this.size;
@@ -30,18 +42,32 @@ export class Queue {
     }
     // return undefined;
   }
+  /**
+   * Enqueue multiple values.
+   * @param {Iterable} values - Values to add.
+   * @returns {Queue} `this` for chaining.
+   */
   addValues(values) {
     pushValuesBack(this, values);
     return this;
   }
+  /**
+   * Remove all elements.
+   * @returns {Queue} `this` for chaining.
+   */
   clear() {
     this.list.clear();
     this.size = 0;
     return this;
   }
+  /** Iterate over values from front to back. */
   [Symbol.iterator]() {
     return this.list[Symbol.iterator]();
   }
+  /**
+   * Get an iterable over values in reverse order.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getReverseIterator() {
     return this.list.getReverseIterator?.();
   }

package/src/slist/basics.d.ts

@@ -0,0 +1,47 @@
+import {SllOptions} from './nodes.js';
+
+/** Result of extracting or popping nodes from a circular SLL. */
+export interface SllExtractResult<T extends object> {
+  /** The extracted sub-range descriptor. */
+  extracted: { prevFrom: T; to: T };
+  /** The remaining circular list head, or `null` if nothing remains. */
+  rest: T | null;
+}
+
+/** A splice range descriptor for SLL operations. */
+export interface SllSpliceRange<T extends object> {
+  /** Node whose next link starts the range. */
+  prevFrom: T;
+  /** Last node of the range (defaults to `prevFrom[nextName]`). */
+  to?: T;
+}
+
+/**
+ * Extract a range of nodes from a circular SLL.
+ * @param options - Link property names.
+ * @param range - Range descriptor with `prevFrom` and optional `to`.
+ * @returns The extracted sub-list and the remaining list.
+ */
+export function extract<T extends object>(options: SllOptions, range: SllSpliceRange<T>): SllExtractResult<T>;
+
+/**
+ * Pop a single node out of its circular SLL.
+ * @param options - Link property names.
+ * @param prev - The node preceding the one to pop.
+ * @returns The popped node (now stand-alone) and the remaining list.
+ */
+export function pop<T extends object>(options: SllOptions, prev: T): SllExtractResult<T>;
+
+/**
+ * Splice a circular SLL into another list after a target node.
+ * @param options - Link property names.
+ * @param target - Node after which to insert.
+ * @param range - Range descriptor of the circular list to splice in.
+ * @returns The target node.
+ */
+export function splice<T extends object>(options: SllOptions, target: T, range: SllSpliceRange<T>): T;
+
+/**
+ * Alias for {@link splice}.
+ */
+export { splice as append };