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

package/README.md

@@ -39,4 +39,6 @@ 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`.
+consume the item limit, and scanning remains bounded by `maxScanPages`. Cursor format version 1 also records the form,
+version, sorted fields, and a SHA-256 filter fingerprint. Reusing a cursor with different query context throws
+`invalid_cursor_context`.

package/dist/index.cjs

@@ -63,11 +63,16 @@ function encodeAzureTextAnswerCursor(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) {
+    if (!isRecord(value) || value.formatVersion !== 1 || typeof value.formId !== "string" || value.formId.length === 0 || value.formVersion !== void 0 && (!Number.isSafeInteger(value.formVersion) || value.formVersion < 1) || !Array.isArray(value.fieldIdsSorted) || value.fieldIdsSorted.some((fieldId) => typeof fieldId !== "string") || typeof value.filterFingerprint !== "string" || value.filterFingerprint.length === 0 || value.tableContinuationToken !== void 0 && (typeof value.tableContinuationToken !== "string" || value.tableContinuationToken.length === 0) || !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,
+      formatVersion: 1,
+      formId: value.formId,
+      ...value.formVersion === void 0 ? {} : { formVersion: value.formVersion },
+      fieldIdsSorted: value.fieldIdsSorted,
+      filterFingerprint: value.filterFingerprint,
+      ...value.tableContinuationToken === void 0 ? {} : { tableContinuationToken: value.tableContinuationToken },
       entityIndex: value.entityIndex,
       fieldIndex: value.fieldIndex
     };
@@ -76,6 +81,28 @@ function decodeAzureTextAnswerCursor(cursor) {
     throw new TypeError("cursor must be a valid Azure text answer cursor.", { cause });
   }
 }
+function canonicalValue(value) {
+  if (typeof value === "function") return JSON.stringify(`function:${String(value)}`);
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : JSON.stringify(String(value));
+  if (Array.isArray(value)) return `[${value.map(canonicalValue).join(",")}]`;
+  if (!isRecord(value)) return JSON.stringify(String(value));
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalValue(value[key])}`).join(",")}}`;
+}
+async function textAnswerFilterFingerprint(odataFilter, query, allFields) {
+  const canonical = canonicalValue({
+    odataFilter,
+    filter: query.filter,
+    metadataFilters: query.metadataFilters,
+    allFields
+  });
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function cursorContextMatches(cursor, formId, formVersion, fieldIdsSorted, filterFingerprint) {
+  return cursor.formId === formId && cursor.formVersion === formVersion && cursor.filterFingerprint === filterFingerprint && cursor.fieldIdsSorted.length === fieldIdsSorted.length && cursor.fieldIdsSorted.every((fieldId, index) => fieldId === fieldIdsSorted[index]);
+}
 function textAnswerQuery(fieldIdOrOptions, options) {
   const query = typeof fieldIdOrOptions === "string" ? options ?? {} : fieldIdOrOptions ?? {};
   const requested = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : query.fieldIds;
@@ -367,16 +394,29 @@ function createAzureTableStorage(options = {}) {
     async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
       const { query, fieldIds } = textAnswerQuery(fieldIdOrOptions, providedOptions);
       const pageSize = (0, import_core.normalizeSubmissionPageSize)(query.pageSize);
+      const fieldIdsSorted = [...fieldIds ?? []].sort();
+      const odataFilter = queryFilter(formId, query);
+      const filterFingerprint = await textAnswerFilterFingerprint(odataFilter, query, fieldIds === void 0);
       const cursor = query.cursor === void 0 ? void 0 : decodeAzureTextAnswerCursor(query.cursor);
+      if (cursor !== void 0 && !cursorContextMatches(cursor, formId, query.version, fieldIdsSorted, filterFingerprint)) {
+        throw new TypeError("invalid_cursor_context");
+      }
+      const cursorContext = {
+        formatVersion: 1,
+        formId,
+        ...query.version === void 0 ? {} : { formVersion: query.version },
+        fieldIdsSorted,
+        filterFingerprint
+      };
       const client = await submissionClient(formId, query);
       const items = [];
-      let tableContinuationToken = cursor?.tableContinuationToken ?? void 0;
+      let tableContinuationToken = cursor?.tableContinuationToken;
       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({
+        const iterator = client.listEntities({ queryOptions: { filter: odataFilter } }).byPage({
           maxPageSize: pageSize,
           ...requestToken === void 0 ? {} : { continuationToken: requestToken }
         });
@@ -414,15 +454,18 @@ function createAzureTableStorage(options = {}) {
             const hasMore = hasFieldsInEntity || hasEntitiesInPage || nextPageToken !== void 0;
             if (!hasMore) return { items, hasMore: false };
             const nextCursor = hasFieldsInEntity ? {
-              tableContinuationToken: requestToken ?? null,
+              ...cursorContext,
+              ...requestToken === void 0 ? {} : { tableContinuationToken: requestToken },
               entityIndex,
               fieldIndex: nextFieldIndex
             } : hasEntitiesInPage ? {
-              tableContinuationToken: requestToken ?? null,
+              ...cursorContext,
+              ...requestToken === void 0 ? {} : { tableContinuationToken: requestToken },
               entityIndex: entityIndex + 1,
               fieldIndex: 0
             } : {
-              tableContinuationToken: nextPageToken ?? null,
+              ...cursorContext,
+              ...nextPageToken === void 0 ? {} : { tableContinuationToken: nextPageToken },
               entityIndex: 0,
               fieldIndex: 0
             };
@@ -440,6 +483,7 @@ function createAzureTableStorage(options = {}) {
         items,
         hasMore: true,
         nextCursor: encodeAzureTextAnswerCursor({
+          ...cursorContext,
           tableContinuationToken,
           entityIndex: 0,
           fieldIndex: 0

package/dist/index.d.cts

@@ -55,9 +55,19 @@ interface AzureTableStorageOptions<T = FormSubmission> {
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
     readonly maxScanPages?: number;
 }
+interface AzureTextAnswerCursorPayload {
+    readonly formatVersion: 1;
+    readonly formId: string;
+    readonly formVersion?: number;
+    readonly fieldIdsSorted: readonly string[];
+    readonly filterFingerprint: string;
+    readonly tableContinuationToken?: string;
+    readonly entityIndex: number;
+    readonly fieldIndex: number;
+}
 declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
 declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
 declare function submissionFilterToOData(filter: SubmissionFilter): string | undefined;
 declare function createAzureTableStorage(options?: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.d.ts

@@ -55,9 +55,19 @@ interface AzureTableStorageOptions<T = FormSubmission> {
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
     readonly maxScanPages?: number;
 }
+interface AzureTextAnswerCursorPayload {
+    readonly formatVersion: 1;
+    readonly formId: string;
+    readonly formVersion?: number;
+    readonly fieldIdsSorted: readonly string[];
+    readonly filterFingerprint: string;
+    readonly tableContinuationToken?: string;
+    readonly entityIndex: number;
+    readonly fieldIndex: number;
+}
 declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
 declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
 declare function submissionFilterToOData(filter: SubmissionFilter): string | undefined;
 declare function createAzureTableStorage(options?: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.js

@@ -36,11 +36,16 @@ function encodeAzureTextAnswerCursor(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) {
+    if (!isRecord(value) || value.formatVersion !== 1 || typeof value.formId !== "string" || value.formId.length === 0 || value.formVersion !== void 0 && (!Number.isSafeInteger(value.formVersion) || value.formVersion < 1) || !Array.isArray(value.fieldIdsSorted) || value.fieldIdsSorted.some((fieldId) => typeof fieldId !== "string") || typeof value.filterFingerprint !== "string" || value.filterFingerprint.length === 0 || value.tableContinuationToken !== void 0 && (typeof value.tableContinuationToken !== "string" || value.tableContinuationToken.length === 0) || !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,
+      formatVersion: 1,
+      formId: value.formId,
+      ...value.formVersion === void 0 ? {} : { formVersion: value.formVersion },
+      fieldIdsSorted: value.fieldIdsSorted,
+      filterFingerprint: value.filterFingerprint,
+      ...value.tableContinuationToken === void 0 ? {} : { tableContinuationToken: value.tableContinuationToken },
       entityIndex: value.entityIndex,
       fieldIndex: value.fieldIndex
     };
@@ -49,6 +54,28 @@ function decodeAzureTextAnswerCursor(cursor) {
     throw new TypeError("cursor must be a valid Azure text answer cursor.", { cause });
   }
 }
+function canonicalValue(value) {
+  if (typeof value === "function") return JSON.stringify(`function:${String(value)}`);
+  if (value === void 0) return "undefined";
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number") return Number.isFinite(value) ? JSON.stringify(value) : JSON.stringify(String(value));
+  if (Array.isArray(value)) return `[${value.map(canonicalValue).join(",")}]`;
+  if (!isRecord(value)) return JSON.stringify(String(value));
+  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalValue(value[key])}`).join(",")}}`;
+}
+async function textAnswerFilterFingerprint(odataFilter, query, allFields) {
+  const canonical = canonicalValue({
+    odataFilter,
+    filter: query.filter,
+    metadataFilters: query.metadataFilters,
+    allFields
+  });
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function cursorContextMatches(cursor, formId, formVersion, fieldIdsSorted, filterFingerprint) {
+  return cursor.formId === formId && cursor.formVersion === formVersion && cursor.filterFingerprint === filterFingerprint && cursor.fieldIdsSorted.length === fieldIdsSorted.length && cursor.fieldIdsSorted.every((fieldId, index) => fieldId === fieldIdsSorted[index]);
+}
 function textAnswerQuery(fieldIdOrOptions, options) {
   const query = typeof fieldIdOrOptions === "string" ? options ?? {} : fieldIdOrOptions ?? {};
   const requested = typeof fieldIdOrOptions === "string" ? [fieldIdOrOptions] : query.fieldIds;
@@ -340,16 +367,29 @@ function createAzureTableStorage(options = {}) {
     async listTextAnswerPage(formId, fieldIdOrOptions, providedOptions) {
       const { query, fieldIds } = textAnswerQuery(fieldIdOrOptions, providedOptions);
       const pageSize = normalizeSubmissionPageSize(query.pageSize);
+      const fieldIdsSorted = [...fieldIds ?? []].sort();
+      const odataFilter = queryFilter(formId, query);
+      const filterFingerprint = await textAnswerFilterFingerprint(odataFilter, query, fieldIds === void 0);
       const cursor = query.cursor === void 0 ? void 0 : decodeAzureTextAnswerCursor(query.cursor);
+      if (cursor !== void 0 && !cursorContextMatches(cursor, formId, query.version, fieldIdsSorted, filterFingerprint)) {
+        throw new TypeError("invalid_cursor_context");
+      }
+      const cursorContext = {
+        formatVersion: 1,
+        formId,
+        ...query.version === void 0 ? {} : { formVersion: query.version },
+        fieldIdsSorted,
+        filterFingerprint
+      };
       const client = await submissionClient(formId, query);
       const items = [];
-      let tableContinuationToken = cursor?.tableContinuationToken ?? void 0;
+      let tableContinuationToken = cursor?.tableContinuationToken;
       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({
+        const iterator = client.listEntities({ queryOptions: { filter: odataFilter } }).byPage({
           maxPageSize: pageSize,
           ...requestToken === void 0 ? {} : { continuationToken: requestToken }
         });
@@ -387,15 +427,18 @@ function createAzureTableStorage(options = {}) {
             const hasMore = hasFieldsInEntity || hasEntitiesInPage || nextPageToken !== void 0;
             if (!hasMore) return { items, hasMore: false };
             const nextCursor = hasFieldsInEntity ? {
-              tableContinuationToken: requestToken ?? null,
+              ...cursorContext,
+              ...requestToken === void 0 ? {} : { tableContinuationToken: requestToken },
               entityIndex,
               fieldIndex: nextFieldIndex
             } : hasEntitiesInPage ? {
-              tableContinuationToken: requestToken ?? null,
+              ...cursorContext,
+              ...requestToken === void 0 ? {} : { tableContinuationToken: requestToken },
               entityIndex: entityIndex + 1,
               fieldIndex: 0
             } : {
-              tableContinuationToken: nextPageToken ?? null,
+              ...cursorContext,
+              ...nextPageToken === void 0 ? {} : { tableContinuationToken: nextPageToken },
               entityIndex: 0,
               fieldIndex: 0
             };
@@ -413,6 +456,7 @@ function createAzureTableStorage(options = {}) {
         items,
         hasMore: true,
         nextCursor: encodeAzureTextAnswerCursor({
+          ...cursorContext,
           tableContinuationToken,
           entityIndex: 0,
           fieldIndex: 0

package/package.json

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