list-toolkit 2.2.6 → 2.3.0

package/src/list/ptr.d.ts

@@ -0,0 +1,72 @@
+import {PtrBase, HeadNode} from './nodes.js';
+
+/** Pointer for navigating and mutating a hosted DLL ({@link List}). */
+export class Ptr<T extends object = object> extends PtrBase<T> {
+  /** The hosted list this pointer belongs to. */
+  list: HeadNode;
+
+  /**
+   * @param list - Owning list or another Ptr to copy.
+   * @param node - Target node.
+   */
+  constructor(list: HeadNode | Ptr<T>, node?: T);
+
+  /** Whether the pointer is on the sentinel head node. */
+  get isHead(): boolean;
+
+  /**
+   * Create a copy of this pointer.
+   * @returns A new Ptr referencing the same list and node.
+   */
+  clone(): Ptr<T>;
+
+  /**
+   * Remove the current node and advance to the next.
+   * @returns The removed node, or `null` if on the head.
+   */
+  removeCurrent(): T | null;
+
+  /**
+   * Insert a value before the current node.
+   * @param value - Value to insert (adopted via the list).
+   * @returns A Ptr to the newly inserted node.
+   */
+  addBefore(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an already-prepared node before the current node.
+   * @param node - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeBefore(node: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert a value after the current node.
+   * @param value - Value to insert (adopted via the list).
+   * @returns A Ptr to the newly inserted node.
+   */
+  addAfter(value: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Insert an already-prepared node after the current node.
+   * @param node - Node or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  addNodeAfter(node: T | PtrBase<T>): Ptr<T>;
+
+  /**
+   * Splice another list's nodes before the current node.
+   * @param list - Compatible hosted list to consume.
+   * @returns A Ptr to the first inserted node, or `null` if the list was empty.
+   */
+  insertBefore(list: HeadNode): Ptr<T> | null;
+
+  /**
+   * Splice another list's nodes after the current node.
+   * @param list - Compatible hosted list to consume.
+   * @returns A Ptr to the first inserted node, or `null` if the list was empty.
+   */
+  insertAfter(list: HeadNode): Ptr<T> | null;
+}
+
+export default Ptr;

package/src/list/ptr.js

@@ -1,44 +1,81 @@
-'use strict';
-
 import {HeadNode, PtrBase} from './nodes.js';
 import {pop, splice} from './basics.js';
 
+/** Pointer for navigating and mutating a hosted doubly linked list. */
 export class Ptr extends PtrBase {
+  /**
+   * @param {HeadNode|Ptr} list - Owning list or another Ptr to copy.
+   * @param {object} [node] - Target node.
+   */
   constructor(list, node) {
     super(list, node, HeadNode);
   }
+  /** Whether the pointer is at the head sentinel. */
   get isHead() {
     return this.node === this.list;
   }
+  /**
+   * Create a copy of this pointer.
+   * @returns {Ptr} A new Ptr referencing the same list and node.
+   */
   clone() {
     return new Ptr(this);
   }
+  /**
+   * Remove the current node and advance to the next.
+   * @returns {object|null} The removed node, or `null` if at head.
+   */
   removeCurrent() {
     if (this.node === this.list) return null;
     const node = this.node;
     this.node = node[this.list.nextName];
     return pop(this.list, node).extracted;
   }
+  /**
+   * Insert a value before the current node.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addBefore(value) {
     const node = this.list.adoptValue(value);
     splice(this.list, this.node[this.list.prevName], node);
     return this.list.makePtr(node);
   }
+  /**
+   * Insert an existing node before the current node.
+   * @param {object} node - Node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeBefore(node) {
     node = this.list.adoptNode(node);
     splice(this.list, this.node[this.list.prevName], node);
     return this.list.makePtr(node);
   }
+  /**
+   * Insert a value after the current node.
+   * @param {*} value - Value or node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addAfter(value) {
     const node = this.list.adoptValue(value);
     splice(this.list, this.node, node);
     return this.list.makePtr(node);
   }
+  /**
+   * Insert an existing node after the current node.
+   * @param {object} node - Node to insert.
+   * @returns {Ptr} A Ptr to the inserted node.
+   */
   addNodeAfter(node) {
     node = this.list.adoptNode(node);
     splice(this.list, this.node, node);
     return this.list.makePtr(node);
   }
+  /**
+   * Splice another list's nodes before the current node.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr|null} A Ptr to the first inserted node, or `null` if empty.
+   */
   insertBefore(list) {
     if (!this.list.isCompatible(list)) throw new Error('Incompatible lists');
     if (list.isEmpty) return null;
@@ -46,6 +83,11 @@ export class Ptr extends PtrBase {
     splice(this.list, this.node[this.list.prevName], head);
     return this.list.makePtr(head);
   }
+  /**
+   * Splice another list's nodes after the current node.
+   * @param {HeadNode} list - Compatible list to consume.
+   * @returns {Ptr|null} A Ptr to the first inserted node, or `null` if empty.
+   */
   insertAfter(list) {
     if (!this.list.isCompatible(list)) throw new Error('Incompatible lists');
     if (list.isEmpty) return null;

package/src/list/value.d.ts

@@ -0,0 +1,292 @@
+import {HeadNode, ValueNode, PtrBase, DllOptions, DllRange} from './nodes.js';
+import {Ptr} from './ptr.js';
+
+/**
+ * Hosted value-based doubly linked list. Wraps values in {@link ValueNode}.
+ *
+ * Extends `List` at runtime. Internally nodes are `ValueNode<V>`.
+ * The default iterator and `getIterator`/`getReverseIterator` yield
+ * unwrapped `V` values; use `getNodeIterator`/`getReverseNodeIterator`
+ * for `ValueNode<V>` nodes.
+ */
+export class ValueList<V = unknown> extends HeadNode {
+  /** The first ValueNode after the head. */
+  get front(): ValueNode<V>;
+
+  /** The last ValueNode before the head. */
+  get back(): ValueNode<V>;
+
+  /** A range spanning all nodes, or `null` if empty. */
+  get range(): DllRange<ValueNode<V>> | null;
+
+  /** Pointer to the first node. */
+  get frontPtr(): Ptr<ValueNode<V>>;
+
+  /** Pointer to the last node. */
+  get backPtr(): Ptr<ValueNode<V>>;
+
+  /**
+   * Create a pointer to a node in this list.
+   * @param node - Target node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtr(node?: ValueNode<V>): Ptr<ValueNode<V>>;
+
+  /**
+   * Create a pointer to the node after `prev`.
+   * @param prev - Preceding node, or `undefined` for the front.
+   * @returns A new Ptr.
+   */
+  makePtrFromPrev(prev?: ValueNode<V>): Ptr<ValueNode<V>>;
+
+  /**
+   * Remove and return the front value.
+   * @returns The unwrapped value, or `undefined` if empty.
+   */
+  popFront(): V | undefined;
+
+  /** Alias for {@link popFront}. */
+  pop(): V | undefined;
+
+  /**
+   * Remove and return the back value.
+   * @returns The unwrapped value, or `undefined` if empty.
+   */
+  popBack(): V | undefined;
+
+  /**
+   * Remove and return the front ValueNode.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popFrontNode(): ValueNode<V> | undefined;
+
+  /**
+   * Remove and return the back ValueNode.
+   * @returns The removed node, or `undefined` if empty.
+   */
+  popBackNode(): ValueNode<V> | undefined;
+
+  /**
+   * Insert a value at the front.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the inserted node.
+   */
+  pushFront(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /** Alias for {@link pushFront}. */
+  push(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert a value at the back.
+   * @param value - Raw value, ValueNode, or Ptr.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBack(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing ValueNode at the front.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushFrontNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Insert an existing ValueNode at the back.
+   * @param nodeOrPtr - ValueNode or pointer to insert.
+   * @returns A Ptr to the inserted node.
+   */
+  pushBackNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Move all nodes from another list to the front.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the new front.
+   */
+  appendFront(list: HeadNode): Ptr<ValueNode<V>>;
+
+  /**
+   * Move all nodes from another list to the back.
+   * @param list - Compatible list to consume.
+   * @returns A Ptr to the first appended node.
+   */
+  appendBack(list: HeadNode): Ptr<ValueNode<V>>;
+
+  /** Alias for {@link appendBack}. */
+  append(list: HeadNode): Ptr<ValueNode<V>>;
+
+  /**
+   * Move a node to the front of the list.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the front.
+   */
+  moveToFront(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Move a node to the back of the list.
+   * @param nodeOrPtr - Node or pointer to move.
+   * @returns A Ptr to the back.
+   */
+  moveToBack(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): Ptr<ValueNode<V>>;
+
+  /**
+   * Remove all nodes.
+   * @param drop - If `true`, pop nodes one by one (making each stand-alone).
+   * @returns `this` for chaining.
+   */
+  clear(drop?: boolean): this;
+
+  /**
+   * Remove a single node from the list.
+   * @param nodeOrPtr - Node or pointer to remove.
+   * @returns The removed node.
+   */
+  removeNode(nodeOrPtr: ValueNode<V> | PtrBase<ValueNode<V>>): ValueNode<V>;
+
+  /**
+   * Remove a range of nodes and optionally drop them.
+   * @param range - Range to remove.
+   * @param drop - If `true`, make each removed node stand-alone.
+   * @returns A new ValueList containing the removed values.
+   */
+  removeRange(range?: DllRange<ValueNode<V>>, drop?: boolean): ValueList<V>;
+
+  /**
+   * Extract a range of nodes into a new list.
+   * @param range - Range to extract (defaults to the whole list).
+   * @returns A new ValueList containing the extracted values.
+   */
+  extractRange(range?: DllRange<ValueNode<V>>): ValueList<V>;
+
+  /**
+   * Extract nodes that satisfy a condition into a new list.
+   * @param condition - Predicate receiving each ValueNode.
+   * @returns A new ValueList containing the extracted values.
+   */
+  extractBy(condition: (node: ValueNode<V>) => boolean): ValueList<V>;
+
+  /**
+   * Reverse the order of all nodes in place.
+   * @returns `this` for chaining.
+   */
+  reverse(): this;
+
+  /**
+   * Sort nodes in place using merge sort.
+   * @param lessFn - Comparison receiving ValueNodes, returns `true` if `a` should precede `b`.
+   * @returns `this` for chaining.
+   */
+  sort(lessFn: (a: ValueNode<V>, b: ValueNode<V>) => boolean): this;
+
+  /**
+   * Detach all nodes as a raw circular list (no sentinel).
+   * @returns Head of the raw circular list, or `null` if empty.
+   */
+  releaseRawList(): ValueNode<V> | null;
+
+  /**
+   * Detach all nodes as a null-terminated list.
+   * @returns Object with `head` and `tail`, or `null` if empty.
+   */
+  releaseNTList(): {head: ValueNode<V>; tail: ValueNode<V>} | null;
+
+  /**
+   * Validate that a range is reachable within this list.
+   * @param range - Range to validate.
+   * @returns `true` if the range is valid.
+   */
+  validateRange(range?: DllRange<ValueNode<V>>): boolean;
+
+  /**
+   * Adopt a value, pointer, or ValueNode into this list.
+   * @param value - Raw value, Ptr, or ValueNode.
+   * @returns A ValueNode ready for insertion.
+   */
+  adoptValue(value: V | ValueNode<V> | PtrBase<ValueNode<V>>): ValueNode<V>;
+
+  /** Iterate over unwrapped values from front to back. */
+  [Symbol.iterator](): IterableIterator<V>;
+
+  /**
+   * Get an iterable over ValueNodes in a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of ValueNodes.
+   */
+  getNodeIterator(range?: DllRange<ValueNode<V>>): IterableIterator<ValueNode<V>>;
+
+  /**
+   * Get an iterable over unwrapped values in a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of values.
+   */
+  getValueIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /** Alias for {@link getValueIterator}. */
+  getIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /**
+   * Get an iterable over ValueNodes in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of ValueNodes.
+   */
+  getReverseNodeIterator(range?: DllRange<ValueNode<V>>): IterableIterator<ValueNode<V>>;
+
+  /**
+   * Get an iterable over unwrapped values in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of values.
+   */
+  getReverseValueIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /** Alias for {@link getReverseValueIterator}. */
+  getReverseIterator(range?: DllRange<ValueNode<V>>): IterableIterator<V>;
+
+  /**
+   * Get an iterable of Ptr objects over a range.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getPtrIterator(range?: DllRange<ValueNode<V>>): IterableIterator<Ptr<ValueNode<V>>>;
+
+  /**
+   * Get an iterable of Ptr objects in reverse order.
+   * @param range - Sub-range to iterate.
+   * @returns An iterable iterator of Ptrs.
+   */
+  getReversePtrIterator(range?: DllRange<ValueNode<V>>): IterableIterator<Ptr<ValueNode<V>>>;
+
+  /**
+   * Create a shallow clone of this list.
+   * @returns A new ValueList with the same values.
+   */
+  clone(): ValueList<V>;
+
+  /**
+   * Create an empty list with the same options.
+   * @returns A new empty ValueList.
+   */
+  make(): ValueList<V>;
+
+  /**
+   * Create a list from values with the same options.
+   * @param values - Iterable of values.
+   * @returns A new ValueList.
+   */
+  makeFrom(values: Iterable<V>): ValueList<V>;
+
+  /**
+   * Build a ValueList from an iterable.
+   * @param values - Iterable of values.
+   * @param options - Link property names.
+   * @returns A new ValueList.
+   */
+  static from<V = unknown>(values: Iterable<V>, options?: DllOptions): ValueList<V>;
+
+  /** The Ptr class associated with this list type. */
+  static Ptr: typeof Ptr;
+
+  /** The ValueNode class used by this list type. */
+  static ValueNode: typeof ValueNode;
+}
+
+export {ValueNode, Ptr};
+export default ValueList;

package/src/list/value.js

@@ -1,19 +1,34 @@
-'use strict';
-
 import List, {Ptr} from './core.js';
 import {ValueNode} from './nodes.js';
 import {pop} from './basics.js';
 import {addAliases, mapIterator, normalizeIterator} from '../meta-utils.js';
 
+/**
+ * Hosted value-based doubly linked list. Wraps values in {@link ValueNode}.
+ * Iterators yield unwrapped values; use `getNodeIterator` for ValueNode access.
+ */
 export class ValueList extends List {
+  /**
+   * Remove and return the front value.
+   * @returns {*} The unwrapped value, or `undefined` if empty.
+   */
   popFront() {
     if (!this.isEmpty) return pop(this, this[this.nextName]).extracted.value;
   }
 
+  /**
+   * Remove and return the back value.
+   * @returns {*} The unwrapped value, or `undefined` if empty.
+   */
   popBack() {
     if (!this.isEmpty) return pop(this, this[this.prevName]).extracted.value;
   }
 
+  /**
+   * Adopt a value, pointer, or ValueNode into this list.
+   * @param {*} value - Raw value, Ptr, or ValueNode.
+   * @returns {ValueNode} A ValueNode ready for insertion.
+   */
   adoptValue(value) {
     if (value instanceof Ptr) {
       if (!this.isCompatiblePtr(value)) throw new Error('Incompatible pointer');
@@ -30,8 +45,7 @@ export class ValueList extends List {
     return new ValueNode(value, this);
   }
 
-  // iterators
-
+  /** Iterate over unwrapped values from front to back. */
   [Symbol.iterator]() {
     let current = this[this.nextName],
       readyToStop = this.isEmpty;
@@ -46,28 +60,55 @@ export class ValueList extends List {
     });
   }
 
+  /**
+   * Get an iterable over unwrapped values in a range.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getValueIterator(range) {
     return mapIterator(this.getNodeIterator(range), node => node.value);
   }
 
+  /**
+   * Get an iterable over unwrapped values in reverse order.
+   * @param {object} [range] - Sub-range to iterate.
+   * @returns {Iterable} An iterable iterator of values.
+   */
   getReverseValueIterator(range) {
     return mapIterator(this.getReverseNodeIterator(range), node => node.value);
   }
 
-  // meta helpers
-
+  /**
+   * Create a shallow clone of this list.
+   * @returns {ValueList} A new ValueList with the same values.
+   */
   clone() {
     return ValueList.from(this, this);
   }
 
+  /**
+   * Create an empty list with the same options.
+   * @returns {ValueList} A new empty ValueList.
+   */
   make() {
     return new ValueList(this);
   }
 
+  /**
+   * Create a list from values with the same options.
+   * @param {Iterable} values - Iterable of values.
+   * @returns {ValueList} A new ValueList.
+   */
   makeFrom(values) {
     return ValueList.from(values, this);
   }
 
+  /**
+   * Build a ValueList from an iterable.
+   * @param {Iterable} values - Iterable of values.
+   * @param {object} [options] - Link property names.
+   * @returns {ValueList} A new ValueList.
+   */
   static from(values, options) {
     const list = new ValueList(options);
     for (const value of values) list.pushBack(value);

package/src/list-helpers.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Normalize a node or pointer to a plain node, validating compatibility.
+ * @param list - Owning list for validation.
+ * @param node - Node or pointer to normalize.
+ * @param PtrBase - Pointer base class for `instanceof` checks.
+ * @returns The underlying node, or `null`.
+ */
+export function normalizeNode(list: object, node: any, PtrBase: Function): object | null;
+
+/**
+ * Check whether a range is compatible with a list host.
+ * @param listHost - List to validate against.
+ * @param range - Range to check.
+ * @param PtrBase - Pointer base class for `instanceof` checks.
+ * @returns `true` if the range is compatible.
+ */
+export function isRangeLike(listHost: object, range: any, PtrBase: Function): boolean;
+
+/**
+ * Normalize a range, resolving any pointers to plain nodes.
+ * @param listHost - List to validate against.
+ * @param range - Range to normalize.
+ * @param PtrBase - Pointer base class for `instanceof` checks.
+ * @returns The normalized range with `from`/`to` as plain nodes, or `null`.
+ */
+export function normalizeRange(listHost: object, range: any, PtrBase: Function): object | null;
+
+/**
+ * Check whether a pointer-based range is compatible with a list host.
+ * @param listHost - List to validate against.
+ * @param range - Pointer range to check (must have `from` as a PtrBase).
+ * @param PtrBase - Pointer base class for `instanceof` checks.
+ * @returns `true` if the pointer range is compatible.
+ */
+export function isPtrRangeLike(listHost: object, range: any, PtrBase: Function): boolean;
+
+/**
+ * Normalize a pointer-based range, resolving `to` to a plain node.
+ * @param listHost - List to validate against.
+ * @param range - Pointer range to normalize.
+ * @param PtrBase - Pointer base class for `instanceof` checks.
+ * @returns The normalized pointer range, or `null`.
+ */
+export function normalizePtrRange(listHost: object, range: any, PtrBase: Function): object | null;

package/src/list-helpers.js

@@ -1,5 +1,10 @@
-'use strict';
-
+/**
+ * Normalize a node or pointer to a plain node, validating compatibility.
+ * @param {object} list - Owning list for validation.
+ * @param {object|null} node - Node or pointer to normalize.
+ * @param {Function} PtrBase - Pointer base class for `instanceof` checks.
+ * @returns {object|null} The underlying node, or `null`.
+ */
 export const normalizeNode = (list, node, PtrBase) => {
   if (!node) return null;
   if (node instanceof PtrBase) {
@@ -11,6 +16,13 @@ export const normalizeNode = (list, node, PtrBase) => {
   return node;
 };
 
+/**
+ * Check whether a range is compatible with a list host.
+ * @param {object} listHost - List to validate against.
+ * @param {object} [range] - Range to check.
+ * @param {Function} PtrBase - Pointer base class for `instanceof` checks.
+ * @returns {boolean} `true` if the range is compatible.
+ */
 export const isRangeLike = (listHost, range, PtrBase) => {
   if (!range) return true;
 
@@ -30,7 +42,7 @@ export const isRangeLike = (listHost, range, PtrBase) => {
   }
 
   if (range.to instanceof PtrBase) {
-    if (list){
+    if (list) {
       if (range.to.list !== list) return false;
     } else {
       if (!listHost.isCompatible(range.to.list)) return false;
@@ -42,6 +54,13 @@ export const isRangeLike = (listHost, range, PtrBase) => {
   return true;
 };
 
+/**
+ * Normalize a range, resolving any pointers to plain nodes.
+ * @param {object} listHost - List to validate against.
+ * @param {object} [range] - Range to normalize.
+ * @param {Function} PtrBase - Pointer base class for `instanceof` checks.
+ * @returns {object|null} The normalized range with `from`/`to` as plain nodes, or `null`.
+ */
 export const normalizeRange = (listHost, range, PtrBase) => {
   if (!range) return null;
   if (!isRangeLike(listHost, range, PtrBase)) throw new Error('Not a compatible range');
@@ -51,6 +70,13 @@ export const normalizeRange = (listHost, range, PtrBase) => {
   return {...range, from, to};
 };
 
+/**
+ * Check whether a pointer-based range is compatible with a list host.
+ * @param {object} listHost - List to validate against.
+ * @param {object} [range] - Pointer range to check (must have `from` as a PtrBase).
+ * @param {Function} PtrBase - Pointer base class for `instanceof` checks.
+ * @returns {boolean} `true` if the pointer range is compatible.
+ */
 export const isPtrRangeLike = (listHost, range, PtrBase) => {
   if (!range) return true;
   if (!(range.from instanceof PtrBase)) return false;
@@ -71,6 +97,13 @@ export const isPtrRangeLike = (listHost, range, PtrBase) => {
   return true;
 };
 
+/**
+ * Normalize a pointer-based range, resolving `to` to a plain node.
+ * @param {object} listHost - List to validate against.
+ * @param {object} [range] - Pointer range to normalize.
+ * @param {Function} PtrBase - Pointer base class for `instanceof` checks.
+ * @returns {object|null} The normalized pointer range, or `null`.
+ */
 export const normalizePtrRange = (listHost, range, PtrBase) => {
   if (!range) return null;
   if (!isPtrRangeLike(listHost, range, PtrBase)) throw new Error('Not a compatible ptr range');