list-toolkit 1.0.2 → 2.0.0

package/src/list/value.js

@@ -0,0 +1,88 @@
+'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';
+
+export class ValueList extends List {
+  popFront() {
+    if (!this.isEmpty) return pop(this, this[this.nextName]).extracted.value;
+  }
+
+  popBack() {
+    if (!this.isEmpty) return pop(this, this[this.prevName]).extracted.value;
+  }
+
+  adoptValue(value) {
+    if (value instanceof Ptr) {
+      if (!this.isCompatiblePtr(value)) throw new Error('Incompatible pointer');
+      if (value.node instanceof ValueNode) {
+        value.list = this;
+        return super.adoptNode(value);
+      }
+      return new ValueNode(value.node, this);
+    }
+    if (value instanceof ValueNode) {
+      if (!this.isNodeLike(value)) throw new Error('Incompatible node');
+      return super.adoptNode(value);
+    }
+    return new ValueNode(value, this);
+  }
+
+  // iterators
+
+  [Symbol.iterator]() {
+    let current = this[this.nextName],
+      readyToStop = this.isEmpty;
+    return normalizeIterator({
+      next: () => {
+        if (readyToStop && current === this) return {done: true};
+        readyToStop = true;
+        const value = current.value;
+        current = current[this.nextName];
+        return {value};
+      }
+    });
+  }
+
+  getValueIterator(range) {
+    return mapIterator(this.getNodeIterator(range), node => node.value);
+  }
+
+  getReverseValueIterator(range) {
+    return mapIterator(this.getReverseNodeIterator(range), node => node.value);
+  }
+
+  // meta helpers
+
+  clone() {
+    return ValueList.from(this, this);
+  }
+
+  make() {
+    return new ValueList(this);
+  }
+
+  makeFrom(values) {
+    return ValueList.from(values, this);
+  }
+
+  static from(values, options) {
+    const list = new ValueList(options);
+    for (const value of values) list.pushBack(value);
+    return list;
+  }
+}
+
+ValueList.Ptr = Ptr;
+ValueList.ValueNode = ValueNode;
+
+addAliases(ValueList.prototype, {
+  popFront: 'pop',
+  getValueIterator: 'getIterator',
+  getReverseValueIterator: 'getReverseIterator'
+});
+
+export {ValueNode, Ptr};
+export default ValueList;

package/src/list-helpers.js

@@ -0,0 +1,80 @@
+'use strict';
+
+export const normalizeNode = (list, node, PtrBase) => {
+  if (!node) return null;
+  if (node instanceof PtrBase) {
+    if (!list.isCompatible(node.list)) throw new Error('Incompatible lists');
+    node = node.node;
+  } else {
+    if (!list.isNodeLike(node)) throw new Error('Not a compatible node');
+  }
+  return node;
+};
+
+export const isRangeLike = (listHost, range, PtrBase) => {
+  if (!range) return true;
+
+  if (range.list && !listHost.isCompatible(range.list)) return false;
+
+  let list = range.list;
+
+  if (range.from instanceof PtrBase) {
+    if (range.list) {
+      if (range.from.list !== range.list) return false;
+    } else {
+      if (!listHost.isCompatible(range.from.list)) return false;
+      list ||= range.from.list;
+    }
+  } else {
+    if (range.from && !listHost.isNodeLike(range.from)) return false;
+  }
+
+  if (range.to instanceof PtrBase) {
+    if (list){
+      if (range.to.list !== list) return false;
+    } else {
+      if (!listHost.isCompatible(range.to.list)) return false;
+    }
+  } else {
+    if (range.to && !listHost.isNodeLike(range.to)) return false;
+  }
+
+  return true;
+};
+
+export const normalizeRange = (listHost, range, PtrBase) => {
+  if (!range) return null;
+  if (!isRangeLike(listHost, range, PtrBase)) throw new Error('Not a compatible range');
+  let {from, to} = range;
+  if (from instanceof PtrBase) from = from.node;
+  if (to instanceof PtrBase) to = to.node;
+  return {...range, from, to};
+};
+
+export const isPtrRangeLike = (listHost, range, PtrBase) => {
+  if (!range) return true;
+  if (!(range.from instanceof PtrBase)) return false;
+
+  if (range.list) {
+    if (!listHost.isCompatible(range.list)) return false;
+    if (range.from.list !== range.list) return false;
+  } else {
+    if (!listHost.isCompatible(range.from.list)) return false;
+  }
+
+  if (range.to instanceof PtrBase) {
+    if (range.to.list !== (range.list || range.from.list)) return false;
+  } else {
+    if (range.to && !listHost.isNodeLike(range.to)) return false;
+  }
+
+  return true;
+};
+
+export const normalizePtrRange = (listHost, range, PtrBase) => {
+  if (!range) return null;
+  if (!isPtrRangeLike(listHost, range, PtrBase)) throw new Error('Not a compatible ptr range');
+  let {from, to} = range;
+  if (to instanceof PtrBase) to = to.node;
+  return {...range, from, to};
+};

package/src/list-utils.js

@@ -0,0 +1,140 @@
+'use strict';
+
+export const isValidList = list => {
+  let current = list;
+  do {
+    const next = current[list.nextName];
+    if (!next || next[list.prevName] !== current) return false;
+    current = next;
+  } while (current !== list);
+  return true;
+};
+
+export const isValidSList = list => {
+  let current = list;
+  do {
+    const next = current[list.nextName];
+    if (!next) return false;
+    current = next;
+  } while (current !== list);
+  return true;
+};
+
+export const pushValuesFront = (list, values) => {
+  for (const value of values) {
+    list.pushFront(value);
+  }
+  return list;
+};
+
+export const pushValuesBack = (list, values) => {
+  for (const value of values) {
+    list.pushBack(value);
+  }
+  return list;
+};
+
+export const appendValuesFront = (list, values) => {
+  if (typeof list.appendFront == 'function' && list.isCompatible(values)) {
+    list.appendFront(values);
+    return list;
+  }
+  if (!Array.isArray(values)) values = Array.from(values);
+  for (let i = values.length - 1; i >= 0; --i) {
+    list.pushFront(values[i]);
+  }
+  return list;
+};
+
+export const appendValuesBack = (list, values) => {
+  if (typeof list.appendBack == 'function' && list.isCompatible(values)) {
+    list.appendBack(values);
+    return list;
+  }
+  return pushValuesBack(list, values);
+};
+
+export const addValuesBefore = (ptr, values) => {
+  for (const value of values) {
+    ptr.addBefore(value);
+  }
+  return ptr;
+};
+
+export const addValuesAfter = (ptr, values) => {
+  for (const value of values) {
+    ptr.addAfter(value);
+  }
+  return ptr;
+};
+
+export const insertValuesBefore = (ptr, values) => {
+  if (typeof ptr.insertBefore == 'function' && ptr.list.isCompatible(values)) {
+    ptr.insertBefore(ptr.list.makeFrom(values));
+    return ptr;
+  }
+  return addValuesBefore(ptr, values);
+};
+
+export const insertValuesAfter = (ptr, values) => {
+  if (typeof ptr.insertAfter == 'function' && ptr.list.isCompatible(values)) {
+    ptr.insertAfter(ptr.list.makeFrom(values));
+    return ptr;
+  }
+  if (!Array.isArray(values)) values = Array.from(values);
+  for (let i = values.length - 1; i >= 0; --i) {
+    ptr.addAfter(values[i]);
+  }
+  return ptr;
+};
+
+export const findNodeBy = (list, condition) => {
+  for (const node of list.getNodeIterator()) {
+    if (condition(node)) return node;
+  }
+  return null;
+};
+
+export const findPtrBy = (list, condition) => {
+  for (const ptr of list.getPtrIterator()) {
+    if (condition(ptr.node)) return ptr;
+  }
+  return null;
+};
+
+export const removeNodeBy = (list, condition) => {
+  for (const ptr of list.getPtrIterator()) {
+    if (condition(ptr.node)) return ptr.removeCurrent();
+  }
+  return null;
+};
+
+export const backPusher = (ExtListClass, options) => {
+  const list = new ExtListClass(null, options),
+    adapter = {
+      nextName: list.nextName,
+      prevName: list.prevName,
+
+      pushBackNode: node => {
+        const ptr = list.addNodeAfter(node);
+        list.next();
+        return ptr.node;
+      },
+
+      releaseList: () => list.make(list.next().detach())
+    };
+  return adapter;
+};
+
+export const frontPusher = (ExtListClass, options) => {
+  const list = new ExtListClass(null, options),
+    adapter = {
+      nextName: list.nextName,
+      prevName: list.prevName,
+
+      pushFrontNode: node => list.addNodeAfter(node).node,
+
+      releaseList: () => this.make(list.detach())
+    };
+  return adapter;
+};

package/src/list.js

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

package/src/meta-utils.js

@@ -0,0 +1,147 @@
+export const capitalize = name => (name ? name[0].toUpperCase() + name.substring(1).toLowerCase() : name);
+
+export const toCamelCase = names => names.map((name, index) => (index ? capitalize(name) : name.toLowerCase())).join('');
+export const fromCamelCase = name => name.split(/(?=[A-Z])/g);
+
+export const toPascalCase = names => names.map(name => capitalize(name)).join('');
+export const fromPascalCase = name => name.split(/(?=[A-Z])/g);
+
+export const toAllCapsSnakeCase = names => names.map(name => name.toUpperCase()).join('_');
+export const toSnakeCase = names => names.map(name => name.toLowerCase()).join('_');
+export const fromSnakeCase = name => name.split('_');
+
+export const toKebabCase = names => names.map(name => name.toLowerCase()).join('-');
+export const fromKebabCase = name => name.split('-');
+
+export const defaultDescriptor = {configurable: true, enumerable: true};
+
+export const fromGetter = (getter, defaultDescriptor = defaultDescriptor) => {
+  const descriptor = {...defaultDescriptor};
+  if (typeof getter == 'function') descriptor.get = getter;
+  return descriptor;
+};
+
+export const fromSetter = (setter, defaultDescriptor = defaultDescriptor) => {
+  const descriptor = {...defaultDescriptor};
+  if (typeof setter == 'function') descriptor.set = setter;
+  return descriptor;
+};
+
+export const fromAccessors = (getter, setter, defaultDescriptor = defaultDescriptor) => {
+  const descriptor = {...defaultDescriptor};
+  if (typeof getter == 'function') descriptor.get = getter;
+  if (typeof setter == 'function') descriptor.set = setter;
+  return descriptor;
+};
+
+export const addDescriptor = (target, names, descriptor, force) => {
+  if (!descriptor) return target;
+  if (typeof names == 'string') names = names.trim().split(/\s*,\s*/);
+  if (!Array.isArray(names)) names = [names];
+  for (const name of names) {
+    if (!force && target.hasOwnProperty(name)) continue;
+    Object.defineProperty(target, name, descriptor);
+  }
+  return target;
+};
+
+export const addDescriptors = (target, dict, force) => {
+  for (const [names, descriptor] of Object.entries(dict)) {
+    addDescriptor(target, names, descriptor, force);
+  }
+  for (const symbol of Object.getOwnPropertySymbols(dict)) {
+    const descriptor = Object.getOwnPropertyDescriptor(dict, symbol);
+    if (!descriptor || !descriptor.enumerable) continue;
+    addDescriptor(target, [symbol], dict[symbol], force);
+  }
+};
+
+export const addAccessor = (target, names, getter, setter, force) => addDescriptor(target, names, fromAccessors(getter, setter), force);
+
+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);
+    if (!descriptor || !descriptor.enumerable) continue;
+    addDescriptor(target, [symbol], fromGetter(dict[symbol]), force);
+  }
+};
+
+export const copyDescriptors = (target, source, names, force) => {
+  switch (typeof names) {
+    case 'string':
+      names = names.trim().split(/\s*,\s*/);
+      break;
+    case 'symbol':
+      names = [names];
+      break;
+  }
+  if (Array.isArray(names)) {
+    for (const name of names) {
+      addDescriptor(target, [name], Object.getOwnPropertyDescriptor(source, name), force);
+    }
+  } else {
+    for (const [name, aliases] of Object.entries(names)) {
+      addDescriptor(target, aliases, Object.getOwnPropertyDescriptor(source, name), force);
+    }
+    for (const symbol of Object.getOwnPropertySymbols(names)) {
+      const descriptor = Object.getOwnPropertyDescriptor(names, symbol);
+      if (!descriptor || !descriptor.enumerable) continue;
+      addDescriptor(target, names[symbol], Object.getOwnPropertyDescriptor(source, symbol), force);
+    }
+  }
+  return target;
+};
+
+export const addAlias = (object, name, aliases, force) => addDescriptor(object, aliases, Object.getOwnPropertyDescriptor(object, name), force);
+
+export const addAliases = (object, dict, force) => copyDescriptors(object, object, dict, force);
+
+export const augmentIterator = iterator => {
+  if (!Object.hasOwnProperty(Symbol.iterator)) {
+    iterator[Symbol.iterator] = function () {
+      return this;
+    };
+  }
+  return iterator;
+};
+
+let normalizeIterator = augmentIterator;
+if (typeof globalThis.Iterator?.from == 'function') {
+  normalizeIterator = iterator => Iterator.from(iterator);
+}
+export {normalizeIterator};
+
+export const mapIterator = (iterator, callbackFn) => {
+  if (typeof iterator?.map == 'function') return iterator.map(callbackFn);
+  return {
+    [Symbol.iterator]: () => {
+      const iterable = iterator[Symbol.iterator]();
+      let index = 0;
+      return normalizeIterator({
+        next: () => {
+          const result = iterable.next();
+          if (result.done) return result;
+          return {value: callbackFn(result.value, index++)};
+        }
+      });
+    }
+  };
+};
+
+export const copyOptions = (target, pattern, ...sources) => {
+  target = target || {};
+  const keys = Object.keys(pattern);
+  for (const key of keys) {
+    target[key] = pattern[key];
+  }
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+    for (const key of keys) {
+      if (key in source) target[key] = source[key];
+    }
+  }
+  return target;
+};

package/src/nt-utils.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// utilities for working with null-terminated lists
+
+export const isNTList = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return true;
+  let current = head;
+  do {
+    const next = current[nextName];
+    if (next === null) return true;
+    if (!next) break;
+    current = next;
+  } while (current !== head);
+  return false;
+};
+
+export const getNTListTail = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return null;
+  let current = head;
+  do {
+    const next = current[nextName];
+    if (!next) return current;
+    current = next;
+  } while (current !== head);
+  return null;
+};
+
+export const getNTListHead = (node, {prevName = 'prev'} = {}) => getNTListTail(node, {nextName: prevName});
+
+export const getNTListLength = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return 0;
+  let current = head;
+  let length = 1;
+  do {
+    const next = current[nextName];
+    if (!next) return length;
+    current = next;
+    ++length;
+  } while (current !== head);
+  return length;
+};
+
+export const makeListFromNTList = (node, {nextName = 'next', prevName = 'prev'} = {}) => {
+  if (node === null) return null;
+  const head = getNTListHead(node, {prevName}),
+    tail = getNTListTail(node, {nextName});
+  head[prevName] = tail;
+  tail[nextName] = head;
+  return {head, tail};
+};
+
+export const makeSListFromNTList = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return null;
+  const tail = getNTListTail(head, {nextName});
+  tail[nextName] = head;
+  return {head, tail};
+};
+
+export const makeNTListFromList = (head, {nextName = 'next', prevName = 'prev'} = {}) => {
+  if (head === null) return null;
+  const tail = head[prevName];
+  tail[nextName] = null;
+  head[prevName] = null;
+  return {head, tail};
+};
+
+export const makeNTListFromSListFast = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return null;
+  const tail = head;
+  head = head[nextName];
+  tail[nextName] = null;
+  return {head, tail};
+};
+
+export const makeNTListFromSList = (head, {nextName = 'next'} = {}) => {
+  if (head === null) return null;
+  let tail = head;
+  for (;;) {
+    const next = tail[nextName];
+    if (next === head) break;
+    tail = next;
+  }
+  tail[nextName] = null;
+  return {head, tail};
+};

package/src/queue.js

@@ -0,0 +1,52 @@
+'use strict';
+
+import ValueList from './value-list.js';
+import {addAliases} from './meta-utils.js';
+import {pushValuesBack} from './list-utils.js';
+
+export class Queue {
+  constructor(underlyingList = new ValueList()) {
+    this.list = underlyingList;
+    this.size = this.list.getLength();
+  }
+  get isEmpty() {
+    return this.list.isEmpty;
+  }
+  get top() {
+    return this.list.isEmpty ? undefined : this.list.front.value;
+  }
+  peek() {
+    return this.list.isEmpty ? undefined : this.list.front.value;
+  }
+  add(value) {
+    this.list.pushBack(value);
+    ++this.size;
+    return this;
+  }
+  remove() {
+    if (!this.list.isEmpty) {
+      --this.size;
+      return this.list.popFront();
+    }
+    // return undefined;
+  }
+  addValues(values) {
+    pushValuesBack(this, values);
+    return this;
+  }
+  clear() {
+    this.list.clear();
+    this.size = 0;
+    return this;
+  }
+  [Symbol.iterator]() {
+    return this.list[Symbol.iterator]();
+  }
+  getReverseIterator() {
+    return this.list.getReverseIterator?.();
+  }
+}
+
+addAliases(Queue.prototype, {add: 'push, pushBack, enqueue', remove: 'pop, popFront, dequeue'});
+
+export default Queue;

package/src/slist/basics.js

@@ -0,0 +1,47 @@
+'use strict';
+
+// useful low-level operations on singly linked lists
+
+export const extract = ({nextName}, {prevFrom, to = prevFrom[nextName]}) => {
+  const node = prevFrom[nextName],
+    next = to[nextName];
+
+  // exclude the range
+  prevFrom[nextName] = to[nextName];
+
+  // circle the range
+  to[nextName] = node;
+
+  return {extracted: {prevFrom: to, to}, rest: next === node ? null : next};
+};
+
+// pop(options, prev).node === extract(options, {prevFrom: prev}).prevFrom[options.nextName]
+
+export const pop = ({nextName}, prev) => {
+  const node = prev[nextName],
+    next = node[nextName];
+
+  // exclude the node
+  prev[nextName] = next;
+
+  // circle the node
+  node[nextName] = node;
+
+  return {extracted: {prevFrom: node, to: node}, rest: next === node ? null : next};
+};
+
+export const splice = ({nextName}, target, {prevFrom, to = prevFrom[nextName]}) => {
+  // form the combined head
+  const next = target[nextName];
+  target[nextName] = prevFrom[nextName];
+
+  // finish the combined  tail
+  prevFrom[nextName] = to[nextName];
+  to[nextName] = next;
+
+  return target;
+};
+
+// append(options, target, range) === splice(options, target, extract(options, range))
+
+export const append = splice;