@form-engine-ts/storage 7.18.1 → 8.0.1

package/README.md

@@ -21,18 +21,30 @@ Both adapters implement the required `UnifiedSubmissionStorageAdapter` surface:
 free-text answer paging, idempotent saving, typed validation, response aggregation, and CSV export. These common
 operations use the same core contracts regardless of the backing database.
 
+## Migration notes
+
+`StorageAdapter`, `TypedStorageAdapter`, and `UnifiedSubmissionStorageAdapter` now require
+`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,
@@ -84,6 +85,23 @@ async function runStorageContract(adapter) {
   check(JSON.stringify(loaded) === JSON.stringify(submissions), "submission ordering/metadata round trip");
   const passed = ["schema", "submission", "translation_metadata"];
   const unsupported = [];
+  check(await adapter.countSubmissions(schema.id) === submissions.length, "count must include all form versions");
+  check(
+    await adapter.countSubmissions(schema.id, schema.version) === submissions.length,
+    "count must filter by form version"
+  );
+  check(
+    await adapter.countSubmissions(schema.id, schema.version, {
+      since: "2026-01-01T00:00:00.000Z",
+      until: "2026-01-01T00:00:00.000Z"
+    }) === submissions.length,
+    "count must include since/until boundaries"
+  );
+  check(
+    await adapter.countSubmissions(schema.id, schema.version, { since: "2026-01-01T00:00:00.001Z" }) === 0,
+    "count must filter by submission time"
+  );
+  passed.push("count");
   if ("listSubmissionPage" in adapter && typeof adapter.listSubmissionPage === "function") {
     const paged = adapter;
     const ids = [];
@@ -116,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)(
@@ -195,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

@@ -60,6 +60,23 @@ async function runStorageContract(adapter) {
   check(JSON.stringify(loaded) === JSON.stringify(submissions), "submission ordering/metadata round trip");
   const passed = ["schema", "submission", "translation_metadata"];
   const unsupported = [];
+  check(await adapter.countSubmissions(schema.id) === submissions.length, "count must include all form versions");
+  check(
+    await adapter.countSubmissions(schema.id, schema.version) === submissions.length,
+    "count must filter by form version"
+  );
+  check(
+    await adapter.countSubmissions(schema.id, schema.version, {
+      since: "2026-01-01T00:00:00.000Z",
+      until: "2026-01-01T00:00:00.000Z"
+    }) === submissions.length,
+    "count must include since/until boundaries"
+  );
+  check(
+    await adapter.countSubmissions(schema.id, schema.version, { since: "2026-01-01T00:00:00.001Z" }) === 0,
+    "count must filter by submission time"
+  );
+  passed.push("count");
   if ("listSubmissionPage" in adapter && typeof adapter.listSubmissionPage === "function") {
     const paged = adapter;
     const ids = [];
@@ -92,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(
@@ -170,6 +235,7 @@ export {
   createStorageContractFixtures,
   runIdempotencyContract,
   runLifecycleContract,
+  runResponseLimitContract,
   runRevisionConflictContract,
   runStorageContract,
   storageContractScope,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage",
-  "version": "7.18.1",
+  "version": "8.0.1",
   "publishConfig": {
     "access": "public"
   },
@@ -42,7 +42,7 @@
     "url": "git+https://github.com/nitta-a/form-engine-ts.git"
   },
   "dependencies": {
-    "@form-engine-ts/core": "7.18.1"
+    "@form-engine-ts/core": "8.0.1"
   },
   "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",