lseq/typescript/README.md

# @peoplesgrocers/lseq

TypeScript implementation of the L-SEQ algorithm for fractional indexing and
list CRDTs.


The library handles edge cases that break other more naive implementations of
fractional indexing.  With this library you can always insert before the first
item or after the last item, indefinitely.

This is exactly what you need to build realtime collaborative apps with
ordering for lists or trees of items. Users can reorder or insert at arbitrary
positions but in practice people really like moving items to the top or end of
a list. So don't crash accept random crashes from other libraries when Alice
moves yet another element to the front of the list.

## Installation

```bash
npm install @peoplesgrocers/lseq
```

## Usage

```typescript
import { LSEQ } from '@peoplesgrocers/lseq';

const lseq = new LSEQ();

const first = lseq.alloc(null, null);
const second = lseq.alloc(first, null);
const between = lseq.alloc(first, second);

// String comparison gives correct order
[second, first, between].sort();  // [first, between, second]
```

## API

### `new LSEQ(random?: () => number)`

Create an allocator. Accepts an optional random function for deterministic testing.

### `lseq.alloc(before: string | null, after: string | null): string`

Allocate a key between `before` and `after`.

- `lseq.alloc(null, null)` — first key in an empty list
- `lseq.alloc(null, first)` — insert at head
- `lseq.alloc(last, null)` — insert at tail
- `lseq.alloc(a, b)` — insert between a and b

### `compareLSEQ(a: string, b: string): number`

Compare two keys. Returns -1, 0, or 1.

### `EvenSpacingIterator`

Generate evenly-spaced keys for bulk initialization:

```typescript
import { EvenSpacingIterator } from '@peoplesgrocers/lseq';

const { k, iterator } = EvenSpacingIterator.create(1000);
const keys = [];
for (const position of iterator) {
  keys.push(EvenSpacingIterator.positionToKey(k, position));
}
```

## Design

Keys are base-64 encoded strings using the base64 url-safe alphabet
`-0-9A-Z_a-z`. There is a compact binary representation inside. Reasonablt
efficient and no serialization issues with JSON, databases, or URLs.

Standard string comparison produces correct ordering. Keys work in SQL `ORDER
BY`, database indexes, and any language with string sorting.

## Cross-language support

I wrote matching implementations for Rust, Golang, and Python; validated
against a shared conformance test suite with fuzzing. If your backend isn't
TypeScript, you can still allocate and work with these keys natively.  This
makes LSEQ a reasonable building block for your application's data model.

## References

- [LSEQ: an Adaptive Structure for Sequences in Distributed Collaborative Editing](https://hal.science/hal-00921633/document) (Nédelec et al., 2013)

## License

AGPL-3.0