@auto-engineer/server-generator-apollo-emmett 0.11.8 → 0.11.10

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

@@ -95,57 +95,57 @@ describe('spec.ts.ejs', () => {
     const specFile = plans.find((p) => p.outputPath.endsWith('specs.ts'));
 
     expect(specFile?.contents).toMatchInlineSnapshot(`
-          "import { describe, it } from 'vitest';
-          import { DeciderSpecification } from '@event-driven-io/emmett';
-          import { decide } from './decide';
-          import { evolve } from './evolve';
-          import { initialState, State } from './state';
-          import type { ListingCreated } from './events';
-          import type { CreateListing } from './commands';
+      "import { describe, it } from 'vitest';
+      import { DeciderSpecification } from '@event-driven-io/emmett';
+      import { decide } from './decide';
+      import { evolve } from './evolve';
+      import { initialState, State } from './state';
+      import type { ListingCreated } from './events';
+      import type { CreateListing } from './commands';
 
-          describe('Should create listing successfully', () => {
-            type Events = ListingCreated;
+      describe('Should create listing successfully', () => {
+        type Events = ListingCreated;
 
-            const given = DeciderSpecification.for<CreateListing, Events, State>({
-              decide,
-              evolve,
-              initialState,
-            });
+        const given = DeciderSpecification.for<CreateListing, Events, State>({
+          decide,
+          evolve,
+          initialState,
+        });
 
-            it('User creates listing with valid data', () => {
-              given([])
-                .when({
-                  type: 'CreateListing',
-                  data: {
-                    propertyId: 'listing_123',
-                    title: 'blah',
-                    pricePerNight: 250,
-                    maxGuests: 4,
-                    amenities: ['wifi', 'kitchen'],
-                    available: true,
-                    tags: ['some tag'],
-                    rating: 4.8,
-                    metadata: { foo: 'bar' },
-                    listedAt: new Date('2024-01-15T10:00:00Z'),
-                  },
-                  metadata: { now: new Date() },
-                })
+        it('User creates listing with valid data', () => {
+          given([])
+            .when({
+              type: 'CreateListing',
+              data: {
+                propertyId: 'listing_123',
+                title: 'blah',
+                pricePerNight: 250,
+                maxGuests: 4,
+                amenities: ['wifi', 'kitchen'],
+                available: true,
+                tags: ['some tag'],
+                rating: 4.8,
+                metadata: { foo: 'bar' },
+                listedAt: new Date('2024-01-15T10:00:00Z'),
+              },
+              metadata: { now: new Date() },
+            })
 
-                .then([
-                  {
-                    type: 'ListingCreated',
-                    data: {
-                      propertyId: 'listing_123',
-                      listedAt: new Date('2024-01-15T10:00:00Z'),
-                      rating: 4.8,
-                      metadata: { foo: 'bar' },
-                    },
-                  },
-                ]);
-            });
-          });
-          "
-        `);
+            .then([
+              {
+                type: 'ListingCreated',
+                data: {
+                  propertyId: 'listing_123',
+                  listedAt: new Date('2024-01-15T10:00:00Z'),
+                  rating: 4.8,
+                  metadata: { foo: 'bar' },
+                },
+              },
+            ]);
+        });
+      });
+      "
+    `);
   });
   it('should include given events in the spec file when provided', async () => {
     const spec: SpecsSchema = {

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

@@ -93,6 +93,7 @@ describe('decide.ts.ejs', () => {
              * - 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\`
+             *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
              * - If valid, return one or more events with the correct structure
              *
              * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
@@ -218,6 +219,7 @@ describe('decide.ts.ejs', () => {
              * - 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\`
+             *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
              * - If valid, return one or more events with the correct structure
              *
              * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
@@ -358,6 +360,7 @@ describe('decide.ts.ejs', () => {
              * - 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\`
+             *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
              * - If valid, return one or more events with the correct structure
              *
              * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.
@@ -545,6 +548,7 @@ describe('decide.ts.ejs', () => {
              * - 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\`
+             *   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
              * - If valid, return one or more events with the correct structure
              *
              * ⚠️ Only read from inputs — never mutate them. \`evolve.ts\` handles state updates.

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

@@ -71,6 +71,7 @@ case '<%= command %>': {
     * - Use `<%= camelCase(integrationReturnType) %>` (integration result) to enrich or filter the output
 <% } -%>
 * - If invalid, throw one of the following domain errors: `NotFoundError`, `ValidationError`, or `IllegalStateError`
+*   ⚠️ Error constructors: NotFoundError takes { id, type, message? }, while IllegalStateError/ValidationError take string
 * - If valid, return one or more events with the correct structure
 *
 * ⚠️ Only read from inputs — never mutate them. `evolve.ts` handles state updates.

package/dist/src/codegen/templates/command/events.ts.ejs

@@ -1,14 +1,17 @@
-<% if (localEvents.length) { -%>
-    import type { Event } from '@event-driven-io/emmett';
-
-    <% for (const event of localEvents) { -%>
-        export type <%= pascalCase(event.type) %> = Event<
-        '<%= event.type %>',
-        {
-        <% for (const field of event.fields) { -%>
-            <%- field.name %>: <%- field.tsType %>;
-        <% } -%>
-        }
-        >;
-    <% } -%>
+<%
+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/dist/src/codegen/templates/command/mutation.resolver.specs.ts

@@ -323,6 +323,7 @@ describe('mutation.resolver.ts.ejs', () => {
 
     expect(mutationFile?.contents).toMatchInlineSnapshot(`
 "import { Mutation, Resolver, Arg, Ctx, Field, InputType } from 'type-graphql';
+import { GraphQLJSON } from 'graphql-type-json';
 import { type GraphQLContext, sendCommand, MutationResponse } from '../../../shared';
 
 @InputType()

package/dist/src/codegen/templates/command/mutation.resolver.ts.ejs

@@ -1,29 +1,8 @@
 <%
-function isInlineObject(ts) {
-    return /^\{[\s\S]*\}$/.test((ts ?? '').trim());
-}
-function isInlineObjectArray(ts) {
-    const t = (ts ?? '').trim();
-    return /^Array<\{[\s\S]*\}>$/.test(t) || /^\{[\s\S]*\}\[\]$/.test(t);
-}
-function baseTs(ts) {
-    return (ts ?? 'string').replace(/\s*\|\s*null\b/g, '').trim();
-}
-function fieldUsesDate(ts) {
-    const b = baseTs(ts);
-    if (b === 'Date') return true;
-    if (isInlineObject(b) || isInlineObjectArray(b)) return /:\s*Date\b/.test(b);
-    return false;
-}
-function fieldUsesJSON(ts) {
-    const b = baseTs(ts);
-    if (b === 'unknown' || b === 'any' || b === 'object') return true;
-    if (isInlineObject(b) || isInlineObjectArray(b)) return /:\s*(unknown|any|object)\b/.test(b);
-    return false;
-}
 const cmd = commands[0];
 const usesDate = cmd.fields.some(f => fieldUsesDate(f.tsType));
 const usesJSON = cmd.fields.some(f => fieldUsesJSON(f.tsType));
+const enumList = collectEnumNames(cmd.fields);
 
 const embeddedInputs = [];
 for (const f of cmd.fields) {
@@ -38,7 +17,7 @@ for (const f of cmd.fields) {
 %>
 import { Mutation, Resolver, Arg, Ctx, Field, InputType<% if (usesDate) { %>, GraphQLISODateTime<% } %> } from 'type-graphql';
 <% if (usesJSON) { %>import { GraphQLJSON } from 'graphql-type-json';
-<% } %>import { type GraphQLContext, sendCommand, MutationResponse } from '../../../shared';
+<% } %>import { type GraphQLContext, sendCommand, MutationResponse<% if (enumList.length > 0) { %>, <%= enumList.join(', ') %><% } %> } from '../../../shared';
 
 <% for (const { typeName, tsType } of embeddedInputs) {
     const inner = tsType.trim().startsWith('Array<')

package/dist/src/codegen/templates/command/register.specs.ts

@@ -107,7 +107,7 @@ describe('generateScaffoldFilePlans', () => {
           import type { CreateListing } from './commands';
 
           export function register(messageBus: CommandProcessor, eventStore: EventStore) {
-            messageBus.handle((command: CreateListing) => handle(eventStore, command), 'CreateListing');
+            messageBus.handle<CreateListing>((command: CreateListing) => handle(eventStore, command), 'CreateListing');
           }
           "
         `);

package/dist/src/codegen/templates/command/register.ts.ejs

@@ -4,9 +4,6 @@ import type { <%= commands.map(c => pascalCase(c.type)).join(', ') %> } from './
 
 export function register(messageBus: CommandProcessor, eventStore: EventStore) {
 <% for (const command of commands) { -%>
-    messageBus.handle(
-    (command: <%= pascalCase(command.type) %>) => handle(eventStore, command),
-    '<%= command.type %>'
-    );
+  messageBus.handle<<%= pascalCase(command.type) %>>((command: <%= pascalCase(command.type) %>) => handle(eventStore, command), '<%= command.type %>');
 <% } -%>
 }

package/dist/src/codegen/templates/command/state.specs.ts

@@ -82,54 +82,58 @@ describe('state.ts.ejs', () => {
     const stateFile = plans.find((p) => p.outputPath.endsWith('state.ts'));
 
     expect(stateFile?.contents).toMatchInlineSnapshot(`
-          "/**
-           * ## IMPLEMENTATION INSTRUCTIONS ##
-           *
-           * Define the shape of the domain state for the current slice below. This state is used by \`decide.ts\`
-           * to determine whether a command is valid.
-           *
-           * The state is evolved over time by applying domain events (in \`evolve.ts\`).
-           * Each event updates the state incrementally based on business rules.
-           *
-           * Guidelines:
-           * - Include only fields that are **read** during command validation.
-           * - Use discriminated unions (e.g., \`status: 'Pending' | 'Done'\`) to model state transitions.
-           * - Prefer primitive types: \`string\`, \`boolean\`, \`number\`.
-           * - Use objects or maps only when structure is essential for decision logic.
-           *
-           * Do NOT include:
-           * - Redundant data already emitted in events unless required to enforce business rules.
-           * - Fields used only for projections, UI, or query purposes.
-           *
-           * ### Example (for a Task domain):
-           *
-           * \`\`\`ts
-           * export type PendingTask = {
-           *   status: 'Pending';
-           * };
-           *
-           * export type InProgressTask = {
-           *   status: 'InProgress';
-           *   startedAt: string;
-           * };
-           *
-           * export type CompletedTask = {
-           *   status: 'Completed';
-           *   completedAt: string;
-           * };
-           *
-           * export type State = PendingTask | InProgressTask | CompletedTask;
-           * \`\`\`
-           */
+      "/**
+       * ## IMPLEMENTATION INSTRUCTIONS ##
+       *
+       * Define the shape of the domain state for the current slice below. This state is used by \`decide.ts\`
+       * to determine whether a command is valid.
+       *
+       * The state is evolved over time by applying domain events (in \`evolve.ts\`).
+       * Each event updates the state incrementally based on business rules.
+       *
+       * Guidelines:
+       * - Include only fields that are **read** during command validation.
+       * - Use discriminated unions with string literal types (e.g., \`status: 'pending' | 'done'\`) to model state transitions.
+       * - IMPORTANT: If an enum exists in domain/shared/types.ts for your field (e.g., Status enum), use the enum constant type instead (e.g., \`status: Status.PENDING\`).
+       * - Prefer primitive types: \`string\`, \`boolean\`, \`number\`.
+       * - Use objects or maps only when structure is essential for decision logic.
+       *
+       * Do NOT include:
+       * - Redundant data already emitted in events unless required to enforce business rules.
+       * - Fields used only for projections, UI, or query purposes.
+       *
+       * ### Example (for a Task domain):
+       *
+       * \`\`\`ts
+       * export type PendingTask = {
+       *   status: 'pending';
+       * };
+       *
+       * export type InProgressTask = {
+       *   status: 'in_progress';
+       *   startedAt: string;
+       * };
+       *
+       * export type CompletedTask = {
+       *   status: 'completed';
+       *   completedAt: string;
+       * };
+       *
+       * export type State = PendingTask | InProgressTask | CompletedTask;
+       * \`\`\`
+       *
+       * Note: Status string literals should match your schema's enum values (usually snake_case).
+       * If an enum is defined in domain/shared/types.ts, reference the enum type instead of literals.
+       */
 
-          // TODO: Replace with a discriminated union of domain states for the current slice
-          export type State = {};
+      // TODO: Replace with a discriminated union of domain states for the current slice
+      export type State = {};
 
-          // TODO: Replace the Return with the initial domain state of the current slice
-          export const initialState = (): State => {
-            return {};
-          };
-          "
-        `);
+      // TODO: Replace the Return with the initial domain state of the current slice
+      export const initialState = (): State => {
+        return {};
+      };
+      "
+    `);
   });
 });

package/dist/src/codegen/templates/command/state.ts.ejs

@@ -9,7 +9,8 @@
 *
 * Guidelines:
 * - Include only fields that are **read** during command validation.
-* - Use discriminated unions (e.g., `status: 'Pending' | 'Done'`) to model state transitions.
+* - Use discriminated unions with string literal types (e.g., `status: 'pending' | 'done'`) to model state transitions.
+* - IMPORTANT: If an enum exists in domain/shared/types.ts for your field (e.g., Status enum), use the enum constant type instead (e.g., `status: Status.PENDING`).
 * - Prefer primitive types: `string`, `boolean`, `number`.
 * - Use objects or maps only when structure is essential for decision logic.
 *
@@ -21,21 +22,24 @@
 *
 * ```ts
 * export type PendingTask = {
-*   status: 'Pending';
+*   status: 'pending';
 * };
 *
 * export type InProgressTask = {
-*   status: 'InProgress';
+*   status: 'in_progress';
 *   startedAt: string;
 * };
 *
 * export type CompletedTask = {
-*   status: 'Completed';
+*   status: 'completed';
 *   completedAt: string;
 * };
 *
 * export type State = PendingTask | InProgressTask | CompletedTask;
 * ```
+*
+* Note: Status string literals should match your schema's enum values (usually snake_case).
+* If an enum is defined in domain/shared/types.ts, reference the enum type instead of literals.
 */
 
 // TODO: Replace with a discriminated union of domain states for the current slice

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

@@ -227,8 +227,24 @@ describe('projection.ts.ejs', () => {
             case 'ListingCreated': {
               /**
                * ## IMPLEMENTATION INSTRUCTIONS ##
-               * This event adds or updates the document.
-               * Implement the correct fields as needed for your read model.
+               * 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 as InternalAvailableListings) || { ...defaults };
+               *
+               * 3. Cast return values to extended type:
+               *    return { ...allFields, internalField } as InternalAvailableListings;
+               *
+               * This keeps internal state separate from the public GraphQL schema.
                */
               return {
                 propertyId: /* TODO: map from event.data */ '',
@@ -329,6 +345,7 @@ describe('projection.ts.ejs', () => {
         @Field(() => String)
         items!: string;
 
+        // IMPORTANT: Index signature required for ReadModel<T extends Record<string, unknown>> compatibility
         [key: string]: unknown;
       }
 

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

@@ -10,6 +10,30 @@ if (eventImportGroups.length > 0) {
 import type { <%= group.eventTypes.join(', ') %> } from '<%= group.importPath %>';
 <%
     }
+}
+
+// Collect enums used in state fields
+const stateEnums = [];
+const targetName = slice.server?.data?.[0]?.target?.name;
+if (targetName && messages) {
+    const targetDef = messages.find(m => m.name === targetName);
+    if (targetDef?.fields) {
+        for (const field of targetDef.fields) {
+            const fieldType = (field.type || '').replace(/\s*\|\s*null/g, '').trim();
+            if (fieldType.includes('|') && (fieldType.includes('"') || fieldType.includes("'"))) {
+                const enumName = toTsFieldType(field.type);
+                if (enumName && enumName !== 'String' && !stateEnums.includes(enumName)) {
+                    stateEnums.push(enumName);
+                }
+            }
+        }
+    }
+}
+
+if (stateEnums.length > 0) {
+%>
+import { <%= stateEnums.join(', ') %> } from '../../../shared';
+<%
 } -%>
 
 type AllEvents = <%= allEventTypes %>;
@@ -76,8 +100,24 @@ case '<%= event.type %>': {
     * - 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.
 <% } else { -%>
-    * This event adds or updates the document.
-    * Implement the correct fields as needed for your read model.
+    * Implement how this event updates the projection.
+    *
+    * **IMPORTANT - Internal State Pattern:**
+    * If you need to track state beyond the public <%= pascalCase(targetName || 'State') %> type (e.g., to calculate
+    * aggregations, track previous values, etc.), follow this pattern:
+    *
+    * 1. Define an extended interface BEFORE the projection:
+    *    interface Internal<%= pascalCase(targetName || 'State') %> extends <%= pascalCase(targetName || 'State') %> {
+    *      internalField: SomeType;
+    *    }
+    *
+    * 2. Cast document parameter to extended type:
+    *    const current: Internal<%= pascalCase(targetName || 'State') %> = (document as Internal<%= pascalCase(targetName || 'State') %>) || { ...defaults };
+    *
+    * 3. Cast return values to extended type:
+    *    return { ...allFields, internalField } as Internal<%= pascalCase(targetName || 'State') %>;
+    *
+    * This keeps internal state separate from the public GraphQL schema.
 <% } -%>
 */
 <% if (isRemovalEvent) { -%>
@@ -94,16 +134,28 @@ case '<%= event.type %>': {
         const type = def?.type ?? 'string';
 
         let placeholder = 'undefined';
-        if (type === 'string' || type === 'ID') {
-            placeholder = "/* TODO: map from event.data */ ''";
-        } else if (type === 'number') {
-            placeholder = '/* TODO: map from event.data */ 0';
-        } else if (type === 'boolean') {
-            placeholder = '/* TODO: map from event.data */ false';
-        } else if (type === 'Date') {
-            placeholder = '/* TODO: map from event.data */ new Date()';
-        } else if (type.startsWith('Array<')) {
-            placeholder = '/* TODO: map from event.data */ []';
+        const isNullable = type.includes('| null') || type.includes('|null');
+        const baseType = isNullable ? type.replace(/\s*\|\s*null/g, '').trim() : type;
+
+        if (baseType === 'string' || baseType === 'ID') {
+            placeholder = isNullable ? "/* TODO: map from event.data */ null" : "/* TODO: map from event.data */ ''";
+        } else if (baseType === 'number') {
+            placeholder = isNullable ? '/* TODO: map from event.data */ null' : '/* TODO: map from event.data */ 0';
+        } else if (baseType === 'boolean') {
+            placeholder = isNullable ? '/* TODO: map from event.data */ null' : '/* TODO: map from event.data */ false';
+        } else if (baseType === 'Date') {
+            placeholder = isNullable ? '/* TODO: map from event.data */ null' : '/* TODO: map from event.data */ new Date()';
+        } else if (baseType.startsWith('Array<')) {
+            placeholder = isNullable ? '/* TODO: map from event.data */ null' : '/* TODO: map from event.data */ []';
+        } else if (baseType.includes('|') && (baseType.includes('"') || baseType.includes("'"))) {
+            const enumName = toTsFieldType(type);
+            const firstValue = baseType.match(/['"]([^'"]+)['"]/)?.[1] ?? '';
+            const enumConstant = firstValue ? firstValue.toUpperCase().replace(/[^A-Z0-9]/g, '_') : '';
+            if (enumName && enumName !== 'String') {
+                placeholder = `${enumName}.${enumConstant} /* TODO: verify this enum constant is correct */`;
+            } else {
+                placeholder = `/* TODO: use enum constant from types.ts */ '${firstValue}'`;
+            }
         } else {
             placeholder = '/* TODO: map from event.data */ undefined as any';
         }

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

@@ -87,6 +87,7 @@ describe('query.resolver.ts.ejs', () => {
         @Field(() => Float)
         maxGuests!: number;
 
+        // IMPORTANT: Index signature required for ReadModel<T extends Record<string, unknown>> compatibility
         [key: string]: unknown;
       }
 
@@ -217,6 +218,7 @@ describe('query.resolver.ts.ejs', () => {
         @Field(() => [SuggestedItemsItems])
         items!: SuggestedItemsItems[];
 
+        // IMPORTANT: Index signature required for ReadModel<T extends Record<string, unknown>> compatibility
         [key: string]: unknown;
       }
 
@@ -360,7 +362,7 @@ describe('query.resolver.ts.ejs', () => {
     expect(queryFile?.contents).toMatchInlineSnapshot(`
       "import { Query, Resolver, Arg, Ctx, ObjectType, Field, ID } from 'type-graphql';
       import { GraphQLJSON } from 'graphql-type-json';
-      import { type GraphQLContext, ReadModel } from '../../../shared';
+      import { type GraphQLContext, ReadModel, QuestionnaireProgressStatus } from '../../../shared';
 
       @ObjectType()
       export class QuestionnaireProgressAnswers {
@@ -379,8 +381,8 @@ describe('query.resolver.ts.ejs', () => {
         @Field(() => String)
         participantId!: string;
 
-        @Field(() => String)
-        status!: 'in_progress' | 'ready_to_submit' | 'submitted';
+        @Field(() => QuestionnaireProgressStatus)
+        status!: QuestionnaireProgressStatus;
 
         @Field(() => String, { nullable: true })
         currentQuestionId?: string | null;
@@ -391,6 +393,7 @@ describe('query.resolver.ts.ejs', () => {
         @Field(() => [QuestionnaireProgressAnswers])
         answers!: QuestionnaireProgressAnswers[];
 
+        // IMPORTANT: Index signature required for ReadModel<T extends Record<string, unknown>> compatibility
         [key: string]: unknown;
       }