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

package/README.md

@@ -25,9 +25,13 @@ 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.

package/dist/index.cjs

@@ -22,7 +22,8 @@ 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");
@@ -66,12 +67,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 +111,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 [
+    ...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 [
-    ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
-    "kind eq 'submission'",
+    ...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 +186,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 +236,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 +248,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 +272,65 @@ 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.");
-          }
-          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
-          return;
+      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 +344,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

@@ -40,12 +40,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 +84,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 [
+    ...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 [
-    ...formId === void 0 ? [] : [`PartitionKey eq '${escapeOData(formId)}'`],
-    "kind eq 'submission'",
+    ...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 +159,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 +209,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 +221,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 +245,65 @@ 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.");
-          }
-          await submissions.deleteEntity(raw.partitionKey, raw.rowKey);
-          return;
+      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 +316,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.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "2.6.0"
+    "@form-engine-ts/core": "2.7.0"
   },
   "peerDependencies": {
     "@azure/data-tables": "^13.3.2"