@larc-iu/plaid-client 0.2.0-alpha.3 → 0.2.0-alpha.30

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,85 @@
+/**
+ * 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;
+/**
+ * How many violations a write refused by a layer constraint has in all, or
+ * null for any other error. Read from the raw refusal's "violation-count",
+ * since the answer lists at most 100 of them.
+ * @param {any} err
+ * @returns {number | null}
+ */
+export function violationCountOf(err: any): number | 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

@@ -0,0 +1,112 @@
+/**
+ * Layer constraints: rules an app declares on the token, span and relation
+ * layers it owns, which the server enforces inside every write. A write that
+ * breaks one on a row it writes is refused with 422 and the violations. See
+ * the core manual, "Layer constraints".
+ */
+
+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 {ConstraintViolation[] | null}
+ */
+export function violationsOf(err) {
+  const vs = err?.status === 422 ? err?.responseData?.violations : undefined;
+  return Array.isArray(vs) ? transformResponse(vs) : null;
+}
+
+/**
+ * How many violations a write refused by a layer constraint has in all, or
+ * null for any other error. Read from the raw refusal's "violation-count",
+ * since the answer lists at most 100 of them.
+ * @param {any} err
+ * @returns {number | null}
+ */
+export function violationCountOf(err) {
+  const vs = violationsOf(err);
+  if (!vs) return null;
+  const n = err.responseData["violation-count"];
+  return typeof n === "number" ? n : vs.length;
+}
+
+/** The request body of a constraint write: the list, and `expected` when given. */
+export function constraintsBody(constraints, options) {
+  const body = constraints === undefined ? {} : { constraints };
+  if (options && Object.hasOwn(options, "expected")) {
+    body.expected = options.expected === undefined ? null : options.expected;
+  }
+  return body;
+}
+
+// What String.prototype.trim trims. The server trims a value-set's parts the
+// same way, so a value read as listed here is read so there.
+const splitParts = (value, delimiters) => {
+  const set = new Set([...(delimiters || "")]);
+  if (!set.size) return [value];
+  const out = [];
+  let part = "";
+  for (const ch of value) {
+    if (set.has(ch)) {
+      out.push(part);
+      part = "";
+    } else {
+      part += ch;
+    }
+  }
+  out.push(part);
+  return out;
+};
+
+/**
+ * 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, value) {
+  if (value == null) return true;
+  if (typeof value !== "string") return false;
+  if (value.trim() === "") return true;
+  const delimiters = constraint?.delimiters || "";
+  const values = constraint?.values || [];
+  const parts = splitParts(value, delimiters);
+  if (constraint?.parts === "first") {
+    const firsts = new Set(values.map((v) => splitParts(v, delimiters)[0].trim()));
+    return firsts.has(parts[0].trim());
+  }
+  const allowed = new Set(values);
+  return parts.every((p) => p.trim() !== "" && allowed.has(p.trim()));
+}

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/created.js

@@ -0,0 +1,29 @@
+/**
+ * The ids a create answered with. A create's response is `{id}` and a bulk
+ * create's is `{ids}`, read straight off the call or off its result in a
+ * batch (`{status, body}`). Every reader of a create response goes through
+ * these, so none guesses at the shape.
+ */
+
+const isId = (v) => typeof v === "string";
+
+/**
+ * The id a single create answered with, or undefined when it gave none.
+ * @param {Object|null|undefined} result - the create's response, or its batch result
+ * @returns {string|undefined}
+ */
+export const createdId = (result) => {
+  if (isId(result?.id)) return result.id;
+  return isId(result?.body?.id) ? result.body.id : undefined;
+};
+
+/**
+ * The ids a bulk create answered with, in input order, or an empty array
+ * when it gave none.
+ * @param {Object|null|undefined} result - the bulk create's response, or its batch result
+ * @returns {string[]}
+ */
+export const createdIds = (result) => {
+  if (Array.isArray(result?.ids)) return result.ids;
+  return Array.isArray(result?.body?.ids) ? result.body.ids : [];
+};

package/src/documentLock.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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". Two extra requests a minute is the whole cost. A write the server
+ * took that moved the locked document's version renewed the lock as well, and
+ * the request layer tells the keeper (`writesStarted`, `writesLanded` in
+ * http.js), so renewals that fail with something other than a 423 while the
+ * run's writes land do not end the run as a lost lock.
+ *
+ * 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>;
+    _deadline: any;
+    /**
+     * The `DocumentLockLost` this keeper raised, or null.
+     * @type {DocumentLockLost | null}
+     */
+    lost: DocumentLockLost | null;
+    get documentId(): any;
+    /** This keeper's clock, which a write's send time is read on. */
+    now(): number;
+    /**
+     * A write of the locked document, sent at `sentAt`, was taken. The server
+     * renews a live lock on every write its holder makes to the document, from
+     * when it took the write, which is no earlier than `sentAt`. It counts only
+     * when its answer came back before the window this keeper counts ran out:
+     * the server then still held the lock when it took the write.
+     * @param {number} sentAt
+     */
+    noteWrite(sentAt: number): void;
+    /**
+     * 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;