@auto-engineer/server-generator-apollo-emmett 1.131.0 → 1.135.0

package/src/codegen/templates/query/projection.specs.ts

@@ -1008,4 +1008,327 @@ describe('projection.ts.ejs', () => {
     expect(projectionFile?.contents).not.toContain('number | "pending"');
     expect(projectionFile?.contents).toContain('mixedStatus: /* TODO: map from event.data */ undefined as any');
   });
+
+  it('should generate switch-based getDocumentId when events come from slices with different id fields', async () => {
+    const flows: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'workout-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'create-workout',
+              stream: 'workouts-${id}',
+              client: { specs: [] },
+              server: {
+                description: 'creates a workout',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Create workout',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'success',
+                            steps: [
+                              { keyword: 'When', text: 'CreateWorkout', docString: { id: 'w1', name: 'Leg Day' } },
+                              { keyword: 'Then', text: 'WorkoutCreated', docString: { id: 'w1', name: 'Leg Day' } },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'command',
+              name: 'log-exercises',
+              stream: 'workouts-${workoutId}',
+              client: { specs: [] },
+              server: {
+                description: 'logs exercises to a workout',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Log exercises',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'success',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'LogExercises',
+                                docString: { workoutId: 'w1', exercise: 'Squats' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ExerciseLogged',
+                                docString: { workoutId: 'w1', exercise: 'Squats' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-workout',
+              stream: 'workouts',
+              client: { specs: [] },
+              server: {
+                description: 'projection for workout details',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'WorkoutView' },
+                      origin: {
+                        type: 'projection',
+                        name: 'WorkoutProjection',
+                        idField: 'id',
+                      },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View workout',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'workout created',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'WorkoutCreated',
+                                docString: { id: 'w1', name: 'Leg Day' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'WorkoutView',
+                                docString: { id: 'w1', name: 'Leg Day', exercises: [] },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'exercise logged',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'ExerciseLogged',
+                                docString: { workoutId: 'w1', exercise: 'Squats' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'WorkoutView',
+                                docString: { id: 'w1', name: 'Leg Day', exercises: ['Squats'] },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateWorkout',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'LogExercises',
+          fields: [
+            { name: 'workoutId', type: 'string', required: true },
+            { name: 'exercise', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'WorkoutCreated',
+          source: 'internal',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ExerciseLogged',
+          source: 'internal',
+          fields: [
+            { name: 'workoutId', type: 'string', required: true },
+            { name: 'exercise', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'WorkoutView',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+            { name: 'exercises', type: 'Array<string>', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(flows.narratives, flows.messages, undefined, 'src/domain/flows');
+    const projectionFile = plans.find((p) => p.outputPath.endsWith('view-workout/projection.ts'));
+
+    expect(projectionFile?.contents).toMatchInlineSnapshot(`
+      "import {
+        inMemorySingleStreamProjection,
+        type ReadEvent,
+        type InMemoryReadEventMetadata,
+      } from '@event-driven-io/emmett';
+      import type { WorkoutView } from './state';
+      import type { WorkoutCreated } from '../create-workout/events';
+
+      import type { ExerciseLogged } from '../log-exercises/events';
+
+      type AllEvents = ExerciseLogged | WorkoutCreated;
+
+      // Auto-generated — do not change this function, its imports, or type parameters.
+      // Only implement the case bodies inside evolve.
+      export const projection = inMemorySingleStreamProjection<WorkoutView, AllEvents>({
+        collectionName: 'WorkoutProjection',
+        canHandle: ['WorkoutCreated', 'ExerciseLogged'],
+        getDocumentId: (event) => {
+          switch (event.type) {
+            case 'WorkoutCreated':
+              return event.data.id;
+
+            case 'ExerciseLogged':
+              return event.data.workoutId;
+
+            default:
+              return event.data.id;
+          }
+        },
+        evolve: (
+          document: WorkoutView | null,
+          event: ReadEvent<AllEvents, InMemoryReadEventMetadata>,
+        ): WorkoutView | null => {
+          switch (event.type) {
+            case 'WorkoutCreated': {
+              /**
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+      *
+      * Derive ALL field values from event.data or existing document state.
+      * NEVER hardcode constant values — every output field must trace to an input.
+      * Preserve all import paths above — they are generated from the model.
+      * ⚠️ \`document\` may be null (first event for this entity). Guard before accessing properties.
+      *
+      * CONSTRAINTS:
+      * - NEVER use \`as SomeType\` type assertions. Declare typed variables instead: \`const x: Type = value;\`
+      * - Only reference event.data fields listed in the "Event fields:" line below.
+      * - Do NOT modify anything outside this case block: imports, type parameters, canHandle, collectionName, and getDocumentId are auto-generated.
+      *
+          * Implement how this event updates the projection.
+          *
+          * **Internal State Pattern (extends, never replaces the imported type):**
+          * If you need to track state beyond the public WorkoutView type (e.g., to calculate
+          * aggregations, track previous values, etc.), you may EXTEND it with an interface (never replace it):
+          *
+          * 1. Define an extended interface BEFORE the projection:
+          *    interface InternalWorkoutView extends WorkoutView {
+          *      internalField: SomeType;
+          *    }
+          *
+          * 2. Assign document to extended type:
+          *    const current: InternalWorkoutView = document ?? { ...defaults };
+          *
+          * 3. Return via typed variable (preserves internal state for next event):
+          *    const result: InternalWorkoutView = { ...allFields, internalField };
+          *    return result;
+          *
+          * This keeps internal state separate from the public GraphQL schema.
+
+          * Event (WorkoutCreated) fields: id: string, name: string
+      */
+              return {
+                ...document,
+                id: /* TODO: map from event.data */ '',
+                name: /* TODO: map from event.data */ '',
+                exercises: /* TODO: map from event.data */ [],
+              };
+            }
+
+            case 'ExerciseLogged': {
+              /**
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+      *
+      * Derive ALL field values from event.data or existing document state.
+      * NEVER hardcode constant values — every output field must trace to an input.
+      * Preserve all import paths above — they are generated from the model.
+      * ⚠️ \`document\` may be null (first event for this entity). Guard before accessing properties.
+      *
+      * CONSTRAINTS:
+      * - NEVER use \`as SomeType\` type assertions. Declare typed variables instead: \`const x: Type = value;\`
+      * - Only reference event.data fields listed in the "Event fields:" line below.
+      * - Do NOT modify anything outside this case block: imports, type parameters, canHandle, collectionName, and getDocumentId are auto-generated.
+      *
+          * Implement how this event updates the projection.
+          *
+          * **Internal State Pattern (extends, never replaces the imported type):**
+          * If you need to track state beyond the public WorkoutView type (e.g., to calculate
+          * aggregations, track previous values, etc.), you may EXTEND it with an interface (never replace it):
+          *
+          * 1. Define an extended interface BEFORE the projection:
+          *    interface InternalWorkoutView extends WorkoutView {
+          *      internalField: SomeType;
+          *    }
+          *
+          * 2. Assign document to extended type:
+          *    const current: InternalWorkoutView = document ?? { ...defaults };
+          *
+          * 3. Return via typed variable (preserves internal state for next event):
+          *    const result: InternalWorkoutView = { ...allFields, internalField };
+          *    return result;
+          *
+          * This keeps internal state separate from the public GraphQL schema.
+
+          * Event (ExerciseLogged) fields: workoutId: string, exercise: string
+      */
+              return {
+                ...document,
+                id: /* TODO: map from event.data */ '',
+                name: /* TODO: map from event.data */ '',
+                exercises: /* TODO: map from event.data */ [],
+              };
+            }
+            default:
+              return document;
+          }
+        },
+      });
+
+      export default projection;
+      "
+    `);
+  });
 });

package/src/codegen/templates/query/projection.ts.ejs

@@ -75,22 +75,45 @@ if (isSingleton) {
         index === 0 ? `\${event.data.${field}}` : `-\${event.data.${field}}`
     ).join('');
 %>`<%= template %>`<%
+} else if (eventIdFieldMap) {
+    const uniqueFields = [...new Set(eventIdFieldMap.values())];
+    if (uniqueFields.length === 1) {
+%>event.data.<%= uniqueFields[0] %><%
+    } else {
+%>{
+  switch (event.type) {
+<% for (const [eventType, field] of eventIdFieldMap) { %>
+    case '<%= eventType %>': return event.data.<%= field %>;
+<% } %>
+    default: return event.data.<%= typeof idField === 'string' ? idField : 'id' %>;
+  }
+}<%
+    }
 } else {
     const singleIdField = typeof idField === 'string' ? idField : 'id';
 %>event.data.<%= singleIdField %><%
 }
 %>,
 <%
-if (!isSingleton && !isCompositeKey && typeof idField === 'string') {
+const effectiveIdField = eventIdFieldMap
+  ? [...new Set(eventIdFieldMap.values())].length === 1 ? [...new Set(eventIdFieldMap.values())][0] : null
+  : typeof idField === 'string' ? idField : null;
+if (!isSingleton && !isCompositeKey && effectiveIdField) {
     const missing = events.filter(e => {
+        if (eventIdFieldMap) {
+            const mappedField = eventIdFieldMap.get(e.type);
+            if (!mappedField) return false;
+            const def = messages.find(m => m.name === e.type);
+            return def && !def.fields?.some(f => f.name === mappedField);
+        }
         const def = messages.find(m => m.name === e.type);
-        return def && !def.fields?.some(f => f.name === idField);
+        return def && !def.fields?.some(f => f.name === effectiveIdField);
     });
     if (missing.length > 0) {
 %>
-// WARNING: These events lack field '<%= idField %>': <%= missing.map(e => e.type).join(', ') %>
+// WARNING: These events lack field '<%= effectiveIdField %>': <%= missing.map(e => e.type).join(', ') %>
 // The projection cannot route these events to the correct document.
-// Fix: add '<%= idField %>' to these events in the model.
+// Fix: add '<%= effectiveIdField %>' to these events in the model.
 <%  }
 }
 -%>

package/src/codegen/templates/query/query.resolver.specs.ts

@@ -1250,4 +1250,246 @@ describe('query.resolver.ts.ejs', () => {
     expect(resolverFile?.contents).toContain("@Arg('limit', () => Float, { nullable: true }) _limit?: number");
     expect(resolverFile?.contents).not.toContain('ListWorkoutsFilterInput');
   });
+
+  it('should map query arg to state field via value matching when names differ', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'workout-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'create-workout',
+              stream: 'workouts-${id}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Create workout',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'success',
+                            steps: [
+                              { keyword: 'When', text: 'CreateWorkout', docString: { id: 'w1', name: 'Leg Day' } },
+                              { keyword: 'Then', text: 'WorkoutCreated', docString: { id: 'w1', name: 'Leg Day' } },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-workout',
+              request: `
+                query GetWorkout($workoutId: ID!) {
+                  workout(workoutId: $workoutId) {
+                    id
+                    name
+                  }
+                }
+              `,
+              stream: 'workouts',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'WorkoutView' },
+                      origin: { type: 'projection', name: 'WorkoutProjection', idField: 'id' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View workout',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'fetch workout by id',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'GetWorkout',
+                                docString: { workoutId: 'w1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'WorkoutView',
+                                docString: { id: 'w1', name: 'Leg Day' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateWorkout',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'WorkoutCreated',
+          source: 'internal',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'WorkoutView',
+          fields: [
+            { name: 'id', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const resolverFile = plans.find((p) => p.outputPath.endsWith('view-workout/query.resolver.ts'));
+
+    expect(resolverFile?.contents).toMatchInlineSnapshot(`
+      "import { Query, Resolver, Arg, Ctx, ObjectType, Field, ID } from 'type-graphql';
+      import { type GraphQLContext, ReadModel } from '../../../shared';
+
+      @ObjectType()
+      export class WorkoutView {
+        @Field(() => String)
+        id!: string;
+
+        @Field(() => String)
+        name!: string;
+
+        // IMPORTANT: Index signature required for ReadModel<T extends Record<string, unknown>> compatibility
+        [key: string]: unknown;
+      }
+
+      @Resolver()
+      export class ViewWorkoutQueryResolver {
+        @Query(() => [WorkoutView])
+        async workout(
+          @Ctx() ctx: GraphQLContext,
+          @Arg('workoutId', () => ID, { nullable: true }) workoutId?: string,
+        ): Promise<WorkoutView[]> {
+          const model = new ReadModel<WorkoutView>(ctx.database, 'WorkoutProjection');
+
+          // ReadModel API:
+          // - model.find(filterFn?)  → T[]       returns all matches (or all documents if no filter)
+          // - model.findOne(filterFn) → T | null  returns the first match
+          //
+          // The scaffolded code below uses find() returning an array.
+          // If this query should return a single item, switch to findOne().
+
+          return model.find((item) => {
+            if (workoutId !== undefined && item.id !== workoutId) return false;
+
+            return true;
+          });
+        }
+      }
+      "
+    `);
+  });
+
+  it('should generate operator-based filters from explicit mappings', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'rental-flow',
+          slices: [
+            {
+              type: 'query',
+              name: 'search-listings',
+              request: `
+                query SearchListings($minBedrooms: Int, $maxPrice: Float) {
+                  searchListings(minBedrooms: $minBedrooms, maxPrice: $maxPrice) {
+                    listingId
+                    numBedrooms
+                    pricePerNight
+                  }
+                }
+              `,
+              mappings: [
+                {
+                  source: { type: 'Query', name: 'SearchListings', field: 'minBedrooms' },
+                  target: { type: 'State', name: 'ListingResult', field: 'numBedrooms' },
+                  operator: 'gte',
+                },
+                {
+                  source: { type: 'Query', name: 'SearchListings', field: 'maxPrice' },
+                  target: { type: 'State', name: 'ListingResult', field: 'pricePerNight' },
+                  operator: 'lte',
+                },
+              ],
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      origin: {
+                        type: 'projection',
+                        idField: 'listingId',
+                        name: 'ListingsProjection',
+                      },
+                      target: {
+                        type: 'State',
+                        name: 'ListingResult',
+                      },
+                    },
+                  ],
+                },
+                specs: [],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'state',
+          name: 'ListingResult',
+          fields: [
+            { name: 'listingId', type: 'string', required: true },
+            { name: 'numBedrooms', type: 'number', required: true },
+            { name: 'pricePerNight', type: 'number', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const resolverFile = plans.find((p) => p.outputPath.endsWith('query.resolver.ts'));
+
+    expect(resolverFile?.contents).toContain('item.numBedrooms < minBedrooms');
+    expect(resolverFile?.contents).toContain('item.pricePerNight > maxPrice');
+  });
 });

package/src/codegen/templates/query/query.resolver.ts.ejs

@@ -37,9 +37,11 @@ for (const field of messageFields) {
 const hasArgs = parsedRequest?.args?.length > 0;
 
 const stateFieldNames = new Set(messageFields.map(f => f.name));
+const argFieldMap = argToStateFieldMap ?? {};
+const negatedOp = { eq: '!==', ne: '===', gt: '<=', gte: '<', lt: '>=', lte: '>' };
 const usedArgNames = isSingleton
   ? new Set()
-  : new Set((parsedRequest?.args ?? []).filter(a => stateFieldNames.has(a.name)).map(a => a.name));
+  : new Set((parsedRequest?.args ?? []).filter(a => stateFieldNames.has(a.name) || argFieldMap[a.name]).map(a => a.name));
 const hasMatchingArgs = usedArgNames.size > 0;
 
 const resolveArgTypes = (arg) => {
@@ -180,10 +182,12 @@ const model = new ReadModel<<%= viewType %>>(ctx.database, '<%= collectionName %
 
 return model.find((<%= hasMatchingArgs ? 'item' : '_item' %>) => {
 <% if (parsedRequest?.args?.length) {
-        const stateFieldNames = new Set(messageFields.map(f => f.name));
         for (const arg of parsedRequest.args) {
-            if (stateFieldNames.has(arg.name)) { %>
-    if (<%= arg.name %> !== undefined && item.<%= arg.name %> !== <%= arg.name %>) return false;
+            const mapping = argFieldMap[arg.name];
+            const mappedField = mapping ? mapping.field : (stateFieldNames.has(arg.name) ? arg.name : null);
+            const op = mapping ? negatedOp[mapping.operator] : '!==';
+            if (mappedField) { %>
+    if (<%= arg.name %> !== undefined && item.<%= mappedField %> <%= op %> <%= arg.name %>) return false;
 <%          } else { %>
     // NOTE: '<%= arg.name %>' has no matching field on the state type — add custom filter logic if needed.
 <%          }

package/src/commands/generate-server.ts

@@ -117,14 +117,14 @@ export type GenerateServerEvents =
 
 export const commandHandler = defineCommandHandler({
   name: 'GenerateServer',
-  displayName: 'Generate Server',
-  alias: 'generate:server',
+  displayName: 'Build Back End',
+  alias: 'build:backend',
   description: 'Generate server from model',
   category: 'generate',
   icon: 'server',
   events: [
-    { name: 'ServerGenerated', displayName: 'Server Generated' },
-    { name: 'ServerGenerationFailed', displayName: 'Server Generation Failed' },
+    { name: 'ServerGenerated', displayName: 'Back End Built' },
+    { name: 'ServerGenerationFailed', displayName: 'Back End Build Failed' },
     { name: 'SliceGenerated', displayName: 'Slice Generated' },
     { name: 'SliceGenerationFailed', displayName: 'Slice Generation Failed' },
   ],
@@ -138,7 +138,7 @@ export const commandHandler = defineCommandHandler({
       required: true,
     },
   },
-  examples: ['$ auto generate:server --destination=.'],
+  examples: ['$ auto build:backend --destination=.'],
   handle: async (command: Command): Promise<GenerateServerEvents | GenerateServerEvents[]> => {
     const typedCommand = command as GenerateServerCommand;
     const result = await handleGenerateServerCommandInternal(typedCommand);