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

@@ -63,7 +63,10 @@ export type RestApiHandlerOptions<Schema extends SchemaDef = SchemaDef> = {
     /**
      * Mapping from model names to unique field name to be used as resource's ID.
      */
-    externalIdMapping?: Record<string, string>;
+    /**
+     * Mapping from model names to unique key name or array of column names to be used as resource's ID.
+     */
+    externalIdMapping?: Record<string, string | string[]>;
 };
 
 type RelationshipInfo = {
@@ -260,7 +263,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);
@@ -296,7 +299,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) {
@@ -1334,24 +1337,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 {
@@ -1365,7 +1397,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`);
@@ -1379,7 +1412,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

@@ -3092,6 +3092,8 @@ describe('REST server tests', () => {
         posts Post[]
 
         @@unique([name, source])
+        @@unique([email_with_underscore])
+        email_with_underscore String @unique
     }
 
     model Post {
@@ -3101,9 +3103,8 @@ describe('REST server tests', () => {
         authorId Int?
     }
     `;
-        beforeEach(async () => {
+        it('works with id mapping (unique key name as string)', async () => {
             client = await createTestClient(schema);
-
             const _handler = new RestApiHandler({
                 schema: client.$schema,
                 endpoint: 'http://localhost/api',
@@ -3112,11 +3113,9 @@ describe('REST server tests', () => {
                 },
             });
             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' },
+                data: { id: 1, name: 'User1', source: 'a', email_with_underscore: 'e1' },
             });
 
             // user is no longer exposed using the `id` field
@@ -3126,7 +3125,6 @@ describe('REST server tests', () => {
                 query: {},
                 client,
             });
-
             expect(r.status).toBe(422);
             expect(r.body.errors[0].code).toBe('validation-error');
 
@@ -3137,7 +3135,6 @@ describe('REST server tests', () => {
                 query: {},
                 client,
             });
-
             expect(r.status).toBe(200);
             expect(r.body.data.attributes.source).toBe('a');
             expect(r.body.data.attributes.name).toBe('User1');
@@ -3153,7 +3150,6 @@ describe('REST server tests', () => {
                 query: { include: 'author' },
                 client,
             });
-
             expect(r.status).toBe(200);
             expect(r.body.data.attributes.title).toBe('Title1');
             // Verify author relationship contains the external ID
@@ -3162,6 +3158,57 @@ describe('REST server tests', () => {
                 id: 'User1_a',
             });
         });
+
+        it('works with id mapping (array of columns)', async () => {
+            client = await createTestClient(schema);
+            const _handler = new RestApiHandler({
+                schema: client.$schema,
+                endpoint: 'http://localhost/api',
+                externalIdMapping: {
+                    User: ['name', 'source'],
+                },
+            });
+            handler = (args) => _handler.handleRequest({ ...args, url: new URL(`http://localhost/${args.path}`) });
+
+            await client.user.create({
+                data: { id: 2, name: 'User2', source: 'b', email_with_underscore: 'e2' },
+            });
+
+            let r = await handler({
+                method: 'get',
+                path: '/user/User2_b',
+                query: {},
+                client,
+            });
+            expect(r.status).toBe(200);
+            expect(r.body.data.attributes.source).toBe('b');
+            expect(r.body.data.attributes.name).toBe('User2');
+        });
+
+        it('works with id mapping (single column with underscore)', async () => {
+            client = await createTestClient(schema);
+            const _handler = new RestApiHandler({
+                schema: client.$schema,
+                endpoint: 'http://localhost/api',
+                externalIdMapping: {
+                    User: ['email_with_underscore'],
+                },
+            });
+            handler = (args) => _handler.handleRequest({ ...args, url: new URL(`http://localhost/${args.path}`) });
+
+            await client.user.create({
+                data: { id: 3, name: 'User3', source: 'c', email_with_underscore: 'e3' },
+            });
+
+            let r = await handler({
+                method: 'get',
+                path: '/user/e3',
+                query: {},
+                client,
+            });
+            expect(r.status).toBe(200);
+            expect(r.body.data.attributes.email_with_underscore).toBe('e3');
+        });
     });
 
     describe('REST server tests - procedures', () => {
@@ -3266,7 +3313,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,
@@ -3287,7 +3335,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,
             });
 
@@ -3400,7 +3448,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,
             });