@graphprotocol/grc-20 0.0.4

package/dist/src/core/position-strings/find-position.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Returns `{ index, isPresent }`, where:
+ * - `index` is the current index of `position` in `positions`,
+ * or where it would be if added.
+ * - `isPresent` is true if `position` is present in `positions`.
+ *
+ * If this method is inconvenient (e.g., the positions are in a database
+ * instead of an array), you can instead compute
+ * `index` by finding the number of positions less than `position`.
+ * For example, in SQL, use:
+ * ```sql
+ * SELECT COUNT(*) FROM table WHERE position < $position
+ * ```
+ *
+ * See also: `Cursors.toIndex`.
+ *
+ * @param positions The target list's positions, in lexicographic order.
+ * There should be no duplicate positions.
+ */
+export declare function findPosition(position: string, positions: ArrayLike<string>): {
+    index: number;
+    isPresent: boolean;
+};
+//# sourceMappingURL=find-position.d.ts.map

package/dist/src/core/position-strings/find-position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-position.d.ts","sourceRoot":"","sources":["../../../../src/core/position-strings/find-position.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAqBlH"}

package/dist/src/core/position-strings/find-position.js

@@ -0,0 +1,38 @@
+import { assert } from './util.js';
+/**
+ * Returns `{ index, isPresent }`, where:
+ * - `index` is the current index of `position` in `positions`,
+ * or where it would be if added.
+ * - `isPresent` is true if `position` is present in `positions`.
+ *
+ * If this method is inconvenient (e.g., the positions are in a database
+ * instead of an array), you can instead compute
+ * `index` by finding the number of positions less than `position`.
+ * For example, in SQL, use:
+ * ```sql
+ * SELECT COUNT(*) FROM table WHERE position < $position
+ * ```
+ *
+ * See also: `Cursors.toIndex`.
+ *
+ * @param positions The target list's positions, in lexicographic order.
+ * There should be no duplicate positions.
+ */
+export function findPosition(position, positions) {
+    // Binary search: index is the "rank" of position, computed using
+    // https://en.wikipedia.org/wiki/Binary_search_algorithm#Procedure_for_finding_the_leftmost_element
+    let L = 0;
+    let R = positions.length;
+    while (L < R) {
+        const m = Math.floor((L + R) / 2);
+        const left = positions[m];
+        if (left < position)
+            L = m + 1;
+        else
+            R = m;
+    }
+    const left = positions[L - 1];
+    assert((L === 0 || left < position) && (L === positions.length || left >= position), 'Bad binary search (positions out of order?):', position, L);
+    return { index: L, isPresent: left === position };
+}
+//# sourceMappingURL=find-position.js.map

package/dist/src/core/position-strings/find-position.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"find-position.js","sourceRoot":"","sources":["../../../../src/core/position-strings/find-position.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAgB,EAAE,SAA4B;IACzE,iEAAiE;IACjE,mGAAmG;IACnG,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM,CAAC;IACzB,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,CAAW,CAAC;QACpC,IAAI,IAAI,GAAG,QAAQ;YAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;;YAC1B,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IAED,MAAM,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAW,CAAC;IAExC,MAAM,CACJ,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,IAAI,IAAI,IAAI,QAAQ,CAAC,EAC5E,8CAA8C,EAC9C,QAAQ,EACR,CAAC,CACF,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;AACpD,CAAC"}

package/dist/src/core/position-strings/ids.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Utitilies for generating `PositionSource` IDs
+ * (the `options.ID` constructor argument).
+ */
+export declare class IDs {
+    private constructor();
+    /**
+     * Default characters used in IDs: alphanumeric chars.
+     */
+    static readonly DEFAULT_CHARS: string;
+    /**
+     * The default length of an ID, in characters.
+     */
+    static readonly DEFAULT_LENGTH: number;
+    /**
+     * Returns a cryptographically random ID made of alphanumeric characters.
+     *
+     * @param options.length The length of the ID, in characters.
+     * Default: `IDs.DEFAULT_LENGTH`.
+     * @param options.chars The characters to draw from. Default: `IDs.DEFAULT_CHARS`.
+     *
+     * If specified, only the first 256 elements are used, and you achieve
+     * about `log_2(chars.length)` bits of entropy per `length`.
+     */
+    static random(options?: {
+        length?: number;
+        chars?: string;
+    }): string;
+    /**
+     * Throws an error if `ID` does not satisfy the
+     * following requirements from `PositionSource`'s constructor:
+     * - It does not contain `','` or `'.'`.
+     * - The first character is lexicographically less than `'~'` (code point 126).
+     */
+    static validate(ID: string): void;
+}
+//# sourceMappingURL=ids.d.ts.map

package/dist/src/core/position-strings/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../../../src/core/position-strings/ids.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,qBAAa,GAAG;IACd,OAAO;IAIP;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAoE;IAUzG;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAK;IAE3C;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM;IA+BpE;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAKlC"}

package/dist/src/core/position-strings/ids.js

@@ -0,0 +1,79 @@
+import * as crypto from 'crypto';
+import { LastInternal, precond } from './util.js';
+/**
+ * Utitilies for generating `PositionSource` IDs
+ * (the `options.ID` constructor argument).
+ */
+export class IDs {
+    constructor() {
+        // Not instantiable.
+    }
+    /**
+     * Default characters used in IDs: alphanumeric chars.
+     */
+    static DEFAULT_CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    // Rationale for value 8:
+    // Each character of the ID gives us ~6 bits of entropy,
+    //  for a total of ~48 bits.  This gives a < 1%
+    // probability that two connected `PositionSource`s
+    // will ever choose the same IDs, even if we
+    // consider the total probability across 100,000,000
+    // documents with 1,000 IDs each
+    // (= 10 users x 100 days x 1 ID/user/day).
+    /**
+     * The default length of an ID, in characters.
+     */
+    static DEFAULT_LENGTH = 8;
+    /**
+     * Returns a cryptographically random ID made of alphanumeric characters.
+     *
+     * @param options.length The length of the ID, in characters.
+     * Default: `IDs.DEFAULT_LENGTH`.
+     * @param options.chars The characters to draw from. Default: `IDs.DEFAULT_CHARS`.
+     *
+     * If specified, only the first 256 elements are used, and you achieve
+     * about `log_2(chars.length)` bits of entropy per `length`.
+     */
+    static random(options) {
+        const length = options?.length ?? this.DEFAULT_LENGTH;
+        const chars = options?.chars ?? this.DEFAULT_CHARS;
+        const arr = new Array(length);
+        let randomValues = new Uint8Array(length);
+        if (typeof window === 'undefined') {
+            // Use Node crypto library.
+            // We use eval("require") to prevent Webpack from attempting
+            // to bundle the crypto module and complaining.
+            // In theory we should also be able to do this by
+            // adding "browser": {"crypto": false} to package.json,
+            // but that is not working, and besides, every user
+            // of this package would have to remember to do so.
+            // See https://github.com/webpack/webpack/issues/8826
+            const cryptoReal = crypto;
+            const randomBuffer = cryptoReal.randomBytes(length);
+            randomValues = new Uint8Array(randomBuffer);
+        }
+        else {
+            // Use browser crypto library.
+            window.crypto.getRandomValues(randomValues);
+        }
+        for (let i = 0; i < length; i++) {
+            // This will be biased if chars.length does not divide 256,
+            // but it will still give at least floor(log_2(chars.length))
+            // bits of entropy.
+            arr[i] = chars[randomValues[i] % chars.length];
+        }
+        return arr.join('');
+    }
+    /**
+     * Throws an error if `ID` does not satisfy the
+     * following requirements from `PositionSource`'s constructor:
+     * - It does not contain `','` or `'.'`.
+     * - The first character is lexicographically less than `'~'` (code point 126).
+     */
+    static validate(ID) {
+        precond(ID < LastInternal, 'ID must be less than', LastInternal, ':', ID);
+        precond(!ID.includes(','), "ID must not contain ',':", ID);
+        precond(!ID.includes('.'), "ID must not contain '.':", ID);
+    }
+}
+//# sourceMappingURL=ids.js.map

package/dist/src/core/position-strings/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../../../src/core/position-strings/ids.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AAEjC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAElD;;;GAGG;AACH,MAAM,OAAO,GAAG;IACd;QACE,oBAAoB;IACtB,CAAC;IAED;;OAEG;IACH,MAAM,CAAU,aAAa,GAAW,gEAAgE,CAAC;IAEzG,yBAAyB;IACzB,wDAAwD;IACxD,+CAA+C;IAC/C,mDAAmD;IACnD,4CAA4C;IAC5C,oDAAoD;IACpD,gCAAgC;IAChC,2CAA2C;IAC3C;;OAEG;IACH,MAAM,CAAU,cAAc,GAAW,CAAC,CAAC;IAE3C;;;;;;;;;OASG;IACH,MAAM,CAAC,MAAM,CAAC,OAA6C;QACzD,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;QACtD,MAAM,KAAK,GAAG,OAAO,EAAE,KAAK,IAAI,IAAI,CAAC,aAAa,CAAC;QAEnD,MAAM,GAAG,GAAG,IAAI,KAAK,CAAS,MAAM,CAAC,CAAC;QACtC,IAAI,YAAY,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;YAClC,2BAA2B;YAC3B,4DAA4D;YAC5D,+CAA+C;YAC/C,iDAAiD;YACjD,uDAAuD;YACvD,mDAAmD;YACnD,mDAAmD;YACnD,qDAAqD;YACrD,MAAM,UAAU,GAAG,MAAM,CAAC;YAC1B,MAAM,YAAY,GAAG,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;YACpD,YAAY,GAAG,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC;QAC9C,CAAC;aAAM,CAAC;YACN,8BAA8B;YAC9B,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;QAC9C,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAChC,2DAA2D;YAC3D,6DAA6D;YAC7D,mBAAmB;YACnB,GAAG,CAAC,CAAC,CAAC,GAAG,KAAK,CAAE,YAAY,CAAC,CAAC,CAAY,GAAG,KAAK,CAAC,MAAM,CAAW,CAAC;QACvE,CAAC;QACD,OAAO,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAU;QACxB,OAAO,CAAC,EAAE,GAAG,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,0BAA0B,EAAE,EAAE,CAAC,CAAC;QAC3D,OAAO,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,0BAA0B,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC"}

package/dist/src/core/position-strings/index.d.ts

@@ -0,0 +1,5 @@
+export * from './cursors.js';
+export * from './ids.js';
+export * from './position-source.js';
+export * from './find-position.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/core/position-strings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/core/position-strings/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/dist/src/core/position-strings/index.js

@@ -0,0 +1,6 @@
+export * from './cursors.js';
+export * from './ids.js';
+export * from './position-source.js';
+export * from './find-position.js';
+// utils.ts is internal only.
+//# sourceMappingURL=index.js.map

package/dist/src/core/position-strings/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/core/position-strings/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,6BAA6B"}

package/dist/src/core/position-strings/position-source.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A source of lexicographically-ordered "position strings" for
+ * collaborative lists and text.
+ *
+ * In a collaborative list (or text string), you need a way to refer
+ * to "positions" within that list that:
+ * 1. Point to a specific list element (or text character).
+ * 2. Are global (all users agree on them) and immutable (they do not
+ * change over time).
+ * 3. Can be sorted.
+ * 4. Are unique, even if different users concurrently create positions
+ * at the same place.
+ *
+ * `PositionSource` gives you such positions, in the form
+ * of lexicographically-ordered strings. Specifically, `createBetween`
+ * returns a new "position string" in between two existing position strings.
+ *
+ * These strings have the bonus properties:
+ * - 5. (Non-Interleaving) If two `PositionSource`s concurrently create a (forward or backward)
+ * sequence of positions at the same place,
+ * their sequences will not be interleaved.
+ * For example, if
+ * Alice types "Hello" while Bob types "World" at the same place,
+ * and they each use a `PositionSource` to create a position for each
+ * character, then
+ * the resulting order will be "HelloWorld" or "WorldHello", not
+ * "HWeolrllod".
+ * - 6. If a `PositionSource` creates positions in a forward (increasing)
+ * sequence, their lengths as strings will only grow logarithmically,
+ * not linearly.
+ *
+ * Position strings are printable ASCII. Specifically, they
+ * contain alphanumeric characters, `','`, and `'.'`.
+ * Also, the special string `PositionSource.LAST` is `'~'`.
+ *
+ * Further reading:
+ * - [Fractional indexing](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing),
+ * a related scheme that satisfies 1-3 but not 4-6.
+ * - [List CRDTs](https://mattweidner.com/2022/10/21/basic-list-crdt.html)
+ * and how they map to position strings. `PositionSource` uses an optimized
+ * variant of that link's string implementation.
+ * - [Paper about interleaving](https://www.repository.cam.ac.uk/handle/1810/290391)
+ * in collaborative text editors.
+ */
+export declare class PositionSource {
+    /**
+     * A string that is less than all positions.
+     *
+     * Value: `""`.
+     */
+    static readonly FIRST: string;
+    /**
+     * A string that is greater than all positions.
+     *
+     * Value: `"~"`.
+     */
+    static readonly LAST: string;
+    /**
+     * The unique ID for this `PositionSource`.
+     */
+    readonly ID: string;
+    /**
+     * Our waypoints' long name: `,${ID}.`.
+     */
+    private readonly longName;
+    /**
+     * Variant of longName used for a position's first ID: `${ID}.`.
+     * (Otherwise every position would start with a redundant ','.)
+     */
+    private readonly firstName;
+    /**
+     * For each waypoint that we created, maps a prefix (see getPrefix)
+     * for that waypoint to its last (most recent) valueSeq.
+     * We always store the right-side version (odd valueSeq).
+     */
+    private lastValueSeqs;
+    /**
+     * Constructs a new `PositionSource`.
+     *
+     * It is okay to share a single `PositionSource` between
+     * all documents (lists/text strings) in the same JavaScript runtime.
+     *
+     * For efficiency (shorter position strings),
+     * within each JavaScript runtime, you should not use
+     * more than one `PositionSource` for the same document.
+     * An exception is if multiple logical users share the same runtime;
+     * we then recommend one `PositionSource` per user.
+     *
+     * @param options.ID A unique ID for this `PositionSource`. Defaults to
+     * `IDs.random()`.
+     *
+     * If provided, `options.ID` must satisfy:
+     * - It is unique across the entire collaborative application, i.e.,
+     * all `PositionSource`s whose positions may be compared to ours. This
+     * includes past `PositionSource`s, even if they correspond to the same
+     * user/device.
+     * - It does not contain `','` or `'.'`.
+     * - The first character is lexicographically less than `'~'` (code point 126).
+     *
+     * If `options.ID` contains non-alphanumeric characters, then created
+     * positions will contain those characters in addition to
+     * alphanumeric characters, `','`, and `'.'`.
+     */
+    constructor(options?: {
+        ID?: string;
+    });
+    /**
+     * Returns a new position between `left` and `right`
+     * (`left < new < right`).
+     *
+     * The new position is unique across the entire collaborative application,
+     * even in the face of concurrent calls to this method on other
+     * `PositionSource`s.
+     *
+     * @param left Defaults to `PositionSource.FIRST` (insert at the beginning).
+     *
+     * @param right Defaults to `PositionSource.LAST` (insert at the end).
+     */
+    createBetween(left?: string, right?: string): string;
+    /**
+     * Appends a wayoint to the given ancestor (= prefix adjusted for
+     * side), returning a unique new position using that waypoint.
+     *
+     * lastValueSeqs is also updated as needed for the waypoint.
+     */
+    private appendWaypoint;
+}
+//# sourceMappingURL=position-source.d.ts.map

package/dist/src/core/position-strings/position-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-source.d.ts","sourceRoot":"","sources":["../../../../src/core/position-strings/position-source.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBAAa,cAAc;IACzB;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAM;IACnC;;;;OAIG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAgB;IAE5C;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;;;OAIG;IACH,OAAO,CAAC,aAAa,CAA6B;IAElD;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;gBACS,OAAO,CAAC,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE;IASrC;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,IAAI,GAAE,MAA6B,EAAE,KAAK,GAAE,MAA4B,GAAG,MAAM;IA+C/F;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CA2BvB"}

package/dist/src/core/position-strings/position-source.js

@@ -0,0 +1,314 @@
+import { IDs } from './ids.js';
+import { LastInternal, assert, precond } from './util.js';
+/**
+ * A source of lexicographically-ordered "position strings" for
+ * collaborative lists and text.
+ *
+ * In a collaborative list (or text string), you need a way to refer
+ * to "positions" within that list that:
+ * 1. Point to a specific list element (or text character).
+ * 2. Are global (all users agree on them) and immutable (they do not
+ * change over time).
+ * 3. Can be sorted.
+ * 4. Are unique, even if different users concurrently create positions
+ * at the same place.
+ *
+ * `PositionSource` gives you such positions, in the form
+ * of lexicographically-ordered strings. Specifically, `createBetween`
+ * returns a new "position string" in between two existing position strings.
+ *
+ * These strings have the bonus properties:
+ * - 5. (Non-Interleaving) If two `PositionSource`s concurrently create a (forward or backward)
+ * sequence of positions at the same place,
+ * their sequences will not be interleaved.
+ * For example, if
+ * Alice types "Hello" while Bob types "World" at the same place,
+ * and they each use a `PositionSource` to create a position for each
+ * character, then
+ * the resulting order will be "HelloWorld" or "WorldHello", not
+ * "HWeolrllod".
+ * - 6. If a `PositionSource` creates positions in a forward (increasing)
+ * sequence, their lengths as strings will only grow logarithmically,
+ * not linearly.
+ *
+ * Position strings are printable ASCII. Specifically, they
+ * contain alphanumeric characters, `','`, and `'.'`.
+ * Also, the special string `PositionSource.LAST` is `'~'`.
+ *
+ * Further reading:
+ * - [Fractional indexing](https://www.figma.com/blog/realtime-editing-of-ordered-sequences/#fractional-indexing),
+ * a related scheme that satisfies 1-3 but not 4-6.
+ * - [List CRDTs](https://mattweidner.com/2022/10/21/basic-list-crdt.html)
+ * and how they map to position strings. `PositionSource` uses an optimized
+ * variant of that link's string implementation.
+ * - [Paper about interleaving](https://www.repository.cam.ac.uk/handle/1810/290391)
+ * in collaborative text editors.
+ */
+export class PositionSource {
+    /**
+     * A string that is less than all positions.
+     *
+     * Value: `""`.
+     */
+    static FIRST = '';
+    /**
+     * A string that is greater than all positions.
+     *
+     * Value: `"~"`.
+     */
+    static LAST = LastInternal;
+    /**
+     * The unique ID for this `PositionSource`.
+     */
+    ID;
+    /**
+     * Our waypoints' long name: `,${ID}.`.
+     */
+    longName;
+    /**
+     * Variant of longName used for a position's first ID: `${ID}.`.
+     * (Otherwise every position would start with a redundant ','.)
+     */
+    firstName;
+    /**
+     * For each waypoint that we created, maps a prefix (see getPrefix)
+     * for that waypoint to its last (most recent) valueSeq.
+     * We always store the right-side version (odd valueSeq).
+     */
+    lastValueSeqs = new Map();
+    /**
+     * Constructs a new `PositionSource`.
+     *
+     * It is okay to share a single `PositionSource` between
+     * all documents (lists/text strings) in the same JavaScript runtime.
+     *
+     * For efficiency (shorter position strings),
+     * within each JavaScript runtime, you should not use
+     * more than one `PositionSource` for the same document.
+     * An exception is if multiple logical users share the same runtime;
+     * we then recommend one `PositionSource` per user.
+     *
+     * @param options.ID A unique ID for this `PositionSource`. Defaults to
+     * `IDs.random()`.
+     *
+     * If provided, `options.ID` must satisfy:
+     * - It is unique across the entire collaborative application, i.e.,
+     * all `PositionSource`s whose positions may be compared to ours. This
+     * includes past `PositionSource`s, even if they correspond to the same
+     * user/device.
+     * - It does not contain `','` or `'.'`.
+     * - The first character is lexicographically less than `'~'` (code point 126).
+     *
+     * If `options.ID` contains non-alphanumeric characters, then created
+     * positions will contain those characters in addition to
+     * alphanumeric characters, `','`, and `'.'`.
+     */
+    constructor(options) {
+        if (options?.ID !== undefined) {
+            IDs.validate(options.ID);
+        }
+        this.ID = options?.ID ?? IDs.random();
+        this.longName = `,${this.ID}.`;
+        this.firstName = `${this.ID}.`;
+    }
+    /**
+     * Returns a new position between `left` and `right`
+     * (`left < new < right`).
+     *
+     * The new position is unique across the entire collaborative application,
+     * even in the face of concurrent calls to this method on other
+     * `PositionSource`s.
+     *
+     * @param left Defaults to `PositionSource.FIRST` (insert at the beginning).
+     *
+     * @param right Defaults to `PositionSource.LAST` (insert at the end).
+     */
+    createBetween(left = PositionSource.FIRST, right = PositionSource.LAST) {
+        precond(left < right, 'left must be less than right:', left, '!<', right);
+        precond(right <= PositionSource.LAST, 'right must be less than or equal to LAST:', right, '!<=', PositionSource.LAST);
+        const leftFixed = left === PositionSource.FIRST ? null : left;
+        const rightFixed = right === PositionSource.LAST ? null : right;
+        let ans;
+        if (rightFixed !== null && (leftFixed === null || rightFixed.startsWith(leftFixed))) {
+            // Left child of right. This always appends a waypoint.
+            const ancestor = leftVersion(rightFixed);
+            ans = this.appendWaypoint(ancestor);
+        }
+        else {
+            // Right child of left.
+            if (leftFixed === null) {
+                // ancestor is FIRST.
+                ans = this.appendWaypoint('');
+            }
+            else {
+                // Check if we can reuse left's prefix.
+                // It needs to be one of ours, and right can't use the same
+                // prefix (otherwise we would get ans > right by comparing right's
+                // older valueIndex to our new valueIndex).
+                const prefix = getPrefix(leftFixed);
+                const lastValueSeq = this.lastValueSeqs.get(prefix);
+                if (lastValueSeq !== undefined && !(rightFixed !== null && rightFixed.startsWith(prefix))) {
+                    // Reuse.
+                    const valueSeq = nextOddValueSeq(lastValueSeq);
+                    ans = prefix + stringifyBase52(valueSeq);
+                    this.lastValueSeqs.set(prefix, valueSeq);
+                }
+                else {
+                    // Append waypoint.
+                    ans = this.appendWaypoint(leftFixed);
+                }
+            }
+        }
+        assert(left < ans && ans < right, 'Bad position:', left, ans, right);
+        return ans;
+    }
+    /**
+     * Appends a wayoint to the given ancestor (= prefix adjusted for
+     * side), returning a unique new position using that waypoint.
+     *
+     * lastValueSeqs is also updated as needed for the waypoint.
+     */
+    appendWaypoint(ancestor) {
+        let waypointName = ancestor === '' ? this.firstName : this.longName;
+        // If our ID already appears in ancestor, instead use a short
+        // name for the waypoint.
+        // Here we use the uniqueness of ',' and '.' to
+        // claim that if this.longName (= `,${ID}.`) appears in ancestor, then it
+        // must actually be from a waypoint that we created.
+        let existing = ancestor.lastIndexOf(this.longName);
+        if (ancestor.startsWith(this.firstName))
+            existing = 0;
+        if (existing !== -1) {
+            // Find the index of existing among the long-name
+            // waypoints, in backwards order. Here we use the fact that
+            // each longName ends with '.' and that '.' does not appear otherwise.
+            let index = -1;
+            for (let i = existing; i < ancestor.length; i++) {
+                if (ancestor[i] === '.')
+                    index++;
+            }
+            waypointName = stringifyShortName(index);
+        }
+        const prefix = ancestor + waypointName;
+        const lastValueSeq = this.lastValueSeqs.get(prefix);
+        // Use next odd (right-side) valueSeq (1 if it's a new waypoint).
+        const valueSeq = lastValueSeq === undefined ? 1 : nextOddValueSeq(lastValueSeq);
+        this.lastValueSeqs.set(prefix, valueSeq);
+        return prefix + stringifyBase52(valueSeq);
+    }
+}
+/**
+ * Returns position's *prefix*: the string through the last waypoint
+ * name, or equivalently, without the final valueSeq.
+ */
+function getPrefix(position) {
+    // Last waypoint char is the last '.' (for long names) or
+    // digit (for short names). Note that neither appear in valueSeq,
+    // which is all letters.
+    for (let i = position.length - 2; i >= 0; i--) {
+        const char = position[i];
+        if (char === '.' || ('0' <= char && char <= '9')) {
+            // i is the last waypoint char, i.e., the end of the prefix.
+            return position.slice(0, i + 1);
+        }
+    }
+    assert(false, 'No last waypoint char found (not a position?)', position);
+    return '';
+}
+/**
+ * Returns the variant of position ending with a "left" marker
+ * instead of the default "right" marker.
+ *
+ * I.e., the ancestor for position's left descendants.
+ */
+function leftVersion(position) {
+    // We need to subtract one from the (odd) valueSeq, equivalently, from
+    // its last base52 digit.
+    const last = parseBase52(position[position.length - 1]);
+    assert(last % 2 === 1, 'Bad valueSeq (not a position?)', last, position);
+    return position.slice(0, -1) + stringifyBase52(last - 1);
+}
+/**
+ * Base 52, except for last digit, which is base 10 using
+ * digits. That makes it easy to find the end of a short name
+ * in getPrefix: it ends at the last digit.
+ */
+function stringifyShortName(n) {
+    if (n < 10)
+        return String.fromCharCode(48 + n);
+    else
+        return stringifyBase52(Math.floor(n / 10)) + String.fromCharCode(48 + (n % 10));
+}
+/**
+ * Base 52 encoding using letters (with "digits" in order by code point).
+ */
+function stringifyBase52(n) {
+    if (n === 0)
+        return 'A';
+    const codes = [];
+    while (n > 0) {
+        const digit = n % 52;
+        codes.unshift((digit >= 26 ? 71 : 65) + digit);
+        n = Math.floor(n / 52);
+    }
+    return String.fromCharCode(...codes);
+}
+function parseBase52(s) {
+    let n = 0;
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        const digit = code - (code >= 97 ? 71 : 65);
+        n = 52 * n + digit;
+    }
+    return n;
+}
+const log52 = Math.log(52);
+/**
+ * Returns the next odd valueSeq in the special sequence.
+ * This is equivalent to mapping n to its valueIndex, adding 2,
+ * then mapping back.
+ *
+ * The sequence has the following properties:
+ * 1. Each number is a nonnegative integer (however, not all
+ * nonnegative integers are enumerated).
+ * 2. The numbers' base-52 representations are enumerated in
+ * lexicographic order, with no prefixes (i.e., no string
+ * representation is a prefix of another).
+ * 3. The n-th enumerated number has O(log(n)) base-52 digits.
+ *
+ * Properties (2) and (3) are analogous to normal counting, except
+ * that we order by the (base-52) lexicographic order instead of the
+ * usual order by magnitude. It is also the case that
+ * the numbers are in order by magnitude, although we do not
+ * use this property.
+ *
+ * The specific sequence is as follows:
+ * - Start with 0.
+ * - Enumerate 26^1 numbers (A, B, ..., Z).
+ * - Add 1, multiply by 52, then enumerate 26^2 numbers
+ * (aA, aB, ..., mz).
+ * - Add 1, multiply by 52, then enumerate 26^3 numbers
+ * (nAA, nAB, ..., tZz).
+ * - Repeat this pattern indefinitely, enumerating
+ * 26^d d-digit numbers for each d >= 1. Imagining a decimal place
+ * in front of each number, each d consumes 2^(-d) of the unit interval,
+ * so we never "reach 1" (overflow to d+1 digits when
+ * we meant to use d digits).
+ *
+ * I believe this is related to
+ * [Elias gamma coding](https://en.wikipedia.org/wiki/Elias_gamma_coding).
+ */
+function nextOddValueSeq(n) {
+    const d = n === 0 ? 1 : Math.floor(Math.log(n) / log52) + 1;
+    // You can calculate that the last d-digit number is 52^d - 26^d - 1.
+    if (n === Math.pow(52, d) - Math.pow(26, d) - 1) {
+        // First step is a new length: n -> (n + 1) * 52.
+        // Second step is n -> n + 1.
+        return (n + 1) * 52 + 1;
+    }
+    else {
+        // n -> n + 1 twice.
+        return n + 2;
+    }
+}
+//# sourceMappingURL=position-source.js.map