@auto-engineer/server-generator-apollo-emmett 0.1.1

package/src/codegen/templates/command/decide.specs.ts

@@ -0,0 +1,542 @@
+import { describe, it, expect } from 'vitest';
+import { SpecsSchemaType as SpecsSchema } from '@auto-engineer/flow';
+import { generateScaffoldFilePlans } from '../../scaffoldFromSchema';
+
+describe('decide.ts.ejs', () => {
+  it('should generate a valid decide file when both command and event exist', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host creates a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create listing',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: 'Some apartment',
+                        listedAt: '2024-01-15T10:00:00Z',
+                        rating: 4.8,
+                        metadata: { foo: 'bar' },
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                          rating: 4.8,
+                          metadata: { foo: 'bar' },
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateListing',
+          fields: [],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const decideFile = plans.find((p) => p.outputPath.endsWith('decide.ts'));
+
+    expect(decideFile?.contents).toMatchInlineSnapshot(`
+      "import { IllegalStateError } from '@event-driven-io/emmett';
+      import type { State } from './state';
+      import type { CreateListing } from './commands';
+      import type { ListingCreated } from './events';
+
+      export const decide = (command: CreateListing, state: State): ListingCreated => {
+        switch (command.type) {
+          case 'CreateListing': {
+            /**
+             * ## IMPLEMENTATION INSTRUCTIONS ##
+             *
+             * This command can directly emit one or more events based on the input.
+             *
+             * You should:
+             * - Validate the command input fields
+             * - Inspect the current domain \`state\` to determine if the command is allowed
+             * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
+             * - If valid, return one or more events with the correct structure
+             *
+             * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
+             */
+
+            // return {
+            //   type: 'ListingCreated',
+            //   data: { ...command.data },
+            // } as ListingCreated;
+
+            throw new IllegalStateError('Not yet implemented: ' + command.type);
+          }
+          default:
+            throw new IllegalStateError('Unexpected command type: ' + command.type);
+        }
+      };
+      "
+    `);
+  });
+
+  it('should include implementation instructions when prior events are required', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host removes a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Remove listing',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    given: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                        },
+                      },
+                    ],
+                    when: {
+                      commandRef: 'RemoveListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingRemoved',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          removedAt: '2024-01-16T12:00:00Z',
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'RemoveListing',
+          fields: [{ name: 'propertyId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ListingRemoved',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'removedAt', type: 'Date', required: true },
+          ],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const decideFile = plans.find((p) => p.outputPath.endsWith('decide.ts'));
+
+    expect(decideFile?.contents).toMatchInlineSnapshot(`
+      "import { IllegalStateError } from '@event-driven-io/emmett';
+      import type { State } from './state';
+      import type { RemoveListing } from './commands';
+      import type { ListingRemoved } from './events';
+
+      export const decide = (command: RemoveListing, state: State): ListingRemoved => {
+        switch (command.type) {
+          case 'RemoveListing': {
+            /**
+             * ## IMPLEMENTATION INSTRUCTIONS ##
+             *
+             * This command requires evaluating prior state to determine if it can proceed.
+             *
+             * You should:
+             * - Validate the command input fields
+             * - Inspect the current domain \`state\` to determine if the command is allowed
+             * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
+             * - If valid, return one or more events with the correct structure
+             *
+             * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
+             */
+
+            // return {
+            //   type: 'ListingRemoved',
+            //   data: { ...command.data },
+            // } as ListingRemoved;
+
+            throw new IllegalStateError('Not yet implemented: ' + command.type);
+          }
+          default:
+            throw new IllegalStateError('Unexpected command type: ' + command.type);
+        }
+      };
+      "
+    `);
+  });
+
+  it('should generate a decide file that handles multiple GWTs including an error', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Host creates a listing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create listing',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: 'test',
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: 'Some Apartment',
+                        listedAt: '2024-01-15T10:00:00Z',
+                        rating: 4.8,
+                        metadata: { foo: 'bar' },
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ListingCreated',
+                        exampleData: {
+                          propertyId: 'listing_123',
+                          listedAt: '2024-01-15T10:00:00Z',
+                          rating: 4.8,
+                          metadata: { foo: 'bar' },
+                        },
+                      },
+                    ],
+                  },
+                  {
+                    when: {
+                      commandRef: 'CreateListing',
+                      exampleData: {
+                        propertyId: 'listing_123',
+                        title: '',
+                        listedAt: '2024-01-15T10:00:00Z',
+                        rating: 4.8,
+                        metadata: {},
+                      },
+                    },
+                    then: [
+                      {
+                        errorType: 'ValidationError',
+                        message: 'Title must not be empty',
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateListing',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ListingCreated',
+          source: 'internal',
+          fields: [
+            { name: 'propertyId', type: 'string', required: true },
+            { name: 'listedAt', type: 'Date', required: true },
+            { name: 'rating', type: 'number', required: true },
+            { name: 'metadata', type: 'object', required: true },
+          ],
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, undefined, 'src/domain/flows');
+    const decideFile = plans.find((p) => p.outputPath.endsWith('decide.ts'));
+
+    expect(decideFile?.contents).toMatchInlineSnapshot(`
+      "import { IllegalStateError, ValidationError } from '@event-driven-io/emmett';
+      import type { State } from './state';
+      import type { CreateListing } from './commands';
+      import type { ListingCreated } from './events';
+
+      export const decide = (command: CreateListing, state: State): ListingCreated => {
+        switch (command.type) {
+          case 'CreateListing': {
+            /**
+             * ## IMPLEMENTATION INSTRUCTIONS ##
+             *
+             * This command can directly emit one or more events based on the input.
+             *
+             * You should:
+             * - Validate the command input fields
+             * - Inspect the current domain \`state\` to determine if the command is allowed
+             * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
+             * - If valid, return one or more events with the correct structure
+             *
+             * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
+             */
+
+            if (command.data.title === '') {
+              throw new ValidationError('Title must not be empty');
+            }
+
+            // return {
+            //   type: 'ListingCreated',
+            //   data: { ...command.data },
+            // } as ListingCreated;
+
+            throw new IllegalStateError('Not yet implemented: ' + command.type);
+          }
+          default:
+            throw new IllegalStateError('Unexpected command type: ' + command.type);
+        }
+      };
+      "
+    `);
+  });
+
+  it('should include integration return type and usage in decide function', async () => {
+    const spec: SpecsSchema = {
+      variant: 'specs',
+      flows: [
+        {
+          name: 'Assistant suggests items',
+          slices: [
+            {
+              type: 'command',
+              name: 'Suggest Items',
+              stream: 'session-${sessionId}',
+              client: {
+                description: 'test',
+                specs: [],
+              },
+              server: {
+                description: '',
+                data: [
+                  {
+                    target: {
+                      type: 'Command',
+                      name: 'SuggestItems',
+                    },
+                    destination: {
+                      type: 'integration',
+                      systems: ['AI'],
+                      message: {
+                        name: 'DoChat',
+                        type: 'command',
+                      },
+                    },
+                    _additionalInstructions: 'Ensure systemPrompt includes product catalogue guidance',
+                    _withState: {
+                      target: {
+                        type: 'State',
+                        name: 'Products',
+                      },
+                      origin: {
+                        type: 'integration',
+                        systems: ['product-catalog'],
+                      },
+                    },
+                  },
+                  {
+                    target: {
+                      type: 'Event',
+                      name: 'ItemsSuggested',
+                    },
+                    destination: {
+                      type: 'stream',
+                      pattern: 'session-${sessionId}',
+                    },
+                  },
+                ],
+                gwt: [
+                  {
+                    when: {
+                      commandRef: 'SuggestItems',
+                      exampleData: {
+                        sessionId: 'session-123',
+                        prompt: 'What should I buy?',
+                      },
+                    },
+                    then: [
+                      {
+                        eventRef: 'ItemsSuggested',
+                        exampleData: {
+                          sessionId: 'session-123',
+                          items: [],
+                        },
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'SuggestItems',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'prompt', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'DoChat',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'prompt', type: 'string', required: true },
+            { name: 'systemPrompt', type: 'string', required: false },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'ItemsSuggested',
+          source: 'internal',
+          fields: [
+            { name: 'sessionId', type: 'string', required: true },
+            { name: 'items', type: 'Array<object>', required: true },
+          ],
+        },
+        {
+          type: 'state',
+          name: 'Products',
+          fields: [
+            {
+              name: 'products',
+              type: 'Array<{ id: string, name: string }>',
+              required: true,
+            },
+          ],
+        },
+      ],
+      integrations: [
+        {
+          name: 'AI',
+          source: '@auto-engineer/ai-integration',
+          description: '',
+        },
+        {
+          name: 'product-catalog',
+          source: '@auto-engineer/product-catalogue-integration',
+          description: '',
+        },
+      ],
+    };
+
+    const plans = await generateScaffoldFilePlans(spec.flows, spec.messages, spec.integrations);
+    const decideFile = plans.find((p) => p.outputPath.endsWith('decide.ts'));
+
+    expect(decideFile?.contents).toMatchInlineSnapshot(`
+      "import { IllegalStateError } from '@event-driven-io/emmett';
+      import type { State } from './state';
+      import type { SuggestItems } from './commands';
+      import type { ItemsSuggested } from './events';
+      import type { Products } from '@auto-engineer/product-catalogue-integration';
+
+      export const decide = (command: SuggestItems, state: State, products?: Products): ItemsSuggested => {
+        switch (command.type) {
+          case 'SuggestItems': {
+            /**
+             * ## IMPLEMENTATION INSTRUCTIONS ##
+             *
+             * This command can directly emit one or more events based on the input.
+             *
+             * You should:
+             * - Validate the command input fields
+             * - Inspect the current domain \`state\` to determine if the command is allowed
+             * - Use \`products\` (integration result) to enrich or filter the output
+             * - If invalid, throw one of the following domain errors: \`NotFoundError\`, \`ValidationError\`, or \`IllegalStateError\`
+             * - If valid, return one or more events with the correct structure
+             *
+             * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
+             *
+             * Integration result shape (Products):
+             * products?.data = {
+             *   products: Array<{
+             *     id: string;
+             *     name: string };
+             *   }>;
+             * }
+             */
+
+            // return {
+            //   type: 'ItemsSuggested',
+            //   data: { ...command.data },
+            // } as ItemsSuggested;
+
+            throw new IllegalStateError('Not yet implemented: ' + command.type);
+          }
+          default:
+            throw new IllegalStateError('Unexpected command type: ' + command.type);
+        }
+      };
+      "
+    `);
+  });
+});

package/src/codegen/templates/command/decide.specs.ts.ejs

@@ -0,0 +1,51 @@
+import { describe, it } from 'vitest';
+import { DeciderSpecification } from '@event-driven-io/emmett';
+import { decide } from './decide';
+import { evolve } from './evolve';
+import { initialState } from './state';
+
+describe('<%= flowName %> | <%= sliceName %>', () => {
+const given = DeciderSpecification.for({
+decide,
+evolve,
+initialState,
+});
+
+<% for (const commandName in gwtMapping) {
+    const cases = gwtMapping[commandName];
+    const schema = commandSchemasByName[commandName];
+        for (const [i, gwt] of cases.entries()) {
+    const example = gwt.when;
+    const eventResults = gwt.then.filter(t => 'eventRef' in t);
+    const errorResult = gwt.then.find(t => 'errorType' in t);
+    const testName = errorResult
+            ? `should throw ${errorResult.errorType} when ${gwt.failingFields?.join(', ') || 'invalid input'}`
+            : `should emit ${eventResults.map(e => e.eventRef).join(', ')} for valid ${commandName}`;
+%>
+it('<%- testName %>', () => {
+given([
+<%_ if (gwt.given && gwt.given.length) { _%>
+    <%- gwt.given.map(g => `{
+        type: '${g.eventRef}',
+        data: ${formatDataObject(g.exampleData, events.find(e => e.type === g.eventRef))}
+      }`).join(',\n      ') %>
+<%_ } _%>
+])
+.when({
+type: '<%= example.commandRef %>',
+data: <%- formatDataObject(example.exampleData, schema) %>,
+metadata: { now: new Date() }
+})
+<% if (errorResult) { %>
+    .thenThrows((err) => err instanceof <%= errorResult.errorType %> && err.message === '<%= errorResult.message || '' %>');
+<% } else { %>
+    .then([
+    <%- eventResults.map(e => `{
+        type: '${e.eventRef}',
+        data: ${formatDataObject(e.exampleData, events.find(evt => evt.type === e.eventRef))}
+      }`).join(',\n      ') %>
+    ]);
+<% } %>
+});
+<% }} %>
+});

package/src/codegen/templates/command/decide.ts.ejs

@@ -0,0 +1,107 @@
+import {
+IllegalStateError<% if (usedErrors.includes('ValidationError')) { %>, ValidationError<% } %><% if (usedErrors.includes('NotFoundError')) { %>, NotFoundError<% } %>
+} from '@event-driven-io/emmett';
+import type { State } from './state';
+import type { <%= Object.keys(gwtMapping).map(pascalCase).join(', ') %> } from './commands';
+<%
+const fallbackEvents = Object.values(gwtMapping).flatMap(scenarios =>
+        scenarios.flatMap(s => s.then?.filter(t => 'eventRef' in t) || [])
+);
+const uniqueEventTypes = [...new Set(fallbackEvents.map(e => pascalCase(e.eventRef)))];
+
+const integrationData = (slice.server?.data ?? []).filter(d => d.destination?.type === 'integration');
+const integration = integrationData[0];
+const integrationReturnType = integration?._withState?.target?.name;
+const integrationReturnSystem = integration?._withState?.origin?.systems?.[0];
+const integrationReturnImportSource = integrations?.find(i => i.name === integrationReturnSystem)?.source;
+const integrationReturnFields = messages?.find(m => m.name === integrationReturnType && m.type === 'state')?.fields ?? [];
+
+function formatFieldDocLine(field) {
+    const optional = field.required ? '' : '?';
+    const name = `${field.name}${optional}`;
+    const type = field.type;
+
+    if (type.startsWith('Array<{') && type.endsWith('}>')) {
+        const inner = type.slice(7, -1);
+        const entries = inner
+                .split(',')
+                .map(s => s.trim())
+                .map(pair => {
+                    const [k, v] = pair.split(':').map(p => p.trim());
+                    return `*     ${k}: ${v};`;
+                });
+        return [`*   ${name}: Array<{`, ...entries, `*   }>;`];
+    }
+
+    return [`*   ${name}: ${type};`];
+}
+-%>
+<% if (uniqueEventTypes.length > 0) { -%>
+    import type { <%= uniqueEventTypes.join(', ') %> } from './events';
+<% } -%>
+<% if (integrationReturnType && integrationReturnImportSource) { -%>
+    import type { <%= integrationReturnType %> } from '<%= integrationReturnImportSource %>';
+<% } -%>
+
+export const decide = (
+command: <%= Object.keys(gwtMapping).map(pascalCase).join(' | ') %>,
+state: State<%= integrationReturnType ? `,\n  ${camelCase(integrationReturnType)}?: ${integrationReturnType}` : '' %>
+): <%= uniqueEventTypes.length === 0
+        ? 'never'
+        : uniqueEventTypes.length === 1
+                ? uniqueEventTypes[0]
+                : `(${uniqueEventTypes.join(' | ')}) | (${uniqueEventTypes.join(' | ')})[]` %> => {
+switch (command.type) {
+<% for (const command of Object.keys(gwtMapping)) {
+    const scenarios = gwtMapping?.[command] ?? [];
+    const hasGivenEvents = scenarios.some(s => s.given?.length > 0);
+    const fallbackEvents = scenarios.flatMap(s => s.then.filter(t => 'eventRef' in t));
+    const fallbackEventTypes = [...new Set(fallbackEvents.map(e => e.eventRef))];
+-%>
+case '<%= command %>': {
+/**
+* ## IMPLEMENTATION INSTRUCTIONS ##
+*
+* This command <%= hasGivenEvents ? 'requires evaluating prior state to determine if it can proceed' : 'can directly emit one or more events based on the input' %>.
+*
+* You should:
+* - Validate the command input fields
+* - Inspect the current domain `state` to determine if the command is allowed
+<% if (integrationReturnType) { -%>
+    * - Use `<%= camelCase(integrationReturnType) %>` (integration result) to enrich or filter the output
+<% } -%>
+* - If invalid, throw one of the following domain errors: `NotFoundError`, `ValidationError`, or `IllegalStateError`
+* - If valid, return one or more events with the correct structure
+*
+* ⚠️ Only read from inputs — never mutate them. `evolve.ts` handles state updates.
+<% if (integrationReturnFields.length > 0) { -%>
+    *
+    * Integration result shape (<%= integrationReturnType %>):
+    * <%= camelCase(integrationReturnType) %>?.data = {
+    <%= integrationReturnFields.flatMap(formatFieldDocLine).join('\n') %>
+    * }
+<% } -%>
+*/
+
+<% for (const gwt of scenarios) {
+    const error = gwt.then.find(t => 'errorType' in t);
+if (error && gwt.failingFields?.length) {
+    const condition = gwt.failingFields.map(field => `command.data.${field} === ''`).join(' || ');
+-%>
+if (<%- condition %>) {
+throw new <%= error.errorType %>('<%- error.message ?? 'Validation failed' %>');
+}
+<% } } -%>
+
+// return {
+//   type: '<%= fallbackEventTypes[0] ?? 'TODO_EVENT_TYPE' %>',
+//   data: { ...command.data },
+// } as <%= fallbackEventTypes[0] ? pascalCase(fallbackEventTypes[0]) : 'TODO_EVENT_TYPE' %>;
+
+throw new IllegalStateError('Not yet implemented: ' + command.type);
+}
+<% } -%>
+default:
+throw new IllegalStateError('Unexpected command type: ' + command.type);
+}
+};