make it optionally possible to define externalIdMapping using an array of columns and not a unique key name

Author: lsmith77

packages/server/src/api/rest/index.ts

@@ -61,9 +61,9 @@ export type RestApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
     modelNameMapping?: Record<string, string>;
 
     /**
-     * Mapping from model names to unique field name to be used as resource's ID.
+     * Mapping from model names to unique index fields names to be used as resource's ID.
      */
-    externalIdMapping?: Record<string, string>;
+    externalIdMapping?: Record<string, string | string[]>;
 };
 
 type RelationshipInfo = {
@@ -261,7 +261,7 @@ export class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
     private urlPatternMap: Record<UrlPatterns, UrlPattern>;
     private modelNameMapping: Record<string, string>;
     private reverseModelNameMapping: Record<string, string>;
-    private externalIdMapping: Record<string, string>;
+    private externalIdMapping: Record<string, string | string[]>;
 
     constructor(private readonly options: RestApiHandlerOptions<Schema>) {
         this.validateOptions(options);
@@ -297,7 +297,7 @@ export class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
             idDivider: z.string().min(1).optional(),
             urlSegmentCharset: z.string().min(1).optional(),
             modelNameMapping: z.record(z.string(), z.string()).optional(),
-            externalIdMapping: z.record(z.string(), z.string()).optional(),
+            externalIdMapping: z.record(z.string(), z.union([z.string(), z.array(z.string()).min(1)])).optional(),
         });
         const parseResult = schema.safeParse(options);
         if (!parseResult.success) {
@@ -1335,24 +1335,53 @@ export class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
         const modelDef = this.requireModel(model);
         const modelLower = lowerCaseFirst(model);
         if (!(modelLower in this.externalIdMapping)) {
-            return Object.values(modelDef.fields).filter((f) => modelDef.idFields.includes(f.name));
-        }
-
-        // map external ID name to unique constraint field
-        const externalIdName = this.externalIdMapping[modelLower];
-        for (const [name, info] of Object.entries(modelDef.uniqueFields)) {
-            if (name === externalIdName) {
-                if (typeof info.type === 'string') {
-                    // single unique field
-                    return [this.requireField(model, info.type)];
-                } else {
+            return Object.values(modelDef.fields).filter(
+                (f) => (f as FieldDef).name && modelDef.idFields.includes((f as FieldDef).name),
+            ) as FieldDef[];
+        }
+
+        // map external ID name or columns to unique constraint field(s)
+        const externalId = this.externalIdMapping[modelLower];
+        let resolved: FieldDef[] | undefined;
+        if (typeof externalId === 'string') {
+            // Try to match unique key name first
+            for (const [name, info] of Object.entries(modelDef.uniqueFields as Record<string, unknown>)) {
+                const infoTyped = info as any;
+                if (name === externalId) {
+                    if (typeof infoTyped.type === 'string') {
+                        // single unique field
+                        resolved = [this.requireField(model, name)];
+                        break;
+                    }
                     // compound unique fields
-                    return Object.keys(info).map((f) => this.requireField(model, f));
+                    resolved = Object.keys(infoTyped).map((f) => this.requireField(model, f));
+                    break;
                 }
             }
-        }
-
-        throw new Error(`Model ${model} does not have unique key ${externalIdName}`);
+            // If not found, treat as a single column name (for single-column unique index with underscores)
+            if (modelDef.fields[externalId]) {
+                resolved = [this.requireField(model, externalId)];
+            }
+        } else if (Array.isArray(externalId)) {
+            // Array of column names (for compound or single unique index)
+            resolved = externalId.map((col) => this.requireField(model, col));
+        }
+
+        if (!resolved) {
+            throw new Error(`Invalid externalIdMapping for model ${model}`);
+        }
+        const resolvedNames = resolved.map((f) => f.name);
+        const uniqueSets = this.getUniqueFieldSets(model);
+        const isUnique =
+            uniqueSets.some(
+                (set) => set.length === resolvedNames.length && set.every((f, i) => f === resolvedNames[i]),
+            ) ||
+            (modelDef.idFields.length === resolvedNames.length &&
+                modelDef.idFields.every((f, i) => f === resolvedNames[i]));
+        if (!isUnique) {
+            throw new Error(`Model ${model} externalIdMapping must reference unique fields`);
+        }
+        return resolved;
     }
 
     private requireField(model: string, field: string): FieldDef {
@@ -1366,7 +1395,8 @@ export class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
 
     private buildTypeMap() {
         this.typeMap = {};
-        for (const [model, { fields }] of Object.entries(this.schema.models)) {
+        for (const [model, modelVal] of Object.entries(this.schema.models as Record<string, unknown>)) {
+            const fields = (modelVal as any).fields as Record<string, FieldDef>;
             const idFields = this.getIdFields(model);
             if (idFields.length === 0) {
                 log(this.options.log, 'warn', `Not including model ${model} in the API because it has no ID field`);
@@ -1380,7 +1410,8 @@ export class RestApiHandler<Schema extends SchemaDef = SchemaDef> implements Api
                 fields,
             });
 
-            for (const [field, fieldInfo] of Object.entries(fields)) {
+            for (const [field, fieldInfoRaw] of Object.entries(fields)) {
+                const fieldInfo = fieldInfoRaw as any;
                 if (!fieldInfo.relation) {
                     continue;
                 }

packages/server/test/api/options-validation.test.ts

@@ -192,7 +192,7 @@ describe('API Handler Options Validation', () => {
             }).toThrow('Invalid options');
         });
 
-        it('should throw error when externalIdMapping values are not strings', () => {
+        it('should throw error when externalIdMapping values are not string or string[]', () => {
             expect(() => {
                 new RestApiHandler({
                     schema: client.$schema,
@@ -202,6 +202,16 @@ describe('API Handler Options Validation', () => {
             }).toThrow('Invalid options');
         });
 
+        it('should accept externalIdMapping as string[]', () => {
+            expect(() => {
+                new RestApiHandler({
+                    schema: client.$schema,
+                    endpoint: 'http://localhost/api',
+                    externalIdMapping: { User: ['email'] },
+                });
+            }).not.toThrow();
+        });
+
         it('should throw error when log is invalid type', () => {
             expect(() => {
                 new RestApiHandler({

packages/server/test/api/rest.test.ts

@@ -3185,6 +3185,28 @@ describe('REST server tests', () => {
         title String
         author User? @relation(fields: [authorId], references: [id])
         authorId Int?
+        comments Comment[]
+        images Image[]
+    }
+
+    model Comment {
+        
+        id Int @id @default(autoincrement())
+        content String
+        short_title String
+        post_id Int
+        post Post @relation(fields: [post_id], references: [id])
+
+        @@unique([short_title, post_id])
+    }
+
+    model Image {
+        
+        id Int @id @default(autoincrement())
+        content String
+        short_title String @unique
+        post_id Int
+        post Post @relation(fields: [post_id], references: [id])
     }
     `;
         beforeEach(async () => {
@@ -3195,16 +3217,27 @@ describe('REST server tests', () => {
                 endpoint: 'http://localhost/api',
                 externalIdMapping: {
                     User: 'name_source',
+                    Image: 'short_title',
+                    Comment: ['short_title', 'post_id'],
                 },
             });
             handler = (args) => _handler.handleRequest({ ...args, url: new URL(`http://localhost/${args.path}`) });
-        });
 
-        it('works with id mapping', async () => {
             await client.user.create({
                 data: { id: 1, name: 'User1', source: 'a' },
             });
+            await client.post.create({
+                data: { id: 2, title: 'Some title', authorId: 1 },
+            });
+            await client.comment.create({
+                data: { id: 3, short_title: 'comment-title', post_id: 2, content: 'Comment1' },
+            });
+            await client.image.create({
+                data: { id: 1, short_title: 'image-title', post_id: 2, content: 'Image1' },
+            });
+        });
 
+        it('works with id mapping', async () => {
             // user is no longer exposed using the `id` field
             let r = await handler({
                 method: 'get',
@@ -3248,6 +3281,29 @@ describe('REST server tests', () => {
                 id: 'User1_a',
             });
         });
+
+        it('works with externalIdMapping as single column with underscore (single unique index)', async () => {
+            const r = await handler({
+                method: 'get',
+                path: '/image/image-title',
+                query: {},
+                client,
+            });
+            expect(r.status).toBe(200);
+            expect(r.body.data.attributes.content).toBe('Image1');
+        });
+
+        it('works with externalIdMapping as array of fields (compound unique index)', async () => {
+            const r = await handler({
+                method: 'get',
+                path: '/comment/comment-title_2',
+                query: {},
+                client,
+            });
+            expect(r.status).toBe(200);
+            expect(r.body.data.attributes.short_title).toBe('comment-title');
+            expect(r.body.data.attributes.post_id).toBe(2);
+        });
     });
 
     describe('REST server tests - procedures', () => {
@@ -3352,7 +3408,8 @@ mutation procedure sum(a: Int, b: Int): Int
                         const b = args?.b as number | undefined;
                         return (a ?? 0) + (b ?? 0);
                     },
-                    sumIds: async ({ args }: ProcCtx<SumIdsArgs>) => (args.ids as number[]).reduce((acc, x) => acc + x, 0),
+                    sumIds: async ({ args }: ProcCtx<SumIdsArgs>) =>
+                        (args.ids as number[]).reduce((acc, x) => acc + x, 0),
                     echoRole: async ({ args }: ProcCtx<EchoRoleArgs>) => args.r,
                     echoOverview: async ({ args }: ProcCtx<EchoOverviewArgs>) => args.o,
                     sum: async ({ args }: ProcCtx<SumArgs>) => args.a + args.b,
@@ -3373,7 +3430,7 @@ mutation procedure sum(a: Int, b: Int): Int
             const r = await handler({
                 method: 'get',
                 path: '/$procs/echoDecimal',
-                query: { ...json as object, meta: { serialization: meta } } as any,
+                query: { ...(json as object), meta: { serialization: meta } } as any,
                 client,
             });
 
@@ -3486,7 +3543,7 @@ mutation procedure sum(a: Int, b: Int): Int
             const r = await handler({
                 method: 'post',
                 path: '/$procs/sum',
-                requestBody: { ...json as object, meta: { serialization: meta } } as any,
+                requestBody: { ...(json as object), meta: { serialization: meta } } as any,
                 client,
             });