@auto-engineer/server-generator-apollo-emmett 1.26.0 → 1.27.0

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

@@ -1566,27 +1566,30 @@ describe('projection.specs.ts.ejs', () => {
           switch (event.type) {
             case 'WorkoutRecorded': {
               /**
-               * ## IMPLEMENTATION INSTRUCTIONS ##
-               * Implement how this event updates the projection.
-               *
-               * **IMPORTANT - Internal State Pattern:**
-               * If you need to track state beyond the public WorkoutHistory type (e.g., to calculate
-               * aggregations, track previous values, etc.), follow this pattern:
-               *
-               * 1. Define an extended interface BEFORE the projection:
-               *    interface InternalWorkoutHistory extends WorkoutHistory {
-               *      internalField: SomeType;
-               *    }
-               *
-               * 2. Cast document parameter to extended type:
-               *    const current: InternalWorkoutHistory = document ?? { ...defaults };
-               *
-               * 3. Cast return values to extended type:
-               *    return { ...allFields, internalField } as InternalWorkoutHistory;
-               *
-               * This keeps internal state separate from the public GraphQL schema.
-               */
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+          * Implement how this event updates the projection.
+          *
+          * **IMPORTANT - Internal State Pattern:**
+          * If you need to track state beyond the public WorkoutHistory type (e.g., to calculate
+          * aggregations, track previous values, etc.), follow this pattern:
+          *
+          * 1. Define an extended interface BEFORE the projection:
+          *    interface InternalWorkoutHistory extends WorkoutHistory {
+          *      internalField: SomeType;
+          *    }
+          *
+          * 2. Cast document parameter to extended type:
+          *    const current: InternalWorkoutHistory = document ?? { ...defaults };
+          *
+          * 3. Cast return values to extended type:
+          *    return { ...allFields, internalField } as InternalWorkoutHistory;
+          *
+          * This keeps internal state separate from the public GraphQL schema.
+
+          * Event (WorkoutRecorded) fields: memberId: string, caloriesBurned: number
+      */
               return {
+                ...document,
                 memberId: /* TODO: map from event.data */ '',
                 totalCalories: /* TODO: map from event.data */ 0,
               };
@@ -1601,4 +1604,367 @@ describe('projection.specs.ts.ejs', () => {
       "
     `);
   });
+
+  it('should include ...document spread in non-removal evolve cases', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'item-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'manage-item',
+              stream: 'items-${itemId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Manage item command',
+                    rules: [
+                      {
+                        name: 'Should manage items',
+                        examples: [
+                          {
+                            name: 'Item created',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'CreateItem',
+                                docString: { itemId: 'item_1', name: 'Widget' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ItemCreated',
+                                docString: { itemId: 'item_1', name: 'Widget' },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'Item removed',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'RemoveItem',
+                                docString: { itemId: 'item_1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ItemRemoved',
+                                docString: {},
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-items',
+              stream: 'items',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'ItemView' },
+                      origin: { type: 'projection', name: 'ItemsProjection', idField: 'itemId' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View items query',
+                    rules: [
+                      {
+                        name: 'Should project items',
+                        examples: [
+                          {
+                            name: 'Item created shows in view',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'ItemCreated',
+                                docString: { itemId: 'item_1', name: 'Widget' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ItemView',
+                                docString: { itemId: 'item_1', name: 'Widget' },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'Item removed disappears from view',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'ItemCreated',
+                                docString: { itemId: 'item_1', name: 'Widget' },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'ItemRemoved',
+                                docString: {},
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'ItemView',
+                                docString: {},
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateItem',
+          fields: [
+            { name: 'itemId', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'RemoveItem',
+          fields: [{ name: 'itemId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'ItemCreated',
+          source: 'internal',
+          fields: [
+            { name: 'itemId', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ItemRemoved',
+          source: 'internal',
+          fields: [{ name: 'itemId', type: 'string', required: true }],
+        },
+        {
+          type: 'state',
+          name: 'ItemView',
+          fields: [
+            { name: 'itemId', type: 'string', required: true },
+            { name: 'name', type: 'string', required: true },
+          ],
+        },
+      ],
+    } as SpecsSchema;
+
+    const plans = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const projectionFile = plans.find((p) => p.outputPath.endsWith('view-items/projection.ts'));
+    expect(projectionFile?.contents).toBeDefined();
+
+    // Non-removal evolve case should spread existing document
+    expect(projectionFile?.contents).toContain('...document,');
+
+    // Removal event case should return null, not spread
+    expect(projectionFile?.contents).toContain('return null;');
+
+    // Should include event field-type hints in comments
+    expect(projectionFile?.contents).toContain('Event (ItemCreated) fields:');
+  });
+
+  it('should warn when events lack the idField used by getDocumentId', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'order-flow',
+          slices: [
+            {
+              type: 'command',
+              name: 'manage-order',
+              stream: 'orders-${orderId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Manage order',
+                    rules: [
+                      {
+                        name: 'Should manage orders',
+                        examples: [
+                          {
+                            name: 'Order placed',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'PlaceOrder',
+                                docString: { orderId: 'o1', total: 100 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'OrderPlaced',
+                                docString: { orderId: 'o1', total: 100 },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'Payment received',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'ReceivePayment',
+                                docString: { orderId: 'o1', amount: 100 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'PaymentReceived',
+                                docString: { amount: 100, paidAt: '2030-01-01' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+            {
+              type: 'query',
+              name: 'view-orders',
+              stream: 'orders',
+              client: { specs: [] },
+              server: {
+                description: '',
+                data: {
+                  items: [
+                    {
+                      target: { type: 'State', name: 'OrderView' },
+                      origin: { type: 'projection', name: 'OrdersProjection', idField: 'orderId' },
+                    },
+                  ],
+                },
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'View orders',
+                    rules: [
+                      {
+                        name: 'Should project orders',
+                        examples: [
+                          {
+                            name: 'Order placed shows in view',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'OrderPlaced',
+                                docString: { orderId: 'o1', total: 100 },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'OrderView',
+                                docString: { orderId: 'o1', total: 100, paid: false },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'Payment marks order as paid',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'OrderPlaced',
+                                docString: { orderId: 'o1', total: 100 },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'PaymentReceived',
+                                docString: { amount: 100, paidAt: '2030-01-01' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'OrderView',
+                                docString: { orderId: 'o1', total: 100, paid: true },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'PlaceOrder',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'total', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'ReceivePayment',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'amount', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'OrderPlaced',
+          source: 'internal',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'total', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'PaymentReceived',
+          source: 'internal',
+          fields: [
+            { name: 'amount', type: 'number', required: true },
+            { name: 'paidAt', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'OrderView',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'total', type: 'number', required: true },
+            { name: 'paid', type: 'boolean', required: true },
+          ],
+        },
+      ],
+    } as SpecsSchema;
+
+    const plans = await generateScaffoldFilePlans(spec.narratives, spec.messages, undefined, 'src/domain/flows');
+    const projectionFile = plans.find((p) => p.outputPath.endsWith('view-orders/projection.ts'));
+    expect(projectionFile?.contents).toBeDefined();
+
+    // PaymentReceived lacks 'orderId' field, so should have a warning
+    expect(projectionFile?.contents).toContain("WARNING: These events lack field 'orderId': PaymentReceived");
+  });
 });

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

@@ -238,27 +238,30 @@ describe('projection.ts.ejs', () => {
           switch (event.type) {
             case 'ListingCreated': {
               /**
-               * ## IMPLEMENTATION INSTRUCTIONS ##
-               * Implement how this event updates the projection.
-               *
-               * **IMPORTANT - Internal State Pattern:**
-               * If you need to track state beyond the public AvailableListings type (e.g., to calculate
-               * aggregations, track previous values, etc.), follow this pattern:
-               *
-               * 1. Define an extended interface BEFORE the projection:
-               *    interface InternalAvailableListings extends AvailableListings {
-               *      internalField: SomeType;
-               *    }
-               *
-               * 2. Cast document parameter to extended type:
-               *    const current: InternalAvailableListings = document ?? { ...defaults };
-               *
-               * 3. Cast return values to extended type:
-               *    return { ...allFields, internalField } as InternalAvailableListings;
-               *
-               * This keeps internal state separate from the public GraphQL schema.
-               */
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+          * Implement how this event updates the projection.
+          *
+          * **IMPORTANT - Internal State Pattern:**
+          * If you need to track state beyond the public AvailableListings type (e.g., to calculate
+          * aggregations, track previous values, etc.), follow this pattern:
+          *
+          * 1. Define an extended interface BEFORE the projection:
+          *    interface InternalAvailableListings extends AvailableListings {
+          *      internalField: SomeType;
+          *    }
+          *
+          * 2. Cast document parameter to extended type:
+          *    const current: InternalAvailableListings = document ?? { ...defaults };
+          *
+          * 3. Cast return values to extended type:
+          *    return { ...allFields, internalField } as InternalAvailableListings;
+          *
+          * This keeps internal state separate from the public GraphQL schema.
+
+          * Event (ListingCreated) fields: propertyId: string, title: string, pricePerNight: number, location: string, maxGuests: number
+      */
               return {
+                ...document,
                 propertyId: /* TODO: map from event.data */ '',
                 title: /* TODO: map from event.data */ '',
                 pricePerNight: /* TODO: map from event.data */ 0,
@@ -269,13 +272,15 @@ describe('projection.ts.ejs', () => {
 
             case 'ListingRemoved': {
               /**
-               * ## IMPLEMENTATION INSTRUCTIONS ##
-               * This event might indicate removal of a AvailableListings.
-               *
-               * - If the intent is to **remove the document**, return \`null\`.
-               * - If the intent is to **soft delete**, consider adding a \`status\` field (e.g., \`status: 'removed'\`).
-               * - Ensure consumers of this projection (e.g., UI) handle the chosen approach appropriately.
-               */
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+          * This event might indicate removal of a AvailableListings.
+          *
+          * - If the intent is to **remove the document**, return \`null\`.
+          * - If the intent is to **soft delete**, consider adding a \`status\` field (e.g., \`status: 'removed'\`).
+          * - Ensure consumers of this projection (e.g., UI) handle the chosen approach appropriately.
+
+          * Event (ListingRemoved) fields: propertyId: string
+      */
               return null;
             }
             default:
@@ -565,35 +570,38 @@ describe('projection.ts.ejs', () => {
           switch (event.type) {
             case 'TodoAdded': {
               /**
-               * ## IMPLEMENTATION INSTRUCTIONS ##
-               * **SINGLETON AGGREGATION PATTERN**
-               *
-               * This projection maintains ONE document aggregating data from MANY entities.
-               *
-               * CRITICAL: Use internal state to track individual entity information:
-               *
-               * 1. Access current state:
-               *    const current: InternalTodoSummary = document ?? { ...initialState, _entities: {} };
-               *
-               * 2. Track entity changes:
-               *    // a) Extract the unique identifier that distinguishes this entity
-               *    //    Examine event.data to find the ID field (often 'id' or '<entity>Id')
-               *    const entityId = event.data.[ENTITY_ID_FIELD];
-               *
-               *    // b) Store/update entity state with relevant properties from event.data
-               *    //    Include only fields needed for aggregation calculations
-               *    current._entities[entityId] = { [field]: value, ... };
-               *
-               * 3. Calculate aggregates from entity states:
-               *    const counts = Object.values(current._entities).reduce((acc, entity) => {
-               *      acc[entity.status] = (acc[entity.status] || 0) + 1;
-               *      return acc;
-               *    }, {});
-               *
-               * 4. Return with internal state:
-               *    return { ...publicFields, _entities: current._entities } as InternalTodoSummary;
-               */
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+          * **SINGLETON AGGREGATION PATTERN**
+          *
+          * This projection maintains ONE document aggregating data from MANY entities.
+          *
+          * CRITICAL: Use internal state to track individual entity information:
+          *
+          * 1. Access current state:
+          *    const current: InternalTodoSummary = document ?? { ...initialState, _entities: {} };
+          *
+          * 2. Track entity changes:
+          *    // a) Extract the unique identifier that distinguishes this entity
+          *    //    Examine event.data to find the ID field (often 'id' or '<entity>Id')
+          *    const entityId = event.data.[ENTITY_ID_FIELD];
+          *
+          *    // b) Store/update entity state with relevant properties from event.data
+          *    //    Include only fields needed for aggregation calculations
+          *    current._entities[entityId] = { [field]: value, ... };
+          *
+          * 3. Calculate aggregates from entity states:
+          *    const counts = Object.values(current._entities).reduce((acc, entity) => {
+          *      acc[entity.status] = (acc[entity.status] || 0) + 1;
+          *      return acc;
+          *    }, {});
+          *
+          * 4. Return with internal state:
+          *    return { ...publicFields, _entities: current._entities } as InternalTodoSummary;
+
+          * Event (TodoAdded) fields: todoId: string, title: string
+      */
               return {
+                ...document,
                 totalCount: /* TODO: map from event.data */ 0,
               };
             }
@@ -784,27 +792,30 @@ describe('projection.ts.ejs', () => {
           switch (event.type) {
             case 'UserJoinedProject': {
               /**
-               * ## IMPLEMENTATION INSTRUCTIONS ##
-               * **COMPOSITE KEY PROJECTION**
-               *
-               * This projection uses a composite key: userId + projectId
-               * Document ID format: \`\${event.data.userId}-\${event.data.projectId}\`
-               *
-               * CRITICAL: You MUST include ALL key fields in every return statement:
-               * - userId: event.data.userId
-               * - projectId: event.data.projectId
-               *
-               * Missing even one key field will cause the projection to fail.
-               * Key fields typically map directly from event data (no transformation needed).
-               *
-               * Example implementation:
-               *    return {
-               *      userId: event.data.userId,
-               *      projectId: event.data.projectId,
-               *      // ... other fields
-               *    };
-               */
+      * ## IMPLEMENTATION INSTRUCTIONS ##
+          * **COMPOSITE KEY PROJECTION**
+          *
+          * This projection uses a composite key: userId + projectId
+          * Document ID format: \`\${event.data.userId}-\${event.data.projectId}\`
+          *
+          * CRITICAL: You MUST include ALL key fields in every return statement:
+          * - userId: event.data.userId
+          * - projectId: event.data.projectId
+          *
+          * Missing even one key field will cause the projection to fail.
+          * Key fields typically map directly from event data (no transformation needed).
+          *
+          * Example implementation:
+          *    return {
+          *      userId: event.data.userId,
+          *      projectId: event.data.projectId,
+          *      // ... other fields
+          *    };
+
+          * Event (UserJoinedProject) fields: userId: string, projectId: string, role: string
+      */
               return {
+                ...document,
                 userId: /* TODO: map from event.data */ '',
                 projectId: /* TODO: map from event.data */ '',
                 role: /* TODO: map from event.data */ '',

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

@@ -70,6 +70,20 @@ if (isSingleton) {
 %>event.data.<%= singleIdField %><%
 }
 %>,
+<%
+if (!isSingleton && !isCompositeKey && typeof idField === 'string') {
+    const missing = events.filter(e => {
+        const def = messages.find(m => m.name === e.type);
+        return def && !def.fields?.some(f => f.name === idField);
+    });
+    if (missing.length > 0) {
+%>
+// WARNING: These events lack field '<%= idField %>': <%= 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.
+<%  }
+}
+-%>
 evolve: (
 document: <%= pascalCase(slice.server?.data?.items?.[0]?.target?.name || 'UnknownState') %> | null,
 event: ReadEvent<AllEvents, InMemoryReadEventMetadata>
@@ -176,6 +190,10 @@ case '<%= event.type %>': {
     *
     * This keeps internal state separate from the public GraphQL schema.
 <% } -%>
+<% const evtDef = messages.find(m => m.name === event.type); -%>
+<% if (evtDef?.fields?.length) { %>
+    * Event (<%= event.type %>) fields: <%= evtDef.fields.map(f => f.name + ': ' + (f.tsType || f.type)).join(', ') %>
+<% } -%>
 */
 <% if (isRemovalEvent) { -%>
     return null;
@@ -184,6 +202,7 @@ case '<%= event.type %>': {
     return null;
 <% } else { -%>
     return {
+        ...document,
     <% for (let i = 0; i < usedFields.length; i++) {
         const field = usedFields[i];
         const isLast = i === usedFields.length - 1;