@form-engine-ts/storage-azure-table 5.1.0 → 6.1.0

package/README.md

@@ -42,3 +42,7 @@ and field indexes, so a page can resume inside a multi-answer entity without gap
 consume the item limit, and scanning remains bounded by `maxScanPages`. Cursor format version 1 also records the form,
 version, sorted fields, and a SHA-256 filter fingerprint. Reusing a cursor with different query context throws
 `invalid_cursor_context`.
+
+`createLegacyAzureTableCodec()` decodes older entities using `PartitionKey`, `RowKey`, `answers`, `answeredAt`, and
+`surveyVersion` into the canonical `FormSubmission` shape. Custom partition- and row-key generators can be supplied
+for migration tooling.

package/dist/index.cjs

@@ -21,12 +21,88 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createAzureTableStorage: () => createAzureTableStorage,
+  createLegacyArrayAzureTableCodec: () => createLegacyArrayAzureTableCodec,
+  createLegacyAzureTableCodec: () => createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec: () => defaultAzureTableSubmissionCodec,
   metadataFiltersToOData: () => metadataFiltersToOData,
   submissionFilterToOData: () => submissionFilterToOData
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@form-engine-ts/core");
+function createLegacyArrayAzureTableCodec(options = {}) {
+  const defaultLocale = options.defaultLocale ?? "ja";
+  if (defaultLocale.trim().length === 0) throw new TypeError("defaultLocale must not be empty.");
+  return {
+    encode: (submission) => ({
+      PartitionKey: submission.formId,
+      RowKey: submission.id,
+      answers: JSON.stringify(Object.entries(submission.values).map(([questionId, value]) => ({ questionId, value }))),
+      answeredAt: submission.submittedAt,
+      surveyVersion: submission.formVersion,
+      locale: submission.locale,
+      ...submission.metadata
+    }),
+    decode: (entity) => {
+      const raw = entity;
+      if (typeof raw.PartitionKey !== "string" || typeof raw.RowKey !== "string") {
+        throw new Error("Azure Table legacy array submission is missing PartitionKey or RowKey.");
+      }
+      const submittedAt = typeof raw.answeredAt === "string" ? raw.answeredAt : entity.Timestamp;
+      if (typeof submittedAt !== "string" || submittedAt.trim().length === 0) {
+        throw new Error("Azure Table legacy array submission is missing answeredAt or Timestamp.");
+      }
+      let values = {};
+      if (typeof raw.answers === "string") {
+        const parsed = parseJson(raw.answers, "legacy array answers");
+        if (Array.isArray(parsed)) {
+          values = Object.fromEntries(
+            parsed.flatMap((item) => {
+              if (!isRecord(item) || typeof item.questionId !== "string") return [];
+              return [[item.questionId, item.value]];
+            })
+          );
+        } else if (isRecord(parsed)) {
+          values = parsed;
+        } else {
+          throw new Error("Azure Table legacy array answers payload must be an array or object.");
+        }
+      }
+      const formVersion = Number(raw.surveyVersion);
+      return {
+        id: raw.RowKey,
+        formId: raw.PartitionKey,
+        formVersion: Number.isSafeInteger(formVersion) && formVersion > 0 ? formVersion : 1,
+        values,
+        locale: typeof raw.locale === "string" && raw.locale.trim().length > 0 ? raw.locale : defaultLocale,
+        metadata: options.metadataExtractor?.(entity) ?? {},
+        submittedAt
+      };
+    }
+  };
+}
+var createLegacyAzureTableCodec = (options = {}) => {
+  const createPartitionKey = options.partitionKeyGenerator ?? ((formId) => formId);
+  const createRowKey = options.rowKeyGenerator ?? ((submittedAt, submissionId) => `${submittedAt}_${submissionId}`);
+  return {
+    decode: (entity) => {
+      const values = entity.answers === void 0 ? {} : parseLegacyJsonObject(entity.answers, "answers");
+      const submittedAt = entity.answeredAt ?? entity.Timestamp;
+      if (submittedAt === void 0 || submittedAt.trim().length === 0) {
+        throw new Error("Azure Table legacy submission is missing answeredAt or Timestamp.");
+      }
+      return {
+        id: entity.RowKey,
+        formId: entity.PartitionKey,
+        formVersion: entity.surveyVersion ?? 1,
+        values,
+        metadata: {},
+        submittedAt
+      };
+    },
+    createPartitionKey: (formId, submissionId) => createPartitionKey(formId, submissionId),
+    createRowKey: (submittedAt, submissionId) => createRowKey(submittedAt, submissionId)
+  };
+};
 var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 function encodeBase64(bytes) {
   let result = "";
@@ -135,6 +211,11 @@ function parseJson(value, location) {
     throw new Error(`Azure Table ${location} payload is invalid.`, { cause });
   }
 }
+function parseLegacyJsonObject(value, property) {
+  const parsed = parseJson(value, `legacy ${property}`);
+  if (!isRecord(parsed)) throw new Error(`Azure Table legacy ${property} payload must be an object.`);
+  return parsed;
+}
 function parseSubmission(value, location) {
   const parsed = typeof value === "string" ? parseJson(value, location) : value;
   if (!isRecord(parsed) || typeof parsed.id !== "string" || typeof parsed.formId !== "string" || !Number.isInteger(parsed.formVersion) || typeof parsed.locale !== "string" || typeof parsed.submittedAt !== "string" || !isRecord(parsed.values) || !Object.values(parsed.values).every(isFormValue)) {
@@ -511,6 +592,11 @@ function createAzureTableStorage(options = {}) {
             continue;
           }
           const answers = submissionTextAnswers(submission, fieldIds);
+          const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+            Object.entries(submission.metadata).filter(
+              (entry) => entry[1] !== void 0
+            )
+          );
           for (let fieldIndex = entityIndex === entityStartIndex ? fieldStartIndex : 0; fieldIndex < answers.length; fieldIndex += 1) {
             const answer = answers[fieldIndex];
             if (answer === void 0) continue;
@@ -520,9 +606,9 @@ function createAzureTableStorage(options = {}) {
               formVersion: submission.formVersion,
               fieldId: answer.fieldId,
               text: answer.text,
-              locale: submission.locale,
+              ...submission.locale === void 0 ? {} : { locale: submission.locale },
               submittedAt: submission.submittedAt,
-              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+              ...metadata === void 0 ? {} : { metadata }
             });
             if (items.length < pageSize) continue;
             const nextFieldIndex = fieldIndex + 1;
@@ -614,6 +700,8 @@ function createAzureTableStorage(options = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAzureTableStorage,
+  createLegacyArrayAzureTableCodec,
+  createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec,
   metadataFiltersToOData,
   submissionFilterToOData

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, BaseSubmissionMetadata, StrictFormSubmission, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
@@ -30,6 +30,40 @@ interface AzureTableEntityCodec<T> {
     readonly serialize: (submission: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
 }
+interface AzureTableLegacyEntity {
+    readonly PartitionKey: string;
+    readonly RowKey: string;
+    readonly answers?: string;
+    readonly answeredAt?: string;
+    readonly surveyVersion?: number;
+    readonly Timestamp?: string;
+    readonly [key: string]: unknown;
+}
+interface AzureTableLegacyCodec {
+    readonly decode: (entity: AzureTableLegacyEntity) => FormSubmission;
+    readonly createPartitionKey: (formId: string, submissionId: string) => string;
+    readonly createRowKey: (submittedAt: string, submissionId: string) => string;
+}
+interface LegacyAnswerArrayEntity extends Record<string, unknown> {
+    readonly PartitionKey: string;
+    readonly RowKey: string;
+    readonly answers: string;
+    readonly answeredAt: string;
+    readonly surveyVersion: number;
+    readonly locale?: string;
+}
+interface LegacyArrayAzureTableCodec<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly encode: (submission: StrictFormSubmission<TMeta>) => Record<string, unknown>;
+    readonly decode: (entity: Record<string, unknown>) => StrictFormSubmission<TMeta>;
+}
+declare function createLegacyArrayAzureTableCodec<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(options?: {
+    readonly defaultLocale?: string;
+    readonly metadataExtractor?: (entity: Record<string, unknown>) => TMeta;
+}): LegacyArrayAzureTableCodec<TMeta>;
+declare const createLegacyAzureTableCodec: (options?: {
+    readonly partitionKeyGenerator?: (formId: string, submissionId: string) => string;
+    readonly rowKeyGenerator?: (submittedAt: string, submissionId: string) => string;
+}) => AzureTableLegacyCodec;
 interface AzureTableSubmissionCodec<T = FormSubmission> {
     readonly createEntity: (value: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
@@ -86,4 +120,4 @@ declare function metadataFiltersToOData(options: SubmissionPageQueryOptions, map
 declare function submissionFilterToOData(filter: SubmissionFilter, mapping?: AzureTableFieldMapping): string | undefined;
 declare function createAzureTableStorage(options?: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableFieldMapping, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableFieldMapping, type AzureTableLegacyCodec, type AzureTableLegacyEntity, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, type LegacyAnswerArrayEntity, type LegacyArrayAzureTableCodec, createAzureTableStorage, createLegacyArrayAzureTableCodec, createLegacyAzureTableCodec, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { FormSubmission, SubmissionPageQueryOptions, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
+import { FormSubmission, SubmissionPageQueryOptions, BaseSubmissionMetadata, StrictFormSubmission, PagedSubmissionStorageAdapter, SubmissionFilter } from '@form-engine-ts/core';
 
 interface AzureTableListOptions {
     readonly queryOptions?: {
@@ -30,6 +30,40 @@ interface AzureTableEntityCodec<T> {
     readonly serialize: (submission: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
 }
+interface AzureTableLegacyEntity {
+    readonly PartitionKey: string;
+    readonly RowKey: string;
+    readonly answers?: string;
+    readonly answeredAt?: string;
+    readonly surveyVersion?: number;
+    readonly Timestamp?: string;
+    readonly [key: string]: unknown;
+}
+interface AzureTableLegacyCodec {
+    readonly decode: (entity: AzureTableLegacyEntity) => FormSubmission;
+    readonly createPartitionKey: (formId: string, submissionId: string) => string;
+    readonly createRowKey: (submittedAt: string, submissionId: string) => string;
+}
+interface LegacyAnswerArrayEntity extends Record<string, unknown> {
+    readonly PartitionKey: string;
+    readonly RowKey: string;
+    readonly answers: string;
+    readonly answeredAt: string;
+    readonly surveyVersion: number;
+    readonly locale?: string;
+}
+interface LegacyArrayAzureTableCodec<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata> {
+    readonly encode: (submission: StrictFormSubmission<TMeta>) => Record<string, unknown>;
+    readonly decode: (entity: Record<string, unknown>) => StrictFormSubmission<TMeta>;
+}
+declare function createLegacyArrayAzureTableCodec<TMeta extends BaseSubmissionMetadata = BaseSubmissionMetadata>(options?: {
+    readonly defaultLocale?: string;
+    readonly metadataExtractor?: (entity: Record<string, unknown>) => TMeta;
+}): LegacyArrayAzureTableCodec<TMeta>;
+declare const createLegacyAzureTableCodec: (options?: {
+    readonly partitionKeyGenerator?: (formId: string, submissionId: string) => string;
+    readonly rowKeyGenerator?: (submittedAt: string, submissionId: string) => string;
+}) => AzureTableLegacyCodec;
 interface AzureTableSubmissionCodec<T = FormSubmission> {
     readonly createEntity: (value: T) => Record<string, unknown>;
     readonly deserialize: (entity: Record<string, unknown>) => T;
@@ -86,4 +120,4 @@ declare function metadataFiltersToOData(options: SubmissionPageQueryOptions, map
 declare function submissionFilterToOData(filter: SubmissionFilter, mapping?: AzureTableFieldMapping): string | undefined;
 declare function createAzureTableStorage(options?: AzureTableStorageOptions): PagedSubmissionStorageAdapter;
 
-export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableFieldMapping, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };
+export { type AzureTableClientLike, type AzureTableEntityCodec, type AzureTableEntityIterator, type AzureTableEntityPage, type AzureTableFieldMapping, type AzureTableLegacyCodec, type AzureTableLegacyEntity, type AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, type LegacyAnswerArrayEntity, type LegacyArrayAzureTableCodec, createAzureTableStorage, createLegacyArrayAzureTableCodec, createLegacyAzureTableCodec, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.js

@@ -1,5 +1,79 @@
 // src/index.ts
 import { assertValidFormSchema, matchesSubmissionPageFilters, normalizeSubmissionPageSize } from "@form-engine-ts/core";
+function createLegacyArrayAzureTableCodec(options = {}) {
+  const defaultLocale = options.defaultLocale ?? "ja";
+  if (defaultLocale.trim().length === 0) throw new TypeError("defaultLocale must not be empty.");
+  return {
+    encode: (submission) => ({
+      PartitionKey: submission.formId,
+      RowKey: submission.id,
+      answers: JSON.stringify(Object.entries(submission.values).map(([questionId, value]) => ({ questionId, value }))),
+      answeredAt: submission.submittedAt,
+      surveyVersion: submission.formVersion,
+      locale: submission.locale,
+      ...submission.metadata
+    }),
+    decode: (entity) => {
+      const raw = entity;
+      if (typeof raw.PartitionKey !== "string" || typeof raw.RowKey !== "string") {
+        throw new Error("Azure Table legacy array submission is missing PartitionKey or RowKey.");
+      }
+      const submittedAt = typeof raw.answeredAt === "string" ? raw.answeredAt : entity.Timestamp;
+      if (typeof submittedAt !== "string" || submittedAt.trim().length === 0) {
+        throw new Error("Azure Table legacy array submission is missing answeredAt or Timestamp.");
+      }
+      let values = {};
+      if (typeof raw.answers === "string") {
+        const parsed = parseJson(raw.answers, "legacy array answers");
+        if (Array.isArray(parsed)) {
+          values = Object.fromEntries(
+            parsed.flatMap((item) => {
+              if (!isRecord(item) || typeof item.questionId !== "string") return [];
+              return [[item.questionId, item.value]];
+            })
+          );
+        } else if (isRecord(parsed)) {
+          values = parsed;
+        } else {
+          throw new Error("Azure Table legacy array answers payload must be an array or object.");
+        }
+      }
+      const formVersion = Number(raw.surveyVersion);
+      return {
+        id: raw.RowKey,
+        formId: raw.PartitionKey,
+        formVersion: Number.isSafeInteger(formVersion) && formVersion > 0 ? formVersion : 1,
+        values,
+        locale: typeof raw.locale === "string" && raw.locale.trim().length > 0 ? raw.locale : defaultLocale,
+        metadata: options.metadataExtractor?.(entity) ?? {},
+        submittedAt
+      };
+    }
+  };
+}
+var createLegacyAzureTableCodec = (options = {}) => {
+  const createPartitionKey = options.partitionKeyGenerator ?? ((formId) => formId);
+  const createRowKey = options.rowKeyGenerator ?? ((submittedAt, submissionId) => `${submittedAt}_${submissionId}`);
+  return {
+    decode: (entity) => {
+      const values = entity.answers === void 0 ? {} : parseLegacyJsonObject(entity.answers, "answers");
+      const submittedAt = entity.answeredAt ?? entity.Timestamp;
+      if (submittedAt === void 0 || submittedAt.trim().length === 0) {
+        throw new Error("Azure Table legacy submission is missing answeredAt or Timestamp.");
+      }
+      return {
+        id: entity.RowKey,
+        formId: entity.PartitionKey,
+        formVersion: entity.surveyVersion ?? 1,
+        values,
+        metadata: {},
+        submittedAt
+      };
+    },
+    createPartitionKey: (formId, submissionId) => createPartitionKey(formId, submissionId),
+    createRowKey: (submittedAt, submissionId) => createRowKey(submittedAt, submissionId)
+  };
+};
 var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
 function encodeBase64(bytes) {
   let result = "";
@@ -108,6 +182,11 @@ function parseJson(value, location) {
     throw new Error(`Azure Table ${location} payload is invalid.`, { cause });
   }
 }
+function parseLegacyJsonObject(value, property) {
+  const parsed = parseJson(value, `legacy ${property}`);
+  if (!isRecord(parsed)) throw new Error(`Azure Table legacy ${property} payload must be an object.`);
+  return parsed;
+}
 function parseSubmission(value, location) {
   const parsed = typeof value === "string" ? parseJson(value, location) : value;
   if (!isRecord(parsed) || typeof parsed.id !== "string" || typeof parsed.formId !== "string" || !Number.isInteger(parsed.formVersion) || typeof parsed.locale !== "string" || typeof parsed.submittedAt !== "string" || !isRecord(parsed.values) || !Object.values(parsed.values).every(isFormValue)) {
@@ -484,6 +563,11 @@ function createAzureTableStorage(options = {}) {
             continue;
           }
           const answers = submissionTextAnswers(submission, fieldIds);
+          const metadata = submission.metadata === void 0 ? void 0 : Object.fromEntries(
+            Object.entries(submission.metadata).filter(
+              (entry) => entry[1] !== void 0
+            )
+          );
           for (let fieldIndex = entityIndex === entityStartIndex ? fieldStartIndex : 0; fieldIndex < answers.length; fieldIndex += 1) {
             const answer = answers[fieldIndex];
             if (answer === void 0) continue;
@@ -493,9 +577,9 @@ function createAzureTableStorage(options = {}) {
               formVersion: submission.formVersion,
               fieldId: answer.fieldId,
               text: answer.text,
-              locale: submission.locale,
+              ...submission.locale === void 0 ? {} : { locale: submission.locale },
               submittedAt: submission.submittedAt,
-              ...submission.metadata === void 0 ? {} : { metadata: submission.metadata }
+              ...metadata === void 0 ? {} : { metadata }
             });
             if (items.length < pageSize) continue;
             const nextFieldIndex = fieldIndex + 1;
@@ -586,6 +670,8 @@ function createAzureTableStorage(options = {}) {
 }
 export {
   createAzureTableStorage,
+  createLegacyArrayAzureTableCodec,
+  createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec,
   metadataFiltersToOData,
   submissionFilterToOData

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@form-engine-ts/storage-azure-table",
-  "version": "5.1.0",
+  "version": "6.1.0",
   "publishConfig": {
     "access": "public"
   },
@@ -39,7 +39,7 @@
     "typescript"
   ],
   "dependencies": {
-    "@form-engine-ts/core": "5.1.0"
+    "@form-engine-ts/core": "6.1.0"
   },
   "peerDependencies": {
     "@azure/data-tables": "^13.3.2"