SLL: foundation

Foundational classes for singly linked lists. Prerequisites: Backgrounder, Concepts: list API.

Legend for tables

• API
  • options - options object, which contains nextName link name with default value "next".
  • node - a node object in the list
  • head - a node in the external list
  • list - a list object of the same type as the current list
  • ptr - a pointer to a node in the list
  • range - a range of nodes in the list
  • nodeOrPtr - a node or a pointer to a node
  • value - a value
  • values - an iterable that provides values
  • iterator - an Iterator instance or an object with an iterator/iterable protocol
• Complexity
  • O - complexity of an operation
  • O(1) - constant time
  • O(n) - linear time proportional to the list size
  • O(k) - linear time proportional to the list/range argument size

slist/nodes.js

Include:

import {HeadNode} from 'list-toolkit/slist/nodes.js';

Stand-alone functions

Function	Return Value	Description	O
isNodeLike(options, node)	truthy/falsy	Checks if node is a node-like object.	O(1)
isStandAlone(options, node)	truthy/falsy	Checks if node is a stand-alone node.	O(1)
isCompatible(options1, options2)	truthy/falsy	Checks if options1 and options2 have the same link names.	O(1)

Class Node

Foundation for singly linked list nodes.

Member	Return Value	Description	O
constructor(options)	this	Creates a new node.	O(1)
nextName	string/symbol	The name of the next link.	O(1)
[nextName]	node	The next node.	O(1)
isStandAlone	boolean	Getter — true when the node is stand-alone.	O(1)

The constructor creates a stand-alone node (next link points to itself).

Class HeadNode

Sentinel head node hosting the list. Extends Node; used as the base for singly linked lists.

Member	Return Value	Description	O
last	node	The last node.	O(1)
isNodeLike(node)	truthy/falsy	Checks if node is a node-like object.	O(1)
isCompatibleNames(options)	truthy/falsy	Checks if options have the same link names.	O(1)
isCompatible(list)	truthy/falsy	Checks if list has the same link names.	O(1)
isCompatiblePtr(ptr)	truthy/falsy	Checks if ptr has the same link names.	O(1)
isCompatibleRange(range)	truthy/falsy	Checks if range has the same link names.	O(1)
isEmpty	truthy/falsy	Checks if the list is empty.	O(1)
isOne	truthy/falsy	Checks if the list has only one node.	O(1)
isOneOrEmpty	truthy/falsy	Checks if the list has only one node or empty.	O(1)
head	list	The list itself.	O(1)
front	node	The first node.	O(1)
back	node	The last node.	O(1)
range	range	The list range from the first to the last node or null if the list is empty.	O(1)
getLength()	number	The number of nodes in the list.	O(n)
adoptNode(nodeOrPtr)	node	Adopt a node.	O(1)
adoptValue(value)	node	Adopt a value.	O(1)
normalizeNode(nodeOrPtr)	node	Normalize a node.	O(1)
normalizeRange(range)	range	Normalize a range.	O(1)
syncLast()	this	Sync the last node.	O(n)

adoptNode() dereferences pointers, checks compatibility, and creates missing link properties on raw objects. Throws if the argument cannot be used as a node. adoptValue() is an alias (nodes are values in node-based lists).

normalizeNode() dereferences pointers and validates compatibility. normalizeRange() does the same for ranges, returning normalized node references.

Class ValueNode

Value node for value-based lists. Extends Node.

Member	Return Value	Description	O
constructor(value, options)	this	Create a new value node with value.	O(1)
value	any	The value of the node.	O(1)

value is read-write.

Class PtrBase

Base pointer to a singly linked node.

Member	Return Value	Description	O
constructor(list, node, prev, ListClass)	this	Create a new pointer to a node.	O(1)
list	list	The list it belongs to.	O(1)
node	node	The node it points to.	O(1)
nextNode	node	The next node.	O(1)
prevNode	node	The previous node.	O(1)
isPrevNodeValid()	truthy/falsy	Checks if prevNode is valid.	O(1)
next()	this	Move the pointer to the next node.	O(1)
prev()	this	Move the pointer to the previous node.	O(1)
syncPrev()	this	Sync the previous node.	O(n)

If prevNode.next !== node, some operations are unavailable. Check with isPrevNodeValid() (which may fix trivially invalid states). prev() throws when prevNode is invalid and likely invalidates it after one call — do not rely on it for reverse traversal; use a DLL instead. syncPrev() re-discovers the previous node in O(n).

Class ExtListBase

Pointer-like base for external (headless) singly linked lists. API mirrors HeadNode where applicable.

Member	Return Value	Description	O
constructor(head, options)	this	Create a new listing optionally pointing to an external list.	O(1)
nextName	string/symbol	The name of the next property.	O(1)
head	node or null	The external list it points to or null if the list is empty.	O(1)
isNodeLike(node)	truthy/falsy	Checks if node is a node-like object.	O(1)
isCompatibleNames(options)	truthy/falsy	Checks if options have the same link names.	O(1)
isCompatible(list)	truthy/falsy	Checks if list is compatible with the list.	O(1)
isCompatiblePtr(ptr)	truthy/falsy	Checks if ptr is compatible with the list.	O(1)
isCompatibleRange(range)	truthy/falsy	Checks if range has the same link names.	O(1)
isEmpty	truthy/falsy	Checks if the list is empty.	O(1)
isOne	truthy/falsy	Checks if the list has only one node.	O(1)
isOneOrEmpty	truthy/falsy	Checks if the list has only one node or empty.	O(1)
front	node	The first node or null if the list is empty.	O(1)
range	range	The range of the list or null if the list is empty.	O(1)
getLength()	number	The length of the list or 0 if the list is empty.	O(n)
getBack()	node	The last node or null if the list is empty.	O(n)
adoptNode(nodeOrPtr)	node	Adopt a node.	O(1)
adoptValue(value)	node	Adopt a value.	O(1)
normalizeNode(nodeOrPtr)	node	Normalize a node.	O(1)
normalizeRange(range)	range	Normalize a range.	O(1)
attach(head)	previous head	Attach the list to an external list.	O(1)
detach()	previous head	Detach the list from the external list and make it empty.	O(1)
next()	this	Move the pointer to the next node.	O(1)

head is null when empty. Constructor without arguments creates an empty list with defaults.

attach(null) and detach() are equivalent. next() is a no-op on empty lists.