@jay-framework/list-compare 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+declare const EoF: unique symbol;
+declare const BoF: unique symbol;
+interface LinkedListItem<T, S> {
+    id: string;
+    value: T;
+    attach?: S;
+    next: LinkedListItem<T, S> | typeof EoF;
+    prev: LinkedListItem<T, S> | typeof BoF;
+}
+/**
+ * hack for writing tests without typing, to reduce the need to cast items between LinkedListItem and BoF or EoF
+ */
+interface UntypedRandomAccessLinkedList {
+    first(): any;
+    last(): any;
+    get(id: any): any;
+    has(id: any): any;
+    add(obj: any, beforeItem: any, attach?: any): any;
+    remove(item: any): any;
+    move(itemToMove: any, toBefore: any): any;
+    forEach(handler: (item: any, attach: any, index: any) => void): any;
+}
+declare class RandomAccessLinkedList<T, S> implements UntypedRandomAccessLinkedList {
+    private readonly _matchBy;
+    private readonly _map;
+    private _last;
+    private _first;
+    constructor(arr: Array<T>, matchBy: string);
+    first(): LinkedListItem<T, S> | typeof EoF;
+    last(): LinkedListItem<T, S> | typeof BoF;
+    has(id: string): boolean;
+    get(id: string): LinkedListItem<T, S>;
+    move(itemToMove: LinkedListItem<T, S>, toBefore: LinkedListItem<T, S>): void;
+    remove(item: LinkedListItem<T, S>): void;
+    forEach(handler: (value: T, attach: S, index: number) => void): void;
+    add(obj: T, beforeItem?: LinkedListItem<T, S> | typeof EoF, attach?: S): void;
+    distance(from: LinkedListItem<T, S> | typeof EoF, to: LinkedListItem<T, S>): number;
+    get matchBy(): string;
+}
+
+declare const ITEM_ADDED = "IA";
+declare const ITEM_REMOVED = "IR";
+declare const ITEM_MOVED = "IM";
+interface MatchResult<T, S> {
+    action: typeof ITEM_ADDED | typeof ITEM_MOVED | typeof ITEM_REMOVED;
+    item?: T;
+    pos: number;
+    fromPos?: number;
+    elem?: S;
+}
+declare function listCompare<T, S>(oldArray: RandomAccessLinkedList<T, S>, newArray: RandomAccessLinkedList<T, S>, mkElement: (T: any, id: string) => S): Array<MatchResult<T, S>>;
+
+export { BoF, EoF, ITEM_ADDED, ITEM_MOVED, ITEM_REMOVED, type LinkedListItem, type MatchResult, RandomAccessLinkedList, type UntypedRandomAccessLinkedList, listCompare };

package/dist/index.js

@@ -0,0 +1,233 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => {
+  __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+  return value;
+};
+const EoF = Symbol("EoF");
+const BoF = Symbol("BoF");
+class RandomAccessLinkedList {
+  constructor(arr, matchBy) {
+    __publicField(this, "_matchBy");
+    __publicField(this, "_map");
+    __publicField(this, "_last");
+    __publicField(this, "_first");
+    this._matchBy = matchBy;
+    this._map = {};
+    this._last = BoF;
+    this._first = arr.reduceRight(
+      (nextItem, obj) => {
+        let item = {
+          id: obj[matchBy],
+          value: obj,
+          next: nextItem,
+          prev: BoF
+        };
+        if (nextItem !== EoF)
+          nextItem.prev = item;
+        if (this._last === BoF)
+          this._last = item;
+        this._map[item.id] = item;
+        return item;
+      },
+      EoF
+    );
+  }
+  first() {
+    return this._first;
+  }
+  last() {
+    return this._last;
+  }
+  has(id) {
+    return !!this._map[id];
+  }
+  get(id) {
+    return this._map[id];
+  }
+  move(itemToMove, toBefore) {
+    this.remove(itemToMove);
+    this.add(itemToMove.value, toBefore, itemToMove.attach);
+  }
+  remove(item) {
+    delete this._map[this._matchBy];
+    if (item.prev === BoF) {
+      if (item.next !== EoF) {
+        item.next.prev = BoF;
+        this._first = item.next;
+      } else {
+        this._first = EoF;
+        this._last = BoF;
+      }
+    } else if (item.next === EoF) {
+      this._last = item.prev;
+      item.prev.next = EoF;
+    } else {
+      item.prev.next = item.next;
+      item.next.prev = item.prev;
+    }
+  }
+  forEach(handler) {
+    let listItem = this.first();
+    let index = 0;
+    while (listItem !== EoF) {
+      handler(listItem.value, listItem.attach, index++);
+      listItem = listItem.next;
+    }
+  }
+  add(obj, beforeItem = EoF, attach = void 0) {
+    let newItem;
+    if (this._first === EoF && this._last === BoF) {
+      newItem = { id: obj[this._matchBy], value: obj, prev: BoF, next: EoF, attach };
+      this._first = newItem;
+      this._last = newItem;
+    } else if (beforeItem === EoF) {
+      newItem = { id: obj[this._matchBy], value: obj, prev: this._last, next: EoF, attach };
+      this._last.next = newItem;
+      this._last = newItem;
+    } else if (beforeItem === this._first) {
+      newItem = { id: obj[this._matchBy], value: obj, prev: BoF, next: beforeItem, attach };
+      this._first = newItem;
+      beforeItem.prev = newItem;
+    } else {
+      let itemBefore = beforeItem.prev;
+      newItem = {
+        id: obj[this._matchBy],
+        value: obj,
+        prev: itemBefore,
+        next: beforeItem,
+        attach
+      };
+      itemBefore.next = newItem;
+      beforeItem.prev = newItem;
+    }
+    this._map[newItem.id] = newItem;
+  }
+  distance(from, to) {
+    let count = 0;
+    while (from !== to && from !== EoF) {
+      count++;
+      from = from.next;
+    }
+    return from !== EoF ? count : -1;
+  }
+  get matchBy() {
+    return this._matchBy;
+  }
+}
+const ITEM_ADDED = "IA";
+const ITEM_REMOVED = "IR";
+const ITEM_MOVED = "IM";
+const MOVED_FORWARD_NONE = 0;
+const MOVED_FORWARD_IN_SEQUENCE = 1;
+function listCompare(oldArray, newArray, mkElement) {
+  let oldList = oldArray;
+  let newList = newArray;
+  let oldListItem = oldList.first();
+  let newListItem_ = newList.first();
+  let oldIndex = 0;
+  let index = 0;
+  let instructions = [];
+  function addNewItem(newListItem) {
+    let newElement = mkElement(newListItem.value, newListItem.id);
+    oldList.add(newListItem.value, oldListItem, newElement);
+    newListItem.attach = newElement;
+    instructions.push({
+      action: ITEM_ADDED,
+      item: newListItem.value,
+      pos: index,
+      elem: newElement
+    });
+    newListItem_ = newListItem.next;
+    index += 1;
+  }
+  while (newListItem_ !== EoF) {
+    let newListItem = newListItem_;
+    if (oldListItem === EoF) {
+      addNewItem(newListItem);
+    } else if (oldListItem.id !== newListItem.id) {
+      if (!newList.has(oldListItem.id)) {
+        instructions.push({
+          action: ITEM_REMOVED,
+          item: oldListItem.value,
+          pos: index,
+          elem: oldListItem.attach
+        });
+        oldList.remove(oldListItem);
+        oldListItem = oldListItem.next;
+      } else if (oldList.has(newListItem.id)) {
+        let oldListItemToMove = oldList.get(newListItem.id);
+        newListItem.attach = oldListItemToMove.attach;
+        let distance = oldList.distance(oldListItem, oldListItemToMove);
+        instructions.push({
+          action: ITEM_MOVED,
+          item: oldListItemToMove.value,
+          pos: index,
+          fromPos: oldIndex + distance
+        });
+        oldList.move(oldListItemToMove, oldListItem);
+        newListItem_ = newListItem.next;
+        index += 1;
+        oldIndex += 1;
+      } else {
+        addNewItem(newListItem);
+        oldIndex += 1;
+      }
+    } else {
+      newListItem.attach = oldListItem.attach;
+      oldListItem = oldListItem.next;
+      newListItem_ = newListItem.next;
+      index += 1;
+      oldIndex += 1;
+    }
+  }
+  while (oldListItem !== EoF) {
+    instructions.push({
+      action: ITEM_REMOVED,
+      item: oldListItem.value,
+      pos: oldIndex,
+      elem: oldListItem.attach
+    });
+    oldList.remove(oldListItem);
+    oldListItem = oldListItem.next;
+  }
+  return optimize(instructions);
+}
+function optimize(instructions) {
+  function optimizeSequence(sequenceStart, sequenceEnd) {
+    let newMove = {
+      action: ITEM_MOVED,
+      pos: instructions[sequenceEnd].fromPos,
+      fromPos: instructions[sequenceStart].pos
+    };
+    instructions.splice(sequenceStart, sequenceEnd - sequenceStart + 1, newMove);
+  }
+  let movedForwardSequenceEnd;
+  let movedForwardState = MOVED_FORWARD_NONE;
+  for (let i = instructions.length - 1; i >= 0; i--) {
+    let isCandidateForOptimization = instructions[i].action === ITEM_MOVED && instructions[i].pos + 1 === instructions[i].fromPos;
+    if (movedForwardState === MOVED_FORWARD_IN_SEQUENCE && (!isCandidateForOptimization || instructions[i].pos + 1 !== instructions[i + 1].pos)) {
+      if (i + 1 !== movedForwardSequenceEnd) {
+        optimizeSequence(i + 1, movedForwardSequenceEnd);
+      }
+      movedForwardState = MOVED_FORWARD_NONE;
+    }
+    if (movedForwardState === MOVED_FORWARD_NONE && isCandidateForOptimization) {
+      movedForwardState = MOVED_FORWARD_IN_SEQUENCE;
+      movedForwardSequenceEnd = i;
+    }
+  }
+  if (movedForwardState === MOVED_FORWARD_IN_SEQUENCE && movedForwardSequenceEnd > 1) {
+    optimizeSequence(0, movedForwardSequenceEnd);
+  }
+  return instructions;
+}
+export {
+  BoF,
+  EoF,
+  ITEM_ADDED,
+  ITEM_MOVED,
+  ITEM_REMOVED,
+  RandomAccessLinkedList,
+  listCompare
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@jay-framework/list-compare",
+  "version": "0.5.0",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "readme.md"
+  ],
+  "scripts": {
+    "build": "npm run build:js && npm run build:types",
+    "build:watch": "npm run build:js -- --watch & npm run build:types -- --watch",
+    "build:js": "vite build",
+    "build:types": "tsup lib/index.ts --dts-only --format esm",
+    "build:check-types": "tsc",
+    "clean": "rimraf dist",
+    "confirm": "npm run clean && npm run build && npm run build:check-types && npm run test",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@jay-framework/dev-environment": "workspace:^",
+    "@types/node": "^20.11.5",
+    "rimraf": "^5.0.5",
+    "tsup": "^8.0.1",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.11",
+    "vitest": "^1.2.1"
+  }
+}

package/readme.md

@@ -0,0 +1,103 @@
+# list-compare `listCompare<T, S>()`
+
+The list compare library is an algorithm to compute the mutations needed to update list `A` into list `B`.
+
+## list compare signature
+
+The algorithm signature is
+
+```typescript
+export interface MatchResult<T, S> {
+  action: typeof ITEM_ADDED | typeof ITEM_MOVED | typeof ITEM_REMOVED;
+  item?: T;
+  pos: number;
+  fromPos?: number;
+  elem?: S;
+}
+
+declare function listCompare<T, S>(
+  oldArray: RandomAccessLinkedList<T, S>,
+  newArray: RandomAccessLinkedList<T, S>,
+  mkElement: (T, id: string) => S,
+): Array<MatchResult<T, S>>;
+```
+
+The algorithm compares two instances of a RandomAccessLinkedList data structure and generates instructions for
+transforming one list into the other.
+
+### Inputs:
+
+- `oldArray`: The first RandomAccessLinkedList instance (assumed to be the original list).
+- `newArray`: The second RandomAccessLinkedList instance (assumed to be the desired state).
+- `mkElement`: A function that takes an item value and an ID and creates an element of type S.
+  This function is application specific to the application using the algorithm.
+
+### Outputs:
+
+An array of `MatchResult` objects, which describe the changes needed to transform the old list into the new list.
+Each `MatchResult` object has the following properties:
+
+- `action`: A string representing the type of change needed. Possible values are:
+  - `ITEM_ADDED`: A new item needs to be inserted.
+  - `ITEM_REMOVED`: An existing item needs to be removed.
+  - `ITEM_MOVED`: An existing item needs to be moved to a different position.
+- `item`: The value of the item being added or moved (applicable for ITEM_ADDED and ITEM_MOVED).
+- `pos`: The position in the new list where the item should be (applicable for ITEM_ADDED and ITEM_MOVED).
+- `fromPos`: The original position of the item being moved from (applicable for ITEM_MOVED).
+- `elem`: The attachment object of type `S` created for the item for application specific usage.
+
+## algorithm notes
+
+- The algorithm **mutates the `oldArray` into `newArray`** as part of the algorithm.
+- The algorithm efficiency is `O(N log(N))`.
+- The algorithm is used by the `@jay-framework/json-patch` to compute the JSON diff with support for item movement,
+- The algorithm is used by the `@jay-framework/runtime` to compute how to update the DOM for repeated items in the most efficient way.
+- The algorithm is using the `RandomAccessLinkedList<T, S>` to optimize performance
+- The algorithm assumes items `T` have an `id` which is used to match the same item between `oldArray` into `newArray`.
+- The algorithm assumes an item `T` may have an attached item `S`.
+  - The attachment `S` is moved with the original item `T`.
+  - The attachment is used by the `@jay-framework/runtime` package when ordering `ViewState` items, while the attachment is the DOM
+    element associated with the `ViewState` item. This allows the algorithm instructions to be used for moving DOM elements.
+  - The algorithm, when using attachments, also receives a `mkElement` function that is used for creating the attachment
+    for new items (items that appear in `newArray` but not in `oldArray` by `id` matching).
+
+## Example
+
+Consider the following two arrays:
+
+```typescript
+const array_1 = [
+  { id: 'a114' },
+  { id: 'a33' },
+  { id: 'a75' },
+  { id: 'a201' },
+  { id: 'a153' },
+  { id: 'a204' },
+  { id: 'a207' },
+];
+const array_2 = [
+  { id: 'a114' },
+  { id: 'a75' },
+  { id: 'a153' },
+  { id: 'a204' },
+  { id: 'a207' },
+  { id: 'a210' },
+  { id: 'a201' },
+];
+
+const result = listCompare(
+  new RandomAccessLinkedList(array_1),
+  new RandomAccessLinkedList(array_2),
+  () => undefined,
+);
+expect(result).toEqual([
+  { action: ITEM_REMOVED, item: { id: 'a33' }, pos: 1 },
+  { action: ITEM_MOVED, pos: 5, fromPos: 2 },
+  { action: ITEM_ADDED, item: { id: 'a210' }, pos: 5 },
+]);
+```
+
+## `RandomAccessLinkedList<T, S>`
+
+A double-sided linked list implementation combined with a map `id -> LinkedListItem<T, S>` random access.
+It is used by the `listCompare<T, S>()` algorithm for performance.