@form-engine-ts/storage 8.0.0 → 8.0.2

package/README.md

@@ -27,18 +27,24 @@ operations use the same core contracts regardless of the backing database.
 `countSubmissions(formId, formVersion?, options?)`. Implementations must apply inclusive `since` and `until` filters
 from `SubmissionQueryOptions`; submission pipelines no longer fall back to scanning every page.
 
+Built-in adapters also expose `saveSubmissionWithinLimit(submission, maxResponses, options?)`. This operation checks
+capacity and saves atomically for one form version, preserves idempotent duplicate/conflict results, and returns
+`{ status: "limit_reached" }` without writing when full. Database adapters require their documented transaction or
+conditional-write capability; they throw `transaction_unsupported` rather than performing a racy check-then-save.
+
 The `./testing` subpath exports framework-independent JSON fixtures and contract runners for pagination,
 idempotency, revision conflicts, translation metadata, CSV, and form deletion. Adapters expose
 `inspectFormDeletion` and `deleteForm` through the lifecycle contract when their implementation supports it;
 transactional deletion is required by default and `allowNonAtomic: true` is an explicit fallback.
 
-| Package | 7.18.x contract status |
+| Package | v8 contract status |
 | --- | --- |
-| `storage-memory` | lifecycle, pagination, idempotency |
-| `storage-mongodb` | lifecycle, version state/events, transactions |
-| `storage-azure-table` | lifecycle, pagination; no native transaction |
-| `storage-postgres` / `storage-sqlite` / `storage-d1` | lifecycle, pagination; transaction depends on injected client |
-| `storage-localstorage` | lifecycle, pagination; non-atomic only |
+| `storage-memory` | lifecycle, pagination, idempotency, process-local atomic response limits |
+| `storage-mongodb` | lifecycle, version state/events, transaction-backed response limits |
+| `storage-azure-table` | lifecycle, pagination, same-partition transactional response limits |
+| `storage-postgres` / `storage-sqlite` | lifecycle, pagination, transaction-backed response limits |
+| `storage-d1` | lifecycle, pagination, single-statement conditional response limits |
+| `storage-localstorage` | lifecycle, pagination, same-JavaScript-agent response limits |
 
 Existing `StorageAdapter` methods remain valid. To migrate, pass `schemaValidation` to an adapter when
 Content Mode policy must be enforced at persistence, then use `inspectFormDeletion` before deletion and

package/dist/testing.cjs

@@ -23,6 +23,7 @@ __export(testing_exports, {
   createStorageContractFixtures: () => createStorageContractFixtures,
   runIdempotencyContract: () => runIdempotencyContract,
   runLifecycleContract: () => runLifecycleContract,
+  runResponseLimitContract: () => runResponseLimitContract,
   runRevisionConflictContract: () => runRevisionConflictContract,
   runStorageContract: () => runStorageContract,
   storageContractScope: () => storageContractScope,
@@ -133,6 +134,54 @@ async function runIdempotencyContract(save) {
     "changed payload must conflict"
   );
 }
+async function runResponseLimitContract(adapter) {
+  const [submission] = createStorageContractFixtures().submissions;
+  if (submission === void 0) throw new Error("Missing fixture");
+  const saveWithinLimit = adapter.saveSubmissionWithinLimit?.bind(adapter);
+  check(saveWithinLimit !== void 0, "adapter must implement saveSubmissionWithinLimit");
+  const created = await saveWithinLimit(submission, 1, { idempotent: true });
+  check(created?.status === "created", "first limited save must be created");
+  const duplicate = await saveWithinLimit(submission, 1, { idempotent: true });
+  check(duplicate?.status === "duplicate", "idempotent retry must succeed after reaching the limit");
+  const conflict = await saveWithinLimit({ ...submission, values: { "question-1": "option-2" } }, 1, {
+    idempotent: true
+  });
+  check(conflict?.status === "conflict", "changed retry must conflict after reaching the limit");
+  const limited = await saveWithinLimit({ ...submission, id: "contract-limit" }, 1, {
+    idempotent: true
+  });
+  check(limited?.status === "limit_reached", "second submission must be rejected at the limit");
+  const nextVersion = await saveWithinLimit(
+    { ...submission, id: "contract-next-version", formVersion: submission.formVersion + 1 },
+    1,
+    { idempotent: true }
+  );
+  check(nextVersion?.status === "created", "response limits must be scoped by form version");
+  const retrySubmission = { ...submission, id: "contract-concurrent-retry", formVersion: submission.formVersion + 2 };
+  const retryResults = await Promise.all([
+    saveWithinLimit(retrySubmission, 1, { idempotent: true }),
+    saveWithinLimit(retrySubmission, 1, { idempotent: true })
+  ]);
+  const retryStatuses = retryResults.map((result) => result?.status).sort();
+  check(
+    JSON.stringify(retryStatuses) === JSON.stringify(["created", "duplicate"]),
+    "concurrent idempotent retries must create once"
+  );
+  const concurrentVersion = submission.formVersion + 3;
+  const capacityResults = await Promise.all([
+    saveWithinLimit({ ...submission, id: "contract-concurrent-a", formVersion: concurrentVersion }, 1, {
+      idempotent: true
+    }),
+    saveWithinLimit({ ...submission, id: "contract-concurrent-b", formVersion: concurrentVersion }, 1, {
+      idempotent: true
+    })
+  ]);
+  const capacityStatuses = capacityResults.map((result) => result?.status).sort();
+  check(
+    JSON.stringify(capacityStatuses) === JSON.stringify(["created", "limit_reached"]),
+    "concurrent submissions must not exceed the response limit"
+  );
+}
 async function runRevisionConflictContract(adapter) {
   const { schema, state } = createStorageContractFixtures();
   const planned = (0, import_core.createCloneTransitionPlan)(
@@ -212,6 +261,7 @@ function verifyStorageCodecVectors() {
   createStorageContractFixtures,
   runIdempotencyContract,
   runLifecycleContract,
+  runResponseLimitContract,
   runRevisionConflictContract,
   runStorageContract,
   storageContractScope,

package/dist/testing.d.cts

@@ -32,8 +32,9 @@ interface StorageContractReport {
 /** Run against an empty, disposable adapter. Never clears a caller's database. */
 declare function runStorageContract(adapter: FormStorageAdapter): Promise<StorageContractReport>;
 declare function runIdempotencyContract(save: (submission: FormSubmission) => Promise<undefined | SubmissionSaveResult>): Promise<void>;
+declare function runResponseLimitContract(adapter: FormStorageAdapter): Promise<void>;
 declare function runRevisionConflictContract(adapter: VersionedFormStorageAdapter): Promise<void>;
 declare function runLifecycleContract(adapter: FormStorageAdapter): Promise<void>;
 declare function verifyStorageCodecVectors(): void;
 
-export { type StorageContractReport, createStorageContractFixtures, runIdempotencyContract, runLifecycleContract, runRevisionConflictContract, runStorageContract, storageContractScope, verifyStorageCodecVectors };
+export { type StorageContractReport, createStorageContractFixtures, runIdempotencyContract, runLifecycleContract, runResponseLimitContract, runRevisionConflictContract, runStorageContract, storageContractScope, verifyStorageCodecVectors };

package/dist/testing.d.ts

@@ -32,8 +32,9 @@ interface StorageContractReport {
 /** Run against an empty, disposable adapter. Never clears a caller's database. */
 declare function runStorageContract(adapter: FormStorageAdapter): Promise<StorageContractReport>;
 declare function runIdempotencyContract(save: (submission: FormSubmission) => Promise<undefined | SubmissionSaveResult>): Promise<void>;
+declare function runResponseLimitContract(adapter: FormStorageAdapter): Promise<void>;
 declare function runRevisionConflictContract(adapter: VersionedFormStorageAdapter): Promise<void>;
 declare function runLifecycleContract(adapter: FormStorageAdapter): Promise<void>;
 declare function verifyStorageCodecVectors(): void;
 
-export { type StorageContractReport, createStorageContractFixtures, runIdempotencyContract, runLifecycleContract, runRevisionConflictContract, runStorageContract, storageContractScope, verifyStorageCodecVectors };
+export { type StorageContractReport, createStorageContractFixtures, runIdempotencyContract, runLifecycleContract, runResponseLimitContract, runRevisionConflictContract, runStorageContract, storageContractScope, verifyStorageCodecVectors };

package/dist/testing.js

@@ -109,6 +109,54 @@ async function runIdempotencyContract(save) {
     "changed payload must conflict"
   );
 }
+async function runResponseLimitContract(adapter) {
+  const [submission] = createStorageContractFixtures().submissions;
+  if (submission === void 0) throw new Error("Missing fixture");
+  const saveWithinLimit = adapter.saveSubmissionWithinLimit?.bind(adapter);
+  check(saveWithinLimit !== void 0, "adapter must implement saveSubmissionWithinLimit");
+  const created = await saveWithinLimit(submission, 1, { idempotent: true });
+  check(created?.status === "created", "first limited save must be created");
+  const duplicate = await saveWithinLimit(submission, 1, { idempotent: true });
+  check(duplicate?.status === "duplicate", "idempotent retry must succeed after reaching the limit");
+  const conflict = await saveWithinLimit({ ...submission, values: { "question-1": "option-2" } }, 1, {
+    idempotent: true
+  });
+  check(conflict?.status === "conflict", "changed retry must conflict after reaching the limit");
+  const limited = await saveWithinLimit({ ...submission, id: "contract-limit" }, 1, {
+    idempotent: true
+  });
+  check(limited?.status === "limit_reached", "second submission must be rejected at the limit");
+  const nextVersion = await saveWithinLimit(
+    { ...submission, id: "contract-next-version", formVersion: submission.formVersion + 1 },
+    1,
+    { idempotent: true }
+  );
+  check(nextVersion?.status === "created", "response limits must be scoped by form version");
+  const retrySubmission = { ...submission, id: "contract-concurrent-retry", formVersion: submission.formVersion + 2 };
+  const retryResults = await Promise.all([
+    saveWithinLimit(retrySubmission, 1, { idempotent: true }),
+    saveWithinLimit(retrySubmission, 1, { idempotent: true })
+  ]);
+  const retryStatuses = retryResults.map((result) => result?.status).sort();
+  check(
+    JSON.stringify(retryStatuses) === JSON.stringify(["created", "duplicate"]),
+    "concurrent idempotent retries must create once"
+  );
+  const concurrentVersion = submission.formVersion + 3;
+  const capacityResults = await Promise.all([
+    saveWithinLimit({ ...submission, id: "contract-concurrent-a", formVersion: concurrentVersion }, 1, {
+      idempotent: true
+    }),
+    saveWithinLimit({ ...submission, id: "contract-concurrent-b", formVersion: concurrentVersion }, 1, {
+      idempotent: true
+    })
+  ]);
+  const capacityStatuses = capacityResults.map((result) => result?.status).sort();
+  check(
+    JSON.stringify(capacityStatuses) === JSON.stringify(["created", "limit_reached"]),
+    "concurrent submissions must not exceed the response limit"
+  );
+}
 async function runRevisionConflictContract(adapter) {
   const { schema, state } = createStorageContractFixtures();
   const planned = createCloneTransitionPlan(
@@ -187,6 +235,7 @@ export {
   createStorageContractFixtures,
   runIdempotencyContract,
   runLifecycleContract,
+  runResponseLimitContract,
   runRevisionConflictContract,
   runStorageContract,
   storageContractScope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -42,7 +42,7 @@
     "url": "git+https://github.com/nitta-a/form-engine-ts.git"
   },
   "dependencies": {
-    "@form-engine-ts/core": "8.0.0"
+    "@form-engine-ts/core": "8.0.2"
   },
   "scripts": {
     "build": "tsup src/index.ts src/types.ts src/pagination.ts src/testing.ts --format esm,cjs --dts --clean --external @form-engine-ts/core",