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

package/dist/index.cjs

@@ -142,6 +142,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 +255,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 +279,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 +321,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 +349,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 +368,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 +390,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     async saveSchema(schema) {
+      ensureWritable();
       (0, import_core.assertValidFormSchema)(schema);
       const entity = {
         partitionKey: schema.id,
@@ -345,14 +417,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 = {}) {
@@ -491,6 +569,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 +582,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 +594,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") {

package/dist/index.d.cts

@@ -38,6 +38,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 +61,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 +82,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 AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.d.ts

@@ -38,6 +38,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 +61,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 +82,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 AzureTableListOptions, type AzureTablePageSettings, type AzureTableStorageOptions, type AzureTableSubmissionCodec, type AzureTableValueCodec, type AzureTextAnswerCursorPayload, createAzureTableStorage, defaultAzureTableSubmissionCodec, metadataFiltersToOData, submissionFilterToOData };

package/dist/index.js

@@ -115,6 +115,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 +228,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 +252,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 +294,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 +322,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 +341,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 +363,7 @@ function createAzureTableStorage(options = {}) {
   };
   return {
     async saveSchema(schema) {
+      ensureWritable();
       assertValidFormSchema(schema);
       const entity = {
         partitionKey: schema.id,
@@ -318,14 +390,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 = {}) {
@@ -464,6 +542,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 +555,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 +567,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") {

package/package.json

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