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

package/README.md

@@ -15,12 +15,19 @@ pnpm add @form-engine-ts/core @form-engine-ts/storage-azure-table @azure/data-ta
 import { TableClient } from "@azure/data-tables";
 import { createAzureTableStorage } from "@form-engine-ts/storage-azure-table";
 
-const client = TableClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING!, "forms");
-const storage = createAzureTableStorage({ client });
+const schemasTableClient = TableClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING!, "forms");
+const submissionsTableClient = TableClient.fromConnectionString(
+  process.env.AZURE_STORAGE_CONNECTION_STRING!,
+  "responses"
+);
+const storage = createAzureTableStorage({ schemasTableClient, submissionsTableClient });
 
 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. Custom predicates and metadata filters are applied before page
-sizing. The caller owns table creation, credentials, retries, and the client lifecycle.
+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.

package/dist/index.cjs

@@ -20,7 +20,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  createAzureTableStorage: () => createAzureTableStorage
+  createAzureTableStorage: () => createAzureTableStorage,
+  defaultAzureTableSubmissionCodec: () => defaultAzureTableSubmissionCodec,
+  metadataFiltersToOData: () => metadataFiltersToOData
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@form-engine-ts/core");
@@ -42,127 +44,154 @@ function parseJson(value, location) {
   }
 }
 function parseSubmission(value, location) {
-  const parsed = parseJson(value, location);
+  const parsed = typeof value === "string" ? parseJson(value, location) : value;
   if (!isRecord(parsed) || typeof parsed.id !== "string" || typeof parsed.formId !== "string" || !Number.isInteger(parsed.formVersion) || typeof parsed.locale !== "string" || typeof parsed.submittedAt !== "string" || !isRecord(parsed.values) || !Object.values(parsed.values).every(isFormValue)) {
     throw new Error(`Azure Table ${location} submission is invalid.`);
   }
   return cloneJson(parsed);
 }
-function parseEntity(value) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" && value.kind !== "submission" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
-    throw new Error("Azure Table entity is invalid.");
-  }
-  return value;
+function schemaRowKey(version) {
+  return `schema_${version}`;
+}
+function defaultSubmissionRowKey(submission) {
+  return `${submission.submittedAt}_${submission.id}`;
+}
+function scalarMetadata(metadata) {
+  if (metadata === void 0) return {};
+  return Object.fromEntries(
+    Object.entries(metadata).filter((entry) => {
+      const value = entry[1];
+      return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    })
+  );
 }
+var defaultAzureTableSubmissionCodec = {
+  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")
+};
 function parseSchemaEntity(value) {
-  const entity = parseEntity(value);
-  const schema = parseJson(entity.payload, `schema ${entity.partitionKey}/${entity.rowKey}`);
+  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.");
+  }
+  const schema = parseJson(value.payload, `schema ${value.partitionKey}/${value.rowKey}`);
   (0, import_core.assertValidFormSchema)(schema);
-  if (entity.kind !== "schema" || schema.id !== entity.partitionKey || schema.version !== entity.formVersion) {
+  if (schema.id !== value.partitionKey || schema.version !== value.formVersion) {
     throw new Error("Azure Table schema entity has inconsistent metadata.");
   }
   return cloneJson(schema);
 }
-function parseSubmissionEntity(value) {
-  const entity = parseEntity(value);
-  const submission = parseSubmission(entity.payload, `submission ${entity.partitionKey}/${entity.rowKey}`);
-  if (entity.kind !== "submission" || entity.partitionKey !== submission.formId || entity.rowKey !== submissionRowKey(submission) || entity.formVersion !== submission.formVersion || entity.locale !== submission.locale || entity.submittedAt !== submission.submittedAt || entity.responseId !== submission.id) {
+function parseSubmissionEntity(value, codec) {
+  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "submission") {
+    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.");
   }
   return submission;
 }
-function schemaRowKey(version) {
-  return `schema_${version}`;
-}
-function submissionRowKey(submission) {
-  return `${submission.submittedAt}_${submission.id}`;
-}
 function escapeOData(value) {
   return value.replaceAll("'", "''");
 }
-function odataFilter(formId, options = {}) {
-  const filters = [
+function metadataValueToOData(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.");
+}
+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)}`;
+  }).join(" and ");
+}
+function odataFilter(formId, options, extension) {
+  return [
     ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
     "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)}'`]
-  ];
-  if (options.cursor !== void 0) {
-    const cursor = (0, import_core.decodeSubmissionCursor)(options.cursor);
-    filters.push(`RowKey gt '${escapeOData(`${cursor.submittedAt}_${cursor.responseId}`)}'`);
-  }
-  return filters.join(" and ");
+    ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
+    ...extension.trim().length === 0 ? [] : [`(${extension})`]
+  ].join(" and ");
 }
 function isNotFound(error) {
   return isRecord(error) && (error.statusCode === 404 || error.code === "ResourceNotFound" || error.code === "EntityNotFound");
 }
 function matchesBuiltInFilters(submission, formId, options) {
-  const cursor = options.cursor === void 0 ? void 0 : (0, import_core.decodeSubmissionCursor)(options.cursor);
-  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) && (cursor === void 0 || submission.submittedAt > cursor.submittedAt || submission.submittedAt === cursor.submittedAt && submission.id > cursor.responseId);
+  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;
+  if (client === void 0) throw new TypeError(`${name} is required.`);
+  return client;
 }
 function createAzureTableStorage(options) {
-  if (options?.client === void 0) throw new TypeError("client is required.");
-  const { client } = 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));
   const listSubmissionCandidates = async (formId, query) => {
-    const submissions = [];
-    for await (const raw of client.listEntities({ queryOptions: { filter: odataFilter(formId, query) } })) {
-      const entity = parseEntity(raw);
-      if (entity.kind !== "submission") continue;
-      const submission = parseSubmissionEntity(entity);
+    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;
-      submissions.push(submission);
+      found.push(submission);
     }
-    return submissions.sort(
+    return found.sort(
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
     );
   };
   return {
     async saveSchema(schema) {
       (0, import_core.assertValidFormSchema)(schema);
-      await client.upsertEntity(
-        {
-          partitionKey: schema.id,
-          rowKey: schemaRowKey(schema.version),
-          kind: "schema",
-          formVersion: schema.version,
-          payload: JSON.stringify(schema)
-        },
-        "Replace"
-      );
+      const entity = {
+        partitionKey: schema.id,
+        rowKey: schemaRowKey(schema.version),
+        kind: "schema",
+        formVersion: schema.version,
+        payload: JSON.stringify(schema)
+      };
+      await schemas.upsertEntity(entity, "Replace");
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await client.getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(await schemas.getEntity(formId, schemaRowKey(formVersion)));
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
       }
     },
     async listSchemas() {
-      const schemas = [];
-      for await (const raw of client.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
-        const entity = parseEntity(raw);
-        if (entity.kind === "schema") schemas.push(parseSchemaEntity(entity));
+      const found = [];
+      for await (const raw of schemas.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
+        if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
       }
-      return schemas.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
+      return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
-      await client.deleteEntity(formId, schemaRowKey(formVersion));
+      await schemas.deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
-      const stored = parseSubmission(JSON.stringify(submission), `input ${String(submission?.id)}`);
-      await client.createEntity({
-        partitionKey: stored.formId,
-        rowKey: submissionRowKey(stored),
+      const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      await submissions.createEntity({
+        ...codec.serialize(stored),
+        partitionKey: codec.createPartitionKey(stored),
+        rowKey: codec.createRowKey(stored),
         kind: "submission",
         formVersion: stored.formVersion,
         locale: stored.locale,
         submittedAt: stored.submittedAt,
-        responseId: stored.id,
-        payload: JSON.stringify(stored)
+        responseId: stored.id
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -173,44 +202,58 @@ function createAzureTableStorage(options) {
     },
     async listSubmissionPage(formId, query = {}) {
       const pageSize = (0, import_core.normalizeSubmissionPageSize)(query.pageSize);
-      const candidates = await listSubmissionCandidates(formId, query);
-      const hasMore = candidates.length > pageSize;
-      const items = candidates.slice(0, pageSize);
-      const last = items.at(-1);
+      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;
       return {
         items,
-        hasMore,
-        ...hasMore && last !== void 0 ? { nextCursor: (0, import_core.encodeSubmissionCursor)({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
+        hasMore: nextCursor !== void 0 && nextCursor.length > 0,
+        ...nextCursor === void 0 || nextCursor.length === 0 ? {} : { nextCursor }
       };
     },
     async deleteSubmission(submissionId) {
-      for await (const raw of client.listEntities({ queryOptions: { filter: "kind eq 'submission'" } })) {
-        const entity = parseEntity(raw);
-        if (entity.kind === "submission" && entity.responseId === submissionId) {
-          await client.deleteEntity(entity.partitionKey, entity.rowKey);
+      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.");
+          }
+          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
           return;
         }
       }
     },
     async clearResponses(formId) {
-      for await (const raw of client.listEntities({
-        queryOptions: { filter: `PartitionKey eq '${escapeOData(formId)}' and kind eq 'submission'` }
+      const partitionKey = partitionKeyFromFormId(formId);
+      for await (const raw of submissions.listEntities({
+        queryOptions: { filter: `PartitionKey eq '${escapeOData(partitionKey)}' and kind eq 'submission'` }
       })) {
-        const entity = parseEntity(raw);
-        if (entity.partitionKey === formId && entity.kind === "submission") {
-          await client.deleteEntity(entity.partitionKey, entity.rowKey);
+        if (raw.partitionKey === partitionKey && raw.kind === "submission" && typeof raw.rowKey === "string") {
+          await submissions.deleteEntity(partitionKey, raw.rowKey);
         }
       }
     },
     async clear() {
-      for await (const raw of client.listEntities()) {
-        const entity = parseEntity(raw);
-        await client.deleteEntity(entity.partitionKey, entity.rowKey);
+      for await (const raw of schemas.listEntities()) {
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await schemas.deleteEntity(raw.partitionKey, raw.rowKey);
+        }
+      }
+      if (submissions === schemas) return;
+      for await (const raw of submissions.listEntities()) {
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
+        }
       }
     }
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createAzureTableStorage
+  createAzureTableStorage,
+  defaultAzureTableSubmissionCodec,
+  metadataFiltersToOData
 });

package/dist/index.d.cts

@@ -1,20 +1,44 @@
-import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
         readonly filter?: string;
     };
 }
+interface AzureTablePageSettings {
+    readonly maxPageSize?: number;
+    readonly continuationToken?: string;
+}
+interface AzureTableEntityPage extends ReadonlyArray<Record<string, unknown>> {
+    readonly continuationToken?: string;
+}
+interface AzureTableEntityIterator extends AsyncIterable<Record<string, unknown>> {
+    byPage(settings?: AzureTablePageSettings): AsyncIterableIterator<AzureTableEntityPage>;
+}
 interface AzureTableClientLike {
     createEntity(entity: Record<string, unknown>): Promise<unknown>;
     upsertEntity(entity: Record<string, unknown>, mode?: "Merge" | "Replace"): Promise<unknown>;
     getEntity(partitionKey: string, rowKey: string): Promise<Record<string, unknown>>;
-    listEntities(options?: AzureTableListOptions): AsyncIterable<Record<string, unknown>>;
+    listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
     deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
 }
+interface AzureTableEntityCodec<T> {
+    readonly createPartitionKey: (submission: T) => string;
+    readonly createPartitionKeyFromFormId?: (formId: string) => string;
+    readonly createRowKey: (submission: T) => string;
+    readonly serialize: (submission: T) => Record<string, unknown>;
+    readonly deserialize: (entity: Record<string, unknown>) => T;
+}
 interface AzureTableStorageOptions {
-    readonly client: AzureTableClientLike;
+    /** @deprecated Use schemasTableClient and submissionsTableClient. */
+    readonly client?: AzureTableClientLike;
+    readonly schemasTableClient?: AzureTableClientLike;
+    readonly submissionsTableClient?: AzureTableClientLike;
+    readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
+    readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
 }
+declare const defaultAzureTableSubmissionCodec: AzureTableEntityCodec<FormSubmission>;
+declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
 declare function createAzureTableStorage(options: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableListOptions, type AzureTableStorageOptions, createAzureTableStorage };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData };

package/dist/index.d.ts

@@ -1,20 +1,44 @@
-import { PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
         readonly filter?: string;
     };
 }
+interface AzureTablePageSettings {
+    readonly maxPageSize?: number;
+    readonly continuationToken?: string;
+}
+interface AzureTableEntityPage extends ReadonlyArray<Record<string, unknown>> {
+    readonly continuationToken?: string;
+}
+interface AzureTableEntityIterator extends AsyncIterable<Record<string, unknown>> {
+    byPage(settings?: AzureTablePageSettings): AsyncIterableIterator<AzureTableEntityPage>;
+}
 interface AzureTableClientLike {
     createEntity(entity: Record<string, unknown>): Promise<unknown>;
     upsertEntity(entity: Record<string, unknown>, mode?: "Merge" | "Replace"): Promise<unknown>;
     getEntity(partitionKey: string, rowKey: string): Promise<Record<string, unknown>>;
-    listEntities(options?: AzureTableListOptions): AsyncIterable<Record<string, unknown>>;
+    listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
     deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
 }
+interface AzureTableEntityCodec<T> {
+    readonly createPartitionKey: (submission: T) => string;
+    readonly createPartitionKeyFromFormId?: (formId: string) => string;
+    readonly createRowKey: (submission: T) => string;
+    readonly serialize: (submission: T) => Record<string, unknown>;
+    readonly deserialize: (entity: Record<string, unknown>) => T;
+}
 interface AzureTableStorageOptions {
-    readonly client: AzureTableClientLike;
+    /** @deprecated Use schemasTableClient and submissionsTableClient. */
+    readonly client?: AzureTableClientLike;
+    readonly schemasTableClient?: AzureTableClientLike;
+    readonly submissionsTableClient?: AzureTableClientLike;
+    readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
+    readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
 }
+declare const defaultAzureTableSubmissionCodec: AzureTableEntityCodec<FormSubmission>;
+declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
 declare function createAzureTableStorage(options: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableListOptions, type AzureTableStorageOptions, createAzureTableStorage };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData };

package/dist/index.js

@@ -1,11 +1,5 @@
 // src/index.ts
-import {
-  assertValidFormSchema,
-  decodeSubmissionCursor,
-  encodeSubmissionCursor,
-  matchesSubmissionPageFilters,
-  normalizeSubmissionPageSize
-} from "@form-engine-ts/core";
+import { assertValidFormSchema, matchesSubmissionPageFilters, normalizeSubmissionPageSize } from "@form-engine-ts/core";
 function cloneJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
@@ -24,127 +18,154 @@ function parseJson(value, location) {
   }
 }
 function parseSubmission(value, location) {
-  const parsed = parseJson(value, location);
+  const parsed = typeof value === "string" ? parseJson(value, location) : value;
   if (!isRecord(parsed) || typeof parsed.id !== "string" || typeof parsed.formId !== "string" || !Number.isInteger(parsed.formVersion) || typeof parsed.locale !== "string" || typeof parsed.submittedAt !== "string" || !isRecord(parsed.values) || !Object.values(parsed.values).every(isFormValue)) {
     throw new Error(`Azure Table ${location} submission is invalid.`);
   }
   return cloneJson(parsed);
 }
-function parseEntity(value) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" && value.kind !== "submission" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
-    throw new Error("Azure Table entity is invalid.");
-  }
-  return value;
+function schemaRowKey(version) {
+  return `schema_${version}`;
+}
+function defaultSubmissionRowKey(submission) {
+  return `${submission.submittedAt}_${submission.id}`;
+}
+function scalarMetadata(metadata) {
+  if (metadata === void 0) return {};
+  return Object.fromEntries(
+    Object.entries(metadata).filter((entry) => {
+      const value = entry[1];
+      return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+    })
+  );
 }
+var defaultAzureTableSubmissionCodec = {
+  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")
+};
 function parseSchemaEntity(value) {
-  const entity = parseEntity(value);
-  const schema = parseJson(entity.payload, `schema ${entity.partitionKey}/${entity.rowKey}`);
+  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.");
+  }
+  const schema = parseJson(value.payload, `schema ${value.partitionKey}/${value.rowKey}`);
   assertValidFormSchema(schema);
-  if (entity.kind !== "schema" || schema.id !== entity.partitionKey || schema.version !== entity.formVersion) {
+  if (schema.id !== value.partitionKey || schema.version !== value.formVersion) {
     throw new Error("Azure Table schema entity has inconsistent metadata.");
   }
   return cloneJson(schema);
 }
-function parseSubmissionEntity(value) {
-  const entity = parseEntity(value);
-  const submission = parseSubmission(entity.payload, `submission ${entity.partitionKey}/${entity.rowKey}`);
-  if (entity.kind !== "submission" || entity.partitionKey !== submission.formId || entity.rowKey !== submissionRowKey(submission) || entity.formVersion !== submission.formVersion || entity.locale !== submission.locale || entity.submittedAt !== submission.submittedAt || entity.responseId !== submission.id) {
+function parseSubmissionEntity(value, codec) {
+  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "submission") {
+    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.");
   }
   return submission;
 }
-function schemaRowKey(version) {
-  return `schema_${version}`;
-}
-function submissionRowKey(submission) {
-  return `${submission.submittedAt}_${submission.id}`;
-}
 function escapeOData(value) {
   return value.replaceAll("'", "''");
 }
-function odataFilter(formId, options = {}) {
-  const filters = [
+function metadataValueToOData(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.");
+}
+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)}`;
+  }).join(" and ");
+}
+function odataFilter(formId, options, extension) {
+  return [
     ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
     "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)}'`]
-  ];
-  if (options.cursor !== void 0) {
-    const cursor = decodeSubmissionCursor(options.cursor);
-    filters.push(`RowKey gt '${escapeOData(`${cursor.submittedAt}_${cursor.responseId}`)}'`);
-  }
-  return filters.join(" and ");
+    ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
+    ...extension.trim().length === 0 ? [] : [`(${extension})`]
+  ].join(" and ");
 }
 function isNotFound(error) {
   return isRecord(error) && (error.statusCode === 404 || error.code === "ResourceNotFound" || error.code === "EntityNotFound");
 }
 function matchesBuiltInFilters(submission, formId, options) {
-  const cursor = options.cursor === void 0 ? void 0 : decodeSubmissionCursor(options.cursor);
-  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) && (cursor === void 0 || submission.submittedAt > cursor.submittedAt || submission.submittedAt === cursor.submittedAt && submission.id > cursor.responseId);
+  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;
+  if (client === void 0) throw new TypeError(`${name} is required.`);
+  return client;
 }
 function createAzureTableStorage(options) {
-  if (options?.client === void 0) throw new TypeError("client is required.");
-  const { client } = 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));
   const listSubmissionCandidates = async (formId, query) => {
-    const submissions = [];
-    for await (const raw of client.listEntities({ queryOptions: { filter: odataFilter(formId, query) } })) {
-      const entity = parseEntity(raw);
-      if (entity.kind !== "submission") continue;
-      const submission = parseSubmissionEntity(entity);
+    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;
-      submissions.push(submission);
+      found.push(submission);
     }
-    return submissions.sort(
+    return found.sort(
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
     );
   };
   return {
     async saveSchema(schema) {
       assertValidFormSchema(schema);
-      await client.upsertEntity(
-        {
-          partitionKey: schema.id,
-          rowKey: schemaRowKey(schema.version),
-          kind: "schema",
-          formVersion: schema.version,
-          payload: JSON.stringify(schema)
-        },
-        "Replace"
-      );
+      const entity = {
+        partitionKey: schema.id,
+        rowKey: schemaRowKey(schema.version),
+        kind: "schema",
+        formVersion: schema.version,
+        payload: JSON.stringify(schema)
+      };
+      await schemas.upsertEntity(entity, "Replace");
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await client.getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(await schemas.getEntity(formId, schemaRowKey(formVersion)));
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
       }
     },
     async listSchemas() {
-      const schemas = [];
-      for await (const raw of client.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
-        const entity = parseEntity(raw);
-        if (entity.kind === "schema") schemas.push(parseSchemaEntity(entity));
+      const found = [];
+      for await (const raw of schemas.listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
+        if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
       }
-      return schemas.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
+      return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
-      await client.deleteEntity(formId, schemaRowKey(formVersion));
+      await schemas.deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
-      const stored = parseSubmission(JSON.stringify(submission), `input ${String(submission?.id)}`);
-      await client.createEntity({
-        partitionKey: stored.formId,
-        rowKey: submissionRowKey(stored),
+      const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      await submissions.createEntity({
+        ...codec.serialize(stored),
+        partitionKey: codec.createPartitionKey(stored),
+        rowKey: codec.createRowKey(stored),
         kind: "submission",
         formVersion: stored.formVersion,
         locale: stored.locale,
         submittedAt: stored.submittedAt,
-        responseId: stored.id,
-        payload: JSON.stringify(stored)
+        responseId: stored.id
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -155,43 +176,57 @@ function createAzureTableStorage(options) {
     },
     async listSubmissionPage(formId, query = {}) {
       const pageSize = normalizeSubmissionPageSize(query.pageSize);
-      const candidates = await listSubmissionCandidates(formId, query);
-      const hasMore = candidates.length > pageSize;
-      const items = candidates.slice(0, pageSize);
-      const last = items.at(-1);
+      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;
       return {
         items,
-        hasMore,
-        ...hasMore && last !== void 0 ? { nextCursor: encodeSubmissionCursor({ submittedAt: last.submittedAt, responseId: last.id }) } : {}
+        hasMore: nextCursor !== void 0 && nextCursor.length > 0,
+        ...nextCursor === void 0 || nextCursor.length === 0 ? {} : { nextCursor }
       };
     },
     async deleteSubmission(submissionId) {
-      for await (const raw of client.listEntities({ queryOptions: { filter: "kind eq 'submission'" } })) {
-        const entity = parseEntity(raw);
-        if (entity.kind === "submission" && entity.responseId === submissionId) {
-          await client.deleteEntity(entity.partitionKey, entity.rowKey);
+      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.");
+          }
+          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
           return;
         }
       }
     },
     async clearResponses(formId) {
-      for await (const raw of client.listEntities({
-        queryOptions: { filter: `PartitionKey eq '${escapeOData(formId)}' and kind eq 'submission'` }
+      const partitionKey = partitionKeyFromFormId(formId);
+      for await (const raw of submissions.listEntities({
+        queryOptions: { filter: `PartitionKey eq '${escapeOData(partitionKey)}' and kind eq 'submission'` }
       })) {
-        const entity = parseEntity(raw);
-        if (entity.partitionKey === formId && entity.kind === "submission") {
-          await client.deleteEntity(entity.partitionKey, entity.rowKey);
+        if (raw.partitionKey === partitionKey && raw.kind === "submission" && typeof raw.rowKey === "string") {
+          await submissions.deleteEntity(partitionKey, raw.rowKey);
         }
       }
     },
     async clear() {
-      for await (const raw of client.listEntities()) {
-        const entity = parseEntity(raw);
-        await client.deleteEntity(entity.partitionKey, entity.rowKey);
+      for await (const raw of schemas.listEntities()) {
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await schemas.deleteEntity(raw.partitionKey, raw.rowKey);
+        }
+      }
+      if (submissions === schemas) return;
+      for await (const raw of submissions.listEntities()) {
+        if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
+          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
+        }
       }
     }
   };
 }
 export {
-  createAzureTableStorage
+  createAzureTableStorage,
+  defaultAzureTableSubmissionCodec,
+  metadataFiltersToOData
 };

package/package.json

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