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

package/src/constraints.d.ts

@@ -29,6 +29,14 @@
  * @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;

package/src/constraints.js

@@ -45,6 +45,20 @@ export function violationsOf(err) {
   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 };

package/src/documentLock.d.ts

@@ -45,10 +45,11 @@ export function withDocumentLock(client: object, documentId: string, fn: (lock:
  * 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.
+ * 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
@@ -99,11 +100,24 @@ export class LockKeeper {
     _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.

package/src/documentLock.js

@@ -18,10 +18,11 @@ import { uuidv4 } from "./ids.js";
  * 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.
+ * 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
@@ -109,6 +110,9 @@ export class LockKeeper {
     this._stopped = false;
     this._wake = null;
     this._running = null;
+    // When the window this keeper last saw renewed runs out, on its clock.
+    // Moved by a renewal (run) and by an accepted write (noteWrite).
+    this._deadline = clock() + ttlMs;
     /**
      * The `DocumentLockLost` this keeper raised, or null.
      * @type {DocumentLockLost | null}
@@ -116,6 +120,29 @@ export class LockKeeper {
     this.lost = null;
   }
 
+  get documentId() {
+    return this._documentId;
+  }
+
+  /** This keeper's clock, which a write's send time is read on. */
+  now() {
+    return this._clock();
+  }
+
+  /**
+   * 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) {
+    if (this._clock() < this._deadline) {
+      this._deadline = Math.max(this._deadline, sentAt + this._ttlMs);
+    }
+  }
+
   /**
    * Time between renewals: half the window, so a renewal that fails has a
    * second chance before the lock it is renewing expires.
@@ -151,9 +178,11 @@ export class LockKeeper {
 
   /** The beat. Resolves when the block exits or the lock is lost. */
   async run() {
-    let deadline = this._clock() + this._ttlMs;
     let delay = this.intervalMs;
     while (!(await this._sleep(delay))) {
+      // The window is counted from when the renewal was sent, since the
+      // server starts it on receipt, not when its answer gets back.
+      const sent = this._clock();
       try {
         await this._refresh(this._documentId);
       } catch (error) {
@@ -161,14 +190,14 @@ export class LockKeeper {
         // expired or was dropped, and the server never takes it back.
         // Anything else may be a blip, and is only fatal once the lock we are
         // renewing has actually run out.
-        if (error?.status === 423 || this._clock() >= deadline) {
+        if (error?.status === 423 || this._clock() >= this._deadline) {
           this._fail(error);
           return;
         }
         delay = this.retryMs;
         continue;
       }
-      deadline = this._clock() + this._ttlMs;
+      this._deadline = Math.max(this._deadline, sent + this._ttlMs);
       delay = this.intervalMs;
     }
   }
@@ -264,7 +293,7 @@ async function takeLock(client, documentId, lockId, retryMs) {
     if (error?.status === 423) {
       // The error body is raw JSON off the wire, so it is still kebab-cased.
       const body = error.responseData || {};
-      const holder = body.userId || body["user-id"] || "another user";
+      const holder = body["user-id"] || "another user";
       const readable = new Error(
         `This document is being edited by ${holder}. Try again once they're done.`,
       );
@@ -320,6 +349,7 @@ export async function withDocumentLock(
         },
       },
     );
+    client.lockKeepers?.set(documentId, keeper);
     keeper.start();
   }
 
@@ -331,7 +361,11 @@ export async function withDocumentLock(
     threw = true;
     throw error;
   } finally {
-    if (keeper) keeper.stop();
+    if (keeper) {
+      keeper.stop();
+      if (client.lockKeepers?.get(documentId) === keeper)
+        client.lockKeepers.delete(documentId);
+    }
     const lost = keeper ? keeper.lost : null;
     client.documentLockLost = null;
     // Best-effort release: the server TTL reclaims a stranded lock, and we must

package/src/entryForms.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A form written the way FieldWorks writes a morph standing alone: "-ar" for
+ * a suffix, "ka-" for a prefix, "=ni" for an enclitic, unchanged for a stem or
+ * for a type outside the table or none.
+ *
+ * @template {string | null | undefined} F
+ * @param {string | null | undefined} morphType
+ * @param {F} form
+ * @returns {F | string}
+ */
+export function decorateWithAffixMarkers<F extends string | null | undefined>(morphType: string | null | undefined, form: F): F | string;
+/**
+ * A morph form as FieldWorks writes it, read back: the inverse of
+ * decorateWithAffixMarkers. A morph of a known type loses exactly that type's
+ * markers ("-ar" of a suffix is "ar"), and a form without them is kept as
+ * written. A morph with no type, or a type outside MORPH_TYPES, takes the type
+ * its markers name ("ni=" is a proclitic), and keeps its form whole when they
+ * name none. The type comes back lower-cased, or null.
+ *
+ * @param {string | null | undefined} morphType
+ * @param {string | null | undefined} form
+ * @returns {{ form: string | null | undefined, morphType: string | null }}
+ */
+export function readAffixMarkers(morphType: string | null | undefined, form: string | null | undefined): {
+    form: string | null | undefined;
+    morphType: string | null;
+};
+/**
+ * The form and morph type an entry stores, from the form and type a person,
+ * a file or a model gave. A form carrying its type's markers loses them
+ * ("-s" of a suffix is "s"). A form carrying "-" or "=" markers that name a
+ * type loses them. When a type in MORPH_TYPES came with the form, that type
+ * is kept ("theŋjən-" given as a bound stem is the bound stem "theŋjən"), and
+ * only when none came do the markers set it ("-s" with no type is the suffix
+ * "s"). Any other form, a free-text one with whitespace inside its markers
+ * among them, is kept as written with the type it came with, which is
+ * returned as given ("*kwa" with no type stays "*kwa", a reconstructed form).
+ *
+ * @template {string | null | undefined} T
+ * @param {T} morphType
+ * @param {string | null | undefined} form
+ * @returns {{ form: string | null | undefined, morphType: T | string }}
+ */
+export function entryForm<T extends string | null | undefined>(morphType: T, form: string | null | undefined): {
+    form: string | null | undefined;
+    morphType: T | string;
+};
+/**
+ * How a lexicon entry's form is stored: without affix or clitic markers. An
+ * entry's marker is drawn from its morph type ("-s" is a suffix "s", "ni=" a
+ * proclitic "ni"), so every writer of an entry form, in every app and in the
+ * Python client (plaid_client.workflows.igt.entry_forms), passes the form and
+ * type it was given through `entryForm` and stores what comes back.
+ *
+ * The morph types are FieldWorks' MoMorphType inventory, which LIFT and
+ * .flextext need verbatim. The markers are each type's Prefix and Postfix as
+ * FieldWorks spells a morph standing alone, read off the factory objects of
+ * real .fwbackup files (identical in Lezgi, Sena, Arabic, Onim and Lamkang).
+ * The seven types left out of the table (stem, root, circumfix, clitic,
+ * particle, phrase, discontiguous phrase) have no marker in that data.
+ */
+/** FieldWorks' morph types, the values a stored morph type may take. */
+export const MORPH_TYPES: readonly string[];

package/src/entryForms.js

@@ -0,0 +1,152 @@
+/**
+ * How a lexicon entry's form is stored: without affix or clitic markers. An
+ * entry's marker is drawn from its morph type ("-s" is a suffix "s", "ni=" a
+ * proclitic "ni"), so every writer of an entry form, in every app and in the
+ * Python client (plaid_client.workflows.igt.entry_forms), passes the form and
+ * type it was given through `entryForm` and stores what comes back.
+ *
+ * The morph types are FieldWorks' MoMorphType inventory, which LIFT and
+ * .flextext need verbatim. The markers are each type's Prefix and Postfix as
+ * FieldWorks spells a morph standing alone, read off the factory objects of
+ * real .fwbackup files (identical in Lezgi, Sena, Arabic, Onim and Lamkang).
+ * The seven types left out of the table (stem, root, circumfix, clitic,
+ * particle, phrase, discontiguous phrase) have no marker in that data.
+ */
+
+/** FieldWorks' morph types, the values a stored morph type may take. */
+export const MORPH_TYPES = Object.freeze([
+  "stem",
+  "bound stem",
+  "root",
+  "bound root",
+  "prefix",
+  "suffix",
+  "infix",
+  "circumfix",
+  "simulfix",
+  "suprafix",
+  "infixing interfix",
+  "prefixing interfix",
+  "suffixing interfix",
+  "clitic",
+  "enclitic",
+  "proclitic",
+  "particle",
+  "phrase",
+  "discontiguous phrase",
+]);
+
+/** @type {Readonly<Record<string, readonly [string, string]>>} */
+const MORPH_TYPE_MARKERS = Object.freeze({
+  "bound root": ["*", ""],
+  "bound stem": ["*", ""],
+  enclitic: ["=", ""],
+  infix: ["-", "-"],
+  "infixing interfix": ["-", "-"],
+  prefix: ["", "-"],
+  "prefixing interfix": ["", "-"],
+  proclitic: ["", "="],
+  simulfix: ["=", "="],
+  suffix: ["-", ""],
+  "suffixing interfix": ["-", ""],
+  suprafix: ["~", "~"],
+});
+
+// The one plain type each pair of "-" and "=" markers names, keyed
+// "<before>,<after>". The interfixes share their markers with a plainer type,
+// so markers alone never name one, and "*" and "~" are left out because both
+// also occur in forms as themselves (a reconstructed "*kwa").
+/** @type {Readonly<Record<string, string>>} */
+const TYPE_BY_MARKERS = Object.freeze({
+  "-,": "suffix",
+  ",-": "prefix",
+  "-,-": "infix",
+  "=,": "enclitic",
+  ",=": "proclitic",
+  "=,=": "simulfix",
+});
+
+/**
+ * A form written the way FieldWorks writes a morph standing alone: "-ar" for
+ * a suffix, "ka-" for a prefix, "=ni" for an enclitic, unchanged for a stem or
+ * for a type outside the table or none.
+ *
+ * @template {string | null | undefined} F
+ * @param {string | null | undefined} morphType
+ * @param {F} form
+ * @returns {F | string}
+ */
+export function decorateWithAffixMarkers(morphType, form) {
+  if (form == null || form === "") return form;
+  const marks = MORPH_TYPE_MARKERS[String(morphType ?? "").toLowerCase()];
+  return marks ? `${marks[0]}${form}${marks[1]}` : form;
+}
+
+/** @param {string} form @param {string} type */
+const strips = (form, type) => {
+  const [before, after] = MORPH_TYPE_MARKERS[type] ?? ["", ""];
+  return before + after !== "" &&
+    form.length > before.length + after.length &&
+    form.startsWith(before) &&
+    form.endsWith(after)
+    ? form.slice(before.length, form.length - after.length)
+    : null;
+};
+
+// A form whose bare middle holds whitespace is free text ("-du, du-"), so its
+// markers name no type and stay. WHITESPACE spells out JS's \s, so the
+// Python client's copy matches it character for character.
+const WHITESPACE = /[\t\n\v\f\r \u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]/u;
+/** @param {string} form */
+const markedType = (form) => {
+  const m = /^([-=]?)(.+?)([-=]?)$/su.exec(form);
+  const type = m && !WHITESPACE.test(m[2]) && TYPE_BY_MARKERS[`${m[1]},${m[3]}`];
+  return type && m ? { form: m[2], morphType: type } : null;
+};
+
+/**
+ * A morph form as FieldWorks writes it, read back: the inverse of
+ * decorateWithAffixMarkers. A morph of a known type loses exactly that type's
+ * markers ("-ar" of a suffix is "ar"), and a form without them is kept as
+ * written. A morph with no type, or a type outside MORPH_TYPES, takes the type
+ * its markers name ("ni=" is a proclitic), and keeps its form whole when they
+ * name none. The type comes back lower-cased, or null.
+ *
+ * @param {string | null | undefined} morphType
+ * @param {string | null | undefined} form
+ * @returns {{ form: string | null | undefined, morphType: string | null }}
+ */
+export function readAffixMarkers(morphType, form) {
+  const named = String(morphType ?? "").toLowerCase();
+  const known = MORPH_TYPES.includes(named) ? named : null;
+  if (form == null || form === "") return { form, morphType: known };
+  if (known) return { form: strips(form, known) ?? form, morphType: known };
+  return markedType(form) ?? { form, morphType: null };
+}
+
+/**
+ * The form and morph type an entry stores, from the form and type a person,
+ * a file or a model gave. A form carrying its type's markers loses them
+ * ("-s" of a suffix is "s"). A form carrying "-" or "=" markers that name a
+ * type loses them. When a type in MORPH_TYPES came with the form, that type
+ * is kept ("theŋjən-" given as a bound stem is the bound stem "theŋjən"), and
+ * only when none came do the markers set it ("-s" with no type is the suffix
+ * "s"). Any other form, a free-text one with whitespace inside its markers
+ * among them, is kept as written with the type it came with, which is
+ * returned as given ("*kwa" with no type stays "*kwa", a reconstructed form).
+ *
+ * @template {string | null | undefined} T
+ * @param {T} morphType
+ * @param {string | null | undefined} form
+ * @returns {{ form: string | null | undefined, morphType: T | string }}
+ */
+export function entryForm(morphType, form) {
+  if (typeof form !== "string" || form === "") return { form, morphType };
+  const own = typeof morphType === "string" ? morphType.toLowerCase() : "";
+  const given = MORPH_TYPES.includes(own);
+  const bare = given ? strips(form, own) : null;
+  if (bare != null) return { form: bare, morphType };
+  const marked = markedType(form);
+  if (!marked) return { form, morphType };
+  return given ? { form: marked.form, morphType } : marked;
+}

package/src/events.js

@@ -1,4 +1,5 @@
 import { transformRequest } from "./transforms.js";
+import { readResearchTelemetry } from "./roles.js";
 
 // ---------------------------------------------------------------------------
 // Client events: the opt-in research telemetry of a project (defined in
@@ -214,7 +215,7 @@ export class EventRecorder {
     Promise.resolve()
       .then(() => client.projects.get(projectId))
       .then(
-        (project) => project?.config?.plaid?.research?.telemetry === true,
+        (project) => readResearchTelemetry(project?.config),
         () => false,
       )
       .then((on) => {