@larc-iu/plaid-client 0.2.0-alpha.23 → 0.2.0-alpha.26

package/README.md

@@ -33,3 +33,7 @@ A page served by Plaid, for example from the folder set as `static_resources_pat
 
 - [Manual](https://larc-iu.github.io/plaid/manual.html), which covers the API and its concepts.
 - [API reference](https://larc-iu.github.io/plaid/api-js.html) for this client.
+
+## Types
+
+The type declarations are generated from the JSDoc in `src/` by `npm run types` (TypeScript's `tsc`), which `npm pack` runs. The JSDoc is their only source.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.23",
+  "version": "0.2.0-alpha.26",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {
@@ -17,10 +17,16 @@
     ".": "./src/index.js"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "types": "npm run clean-types && tsc -p .",
+    "clean-types": "node -e \"const fs = require('fs'); for (const f of fs.readdirSync('src')) if (f.endsWith('.d.ts')) fs.rmSync('src/' + f)\"",
+    "prepack": "npm run types",
+    "postpack": "npm run clean-types"
   },
   "files": [
-    "src/",
-    "index.d.ts"
-  ]
+    "src/"
+  ],
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
 }

package/src/batchRef.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A BatchRef for op `opIndex` of `batch` (negative counts from the end, -1
+ * is the op queued last), fixed when it is called.
+ */
+export function makeBatchRef(batch: any, opIndex: any, index: any): BatchRef;
+/**
+ * `body` with each BatchRef in it replaced by null, and the `refs` that say
+ * where they were, or `refs` null when it holds none (the body is then
+ * returned as it was).
+ */
+export function takeRefs(batch: any, body: any): {
+    body: any;
+    refs: any[];
+};
+/**
+ * `refs` counted from `start`, for an op in a batch sent in several requests
+ * (the server counts within one request). A ref to an op of an earlier
+ * request cannot resolve, so it throws before anything goes.
+ */
+export function rebaseRefs(refs: any, start: any): any;
+export class BatchRef {
+    constructor(batch: any, op: any, index: any);
+    /** The op, counted from 0 in the batch, whose id this stands for. */
+    $ref: any;
+    index: any;
+    belongsTo(batch: any): boolean;
+    toJSON(): void;
+    [Symbol.toPrimitive](): void;
+    #private;
+}

package/src/codepoint.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Unicode code-point helpers for working with Plaid text offsets.
+ *
+ * Plaid token offsets (`begin` / `end`) are 0-based indices in Unicode CODE
+ * POINTS (begin inclusive, end exclusive) — NOT UTF-16 code units. JavaScript
+ * strings are UTF-16, so `.length`, `.slice`, `.substring`, `s[i]`,
+ * `String.prototype.indexOf`, and `Intl.Segmenter`'s `index` all count UTF-16
+ * code units, which disagree with code points for astral characters
+ * (>= U+10000 — emoji, and SMP scripts such as Gothic, cuneiform, CJK Ext-B).
+ *
+ * Use these to slice a text body by token offsets, and to compute offsets for
+ * new tokens, in code points. The spread/`for…of` string iterator yields code
+ * points, which is what makes this work.
+ */
+/**
+ * Number of Unicode code points in `s` (not `s.length`, which is UTF-16).
+ * @param {string} s
+ * @returns {number}
+ */
+export function cpLength(s: string): number;
+/**
+ * Substring of `s` by CODE-POINT indices [begin, end) (end optional = to end).
+ * Mirrors `String.prototype.slice` semantics but in code points.
+ * @param {string} s
+ * @param {number} begin
+ * @param {number} [end]
+ * @returns {string}
+ */
+export function cpSlice(s: string, begin: number, end?: number): string;
+/**
+ * Prebuilt slicer for taking MANY code-point slices of the same string:
+ * spreads `s` into code points once, then each slice costs O(slice length).
+ * `cpSlice` spreads the whole string per call, which turns quadratic when a
+ * caller slices every token of a large text. Mirror of the server's
+ * `plaid.util.codepoint/cp-slicer`.
+ * @param {string} s
+ * @returns {(begin: number, end?: number) => string}
+ */
+export function cpSlicer(s: string): (begin: number, end?: number) => string;
+/**
+ * Convert a UTF-16 index `u` into `s` to a code-point index — i.e. how many
+ * code points precede `u`. Inverse of `cpToUtf16`. Useful for converting a
+ * DOM/`indexOf`/`Intl.Segmenter` (UTF-16) position into a code-point offset.
+ * @param {string} s
+ * @param {number} u
+ * @returns {number}
+ */
+export function utf16ToCp(s: string, u: number): number;
+/**
+ * Convert a code-point index `cp` into `s` to a UTF-16 index. Clamps to
+ * `s.length` when `cp` is past the end. Inverse of `utf16ToCp`.
+ * @param {string} s
+ * @param {number} cp
+ * @returns {number}
+ */
+export function cpToUtf16(s: string, cp: number): number;
+/**
+ * Like `String.prototype.indexOf`, but the returned index and `fromCp` are
+ * CODE-POINT indices. Returns -1 when `sub` is not found.
+ * @param {string} s
+ * @param {string} sub
+ * @param {number} [fromCp]
+ * @returns {number}
+ */
+export function cpIndexOf(s: string, sub: string, fromCp?: number): number;
+/**
+ * `s` composed (Unicode NFC), as the server stores every text, and where each
+ * code-point position of `s` goes in it: `{ text, at }`, `at(p)` for every p
+ * in [0, cpLength(s)]. Mirror of the server's `plaid.util.canonical/compose`,
+ * for an app that measures tokens on a body it is about to send: the server
+ * stores `text`, and a token measured at [b, e) on `s` is at [at(b), at(e)).
+ *
+ * `s` is cut before each code point that is not a mark, a piece joined to the
+ * one before when the two compose together (Hangul jamo, a vowel sign), and
+ * each piece composes on its own. A position inside a piece composing changed
+ * goes to where cutting the piece there composes the same, else to the next
+ * such place, at the latest the piece's composed end, so an edge between a
+ * letter and the mark that composes with it moves to after the composed
+ * character, and a mark that does not compose stays out of it. `at` never
+ * reverses two positions.
+ *
+ * `cuts` are the code-point positions of `s` where the text's tokens begin
+ * and end. A piece with a cut inside it composes in parts, one between each
+ * two cuts, so a character whose letter and mark belong to two tokens stays
+ * decomposed, each token keeps its own characters, and none is left with no
+ * text. The server composes every body with its tokens' edges.
+ * @param {string} s
+ * @param {Iterable<number> | null} [cuts]
+ * @returns {{text: string, at: (p: number) => number}}
+ */
+export function composeText(s: string, cuts?: Iterable<number> | null): {
+    text: string;
+    at: (p: number) => number;
+};

package/src/codepoint.js

@@ -13,7 +13,11 @@
  * points, which is what makes this work.
  */
 
-/** Number of Unicode code points in `s` (not `s.length`, which is UTF-16). */
+/**
+ * Number of Unicode code points in `s` (not `s.length`, which is UTF-16).
+ * @param {string} s
+ * @returns {number}
+ */
 export function cpLength(s) {
   return [...s].length;
 }
@@ -21,6 +25,10 @@ export function cpLength(s) {
 /**
  * Substring of `s` by CODE-POINT indices [begin, end) (end optional = to end).
  * Mirrors `String.prototype.slice` semantics but in code points.
+ * @param {string} s
+ * @param {number} begin
+ * @param {number} [end]
+ * @returns {string}
  */
 export function cpSlice(s, begin, end) {
   return [...s].slice(begin, end).join('');
@@ -32,6 +40,8 @@ export function cpSlice(s, begin, end) {
  * `cpSlice` spreads the whole string per call, which turns quadratic when a
  * caller slices every token of a large text. Mirror of the server's
  * `plaid.util.codepoint/cp-slicer`.
+ * @param {string} s
+ * @returns {(begin: number, end?: number) => string}
  */
 export function cpSlicer(s) {
   const chars = [...(s ?? '')];
@@ -42,6 +52,9 @@ export function cpSlicer(s) {
  * Convert a UTF-16 index `u` into `s` to a code-point index — i.e. how many
  * code points precede `u`. Inverse of `cpToUtf16`. Useful for converting a
  * DOM/`indexOf`/`Intl.Segmenter` (UTF-16) position into a code-point offset.
+ * @param {string} s
+ * @param {number} u
+ * @returns {number}
  */
 export function utf16ToCp(s, u) {
   return [...s.slice(0, u)].length;
@@ -50,6 +63,9 @@ export function utf16ToCp(s, u) {
 /**
  * Convert a code-point index `cp` into `s` to a UTF-16 index. Clamps to
  * `s.length` when `cp` is past the end. Inverse of `utf16ToCp`.
+ * @param {string} s
+ * @param {number} cp
+ * @returns {number}
  */
 export function cpToUtf16(s, cp) {
   if (cp <= 0) return 0;
@@ -66,8 +82,122 @@ export function cpToUtf16(s, cp) {
 /**
  * Like `String.prototype.indexOf`, but the returned index and `fromCp` are
  * CODE-POINT indices. Returns -1 when `sub` is not found.
+ * @param {string} s
+ * @param {string} sub
+ * @param {number} [fromCp]
+ * @returns {number}
  */
 export function cpIndexOf(s, sub, fromCp = 0) {
   const u = s.indexOf(sub, cpToUtf16(s, fromCp));
   return u < 0 ? -1 : utf16ToCp(s, u);
 }
+
+const MARK = /^\p{M}$/u;
+
+// The longest piece whose inside positions are each placed where cutting
+// there leaves the composed text as it is (core's `refine-limit`).
+const REFINE_LIMIT = 32;
+
+// The positions strictly inside the piece [b, e) of `cps`, which composed to
+// `c` (`len` code points) at `out`: a place where the piece's two halves
+// compose apart to `c` goes to the end of the first half (a tone mark that
+// does not compose with ẹ stays out of it), any other to the next such place,
+// else to the piece's end. Mirror of core's `refine-inside!`.
+function refineInside(at, cps, b, e, out, c, len) {
+  const whole = e - b > REFINE_LIMIT;
+  let next = out + len;
+  for (let i = e - 1; i > b; i -= 1) {
+    if (!whole) {
+      const pre = cps.slice(b, i).join('').normalize('NFC');
+      if (pre + cps.slice(i, e).join('').normalize('NFC') === c) {
+        next = Math.min(next, out + [...pre].length);
+      }
+    }
+    at[i] = next;
+  }
+}
+
+/**
+ * `s` composed (Unicode NFC), as the server stores every text, and where each
+ * code-point position of `s` goes in it: `{ text, at }`, `at(p)` for every p
+ * in [0, cpLength(s)]. Mirror of the server's `plaid.util.canonical/compose`,
+ * for an app that measures tokens on a body it is about to send: the server
+ * stores `text`, and a token measured at [b, e) on `s` is at [at(b), at(e)).
+ *
+ * `s` is cut before each code point that is not a mark, a piece joined to the
+ * one before when the two compose together (Hangul jamo, a vowel sign), and
+ * each piece composes on its own. A position inside a piece composing changed
+ * goes to where cutting the piece there composes the same, else to the next
+ * such place, at the latest the piece's composed end, so an edge between a
+ * letter and the mark that composes with it moves to after the composed
+ * character, and a mark that does not compose stays out of it. `at` never
+ * reverses two positions.
+ *
+ * `cuts` are the code-point positions of `s` where the text's tokens begin
+ * and end. A piece with a cut inside it composes in parts, one between each
+ * two cuts, so a character whose letter and mark belong to two tokens stays
+ * decomposed, each token keeps its own characters, and none is left with no
+ * text. The server composes every body with its tokens' edges.
+ * @param {string} s
+ * @param {Iterable<number> | null} [cuts]
+ * @returns {{text: string, at: (p: number) => number}}
+ */
+export function composeText(s, cuts = null) {
+  const text0 = s ?? '';
+  if (text0.normalize('NFC') === text0) return { text: text0, at: (p) => p };
+  const cps = [...text0];
+  const n = cps.length;
+  const cutAt = new Set();
+  for (const c of cuts ?? []) if (Number.isInteger(c) && c > 0 && c < n) cutAt.add(c);
+  const pieces = [];
+  let start = 0;
+  for (let i = 1; i <= n; i += 1) {
+    if (i < n && MARK.test(cps[i])) continue;
+    const last = pieces[pieces.length - 1];
+    if (last && cps[start].codePointAt(0) >= 0x300) {
+      const a = cps.slice(last[0], last[1]).join('');
+      const b = cps.slice(start, i).join('');
+      if ((a + b).normalize('NFC') !== a.normalize('NFC') + b.normalize('NFC')) {
+        last[1] = i;
+        start = i;
+        continue;
+      }
+    }
+    pieces.push([start, i]);
+    start = i;
+  }
+  // a piece with a cut strictly inside it composes in parts
+  const parts = [];
+  for (const [b, e] of pieces) {
+    let from = b;
+    for (let i = b + 1; i < e; i += 1) {
+      if (cutAt.has(i)) {
+        parts.push([from, i]);
+        from = i;
+      }
+    }
+    parts.push([from, e]);
+  }
+  const at = new Int32Array(n + 1);
+  let text = '';
+  let out = 0;
+  for (const [b, e] of parts) {
+    const src = cps.slice(b, e).join('');
+    const c = src.normalize('NFC');
+    const len = [...c].length;
+    text += c;
+    if (c === src) {
+      for (let i = b; i < e; i += 1) at[i] = out + (i - b);
+    } else {
+      at[b] = out;
+      refineInside(at, cps, b, e, out, c, len);
+    }
+    out += len;
+  }
+  at[n] = out;
+  const expected = text0.normalize('NFC');
+  if ((cutAt.size ? text.normalize('NFC') : text) !== expected) {
+    throw new Error('The text could not be composed.');
+  }
+  return { text, at: (p) => at[p] };
+}

package/src/constraints.d.ts

@@ -0,0 +1,77 @@
+/**
+ * A constraint an app declares on a layer, e.g. `{type: "value-set", values: ["N"]}`.
+ * @typedef {{type: "max-in-degree" | "acyclic" | "same-ancestor" | "single-span"
+ *   | "value-set" | "coextensive" | "single-link"} & Record<string, any>} LayerConstraint
+ */
+/**
+ * `expected`: the list read for the namespace, null when it was absent.
+ * @typedef {{expected?: LayerConstraint[] | null}} ConstraintWriteOptions
+ */
+/**
+ * One violation a 422 lists.
+ * @typedef {object} ConstraintViolation
+ * @property {string} constraint
+ * @property {string | null} namespace
+ * @property {string} layer
+ * @property {string} layerName
+ * @property {string | null} document
+ * @property {string | null} at
+ * @property {string[]} ids
+ * @property {any} [value]
+ * @property {string[]} [parts]
+ */
+/**
+ * The violations of a write refused by a layer constraint, camelCased
+ * ({constraint, namespace, layer, layerName, document, at, ids, value?,
+ * parts?}), or null for any other error. The answer lists at most 100, and
+ * `err.responseData["violation-count"]` is the total.
+ * @param {any} err
+ * @returns {ConstraintViolation[] | null}
+ */
+export function violationsOf(err: any): ConstraintViolation[] | null;
+/** The request body of a constraint write: the list, and `expected` when given. */
+export function constraintsBody(constraints: any, options: any): {
+    constraints?: undefined;
+} | {
+    constraints: any;
+};
+/**
+ * Whether a value-set constraint ({values, delimiters?, parts?}) allows
+ * `value` as the server reads it: null and blank values pass, a non-string
+ * does not, and every part split on a delimiter (or only the first, with
+ * `parts: "first"`), trimmed, must be listed.
+ * @param {{values: string[], delimiters?: string, parts?: "all"|"first"}} constraint
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function valueSetAllows(constraint: {
+    values: string[];
+    delimiters?: string;
+    parts?: "all" | "first";
+}, value: any): boolean;
+/**
+ * A constraint an app declares on a layer, e.g. `{type: "value-set", values: ["N"]}`.
+ */
+export type LayerConstraint = {
+    type: "max-in-degree" | "acyclic" | "same-ancestor" | "single-span" | "value-set" | "coextensive" | "single-link";
+} & Record<string, any>;
+/**
+ * `expected`: the list read for the namespace, null when it was absent.
+ */
+export type ConstraintWriteOptions = {
+    expected?: LayerConstraint[] | null;
+};
+/**
+ * One violation a 422 lists.
+ */
+export type ConstraintViolation = {
+    constraint: string;
+    namespace: string | null;
+    layer: string;
+    layerName: string;
+    document: string | null;
+    at: string | null;
+    ids: string[];
+    value?: any;
+    parts?: string[];
+};

package/src/constraints.js

@@ -7,13 +7,38 @@
 
 import { transformResponse } from "./transforms.js";
 
+/**
+ * A constraint an app declares on a layer, e.g. `{type: "value-set", values: ["N"]}`.
+ * @typedef {{type: "max-in-degree" | "acyclic" | "same-ancestor" | "single-span"
+ *   | "value-set" | "coextensive" | "single-link"} & Record<string, any>} LayerConstraint
+ */
+
+/**
+ * `expected`: the list read for the namespace, null when it was absent.
+ * @typedef {{expected?: LayerConstraint[] | null}} ConstraintWriteOptions
+ */
+
+/**
+ * One violation a 422 lists.
+ * @typedef {object} ConstraintViolation
+ * @property {string} constraint
+ * @property {string | null} namespace
+ * @property {string} layer
+ * @property {string} layerName
+ * @property {string | null} document
+ * @property {string | null} at
+ * @property {string[]} ids
+ * @property {any} [value]
+ * @property {string[]} [parts]
+ */
+
 /**
  * The violations of a write refused by a layer constraint, camelCased
  * ({constraint, namespace, layer, layerName, document, at, ids, value?,
  * parts?}), or null for any other error. The answer lists at most 100, and
  * `err.responseData["violation-count"]` is the total.
  * @param {any} err
- * @returns {Array<object>|null}
+ * @returns {ConstraintViolation[] | null}
  */
 export function violationsOf(err) {
   const vs = err?.status === 422 ? err?.responseData?.violations : undefined;

package/src/created.d.ts

@@ -0,0 +1,2 @@
+export function createdId(result: any | null | undefined): string | undefined;
+export function createdIds(result: any | null | undefined): string[];

package/src/documentLock.d.ts

@@ -0,0 +1,158 @@
+/**
+ * How long a freshly taken lock lasts, from the server's own answer.
+ *
+ * `expiresAt` is the epoch-millisecond moment the lock endpoints return, on
+ * the server's clock, so it is read against the server's clock too
+ * (`client.serverNow()`): this machine's clock being off cannot stretch or
+ * shrink the window. It is how a window an operator has retuned
+ * (`:plaid.server.locks/config :expiration-ms`) reaches the keeper.
+ *
+ * An answer that cannot be a window (none, already over, past an hour) is
+ * core's default, 60 s.
+ *
+ * @param {number} expiresAt
+ * @param {number} serverNowMs
+ * @returns {number}
+ */
+export function lockTtlMs(expiresAt: number, serverNowMs: number): number;
+/**
+ * Hold `documentId`'s server-enforced lock for the length of `fn`.
+ * `client.documents.locked` is the entry point; see its doc comment.
+ *
+ * @param {object} client
+ * @param {string} documentId
+ * @param {(lock: DocumentLock) => any} fn
+ * @param {{ keepAlive?: boolean, acquireRetryMs?: number }} [options]
+ */
+export function withDocumentLock(client: object, documentId: string, fn: (lock: DocumentLock) => any, { keepAlive, acquireRetryMs }?: {
+    keepAlive?: boolean;
+    acquireRetryMs?: number;
+}): Promise<any>;
+/**
+ * Keeping a document lock alive for as long as a `locked()` block runs.
+ *
+ * plaid-core expires a document lock about a minute after it was taken, and the
+ * holder's own writes are what renew it (`plaid.sql.operation` calls
+ * `refresh-locks!` on every write it accepts). That is the right rule for an
+ * editor, which writes as the person types. It is the wrong one for a service:
+ * a parser loads a model, reads the document, spends minutes in inference and
+ * only then writes, so for most of its run it holds nothing. The lock lapses in
+ * silence, a person's edit lands between the read the work was planned from and
+ * the write about to go out, and the write clobbers it.
+ *
+ * A `locked()` block therefore renews on a timer of its own. The renewal is an
+ * acquire that names the holder's `lockId`: the server refreshes the lock that
+ * id holds, and refuses one somebody else holds (the same user included).
+ *
+ * The beat is unconditional rather than "only when no write has gone out
+ * recently". The request layer knows the method of a call but not which
+ * document it touched, so a write to some other document would count as a
+ * renewal here and would not be one. Two extra requests a minute is the whole
+ * cost.
+ *
+ * A renewal that fails means the block is no longer holding what it asked for,
+ * so it stops the run: the loss is recorded on the client and every later write
+ * throws `DocumentLockLost`. The guard sits in the request layer because the
+ * callers are services, and a check they have to remember to call is a check
+ * that is missing somewhere.
+ */
+/**
+ * The lock a `documents.locked()` block was holding is no longer held.
+ *
+ * Thrown by the keep-alive when it cannot renew the lock, and then by the
+ * request layer on every write this client attempts, so work that has been
+ * running for minutes stops rather than writing over an edit that may have
+ * landed while the lock was gone.
+ */
+export class DocumentLockLost extends Error {
+    /**
+     * @param {string} message
+     * @param {string} documentId
+     * @param {unknown} [cause]
+     */
+    constructor(message: string, documentId: string, cause?: unknown);
+    /** @type {string} */
+    documentId: string;
+}
+/**
+ * Renews one document's lock until the block holding it exits.
+ *
+ * `refresh` is called with the document id and must reject on failure.
+ * `onLost` is called once, with the `DocumentLockLost`, when the lock can no
+ * longer be assumed.
+ *
+ * `clock` and `sleep` exist so the whole policy can be run on a fake clock:
+ * `sleep(delayMs)` resolves to true once the block has exited.
+ */
+export class LockKeeper {
+    constructor(refresh: any, documentId: any, ttlMs: any, { onLost, clock, sleep }?: {
+        onLost?: any;
+        clock?: () => number;
+        sleep?: any;
+    });
+    _refresh: any;
+    _documentId: any;
+    _ttlMs: any;
+    _onLost: any;
+    _clock: () => number;
+    _sleep: any;
+    _stopped: boolean;
+    _wake: any;
+    _running: Promise<void>;
+    /**
+     * The `DocumentLockLost` this keeper raised, or null.
+     * @type {DocumentLockLost | null}
+     */
+    lost: DocumentLockLost | null;
+    /**
+     * Time between renewals: half the window, so a renewal that fails has a
+     * second chance before the lock it is renewing expires.
+     */
+    get intervalMs(): number;
+    /**
+     * Time before retrying a renewal that failed. A blip should not end a run
+     * that the server still considers the holder of.
+     */
+    get retryMs(): number;
+    _defaultSleep(ms: any): Promise<any>;
+    /** The beat. Resolves when the block exits or the lock is lost. */
+    run(): Promise<void>;
+    start(): Promise<void>;
+    stop(): void;
+    _fail(error: any): void;
+}
+/**
+ * What a `client.documents.locked(id, (lock) => ...)` block gets.
+ *
+ * The block does not have to consult it: a lost lock stops the next write on
+ * its own. Read `lock.lost` (or call `lock.raiseIfLost()`) to give up earlier,
+ * between steps of work that has not written anything yet.
+ */
+export class DocumentLock {
+    /**
+     * @param {string} documentId
+     * @param {LockKeeper | null} keeper
+     * @param {string | null} [lockId]
+     */
+    constructor(documentId: string, keeper: LockKeeper | null, lockId?: string | null);
+    /** @type {string} */
+    documentId: string;
+    /**
+     * The holder id the acquire answered with.
+     * @type {string | null}
+     */
+    lockId: string | null;
+    _keeper: LockKeeper;
+    /**
+     * The `DocumentLockLost` if the lock lapsed, else null.
+     * @returns {DocumentLockLost | null}
+     */
+    get lost(): DocumentLockLost | null;
+    /** Throw if the lock lapsed. Call it between steps that have not written. */
+    raiseIfLost(): void;
+}
+/**
+ * The pause before sending again an acquire whose outcome is unknown, which
+ * grows by this much each time (three sends in all).
+ */
+export const LOCK_ACQUIRE_RETRY_MS: 500;

package/src/documentLock.js

@@ -39,10 +39,18 @@ import { uuidv4 } from "./ids.js";
  * landed while the lock was gone.
  */
 export class DocumentLockLost extends Error {
+  /**
+   * @param {string} message
+   * @param {string} documentId
+   * @param {unknown} [cause]
+   */
   constructor(message, documentId, cause) {
     super(message);
+    /** @type {"DocumentLockLost"} */
     this.name = "DocumentLockLost";
+    /** @type {string} */
     this.documentId = documentId;
+    /** @type {unknown} */
     this.cause = cause;
   }
 }
@@ -101,7 +109,10 @@ export class LockKeeper {
     this._stopped = false;
     this._wake = null;
     this._running = null;
-    /** The `DocumentLockLost` this keeper raised, or null. */
+    /**
+     * The `DocumentLockLost` this keeper raised, or null.
+     * @type {DocumentLockLost | null}
+     */
     this.lost = null;
   }
 
@@ -193,18 +204,31 @@ export class LockKeeper {
  * between steps of work that has not written anything yet.
  */
 export class DocumentLock {
+  /**
+   * @param {string} documentId
+   * @param {LockKeeper | null} keeper
+   * @param {string | null} [lockId]
+   */
   constructor(documentId, keeper, lockId = null) {
+    /** @type {string} */
     this.documentId = documentId;
-    /** The holder id the acquire answered with. */
+    /**
+     * The holder id the acquire answered with.
+     * @type {string | null}
+     */
     this.lockId = lockId;
     this._keeper = keeper;
   }
 
-  /** The `DocumentLockLost` if the lock lapsed, else null. */
+  /**
+   * The `DocumentLockLost` if the lock lapsed, else null.
+   * @returns {DocumentLockLost | null}
+   */
   get lost() {
     return this._keeper ? this._keeper.lost : null;
   }
 
+  /** Throw if the lock lapsed. Call it between steps that have not written. */
   raiseIfLost() {
     if (this.lost) throw this.lost;
   }