articulated 0.1.0

package/LICENSE

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright © 2025 Matthew Weidner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# articulated
+
+A TypeScript library for managing stable element identifiers in mutable lists, perfect for collaborative editing and other applications where elements need persistent identities despite insertions and deletions.
+
+## Features
+
+- **Stable identifiers**: Elements keep their identity even as their indices change
+- **Efficient storage**: Optimized compression for sequential IDs
+- **Collaborative-ready**: Supports concurrent operations from multiple sources
+- **Tombstone support**: Deleted elements remain addressable
+- **TypeScript-first**: Full type safety and excellent IDE integration
+
+## Installation
+
+```bash
+npm install --save articulated
+# or
+yarn add articulated
+```
+
+## Quick Start
+
+```typescript
+import { IdList } from "articulated";
+
+// Create an empty list
+const list = new IdList();
+
+// Insert a new element at the beginning
+list.insertAfter(null, { bunchId: "user1", counter: 0 });
+
+// Insert another element after the first
+list.insertAfter(
+  { bunchId: "user1", counter: 0 },
+  { bunchId: "user1", counter: 1 }
+);
+
+// Delete an element (marks as deleted but keeps as known)
+list.delete({ bunchId: "user1", counter: 0 });
+
+// Check if elements are present/known
+console.log(list.has({ bunchId: "user1", counter: 0 })); // false (deleted)
+console.log(list.isKnown({ bunchId: "user1", counter: 0 })); // true (known but deleted)
+```
+
+## Core Concepts
+
+### ElementId
+
+An `ElementId` is a globally unique identifier for a list element, composed of:
+
+- `bunchId`: A string UUID or similar globally unique ID
+- `counter`: A numeric value to distinguish elements in the same bunch
+
+For optimal compression, when inserting multiple elements in sequence, use the same `bunchId` with sequential `counter` values.
+
+```typescript
+// Example of IDs that will compress well
+const id1 = { bunchId: "abc123", counter: 0 };
+const id2 = { bunchId: "abc123", counter: 1 };
+const id3 = { bunchId: "abc123", counter: 2 };
+```
+
+### IdList Operations
+
+#### Basic Operations
+
+- `insertAfter(before, newId)`: Insert after a specific element
+- `insertBefore(after, newId)`: Insert before a specific element
+- `delete(id)`: Mark an element as deleted (remains known)
+- `undelete(id)`: Restore a deleted element
+
+#### Advanced Operations
+
+- `uninsert(id)`: Remove an element completely (no longer known)
+- `at(index)`: Get the element ID at a specific index
+- `indexOf(id, bias)`: Get the index of an element with optional bias for deleted elements
+- `clone()`: Create a deep copy of the list
+
+#### Bulk Operations
+
+```typescript
+// Insert multiple sequential ids at once
+list.insertAfter(null, { bunchId: "user1", counter: 0 }, 5);
+// Inserts 5 ids with bunchId="user1" and counters 0, 1, 2, 3, 4
+```
+
+### Persistence
+
+Save and restore the list state:
+
+```typescript
+// Save list state
+const savedState = list.save();
+
+// Later, restore from saved state
+const newList = new IdList();
+newList.load(savedState);
+```
+
+## Use Cases
+
+- Text editors where characters need stable identities
+- Todo lists with collaborative editing
+- Any list where elements' positions change but need stable identifiers
+- Conflict-free replicated data type (CRDT) implementations

package/build/commonjs/id.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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 declare function equalsId(a: ElementId, b: ElementId): boolean;
+/**
+ * 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 declare function expandIds(startId: ElementId, count: number): ElementId[];

package/build/commonjs/id.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.expandIds = exports.equalsId = void 0;
+/**
+ * Equals function for ElementIds.
+ */
+function equalsId(a, b) {
+    return a.counter === b.counter && a.bunchId === b.bunchId;
+}
+exports.equalsId = equalsId;
+/**
+ * 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 }
+ * ]
+ * ```
+ */
+function expandIds(startId, count) {
+    if (!(Number.isSafeInteger(count) && count >= 0)) {
+        throw new Error(`Invalid count: ${count}`);
+    }
+    const ans = [];
+    for (let i = 0; i < count; i++) {
+        ans.push({ bunchId: startId.bunchId, counter: startId.counter + i });
+    }
+    return ans;
+}
+exports.expandIds = expandIds;
+//# sourceMappingURL=id.js.map

package/build/commonjs/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/id.ts"],"names":[],"mappings":";;;AAwCA;;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/commonjs/id_list.d.ts

@@ -0,0 +1,226 @@
+import { ElementId } 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 declare class IdList {
+    private readonly state;
+    private _length;
+    /**
+     * Constructs an empty list.
+     *
+     * To begin with a non-empty list, use {@link IdList.from} or {@link IdList.fromIds}.
+     */
+    constructor();
+    /**
+     * Constructs a list with the given known ids and their isDeleted status, in list order.
+     */
+    static from(state: Iterable<{
+        id: ElementId;
+        isDeleted: boolean;
+    }>): IdList;
+    /**
+     * 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>): IdList;
+    /**
+     * 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?: number): void;
+    /**
+     * 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?: number): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * 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;
+    /**
+     * Returns whether id is known to this list.
+     *
+     * Compare to {@link has}.
+     */
+    isKnown(id: ElementId): boolean;
+    /**
+     * Returns the id at the given index in the list.
+     *
+     * @throws If index is out of bounds.
+     */
+    at(index: number): ElementId;
+    /**
+     * 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"): number;
+    /**
+     * The length of the list.
+     */
+    get length(): number;
+    /**
+     * Iterates over all present ids in the list.
+     */
+    [Symbol.iterator](): IterableIterator<ElementId>;
+    /**
+     * Iterates over all present ids in the list.
+     */
+    values(): IterableIterator<ElementId>;
+    /**
+     * Iterates over all __known__ ids in the list, indicating which are deleted.
+     */
+    valuesWithDeleted(): IterableIterator<{
+        id: ElementId;
+        isDeleted: boolean;
+    }>;
+    /**
+     * Returns an independent copy of this list, including known but deleted ids.
+     */
+    clone(): IdList;
+    private _knownIds?;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Loads a saved state returned by {@link save}, __overwriting__ the current state of this list.
+     */
+    load(savedState: SavedIdList): void;
+}
+/**
+ * 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 declare class KnownIdView {
+    readonly list: IdList;
+    private readonly state;
+    /**
+     * Internal use only. Use {@link IdList.knownIds} instead.
+     */
+    constructor(list: IdList, state: ListElement[]);
+    /**
+     * 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;
+    /**
+     * Returns the index of `id` in this view, or -1 if it is not known.
+     */
+    indexOf(id: ElementId): number;
+    /**
+     * The length of this view.
+     *
+     * Equivalently, the number of known ids in `this.list`.
+     */
+    get length(): number;
+    /**
+     * Iterates over all ids in this view, i.e., all known ids in `this.list`.
+     */
+    [Symbol.iterator](): IterableIterator<ElementId>;
+    /**
+     * Iterates over all ids in this view, i.e., all known ids in `this.list`.
+     */
+    values(): IterableIterator<ElementId>;
+}
+export {};