@form-engine-ts/core 2.3.0 → 2.5.1

package/dist/index.js

@@ -1042,6 +1042,188 @@ function aggregateResponses(schema, submissions) {
     questions: schema.fields.map((field) => aggregateField(schema, field, submissions))
   };
 }
+function responseValues(submission) {
+  if (typeof submission !== "object" || submission === null) return void 0;
+  if ("values" in submission) return submission.values;
+  return "answers" in submission ? submission.answers : void 0;
+}
+function responseIdentifier(submission) {
+  if (typeof submission !== "object" || submission === null) return "<unknown>";
+  if ("id" in submission && typeof submission.id === "string" && submission.id.length > 0) return submission.id;
+  if ("responseId" in submission && typeof submission.responseId === "string" && submission.responseId.length > 0) {
+    return submission.responseId;
+  }
+  return "<unknown>";
+}
+function isAnswerRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function responseProblem(schema, submission) {
+  if (typeof submission !== "object" || submission === null) {
+    return { reason: "invalid_structure", error: "Submission structure is invalid." };
+  }
+  const identifier = responseIdentifier(submission);
+  const values = responseValues(submission);
+  if (typeof identifier !== "string" || identifier.length === 0 || typeof submission.formId !== "string" || typeof submission.submittedAt !== "string" || !isAnswerRecord(values)) {
+    return { reason: "invalid_structure", error: `Submission ${String(identifier)} structure is invalid.` };
+  }
+  if (submission.formId !== schema.id) {
+    return { reason: "form_id_mismatch", error: `Submission ${identifier} does not match form ${schema.id}.` };
+  }
+  if ("formVersion" in submission && submission.formVersion !== void 0 && submission.formVersion !== schema.version) {
+    return {
+      reason: "version_mismatch",
+      error: `Submission ${identifier} does not match ${schema.id}@${schema.version}.`
+    };
+  }
+  return void 0;
+}
+var IncrementalResponseAccumulator = class _IncrementalResponseAccumulator {
+  #schema;
+  #mode;
+  #fields;
+  #skipReasons = [];
+  #submissionCount = 0;
+  constructor(schema, options) {
+    assertValidFormSchema(schema);
+    this.#schema = JSON.parse(JSON.stringify(schema));
+    this.#mode = options.mode ?? "strict";
+    this.#fields = new Map(
+      schema.fields.map((field) => [
+        field.id,
+        {
+          answeredCount: 0,
+          total: 0,
+          minimum: null,
+          maximum: null,
+          trueCount: 0,
+          falseCount: 0,
+          optionCounts: new Map("options" in field ? field.options.map((option) => [option.id, 0]) : [])
+        }
+      ])
+    );
+  }
+  add(submission) {
+    const problem = responseProblem(this.#schema, submission);
+    if (problem !== void 0) {
+      if (this.#mode === "strict") return { success: false, error: problem.error };
+      this.#skipReasons.push({ responseId: responseIdentifier(submission), reason: problem.reason });
+      return { success: true, skipped: true };
+    }
+    const values = responseValues(submission);
+    if (!isAnswerRecord(values)) throw new Error("Validated response answers are unavailable.");
+    const visibility = calculateFieldVisibility(this.#schema, values);
+    for (const field of this.#schema.fields) {
+      const accumulator = this.#fields.get(field.id);
+      if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+      const candidate = values[field.id];
+      if (visibility[field.id] !== true || !valueIsValid(field, candidate)) continue;
+      accumulator.answeredCount += 1;
+      if ((field.type === "number" || field.type === "rating") && typeof candidate === "number") {
+        accumulator.total += candidate;
+        accumulator.minimum = accumulator.minimum === null ? candidate : Math.min(accumulator.minimum, candidate);
+        accumulator.maximum = accumulator.maximum === null ? candidate : Math.max(accumulator.maximum, candidate);
+      } else if (field.type === "checkbox") {
+        if (candidate === true) accumulator.trueCount += 1;
+        if (candidate === false) accumulator.falseCount += 1;
+      } else if ("options" in field) {
+        const selections = Array.isArray(candidate) ? candidate : typeof candidate === "string" ? [candidate] : [];
+        for (const selection of selections) {
+          accumulator.optionCounts.set(selection, (accumulator.optionCounts.get(selection) ?? 0) + 1);
+        }
+      }
+    }
+    this.#submissionCount += 1;
+    return { success: true };
+  }
+  addMany(submissions) {
+    for (const submission of submissions) {
+      const result = this.add(submission);
+      if (!result.success) throw new TypeError(result.error ?? "Submission could not be accumulated.");
+    }
+    return this.getReport();
+  }
+  merge(other) {
+    if (!(other instanceof _IncrementalResponseAccumulator)) {
+      throw new TypeError("Only form-engine response accumulators can be merged.");
+    }
+    if (other.#schema.id !== this.#schema.id || other.#schema.version !== this.#schema.version || JSON.stringify(other.#schema.fields) !== JSON.stringify(this.#schema.fields)) {
+      throw new TypeError("Response accumulators must use the same schema.");
+    }
+    this.#submissionCount += other.#submissionCount;
+    this.#skipReasons.push(...other.#skipReasons);
+    for (const [fieldId, source] of other.#fields) {
+      const target = this.#fields.get(fieldId);
+      if (target === void 0) throw new Error(`Accumulator for ${fieldId} is unavailable.`);
+      target.answeredCount += source.answeredCount;
+      target.total += source.total;
+      target.minimum = target.minimum === null ? source.minimum : source.minimum === null ? target.minimum : Math.min(target.minimum, source.minimum);
+      target.maximum = target.maximum === null ? source.maximum : source.maximum === null ? target.maximum : Math.max(target.maximum, source.maximum);
+      target.trueCount += source.trueCount;
+      target.falseCount += source.falseCount;
+      for (const [optionId, count] of source.optionCounts) {
+        target.optionCounts.set(optionId, (target.optionCounts.get(optionId) ?? 0) + count);
+      }
+    }
+    return this;
+  }
+  getReport() {
+    return {
+      processedCount: this.#submissionCount,
+      skippedCount: this.#skipReasons.length,
+      skipReasons: this.#skipReasons.map((reason) => ({ ...reason }))
+    };
+  }
+  finalize() {
+    return {
+      formId: this.#schema.id,
+      formVersion: this.#schema.version,
+      submissionCount: this.#submissionCount,
+      questions: this.#schema.fields.map((field) => {
+        const accumulator = this.#fields.get(field.id);
+        if (accumulator === void 0) throw new Error(`Accumulator for ${field.id} is unavailable.`);
+        const base = {
+          fieldId: field.id,
+          answeredCount: accumulator.answeredCount,
+          unansweredCount: this.#submissionCount - accumulator.answeredCount
+        };
+        if (field.type === "text" || field.type === "textarea") return { ...base, kind: field.type };
+        if (field.type === "number" || field.type === "rating") {
+          return {
+            ...base,
+            kind: field.type,
+            minimum: accumulator.minimum,
+            maximum: accumulator.maximum,
+            average: accumulator.answeredCount === 0 ? null : accumulator.total / accumulator.answeredCount,
+            total: accumulator.total
+          };
+        }
+        if (field.type === "checkbox") {
+          return {
+            ...base,
+            kind: "checkbox",
+            trueCount: accumulator.trueCount,
+            falseCount: accumulator.falseCount,
+            truePercentageOfSubmissions: percentage(accumulator.trueCount, this.#submissionCount),
+            falsePercentageOfSubmissions: percentage(accumulator.falseCount, this.#submissionCount)
+          };
+        }
+        if (!("options" in field)) throw new TypeError(`Field ${field.id} cannot be aggregated.`);
+        return {
+          ...base,
+          kind: field.type,
+          options: field.options.map((option) => {
+            const count = accumulator.optionCounts.get(option.id) ?? 0;
+            return { id: option.id, count, percentageOfSubmissions: percentage(count, this.#submissionCount) };
+          })
+        };
+      })
+    };
+  }
+};
+function createResponseAccumulator(schema, options = {}) {
+  return new IncrementalResponseAccumulator(schema, options);
+}
 function escapeCsvCell(value, neutralizeFormulas = true) {
   if (value === null || value === void 0) return "";
   let stringValue = String(value);
@@ -1057,6 +1239,105 @@ function serializeValue(value) {
   if (value === void 0) return "";
   return typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value);
 }
+function asFormResponse(submission) {
+  if (!("values" in submission)) return submission;
+  return {
+    responseId: submission.id,
+    formId: submission.formId,
+    sourceLocale: submission.locale,
+    formVersion: submission.formVersion,
+    answers: submission.values,
+    submittedAt: submission.submittedAt,
+    ...submission.metadata === void 0 ? {} : { metadata: submission.metadata },
+    ...submission.translationMetadata === void 0 ? {} : { translationMetadata: submission.translationMetadata }
+  };
+}
+function serializeUnknown(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  return JSON.stringify(value);
+}
+async function* exportResponsesToCsvStream(schema, submissions, options = {}) {
+  assertValidFormSchema(schema);
+  const includeDefaultColumns = options.includeDefaultColumns ?? true;
+  const customColumns = options.columns ?? [];
+  const headers = [
+    ...includeDefaultColumns ? ["submissionId", "submittedAt", "locale", ...schema.fields.map((field) => field.id)] : [],
+    ...customColumns.map((column) => column.header)
+  ];
+  const neutralizeFormulas = options.neutralizeFormulas ?? true;
+  const header = headers.map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",");
+  yield `${options.withBom ?? true ? "\uFEFF" : ""}${header}`;
+  for await (const submission of submissions) {
+    const problem = responseProblem(schema, submission);
+    if (problem !== void 0) throw new TypeError(problem.error);
+    const response = asFormResponse(submission);
+    const answers = response.answers;
+    const visible = selectVisibleAnswers(schema, answers);
+    const defaultCells = includeDefaultColumns ? [
+      response.responseId,
+      response.submittedAt,
+      response.sourceLocale ?? "",
+      ...schema.fields.map((field) => serializeUnknown(visible[field.id]))
+    ] : [];
+    const context = {
+      ...response,
+      submission: response,
+      formVersion: response.formVersion ?? schema.version,
+      schema
+    };
+    const customCells = customColumns.map((column) => column.getValue(context));
+    yield `\r
+${[...defaultCells, ...customCells].map((value) => escapeCsvCell(value, neutralizeFormulas)).join(",")}`;
+  }
+}
+function isWebWritableStream(writable) {
+  return "getWriter" in writable && typeof writable.getWriter === "function";
+}
+async function writeNodeChunk(writable, chunk, streamError) {
+  if (writable.write(chunk)) return;
+  let onDrain;
+  const drain = new Promise((resolve) => {
+    onDrain = resolve;
+    writable.once("drain", resolve);
+  });
+  try {
+    await Promise.race([drain, streamError]);
+  } finally {
+    if (onDrain !== void 0) writable.removeListener("drain", onDrain);
+  }
+}
+async function pipeResponsesToCsvStream(schema, submissions, writable, options = {}) {
+  const encoder = new TextEncoder();
+  if (isWebWritableStream(writable)) {
+    const writer = writable.getWriter();
+    try {
+      for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+        await writer.write(encoder.encode(chunk));
+      }
+      await writer.close();
+    } catch (cause) {
+      await writer.abort(cause);
+      throw cause;
+    } finally {
+      writer.releaseLock();
+    }
+    return;
+  }
+  let onStreamError;
+  const streamError = new Promise((_resolve, reject) => {
+    onStreamError = reject;
+    writable.once("error", reject);
+  });
+  try {
+    for await (const chunk of exportResponsesToCsvStream(schema, submissions, options)) {
+      await writeNodeChunk(writable, encoder.encode(chunk), streamError);
+    }
+    await Promise.race([new Promise((resolve) => writable.end(resolve)), streamError]);
+  } finally {
+    if (onStreamError !== void 0) writable.removeListener("error", onStreamError);
+  }
+}
 function exportResponsesToCsv(schema, responses, options = {}) {
   assertValidFormSchema(schema);
   for (const response of responses) {
@@ -1174,6 +1455,87 @@ function transformFieldType(field, nextType) {
   return { ...common, type: nextType, options };
 }
 
+// src/pagination.ts
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function encodeBase64(bytes) {
+  let result = "";
+  for (let index = 0; index < bytes.length; index += 3) {
+    const first = bytes[index] ?? 0;
+    const second = bytes[index + 1] ?? 0;
+    const third = bytes[index + 2] ?? 0;
+    const combined = first << 16 | second << 8 | third;
+    result += BASE64_ALPHABET[combined >> 18 & 63] ?? "";
+    result += BASE64_ALPHABET[combined >> 12 & 63] ?? "";
+    result += index + 1 < bytes.length ? BASE64_ALPHABET[combined >> 6 & 63] ?? "" : "=";
+    result += index + 2 < bytes.length ? BASE64_ALPHABET[combined & 63] ?? "" : "=";
+  }
+  return result;
+}
+function decodeBase64(value) {
+  if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)) {
+    throw new TypeError("cursor must be a valid Base64 token.");
+  }
+  const bytes = [];
+  for (let index = 0; index < value.length; index += 4) {
+    const characters = value.slice(index, index + 4);
+    const sextets = [...characters].map((character) => character === "=" ? 0 : BASE64_ALPHABET.indexOf(character));
+    const combined = (sextets[0] ?? 0) << 18 | (sextets[1] ?? 0) << 12 | (sextets[2] ?? 0) << 6 | (sextets[3] ?? 0);
+    bytes.push(combined >> 16 & 255);
+    if (characters[2] !== "=") bytes.push(combined >> 8 & 255);
+    if (characters[3] !== "=") bytes.push(combined & 255);
+  }
+  return new Uint8Array(bytes);
+}
+function encodeSubmissionCursor(value) {
+  if (value.submittedAt.length === 0 || value.responseId.length === 0) {
+    throw new TypeError("Cursor values must not be empty.");
+  }
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeSubmissionCursor(cursor) {
+  try {
+    const parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (typeof parsed !== "object" || parsed === null || !("submittedAt" in parsed) || typeof parsed.submittedAt !== "string" || parsed.submittedAt.length === 0 || !("responseId" in parsed) || typeof parsed.responseId !== "string" || parsed.responseId.length === 0) {
+      throw new TypeError("cursor payload is invalid.");
+    }
+    return { submittedAt: parsed.submittedAt, responseId: parsed.responseId };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid form-engine cursor.", { cause });
+  }
+}
+function normalizeSubmissionPageSize(pageSize, fallback = 100) {
+  const value = pageSize ?? fallback;
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("pageSize must be a positive safe integer.");
+  return value;
+}
+function isJsonArray(value) {
+  return Array.isArray(value);
+}
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !isJsonArray(value);
+}
+function jsonValuesEqual(left, right) {
+  if (left === right) return true;
+  if (left === void 0 || left === null || right === void 0 || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (isJsonArray(left) || isJsonArray(right)) {
+    return isJsonArray(left) && isJsonArray(right) && left.length === right.length && left.every((value, index) => jsonValuesEqual(value, right[index]));
+  }
+  if (!isJsonObject(left) || !isJsonObject(right)) return false;
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length && leftKeys.every((key) => Object.hasOwn(right, key) && jsonValuesEqual(left[key], right[key]));
+}
+function matchesSubmissionPageFilters(submission, options) {
+  if (options.filter !== void 0 && !options.filter(submission)) return false;
+  if (options.metadataFilters === void 0) return true;
+  return Object.entries(options.metadataFilters).every(
+    ([key, value]) => jsonValuesEqual(submission.metadata?.[key], value)
+  );
+}
+
 // src/validation.ts
 var DEFAULT_MESSAGES = {
   required: "validation.required",
@@ -1609,22 +1971,160 @@ async function resolveFormTranslation(schema, adapter, targetLocale, sourceLocal
   );
   return resolveLocalizedSchema(populated.schema, targetLocale);
 }
+
+// src/versioning.ts
+function revisionConflict(state, expectedRevision) {
+  return expectedRevision === void 0 || expectedRevision === state.revision ? void 0 : {
+    success: false,
+    error: { type: "revision_conflict", expectedRevision, actualRevision: state.revision }
+  };
+}
+function validateState(state) {
+  if (state.formId.trim().length === 0) throw new TypeError("formId must not be empty.");
+  if (!Number.isSafeInteger(state.nextVersion) || state.nextVersion < 1) {
+    throw new TypeError("nextVersion must be a positive safe integer.");
+  }
+  if (!Number.isSafeInteger(state.revision) || state.revision < 0) {
+    throw new TypeError("revision must be a non-negative safe integer.");
+  }
+}
+function cloneVersionToDraft(state, sourceSchema, options = {}) {
+  validateState(state);
+  if (sourceSchema.id !== state.formId) throw new TypeError("sourceSchema.id must match state.formId.");
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
+  if (state.draftVersion !== void 0) {
+    return { success: false, error: { type: "draft_already_exists", currentDraftVersion: state.draftVersion } };
+  }
+  const allowedSourceVersions = /* @__PURE__ */ new Set([
+    ...state.publishedVersion === void 0 ? [] : [state.publishedVersion],
+    ...options.allowedSourceVersions ?? []
+  ]);
+  if (!allowedSourceVersions.has(sourceSchema.version)) {
+    return {
+      success: false,
+      error: {
+        type: "invalid_source_version",
+        requestedVersion: sourceSchema.version,
+        ...state.publishedVersion === void 0 ? {} : { publishedVersion: state.publishedVersion }
+      }
+    };
+  }
+  const maxVersions = options.maxVersions ?? Number.MAX_SAFE_INTEGER;
+  if (!Number.isSafeInteger(maxVersions) || maxVersions < 1) {
+    throw new TypeError("maxVersions must be a positive safe integer.");
+  }
+  if (state.nextVersion > maxVersions) {
+    return { success: false, error: { type: "max_version_exceeded", max: maxVersions } };
+  }
+  const version = state.nextVersion;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...state,
+        draftVersion: version,
+        nextVersion: version + 1,
+        revision: state.revision + 1
+      },
+      draftSchema: { ...sourceSchema, version }
+    }
+  };
+}
+function publishDraft(state, draftSchema, options = {}) {
+  validateState(state);
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
+  if (state.draftVersion === void 0 || draftSchema.id !== state.formId || draftSchema.version !== state.draftVersion) {
+    return { success: false, error: { type: "draft_not_found" } };
+  }
+  const validation = options.validate?.(draftSchema);
+  if (validation === false || Array.isArray(validation) && validation.length > 0) {
+    return {
+      success: false,
+      error: { type: "validation_failed", issues: Array.isArray(validation) ? validation : [] }
+    };
+  }
+  const timestamp = options.timestamp ?? "1970-01-01T00:00:00.000Z";
+  if (!Number.isFinite(Date.parse(timestamp))) throw new TypeError("timestamp must be a valid date string.");
+  const archivedVersion = state.publishedVersion;
+  const archivedRecords = archivedVersion === void 0 ? [] : [
+    {
+      formId: state.formId,
+      version: archivedVersion,
+      status: "archived",
+      schema: { ...draftSchema, version: archivedVersion },
+      createdAt: timestamp,
+      publishedAt: timestamp,
+      archivedAt: timestamp
+    }
+  ];
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: {
+      nextState: {
+        ...stateWithoutDraft,
+        publishedVersion: draftSchema.version,
+        revision: state.revision + 1
+      },
+      publishedRecord: {
+        formId: state.formId,
+        version: draftSchema.version,
+        status: "published",
+        schema: draftSchema,
+        createdAt: timestamp,
+        publishedAt: timestamp
+      },
+      archivedRecords,
+      ...archivedVersion === void 0 ? {} : { archivedVersion }
+    }
+  };
+}
+function deleteDraft(state, options = {}) {
+  validateState(state);
+  const conflict = revisionConflict(state, options.expectedRevision);
+  if (conflict !== void 0) return conflict;
+  if (state.draftVersion === void 0) return { success: false, error: { type: "draft_not_found" } };
+  const { draftVersion: _draftVersion, ...stateWithoutDraft } = state;
+  return {
+    success: true,
+    value: { nextState: { ...stateWithoutDraft, revision: state.revision + 1 } }
+  };
+}
+function assertVersionMutable(status) {
+  if (status !== "draft") {
+    const error = { type: "version_immutable", status };
+    throw new TypeError(`A ${status} form version is immutable.`, { cause: error });
+  }
+}
 export {
   aggregateResponses,
   assertValidFormSchema,
+  assertVersionMutable,
   calculateChoiceDistribution,
   calculateCrossTabulation,
   calculateFieldVisibility,
   calculateNumericSummary,
   calculatePageVisibility,
+  cloneVersionToDraft,
   collectSchemaLocales,
+  createResponseAccumulator,
   createSubmission,
+  decodeSubmissionCursor,
+  deleteDraft,
   dispatchWebhook,
+  encodeSubmissionCursor,
   escapeCsvCell,
   exportResponsesToCsv,
+  exportResponsesToCsvStream,
   isDisplayConditionSatisfied,
   isQuestionVisible,
+  matchesSubmissionPageFilters,
+  normalizeSubmissionPageSize,
+  pipeResponsesToCsvStream,
   populateSchemaTranslations,
+  publishDraft,
   resolveFormTranslation,
   resolveLocalizedSchema,
   sanitizeSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/core",
-  "version": "2.3.0",
+  "version": "2.5.1",
   "publishConfig": {
     "access": "public"
   },