@form-engine-ts/storage-azure-table 2.7.0 → 2.8.0

package/README.md

@@ -35,3 +35,8 @@ unsupported expressions remain client-filtered with identical semantics.
 to fill the requested logical page after client-side filtering. `buildSubmissionFilter` can replace filter generation.
 The deprecated `client`, `submissionCodec`, and `toODataFilter` options remain available for compatibility. The caller
 owns table creation, credentials, retries, and client lifecycle.
+
+`listTextAnswerPage` accepts either the legacy single field ID or `TextAnswerPageQueryOptions.fieldIds`. Page size counts
+emitted text items rather than entities. Its opaque Base64 JSON cursor retains the Azure continuation token plus entity
+and field indexes, so a page can resume inside a multi-answer entity without gaps or duplicates. Empty answers do not
+consume the item limit, and scanning remains bounded by `maxScanPages`.

package/dist/index.cjs

@@ -27,6 +27,70 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@form-engine-ts/core");
+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 encodeAzureTextAnswerCursor(value) {
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeAzureTextAnswerCursor(cursor) {
+  try {
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (!isRecord(value) || value.tableContinuationToken !== null && typeof value.tableContinuationToken !== "string" || !Number.isSafeInteger(value.entityIndex) || value.entityIndex < 0 || !Number.isSafeInteger(value.fieldIndex) || value.fieldIndex < 0) {
+      throw new TypeError("Azure text answer cursor payload is invalid.");
+    }
+    return {
+      tableContinuationToken: value.tableContinuationToken,
+      entityIndex: value.entityIndex,
+      fieldIndex: value.fieldIndex
+    };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "Azure text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid Azure text answer cursor.", { cause });
+  }
+}
+function textAnswerQuery(fieldIdOrOptions, options) {
+  const query = typeof fieldIdOrOptions === "string" ? options ?? {} : fieldIdOrOptions ?? {};
+  const requested = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : query.fieldIds;
+  if (requested?.some((fieldId) => fieldId.trim().length === 0)) {
+    throw new TypeError("fieldIds must not contain empty values.");
+  }
+  const fieldIds = requested === void 0 ? void 0 : [...new Set(requested)];
+  return { query, ...fieldIds === void 0 ? {} : { fieldIds } };
+}
+function submissionTextAnswers(submission, fieldIds) {
+  const entries = fieldIds === void 0 ? Object.entries(submission.values) : fieldIds.map((id) => [id, submission.values[id]]);
+  return entries.flatMap(
+    ([fieldId, value]) => typeof value === "string" && value.length > 0 ? [{ fieldId, text: value }] : []
+  );
+}
 function cloneJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
@@ -300,6 +364,88 @@ function createAzureTableStorage(options = {}) {
         ...continuationToken === void 0 || continuationToken.length === 0 ? {} : { nextCursor: continuationToken }
       };
     },
+    async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
+      const { query, fieldIds } = textAnswerQuery(fieldIdOrOptions, providedOptions);
+      const pageSize = (0, import_core.normalizeSubmissionPageSize)(query.pageSize);
+      const cursor = query.cursor === void 0 ? void 0 : decodeAzureTextAnswerCursor(query.cursor);
+      const client = await submissionClient(formId, query);
+      const items = [];
+      let tableContinuationToken = cursor?.tableContinuationToken ?? void 0;
+      let entityStartIndex = cursor?.entityIndex ?? 0;
+      let fieldStartIndex = cursor?.fieldIndex ?? 0;
+      let scannedPages = 0;
+      while (scannedPages < maxScanPages) {
+        const requestToken = tableContinuationToken;
+        const iterator = client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({
+          maxPageSize: pageSize,
+          ...requestToken === void 0 ? {} : { continuationToken: requestToken }
+        });
+        const result = await iterator.next();
+        if (result.done === true) break;
+        scannedPages += 1;
+        const page = result.value;
+        for (let entityIndex = entityStartIndex; entityIndex < page.length; entityIndex += 1) {
+          const raw = page[entityIndex];
+          if (raw === void 0) continue;
+          const submission = deserializeIfMatching(raw);
+          if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query) || !(0, import_core.matchesSubmissionPageFilters)(submission, query)) {
+            fieldStartIndex = 0;
+            continue;
+          }
+          const answers = submissionTextAnswers(submission, fieldIds);
+          for (let fieldIndex = entityIndex === entityStartIndex ? fieldStartIndex : 0; fieldIndex < answers.length; fieldIndex += 1) {
+            const answer = answers[fieldIndex];
+            if (answer === void 0) continue;
+            items.push({
+              responseId: submission.id,
+              formId: submission.formId,
+              formVersion: submission.formVersion,
+              fieldId: answer.fieldId,
+              text: answer.text,
+              locale: submission.locale,
+              submittedAt: submission.submittedAt,
+              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+            });
+            if (items.length < pageSize) continue;
+            const nextFieldIndex = fieldIndex + 1;
+            const hasFieldsInEntity = nextFieldIndex < answers.length;
+            const hasEntitiesInPage = entityIndex + 1 < page.length;
+            const nextPageToken = page.continuationToken;
+            const hasMore = hasFieldsInEntity || hasEntitiesInPage || nextPageToken !== void 0;
+            if (!hasMore) return { items, hasMore: false };
+            const nextCursor = hasFieldsInEntity ? {
+              tableContinuationToken: requestToken ?? null,
+              entityIndex,
+              fieldIndex: nextFieldIndex
+            } : hasEntitiesInPage ? {
+              tableContinuationToken: requestToken ?? null,
+              entityIndex: entityIndex + 1,
+              fieldIndex: 0
+            } : {
+              tableContinuationToken: nextPageToken ?? null,
+              entityIndex: 0,
+              fieldIndex: 0
+            };
+            return { items, hasMore: true, nextCursor: encodeAzureTextAnswerCursor(nextCursor) };
+          }
+          fieldStartIndex = 0;
+        }
+        tableContinuationToken = page.continuationToken;
+        entityStartIndex = 0;
+        fieldStartIndex = 0;
+        if (tableContinuationToken === void 0) break;
+      }
+      if (tableContinuationToken === void 0) return { items, hasMore: false };
+      return {
+        items,
+        hasMore: true,
+        nextCursor: encodeAzureTextAnswerCursor({
+          tableContinuationToken,
+          entityIndex: 0,
+          fieldIndex: 0
+        })
+      };
+    },
     async deleteSubmission(submissionId) {
       const client = await submissionClient("");
       for await (const raw of client.listEntities()) {

package/dist/index.js

@@ -1,5 +1,69 @@
 // src/index.ts
 import { assertValidFormSchema, matchesSubmissionPageFilters, normalizeSubmissionPageSize } from "@form-engine-ts/core";
+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 encodeAzureTextAnswerCursor(value) {
+  return encodeBase64(new TextEncoder().encode(JSON.stringify(value)));
+}
+function decodeAzureTextAnswerCursor(cursor) {
+  try {
+    const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(decodeBase64(cursor)));
+    if (!isRecord(value) || value.tableContinuationToken !== null && typeof value.tableContinuationToken !== "string" || !Number.isSafeInteger(value.entityIndex) || value.entityIndex < 0 || !Number.isSafeInteger(value.fieldIndex) || value.fieldIndex < 0) {
+      throw new TypeError("Azure text answer cursor payload is invalid.");
+    }
+    return {
+      tableContinuationToken: value.tableContinuationToken,
+      entityIndex: value.entityIndex,
+      fieldIndex: value.fieldIndex
+    };
+  } catch (cause) {
+    if (cause instanceof TypeError && cause.message === "Azure text answer cursor payload is invalid.") throw cause;
+    throw new TypeError("cursor must be a valid Azure text answer cursor.", { cause });
+  }
+}
+function textAnswerQuery(fieldIdOrOptions, options) {
+  const query = typeof fieldIdOrOptions === "string" ? options ?? {} : fieldIdOrOptions ?? {};
+  const requested = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : query.fieldIds;
+  if (requested?.some((fieldId) => fieldId.trim().length === 0)) {
+    throw new TypeError("fieldIds must not contain empty values.");
+  }
+  const fieldIds = requested === void 0 ? void 0 : [...new Set(requested)];
+  return { query, ...fieldIds === void 0 ? {} : { fieldIds } };
+}
+function submissionTextAnswers(submission, fieldIds) {
+  const entries = fieldIds === void 0 ? Object.entries(submission.values) : fieldIds.map((id) => [id, submission.values[id]]);
+  return entries.flatMap(
+    ([fieldId, value]) => typeof value === "string" && value.length > 0 ? [{ fieldId, text: value }] : []
+  );
+}
 function cloneJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
@@ -273,6 +337,88 @@ function createAzureTableStorage(options = {}) {
         ...continuationToken === void 0 || continuationToken.length === 0 ? {} : { nextCursor: continuationToken }
       };
     },
+    async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
+      const { query, fieldIds } = textAnswerQuery(fieldIdOrOptions, providedOptions);
+      const pageSize = normalizeSubmissionPageSize(query.pageSize);
+      const cursor = query.cursor === void 0 ? void 0 : decodeAzureTextAnswerCursor(query.cursor);
+      const client = await submissionClient(formId, query);
+      const items = [];
+      let tableContinuationToken = cursor?.tableContinuationToken ?? void 0;
+      let entityStartIndex = cursor?.entityIndex ?? 0;
+      let fieldStartIndex = cursor?.fieldIndex ?? 0;
+      let scannedPages = 0;
+      while (scannedPages < maxScanPages) {
+        const requestToken = tableContinuationToken;
+        const iterator = client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({
+          maxPageSize: pageSize,
+          ...requestToken === void 0 ? {} : { continuationToken: requestToken }
+        });
+        const result = await iterator.next();
+        if (result.done === true) break;
+        scannedPages += 1;
+        const page = result.value;
+        for (let entityIndex = entityStartIndex; entityIndex < page.length; entityIndex += 1) {
+          const raw = page[entityIndex];
+          if (raw === void 0) continue;
+          const submission = deserializeIfMatching(raw);
+          if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query) || !matchesSubmissionPageFilters(submission, query)) {
+            fieldStartIndex = 0;
+            continue;
+          }
+          const answers = submissionTextAnswers(submission, fieldIds);
+          for (let fieldIndex = entityIndex === entityStartIndex ? fieldStartIndex : 0; fieldIndex < answers.length; fieldIndex += 1) {
+            const answer = answers[fieldIndex];
+            if (answer === void 0) continue;
+            items.push({
+              responseId: submission.id,
+              formId: submission.formId,
+              formVersion: submission.formVersion,
+              fieldId: answer.fieldId,
+              text: answer.text,
+              locale: submission.locale,
+              submittedAt: submission.submittedAt,
+              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+            });
+            if (items.length < pageSize) continue;
+            const nextFieldIndex = fieldIndex + 1;
+            const hasFieldsInEntity = nextFieldIndex < answers.length;
+            const hasEntitiesInPage = entityIndex + 1 < page.length;
+            const nextPageToken = page.continuationToken;
+            const hasMore = hasFieldsInEntity || hasEntitiesInPage || nextPageToken !== void 0;
+            if (!hasMore) return { items, hasMore: false };
+            const nextCursor = hasFieldsInEntity ? {
+              tableContinuationToken: requestToken ?? null,
+              entityIndex,
+              fieldIndex: nextFieldIndex
+            } : hasEntitiesInPage ? {
+              tableContinuationToken: requestToken ?? null,
+              entityIndex: entityIndex + 1,
+              fieldIndex: 0
+            } : {
+              tableContinuationToken: nextPageToken ?? null,
+              entityIndex: 0,
+              fieldIndex: 0
+            };
+            return { items, hasMore: true, nextCursor: encodeAzureTextAnswerCursor(nextCursor) };
+          }
+          fieldStartIndex = 0;
+        }
+        tableContinuationToken = page.continuationToken;
+        entityStartIndex = 0;
+        fieldStartIndex = 0;
+        if (tableContinuationToken === void 0) break;
+      }
+      if (tableContinuationToken === void 0) return { items, hasMore: false };
+      return {
+        items,
+        hasMore: true,
+        nextCursor: encodeAzureTextAnswerCursor({
+          tableContinuationToken,
+          entityIndex: 0,
+          fieldIndex: 0
+        })
+      };
+    },
     async deleteSubmission(submissionId) {
       const client = await submissionClient("");
       for await (const raw of client.listEntities()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage-azure-table",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.7.0"
+    "@form-engine-ts/core": "2.8.0"
   },
   "peerDependencies": {
     "@azure/data-tables": "^13.3.2"