@form-engine-ts/storage-azure-table 5.0.1 → 6.0.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,36 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   createAzureTableStorage: () => createAzureTableStorage,
+  createLegacyAzureTableCodec: () => createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec: () => defaultAzureTableSubmissionCodec,
   metadataFiltersToOData: () => metadataFiltersToOData,
   submissionFilterToOData: () => submissionFilterToOData
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@form-engine-ts/core");
+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 +159,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)) {
@@ -142,6 +171,60 @@ function parseSubmission(value, location) {
   }
   return cloneJson(parsed);
 }
+function propertyName(mapping, logicalName, fallback) {
+  return mapping?.customPropertyMappings?.[logicalName] ?? (logicalName === "formId" ? mapping?.formId : void 0) ?? (logicalName === "formVersion" ? mapping?.formVersion : void 0) ?? (logicalName === "submittedAt" ? mapping?.submittedAt : void 0) ?? (logicalName === "values" ? mapping?.values : void 0) ?? (logicalName === "metadata" ? mapping?.metadata : void 0) ?? fallback;
+}
+function physicalKeyNames(mapping) {
+  return {
+    partitionKey: mapping?.partitionKeyProperty ?? "PartitionKey",
+    rowKey: mapping?.rowKeyProperty ?? "RowKey"
+  };
+}
+function entityKey(entity, property, compatibilityProperty) {
+  return entity[property] ?? entity[compatibilityProperty];
+}
+function mappedSubmissionEntity(entity, submission, mapping, valueCodec) {
+  if (mapping === void 0 && valueCodec === void 0) return entity;
+  const keys = physicalKeyNames(mapping);
+  const values = valueCodec?.encodeValues?.({ ...submission.values }) ?? JSON.stringify(submission.values);
+  const metadata = submission.metadata === void 0 ? void 0 : JSON.stringify(submission.metadata);
+  return {
+    ...entity,
+    [keys.partitionKey]: submission.formId,
+    [keys.rowKey]: entity.rowKey ?? defaultSubmissionRowKey(submission),
+    [propertyName(mapping, "formId", "formId")]: submission.formId,
+    [propertyName(mapping, "formVersion", "formVersion")]: submission.formVersion,
+    [propertyName(mapping, "submittedAt", "submittedAt")]: submission.submittedAt,
+    [propertyName(mapping, "values", "values")]: values,
+    ...metadata === void 0 ? {} : { [propertyName(mapping, "metadata", "metadata")]: metadata }
+  };
+}
+function mappedSubmissionFromEntity(entity, mapping, valueCodec) {
+  const id = typeof entity.responseId === "string" ? entity.responseId : entity.id;
+  const formId = entity[propertyName(mapping, "formId", "formId")];
+  const formVersion = entity[propertyName(mapping, "formVersion", "formVersion")];
+  const submittedAt = entity[propertyName(mapping, "submittedAt", "submittedAt")];
+  const rawValues = entity[propertyName(mapping, "values", "values")];
+  if (typeof id !== "string" || typeof formId !== "string" || typeof formVersion !== "number" || typeof submittedAt !== "string" || typeof rawValues !== "string")
+    return void 0;
+  const values = valueCodec?.decodeValues?.(rawValues) ?? parseJson(rawValues, "submission values");
+  if (!isRecord(values) || !Object.values(values).every(isFormValue))
+    throw new Error("Azure Table values are invalid.");
+  const rawMetadata = entity[propertyName(mapping, "metadata", "metadata")];
+  const metadata = rawMetadata === void 0 ? void 0 : parseJson(rawMetadata, "submission metadata");
+  return parseSubmission(
+    {
+      id,
+      formId,
+      formVersion,
+      locale: typeof entity.locale === "string" ? entity.locale : "",
+      values,
+      ...metadata === void 0 || !isRecord(metadata) ? {} : { metadata },
+      submittedAt
+    },
+    "mapped submission entity"
+  );
+}
 function schemaRowKey(version) {
   return `schema_${version}`;
 }
@@ -201,12 +284,16 @@ function parseSchemaEntity(value) {
   }
   return cloneJson(schema);
 }
-function parseSubmissionEntity(value, codec) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || !codec.matchesEntity(value)) {
+function parseSubmissionEntity(value, codec, mapping, valueCodec) {
+  const keys = physicalKeyNames(mapping);
+  const partitionKey = entityKey(value, keys.partitionKey, "partitionKey");
+  const rowKey = entityKey(value, keys.rowKey, "rowKey");
+  if (typeof partitionKey !== "string" || typeof rowKey !== "string" || !codec.matchesEntity(value)) {
     throw new Error("Azure Table submission entity is invalid.");
   }
-  const submission = parseSubmission(codec.deserialize(value), `submission ${value.partitionKey}/${value.rowKey}`);
-  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey) {
+  const submissionValue = mappedSubmissionFromEntity(value, mapping, valueCodec) ?? codec.deserialize(value);
+  const submission = parseSubmission(submissionValue, `submission ${partitionKey}/${rowKey}`);
+  if (codec.createPartitionKey(submission) !== partitionKey || codec.createRowKey(submission) !== rowKey) {
     throw new Error("Azure Table submission entity has inconsistent keys.");
   }
   return submission;
@@ -221,30 +308,36 @@ function valueToOData(value) {
   if (typeof value === "boolean") return String(value);
   throw new TypeError("Azure Table OData filters support only scalar JSON values.");
 }
-function metadataFiltersToOData(options) {
+function metadataFiltersToOData(options, mapping) {
   return Object.entries(options.metadataFilters ?? {}).map(([key, value]) => {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new TypeError(`Invalid Azure Table property name: ${key}`);
-    return `${key} eq ${valueToOData(value)}`;
+    const property = mapping?.customPropertyMappings?.[`metadata.${key}`] ?? mapping?.customPropertyMappings?.[key] ?? key;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(property))
+      throw new TypeError(`Invalid Azure Table property name: ${property}`);
+    return `${property} eq ${valueToOData(value)}`;
   }).join(" and ");
 }
-function odataProperty(path) {
+function odataProperty(path, mapping) {
   if (path === "id" || path === "responseId") return "responseId";
-  if (["formVersion", "locale", "submittedAt"].includes(path)) return path;
+  if (["formVersion", "locale", "submittedAt"].includes(path)) {
+    return propertyName(mapping, path, path);
+  }
   if (path.startsWith("metadata.")) {
     const property = path.slice("metadata.".length);
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(property) ? property : void 0;
+    const mapped = mapping?.customPropertyMappings?.[path] ?? mapping?.customPropertyMappings?.[property] ?? property;
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(mapped) ? mapped : void 0;
   }
   return void 0;
 }
-function submissionFilterToOData(filter) {
+function submissionFilterToOData(filter, mapping) {
   if (filter.op === "and" || filter.op === "or") {
-    const converted = filter.filters.map(submissionFilterToOData);
+    const converted = filter.filters.map((child) => submissionFilterToOData(child, mapping));
     if (filter.op === "or" && converted.some((value) => value === void 0)) return void 0;
     const available = converted.filter((value) => value !== void 0 && value.length > 0);
     if (available.length === 0) return void 0;
     return available.map((value) => `(${value})`).join(filter.op === "and" ? " and " : " or ");
   }
-  const property = odataProperty(filter.path);
+  const property = odataProperty(filter.path, mapping);
   if (property === void 0) return void 0;
   if (filter.op === "eq") return `${property} eq ${valueToOData(filter.value)}`;
   if (filter.op === "in") {
@@ -257,15 +350,16 @@ function submissionFilterToOData(filter) {
     ...filter.to === void 0 ? [] : [`${property} le ${valueToOData(filter.to)}`]
   ].join(" and ");
 }
-function defaultSubmissionFilter(codec, formId, options, legacyExtension) {
+function defaultSubmissionFilter(codec, formId, options, legacyExtension, mapping) {
   const partitionKey = codec.createPartitionKeyFromQuery(formId, options);
-  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter);
+  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter, mapping);
+  const keys = physicalKeyNames(mapping);
   return [
-    ...partitionKey === void 0 ? [] : [`PartitionKey eq '${escapeOData(partitionKey)}'`],
+    ...partitionKey === void 0 ? [] : [`${keys.partitionKey} eq '${escapeOData(partitionKey)}'`],
     ...codec === defaultAzureTableSubmissionCodec ? ["kind eq 'submission'"] : [],
-    ...options.version === void 0 ? [] : [`formVersion eq ${options.version}`],
-    ...options.since === void 0 ? [] : [`submittedAt ge '${escapeOData(options.since)}'`],
-    ...options.until === void 0 ? [] : [`submittedAt le '${escapeOData(options.until)}'`],
+    ...options.version === void 0 ? [] : [`${propertyName(mapping, "formVersion", "formVersion")} eq ${options.version}`],
+    ...options.since === void 0 ? [] : [`${propertyName(mapping, "submittedAt", "submittedAt")} ge '${escapeOData(options.since)}'`],
+    ...options.until === void 0 ? [] : [`${propertyName(mapping, "submittedAt", "submittedAt")} le '${escapeOData(options.until)}'`],
     ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
     ...ast === void 0 || ast.length === 0 ? [] : [`(${ast})`],
     ...legacyExtension.trim().length === 0 ? [] : [`(${legacyExtension})`]
@@ -284,7 +378,9 @@ function requireClient(client, name) {
 function createAzureTableStorage(options = {}) {
   const staticSchemas = options.schemasTableClient ?? options.client;
   const staticSubmissions = options.submissionsTableClient ?? options.client;
-  const codec = options.codec ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
+  const configuredCodec = options.codec;
+  const valueCodec = configuredCodec !== void 0 && "encodeValues" in configuredCodec ? configuredCodec : void 0;
+  const codec = (configuredCodec !== void 0 && "createEntity" in configuredCodec ? configuredCodec : void 0) ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
   const maxScanPages = options.maxScanPages ?? 5;
   if (!Number.isSafeInteger(maxScanPages) || maxScanPages < 1) {
     throw new TypeError("maxScanPages must be a positive safe integer.");
@@ -301,10 +397,14 @@ function createAzureTableStorage(options = {}) {
       codec,
       formId,
       query,
-      options.toODataFilter?.(query) ?? metadataFiltersToOData(query)
+      options.toODataFilter?.(query) ?? metadataFiltersToOData(query, options.fieldMapping),
+      options.fieldMapping
     );
   };
-  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec) : void 0;
+  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec, options.fieldMapping, valueCodec) : void 0;
+  const ensureWritable = () => {
+    if (options.readOnly === true) throw new Error("Azure Table storage is read-only.");
+  };
   const listSubmissionCandidates = async (formId, query) => {
     const client = await submissionClient(formId, query);
     const found = [];
@@ -319,6 +419,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     async saveSchema(schema) {
+      ensureWritable();
       (0, import_core.assertValidFormSchema)(schema);
       const entity = {
         partitionKey: schema.id,
@@ -345,14 +446,20 @@ function createAzureTableStorage(options = {}) {
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
+      ensureWritable();
       await (await schemaClient(formId)).deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
+      ensureWritable();
       const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      const mappedEntity = mappedSubmissionEntity(codec.createEntity(stored), stored, options.fieldMapping, valueCodec);
+      const keys = physicalKeyNames(options.fieldMapping);
       await (await submissionClient(stored.formId)).createEntity({
-        ...codec.createEntity(stored),
+        ...mappedEntity,
         partitionKey: codec.createPartitionKey(stored),
-        rowKey: codec.createRowKey(stored)
+        rowKey: codec.createRowKey(stored),
+        [keys.partitionKey]: codec.createPartitionKey(stored),
+        [keys.rowKey]: codec.createRowKey(stored)
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -433,6 +540,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;
@@ -442,9 +554,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;
@@ -491,6 +603,7 @@ function createAzureTableStorage(options = {}) {
       };
     },
     async deleteSubmission(submissionId) {
+      ensureWritable();
       const client = await submissionClient("");
       for await (const raw of client.listEntities()) {
         const submission = deserializeIfMatching(raw);
@@ -503,6 +616,7 @@ function createAzureTableStorage(options = {}) {
       }
     },
     async clearResponses(formId) {
+      ensureWritable();
       const query = {};
       const client = await submissionClient(formId, query);
       for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
@@ -514,6 +628,7 @@ function createAzureTableStorage(options = {}) {
       }
     },
     async clear() {
+      ensureWritable();
       const schemas = await schemaClient("");
       for await (const raw of schemas.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
@@ -533,6 +648,7 @@ function createAzureTableStorage(options = {}) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAzureTableStorage,
+  createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec,
   metadataFiltersToOData,
   submissionFilterToOData

package/dist/index.d.cts

@@ -30,6 +30,24 @@ 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;
+}
+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;
@@ -38,6 +56,20 @@ interface AzureTableSubmissionCodec<T = FormSubmission> {
     readonly createPartitionKeyFromQuery: (formId: string, query: SubmissionPageQueryOptions) => string | undefined;
     readonly createRowKey: (value: T) => string;
 }
+interface AzureTableFieldMapping {
+    readonly partitionKeyProperty?: string;
+    readonly rowKeyProperty?: string;
+    readonly formId?: string;
+    readonly formVersion?: string;
+    readonly submittedAt?: string;
+    readonly values?: string;
+    readonly metadata?: string;
+    readonly customPropertyMappings?: Readonly<Record<string, string>>;
+}
+interface AzureTableValueCodec {
+    readonly encodeValues?: (values: Record<string, unknown>) => string;
+    readonly decodeValues?: (raw: string) => Record<string, unknown>;
+}
 interface AzureTableStorageOptions<T = FormSubmission> {
     /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
@@ -47,13 +79,15 @@ interface AzureTableStorageOptions<T = FormSubmission> {
         readonly formId: string;
         readonly query?: SubmissionPageQueryOptions;
     }) => AzureTableClientLike | Promise<AzureTableClientLike>;
-    readonly codec?: AzureTableSubmissionCodec<T>;
+    readonly codec?: AzureTableSubmissionCodec<T> | AzureTableValueCodec;
     /** @deprecated Use codec. */
     readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
     readonly buildSubmissionFilter?: (formId: string, query: SubmissionPageQueryOptions) => string;
     /** @deprecated Use buildSubmissionFilter. */
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
     readonly maxScanPages?: number;
+    readonly fieldMapping?: AzureTableFieldMapping;
+    readonly readOnly?: boolean;
 }
 interface AzureTextAnswerCursorPayload {
     readonly formatVersion: 1;
@@ -66,8 +100,8 @@ interface AzureTextAnswerCursorPayload {
     readonly fieldIndex: number;
 }
 declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
-declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
-declare function submissionFilterToOData(filter: SubmissionFilter): string | undefined;
+declare function metadataFiltersToOData(options: SubmissionPageQueryOptions, mapping?: AzureTableFieldMapping): string;
+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 AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, 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, createAzureTableStorage, createLegacyAzureTableCodec, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.d.ts

@@ -30,6 +30,24 @@ 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;
+}
+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;
@@ -38,6 +56,20 @@ interface AzureTableSubmissionCodec<T = FormSubmission> {
     readonly createPartitionKeyFromQuery: (formId: string, query: SubmissionPageQueryOptions) => string | undefined;
     readonly createRowKey: (value: T) => string;
 }
+interface AzureTableFieldMapping {
+    readonly partitionKeyProperty?: string;
+    readonly rowKeyProperty?: string;
+    readonly formId?: string;
+    readonly formVersion?: string;
+    readonly submittedAt?: string;
+    readonly values?: string;
+    readonly metadata?: string;
+    readonly customPropertyMappings?: Readonly<Record<string, string>>;
+}
+interface AzureTableValueCodec {
+    readonly encodeValues?: (values: Record<string, unknown>) => string;
+    readonly decodeValues?: (raw: string) => Record<string, unknown>;
+}
 interface AzureTableStorageOptions<T = FormSubmission> {
     /** @deprecated Use schemasTableClient, submissionsTableClient, or clientResolver. */
     readonly client?: AzureTableClientLike;
@@ -47,13 +79,15 @@ interface AzureTableStorageOptions<T = FormSubmission> {
         readonly formId: string;
         readonly query?: SubmissionPageQueryOptions;
     }) => AzureTableClientLike | Promise<AzureTableClientLike>;
-    readonly codec?: AzureTableSubmissionCodec<T>;
+    readonly codec?: AzureTableSubmissionCodec<T> | AzureTableValueCodec;
     /** @deprecated Use codec. */
     readonly submissionCodec?: AzureTableEntityCodec<FormSubmission>;
     readonly buildSubmissionFilter?: (formId: string, query: SubmissionPageQueryOptions) => string;
     /** @deprecated Use buildSubmissionFilter. */
     readonly toODataFilter?: (options: SubmissionPageQueryOptions) => string;
     readonly maxScanPages?: number;
+    readonly fieldMapping?: AzureTableFieldMapping;
+    readonly readOnly?: boolean;
 }
 interface AzureTextAnswerCursorPayload {
     readonly formatVersion: 1;
@@ -66,8 +100,8 @@ interface AzureTextAnswerCursorPayload {
     readonly fieldIndex: number;
 }
 declare const defaultAzureTableSubmissionCodec: AzureTableSubmissionCodec<FormSubmission>;
-declare function metadataFiltersToOData(options: SubmissionPageQueryOptions): string;
-declare function submissionFilterToOData(filter: SubmissionFilter): string | undefined;
+declare function metadataFiltersToOData(options: SubmissionPageQueryOptions, mapping?: AzureTableFieldMapping): string;
+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 AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, 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, createAzureTableStorage, createLegacyAzureTableCodec, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.js

@@ -1,5 +1,28 @@
 // src/index.ts
 import { assertValidFormSchema, matchesSubmissionPageFilters, normalizeSubmissionPageSize } from "@form-engine-ts/core";
+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 +131,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)) {
@@ -115,6 +143,60 @@ function parseSubmission(value, location) {
   }
   return cloneJson(parsed);
 }
+function propertyName(mapping, logicalName, fallback) {
+  return mapping?.customPropertyMappings?.[logicalName] ?? (logicalName === "formId" ? mapping?.formId : void 0) ?? (logicalName === "formVersion" ? mapping?.formVersion : void 0) ?? (logicalName === "submittedAt" ? mapping?.submittedAt : void 0) ?? (logicalName === "values" ? mapping?.values : void 0) ?? (logicalName === "metadata" ? mapping?.metadata : void 0) ?? fallback;
+}
+function physicalKeyNames(mapping) {
+  return {
+    partitionKey: mapping?.partitionKeyProperty ?? "PartitionKey",
+    rowKey: mapping?.rowKeyProperty ?? "RowKey"
+  };
+}
+function entityKey(entity, property, compatibilityProperty) {
+  return entity[property] ?? entity[compatibilityProperty];
+}
+function mappedSubmissionEntity(entity, submission, mapping, valueCodec) {
+  if (mapping === void 0 && valueCodec === void 0) return entity;
+  const keys = physicalKeyNames(mapping);
+  const values = valueCodec?.encodeValues?.({ ...submission.values }) ?? JSON.stringify(submission.values);
+  const metadata = submission.metadata === void 0 ? void 0 : JSON.stringify(submission.metadata);
+  return {
+    ...entity,
+    [keys.partitionKey]: submission.formId,
+    [keys.rowKey]: entity.rowKey ?? defaultSubmissionRowKey(submission),
+    [propertyName(mapping, "formId", "formId")]: submission.formId,
+    [propertyName(mapping, "formVersion", "formVersion")]: submission.formVersion,
+    [propertyName(mapping, "submittedAt", "submittedAt")]: submission.submittedAt,
+    [propertyName(mapping, "values", "values")]: values,
+    ...metadata === void 0 ? {} : { [propertyName(mapping, "metadata", "metadata")]: metadata }
+  };
+}
+function mappedSubmissionFromEntity(entity, mapping, valueCodec) {
+  const id = typeof entity.responseId === "string" ? entity.responseId : entity.id;
+  const formId = entity[propertyName(mapping, "formId", "formId")];
+  const formVersion = entity[propertyName(mapping, "formVersion", "formVersion")];
+  const submittedAt = entity[propertyName(mapping, "submittedAt", "submittedAt")];
+  const rawValues = entity[propertyName(mapping, "values", "values")];
+  if (typeof id !== "string" || typeof formId !== "string" || typeof formVersion !== "number" || typeof submittedAt !== "string" || typeof rawValues !== "string")
+    return void 0;
+  const values = valueCodec?.decodeValues?.(rawValues) ?? parseJson(rawValues, "submission values");
+  if (!isRecord(values) || !Object.values(values).every(isFormValue))
+    throw new Error("Azure Table values are invalid.");
+  const rawMetadata = entity[propertyName(mapping, "metadata", "metadata")];
+  const metadata = rawMetadata === void 0 ? void 0 : parseJson(rawMetadata, "submission metadata");
+  return parseSubmission(
+    {
+      id,
+      formId,
+      formVersion,
+      locale: typeof entity.locale === "string" ? entity.locale : "",
+      values,
+      ...metadata === void 0 || !isRecord(metadata) ? {} : { metadata },
+      submittedAt
+    },
+    "mapped submission entity"
+  );
+}
 function schemaRowKey(version) {
   return `schema_${version}`;
 }
@@ -174,12 +256,16 @@ function parseSchemaEntity(value) {
   }
   return cloneJson(schema);
 }
-function parseSubmissionEntity(value, codec) {
-  if (typeof value.partitionKey !== "string" || typeof value.rowKey !== "string" || !codec.matchesEntity(value)) {
+function parseSubmissionEntity(value, codec, mapping, valueCodec) {
+  const keys = physicalKeyNames(mapping);
+  const partitionKey = entityKey(value, keys.partitionKey, "partitionKey");
+  const rowKey = entityKey(value, keys.rowKey, "rowKey");
+  if (typeof partitionKey !== "string" || typeof rowKey !== "string" || !codec.matchesEntity(value)) {
     throw new Error("Azure Table submission entity is invalid.");
   }
-  const submission = parseSubmission(codec.deserialize(value), `submission ${value.partitionKey}/${value.rowKey}`);
-  if (codec.createPartitionKey(submission) !== value.partitionKey || codec.createRowKey(submission) !== value.rowKey) {
+  const submissionValue = mappedSubmissionFromEntity(value, mapping, valueCodec) ?? codec.deserialize(value);
+  const submission = parseSubmission(submissionValue, `submission ${partitionKey}/${rowKey}`);
+  if (codec.createPartitionKey(submission) !== partitionKey || codec.createRowKey(submission) !== rowKey) {
     throw new Error("Azure Table submission entity has inconsistent keys.");
   }
   return submission;
@@ -194,30 +280,36 @@ function valueToOData(value) {
   if (typeof value === "boolean") return String(value);
   throw new TypeError("Azure Table OData filters support only scalar JSON values.");
 }
-function metadataFiltersToOData(options) {
+function metadataFiltersToOData(options, mapping) {
   return Object.entries(options.metadataFilters ?? {}).map(([key, value]) => {
     if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) throw new TypeError(`Invalid Azure Table property name: ${key}`);
-    return `${key} eq ${valueToOData(value)}`;
+    const property = mapping?.customPropertyMappings?.[`metadata.${key}`] ?? mapping?.customPropertyMappings?.[key] ?? key;
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(property))
+      throw new TypeError(`Invalid Azure Table property name: ${property}`);
+    return `${property} eq ${valueToOData(value)}`;
   }).join(" and ");
 }
-function odataProperty(path) {
+function odataProperty(path, mapping) {
   if (path === "id" || path === "responseId") return "responseId";
-  if (["formVersion", "locale", "submittedAt"].includes(path)) return path;
+  if (["formVersion", "locale", "submittedAt"].includes(path)) {
+    return propertyName(mapping, path, path);
+  }
   if (path.startsWith("metadata.")) {
     const property = path.slice("metadata.".length);
-    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(property) ? property : void 0;
+    const mapped = mapping?.customPropertyMappings?.[path] ?? mapping?.customPropertyMappings?.[property] ?? property;
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(mapped) ? mapped : void 0;
   }
   return void 0;
 }
-function submissionFilterToOData(filter) {
+function submissionFilterToOData(filter, mapping) {
   if (filter.op === "and" || filter.op === "or") {
-    const converted = filter.filters.map(submissionFilterToOData);
+    const converted = filter.filters.map((child) => submissionFilterToOData(child, mapping));
     if (filter.op === "or" && converted.some((value) => value === void 0)) return void 0;
     const available = converted.filter((value) => value !== void 0 && value.length > 0);
     if (available.length === 0) return void 0;
     return available.map((value) => `(${value})`).join(filter.op === "and" ? " and " : " or ");
   }
-  const property = odataProperty(filter.path);
+  const property = odataProperty(filter.path, mapping);
   if (property === void 0) return void 0;
   if (filter.op === "eq") return `${property} eq ${valueToOData(filter.value)}`;
   if (filter.op === "in") {
@@ -230,15 +322,16 @@ function submissionFilterToOData(filter) {
     ...filter.to === void 0 ? [] : [`${property} le ${valueToOData(filter.to)}`]
   ].join(" and ");
 }
-function defaultSubmissionFilter(codec, formId, options, legacyExtension) {
+function defaultSubmissionFilter(codec, formId, options, legacyExtension, mapping) {
   const partitionKey = codec.createPartitionKeyFromQuery(formId, options);
-  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter);
+  const ast = options.filter === void 0 || typeof options.filter === "function" ? void 0 : submissionFilterToOData(options.filter, mapping);
+  const keys = physicalKeyNames(mapping);
   return [
-    ...partitionKey === void 0 ? [] : [`PartitionKey eq '${escapeOData(partitionKey)}'`],
+    ...partitionKey === void 0 ? [] : [`${keys.partitionKey} eq '${escapeOData(partitionKey)}'`],
     ...codec === defaultAzureTableSubmissionCodec ? ["kind eq 'submission'"] : [],
-    ...options.version === void 0 ? [] : [`formVersion eq ${options.version}`],
-    ...options.since === void 0 ? [] : [`submittedAt ge '${escapeOData(options.since)}'`],
-    ...options.until === void 0 ? [] : [`submittedAt le '${escapeOData(options.until)}'`],
+    ...options.version === void 0 ? [] : [`${propertyName(mapping, "formVersion", "formVersion")} eq ${options.version}`],
+    ...options.since === void 0 ? [] : [`${propertyName(mapping, "submittedAt", "submittedAt")} ge '${escapeOData(options.since)}'`],
+    ...options.until === void 0 ? [] : [`${propertyName(mapping, "submittedAt", "submittedAt")} le '${escapeOData(options.until)}'`],
     ...options.locale === void 0 ? [] : [`locale eq '${escapeOData(options.locale)}'`],
     ...ast === void 0 || ast.length === 0 ? [] : [`(${ast})`],
     ...legacyExtension.trim().length === 0 ? [] : [`(${legacyExtension})`]
@@ -257,7 +350,9 @@ function requireClient(client, name) {
 function createAzureTableStorage(options = {}) {
   const staticSchemas = options.schemasTableClient ?? options.client;
   const staticSubmissions = options.submissionsTableClient ?? options.client;
-  const codec = options.codec ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
+  const configuredCodec = options.codec;
+  const valueCodec = configuredCodec !== void 0 && "encodeValues" in configuredCodec ? configuredCodec : void 0;
+  const codec = (configuredCodec !== void 0 && "createEntity" in configuredCodec ? configuredCodec : void 0) ?? (options.submissionCodec === void 0 ? defaultAzureTableSubmissionCodec : legacyCodec(options.submissionCodec));
   const maxScanPages = options.maxScanPages ?? 5;
   if (!Number.isSafeInteger(maxScanPages) || maxScanPages < 1) {
     throw new TypeError("maxScanPages must be a positive safe integer.");
@@ -274,10 +369,14 @@ function createAzureTableStorage(options = {}) {
       codec,
       formId,
       query,
-      options.toODataFilter?.(query) ?? metadataFiltersToOData(query)
+      options.toODataFilter?.(query) ?? metadataFiltersToOData(query, options.fieldMapping),
+      options.fieldMapping
     );
   };
-  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec) : void 0;
+  const deserializeIfMatching = (entity) => codec.matchesEntity(entity) ? parseSubmissionEntity(entity, codec, options.fieldMapping, valueCodec) : void 0;
+  const ensureWritable = () => {
+    if (options.readOnly === true) throw new Error("Azure Table storage is read-only.");
+  };
   const listSubmissionCandidates = async (formId, query) => {
     const client = await submissionClient(formId, query);
     const found = [];
@@ -292,6 +391,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     async saveSchema(schema) {
+      ensureWritable();
       assertValidFormSchema(schema);
       const entity = {
         partitionKey: schema.id,
@@ -318,14 +418,20 @@ function createAzureTableStorage(options = {}) {
       return found.sort((left, right) => left.id.localeCompare(right.id) || left.version - right.version);
     },
     async deleteSchema(formId, formVersion) {
+      ensureWritable();
       await (await schemaClient(formId)).deleteEntity(formId, schemaRowKey(formVersion));
     },
     async saveSubmission(submission) {
+      ensureWritable();
       const stored = parseSubmission(submission, `input ${String(submission?.id)}`);
+      const mappedEntity = mappedSubmissionEntity(codec.createEntity(stored), stored, options.fieldMapping, valueCodec);
+      const keys = physicalKeyNames(options.fieldMapping);
       await (await submissionClient(stored.formId)).createEntity({
-        ...codec.createEntity(stored),
+        ...mappedEntity,
         partitionKey: codec.createPartitionKey(stored),
-        rowKey: codec.createRowKey(stored)
+        rowKey: codec.createRowKey(stored),
+        [keys.partitionKey]: codec.createPartitionKey(stored),
+        [keys.rowKey]: codec.createRowKey(stored)
       });
     },
     async listSubmissions(formId, formVersion, queryOptions = {}) {
@@ -406,6 +512,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;
@@ -415,9 +526,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;
@@ -464,6 +575,7 @@ function createAzureTableStorage(options = {}) {
       };
     },
     async deleteSubmission(submissionId) {
+      ensureWritable();
       const client = await submissionClient("");
       for await (const raw of client.listEntities()) {
         const submission = deserializeIfMatching(raw);
@@ -476,6 +588,7 @@ function createAzureTableStorage(options = {}) {
       }
     },
     async clearResponses(formId) {
+      ensureWritable();
       const query = {};
       const client = await submissionClient(formId, query);
       for await (const raw of client.listEntities({ queryOptions: { filter: queryFilter(formId, query) } })) {
@@ -487,6 +600,7 @@ function createAzureTableStorage(options = {}) {
       }
     },
     async clear() {
+      ensureWritable();
       const schemas = await schemaClient("");
       for await (const raw of schemas.listEntities()) {
         if (typeof raw.partitionKey === "string" && typeof raw.rowKey === "string") {
@@ -505,6 +619,7 @@ function createAzureTableStorage(options = {}) {
 }
 export {
   createAzureTableStorage,
+  createLegacyAzureTableCodec,
   defaultAzureTableSubmissionCodec,
   metadataFiltersToOData,
   submissionFilterToOData

package/package.json

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