@larc-iu/plaid-client 0.2.0-alpha.14 → 0.2.0-alpha.16

package/src/pagination.js

@@ -11,10 +11,9 @@
  * headers, base URL, and response transforms all apply exactly as for any
  * other request.
  *
- * A page is a read, so every request these helpers make carries `bypassBatch`
- * (see the three classes at the top of http.js). That is what lets them work
- * while a batch is open on the same client: each page is answered from the
- * pool, in order, against the state the batch has not committed yet.
+ * A page is a read, so it goes over the wire even when the helper is handed a
+ * batch (see the note at the top of http.js): each page is answered from the
+ * pool, in order, against the state no batch has committed yet.
  */
 
 // Merge caller query params with paging params, dropping undefined/null so we
@@ -57,7 +56,6 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
-      bypassBatch: true,
     });
     all.push(...entriesOf(response, path));
     prevCursor = cursor;
@@ -87,7 +85,6 @@ export async function listAll(client, path, { pageSize = 1000, query = {} } = {}
 export async function listPage(client, path, { limit, cursor, query = {} } = {}) {
   return client._request('GET', path, {
     queryParams: buildQueryParams(query, limit, cursor),
-    bypassBatch: true,
   });
 }
 
@@ -108,7 +105,6 @@ export async function* iterPages(client, path, { pageSize = 1000, query = {} } =
   do {
     const response = await client._request('GET', path, {
       queryParams: buildQueryParams(query, pageSize, cursor),
-      bypassBatch: true,
     });
     const entries = entriesOf(response, path);
     // Suppress the trailing empty page that the server emits when a collection's

package/src/serviceSchema.js

@@ -22,10 +22,15 @@
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
  *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
- *         placeholder?, multiline? }    // string
+ *         placeholder?, multiline?,     // string
+ *         scope? }                      // 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.
+ *
  * 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`
  * in your service's own convention (Python: snake_case; JS: camelCase) and read
@@ -50,6 +55,20 @@ export const TASKS = Object.freeze({
   LINK_VOCAB: "link-vocab",
   /** Propose an interlinear analysis (morpheme segmentation + glosses) for words. */
   ANALYZE: "analyze",
+  /**
+   * Draft a meaning representation graph over the sentences of a document,
+   * for correction by hand. The request names a `scope` ('document' or
+   * 'sentence'), a `sentence` number when the scope is one sentence, and
+   * `overwrite`. See plaid-umr's drafting services.
+   *
+   * Apart from `analyze` on purpose. A task is the CONTRACT a spot offers a
+   * service against, and these two share almost none of it: an analyze
+   * request names the three token layers plus the language, metalanguage and
+   * orthography, and writes morphemes and glosses. Both claimed `analyze` for
+   * a while, so every app offering an analyze spot offered the other app's
+   * services, which could not answer the request they would have been given.
+   */
+  DRAFT_GRAPH: "draft-graph",
   /** Propose a free translation for each sentence. */
   TRANSLATE: "translate",
   /**
@@ -64,6 +83,13 @@ export const TASKS = Object.freeze({
   DETECT_SPEECH: "detect-speech",
   /** A conversational assistant over a project (chat turns; see plaid-agent). */
   ASSIST: "assist",
+  /**
+   * Score one document's annotation against another document's of the same
+   * text (two annotators' copies), writing a report on the scored document's
+   * metadata and never an annotation. The request names the other document
+   * as `against`. See plaid-umr's AnCast service.
+   */
+  COMPARE: "compare",
 });
 
 /**

package/src/services.js

@@ -92,14 +92,7 @@ export function serviceErrorMessage(error, serviceName = '', secrets = []) {
  * @returns {Promise<Array>} [{serviceId, serviceName, description, extras, online, lastSeenAt}]
  */
 export function discoverServices(client, projectId) {
-  // bypassBatch: the registry is read by whoever asked, not by whatever batch
-  // happens to be open on this shared client. The assistant's availability
-  // probe polls for 49 seconds after a mount and landed inside a Grew rewrite
-  // or an import, where the answer was `{batched: true}`, cached as the
-  // service list, and every later render threw on it until a reload.
-  return client._request('GET', `/api/v1/projects/${projectId}/services`, {
-    bypassBatch: true,
-  });
+  return client._request('GET', `/api/v1/projects/${projectId}/services`);
 }
 
 /**
@@ -113,17 +106,21 @@ export function discoverServices(client, projectId) {
  * @returns {Promise<void>}
  */
 export function discardService(client, projectId, serviceId) {
-  return client._request('DELETE', `/api/v1/projects/${projectId}/services/${encodeURIComponent(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)}`, {
+    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`.
  *
- * bypassBatch: these are out-of-band signals to whoever is waiting, not writes
- * to the project. A service reports them from inside its own
- * `client.batched()` block, where queueing them would hold every one back
- * until submit, deliver none at all if the batch aborts, and take slots in the
+ * outOfBand: these are signals to whoever is waiting, not writes to the
+ * project (see the note at the top of http.js). A service may report them on
+ * the batch it is filling, where queueing them would hold every one back until
+ * submit, deliver none at all if the batch aborts, and take slots in the
  * batch's results. The requester would hear nothing and wait out its idle
  * timeout on work that had already finished.
  *
@@ -137,7 +134,7 @@ export function reportRequestEvent(client, projectId, requestId, body) {
   return client._request(
     'POST',
     `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}/events`,
-    { body, bypassBatch: true },
+    { body, outOfBand: true },
   );
 }
 
@@ -487,13 +484,8 @@ export function createCancelScope(isCancelled) {
  * still ends with whatever the service then reports, on the stream of whoever
  * is awaiting it. Rejects with 404 if unknown or expired, 409 once finished.
  *
- * Goes over the wire even while a batch is open on the client. A DELETE, but
- * not a write: it signals a running service out of band and changes no project
- * data. The Stop button lives in the app's chrome, on the same client an
- * import or a bulk edit is batching on, and a stop that waits for that batch to
- * submit has stopped nothing (and if the batch aborts, it never arrives at
- * all), while the queued DELETE shifts every result index the batch's caller
- * reads back.
+ * outOfBand: a DELETE, but not a write. It signals a running service and
+ * changes no project data (see the note at the top of http.js).
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
@@ -504,7 +496,7 @@ export function cancelServiceRequest(client, projectId, requestId) {
   return client._request(
     'DELETE',
     `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`,
-    { bypassBatch: true },
+    { outOfBand: true },
   );
 }