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

package/src/ids.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A fresh UUIDv7, later than every one this page minted before it.
+ * @returns {string}
+ */
+export function uuidv7(): string;
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4(): string;
+/**
+ * A user id as the server stores it. A user's id is their email address,
+ * trimmed of every whitespace, control and format character at either end
+ * and lowercased, in NFC before and after (a capital with no composed form,
+ * such as J̌, lowercases to one that has one, ǰ), so `Ana@Example.org` and
+ * `ana@example.org` name one account. Compare a typed address with an id
+ * through this. The rule is core's (`plaid.sql.user/normalize-id`), checked
+ * against its case table.
+ * Anything but a string comes back unchanged.
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizeUserId(id: string): string;

package/src/ids.js

@@ -0,0 +1,96 @@
+/**
+ * Ids a client mints for what it creates.
+ *
+ * A create may name the id of the row it makes, so a create sent again after
+ * its answer was lost lands under the same id or is told the id is taken
+ * (409 with `id-taken`). The server takes only a UUIDv7 (RFC 9562), shaped
+ * as its own ids are: a 48-bit millisecond timestamp, a 12-bit counter
+ * within the millisecond, then 62 random bits. Reads are id-ordered, so ids
+ * minted in one millisecond must still sort in the order they were made.
+ */
+
+let lastMs = 0;
+let counter = 0;
+
+const hex = Array.from({ length: 256 }, (_, i) =>
+  i.toString(16).padStart(2, "0"),
+);
+
+/**
+ * A fresh UUIDv7, later than every one this page minted before it.
+ * @returns {string}
+ */
+export function uuidv7() {
+  const now = Date.now();
+  if (now > lastMs) {
+    lastMs = now;
+    counter = 0;
+  } else if (counter < 0xfff) {
+    counter += 1;
+  } else {
+    // This millisecond is full: take the next one rather than repeat an order.
+    lastMs += 1;
+    counter = 0;
+  }
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  const high = Math.floor(lastMs / 0x100000000);
+  const low = lastMs >>> 0;
+  b[0] = (high >>> 8) & 0xff;
+  b[1] = high & 0xff;
+  b[2] = (low >>> 24) & 0xff;
+  b[3] = (low >>> 16) & 0xff;
+  b[4] = (low >>> 8) & 0xff;
+  b[5] = low & 0xff;
+  b[6] = 0x70 | (counter >>> 8);
+  b[7] = counter & 0xff;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  let s = "";
+  for (let i = 0; i < 16; i++) {
+    s += hex[b[i]];
+    if (i === 3 || i === 5 || i === 7 || i === 9) s += "-";
+  }
+  return s;
+}
+
+/**
+ * A random UUIDv4, for ids that need no order (an operation group, a lock
+ * holder). Built on `crypto.getRandomValues`, since `crypto.randomUUID`
+ * exists only in a secure context and a page served over plain HTTP from
+ * another host than localhost is not one.
+ * @returns {string}
+ */
+export function uuidv4() {
+  const b = new Uint8Array(16);
+  crypto.getRandomValues(b);
+  b[6] = (b[6] & 0x0f) | 0x40;
+  b[8] = (b[8] & 0x3f) | 0x80;
+  let s = "";
+  for (let i = 0; i < 16; i++) {
+    s += hex[b[i]];
+    if (i === 3 || i === 5 || i === 7 || i === 9) s += "-";
+  }
+  return s;
+}
+
+// Whitespace, control and format characters at either end of an id (NBSP,
+// the BOM, zero-width and bidi marks as well as ASCII blanks), as core trims.
+const ID_EDGES = /^[\p{Z}\p{Cc}\p{Cf}]+|[\p{Z}\p{Cc}\p{Cf}]+$/gu;
+
+/**
+ * A user id as the server stores it. A user's id is their email address,
+ * trimmed of every whitespace, control and format character at either end
+ * and lowercased, in NFC before and after (a capital with no composed form,
+ * such as J̌, lowercases to one that has one, ǰ), so `Ana@Example.org` and
+ * `ana@example.org` name one account. Compare a typed address with an id
+ * through this. The rule is core's (`plaid.sql.user/normalize-id`), checked
+ * against its case table.
+ * Anything but a string comes back unchanged.
+ * @param {string} id
+ * @returns {string}
+ */
+export function normalizeUserId(id) {
+  return typeof id === "string"
+    ? id.normalize("NFC").replace(ID_EDGES, "").toLowerCase().normalize("NFC")
+    : id;
+}

package/src/index.d.ts

@@ -0,0 +1,101 @@
+export default PlaidClient;
+export { PlaidClient };
+export { BACKUP_TIMEOUT_MS } from "./apiServer.js";
+export { wasReplayed } from "./replayed.js";
+export { MAX_BATCH_OPS } from "./batch.js";
+export type TextEditOp = import("./types.js").TextEditOp;
+export type TextGap = import("./types.js").TextGap;
+export type MetadataOp = import("./types.js").MetadataOp;
+export type LayerConstraint = import("./types.js").LayerConstraint;
+export type ConstraintWriteOptions = import("./types.js").ConstraintWriteOptions;
+export type ConstraintViolation = import("./types.js").ConstraintViolation;
+export type Requester = import("./types.js").Requester;
+export type BatchRef = import("./types.js").BatchRef;
+export type ServiceParam = import("./types.js").ServiceParam;
+export type ServiceInfo = import("./types.js").ServiceInfo;
+export type DiscoveredService = import("./types.js").DiscoveredService;
+export type ResponseHelper = import("./types.js").ResponseHelper;
+export type ServiceRegistration = import("./types.js").ServiceRegistration;
+export type ServiceStatusEvent = import("./types.js").ServiceStatusEvent;
+export type OperationGroupsBundle = import("./types.js").OperationGroupsBundle;
+export type PlaidClientOptions = import("./types.js").PlaidClientOptions;
+export type OperationKind = import("./types.js").OperationKind;
+export type KeySeed = import("./types.js").KeySeed;
+export type PlaidBatch = import("./types.js").PlaidBatch;
+export type AuditPageOptions = import("./types.js").AuditPageOptions;
+export type VocabItemRestoreSummary = import("./types.js").VocabItemRestoreSummary;
+export type UserDataEntry = import("./types.js").UserDataEntry;
+export type AdminUserDataEntry = import("./types.js").AdminUserDataEntry;
+export type ActivityTallyRow = import("./types.js").ActivityTallyRow;
+export type ConstraintRepair = import("./types.js").ConstraintRepair;
+export type ValueSetRule = import("./types.js").ValueSetRule;
+export type RefusedValues = import("./types.js").RefusedValues;
+export type CommentableType = import("./types.js").CommentableType;
+export type Comment = import("./types.js").Comment;
+export type Guideline = import("./types.js").Guideline;
+export type ClientEventType = import("./types.js").ClientEventType;
+export type ClientEvent = import("./types.js").ClientEvent;
+export type Invite = import("./types.js").Invite;
+export type ServerLimits = import("./types.js").ServerLimits;
+export type ServerHealth = import("./types.js").ServerHealth;
+export type RateLimitBucket = import("./types.js").RateLimitBucket;
+export type RateLimitSnapshot = import("./types.js").RateLimitSnapshot;
+export type BackupStatus = import("./types.js").BackupStatus;
+export type ServerReport = import("./types.js").ServerReport;
+export type LiveLog = import("./types.js").LiveLog;
+export type SSEConnection = import("./types.js").SSEConnection;
+export type SSEStats = import("./types.js").SSEStats;
+export type AtomicValue = import("./types.js").AtomicValue;
+export type Created = import("./types.js").Created;
+export type Project = import("./types.js").Project;
+export type ProjectTextLayer = import("./types.js").ProjectTextLayer;
+export type ProjectTokenLayer = import("./types.js").ProjectTokenLayer;
+export type ProjectSpanLayer = import("./types.js").ProjectSpanLayer;
+export type ProjectRelationLayer = import("./types.js").ProjectRelationLayer;
+export type ProjectVocab = import("./types.js").ProjectVocab;
+export type PlaidDocument = import("./types.js").PlaidDocument;
+export type DocumentTextLayer = import("./types.js").DocumentTextLayer;
+export type DocumentTokenLayer = import("./types.js").DocumentTokenLayer;
+export type DocumentSpanLayer = import("./types.js").DocumentSpanLayer;
+export type PlaidText = import("./types.js").PlaidText;
+export type TextReshape = import("./types.js").TextReshape;
+export type Token = import("./types.js").Token;
+export type Span = import("./types.js").Span;
+export type Relation = import("./types.js").Relation;
+export type VocabItem = import("./types.js").VocabItem;
+export type VocabLink = import("./types.js").VocabLink;
+export type VocabLayer = import("./types.js").VocabLayer;
+export type TextLayer = import("./types.js").TextLayer;
+export type TokenLayer = import("./types.js").TokenLayer;
+export type SpanLayer = import("./types.js").SpanLayer;
+export type RelationLayer = import("./types.js").RelationLayer;
+export type MetadataRecords = import("./types.js").MetadataRecords;
+export type LayerRecords = import("./types.js").LayerRecords;
+export type User = import("./types.js").User;
+export type ProjectListEntry = import("./types.js").ProjectListEntry;
+export type DocumentListEntry = import("./types.js").DocumentListEntry;
+export type ApiToken = import("./types.js").ApiToken;
+export type AuditUser = import("./types.js").AuditUser;
+export type AuditTarget = import("./types.js").AuditTarget;
+export type AuditOp = import("./types.js").AuditOp;
+export type AuditEntry = import("./types.js").AuditEntry;
+export type LockGrant = import("./types.js").LockGrant;
+export type DocumentRestoreSummary = import("./types.js").DocumentRestoreSummary;
+export type RestoreCounts = import("./types.js").RestoreCounts;
+export type OperationGroup = import("./types.js").OperationGroup;
+export type QueryResult = import("./types.js").QueryResult;
+export type Page<T = any> = import("./types.js").Page<T>;
+import { PlaidClient } from "./client.js";
+export { valueSetAllows, violationCountOf, violationsOf } from "./constraints.js";
+export { cpLength, cpSlice, cpSlicer, utf16ToCp, cpIndexOf, composeText } from "./codepoint.js";
+export { composeTextEdits, gapsToOps, applyTextOps } from "./textEdits.js";
+export { PLAID_NAMESPACE, ROLE_KEY, PRESERVE_ON_SPLIT_KEY, SPLIT_ON_SPACE_KEY, IGNORED_TOKENS_KEY, TARTAN_KEY, RESEARCH_KEY, readResearchTelemetry, ROLES, readRole, readIgnoredTokens, findByRole } from "./roles.js";
+export { TASKS, servesTask, filterServicesByTask, getParamSchema, getServiceSummary, buildDefaultValues, coerceParamValues } from "./serviceSchema.js";
+export { ServiceCancelled, createCancelScope, UNKNOWN_OUTCOME, UNREACHABLE } from "./services.js";
+export { REQUESTED_BY, makeRequester, requesterOf } from "./requester.js";
+export { DocumentLock, DocumentLockLost } from "./documentLock.js";
+export { PROV, PROV_STATES, PROVENANCE_KEYS, stampInferred, confirmedInferred, stampContributed, provState, provOrigin, isMachine, isProtected, needsReview, contributeOnEdit, serviceSource, REVIEW_KEY, readReview, reviewsAnyone, projectRole, isReviewed, withReviewedUser, CONFIDENCE_KEY, DEFAULT_CONFIDENCE_THRESHOLD, readConfidenceThreshold, machineProb, isDoubtful, VALUE_PROBS_KEY, FORM_PROBS_KEY, readValueProbs, writerPolicy } from "./provenance.js";
+export { MORPH_TYPES, entryForm, readAffixMarkers, decorateWithAffixMarkers } from "./entryForms.js";
+export { metadataOps, applyMetadataOps, mergeMetadata, isReservedMetadataKey } from "./metadataOps.js";
+export { createdId, createdIds } from "./created.js";
+export { uuidv4, uuidv7, normalizeUserId } from "./ids.js";