@auto-engineer/server-generator-apollo-emmett 1.130.0 → 1.134.0

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

@@ -0,0 +1,112 @@
+import type { Model } from '@auto-engineer/narrative';
+import { describe, expect, it } from 'vitest';
+import { generateScaffoldFilePlans } from '../../scaffoldFromSchema';
+
+describe('query events.ts.ejs', () => {
+  it('generates events.ts for orphan events not produced by any command slice', async () => {
+    const spec: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'appointment-flow',
+          slices: [
+            {
+              type: 'query',
+              name: 'view-appointments',
+              stream: 'appointments',
+              client: { specs: [] },
+              server: {
+                description: 'projection for booked appointments',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'Appointment' },
+                      origin: {
+                        type: 'projection',
+                        name: 'AppointmentsProjection',
+                        idField: 'appointmentId',
+                      },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View appointments query',
+                    rules: [
+                      {
+                        name: 'Should project appointments',
+                        examples: [
+                          {
+                            name: 'Appointment booked shows in list',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'AppointmentBooked',
+                                docString: {
+                                  appointmentId: 'appt_1',
+                                  date: '2024-06-15',
+                                },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'Appointment',
+                                docString: {
+                                  appointmentId: 'appt_1',
+                                  date: '2024-06-15',
+                                },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'event',
+          name: 'AppointmentBooked',
+          source: 'internal',
+          fields: [
+            { name: 'appointmentId', type: 'string', required: true },
+            { name: 'date', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'Appointment',
+          fields: [
+            { name: 'appointmentId', type: 'string', required: true },
+            { name: 'date', type: 'string', required: true },
+          ],
+        },
+      ],
+    };
+
+    const { plans } = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+
+    const eventFile = plans.find((p) => p.outputPath.endsWith('view-appointments/events.ts'));
+    expect(eventFile).toBeDefined();
+    expect(eventFile?.contents).toMatchInlineSnapshot(`
+"import type { Event } from '@event-driven-io/emmett';
+
+export type AppointmentBooked = Event<
+  'AppointmentBooked',
+  {
+    appointmentId: string;
+    date: string;
+  }
+>;
+"
+    `);
+
+    const projectionFile = plans.find((p) => p.outputPath.endsWith('view-appointments/projection.ts'));
+    expect(projectionFile?.contents).toContain("import type { AppointmentBooked } from './events'");
+  });
+});

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

@@ -0,0 +1,17 @@
+<%
+const enumList = collectEnumNames(localEvents.flatMap(e => e.fields));
+%><% if (localEvents.length) { -%>
+import type { Event } from '@event-driven-io/emmett';
+<% if (enumList.length > 0) { %>import { <%= enumList.join(', ') %> } from '../../../shared';
+<% } %>
+<% for (const event of localEvents) { -%>
+export type <%= pascalCase(event.type) %> = Event<
+  '<%= event.type %>',
+  {
+  <% for (const field of event.fields) { -%>
+    <%- field.name %>: <%- toTsFieldType(field.tsType) %>;
+  <% } -%>
+  }
+>;
+<% } -%>
+<% } -%>

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.
 <%  }
 }
 -%>