articulated 1.0.0 → 1.2.0

package/src/id_list.ts

@@ -1,6 +1,7 @@
 import { SparseIndices } from "sparse-array-rled";
-import { ElementId } from "./id";
+import { ElementId } from "./element_id";
 import { LeafMap, MutableLeafMap } from "./internal/leaf_map";
+import { checkCount } from "./internal/misc";
 import { getAndBumpNextSeq, MutableSeqMap, SeqMap } from "./internal/seq_map";
 import { SavedIdList } from "./saved_id_list";
 
@@ -271,9 +272,7 @@ export class IdList {
     if (!(Number.isSafeInteger(newId.counter) && newId.counter >= 0)) {
       throw new Error(`Invalid counter: ${newId.counter}`);
     }
-    if (!(Number.isSafeInteger(count) && count >= 0)) {
-      throw new Error(`Invalid count: ${count}`);
-    }
+    checkCount(count);
     if (this.isAnyKnown(newId, count)) {
       throw new Error("An inserted id is already known");
     }
@@ -386,9 +385,7 @@ export class IdList {
     if (!(Number.isSafeInteger(newId.counter) && newId.counter >= 0)) {
       throw new Error(`Invalid counter: ${newId.counter}`);
     }
-    if (!(Number.isSafeInteger(count) && count >= 0)) {
-      throw new Error(`Invalid count: ${count}`);
-    }
+    checkCount(count);
     if (this.isAnyKnown(newId, count)) {
       throw new Error("An inserted id is already known");
     }
@@ -489,9 +486,7 @@ export class IdList {
    * `uninsert(id, count)` is an exact inverse to `insertAfter(-, id, count)` or `insertBefore(-, id, count)`.
    */
   uninsert(id: ElementId, count = 1) {
-    if (!(Number.isSafeInteger(count) && count >= 0)) {
-      throw new Error(`Invalid count: ${count}`);
-    }
+    checkCount(count);
     if (count === 0) return this;
 
     // We optimize for the case where you are undoing the most recent insert operation.
@@ -568,8 +563,23 @@ export class IdList {
    * This does have a memory cost, but it is compressed in common cases.
    *
    * If `id` is already deleted or is not known, this method does nothing.
+   *
+   * @param count Provide this to bulk-delete `count` ids,
+   * starting with newId and proceeding with the same bunchId and sequential counters.
+   * __Note__: To delete multiple ids at sequential *indexes*, use deleteRange.
    */
-  delete(id: ElementId) {
+  delete(id: ElementId, count = 1) {
+    checkCount(count);
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let ans: IdList = this;
+    for (let i = 0; i < count; i++) {
+      ans = ans.deleteOne({ bunchId: id.bunchId, counter: id.counter + i });
+    }
+    return ans;
+  }
+
+  private deleteOne(id: ElementId) {
     const located = this.locate(id);
     if (located === null) return this;
 
@@ -582,6 +592,24 @@ export class IdList {
     return this.replaceLeaf(located, { ...leaf, present: newPresent });
   }
 
+  /**
+   * Deletes all ids with indexes in the range [from, to).
+   *
+   * @throws If any deleted index is out of bounds.
+   */
+  deleteRange(from: number, to: number) {
+    const allIds: ElementId[] = [];
+    for (let i = from; i < to; i++) {
+      allIds.push(this.at(i));
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let ans: IdList = this;
+    for (const id of allIds) ans = ans.delete(id);
+
+    return ans;
+  }
+
   /**
    * Un-marks `id` as deleted from this list, making it present again.
    * A new IdList is returned and the current list remains unchanged.
@@ -590,9 +618,22 @@ export class IdList {
    *
    * If `id` is already present, this method does nothing.
    *
-   * @throws If `id` is not known.
+   * @param count Provide this to bulk-undelete `count` ids,
+   * starting with newId and proceeding with the same bunchId and sequential counters.
+   * @throws If any deleted id is not known.
    */
-  undelete(id: ElementId) {
+  undelete(id: ElementId, count = 1) {
+    checkCount(count);
+
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    let ans: IdList = this;
+    for (let i = count - 1; i >= 0; i--) {
+      ans = ans.undeleteOne({ bunchId: id.bunchId, counter: id.counter + i });
+    }
+    return ans;
+  }
+
+  private undeleteOne(id: ElementId) {
     const located = this.locate(id);
     if (located === null) {
       throw new Error("id is not known");
@@ -753,8 +794,6 @@ export class IdList {
   /**
    * Returns the maximum counter across all known ElementIds with the given bunchId,
    * or undefined if no such ElementIds are known.
-   *
-   * This method is useful when creating ElementIds.
    */
   maxCounter(bunchId: string): number | undefined {
     // Find the greatest-counter leaf containing bunchId.
@@ -872,6 +911,44 @@ export class IdList {
     }
   }
 
+  /**
+   * Returns the cursor at the given index within the list, i.e., between `index - 1` and `index`.
+   * See [Cursors](https://github.com/mweidner037/articulated#cursors).
+   *
+   * Invert with {@link cursorIndex}.
+   *
+   * @param bind Whether to bind to the left or the right side of the gap, in case ids
+   * later appear between `index - 1` and `index`. Default: `"left"`, which is typical for text cursors.
+   * @throws If index is not in the range `[0, list.length]`.
+   */
+  cursorAt(index: number, bind: "left" | "right" = "left"): ElementId | null {
+    if (bind === "left") {
+      return index === 0 ? null : this.at(index - 1);
+    } else {
+      return index === this.length ? null : this.at(index);
+    }
+  }
+
+  /**
+   * Returns the current index of the given cursor within the list.
+   * That is, the cursor is in the gap between `index - 1` and `index`.
+   *
+   * Inverts {@link cursorAt}.
+   *
+   * @param bind The `bind` value that was used with {@link cursorAt}, if any.
+   * @throws If `cursor` is an ElementId that is not known.
+   */
+  cursorIndex(
+    cursor: ElementId | null,
+    bind: "left" | "right" = "left"
+  ): number {
+    if (bind === "left") {
+      return cursor === null ? 0 : this.indexOf(cursor, "left") + 1;
+    } else {
+      return cursor === null ? this.length : this.indexOf(cursor, "right");
+    }
+  }
+
   // Iterators and views
 
   /**

package/src/index.ts

@@ -1,3 +1,4 @@
-export * from "./id";
+export * from "./element_id";
+export * from "./element_id_generator";
 export { IdList, KnownIdView } from "./id_list";
 export * from "./saved_id_list";

package/src/internal/misc.ts

@@ -0,0 +1,5 @@
+export function checkCount(count: number) {
+  if (!(Number.isSafeInteger(count) && count >= 0)) {
+    throw new Error(`Invalid count: ${count}`);
+  }
+}

package/build/commonjs/id.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":";;;AAsCA;;GAEG;AACH,SAAgB,QAAQ,CAAC,CAAY,EAAE,CAAY;IACjD,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC;AAC5D,CAAC;AAFD,4BAEC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,SAAS,CAAC,OAAkB,EAAE,KAAa;IACzD,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAVD,8BAUC"}

package/build/esm/id.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":"AAsCA;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,CAAY,EAAE,CAAY;IACjD,OAAO,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,CAAC;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,OAAkB,EAAE,KAAa;IACzD,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}