@recordtimelabel/core 0.3.2 → 0.4.0

package/src/protocol.js

@@ -0,0 +1,128 @@
+/**
+ * Platform-neutral acknowledgement contract for RecordTimeLabel operation
+ * envelopes. Keep this module free of app and transport dependencies so the
+ * gateway and every client classify partial acknowledgements identically.
+ */
+
+export const RECORD_TIMELABEL_OPERATION_RESULT_STATUSES = Object.freeze({
+  APPLIED: 'applied',
+  NOOP: 'noop',
+  REJECTED: 'rejected',
+  RETRYABLE: 'retryable'
+});
+
+const ALLOWED_OPERATION_RESULT_STATUSES = new Set(
+  Object.values(RECORD_TIMELABEL_OPERATION_RESULT_STATUSES)
+);
+
+const createCountMismatchError = (operations, results) => {
+  const error = new Error('operation_result_count_mismatch');
+  error.code = 'operation_result_count_mismatch';
+  error.operationCount = Array.isArray(operations) ? operations.length : null;
+  error.resultCount = Array.isArray(results) ? results.length : null;
+  return error;
+};
+
+const asObject = (value) => (
+  value && typeof value === 'object' && !Array.isArray(value) ? value : {}
+);
+
+const normalizeStatus = (result) => {
+  if (ALLOWED_OPERATION_RESULT_STATUSES.has(result.status)) {
+    return result.status;
+  }
+  if (result.applied === true) {
+    return RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.APPLIED;
+  }
+  if (result.retryable === true) {
+    return RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.RETRYABLE;
+  }
+  return RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.REJECTED;
+};
+
+const isSuccessfulEnvelope = (response) => {
+  if (!response || typeof response !== 'object' || Array.isArray(response)) return false;
+  if (
+    response.success === false ||
+    response.ok === false ||
+    response.error ||
+    response.code === 'error'
+  ) return false;
+  return response.success === true || response.ok === true || (
+    response.success === undefined && response.ok === undefined
+  );
+};
+
+/**
+ * Normalize one positional result for every submitted operation.
+ *
+ * Unknown result properties are retained for forward compatibility, while
+ * all contract fields below are replaced with their normalized values.
+ */
+export const normalizeRecordTimeLabelOperationResults = (operations, results) => {
+  if (!Array.isArray(operations) || !Array.isArray(results) || operations.length !== results.length) {
+    throw createCountMismatchError(operations, results);
+  }
+
+  return operations.map((rawOperation, index) => {
+    const operation = asObject(rawOperation);
+    const result = asObject(results[index]);
+    const status = normalizeStatus(result);
+    const operationId = result.operationId ?? result.id ?? operation.id ?? null;
+    const id = result.id ?? operationId;
+    const retryAfterMs = result.retryAfterMs;
+
+    return {
+      ...result,
+      operationId,
+      id,
+      type: result.type ?? operation.type ?? null,
+      applied: result.applied === true,
+      status,
+      retryable: status === RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.RETRYABLE,
+      reason: typeof result.reason === 'string' ? result.reason : null,
+      retryAfterMs: typeof retryAfterMs === 'number' && Number.isFinite(retryAfterMs) && retryAfterMs > 0
+        ? retryAfterMs
+        : null
+    };
+  });
+};
+
+/**
+ * Normalize a successful operation envelope. During the compatibility
+ * window, a successful legacy envelope with no operationResults property is
+ * treated as acknowledging every submitted operation.
+ */
+export const normalizeRecordTimeLabelEnvelopeResponse = (operations, response) => {
+  if (!Array.isArray(operations)) {
+    throw createCountMismatchError(operations, response?.operationResults);
+  }
+
+  const hasExplicitResults = Boolean(
+    response &&
+    typeof response === 'object' &&
+    Object.prototype.hasOwnProperty.call(response, 'operationResults')
+  );
+  if (hasExplicitResults) {
+    return normalizeRecordTimeLabelOperationResults(operations, response.operationResults);
+  }
+  if (!isSuccessfulEnvelope(response)) {
+    throw createCountMismatchError(operations, null);
+  }
+
+  return normalizeRecordTimeLabelOperationResults(
+    operations,
+    operations.map((operation) => ({
+      operationId: asObject(operation).id ?? null,
+      id: asObject(operation).id ?? null,
+      applied: true,
+      status: RECORD_TIMELABEL_OPERATION_RESULT_STATUSES.APPLIED
+    }))
+  );
+};
+
+export default {
+  RECORD_TIMELABEL_OPERATION_RESULT_STATUSES,
+  normalizeRecordTimeLabelOperationResults,
+  normalizeRecordTimeLabelEnvelopeResponse
+};