articulated 0.1.0

package/build/esm/saved_id_list.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=saved_id_list.js.map

package/build/esm/saved_id_list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"saved_id_list.js","sourceRoot":"","sources":["../../src/saved_id_list.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "articulated",
+  "version": "0.1.0",
+  "description": "A TypeScript library for managing stable element identifiers in mutable lists",
+  "author": "Matthew Weidner",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mweidner037/articulated/issues"
+  },
+  "homepage": "https://github.com/mweidner037/articulated#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mweidner037/articulated.git"
+  },
+  "keywords": [
+    "list",
+    "UUID",
+    "CRDT"
+  ],
+  "main": "build/commonjs/index.js",
+  "browser": "build/esm/index.js",
+  "module": "build/esm/index.js",
+  "types": "build/esm/index.d.ts",
+  "files": [
+    "/build",
+    "/src"
+  ],
+  "directories": {
+    "lib": "src"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@istanbuljs/nyc-config-typescript": "^1.0.2",
+    "@types/chai": "^4.3.4",
+    "@types/mocha": "^10.0.1",
+    "@typescript-eslint/eslint-plugin": "^7.7.1",
+    "@typescript-eslint/parser": "^7.7.1",
+    "chai": "^4.3.7",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-import": "^2.29.1",
+    "mocha": "^10.2.0",
+    "npm-run-all": "^4.1.5",
+    "nyc": "^15.1.0",
+    "prettier": "^2.8.4",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.4.5"
+  },
+  "scripts": {
+    "prepack": "npm run clean && npm run build && npm run test",
+    "build": "npm-run-all build:*",
+    "build:ts": "tsc -p tsconfig.json && tsc -p tsconfig.commonjs.json",
+    "test": "npm-run-all test:*",
+    "test:lint": "eslint --ext .ts,.js .",
+    "test:unit": "TS_NODE_PROJECT='./tsconfig.dev.json' mocha",
+    "test:format": "prettier --check .",
+    "coverage": "npm-run-all coverage:*",
+    "coverage:run": "nyc npm run test:unit",
+    "coverage:open": "open coverage/index.html > /dev/null 2>&1 &",
+    "fix": "npm-run-all fix:*",
+    "fix:format": "prettier --write .",
+    "docs": "typedoc --options typedoc.json src/index.ts",
+    "clean": "rm -rf build docs coverage .nyc_output"
+  }
+}

package/src/id.ts

@@ -0,0 +1,75 @@
+/**
+ * A unique and immutable id for a list element.
+ *
+ * ElementIds are conceptually the same as UUIDs (or nanoids, etc.).
+ * However, when a single thread generates a series of ElementIds, you are
+ * allowed to optimize by generating a single UUID/nanoid/etc. and using that as the "bunchId"
+ * for a "bunch" of elements, with varying `counter`.
+ * The resulting ElementIds compress better than a set of UUIDs, but they are
+ * still globally unique, even if another thread/user/device generates ElementIds concurrently.
+ *
+ * For example, if a user types a sentence from left to right, you may generate a
+ * single `bunchId` and assign their characters the sequential ElementIds
+ * `{ bunchId, counter: 0 }, { bunchId, counter: 1 }, { bunchId, counter: 2 }, ...`.
+ * An IdList will store all of these as a single object instead of
+ * one object per ElementId.
+ */
+export interface ElementId {
+  /**
+   * A UUID or similar globally unique ID.
+   *
+   * You must choose this so that the resulting ElementId is globally unique,
+   * even if another part of your application creates
+   * ElementIds concurrently (possibly on a different device).
+   */
+  readonly bunchId: string;
+  /**
+   * An integer used to distinguish ElementIds in the same bunch.
+   *
+   * Typically, you will assign sequential counters 0, 1, 2, ... to list elements
+   * that are initially inserted in a left-to-right order.
+   * IdList is optimized for this case, but it is not mandatory.
+   * In particular, it is okay if future edits cause the sequential ids to be
+   * separated, partially deleted, or even reordered.
+   *
+   * Negative integers are supported by IdList (e.g., for optimized right-to-left insertions),
+   * though you may choose to avoid these in your application, to make serialization easier.
+   */
+  readonly counter: number;
+}
+
+/**
+ * Equals function for ElementIds.
+ */
+export function equalsId(a: ElementId, b: ElementId) {
+  return a.counter === b.counter && a.bunchId === b.bunchId;
+}
+
+/**
+ * Expands a "compressed" sequence of ElementIds that have the same bunchId but
+ * sequentially increasing counters, starting at `startId.counter`.
+ *
+ * For example,
+ * ```ts
+ * expandIds({ bunchId: "foo", counter: 7 }, 3)
+ * ```
+ * returns
+ * ```ts
+ * [
+ *   { bunchId: "foo", counter: 7 },
+ *   { bunchId: "foo", counter: 8 },
+ *   { bunchId: "foo", counter: 9 }
+ * ]
+ * ```
+ */
+export function expandIds(startId: ElementId, count: number): ElementId[] {
+  if (!(Number.isSafeInteger(count) && count >= 0)) {
+    throw new Error(`Invalid count: ${count}`);
+  }
+
+  const ans: ElementId[] = [];
+  for (let i = 0; i < count; i++) {
+    ans.push({ bunchId: startId.bunchId, counter: startId.counter + i });
+  }
+  return ans;
+}

package/src/id_list.ts

@@ -0,0 +1,471 @@
+import { ElementId, equalsId } from "./id";
+import { SavedIdList } from "./saved_id_list";
+
+interface ListElement {
+  id: ElementId;
+  isDeleted: boolean;
+}
+
+/**
+ * A list of ElementIds.
+ *
+ * An IdList helps you assign a unique immutable id to each element of a list, such
+ * as a todo-list or a text document (= list of characters). That way, you can keep track
+ * of those elements even as their (array) indices change due to insert/delete operations
+ * earlier in the list.
+ *
+ * Any id that has been inserted into an IdList remains **known** to that list indefinitely,
+ * allowing you to reference it in insertAfter/insertBefore operations. Calling {@link delete}
+ * merely marks an id as deleted (not present); it remains in memory as a "tombstone".
+ * This is useful in collaborative settings, since another user might instruct you to
+ * call `insertAfter(before, newId)` when you have already deleted `before` locally.
+ * If that is not a concern and you truly want to make an id no longer known, instead
+ * call {@link uninsert}.
+ *
+ * See {@link ElementId} for advice on generating ElementIds. IdList is optimized for
+ * the case where sequential ElementIds often have the same bunchId and sequential counters.
+ * However, you are not required to order ids in this way - it is okay if future edits
+ * cause such ids to be separated, partially deleted, or even reordered.
+ */
+export class IdList {
+  private readonly state: ListElement[];
+  private _length: number;
+
+  /**
+   * Constructs an empty list.
+   *
+   * To begin with a non-empty list, use {@link IdList.from} or {@link IdList.fromIds}.
+   */
+  constructor() {
+    this.state = [];
+    this._length = 0;
+  }
+
+  /**
+   * Constructs a list with the given known ids and their isDeleted status, in list order.
+   */
+  static from(state: Iterable<{ id: ElementId; isDeleted: boolean }>) {
+    const list = new IdList();
+    for (const { id, isDeleted } of state) {
+      // Clone to prevent aliasing.
+      list.state.push({ id, isDeleted });
+      if (!isDeleted) list._length++;
+    }
+    return list;
+  }
+
+  /**
+   * Constructs a list with the given present ids.
+   *
+   * Typically, you instead want {@link IdList.from}, which allows you to also
+   * specify known-but-deleted ids. That way, you can reference the known-but-deleted ids
+   * in future insertAfter/insertBefore operations.
+   */
+  static fromIds(ids: Iterable<ElementId>) {
+    const list = new IdList();
+    for (const id of ids) {
+      list.state.push({ id, isDeleted: false });
+      list._length++;
+    }
+    return list;
+  }
+
+  /**
+   * Inserts `newId` immediately after the given id (`before`), which may be deleted.
+   * All ids to the right of `before` are shifted one index to the right, in the manner
+   * of [Array.splice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice).
+   *
+   * Use `before = null` to insert at the beginning of the list, to the left of all
+   * known ids.
+   *
+   * @param count Provide this to bulk-insert `count` ids from left-to-right,
+   * starting with newId and proceeding with the same bunchId and sequential counters.
+   * @throws If `before` is not known.
+   * @throws If `newId` is already known.
+   */
+  insertAfter(before: ElementId | null, newId: ElementId, count = 1) {
+    if (this.isKnown(newId)) {
+      throw new Error("newId is already known");
+    }
+
+    let index: number;
+    if (before === null) {
+      // -1 so index + 1 is 0: insert at the beginning of the list.
+      index = -1;
+    } else {
+      index = this.state.findIndex((elt) => equalsId(elt.id, before));
+      if (index === -1) {
+        throw new Error("before is not known");
+      }
+    }
+
+    this.state.splice(index + 1, 0, ...expandElements(newId, false, count));
+    this._length += count;
+  }
+
+  /**
+   * Inserts `newId` immediately before the given id (`after`), which may be deleted.
+   * All ids to the right of `after`, plus `after` itself, are shifted one index to the right, in the manner
+   * of [Array.splice](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/splice).
+   *
+   * Use `after = null` to insert at the end of the list, to the right of all known ids.
+   *
+   * @param count Provide this to bulk-insert `count` ids from left-to-right,
+   * starting with newId and proceeding with the same bunchId and sequential counters.
+   * __Note__: Although the new ids are inserted to the left of `after`, they are still
+   * inserted in left-to-right order relative to each other.
+   * @throws If `after` is not known.
+   * @throws If `newId` is already known.
+   */
+  insertBefore(after: ElementId | null, newId: ElementId, count = 1) {
+    if (this.isKnown(newId)) {
+      throw new Error("newId is already known");
+    }
+
+    let index: number;
+    if (after === null) {
+      index = this.state.length;
+    } else {
+      index = this.state.findIndex((elt) => equalsId(elt.id, after));
+      if (index === -1) {
+        throw new Error("after is not known");
+      }
+    }
+
+    // We insert the bunch from left-to-right even though it's insertBefore.
+    this.state.splice(index, 0, ...expandElements(newId, false, count));
+    this._length += count;
+  }
+
+  /**
+   * Un-inserts `id` from the list, making it no longer known or present in this list.
+   *
+   * Typically, you instead want to call {@link delete}, which marks `id` as deleted while
+   * it remains known. That way, you can reference `id` in future insertAfter/insertBefore
+   * operations, including ones sent concurrently by other devices.
+   *
+   * If `id` is already not known, this method does nothing.
+   */
+  uninsert(id: ElementId) {
+    const index = this.state.findIndex((elt) => equalsId(elt.id, id));
+    if (index !== -1) {
+      this.state.splice(index, 1);
+      this._length--;
+    }
+  }
+
+  /**
+   * Marks `id` as deleted from this list. The id remains known (a "tombstone").
+   *
+   * Because `id` is still known, you can reference it in future insertAfter/insertBefore
+   * operations, including ones sent concurrently by other devices.
+   * However, it does occupy space in memory (compressed in common cases).
+   *
+   * For an exact inverse to `insertAfter(-, id)` or `insertBefore(-, id)`
+   * that makes `id` no longer known, see {@link uninsert}.
+   *
+   * If `id` is already deleted or not known, this method does nothing.
+   */
+  delete(id: ElementId) {
+    const elt = this.state.find((elt) => equalsId(elt.id, id));
+    if (elt !== undefined && !elt.isDeleted) {
+      elt.isDeleted = true;
+      this._length--;
+    }
+  }
+
+  /**
+   * Un-marks `id` as deleted from this list, making it present again.
+   * This is an exact inverse to {@link delete}.
+   *
+   * If `id` is already present, this method does nothing.
+   *
+   * @throws If `id` is not known.
+   */
+  undelete(id: ElementId) {
+    const elt = this.state.find((elt) => equalsId(elt.id, id));
+    if (elt === undefined) {
+      throw new Error("id is not known");
+    }
+    if (elt.isDeleted) {
+      elt.isDeleted = false;
+      this._length++;
+    }
+  }
+
+  // Accessors
+
+  /**
+   * Returns whether `id` is present in the list, i.e., it is known and not deleted.
+   *
+   * If `id` is not known, false is returned.
+   *
+   * Compare to {@link isKnown}.
+   */
+  has(id: ElementId): boolean {
+    const elt = this.state.find((elt) => equalsId(elt.id, id));
+    if (elt === undefined) return false;
+    return !elt.isDeleted;
+  }
+
+  /**
+   * Returns whether id is known to this list.
+   *
+   * Compare to {@link has}.
+   */
+  isKnown(id: ElementId): boolean {
+    return this.state.some((elt) => equalsId(elt.id, id));
+  }
+
+  /**
+   * Returns the id at the given index in the list.
+   *
+   * @throws If index is out of bounds.
+   */
+  at(index: number): ElementId {
+    if (!(Number.isSafeInteger(index) && 0 <= index && index < this.length)) {
+      throw new Error(`Index out of bounds: ${index} (length: ${this.length}`);
+    }
+
+    let remaining = index;
+    for (const elt of this.state) {
+      if (!elt.isDeleted) {
+        if (remaining === 0) return elt.id;
+        remaining--;
+      }
+    }
+
+    throw new Error("Internal error");
+  }
+
+  /**
+   * Returns the index of `id` in the list.
+   *
+   * If `id` is known but deleted, the bias specifies what to return:
+   * - "none": -1.
+   * - "left": The index immediately to the left of `id`, possibly -1.
+   * - "right": The index immediately to the right of `id`, possibly `this.length`.
+   * Equivalently, the index where `id` would be if present.
+   *
+   * @throws If `id` is not known.
+   */
+  indexOf(id: ElementId, bias: "none" | "left" | "right" = "none"): number {
+    /**
+     * The number of present ids less than id.
+     * Equivalently, the index id would have if present.
+     */
+    let index = 0;
+    for (const elt of this.state) {
+      if (equalsId(elt.id, id)) {
+        // Found it.
+        if (elt.isDeleted) {
+          switch (bias) {
+            case "none":
+              return -1;
+            case "left":
+              return index - 1;
+            case "right":
+              return index;
+          }
+        } else return index;
+      }
+      if (!elt.isDeleted) index++;
+    }
+
+    throw new Error("id is not known");
+  }
+
+  /**
+   * The length of the list.
+   */
+  get length(): number {
+    return this._length;
+  }
+
+  // Iterators and views
+
+  /**
+   * Iterates over all present ids in the list.
+   */
+  *[Symbol.iterator](): IterableIterator<ElementId> {
+    for (const elt of this.state) {
+      if (!elt.isDeleted) yield elt.id;
+    }
+  }
+
+  /**
+   * Iterates over all present ids in the list.
+   */
+  values() {
+    return this[Symbol.iterator]();
+  }
+
+  /**
+   * Iterates over all __known__ ids in the list, indicating which are deleted.
+   */
+  valuesWithDeleted(): IterableIterator<{ id: ElementId; isDeleted: boolean }> {
+    return this.state.values();
+  }
+
+  /**
+   * Returns an independent copy of this list, including known but deleted ids.
+   */
+  clone(): IdList {
+    return IdList.from(this.state);
+  }
+
+  private _knownIds?: KnownIdView;
+
+  /**
+   * A live-updating view of this list that treats all known ids as present.
+   * That is, it ignores isDeleted status when computing list indices or iterating.
+   */
+  get knownIds(): KnownIdView {
+    if (this._knownIds === undefined) {
+      this._knownIds = new KnownIdView(this, this.state);
+    }
+    return this._knownIds;
+  }
+
+  // Save and load
+
+  /**
+   * Returns a compact JSON representation of this list's internal state.
+   * Load with {@link load}.
+   *
+   * See {@link SavedIdList} for a description of the save format.
+   */
+  save(): SavedIdList {
+    const ans: SavedIdList = [];
+
+    for (const { id, isDeleted } of this.state) {
+      if (ans.length !== 0) {
+        const current = ans[ans.length - 1];
+        if (
+          id.bunchId === current.bunchId &&
+          id.counter === current.startCounter + current.count &&
+          isDeleted === current.isDeleted
+        ) {
+          current.count++;
+          continue;
+        }
+      }
+
+      ans.push({
+        bunchId: id.bunchId,
+        startCounter: id.counter,
+        count: 1,
+        isDeleted,
+      });
+    }
+
+    return ans;
+  }
+
+  /**
+   * Loads a saved state returned by {@link save}, __overwriting__ the current state of this list.
+   */
+  load(savedState: SavedIdList) {
+    this.state.length = 0;
+    this._length = 0;
+
+    for (const { bunchId, startCounter, count, isDeleted } of savedState) {
+      if (!(Number.isSafeInteger(count) && count >= 0)) {
+        throw new Error(`Invalid length: ${count}`);
+      }
+
+      for (let i = 0; i < count; i++) {
+        this.state.push({
+          id: { bunchId, counter: startCounter + i },
+          isDeleted,
+        });
+      }
+      if (!isDeleted) this._length += count;
+    }
+  }
+}
+
+/**
+ * A live-updating view of an IdList that treats all known ids as present.
+ * That is, this class ignores the underlying list's isDeleted status when computing list indices.
+ *
+ * To mutate, call methods on the original IdList (`this.list`).
+ */
+export class KnownIdView {
+  /**
+   * Internal use only. Use {@link IdList.knownIds} instead.
+   */
+  constructor(readonly list: IdList, private readonly state: ListElement[]) {}
+
+  // Mutators are omitted - mutate this.list instead.
+
+  // Accessors
+
+  /**
+   * Returns the id at the given index in this view.
+   *
+   * Equivalently, returns the index-th known id in `this.list`.
+   *
+   * @throws If index is out of bounds.
+   */
+  at(index: number): ElementId {
+    if (!(Number.isSafeInteger(index) && 0 <= index && index < this.length)) {
+      throw new Error(`Index out of bounds: ${index} (length: ${this.length}`);
+    }
+
+    return this.state[index].id;
+  }
+
+  /**
+   * Returns the index of `id` in this view, or -1 if it is not known.
+   */
+  indexOf(id: ElementId): number {
+    return this.state.findIndex((elt) => equalsId(elt.id, id));
+  }
+
+  /**
+   * The length of this view.
+   *
+   * Equivalently, the number of known ids in `this.list`.
+   */
+  get length(): number {
+    return this.state.length;
+  }
+
+  // Iterators
+
+  /**
+   * Iterates over all ids in this view, i.e., all known ids in `this.list`.
+   */
+  *[Symbol.iterator](): IterableIterator<ElementId> {
+    for (const elt of this.state) {
+      yield elt.id;
+    }
+  }
+
+  /**
+   * Iterates over all ids in this view, i.e., all known ids in `this.list`.
+   */
+  values() {
+    return this[Symbol.iterator]();
+  }
+}
+
+function expandElements(
+  startId: ElementId,
+  isDeleted: boolean,
+  count: number
+): ListElement[] {
+  if (!(Number.isSafeInteger(count) && count >= 0)) {
+    throw new Error(`Invalid count: ${count}`);
+  }
+
+  const ans: ListElement[] = [];
+  for (let i = 0; i < count; i++) {
+    ans.push({
+      id: { bunchId: startId.bunchId, counter: startId.counter + i },
+      isDeleted,
+    });
+  }
+  return ans;
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./id";
+export * from "./id_list";
+export * from "./saved_id_list";

package/src/saved_id_list.ts

@@ -0,0 +1,13 @@
+/**
+ * Saved state for an IdList.
+ *
+ * It describes all of the list's known ElementIds in list order, with basic compression:
+ * if sequential ElementIds have the same bunchId, the same isDeleted status,
+ * and sequential counters, then they are combined into a single object.
+ */
+export type SavedIdList = Array<{
+  bunchId: string;
+  startCounter: number;
+  count: number;
+  isDeleted: boolean;
+}>;