refactor(apps): make the mapped-codec helpers generic and type-safe

Improves type declarativeness of the shared mapping helpers; no runtime
change (type-only), all converter tests still pass.

- `mappedDecode` / `mappedEncode` / `createMappedCodec` are now generic over
  the source document type. The field map is typed `FieldMap<Source>`
  (values constrained to `keyof Source`), so a misspelled/renamed source
  field is a compile error, and the result is the inferred
  `Decoded<Source, Map>` (renamed optional targets + typed
  `_unmappedProperties_` bucket) instead of `Record<string, any>`.
  `Source` defaults to a loose record so untyped call sites still work.
- `visitors`/`departments`/`roles` pass their `Source` type to get the
  typo-safety; a `@ts-expect-error` test locks the constraint.
- `mappedDecodeAsync` stays loose on the map (its consumers map dynamic
  livechat-only fields) but gains a `Result` type parameter, removing the
  `as unknown as Promise<…>` casts at uploads/rooms/messages/threads/contacts.
- Document the type strategy in the proposal.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0185hwJYnx3nzP4pcrYM2XXj

Author: claude

apps/meteor/app/apps/server/converters/codecs/contacts.ts

@@ -98,6 +98,6 @@ export const ContactCodec = z.codec(z.custom<ILivechatContact>(), z.custom<IApps
 			importIds: 'importIds',
 		};
 
-		return mappedDecodeAsync(contact, map) as unknown as Promise<ILivechatContact>;
+		return mappedDecodeAsync<ILivechatContact>(contact, map);
 	},
 });

apps/meteor/app/apps/server/converters/codecs/departments.ts

@@ -12,7 +12,7 @@ import { mappedDecode } from './mappedData';
  * unconditionally, then `_unmappedProperties_` merged on top.
  */
 export const DepartmentCodec = z.codec(z.custom<ILivechatDepartment>(), z.custom<IAppsDepartment>(), {
-	decode: mappedDecode({
+	decode: mappedDecode<ILivechatDepartment>({
 		id: '_id',
 		name: 'name',
 		email: 'email',

apps/meteor/app/apps/server/converters/codecs/mappedData.ts

@@ -1,91 +1,113 @@
 import * as z from 'zod';
 
+type Loose = Record<string, any>;
+
 /**
- * A declarative field map: keys are the Apps-Engine (target) property names, values are the
- * Rocket.Chat (source) property names. This is the "string" entry form supported by
- * {@link mappedDecodeAsync}.
+ * A declarative field map from Apps-Engine (target) property names to Rocket.Chat (source) property
+ * names. Values are constrained to the keys of `Source`, so mapping a renamed or misspelled source
+ * field is a compile error.
  */
-export type FieldMap = Record<string, string>;
+export type FieldMap<Source> = Record<string, Extract<keyof Source, string>>;
 
-type Loose = Record<string, any>;
+/**
+ * The Rocket.Chat -> Apps-Engine result of decoding `Source` through `Map`: each target property
+ * holds its source value (optional, since it is only set when the source value is defined), and
+ * everything the map did not name is collected under `_unmappedProperties_`.
+ */
+export type Decoded<Source, Map extends FieldMap<Source>> = {
+	-readonly [Target in keyof Map]?: Source[Map[Target]];
+} & {
+	_unmappedProperties_: Omit<Source, Map[keyof Map]>;
+};
 
 /**
- * The Rocket.Chat -> Apps-Engine transform for a plain string field map, reproducing the behaviour
- * of the legacy `transformMappedData` for the common "rename these fields, bucket the rest" case:
- * the input is deep-cloned (so the app can never mutate the stored document), each mapped source
- * field is copied to its target name when defined, and every remaining property is collected into
- * `_unmappedProperties_`.
+ * Rocket.Chat -> Apps-Engine transform for a plain string field map, reproducing the "rename these
+ * fields, bucket the rest" behaviour of the original mapping helper: the input is deep-cloned (so the
+ * app can never mutate the stored document), each mapped source field is copied to its target name
+ * when defined, and every remaining property is collected into `_unmappedProperties_`.
  */
-export function mappedDecode(fieldMap: FieldMap): (data: Loose) => Loose {
-	const appKeys = Object.keys(fieldMap);
+export function mappedDecode<Source extends Loose = Loose, const Map extends FieldMap<Source> = FieldMap<Source>>(
+	fieldMap: Map,
+): (data: Source) => Decoded<Source, Map> {
+	const entries = Object.entries(fieldMap) as [string, string][];
 
-	return (data: Loose): Loose => {
+	return (data: Source): Decoded<Source, Map> => {
 		const clone: Loose = structuredClone(data);
 		const result: Loose = {};
 
-		for (const appKey of appKeys) {
-			const sourceKey = fieldMap[appKey];
-
+		for (const [target, sourceKey] of entries) {
 			if (typeof clone[sourceKey] !== 'undefined') {
-				result[appKey] = clone[sourceKey];
+				result[target] = clone[sourceKey];
 			}
 
 			delete clone[sourceKey];
 		}
 
 		result._unmappedProperties_ = clone;
 
-		return result;
+		return result as Decoded<Source, Map>;
 	};
 }
 
 /**
- * The Apps-Engine -> Rocket.Chat transform for a plain string field map: the inverse rename (target
- * fields copied back to their source names when defined) with `_unmappedProperties_` merged onto the
- * result. This is the symmetric counterpart to {@link mappedDecode}; converters whose reverse
- * direction has defaults, conditional fields or asymmetric mappings provide their own `encode`.
+ * The Apps-Engine -> Rocket.Chat inverse of {@link mappedDecode}: target fields are copied back to
+ * their source names when defined and `_unmappedProperties_` is merged onto the result. Because both
+ * the renamed keys and the bucket originate from `Source`, the result is a `Partial<Source>`.
+ *
+ * This is the symmetric counterpart to {@link mappedDecode}; converters whose reverse direction has
+ * defaults, conditional fields or asymmetric mappings provide their own `encode`.
  */
-export function mappedEncode(fieldMap: FieldMap): (app: Loose) => Loose {
-	const appKeys = Object.keys(fieldMap);
+export function mappedEncode<Source extends Loose = Loose, const Map extends FieldMap<Source> = FieldMap<Source>>(
+	fieldMap: Map,
+): (app: Decoded<Source, Map>) => Partial<Source> {
+	const entries = Object.entries(fieldMap) as [string, string][];
 
-	return (app: Loose): Loose => {
-		const { _unmappedProperties_ = {}, ...rest } = app;
+	return (app: Decoded<Source, Map>): Partial<Source> => {
+		const { _unmappedProperties_ = {}, ...rest } = app as Loose;
 		const result: Loose = {};
 
-		for (const appKey of appKeys) {
-			if (typeof rest[appKey] !== 'undefined') {
-				result[fieldMap[appKey]] = rest[appKey];
+		for (const [target, sourceKey] of entries) {
+			if (typeof rest[target] !== 'undefined') {
+				result[sourceKey] = rest[target];
 			}
 		}
 
-		return { ...result, ..._unmappedProperties_ };
+		return { ...result, ..._unmappedProperties_ } as Partial<Source>;
 	};
 }
 
 /**
- * A map whose entries are one of the three forms the legacy `transformMappedData` supports:
- * a source property name (string), a function that derives the target value from the (cloned)
- * source data, or a nested `{ from, map, list }` descriptor for sub-objects and arrays.
+ * A map whose entries are one of the three forms the original mapping helper supports: a source
+ * property name (string), a function that derives the target value from the (cloned) source data,
+ * or a nested `{ from, map, list }` descriptor for sub-objects and arrays.
+ *
+ * Unlike {@link FieldMap}, this is intentionally loosely typed: its consumers (rooms, messages,
+ * uploads) map many optional/livechat-only fields that are not part of the base document types.
  */
 export type AsyncFieldMap = Record<
 	string,
 	string | ((data: Record<string, any>) => unknown | Promise<unknown>) | { from: string; map?: AsyncFieldMap; list?: boolean }
 >;
 
 /**
- * Rocket.Chat -> Apps-Engine transform for a map mixing string renames and (possibly async)
- * derived-value functions. This reproduces the string and function branches of the legacy
- * `transformMappedData` exactly:
+ * Rocket.Chat -> Apps-Engine transform for a map mixing string renames, (possibly async) derived-value
+ * functions and nested `{ from, map, list }` descriptors, reproducing the original mapping helper
+ * exactly:
  *
- * - the input is deep-cloned up front, so functions may freely mutate the clone (e.g. `delete`
- *   fields they consume) and the app can never mutate the stored document;
+ * - the input is deep-cloned up front, so functions may freely mutate the clone (e.g. `delete` fields
+ *   they consume) and the app can never mutate the stored document;
  * - string entries copy the source field to the target name when defined and always drop the source
  *   key from the bucket;
  * - function entries receive the clone and set the target only when they return a defined value
- *   (functions are responsible for deleting any source keys they consume, as before);
+ *   (functions are responsible for deleting any source keys they consume);
+ * - nested entries recurse (producing a `_unmappedProperties_` bucket at each level), and `list`
+ *   entries map arrays element-by-element (or wrap a lone value into a single-element array);
  * - everything left in the clone becomes `_unmappedProperties_`.
+ *
+ * The result shape is caller-asserted via the `Result` type parameter, since it depends on the map's
+ * function/nested entries in ways that are not worth expressing in the type system.
  */
-export async function mappedDecodeAsync(data: Loose, map: AsyncFieldMap): Promise<Loose> {
+export async function mappedDecodeAsync<Result = Loose>(data: Loose, map: AsyncFieldMap): Promise<Result> {
 	const clone: Loose = structuredClone(data);
 	const result: Loose = {};
 
@@ -125,18 +147,19 @@ export async function mappedDecodeAsync(data: Loose, map: AsyncFieldMap): Promis
 
 	result._unmappedProperties_ = clone;
 
-	return result;
+	return result as Result;
 }
 
 /**
  * Builds a Zod codec from a plain string field map, using {@link mappedDecode} / {@link mappedEncode}.
+ * `decode` produces {@link Decoded}; `encode` is its inverse.
  *
  * The endpoints are typed with `z.custom` so no runtime validation is added yet (behaviour-preserving);
  * schemas can be tightened later without changing the transform logic.
  */
-export function createMappedCodec(fieldMap: FieldMap) {
-	return z.codec(z.custom<Loose>(), z.custom<Loose>(), {
-		decode: mappedDecode(fieldMap),
-		encode: mappedEncode(fieldMap),
+export function createMappedCodec<Source extends Loose = Loose, const Map extends FieldMap<Source> = FieldMap<Source>>(fieldMap: Map) {
+	return z.codec(z.custom<Source>(), z.custom<Decoded<Source, Map>>(), {
+		decode: mappedDecode<Source, Map>(fieldMap),
+		encode: (app) => mappedEncode<Source, Map>(fieldMap)(app) as Source,
 	});
 }

apps/meteor/app/apps/server/converters/codecs/roles.ts

@@ -1,12 +1,15 @@
+import type { IRole } from '@rocket.chat/core-typings';
+
 import { createMappedCodec } from './mappedData';
 
 /**
  * Rocket.Chat `IRole` <-> Apps-Engine role.
  *
  * A pure field-rename with an `_unmappedProperties_` bucket, so it is expressed directly via
- * {@link createMappedCodec}. Keys are the Apps-Engine names, values the Rocket.Chat names.
+ * {@link createMappedCodec}. Keys are the Apps-Engine names, values the Rocket.Chat names (checked
+ * against `keyof IRole`).
  */
-export const RoleCodec = createMappedCodec({
+export const RoleCodec = createMappedCodec<IRole>({
 	id: '_id',
 	name: 'name',
 	description: 'description',

apps/meteor/app/apps/server/converters/codecs/rooms.ts

@@ -110,7 +110,7 @@ export async function decodeRoomRaw(room: IRoom): Promise<IAppsRoomRaw> {
 		},
 	};
 
-	return mappedDecodeAsync(room, map) as unknown as Promise<IAppsRoomRaw>;
+	return mappedDecodeAsync<IAppsRoomRaw>(room, map);
 }
 
 async function getCreator(user: string | undefined) {
@@ -455,7 +455,7 @@ export function createRoomCodec(orch: IAppServerOrchestrator) {
 				}),
 			};
 
-			return mappedDecodeAsync(originalRoom, map) as unknown as Promise<IAppsRoom | IAppsLivechatRoom>;
+			return mappedDecodeAsync<IAppsRoom | IAppsLivechatRoom>(originalRoom, map);
 		},
 		encode: (room): Promise<IRoom> => appRoomToRocketChat(room, false) as unknown as Promise<IRoom>,
 	});

apps/meteor/app/apps/server/converters/codecs/uploads.ts

@@ -60,7 +60,7 @@ export function createUploadsCodec(orch: IAppServerOrchestrator) {
 				},
 			};
 
-			return mappedDecodeAsync(upload, map) as unknown as Promise<IAppsUpload>;
+			return mappedDecodeAsync<IAppsUpload>(upload, map);
 		},
 		encode: (upload): IUpload => {
 			const { id: userId } = upload.user || {};

apps/meteor/app/apps/server/converters/codecs/visitors.ts

@@ -13,7 +13,7 @@ import { mappedDecode } from './mappedData';
  * write `_updatedAt`/`activity` back, and merges `_unmappedProperties_`.
  */
 export const VisitorCodec = z.codec(z.custom<ILivechatVisitor>(), z.custom<IAppsVisitor>(), {
-	decode: mappedDecode({
+	decode: mappedDecode<ILivechatVisitor>({
 		id: '_id',
 		username: 'username',
 		name: 'name',

apps/meteor/app/apps/server/converters/messages.ts

@@ -66,7 +66,7 @@ export class AppMessagesConverter implements IAppMessagesConverter {
 			type: 't',
 		} as const;
 
-		return mappedDecodeAsync(message, map) as unknown as Promise<IAppsMesssageRaw>;
+		return mappedDecodeAsync<IAppsMesssageRaw>(message, map);
 	}
 
 	convertMessage(msgObj: undefined | null): Promise<undefined>;
@@ -161,7 +161,7 @@ export class AppMessagesConverter implements IAppMessagesConverter {
 			},
 		} as const;
 
-		return mappedDecodeAsync(msgObj, map) as unknown as Promise<IAppsMessage>;
+		return mappedDecodeAsync<IAppsMessage>(msgObj, map);
 	}
 
 	convertAppMessage(message: undefined | null): Promise<undefined>;

apps/meteor/app/apps/server/converters/threads.ts

@@ -131,7 +131,7 @@ export class AppThreadsConverter implements IAppThreadsConverter {
 			reactions: msgObj.reactions as unknown as AppsEngineMessage['reactions'],
 		} as IMessage & { reactions?: AppsEngineMessage['reactions'] };
 
-		return mappedDecodeAsync(msgData, map as unknown as AsyncFieldMap) as unknown as Promise<AppsEngineMessage>;
+		return mappedDecodeAsync<AppsEngineMessage>(msgData, map as unknown as AsyncFieldMap);
 	}
 
 	async _convertAttachmentsToApp(

apps/meteor/tests/unit/app/apps/server/codecs/mappedData.spec.ts

@@ -2,7 +2,7 @@ import { expect } from 'chai';
 import { describe, it } from 'mocha';
 import * as z from 'zod';
 
-import { createMappedCodec, mappedDecodeAsync } from '../../../../../../app/apps/server/converters/codecs/mappedData';
+import { createMappedCodec, mappedDecode, mappedDecodeAsync } from '../../../../../../app/apps/server/converters/codecs/mappedData';
 
 describe('createMappedCodec', () => {
 	const codec = createMappedCodec({
@@ -153,3 +153,18 @@ describe('mappedDecodeAsync', () => {
 		expect(result).to.deep.equal({ _unmappedProperties_: { os: 'android', version: '1.9', lan: 'en' } });
 	});
 });
+
+describe('mappedDecode type constraints', () => {
+	type Source = { _id: string; name: string };
+
+	it('constrains map values to keys of the source type and infers the decoded shape', () => {
+		const decode = mappedDecode<Source>({ id: '_id', label: 'name' });
+		const result = decode({ _id: 'a', name: 'b' });
+
+		// `result` is typed `Decoded<Source, ...>`: renamed targets plus the bucket.
+		expect(result).to.deep.equal({ id: 'a', label: 'b', _unmappedProperties_: {} });
+
+		// @ts-expect-error - 'missing' is not a key of Source, so the field map is rejected.
+		mappedDecode<Source>({ id: 'missing' });
+	});
+});