@mark1russell7/collections 0.0.0-stage → 0.1.0

package/src/order/rank.ts

@@ -0,0 +1,271 @@
+/**
+ * The keys of an ordered list: fractional indexing with base-62 keys. A
+ * key is a string. Each item of the list keeps one, and the list sorts by it. An item that moves
+ * between two others gets a key between theirs, so a move writes one item and no other.
+ *
+ * - A key has an integer part and a fraction part. The first character of the integer part gives its
+ *   length. An insertion at an end changes the integer part, so the keys stay short.
+ * - An insertion between two keys uses the fraction part, which can grow without a limit. Thus the keys
+ *   do not run out, and the list needs no rebalance.
+ * - Compare two keys by the code units of the strings (`a < b`), not with `localeCompare`.
+ * - Two writers that move items into the same gap at the same time can get the same key. Sort by the
+ *   key, then by the id of the item, so each reader sees one order.
+ *
+ * The algorithm is the one of the `fractional-indexing` package of Rocicorp (CC0), after the article
+ * "Implementing Fractional Indexing" of David Greenspan.
+ */
+
+/** The digits of a key, in ascending order of their code units. */
+export const KEY_DIGITS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+
+const ZERO = KEY_DIGITS[0]!;
+const LAST = KEY_DIGITS[KEY_DIGITS.length - 1]!;
+/** The smallest integer part. No key comes before it. */
+const SMALLEST_INTEGER = `A${ZERO.repeat(26)}`;
+
+function invalid(message: string): RangeError {
+  return new RangeError(message);
+}
+
+/** This function gives the length of an integer part from its head character: a to z and Z to A give 2 to 27. */
+function integerLength(head: string): number {
+  if (head >= "a" && head <= "z") return head.charCodeAt(0) - "a".charCodeAt(0) + 2;
+  if (head >= "A" && head <= "Z") return "Z".charCodeAt(0) - head.charCodeAt(0) + 2;
+  throw invalid(`A key cannot start with "${head}"`);
+}
+
+function integerPart(key: string): string {
+  const length = integerLength(key[0] ?? "");
+  if (length > key.length) throw invalid(`The key "${key}" is too short for its integer part`);
+  return key.slice(0, length);
+}
+
+function validateKey(key: string): void {
+  if (typeof key !== "string" || key === "") throw invalid("A key is a string that is not empty");
+  for (const c of key) if (!KEY_DIGITS.includes(c)) throw invalid(`The key "${key}" has a character that is no digit of a key`);
+  if (key === SMALLEST_INTEGER) throw invalid(`The key "${key}" is reserved`);
+  const fraction = key.slice(integerPart(key).length);
+  if (fraction.endsWith(ZERO)) throw invalid(`The fraction part of the key "${key}" ends with ${ZERO}`);
+}
+
+/** A fraction strictly between two fractions. `b` null is the end. Neither one ends with the zero digit. */
+function midpoint(a: string, b: string | null): string {
+  if (b !== null) {
+    let n = 0;
+    while ((a[n] ?? ZERO) === b[n]) n++;
+    if (n > 0) return b.slice(0, n) + midpoint(a.slice(n), b.slice(n));
+  }
+  const digitA = a ? KEY_DIGITS.indexOf(a[0]!) : 0;
+  const digitB = b !== null ? KEY_DIGITS.indexOf(b[0]!) : KEY_DIGITS.length;
+  if (digitB - digitA > 1) return KEY_DIGITS[Math.round((digitA + digitB) / 2)]!;
+  // The first digits are next to each other
+  if (b !== null && b.length > 1) return b.slice(0, 1);
+  return KEY_DIGITS[digitA]! + midpoint(a.slice(1), null);
+}
+
+function incrementInteger(x: string): string | null {
+  const [head, ...digits] = x.split("") as [string, ...string[]];
+  let carry = true;
+  for (let i = digits.length - 1; carry && i >= 0; i--) {
+    const d = KEY_DIGITS.indexOf(digits[i]!) + 1;
+    if (d === KEY_DIGITS.length) digits[i] = ZERO;
+    else {
+      digits[i] = KEY_DIGITS[d]!;
+      carry = false;
+    }
+  }
+  if (!carry) return head + digits.join("");
+  if (head === "Z") return `a${ZERO}`;
+  if (head === "z") return null;
+  const next = String.fromCharCode(head.charCodeAt(0) + 1);
+  if (next > "a") digits.push(ZERO);
+  else digits.pop();
+  return next + digits.join("");
+}
+
+function decrementInteger(x: string): string | null {
+  const [head, ...digits] = x.split("") as [string, ...string[]];
+  let borrow = true;
+  for (let i = digits.length - 1; borrow && i >= 0; i--) {
+    const d = KEY_DIGITS.indexOf(digits[i]!) - 1;
+    if (d === -1) digits[i] = LAST;
+    else {
+      digits[i] = KEY_DIGITS[d]!;
+      borrow = false;
+    }
+  }
+  if (!borrow) return head + digits.join("");
+  if (head === "a") return `Z${LAST}`;
+  if (head === "A") return null;
+  const next = String.fromCharCode(head.charCodeAt(0) - 1);
+  if (next < "Z") digits.push(LAST);
+  else digits.pop();
+  return next + digits.join("");
+}
+
+/**
+ * This function gives a key strictly between two keys. Without `prev`, the key comes before `next`.
+ * Without `next`, it comes after `prev`. Without both, it gives the first key of a list ("a0").
+ *
+ * @throws RangeError when a key is not valid, or when `prev` is not before `next`
+ *
+ * @example
+ * ```ts
+ * keyBetween(undefined, undefined); // "a0"
+ * keyBetween("a0", undefined); // "a1", after a0
+ * keyBetween("a0", "a1"); // "a0V"
+ * ```
+ */
+export function keyBetween(prev: string | null | undefined, next: string | null | undefined): string {
+  const a = prev ?? null;
+  const b = next ?? null;
+  if (a !== null) validateKey(a);
+  if (b !== null) validateKey(b);
+  if (a !== null && b !== null && a >= b) throw invalid(`The key "${a}" is not before the key "${b}"`);
+  if (a === null) {
+    if (b === null) return `a${ZERO}`;
+    const ib = integerPart(b);
+    const fb = b.slice(ib.length);
+    if (ib === SMALLEST_INTEGER) return ib + midpoint("", fb);
+    if (ib < b) return ib;
+    const decremented = decrementInteger(ib);
+    if (decremented === null) throw invalid("No key comes before this one");
+    return decremented;
+  }
+  const ia = integerPart(a);
+  const fa = a.slice(ia.length);
+  if (b === null) {
+    const incremented = incrementInteger(ia);
+    return incremented === null ? ia + midpoint(fa, null) : incremented;
+  }
+  const ib = integerPart(b);
+  const fb = b.slice(ib.length);
+  if (ia === ib) return ia + midpoint(fa, fb);
+  const incremented = incrementInteger(ia);
+  if (incremented === null) throw invalid("No key comes after this one");
+  if (incremented < b) return incremented;
+  return ia + midpoint(fa, null);
+}
+
+/**
+ * This function gives `count` keys in ascending order, strictly between two keys.
+ * Use it to put several items at one place, or to give keys to a new list.
+ *
+ * @throws RangeError as `keyBetween`, or when `count` is not an integer of 0 or more
+ */
+export function keysBetween(prev: string | null | undefined, next: string | null | undefined, count: number): string[] {
+  if (!Number.isInteger(count) || count < 0) throw invalid(`A count of keys is an integer of 0 or more, not ${count}`);
+  const a = prev ?? null;
+  const b = next ?? null;
+  if (count === 0) return [];
+  if (count === 1) return [keyBetween(a, b)];
+  if (b === null) {
+    const keys = [keyBetween(a, null)];
+    for (let i = 1; i < count; i++) keys.push(keyBetween(keys[i - 1]!, null));
+    return keys;
+  }
+  if (a === null) {
+    const keys = [keyBetween(null, b)];
+    for (let i = 1; i < count; i++) keys.push(keyBetween(null, keys[i - 1]!));
+    return keys.reverse();
+  }
+  const half = Math.floor(count / 2);
+  const middle = keyBetween(a, b);
+  return [...keysBetween(a, middle, half), middle, ...keysBetween(middle, b, count - half - 1)];
+}
+
+/** The options of `isValidKey`. */
+export interface KeyCheckOptions {
+  /** The longest key that the check accepts. The default is 1024 characters. */
+  readonly maxLength?: number;
+}
+
+/**
+ * This function tells if a value is a valid key, for example a key that a client writes. A key that
+ * is longer than `maxLength` is not valid.
+ */
+export function isValidKey(key: unknown, options: KeyCheckOptions = {}): key is string {
+  if (typeof key !== "string" || key.length > (options.maxLength ?? 1024)) return false;
+  try {
+    validateKey(key);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** An item of an ordered list: its id and its key. */
+export interface KeyedItem {
+  readonly id: string;
+  readonly key: string;
+}
+
+/**
+ * This function gives the writes of a move: the new key of the item that moves, and new keys for the
+ * neighbors that need them. Give the other items of the list in order (by key, then by id), without
+ * the item that moves. Also give the index of the drop, from 0 to their number (`dropIndex`).
+ *
+ * Two writers can give two items one key. A drop between two such items has no key between them.
+ * So the helper first gives new keys to the items after the drop that have the key of the item before
+ * it. Each write is `{ id, key }`. The writes of the neighbors come first, and the write of the item
+ * that moves comes last.
+ *
+ * @throws RangeError when the index is outside the list, when the list holds the item that moves, or
+ * when a key is not valid
+ *
+ * @example
+ * ```ts
+ * const index = dropIndex(pointer, others.map(centerOf));
+ * for (const { id, key } of keysForDrop(others, index, dragged.id)) await save(id, { rank: key });
+ * ```
+ */
+export function keysForDrop(items: readonly KeyedItem[], index: number, movingId: string): Array<{ id: string; key: string }> {
+  if (!Number.isInteger(index) || index < 0 || index > items.length) throw invalid(`The index ${index} is outside the list of ${items.length} items`);
+  if (items.some((item) => item.id === movingId)) throw invalid(`The list holds the item that moves (${movingId})`);
+  const prev = items[index - 1]?.key ?? null;
+  // The items from the index on that do not come after the item before the drop need new keys
+  let end = index;
+  while (end < items.length && prev !== null && items[end]!.key <= prev) end++;
+  const writes: Array<{ id: string; key: string }> = [];
+  if (end > index) {
+    const keys = keysBetween(prev, items[end]?.key ?? null, end - index);
+    for (let i = index; i < end; i++) writes.push({ id: items[i]!.id, key: keys[i - index]! });
+  }
+  const next = writes.length > 0 ? writes[0]!.key : (items[index]?.key ?? null);
+  writes.push({ id: movingId, key: keyBetween(prev, next) });
+  return writes;
+}
+
+/** The order of two keys: the code units of the strings, as the keys need (not `localeCompare`). */
+export function compareKeys(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** A point, for example the center of an item on the screen. */
+export interface Point {
+  readonly x: number;
+  readonly y: number;
+}
+
+/**
+ * This function gives the index at which a point goes among the items of a list on the screen.
+ * The reading order is the rows from top to bottom, and each row from left to right.
+ * The index is that of the first item whose center comes after the point, from 0 to the number of items. A center within
+ * `rowTolerance` of the point on the vertical axis is in the row of the point.
+ *
+ * Give the centers in reading order, the same order as the keys, and without the item that moves.
+ *
+ * @example
+ * ```ts
+ * const index = dropIndex(pointer, others.map(centerOf));
+ * const key = keyBetween(keys[index - 1], keys[index]);
+ * ```
+ */
+export function dropIndex(point: Point, centers: readonly Point[], rowTolerance = 24): number {
+  for (let i = 0; i < centers.length; i++) {
+    const c = centers[i]!;
+    if (point.y < c.y - rowTolerance) return i;
+    if (Math.abs(point.y - c.y) <= rowTolerance && point.x < c.x) return i;
+  }
+  return centers.length;
+}

package/src/storage/listeners.ts

@@ -0,0 +1,72 @@
+/**
+ * A set of listeners for the events of a storage: the change batches of `observe()`, or the status
+ * of a sync. A storage package uses it, so each storage treats its listeners in the same way.
+ */
+
+/** The function that gets the error of a listener. */
+export type ListenerErrorHandler = (error: unknown) => void;
+
+/**
+ * The default handler of the error of a listener. It throws the error again in a microtask, as an
+ * `EventTarget` reports the error of a listener. Thus the error is not lost, and the write that
+ * sent the event does not fail.
+ */
+export const reportListenerError: ListenerErrorHandler = (error) => {
+  queueMicrotask(() => {
+    throw error;
+  });
+};
+
+/**
+ * The listeners of one kind of event.
+ *
+ * - `emit()` gives the event to each listener, in the order of `add()`.
+ * - A listener that `add()` gets during an `emit()` gets the next event, not this one.
+ * - The error of a listener goes to the error handler. The other listeners get the event.
+ * - The same function can be added two times. Each `add()` gives its own function that removes it.
+ */
+export class StorageListeners<E> {
+  private readonly listeners = new Set<{ readonly listener: (event: E) => void }>();
+  private readonly onError: ListenerErrorHandler;
+
+  /** @param onError - The function that gets the error of a listener. The default is `reportListenerError`. */
+  constructor(onError: ListenerErrorHandler = reportListenerError) {
+    this.onError = onError;
+  }
+
+  /** The number of listeners. */
+  get size(): number {
+    return this.listeners.size;
+  }
+
+  /**
+   * This method adds a listener.
+   *
+   * @returns The function that removes the listener. A second use of it does nothing.
+   */
+  add(listener: (event: E) => void): () => void {
+    const entry = { listener };
+    this.listeners.add(entry);
+    return () => {
+      this.listeners.delete(entry);
+    };
+  }
+
+  /** This method gives the event to each listener. */
+  emit(event: E): void {
+    for (const entry of [...this.listeners]) {
+      // A listener that a listener before it removed gets no event
+      if (!this.listeners.has(entry)) continue;
+      try {
+        entry.listener(event);
+      } catch (error) {
+        this.onError(error);
+      }
+    }
+  }
+
+  /** This method removes each listener. */
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/testing/check.ts

@@ -0,0 +1,81 @@
+/**
+ * The checks of the contract suite. The suite does not import a test framework, so a runtime
+ * entry of this package does not load one. A failed check throws `ContractViolation`.
+ */
+
+/** The error of a failed check of the contract suite. */
+export class ContractViolation extends Error {
+  override readonly name = "ContractViolation";
+}
+
+/** This function gives the text of a value for a message: JSON, with a `Map` as its entries. */
+export function show(value: unknown): string {
+  if (value === undefined) return "undefined";
+  try {
+    return JSON.stringify(value, (_key, item: unknown) => (item instanceof Map ? { Map: [...item.entries()] } : item === undefined ? "<undefined>" : item));
+  } catch {
+    return String(value);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype = Object.getPrototypeOf(value) as unknown;
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * This function compares two values deeply: JSON values, arrays, plain objects and maps. Two maps
+ * are equal when they have the same keys with equal values, in any order.
+ */
+export function deepEqual(actual: unknown, expected: unknown): boolean {
+  if (Object.is(actual, expected)) return true;
+  if (actual instanceof Map && expected instanceof Map) {
+    if (actual.size !== expected.size) return false;
+    for (const [key, value] of actual) {
+      if (!expected.has(key) || !deepEqual(value, expected.get(key))) return false;
+    }
+    return true;
+  }
+  if (Array.isArray(actual) && Array.isArray(expected)) {
+    return actual.length === expected.length && actual.every((item, index) => deepEqual(item, expected[index]));
+  }
+  if (isPlainObject(actual) && isPlainObject(expected)) {
+    const keys = Object.keys(actual);
+    if (keys.length !== Object.keys(expected).length) return false;
+    return keys.every((key) => Object.prototype.hasOwnProperty.call(expected, key) && deepEqual(actual[key], expected[key]));
+  }
+  return false;
+}
+
+/** This function throws `ContractViolation` when the two values are not deeply equal. */
+export function same(actual: unknown, expected: unknown, what: string): void {
+  if (!deepEqual(actual, expected)) {
+    throw new ContractViolation(`${what}: expected ${show(expected)}, got ${show(actual)}`);
+  }
+}
+
+/** This function throws `ContractViolation` when the condition is false. */
+export function holds(condition: boolean, what: string): void {
+  if (!condition) throw new ContractViolation(what);
+}
+
+/**
+ * This function starts an operation that must fail with a rejected promise, and gives the error.
+ * A synchronous throw breaks the contract too: each method of a storage gives a promise.
+ */
+export async function rejects(start: () => Promise<unknown>, what: string): Promise<unknown> {
+  let promise: Promise<unknown>;
+  try {
+    promise = start();
+  } catch (error) {
+    throw new ContractViolation(`${what}: the method threw at once (${show(error instanceof Error ? error.message : error)}), and did not give a rejected promise`);
+  }
+  holds(typeof promise?.then === "function", `${what}: the method did not give a promise`);
+  try {
+    await promise;
+  } catch (error) {
+    return error;
+  }
+  throw new ContractViolation(`${what}: the promise did not reject`);
+}

package/src/testing/index.ts

@@ -0,0 +1,7 @@
+/**
+ * `@mark1russell7/collections/testing`: the checks of a contract suite.
+ *
+ * This entry imports no test framework. The runtime entries of the package do not import this entry.
+ */
+
+export { ContractViolation, deepEqual, holds, rejects, same, show } from "./check.js";