@form-engine-ts/storage-azure-table 8.0.0 → 8.0.1

package/README.md

@@ -48,6 +48,10 @@ Applications must migrate legacy data to the canonical `values` contract before
 source can be supplied per call as `saveSubmission(submission, { validation })`. A source can be a FormSchema, a
 Zod-compatible object with `safeParse`, or an async validator callback.
 
+`saveSubmissionWithinLimit(submission, maxResponses, options?)` uses an ETag-protected capacity entity and an Azure
+Table transaction to update capacity and create the response together. The submission codec must place a form's
+responses in one partition (the default codec does), and the injected client must expose `submitTransaction`.
+
 `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

package/dist/index.cjs

@@ -351,6 +351,9 @@ function isDuplicateEntityError(error) {
   const message = error instanceof Error ? error.message : isRecord(error) ? String(error.message ?? "") : "";
   return isRecord(error) && (error.statusCode === 409 || error.code === "EntityAlreadyExists") || /alreadyexists|duplicate/iu.test(message);
 }
+function isPreconditionFailed(error) {
+  return isRecord(error) && (error.statusCode === 412 || error.code === "UpdateConditionNotSatisfied");
+}
 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);
 }
@@ -532,6 +535,110 @@ function createAzureTableStorage(options = {}) {
         return { status: "created", submission: stored, payloadHash };
       }
     },
+    async saveSubmissionWithinLimit(submission, maxResponses, saveOptions = {}) {
+      if (!Number.isInteger(maxResponses) || maxResponses < 1)
+        throw new RangeError("maxResponses must be a positive integer.");
+      ensureWritable();
+      const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      const explicitValidation = saveOptions.validator ?? saveOptions.validation;
+      const configuredValidation = options.submissionValidator ?? options.submissionSchema ?? options.validator ?? options.schema ?? options.validation;
+      if (explicitValidation !== void 0) await (0, import_core.assertValidFormSubmissionWith)(explicitValidation, stored);
+      if (explicitValidation === void 0 && configuredValidation !== void 0) {
+        await (0, import_core.assertValidFormSubmissionWith)(configuredValidation, stored);
+      }
+      if (options.validateSubmissions === true || saveOptions.validateAgainstSchema === true) {
+        const schema = parseSchemaEntity(
+          await (await schemaClient(stored.formId)).getEntity(stored.formId, schemaRowKey(stored.formVersion))
+        );
+        (0, import_core.assertValidFormSubmission)(schema, stored, options.schemaValidation);
+      }
+      const client = await submissionClient(stored.formId);
+      if (client.submitTransaction === void 0)
+        throw Object.assign(new Error("Azure Table transactions are required for atomic response limits."), {
+          code: "transaction_unsupported"
+        });
+      const partitionKey = codec.createPartitionKey(stored);
+      if (codec.createPartitionKeyFromQuery(stored.formId, { version: stored.formVersion }) !== partitionKey)
+        throw new Error("Atomic response limits require one Azure Table partition per form.");
+      const rowKey = codec.createRowKey(stored);
+      const payloadHash = await (0, import_core.hashFormSubmissionPayload)(stored);
+      const keys = physicalKeyNames(options.fieldMapping);
+      const createdEntity = codec.createEntity(stored);
+      assertCanonicalSubmissionEntity(createdEntity);
+      const submissionEntity = {
+        ...mappedSubmissionEntity(createdEntity, stored, options.fieldMapping, valueCodec),
+        payloadHash,
+        partitionKey,
+        rowKey,
+        [keys.partitionKey]: partitionKey,
+        [keys.rowKey]: rowKey
+      };
+      const idempotent = saveOptions.idempotent ?? options.idempotentSubmissions ?? options.idempotency ?? false;
+      try {
+        const existingEntity = await client.getEntity(partitionKey, rowKey);
+        if (!idempotent) throw new Error(`A submission with ID "${stored.id}" already exists.`);
+        const existing = parseSubmissionEntity(existingEntity, codec, options.fieldMapping, valueCodec);
+        const existingPayloadHash = typeof existingEntity.payloadHash === "string" ? existingEntity.payloadHash : await (0, import_core.hashFormSubmissionPayload)(existing);
+        if (existingPayloadHash === payloadHash) return { status: "duplicate", submission: existing, payloadHash };
+        return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash };
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
+      }
+      const capacityRowKey = `capacity_${stored.formVersion}`;
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        let capacity;
+        try {
+          capacity = await client.getEntity(partitionKey, capacityRowKey);
+        } catch (error) {
+          if (!isNotFound(error)) throw error;
+          const count2 = await adapter.countSubmissions(stored.formId, stored.formVersion);
+          try {
+            await client.createEntity({ partitionKey, rowKey: capacityRowKey, kind: "capacity", count: count2 });
+          } catch (createError) {
+            if (!isDuplicateEntityError(createError)) throw createError;
+          }
+          continue;
+        }
+        const count = await adapter.countSubmissions(stored.formId, stored.formVersion);
+        if (count >= maxResponses) return { status: "limit_reached" };
+        if (typeof capacity.etag !== "string") throw new Error("Azure Table capacity entity is missing an ETag.");
+        const actions = [
+          [
+            "update",
+            { ...capacity, partitionKey, rowKey: capacityRowKey, count: count + 1 },
+            "Replace",
+            { etag: capacity.etag }
+          ],
+          ["create", submissionEntity]
+        ];
+        try {
+          await client.submitTransaction(actions);
+          if (idempotent) return { status: "created", submission: stored, payloadHash };
+          return;
+        } catch (error) {
+          if (isPreconditionFailed(error)) {
+            try {
+              const racedEntity = await client.getEntity(partitionKey, rowKey);
+              if (!idempotent) throw new Error(`A submission with ID "${stored.id}" already exists.`);
+              const raced = parseSubmissionEntity(racedEntity, codec, options.fieldMapping, valueCodec);
+              const existingPayloadHash2 = typeof racedEntity.payloadHash === "string" ? racedEntity.payloadHash : await (0, import_core.hashFormSubmissionPayload)(raced);
+              if (existingPayloadHash2 === payloadHash) return { status: "duplicate", submission: raced, payloadHash };
+              return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash: existingPayloadHash2 };
+            } catch (lookupError) {
+              if (!isNotFound(lookupError)) throw lookupError;
+            }
+            continue;
+          }
+          if (!idempotent || !isDuplicateEntityError(error)) throw error;
+          const existingEntity = await client.getEntity(partitionKey, rowKey);
+          const existing = parseSubmissionEntity(existingEntity, codec, options.fieldMapping, valueCodec);
+          const existingPayloadHash = typeof existingEntity.payloadHash === "string" ? existingEntity.payloadHash : await (0, import_core.hashFormSubmissionPayload)(existing);
+          if (existingPayloadHash === payloadHash) return { status: "duplicate", submission: existing, payloadHash };
+          return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash };
+        }
+      }
+      throw new Error("Azure Table response capacity update conflicted too many times.");
+    },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
       return listSubmissionCandidates(formId, {
         ...queryOptions,

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { TransactionAction } from '@azure/data-tables';
 import { BaseSubmissionMetadata, PagedSubmissionStorageAdapter, TextAnswerPageQueryOptions, TextAnswerPage, TypedSubmissionPageQueryOptions, TypedSubmissionPage, FormSubmission, FormSchema, SubmissionPageQueryOptions, FormAnalytics, StorageSubmissionExportOptions, FormSubmissionValidationSource, ValidateFormSchemaOptions, FormLifecycleOptions, FormSubmissionValidator, SaveSubmissionOptions, SubmissionSaveResult, SubmissionFilter, JsonValue, TypedTextAnswerPage } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
@@ -23,6 +24,7 @@ interface AzureTableClientLike {
     deleteEntity(partitionKey: string, rowKey: string, options?: {
         readonly etag?: string;
     }): Promise<unknown>;
+    readonly submitTransaction?: (actions: TransactionAction[]) => Promise<unknown>;
 }
 type AzureTableSubmissionEntity = Record<string, unknown> & {
     readonly answers?: never;
@@ -97,8 +99,11 @@ interface AzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata = BaseSu
     readonly exportResponsesToCsv: (schema: FormSchema, options?: StorageSubmissionExportOptions) => Promise<string>;
     readonly validateSubmission: (submission: FormSubmission, source?: FormSubmissionValidationSource) => Promise<void>;
 }
-type TypedAzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata | undefined = undefined> = Omit<PagedSubmissionStorageAdapter, "saveSubmission" | "listSubmissionPage" | "listTextAnswerPage"> & {
+type TypedAzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata | undefined = undefined> = Omit<PagedSubmissionStorageAdapter, "saveSubmission" | "saveSubmissionWithinLimit" | "listSubmissionPage" | "listTextAnswerPage"> & {
     readonly saveSubmission: (submission: FormSubmission<TMeta>, options?: SaveSubmissionOptions) => Promise<undefined | SubmissionSaveResult<TMeta>>;
+    readonly saveSubmissionWithinLimit: (submission: FormSubmission<TMeta>, maxResponses: number, options?: SaveSubmissionOptions) => Promise<undefined | SubmissionSaveResult<TMeta> | {
+        readonly status: "limit_reached";
+    }>;
     readonly listSubmissionPage: (formId: string, options?: SubmissionPageQueryOptions & {
         readonly filter?: SubmissionFilter | ((submission: FormSubmission<TMeta>) => boolean);
         readonly metadataFilters?: TMeta extends BaseSubmissionMetadata ? Partial<TMeta> : Readonly<Record<string, JsonValue>>;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { TransactionAction } from '@azure/data-tables';
 import { BaseSubmissionMetadata, PagedSubmissionStorageAdapter, TextAnswerPageQueryOptions, TextAnswerPage, TypedSubmissionPageQueryOptions, TypedSubmissionPage, FormSubmission, FormSchema, SubmissionPageQueryOptions, FormAnalytics, StorageSubmissionExportOptions, FormSubmissionValidationSource, ValidateFormSchemaOptions, FormLifecycleOptions, FormSubmissionValidator, SaveSubmissionOptions, SubmissionSaveResult, SubmissionFilter, JsonValue, TypedTextAnswerPage } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
@@ -23,6 +24,7 @@ interface AzureTableClientLike {
     deleteEntity(partitionKey: string, rowKey: string, options?: {
         readonly etag?: string;
     }): Promise<unknown>;
+    readonly submitTransaction?: (actions: TransactionAction[]) => Promise<unknown>;
 }
 type AzureTableSubmissionEntity = Record<string, unknown> & {
     readonly answers?: never;
@@ -97,8 +99,11 @@ interface AzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata = BaseSu
     readonly exportResponsesToCsv: (schema: FormSchema, options?: StorageSubmissionExportOptions) => Promise<string>;
     readonly validateSubmission: (submission: FormSubmission, source?: FormSubmissionValidationSource) => Promise<void>;
 }
-type TypedAzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata | undefined = undefined> = Omit<PagedSubmissionStorageAdapter, "saveSubmission" | "listSubmissionPage" | "listTextAnswerPage"> & {
+type TypedAzureTableStorageAdapter<TMeta extends BaseSubmissionMetadata | undefined = undefined> = Omit<PagedSubmissionStorageAdapter, "saveSubmission" | "saveSubmissionWithinLimit" | "listSubmissionPage" | "listTextAnswerPage"> & {
     readonly saveSubmission: (submission: FormSubmission<TMeta>, options?: SaveSubmissionOptions) => Promise<undefined | SubmissionSaveResult<TMeta>>;
+    readonly saveSubmissionWithinLimit: (submission: FormSubmission<TMeta>, maxResponses: number, options?: SaveSubmissionOptions) => Promise<undefined | SubmissionSaveResult<TMeta> | {
+        readonly status: "limit_reached";
+    }>;
     readonly listSubmissionPage: (formId: string, options?: SubmissionPageQueryOptions & {
         readonly filter?: SubmissionFilter | ((submission: FormSubmission<TMeta>) => boolean);
         readonly metadataFilters?: TMeta extends BaseSubmissionMetadata ? Partial<TMeta> : Readonly<Record<string, JsonValue>>;

package/dist/index.js

@@ -333,6 +333,9 @@ function isDuplicateEntityError(error) {
   const message = error instanceof Error ? error.message : isRecord(error) ? String(error.message ?? "") : "";
   return isRecord(error) && (error.statusCode === 409 || error.code === "EntityAlreadyExists") || /alreadyexists|duplicate/iu.test(message);
 }
+function isPreconditionFailed(error) {
+  return isRecord(error) && (error.statusCode === 412 || error.code === "UpdateConditionNotSatisfied");
+}
 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);
 }
@@ -514,6 +517,110 @@ function createAzureTableStorage(options = {}) {
         return { status: "created", submission: stored, payloadHash };
       }
     },
+    async saveSubmissionWithinLimit(submission, maxResponses, saveOptions = {}) {
+      if (!Number.isInteger(maxResponses) || maxResponses < 1)
+        throw new RangeError("maxResponses must be a positive integer.");
+      ensureWritable();
+      const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      const explicitValidation = saveOptions.validator ?? saveOptions.validation;
+      const configuredValidation = options.submissionValidator ?? options.submissionSchema ?? options.validator ?? options.schema ?? options.validation;
+      if (explicitValidation !== void 0) await assertValidFormSubmissionWith(explicitValidation, stored);
+      if (explicitValidation === void 0 && configuredValidation !== void 0) {
+        await assertValidFormSubmissionWith(configuredValidation, stored);
+      }
+      if (options.validateSubmissions === true || saveOptions.validateAgainstSchema === true) {
+        const schema = parseSchemaEntity(
+          await (await schemaClient(stored.formId)).getEntity(stored.formId, schemaRowKey(stored.formVersion))
+        );
+        assertValidFormSubmission(schema, stored, options.schemaValidation);
+      }
+      const client = await submissionClient(stored.formId);
+      if (client.submitTransaction === void 0)
+        throw Object.assign(new Error("Azure Table transactions are required for atomic response limits."), {
+          code: "transaction_unsupported"
+        });
+      const partitionKey = codec.createPartitionKey(stored);
+      if (codec.createPartitionKeyFromQuery(stored.formId, { version: stored.formVersion }) !== partitionKey)
+        throw new Error("Atomic response limits require one Azure Table partition per form.");
+      const rowKey = codec.createRowKey(stored);
+      const payloadHash = await hashFormSubmissionPayload(stored);
+      const keys = physicalKeyNames(options.fieldMapping);
+      const createdEntity = codec.createEntity(stored);
+      assertCanonicalSubmissionEntity(createdEntity);
+      const submissionEntity = {
+        ...mappedSubmissionEntity(createdEntity, stored, options.fieldMapping, valueCodec),
+        payloadHash,
+        partitionKey,
+        rowKey,
+        [keys.partitionKey]: partitionKey,
+        [keys.rowKey]: rowKey
+      };
+      const idempotent = saveOptions.idempotent ?? options.idempotentSubmissions ?? options.idempotency ?? false;
+      try {
+        const existingEntity = await client.getEntity(partitionKey, rowKey);
+        if (!idempotent) throw new Error(`A submission with ID "${stored.id}" already exists.`);
+        const existing = parseSubmissionEntity(existingEntity, codec, options.fieldMapping, valueCodec);
+        const existingPayloadHash = typeof existingEntity.payloadHash === "string" ? existingEntity.payloadHash : await hashFormSubmissionPayload(existing);
+        if (existingPayloadHash === payloadHash) return { status: "duplicate", submission: existing, payloadHash };
+        return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash };
+      } catch (error) {
+        if (!isNotFound(error)) throw error;
+      }
+      const capacityRowKey = `capacity_${stored.formVersion}`;
+      for (let attempt = 0; attempt < 5; attempt += 1) {
+        let capacity;
+        try {
+          capacity = await client.getEntity(partitionKey, capacityRowKey);
+        } catch (error) {
+          if (!isNotFound(error)) throw error;
+          const count2 = await adapter.countSubmissions(stored.formId, stored.formVersion);
+          try {
+            await client.createEntity({ partitionKey, rowKey: capacityRowKey, kind: "capacity", count: count2 });
+          } catch (createError) {
+            if (!isDuplicateEntityError(createError)) throw createError;
+          }
+          continue;
+        }
+        const count = await adapter.countSubmissions(stored.formId, stored.formVersion);
+        if (count >= maxResponses) return { status: "limit_reached" };
+        if (typeof capacity.etag !== "string") throw new Error("Azure Table capacity entity is missing an ETag.");
+        const actions = [
+          [
+            "update",
+            { ...capacity, partitionKey, rowKey: capacityRowKey, count: count + 1 },
+            "Replace",
+            { etag: capacity.etag }
+          ],
+          ["create", submissionEntity]
+        ];
+        try {
+          await client.submitTransaction(actions);
+          if (idempotent) return { status: "created", submission: stored, payloadHash };
+          return;
+        } catch (error) {
+          if (isPreconditionFailed(error)) {
+            try {
+              const racedEntity = await client.getEntity(partitionKey, rowKey);
+              if (!idempotent) throw new Error(`A submission with ID "${stored.id}" already exists.`);
+              const raced = parseSubmissionEntity(racedEntity, codec, options.fieldMapping, valueCodec);
+              const existingPayloadHash2 = typeof racedEntity.payloadHash === "string" ? racedEntity.payloadHash : await hashFormSubmissionPayload(raced);
+              if (existingPayloadHash2 === payloadHash) return { status: "duplicate", submission: raced, payloadHash };
+              return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash: existingPayloadHash2 };
+            } catch (lookupError) {
+              if (!isNotFound(lookupError)) throw lookupError;
+            }
+            continue;
+          }
+          if (!idempotent || !isDuplicateEntityError(error)) throw error;
+          const existingEntity = await client.getEntity(partitionKey, rowKey);
+          const existing = parseSubmissionEntity(existingEntity, codec, options.fieldMapping, valueCodec);
+          const existingPayloadHash = typeof existingEntity.payloadHash === "string" ? existingEntity.payloadHash : await hashFormSubmissionPayload(existing);
+          if (existingPayloadHash === payloadHash) return { status: "duplicate", submission: existing, payloadHash };
+          return { status: "conflict", submissionId: stored.id, payloadHash, existingPayloadHash };
+        }
+      }
+      throw new Error("Azure Table response capacity update conflicted too many times.");
+    },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
       return listSubmissionCandidates(formId, {
         ...queryOptions,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage-azure-table",
-  "version": "8.0.0",
+  "version": "8.0.1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "8.0.0"
+    "@form-engine-ts/core": "8.0.1"
   },
   "peerDependencies": {
     "@azure/data-tables": "^13.3.2"
@@ -51,7 +51,7 @@
   },
   "devDependencies": {
     "@azure/data-tables": "^13.3.2",
-    "@form-engine-ts/storage": "8.0.0"
+    "@form-engine-ts/storage": "8.0.1"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",