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

package/src/serviceSchema.d.ts

@@ -22,6 +22,9 @@
  * @property {"Sentence" | "Word" | "Morpheme"} [scope] `field` only: the
  *   scope of the project's annotation fields the value names one of. A
  *   `field` value is a string everywhere else.
+ * @property {string} [role] `field` only: the lexicon role whose paired field,
+ *   or the sentence role whose field, fills the parameter when nothing else
+ *   does.
  */
 /**
  * A service's standardized self-description (lives in `extras`).
@@ -106,17 +109,9 @@ export function getServiceSummary(service: {
  * @returns {Record<string, any>} { [key]: defaultValue }
  */
 export function buildDefaultValues(schema: ServiceParam[]): Record<string, any>;
-/**
- * Coerce/validate raw form values against the schema. Returns the cleaned
- * values (keyed by param key, ready to merge into the request payload) plus any
- * validation errors keyed by param key. Unknown keys in `raw` are dropped.
- * @param {ServiceParam[]} schema getParamSchema(service)
- * @param {Record<string, any>} raw current form values
- * @returns {{values: Record<string, any>, errors: Record<string, string>}}
- */
-export function coerceParamValues(schema: ServiceParam[], raw: Record<string, any>): {
-    values: Record<string, any>;
-    errors: Record<string, string>;
+export function coerceParamValues(schema: any, raw: any): {
+    values: {};
+    errors: {};
 };
 /**
  * Service self-description: tasks, summary, and a parameter schema.
@@ -143,13 +138,18 @@ export function coerceParamValues(schema: ServiceParam[], raw: Record<string, an
  *         options?: [{value, label}],   // enum / multiselect
  *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
  *         placeholder?, multiline?,     // string
- *         scope? }                      // field: 'Sentence' | 'Word' | 'Morpheme'
+ *         scope?, role? }               // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
  * A `field` parameter names one of the project's annotation fields at its
  * `scope`. A UI that knows the project offers those fields to choose from; to
- * everything here, and to a UI that does not, it is a string.
+ * everything here, and to a UI that does not, it is a string. Its optional
+ * `role` names a lexicon role ("gloss") or, at Sentence scope, a sentence
+ * field's role ("translation", "literalTranslation", "note"): a UI that knows
+ * the project fills the parameter with the one field at `scope` whose stored
+ * Lexicon field holds that role, or whose stored role it is. A field is never
+ * chosen by its name.
  *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
@@ -265,6 +265,12 @@ export type ServiceParam = {
      * `field` value is a string everywhere else.
      */
     scope?: "Sentence" | "Word" | "Morpheme";
+    /**
+     * `field` only: the lexicon role whose paired field,
+     * or the sentence role whose field, fills the parameter when nothing else
+     * does.
+     */
+    role?: string;
 };
 /**
  * A service's standardized self-description (lives in `extras`).

package/src/serviceSchema.js

@@ -23,13 +23,18 @@
  *         options?: [{value, label}],   // enum / multiselect
  *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
  *         placeholder?, multiline?,     // string
- *         scope? }                      // field: 'Sentence' | 'Word' | 'Morpheme'
+ *         scope?, role? }               // field: 'Sentence' | 'Word' | 'Morpheme'
  *     ]
  *   }
  *
  * A `field` parameter names one of the project's annotation fields at its
  * `scope`. A UI that knows the project offers those fields to choose from; to
- * everything here, and to a UI that does not, it is a string.
+ * everything here, and to a UI that does not, it is a string. Its optional
+ * `role` names a lexicon role ("gloss") or, at Sentence scope, a sentence
+ * field's role ("translation", "literalTranslation", "note"): a UI that knows
+ * the project fills the parameter with the one field at `scope` whose stored
+ * Lexicon field holds that role, or whose stored role it is. A field is never
+ * chosen by its name.
  *
  * A parameter's `key` is a string VALUE, so it passes over the wire verbatim;
  * the UI sends `{ [param.key]: value }` in the request data. Declare each `key`
@@ -117,6 +122,9 @@ export const TASKS = Object.freeze({
  * @property {"Sentence" | "Word" | "Morpheme"} [scope] `field` only: the
  *   scope of the project's annotation fields the value names one of. A
  *   `field` value is a string everywhere else.
+ * @property {string} [role] `field` only: the lexicon role whose paired field,
+ *   or the sentence role whose field, fills the parameter when nothing else
+ *   does.
  */
 
 /**
@@ -255,6 +263,20 @@ export function buildDefaultValues(schema) {
  * @param {Record<string, any>} raw current form values
  * @returns {{values: Record<string, any>, errors: Record<string, string>}}
  */
+// A decimal number as a person types one: an optional sign, digits with an
+// optional fraction (or a bare fraction), an optional exponent, with spaces
+// around it allowed. ASCII whitespace only, as in Python (each language's \s
+// holds characters the other's lacks).
+const DECIMAL = /^[ \t\n\v\f\r]*[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?[ \t\n\v\f\r]*$/;
+
+/** `v` as a finite number when it is one or a decimal string, else null. */
+function numberOf(v) {
+  let n = null;
+  if (typeof v === "number") n = v;
+  else if (typeof v === "string" && DECIMAL.test(v)) n = Number(v);
+  return n !== null && Number.isFinite(n) ? n : null;
+}
+
 export function coerceParamValues(schema, raw) {
   const values = {};
   const errors = {};
@@ -267,19 +289,12 @@ export function coerceParamValues(schema, raw) {
 
     switch (param.type) {
       case "number": {
-        // Blank / nullish counts as "missing" → the param's default (matches the
-        // Python client, where float('') raises and falls back to the default).
-        let n;
-        if (
-          v === "" ||
-          v == null ||
-          (typeof v === "string" && v.trim() === "")
-        ) {
-          n = defaultForParam(param);
-        } else {
-          n = typeof v === "number" ? v : Number(v);
-          if (Number.isNaN(n)) n = defaultForParam(param);
-        }
+        // A finite number, or a string holding a decimal one; anything else
+        // (blank, a boolean, a list, hex, an underscore, Infinity, a value too
+        // large to be finite) is the param's default. The Python client's
+        // `coerce` reads the same rule.
+        let n = numberOf(v);
+        if (n === null) n = defaultForParam(param);
         if (typeof param.min === "number") n = Math.max(param.min, n);
         if (typeof param.max === "number") n = Math.min(param.max, n);
         v = n;

package/src/services.d.ts

@@ -38,12 +38,15 @@ export function serviceErrorMessage(error: any, serviceName?: string, secrets?:
  * it, as the caller sees it: `runnerName` (the runner's display name),
  * `runByYou`, and `servesYou`, whether it would take the caller's requests on
  * this project. A delegating service serves members other than its runner
- * only where the runner is a maintainer or an admin. Goes over the wire even
- * while a batch is open on the client.
+ * only where the runner is a maintainer or an admin. Every entry whose id an
+ * account holds gives its display name in `claimedByName`. An admin also gets
+ * the account in `claimedBy` (see `releaseService`), and an entry with
+ * `seen: false` for each held id whose registration was forgotten. Goes over
+ * the wire even while a batch is open on the client.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou}]
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou, claimedByName, claimedBy, seen}]
  */
 export function discoverServices(client: any, projectId: string): Promise<any[]>;
 /**
@@ -57,6 +60,20 @@ export function discoverServices(client: any, projectId: string): Promise<any[]>
  * @returns {Promise<void>}
  */
 export function discardService(client: any, projectId: string, serviceId: string): Promise<void>;
+/**
+ * Release a service id from the account that first registered it on the
+ * project. A service id belongs to that account, and the server refuses any
+ * other account's registration (403) until an admin releases it. The next
+ * account to register it then claims it. Deactivating the account releases
+ * every id it holds. Admin-only; 409 while the service is connected, 404 when
+ * no account holds it.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to release
+ * @returns {Promise<void>}
+ */
+export function releaseService(client: any, projectId: string, serviceId: string): Promise<void>;
 /**
  * POST a progress, result or error event for an in-flight request; the server
  * relays it to the waiting requester. The Python twin is `_report_event`.

package/src/services.js

@@ -37,9 +37,12 @@ export const UNKNOWN_OUTCOME =
 /** The server was never reached, so nothing was sent. */
 export const UNREACHABLE = 'The Plaid server could not be reached.';
 
-// A few reads travel as a POST, and saved nothing either way (the Python twin
-// and plaid-ui's errors.js keep the same list).
-const READ_POSTS = /\/api\/v1\/(?:query|login|invites\/lookup)(?:[?#]|$)/;
+// A few reads travel as a POST (a query, a token count, a layer rule check,
+// the values a rule would refuse, signing in, looking an invite up), and saved
+// nothing either way. The Python twin and plaid-ui's errors.js keep the same
+// list (readPosts.test.js holds the three equal).
+const READ_POSTS =
+  /\/api\/v1\/(?:query|query\/token-counts|login|invites\/lookup|(?:token|span|relation)-layers\/[^/?#]+\/constraints\/(?:check|refused-values))(?:[?#]|$)/;
 
 // Node's fetch (undici) names a connection that never opened by its code: a
 // refused port, a name that did not resolve, a connect timeout. Nothing was
@@ -136,12 +139,15 @@ export function serviceErrorMessage(error, serviceName = '', secrets = []) {
  * it, as the caller sees it: `runnerName` (the runner's display name),
  * `runByYou`, and `servesYou`, whether it would take the caller's requests on
  * this project. A delegating service serves members other than its runner
- * only where the runner is a maintainer or an admin. Goes over the wire even
- * while a batch is open on the client.
+ * only where the runner is a maintainer or an admin. Every entry whose id an
+ * account holds gives its display name in `claimedByName`. An admin also gets
+ * the account in `claimedBy` (see `releaseService`), and an entry with
+ * `seen: false` for each held id whose registration was forgotten. Goes over
+ * the wire even while a batch is open on the client.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
- * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou}]
+ * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt, runnerName, runByYou, servesYou, claimedByName, claimedBy, seen}]
  */
 export function discoverServices(client, projectId) {
   return client._request('GET', `/api/v1/projects/${projectId}/services`);
@@ -165,6 +171,27 @@ export function discardService(client, projectId, serviceId) {
   });
 }
 
+/**
+ * Release a service id from the account that first registered it on the
+ * project. A service id belongs to that account, and the server refuses any
+ * other account's registration (403) until an admin releases it. The next
+ * account to register it then claims it. Deactivating the account releases
+ * every id it holds. Admin-only; 409 while the service is connected, 404 when
+ * no account holds it.
+ *
+ * @param {Object} client - PlaidClient instance
+ * @param {string} projectId - Project UUID
+ * @param {string} serviceId - Service ID to release
+ * @returns {Promise<void>}
+ */
+export function releaseService(client, projectId, serviceId) {
+  // outOfBand: the registry is not project data (see the note at the top of
+  // http.js).
+  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(serviceId)}/owner`, {
+    outOfBand: true,
+  });
+}
+
 /**
  * POST a progress, result or error event for an in-flight request; the server
  * relays it to the waiting requester. The Python twin is `_report_event`.
@@ -430,7 +457,14 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
         // What reaches the requester is the sanitized half: the raw message
         // names the endpoint the client called, which is the operator's
         // business. The console keeps the whole error.
-        console.error(`Service ${serviceId} failed request ${requestId}:`, error);
+        // Somebody else holding the document is a refusal a service expects,
+        // which the lock acquire words itself (from the server's 423): one
+        // line, not the error and its cause.
+        if (error?.status === 423) {
+          console.error(`Service ${serviceId} failed request ${requestId}: ${error.message}`);
+        } else {
+          console.error(`Service ${serviceId} failed request ${requestId}:`, error);
+        }
         responseHelper.error(serviceErrorMessage(error, serviceName));
       }
     };
@@ -468,7 +502,10 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
       if (PERMANENT_STATUSES.has(status)) {
         noteDisconnected();
         serviceRegistration.stop();
-        report('stopped', `HTTP ${status}`);
+        // The server's reason when it gave one (a service id another
+        // account holds says whose it is).
+        const why = connection.error?.responseData?.error;
+        report('stopped', typeof why === 'string' ? `HTTP ${status}: ${why}` : `HTTP ${status}`);
         return;
       }
       noteDisconnected();

package/src/sse.js

@@ -145,8 +145,17 @@ export function createSSEConnection(client, projectId, onEvent, path) {
           // takes over.
           console.warn('Service registration rejected (409): another instance of this service is already connected; will retry');
         }
-        const refused = new Error(`HTTP ${response.status} ${response.statusText}`);
+        // A refusal says why in its body (`{error}`), as on every other route.
+        let said = null;
+        try {
+          said = await response.json();
+        } catch {
+          said = null;
+        }
+        const why = typeof said?.error === 'string' ? `: ${said.error}` : '';
+        const refused = new Error(`HTTP ${response.status} ${response.statusText}${why}`);
         refused.status = response.status;
+        if (said && typeof said === 'object') refused.responseData = said;
         throw refused;
       }
 

package/src/testing.d.ts

@@ -0,0 +1,128 @@
+/**
+ * A request as `answer` is asked it: the bundle call that made it (`kind` and
+ * `args`), and the request as the server reads it.
+ * @typedef {{kind?: string, args: any[], method: string, path: string,
+ *   query: Record<string, string>, body: any, batched: boolean}} FakeRequest
+ */
+/**
+ * A round trip as `requests` holds it and `onRequest` hears it: a request,
+ * or a batch request with its `operations`.
+ * @typedef {{method: string, path: string, query: Record<string, string>, body: any,
+ *   kind?: string, args?: any[], operations?: object[]}} RecordedRequest
+ */
+/**
+ * An error as the client throws it for a refusal: `status`, and the
+ * server's answer as `responseData`.
+ * @param {number} status
+ * @param {object} [responseData]
+ * @returns {Error & {status: number, responseData: object}}
+ */
+export function refusal(status: number, responseData?: object): Error & {
+    status: number;
+    responseData: object;
+};
+/**
+ * What a request is answered with when `answer` gives nothing: the id a
+ * create minted (or a new one), the ids of a bulk create, an empty page for a
+ * read, and `{}` for anything else.
+ * @param {{kind?: string, method: string, body?: any}} request
+ * @returns {object}
+ */
+export function defaultAnswer({ kind, method, body }: {
+    kind?: string;
+    method: string;
+    body?: any;
+}): object;
+/**
+ * A real PlaidClient on a recording transport (see the module's note).
+ *
+ * `answer(request)` answers each request, `request` being `{kind, args,
+ * method, path, query, body, batched}`: the bundle call that made it (`kind`
+ * and `args`, any batch refs in them filled in, undefined for a request no
+ * bundle call made), and the request as the server reads it. It returns the
+ * answer as the client hands it back (camelCase), or a promise of it, or
+ * undefined for `defaultAnswer`'s. To refuse, it throws (see `refusal`). A
+ * refusal of any op of a batch refuses the whole batch, as the server's
+ * transaction does.
+ *
+ * @param {{answer?: (request: FakeRequest) => any,
+ *   onRequest?: (request: RecordedRequest) => void, baseUrl?: string}} [options]
+ * @returns {PlaidClient & {calls: Array<{kind: string, args: any[]}>,
+ *   requests: RecordedRequest[], operations: Array<{message: string, kind?: string, ref?: string}>}}
+ */
+export function fakeClient({ answer, onRequest, baseUrl, }?: {
+    answer?: (request: FakeRequest) => any;
+    onRequest?: (request: RecordedRequest) => void;
+    baseUrl?: string;
+}): PlaidClient & {
+    calls: Array<{
+        kind: string;
+        args: any[];
+    }>;
+    requests: RecordedRequest[];
+    operations: Array<{
+        message: string;
+        kind?: string;
+        ref?: string;
+    }>;
+};
+/**
+ * Runs `f` and gives its value and the milliseconds it took. With `warm`,
+ * runs it that many times first, untimed, so the engine has compiled it.
+ * With `runs`, times that many runs and keeps the quickest, which a pause for
+ * garbage collection or another process touches least. Only for an `f` that
+ * can run again.
+ * @template T
+ * @param {() => T} f
+ * @param {{warm?: number, runs?: number}} [options]
+ * @returns {[T, number]}
+ */
+export function timed<T>(f: () => T, { warm, runs }?: {
+    warm?: number;
+    runs?: number;
+}): [T, number];
+/**
+ * Throws unless `bigMs` is under `factor` times `smallMs`, two cases timed on
+ * the same machine in the same run. A loaded runner slows both, so the bound
+ * holds where a fixed number of milliseconds fails. Pick the cases so that
+ * the fault the test guards against grows the ratio well past `factor`: a
+ * scan of every row per row goes from 10 to 100 when the big case is ten
+ * times the small one. `smallMs` counts as at least `floorMs` (default 1),
+ * so a case too quick to time cannot make the bound nothing.
+ * @param {number} factor
+ * @param {number} smallMs
+ * @param {number} bigMs
+ * @param {{floorMs?: number, label?: string}} [options]
+ * @returns {number} `bigMs`
+ */
+export function withinFactorOf(factor: number, smallMs: number, bigMs: number, { floorMs, label }?: {
+    floorMs?: number;
+    label?: string;
+}): number;
+/**
+ * A request as `answer` is asked it: the bundle call that made it (`kind` and
+ * `args`), and the request as the server reads it.
+ */
+export type FakeRequest = {
+    kind?: string;
+    args: any[];
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    body: any;
+    batched: boolean;
+};
+/**
+ * A round trip as `requests` holds it and `onRequest` hears it: a request,
+ * or a batch request with its `operations`.
+ */
+export type RecordedRequest = {
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    body: any;
+    kind?: string;
+    args?: any[];
+    operations?: object[];
+};
+import { PlaidClient } from "./client.js";