@form-engine-ts/storage-azure-table 7.17.3 → 7.18.0

package/README.md

@@ -40,8 +40,9 @@ to fill the requested logical page after client-side filtering. `buildSubmission
 The caller owns table creation, credentials, retries, and client lifecycle.
 
 The default codec persists the canonical `FormSubmission.values` payload and never creates an `answers` property. The
-standard adapter rejects entities containing the legacy `answers` column; it does not decode or migrate them. Legacy
-codecs are available only from `@form-engine-ts/legacy`. `idempotentSubmissions: true` enables typed `created`, `duplicate`, and `conflict` results from
+standard adapter rejects entities containing the legacy `answers` column; it does not decode or migrate them.
+Applications must migrate legacy data to the canonical `values` contract before using this adapter.
+`idempotentSubmissions: true` enables typed `created`, `duplicate`, and `conflict` results from
 `saveSubmission(submission)`. Pass `validateAgainstSchema: true` to re-validate against the stored schema. Pass
 `submissionSchema`, `submissionValidator`, or `validation` to validate every submission before it is written; the same
 source can be supplied per call as `saveSubmission(submission, { validation })`. A source can be a FormSchema, a

package/dist/index.cjs

@@ -247,12 +247,12 @@ async function collectSubmissionPages(fetchPage, formId, options) {
   } while (cursor !== void 0);
   return submissions;
 }
-function parseSchemaEntity(value) {
+function parseSchemaEntity(value, validation = {}) {
   if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
     throw new Error("Azure Table schema entity is invalid.");
   }
   const schema = parseJson(value.payload, `schema ${value.partitionKey}/${value.rowKey}`);
-  (0, import_core.assertValidFormSchema)(schema);
+  (0, import_core.assertValidFormSchema)(schema, validation);
   if (schema.id !== value.partitionKey || schema.version !== value.formVersion) {
     throw new Error("Azure Table schema entity has inconsistent metadata.");
   }
@@ -403,10 +403,57 @@ function createAzureTableStorage(options = {}) {
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
     );
   };
+  const lifecycleBackend = {
+    resources: ["schema", "submission"],
+    async list(formId) {
+      const records = [];
+      for (const kind of ["schema", "submission"]) {
+        const client = kind === "schema" ? await schemaClient(formId) : await submissionClient(formId);
+        const filter = kind === "schema" ? `PartitionKey eq '${escapeOData(formId)}' and kind eq 'schema'` : queryFilter(formId, {});
+        for await (const raw of client.listEntities({ queryOptions: { filter } })) {
+          if (kind === "schema" && raw.kind !== "schema") continue;
+          const value = kind === "schema" ? parseSchemaEntity(raw, options.schemaValidation) : deserializeIfMatching(raw);
+          if (value === void 0 || ("formId" in value ? value.formId : value.id) !== formId) continue;
+          if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string")
+            throw new TypeError("Missing entity keys.");
+          records.push({ kind, id: JSON.stringify([raw.partitionKey, raw.rowKey]), value: { raw, value, formId } });
+        }
+      }
+      return records;
+    },
+    async remove(resource) {
+      ensureWritable();
+      if (!isRecord(resource.value) || !isRecord(resource.value.raw) || typeof resource.value.formId !== "string")
+        throw new TypeError("Invalid deletion resource.");
+      const { raw, formId } = resource.value;
+      if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string" || typeof raw.etag !== "string")
+        throw new TypeError("Conditional deletion requires entity keys and an ETag.");
+      const client = resource.kind === "schema" ? await schemaClient(formId) : await submissionClient(formId);
+      try {
+        await client.deleteEntity(raw.partitionKey, raw.rowKey, { etag: raw.etag });
+        return 1;
+      } catch (error) {
+        if (isNotFound(error)) return 0;
+        throw error;
+      }
+    }
+  };
+  const lifecycle = (0, import_core.createFormLifecycleAdapter)(
+    lifecycleBackend,
+    options.lifecycle === void 0 ? {} : {
+      ...options.lifecycle,
+      ...options.lifecycle.scope === void 0 ? {} : {
+        scope: (resource) => {
+          if (!isRecord(resource.value)) throw new TypeError("Invalid deletion resource.");
+          return options.lifecycle?.scope?.({ ...resource, value: resource.value.value }) ?? {};
+        }
+      }
+    }
+  );
   const adapter = {
     async saveSchema(schema) {
       ensureWritable();
-      (0, import_core.assertValidFormSchema)(schema);
+      (0, import_core.assertValidFormSchema)(schema, options.schemaValidation);
       const entity = {
         partitionKey: schema.id,
         rowKey: schemaRowKey(schema.version),
@@ -418,7 +465,10 @@ function createAzureTableStorage(options = {}) {
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(
+          await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)),
+          options.schemaValidation
+        );
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
@@ -427,7 +477,7 @@ function createAzureTableStorage(options = {}) {
     async listSchemas() {
       const found = [];
       for await (const raw of (await schemaClient("")).listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
-        if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
+        if (raw.kind === "schema") found.push(parseSchemaEntity(raw, options.schemaValidation));
       }
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
@@ -448,7 +498,7 @@ function createAzureTableStorage(options = {}) {
         const schema = parseSchemaEntity(
           await (await schemaClient(stored.formId)).getEntity(stored.formId, schemaRowKey(stored.formVersion))
         );
-        (0, import_core.assertValidFormSubmission)(schema, stored);
+        (0, import_core.assertValidFormSubmission)(schema, stored, options.schemaValidation);
       }
       const payloadHash = await (0, import_core.hashFormSubmissionPayload)(stored);
       const createdEntity = codec.createEntity(stored);
@@ -658,7 +708,7 @@ function createAzureTableStorage(options = {}) {
       }
       const schema = await adapter.getSchema(submission.formId, submission.formVersion);
       if (schema === null) throw new Error("Azure Table submission schema was not found.");
-      (0, import_core.assertValidFormSubmission)(schema, submission);
+      (0, import_core.assertValidFormSubmission)(schema, submission, options.schemaValidation);
     },
     async deleteSubmission(submissionId) {
       ensureWritable();
@@ -704,6 +754,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     ...adapter,
+    ...lifecycle,
     async fetchSubmissionPage(formId, options2) {
       return await adapter.listSubmissionPage(
         formId,

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BaseSubmissionMetadata, PagedSubmissionStorageAdapter, TextAnswerPageQueryOptions, TextAnswerPage, TypedSubmissionPageQueryOptions, TypedSubmissionPage, FormSubmission, FormSchema, SubmissionPageQueryOptions, FormAnalytics, StorageSubmissionExportOptions, FormSubmissionValidationSource, FormSubmissionValidator, SaveSubmissionOptions, SubmissionSaveResult, SubmissionFilter, JsonValue, TypedTextAnswerPage } from '@form-engine-ts/core';
+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 {
     readonly queryOptions?: {
@@ -20,7 +20,9 @@ interface AzureTableClientLike {
     upsertEntity(entity: Record<string, unknown>, mode?: "Merge" | "Replace"): Promise<unknown>;
     getEntity(partitionKey: string, rowKey: string): Promise<Record<string, unknown>>;
     listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
-    deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
+    deleteEntity(partitionKey: string, rowKey: string, options?: {
+        readonly etag?: string;
+    }): Promise<unknown>;
 }
 type AzureTableSubmissionEntity = Record<string, unknown> & {
     readonly answers?: never;
@@ -48,6 +50,8 @@ interface AzureTableValueCodec {
     readonly decodeValues?: (raw: string) => Record<string, unknown>;
 }
 interface AzureTableStorageOptions<T = FormSubmission> {
+    readonly schemaValidation?: ValidateFormSchemaOptions;
+    readonly lifecycle?: FormLifecycleOptions;
     /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
     readonly schemasTableClient?: AzureTableClientLike;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BaseSubmissionMetadata, PagedSubmissionStorageAdapter, TextAnswerPageQueryOptions, TextAnswerPage, TypedSubmissionPageQueryOptions, TypedSubmissionPage, FormSubmission, FormSchema, SubmissionPageQueryOptions, FormAnalytics, StorageSubmissionExportOptions, FormSubmissionValidationSource, FormSubmissionValidator, SaveSubmissionOptions, SubmissionSaveResult, SubmissionFilter, JsonValue, TypedTextAnswerPage } from '@form-engine-ts/core';
+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 {
     readonly queryOptions?: {
@@ -20,7 +20,9 @@ interface AzureTableClientLike {
     upsertEntity(entity: Record<string, unknown>, mode?: "Merge" | "Replace"): Promise<unknown>;
     getEntity(partitionKey: string, rowKey: string): Promise<Record<string, unknown>>;
     listEntities(options?: AzureTableListOptions): AzureTableEntityIterator;
-    deleteEntity(partitionKey: string, rowKey: string): Promise<unknown>;
+    deleteEntity(partitionKey: string, rowKey: string, options?: {
+        readonly etag?: string;
+    }): Promise<unknown>;
 }
 type AzureTableSubmissionEntity = Record<string, unknown> & {
     readonly answers?: never;
@@ -48,6 +50,8 @@ interface AzureTableValueCodec {
     readonly decodeValues?: (raw: string) => Record<string, unknown>;
 }
 interface AzureTableStorageOptions<T = FormSubmission> {
+    readonly schemaValidation?: ValidateFormSchemaOptions;
+    readonly lifecycle?: FormLifecycleOptions;
     /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
     readonly schemasTableClient?: AzureTableClientLike;

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   assertValidFormSchema,
   assertValidFormSubmission,
   assertValidFormSubmissionWith,
+  createFormLifecycleAdapter,
   exportResponsesToCsv,
   hashFormSubmissionPayload,
   matchesSubmissionPageFilters,
@@ -228,12 +229,12 @@ async function collectSubmissionPages(fetchPage, formId, options) {
   } while (cursor !== void 0);
   return submissions;
 }
-function parseSchemaEntity(value) {
+function parseSchemaEntity(value, validation = {}) {
   if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || value.kind !== "schema" || !Number.isInteger(value.formVersion) || typeof value.payload !== "string") {
     throw new Error("Azure Table schema entity is invalid.");
   }
   const schema = parseJson(value.payload, `schema ${value.partitionKey}/${value.rowKey}`);
-  assertValidFormSchema(schema);
+  assertValidFormSchema(schema, validation);
   if (schema.id !== value.partitionKey || schema.version !== value.formVersion) {
     throw new Error("Azure Table schema entity has inconsistent metadata.");
   }
@@ -384,10 +385,57 @@ function createAzureTableStorage(options = {}) {
       (left, right) => left.submittedAt.localeCompare(right.submittedAt) || left.id.localeCompare(right.id)
     );
   };
+  const lifecycleBackend = {
+    resources: ["schema", "submission"],
+    async list(formId) {
+      const records = [];
+      for (const kind of ["schema", "submission"]) {
+        const client = kind === "schema" ? await schemaClient(formId) : await submissionClient(formId);
+        const filter = kind === "schema" ? `PartitionKey eq '${escapeOData(formId)}' and kind eq 'schema'` : queryFilter(formId, {});
+        for await (const raw of client.listEntities({ queryOptions: { filter } })) {
+          if (kind === "schema" && raw.kind !== "schema") continue;
+          const value = kind === "schema" ? parseSchemaEntity(raw, options.schemaValidation) : deserializeIfMatching(raw);
+          if (value === void 0 || ("formId" in value ? value.formId : value.id) !== formId) continue;
+          if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string")
+            throw new TypeError("Missing entity keys.");
+          records.push({ kind, id: JSON.stringify([raw.partitionKey, raw.rowKey]), value: { raw, value, formId } });
+        }
+      }
+      return records;
+    },
+    async remove(resource) {
+      ensureWritable();
+      if (!isRecord(resource.value) || !isRecord(resource.value.raw) || typeof resource.value.formId !== "string")
+        throw new TypeError("Invalid deletion resource.");
+      const { raw, formId } = resource.value;
+      if (typeof raw.partitionKey !== "string" || typeof raw.rowKey !== "string" || typeof raw.etag !== "string")
+        throw new TypeError("Conditional deletion requires entity keys and an ETag.");
+      const client = resource.kind === "schema" ? await schemaClient(formId) : await submissionClient(formId);
+      try {
+        await client.deleteEntity(raw.partitionKey, raw.rowKey, { etag: raw.etag });
+        return 1;
+      } catch (error) {
+        if (isNotFound(error)) return 0;
+        throw error;
+      }
+    }
+  };
+  const lifecycle = createFormLifecycleAdapter(
+    lifecycleBackend,
+    options.lifecycle === void 0 ? {} : {
+      ...options.lifecycle,
+      ...options.lifecycle.scope === void 0 ? {} : {
+        scope: (resource) => {
+          if (!isRecord(resource.value)) throw new TypeError("Invalid deletion resource.");
+          return options.lifecycle?.scope?.({ ...resource, value: resource.value.value }) ?? {};
+        }
+      }
+    }
+  );
   const adapter = {
     async saveSchema(schema) {
       ensureWritable();
-      assertValidFormSchema(schema);
+      assertValidFormSchema(schema, options.schemaValidation);
       const entity = {
         partitionKey: schema.id,
         rowKey: schemaRowKey(schema.version),
@@ -399,7 +447,10 @@ function createAzureTableStorage(options = {}) {
     },
     async getSchema(formId, formVersion) {
       try {
-        return parseSchemaEntity(await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)));
+        return parseSchemaEntity(
+          await (await schemaClient(formId)).getEntity(formId, schemaRowKey(formVersion)),
+          options.schemaValidation
+        );
       } catch (error) {
         if (isNotFound(error)) return null;
         throw error;
@@ -408,7 +459,7 @@ function createAzureTableStorage(options = {}) {
     async listSchemas() {
       const found = [];
       for await (const raw of (await schemaClient("")).listEntities({ queryOptions: { filter: "kind eq 'schema'" } })) {
-        if (raw.kind === "schema") found.push(parseSchemaEntity(raw));
+        if (raw.kind === "schema") found.push(parseSchemaEntity(raw, options.schemaValidation));
       }
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
@@ -429,7 +480,7 @@ function createAzureTableStorage(options = {}) {
         const schema = parseSchemaEntity(
           await (await schemaClient(stored.formId)).getEntity(stored.formId, schemaRowKey(stored.formVersion))
         );
-        assertValidFormSubmission(schema, stored);
+        assertValidFormSubmission(schema, stored, options.schemaValidation);
       }
       const payloadHash = await hashFormSubmissionPayload(stored);
       const createdEntity = codec.createEntity(stored);
@@ -639,7 +690,7 @@ function createAzureTableStorage(options = {}) {
       }
       const schema = await adapter.getSchema(submission.formId, submission.formVersion);
       if (schema === null) throw new Error("Azure Table submission schema was not found.");
-      assertValidFormSubmission(schema, submission);
+      assertValidFormSubmission(schema, submission, options.schemaValidation);
     },
     async deleteSubmission(submissionId) {
       ensureWritable();
@@ -685,6 +736,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     ...adapter,
+    ...lifecycle,
     async fetchSubmissionPage(formId, options2) {
       return await adapter.listSubmissionPage(
         formId,

package/package.json

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