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

package/README.md

@@ -25,9 +25,18 @@ const storage = createAzureTableStorage({ schemasTableClient, submissionsTableCl
 const page = await storage.listSubmissionPage("contact", { pageSize: 500, locale: "ja" });
 ```
 
-Submission entities use `formId` as `PartitionKey` and `submittedAt_responseId` as `RowKey`. Built-in date, locale,
-version, and cursor constraints are sent as OData filters. `listSubmissionPage` calls the Azure iterator's
-`.byPage({ maxPageSize, continuationToken })` and consumes exactly one native page per request; the returned service token
-remains opaque. Scalar metadata filters can be converted to OData with `metadataFiltersToOData` or a custom
-`toODataFilter`. Supply `submissionCodec` for custom entity layouts. The deprecated single `client` option remains
-available for compatibility. The caller owns table creation, credentials, retries, and the client lifecycle.
+The default codec uses `formId` as `PartitionKey` and `submittedAt_responseId` as `RowKey`. Supply an
+`AzureTableSubmissionCodec` to define a completely different entity layout, key strategy, deserializer, and client-side
+matcher; custom entities are not polluted with default discriminator fields. `clientResolver` can select a table client
+per form and operation. Date, locale, version, cursor, metadata, and supported filter-AST constraints are sent as OData;
+unsupported expressions remain client-filtered with identical semantics.
+
+`listSubmissionPage` follows opaque Azure continuation tokens and scans at most `maxScanPages` native pages (default 5)
+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

@@ -22,10 +22,75 @@ var index_exports = {};
 __export(index_exports, {
   createAzureTableStorage: () => createAzureTableStorage,
   defaultAzureTableSubmissionCodec: () => defaultAzureTableSubmissionCodec,
-  metadataFiltersToOData: () => metadataFiltersToOData
+  metadataFiltersToOData: () => metadataFiltersToOData,
+  submissionFilterToOData: () => submissionFilterToOData
 });
 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));
 }
@@ -66,12 +131,38 @@ function scalarMetadata(metadata) {
   );
 }
 var defaultAzureTableSubmissionCodec = {
+  createEntity: (submission) => ({
+    ...scalarMetadata(submission.metadata),
+    kind: "submission",
+    formVersion: submission.formVersion,
+    locale: submission.locale,
+    submittedAt: submission.submittedAt,
+    responseId: submission.id,
+    payload: JSON.stringify(submission)
+  }),
+  deserialize: (entity) => parseSubmission(entity.payload, "submission entity"),
+  matchesEntity: (entity) => entity.kind === "submission",
   createPartitionKey: (submission) => submission.formId,
-  createPartitionKeyFromFormId: (formId) => formId,
-  createRowKey: defaultSubmissionRowKey,
-  serialize: (submission) => ({ ...scalarMetadata(submission.metadata), payload: JSON.stringify(submission) }),
-  deserialize: (entity) => parseSubmission(entity.payload, "submission entity")
+  createPartitionKeyFromQuery: (formId) => formId,
+  createRowKey: defaultSubmissionRowKey
 };
+function legacyCodec(codec) {
+  return {
+    createEntity: (value) => ({
+      ...codec.serialize(value),
+      kind: "submission",
+      formVersion: value.formVersion,
+      locale: value.locale,
+      submittedAt: value.submittedAt,
+      responseId: value.id
+    }),
+    deserialize: codec.deserialize,
+    matchesEntity: (entity) => entity.kind === "submission",
+    createPartitionKey: codec.createPartitionKey,
+    createPartitionKeyFromQuery: (formId) => codec.createPartitionKeyFromFormId?.(formId) ?? formId,
+    createRowKey: codec.createRowKey
+  };
+}
 function parseSchemaEntity(value) {
   if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
     throw new Error("Azure Table schema entity is invalid.");
@@ -84,40 +175,73 @@ function parseSchemaEntity(value) {
   return cloneJson(schema);
 }
 function parseSubmissionEntity(value, codec) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "submission") {
+  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || !codec.matchesEntity(value)) {
     throw new Error("Azure Table submission entity is invalid.");
   }
   const submission = parseSubmission(codec.deserialize(value), `submission ${value.partitionKey}/${value.rowKey}`);
-  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey || value.formVersion !== submission.formVersion || value.locale !== submission.locale || value.submittedAt !== submission.submittedAt || value.responseId !== submission.id) {
-    throw new Error("Azure Table submission entity has inconsistent metadata.");
+  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey) {
+    throw new Error("Azure Table submission entity has inconsistent keys.");
   }
   return submission;
 }
 function escapeOData(value) {
   return value.replaceAll("'", "''");
 }
-function metadataValueToOData(value) {
+function valueToOData(value) {
   if (value === null) return "null";
   if (typeof value === "string") return `'${escapeOData(value)}'`;
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
   if (typeof value === "boolean") return String(value);
-  throw new TypeError("Azure Table metadata OData filters support only scalar JSON values.");
+  throw new TypeError("Azure Table OData filters support only scalar JSON values.");
 }
 function metadataFiltersToOData(options) {
   return Object.entries(options.metadataFilters ?? {}).map(([key, value]) => {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new TypeError(`Invalid Azure Table property name: ${key}`);
-    return `${key} eq ${metadataValueToOData(value)}`;
+    return `${key} eq ${valueToOData(value)}`;
   }).join(" and ");
 }
-function odataFilter(formId, options, extension) {
+function odataProperty(path) {
+  if (path === "id" || path === "responseId") return "responseId";
+  if (["formVersion", "locale", "submittedAt"].includes(path)) return path;
+  if (path.startsWith("metadata.")) {
+    const property = path.slice("metadata.".length);
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(property) ? property : void 0;
+  }
+  return void 0;
+}
+function submissionFilterToOData(filter) {
+  if (filter.op === "and" || filter.op === "or") {
+    const converted = filter.filters.map(submissionFilterToOData);
+    if (filter.op === "or" && converted.some((value) => value === void 0)) return void 0;
+    const available = converted.filter((value) => value !== void 0 && value.length > 0);
+    if (available.length === 0) return void 0;
+    return available.map((value) => `(${value})`).join(filter.op === "and" ? " and " : " or ");
+  }
+  const property = odataProperty(filter.path);
+  if (property === void 0) return void 0;
+  if (filter.op === "eq") return `${property} eq ${valueToOData(filter.value)}`;
+  if (filter.op === "in") {
+    if (filter.values.length === 0) return "false";
+    return filter.values.map((value) => `${property} eq ${valueToOData(value)}`).join(" or ");
+  }
+  if (filter.op === "exists") return `${property} ${filter.value ? "ne" : "eq"} null`;
   return [
-    ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
-    "kind eq 'submission'",
+    ...filter.from === void 0 ? [] : [`${property} ge ${valueToOData(filter.from)}`],
+    ...filter.to === void 0 ? [] : [`${property} le ${valueToOData(filter.to)}`]
+  ].join(" and ");
+}
+function defaultSubmissionFilter(codec, formId, options, legacyExtension) {
+  const partitionKey = codec.createPartitionKeyFromQuery(formId, options);
+  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter);
+  return [
+    ...partitionKey === void 0 ? [] : [`PartitionKey eq '${escapeOData(partitionKey)}'`],
+    ...codec === defaultAzureTableSubmissionCodec ? ["kind eq 'submission'"] : [],
     ...options.version === void 0 ? [] : [`formVersion eq ${options.version}`],
     ...options.since === void 0 ? [] : [`submittedAt ge '${escapeOData(options.since)}'`],
     ...options.until === void 0 ? [] : [`submittedAt le '${escapeOData(options.until)}'`],
     ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
-    ...extension.trim().length === 0 ? [] : [`(${extension})`]
+    ...ast === void 0 || ast.length === 0 ? [] : [`(${ast})`],
+    ...legacyExtension.trim().length === 0 ? [] : [`(${legacyExtension})`]
   ].join(" and ");
 }
 function isNotFound(error) {
@@ -126,26 +250,41 @@ function isNotFound(error) {
 function matchesBuiltInFilters(submission, formId, options) {
   return submission.formId === formId && (options.version === void 0 || submission.formVersion === options.version) && (options.since === void 0 || submission.submittedAt >= options.since) && (options.until === void 0 || submission.submittedAt <= options.until) && (options.locale === void 0 || submission.locale === options.locale);
 }
-function resolveClient(preferred, fallback, name) {
-  const client = preferred ?? fallback;
+function requireClient(client, name) {
   if (client === void 0) throw new TypeError(`${name} is required.`);
   return client;
 }
-function createAzureTableStorage(options) {
-  const schemas = resolveClient(options?.schemasTableClient, options?.client, "schemasTableClient");
-  const submissions = resolveClient(options?.submissionsTableClient, options?.client, "submissionsTableClient");
-  const codec = options.submissionCodec ?? defaultAzureTableSubmissionCodec;
-  const toODataFilter = options.toODataFilter ?? metadataFiltersToOData;
-  const partitionKeyFromFormId = codec.createPartitionKeyFromFormId ?? ((formId) => formId);
-  const queryFilter = (formId, query) => odataFilter(formId === void 0 ? void 0 : partitionKeyFromFormId(formId), query, toODataFilter(query));
+function createAzureTableStorage(options = {}) {
+  const staticSchemas = options.schemasTableClient ?? options.client;
+  const staticSubmissions = options.submissionsTableClient ?? options.client;
+  const codec = options.codec ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
+  const maxScanPages = options.maxScanPages ?? 5;
+  if (!Number.isSafeInteger(maxScanPages) || maxScanPages < 1) {
+    throw new TypeError("maxScanPages must be a positive safe integer.");
+  }
+  const resolveDynamicClient = async (formId, query) => options.clientResolver?.({ formId, ...query === void 0 ? {} : { query } });
+  const schemaClient = async (formId) => requireClient(staticSchemas ?? await resolveDynamicClient(formId), "schemasTableClient or clientResolver");
+  const submissionClient = async (formId, query) => requireClient(
+    await resolveDynamicClient(formId, query) ?? staticSubmissions,
+    "submissionsTableClient or clientResolver"
+  );
+  const queryFilter = (formId, query) => {
+    if (options.buildSubmissionFilter !== void 0) return options.buildSubmissionFilter(formId, query);
+    return defaultSubmissionFilter(
+      codec,
+      formId,
+      query,
+      options.toODataFilter?.(query) ?? metadataFiltersToOData(query)
+    );
+  };
+  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec) : void 0;
   const listSubmissionCandidates = async (formId, query) => {
+    const client = await submissionClient(formId, query);
     const found = [];
-    for await (const raw of submissions.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
-      if (raw.kind !== "submission") continue;
-      const submission = parseSubmissionEntity(raw, codec);
-      if (!matchesBuiltInFilters(submission, formId, query)) continue;
-      if (!(0, import_core.matchesSubmissionPageFilters)(submission, query)) continue;
-      found.push(submission);
+    for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
+      const submission = deserializeIfMatching(raw);
+      if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query)) continue;
+      if ((0, import_core.matchesSubmissionPageFilters)(submission, query)) found.push(submission);
     }
     return found.sort(
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
@@ -161,11 +300,11 @@ function createAzureTableStorage(options) {
         formVersion: schema.version,
         payload: JSON.stringify(schema)
       };
-      await schemas.upsertEntity(entity, "Replace");
+      await (await schemaClient(schema.id)).upsertEntity(entity, "Replace");
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await schemas.getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)));
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
@@ -173,25 +312,20 @@ function createAzureTableStorage(options) {
     },
     async listSchemas() {
       const found = [];
-      for await (const raw of schemas.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
+      for await (const raw of (await schemaClient("")).listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
         if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
       }
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
-      await schemas.deleteEntity(formId, schemaRowKey(formVersion));
+      await (await schemaClient(formId)).deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
       const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
-      await submissions.createEntity({
-        ...codec.serialize(stored),
+      await (await submissionClient(stored.formId)).createEntity({
+        ...codec.createEntity(stored),
         partitionKey: codec.createPartitionKey(stored),
-        rowKey: codec.createRowKey(stored),
-        kind: "submission",
-        formVersion: stored.formVersion,
-        locale: stored.locale,
-        submittedAt: stored.submittedAt,
-        responseId: stored.id
+        rowKey: codec.createRowKey(stored)
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -202,46 +336,147 @@ function createAzureTableStorage(options) {
     },
     async listSubmissionPage(formId, query = {}) {
       const pageSize = (0, import_core.normalizeSubmissionPageSize)(query.pageSize);
-      const iterator = submissions.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({ maxPageSize: pageSize, ...query.cursor === void 0 ? {} : { continuationToken: query.cursor } });
-      const result = await iterator.next();
-      if (result.done === true) return { items: [], hasMore: false };
-      const items = result.value.filter((raw) => raw.kind === "submission").map((raw) => parseSubmissionEntity(raw, codec)).filter(
-        (submission) => matchesBuiltInFilters(submission, formId, query) && (0, import_core.matchesSubmissionPageFilters)(submission, query)
-      );
-      const nextCursor = result.value.continuationToken;
+      const client = await submissionClient(formId, query);
+      const items = [];
+      let continuationToken = query.cursor;
+      let scannedPages = 0;
+      do {
+        const iterator = client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({
+          maxPageSize: Math.max(1, pageSize - items.length),
+          ...continuationToken === void 0 ? {} : { continuationToken }
+        });
+        const result = await iterator.next();
+        if (result.done === true) {
+          continuationToken = void 0;
+          break;
+        }
+        scannedPages += 1;
+        for (const raw of result.value) {
+          const submission = deserializeIfMatching(raw);
+          if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query)) continue;
+          if ((0, import_core.matchesSubmissionPageFilters)(submission, query)) items.push(submission);
+        }
+        continuationToken = result.value.continuationToken;
+      } while (items.length < pageSize && continuationToken !== void 0 && scannedPages < maxScanPages);
       return {
         items,
-        hasMore: nextCursor !== void 0 && nextCursor.length > 0,
-        ...nextCursor === void 0 || nextCursor.length === 0 ? {} : { nextCursor }
+        hasMore: continuationToken !== void 0 && continuationToken.length > 0,
+        ...continuationToken === void 0 || continuationToken.length === 0 ? {} : { nextCursor: continuationToken }
       };
     },
-    async deleteSubmission(submissionId) {
-      for await (const raw of submissions.listEntities({ queryOptions: { filter: "kind eq 'submission'" } })) {
-        if (raw.kind === "submission" && raw.responseId === submissionId) {
-          if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string") {
-            throw new Error("Azure Table submission entity is invalid.");
+    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;
           }
-          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
-          return;
+          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()) {
+        const submission = deserializeIfMatching(raw);
+        if (submission?.id !== submissionId) continue;
+        if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string") {
+          throw new Error("Azure Table submission entity is invalid.");
         }
+        await client.deleteEntity(raw.partitionKey, raw.rowKey);
+        return;
       }
     },
     async clearResponses(formId) {
-      const partitionKey = partitionKeyFromFormId(formId);
-      for await (const raw of submissions.listEntities({
-        queryOptions: { filter: `PartitionKey eq '${escapeOData(partitionKey)}' and kind eq 'submission'` }
-      })) {
-        if (raw.partitionKey === partitionKey && raw.kind === "submission" && typeof raw.rowKey === "string") {
-          await submissions.deleteEntity(partitionKey, raw.rowKey);
+      const query = {};
+      const client = await submissionClient(formId, query);
+      for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
+        const submission = deserializeIfMatching(raw);
+        if (submission?.formId !== formId) continue;
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await client.deleteEntity(raw.partitionKey, raw.rowKey);
         }
       }
     },
     async clear() {
+      const schemas = await schemaClient("");
       for await (const raw of schemas.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
           await schemas.deleteEntity(raw.partitionKey, raw.rowKey);
         }
       }
+      const submissions = await submissionClient("");
       if (submissions === schemas) return;
       for await (const raw of submissions.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
@@ -255,5 +490,6 @@ function createAzureTableStorage(options) {
 0 && (module.exports = {
   createAzureTableStorage,
   defaultAzureTableSubmissionCodec,
-  metadataFiltersToOData
+  metadataFiltersToOData,
+  submissionFilterToOData
 });

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
@@ -22,6 +22,7 @@ interface AzureTableClientLike {
     listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
     deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
 }
+/** @deprecated Use AzureTableSubmissionCodec. */
 interface AzureTableEntityCodec<T> {
     readonly createPartitionKey: (submission: T) => string;
     readonly createPartitionKeyFromFormId?: (formId: string) => string;
@@ -29,16 +30,34 @@ interface AzureTableEntityCodec<T> {
     readonly serialize: (submission: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
 }
-interface AzureTableStorageOptions {
-    /** @deprecated Use schemasTableClient and submissionsTableClient. */
+interface AzureTableSubmissionCodec<T = FormSubmission> {
+    readonly createEntity: (value: T) => Record<string, unknown>;
+    readonly deserialize: (entity: Record<string, unknown>) => T;
+    readonly matchesEntity: (entity: Record<string, unknown>) => boolean;
+    readonly createPartitionKey: (value: T) => string;
+    readonly createPartitionKeyFromQuery: (formId: string, query: SubmissionPageQueryOptions) => string | undefined;
+    readonly createRowKey: (value: T) => string;
+}
+interface AzureTableStorageOptions<T = FormSubmission> {
+    /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
     readonly schemasTableClient?: AzureTableClientLike;
     readonly submissionsTableClient?: AzureTableClientLike;
+    readonly clientResolver?: (context: {
+        readonly formId: string;
+        readonly query?: SubmissionPageQueryOptions;
+    }) => AzureTableClientLike | Promise<AzureTableClientLike>;
+    readonly codec?: AzureTableSubmissionCodec<T>;
+    /** @deprecated Use codec. */
     readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
+    readonly buildSubmissionFilter?: (formId: string, query: SubmissionPageQueryOptions) => string;
+    /** @deprecated Use buildSubmissionFilter. */
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
+    readonly maxScanPages?: number;
 }
-declare const defaultAzureTableSubmissionCodec: AzureTableEntityCodec<FormSubmission>;
+declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
 declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
-declare function createAzureTableStorage(options: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
+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, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
@@ -22,6 +22,7 @@ interface AzureTableClientLike {
     listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
     deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
 }
+/** @deprecated Use AzureTableSubmissionCodec. */
 interface AzureTableEntityCodec<T> {
     readonly createPartitionKey: (submission: T) => string;
     readonly createPartitionKeyFromFormId?: (formId: string) => string;
@@ -29,16 +30,34 @@ interface AzureTableEntityCodec<T> {
     readonly serialize: (submission: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
 }
-interface AzureTableStorageOptions {
-    /** @deprecated Use schemasTableClient and submissionsTableClient. */
+interface AzureTableSubmissionCodec<T = FormSubmission> {
+    readonly createEntity: (value: T) => Record<string, unknown>;
+    readonly deserialize: (entity: Record<string, unknown>) => T;
+    readonly matchesEntity: (entity: Record<string, unknown>) => boolean;
+    readonly createPartitionKey: (value: T) => string;
+    readonly createPartitionKeyFromQuery: (formId: string, query: SubmissionPageQueryOptions) => string | undefined;
+    readonly createRowKey: (value: T) => string;
+}
+interface AzureTableStorageOptions<T = FormSubmission> {
+    /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
     readonly schemasTableClient?: AzureTableClientLike;
     readonly submissionsTableClient?: AzureTableClientLike;
+    readonly clientResolver?: (context: {
+        readonly formId: string;
+        readonly query?: SubmissionPageQueryOptions;
+    }) => AzureTableClientLike | Promise<AzureTableClientLike>;
+    readonly codec?: AzureTableSubmissionCodec<T>;
+    /** @deprecated Use codec. */
     readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
+    readonly buildSubmissionFilter?: (formId: string, query: SubmissionPageQueryOptions) => string;
+    /** @deprecated Use buildSubmissionFilter. */
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
+    readonly maxScanPages?: number;
 }
-declare const defaultAzureTableSubmissionCodec: AzureTableEntityCodec<FormSubmission>;
+declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
 declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
-declare function createAzureTableStorage(options: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
+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, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

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));
 }
@@ -40,12 +104,38 @@ function scalarMetadata(metadata) {
   );
 }
 var defaultAzureTableSubmissionCodec = {
+  createEntity: (submission) => ({
+    ...scalarMetadata(submission.metadata),
+    kind: "submission",
+    formVersion: submission.formVersion,
+    locale: submission.locale,
+    submittedAt: submission.submittedAt,
+    responseId: submission.id,
+    payload: JSON.stringify(submission)
+  }),
+  deserialize: (entity) => parseSubmission(entity.payload, "submission entity"),
+  matchesEntity: (entity) => entity.kind === "submission",
   createPartitionKey: (submission) => submission.formId,
-  createPartitionKeyFromFormId: (formId) => formId,
-  createRowKey: defaultSubmissionRowKey,
-  serialize: (submission) => ({ ...scalarMetadata(submission.metadata), payload: JSON.stringify(submission) }),
-  deserialize: (entity) => parseSubmission(entity.payload, "submission entity")
+  createPartitionKeyFromQuery: (formId) => formId,
+  createRowKey: defaultSubmissionRowKey
 };
+function legacyCodec(codec) {
+  return {
+    createEntity: (value) => ({
+      ...codec.serialize(value),
+      kind: "submission",
+      formVersion: value.formVersion,
+      locale: value.locale,
+      submittedAt: value.submittedAt,
+      responseId: value.id
+    }),
+    deserialize: codec.deserialize,
+    matchesEntity: (entity) => entity.kind === "submission",
+    createPartitionKey: codec.createPartitionKey,
+    createPartitionKeyFromQuery: (formId) => codec.createPartitionKeyFromFormId?.(formId) ?? formId,
+    createRowKey: codec.createRowKey
+  };
+}
 function parseSchemaEntity(value) {
   if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
     throw new Error("Azure Table schema entity is invalid.");
@@ -58,40 +148,73 @@ function parseSchemaEntity(value) {
   return cloneJson(schema);
 }
 function parseSubmissionEntity(value, codec) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "submission") {
+  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || !codec.matchesEntity(value)) {
     throw new Error("Azure Table submission entity is invalid.");
   }
   const submission = parseSubmission(codec.deserialize(value), `submission ${value.partitionKey}/${value.rowKey}`);
-  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey || value.formVersion !== submission.formVersion || value.locale !== submission.locale || value.submittedAt !== submission.submittedAt || value.responseId !== submission.id) {
-    throw new Error("Azure Table submission entity has inconsistent metadata.");
+  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey) {
+    throw new Error("Azure Table submission entity has inconsistent keys.");
   }
   return submission;
 }
 function escapeOData(value) {
   return value.replaceAll("'", "''");
 }
-function metadataValueToOData(value) {
+function valueToOData(value) {
   if (value === null) return "null";
   if (typeof value === "string") return `'${escapeOData(value)}'`;
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
   if (typeof value === "boolean") return String(value);
-  throw new TypeError("Azure Table metadata OData filters support only scalar JSON values.");
+  throw new TypeError("Azure Table OData filters support only scalar JSON values.");
 }
 function metadataFiltersToOData(options) {
   return Object.entries(options.metadataFilters ?? {}).map(([key, value]) => {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new TypeError(`Invalid Azure Table property name: ${key}`);
-    return `${key} eq ${metadataValueToOData(value)}`;
+    return `${key} eq ${valueToOData(value)}`;
   }).join(" and ");
 }
-function odataFilter(formId, options, extension) {
+function odataProperty(path) {
+  if (path === "id" || path === "responseId") return "responseId";
+  if (["formVersion", "locale", "submittedAt"].includes(path)) return path;
+  if (path.startsWith("metadata.")) {
+    const property = path.slice("metadata.".length);
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(property) ? property : void 0;
+  }
+  return void 0;
+}
+function submissionFilterToOData(filter) {
+  if (filter.op === "and" || filter.op === "or") {
+    const converted = filter.filters.map(submissionFilterToOData);
+    if (filter.op === "or" && converted.some((value) => value === void 0)) return void 0;
+    const available = converted.filter((value) => value !== void 0 && value.length > 0);
+    if (available.length === 0) return void 0;
+    return available.map((value) => `(${value})`).join(filter.op === "and" ? " and " : " or ");
+  }
+  const property = odataProperty(filter.path);
+  if (property === void 0) return void 0;
+  if (filter.op === "eq") return `${property} eq ${valueToOData(filter.value)}`;
+  if (filter.op === "in") {
+    if (filter.values.length === 0) return "false";
+    return filter.values.map((value) => `${property} eq ${valueToOData(value)}`).join(" or ");
+  }
+  if (filter.op === "exists") return `${property} ${filter.value ? "ne" : "eq"} null`;
   return [
-    ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
-    "kind eq 'submission'",
+    ...filter.from === void 0 ? [] : [`${property} ge ${valueToOData(filter.from)}`],
+    ...filter.to === void 0 ? [] : [`${property} le ${valueToOData(filter.to)}`]
+  ].join(" and ");
+}
+function defaultSubmissionFilter(codec, formId, options, legacyExtension) {
+  const partitionKey = codec.createPartitionKeyFromQuery(formId, options);
+  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter);
+  return [
+    ...partitionKey === void 0 ? [] : [`PartitionKey eq '${escapeOData(partitionKey)}'`],
+    ...codec === defaultAzureTableSubmissionCodec ? ["kind eq 'submission'"] : [],
     ...options.version === void 0 ? [] : [`formVersion eq ${options.version}`],
     ...options.since === void 0 ? [] : [`submittedAt ge '${escapeOData(options.since)}'`],
     ...options.until === void 0 ? [] : [`submittedAt le '${escapeOData(options.until)}'`],
     ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
-    ...extension.trim().length === 0 ? [] : [`(${extension})`]
+    ...ast === void 0 || ast.length === 0 ? [] : [`(${ast})`],
+    ...legacyExtension.trim().length === 0 ? [] : [`(${legacyExtension})`]
   ].join(" and ");
 }
 function isNotFound(error) {
@@ -100,26 +223,41 @@ function isNotFound(error) {
 function matchesBuiltInFilters(submission, formId, options) {
   return submission.formId === formId && (options.version === void 0 || submission.formVersion === options.version) && (options.since === void 0 || submission.submittedAt >= options.since) && (options.until === void 0 || submission.submittedAt <= options.until) && (options.locale === void 0 || submission.locale === options.locale);
 }
-function resolveClient(preferred, fallback, name) {
-  const client = preferred ?? fallback;
+function requireClient(client, name) {
   if (client === void 0) throw new TypeError(`${name} is required.`);
   return client;
 }
-function createAzureTableStorage(options) {
-  const schemas = resolveClient(options?.schemasTableClient, options?.client, "schemasTableClient");
-  const submissions = resolveClient(options?.submissionsTableClient, options?.client, "submissionsTableClient");
-  const codec = options.submissionCodec ?? defaultAzureTableSubmissionCodec;
-  const toODataFilter = options.toODataFilter ?? metadataFiltersToOData;
-  const partitionKeyFromFormId = codec.createPartitionKeyFromFormId ?? ((formId) => formId);
-  const queryFilter = (formId, query) => odataFilter(formId === void 0 ? void 0 : partitionKeyFromFormId(formId), query, toODataFilter(query));
+function createAzureTableStorage(options = {}) {
+  const staticSchemas = options.schemasTableClient ?? options.client;
+  const staticSubmissions = options.submissionsTableClient ?? options.client;
+  const codec = options.codec ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
+  const maxScanPages = options.maxScanPages ?? 5;
+  if (!Number.isSafeInteger(maxScanPages) || maxScanPages < 1) {
+    throw new TypeError("maxScanPages must be a positive safe integer.");
+  }
+  const resolveDynamicClient = async (formId, query) => options.clientResolver?.({ formId, ...query === void 0 ? {} : { query } });
+  const schemaClient = async (formId) => requireClient(staticSchemas ?? await resolveDynamicClient(formId), "schemasTableClient or clientResolver");
+  const submissionClient = async (formId, query) => requireClient(
+    await resolveDynamicClient(formId, query) ?? staticSubmissions,
+    "submissionsTableClient or clientResolver"
+  );
+  const queryFilter = (formId, query) => {
+    if (options.buildSubmissionFilter !== void 0) return options.buildSubmissionFilter(formId, query);
+    return defaultSubmissionFilter(
+      codec,
+      formId,
+      query,
+      options.toODataFilter?.(query) ?? metadataFiltersToOData(query)
+    );
+  };
+  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec) : void 0;
   const listSubmissionCandidates = async (formId, query) => {
+    const client = await submissionClient(formId, query);
     const found = [];
-    for await (const raw of submissions.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
-      if (raw.kind !== "submission") continue;
-      const submission = parseSubmissionEntity(raw, codec);
-      if (!matchesBuiltInFilters(submission, formId, query)) continue;
-      if (!matchesSubmissionPageFilters(submission, query)) continue;
-      found.push(submission);
+    for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
+      const submission = deserializeIfMatching(raw);
+      if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query)) continue;
+      if (matchesSubmissionPageFilters(submission, query)) found.push(submission);
     }
     return found.sort(
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
@@ -135,11 +273,11 @@ function createAzureTableStorage(options) {
         formVersion: schema.version,
         payload: JSON.stringify(schema)
       };
-      await schemas.upsertEntity(entity, "Replace");
+      await (await schemaClient(schema.id)).upsertEntity(entity, "Replace");
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await schemas.getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)));
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
@@ -147,25 +285,20 @@ function createAzureTableStorage(options) {
     },
     async listSchemas() {
       const found = [];
-      for await (const raw of schemas.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
+      for await (const raw of (await schemaClient("")).listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
         if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
       }
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
-      await schemas.deleteEntity(formId, schemaRowKey(formVersion));
+      await (await schemaClient(formId)).deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
       const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
-      await submissions.createEntity({
-        ...codec.serialize(stored),
+      await (await submissionClient(stored.formId)).createEntity({
+        ...codec.createEntity(stored),
         partitionKey: codec.createPartitionKey(stored),
-        rowKey: codec.createRowKey(stored),
-        kind: "submission",
-        formVersion: stored.formVersion,
-        locale: stored.locale,
-        submittedAt: stored.submittedAt,
-        responseId: stored.id
+        rowKey: codec.createRowKey(stored)
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -176,46 +309,147 @@ function createAzureTableStorage(options) {
     },
     async listSubmissionPage(formId, query = {}) {
       const pageSize = normalizeSubmissionPageSize(query.pageSize);
-      const iterator = submissions.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({ maxPageSize: pageSize, ...query.cursor === void 0 ? {} : { continuationToken: query.cursor } });
-      const result = await iterator.next();
-      if (result.done === true) return { items: [], hasMore: false };
-      const items = result.value.filter((raw) => raw.kind === "submission").map((raw) => parseSubmissionEntity(raw, codec)).filter(
-        (submission) => matchesBuiltInFilters(submission, formId, query) && matchesSubmissionPageFilters(submission, query)
-      );
-      const nextCursor = result.value.continuationToken;
+      const client = await submissionClient(formId, query);
+      const items = [];
+      let continuationToken = query.cursor;
+      let scannedPages = 0;
+      do {
+        const iterator = client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } }).byPage({
+          maxPageSize: Math.max(1, pageSize - items.length),
+          ...continuationToken === void 0 ? {} : { continuationToken }
+        });
+        const result = await iterator.next();
+        if (result.done === true) {
+          continuationToken = void 0;
+          break;
+        }
+        scannedPages += 1;
+        for (const raw of result.value) {
+          const submission = deserializeIfMatching(raw);
+          if (submission === void 0 || !matchesBuiltInFilters(submission, formId, query)) continue;
+          if (matchesSubmissionPageFilters(submission, query)) items.push(submission);
+        }
+        continuationToken = result.value.continuationToken;
+      } while (items.length < pageSize && continuationToken !== void 0 && scannedPages < maxScanPages);
       return {
         items,
-        hasMore: nextCursor !== void 0 && nextCursor.length > 0,
-        ...nextCursor === void 0 || nextCursor.length === 0 ? {} : { nextCursor }
+        hasMore: continuationToken !== void 0 && continuationToken.length > 0,
+        ...continuationToken === void 0 || continuationToken.length === 0 ? {} : { nextCursor: continuationToken }
       };
     },
-    async deleteSubmission(submissionId) {
-      for await (const raw of submissions.listEntities({ queryOptions: { filter: "kind eq 'submission'" } })) {
-        if (raw.kind === "submission" && raw.responseId === submissionId) {
-          if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string") {
-            throw new Error("Azure Table submission entity is invalid.");
+    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;
           }
-          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
-          return;
+          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()) {
+        const submission = deserializeIfMatching(raw);
+        if (submission?.id !== submissionId) continue;
+        if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string") {
+          throw new Error("Azure Table submission entity is invalid.");
         }
+        await client.deleteEntity(raw.partitionKey, raw.rowKey);
+        return;
       }
     },
     async clearResponses(formId) {
-      const partitionKey = partitionKeyFromFormId(formId);
-      for await (const raw of submissions.listEntities({
-        queryOptions: { filter: `PartitionKey eq '${escapeOData(partitionKey)}' and kind eq 'submission'` }
-      })) {
-        if (raw.partitionKey === partitionKey && raw.kind === "submission" && typeof raw.rowKey === "string") {
-          await submissions.deleteEntity(partitionKey, raw.rowKey);
+      const query = {};
+      const client = await submissionClient(formId, query);
+      for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
+        const submission = deserializeIfMatching(raw);
+        if (submission?.formId !== formId) continue;
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await client.deleteEntity(raw.partitionKey, raw.rowKey);
         }
       }
     },
     async clear() {
+      const schemas = await schemaClient("");
       for await (const raw of schemas.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
           await schemas.deleteEntity(raw.partitionKey, raw.rowKey);
         }
       }
+      const submissions = await submissionClient("");
       if (submissions === schemas) return;
       for await (const raw of submissions.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
@@ -228,5 +462,6 @@ function createAzureTableStorage(options) {
 export {
   createAzureTableStorage,
   defaultAzureTableSubmissionCodec,
-  metadataFiltersToOData
+  metadataFiltersToOData,
+  submissionFilterToOData
 };

package/package.json

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