@auto-engineer/narrative 0.11.13 → 0.11.14

package/src/model-to-narrative.specs.ts

@@ -501,7 +501,9 @@ narrative('Test Flow with IDs', 'FLOW-123', () => {
         should('allow filtering');
       });
     })
-    .server(() => {});
+    .server(() => {
+      specs('Product data specs', () => {});
+    });
 });
 `);
   });
@@ -2031,4 +2033,398 @@ narrative('Todo List Summary', 'TODO-001', () => {
     expect(code).not.toContain('.when({})');
     expect(code).not.toContain('.when<');
   });
+
+  describe('projection DSL generation', () => {
+    it('should generate fromSingletonProjection for singleton projections', async () => {
+      const modelWithSingletonProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Todo Summary Flow',
+            id: 'TODO-SUMMARY',
+            slices: [
+              {
+                name: 'views todo summary',
+                id: 'SUMMARY-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Summary client',
+                },
+                server: {
+                  description: 'Summary server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoListSummary',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'TodoSummary',
+                        singleton: true,
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Summary Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoListSummary',
+            fields: [
+              { name: 'summaryId', type: 'string', required: true },
+              { name: 'totalTodos', type: 'number', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithSingletonProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoListSummary = State<
+  'TodoListSummary',
+  {
+    summaryId: string;
+    totalTodos: number;
+  }
+>;
+narrative('Todo Summary Flow', 'TODO-SUMMARY', () => {
+  query('views todo summary', 'SUMMARY-SLICE').server(() => {
+    data([source().state('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    specs('Summary Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate fromProjection with single idField for regular projections', async () => {
+      const modelWithRegularProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Todo Flow',
+            id: 'TODO-FLOW',
+            slices: [
+              {
+                name: 'views todo',
+                id: 'TODO-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Todo client',
+                },
+                server: {
+                  description: 'Todo server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'Todos',
+                        idField: 'todoId',
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Todo Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoState',
+            fields: [
+              { name: 'todoId', type: 'string', required: true },
+              { name: 'description', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithRegularProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoState = State<
+  'TodoState',
+  {
+    todoId: string;
+    description: string;
+  }
+>;
+narrative('Todo Flow', 'TODO-FLOW', () => {
+  query('views todo', 'TODO-SLICE').server(() => {
+    data([source().state('TodoState').fromProjection('Todos', 'todoId')]);
+    specs('Todo Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate fromCompositeProjection with array idField for composite key projections', async () => {
+      const modelWithCompositeProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'User Project Flow',
+            id: 'USER-PROJECT-FLOW',
+            slices: [
+              {
+                name: 'views user project',
+                id: 'USER-PROJECT-SLICE',
+                type: 'query',
+                client: {
+                  description: 'User project client',
+                },
+                server: {
+                  description: 'User project server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'UserProjectState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'UserProjects',
+                        idField: ['userId', 'projectId'],
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'User Project Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'UserProjectState',
+            fields: [
+              { name: 'userId', type: 'string', required: true },
+              { name: 'projectId', type: 'string', required: true },
+              { name: 'role', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithCompositeProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type UserProjectState = State<
+  'UserProjectState',
+  {
+    userId: string;
+    projectId: string;
+    role: string;
+  }
+>;
+narrative('User Project Flow', 'USER-PROJECT-FLOW', () => {
+  query('views user project', 'USER-PROJECT-SLICE').server(() => {
+    data([source().state('UserProjectState').fromCompositeProjection('UserProjects', ['userId', 'projectId'])]);
+    specs('User Project Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate all three projection types in a single narrative', async () => {
+      const modelWithAllProjectionTypes: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'All Projection Types',
+            id: 'ALL-PROJ',
+            slices: [
+              {
+                name: 'views summary',
+                id: 'SUMMARY-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Summary client',
+                },
+                server: {
+                  description: 'Summary server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoListSummary',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'TodoSummary',
+                        singleton: true,
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Summary Rules',
+                    rules: [],
+                  },
+                },
+              },
+              {
+                name: 'views todo',
+                id: 'TODO-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Todo client',
+                },
+                server: {
+                  description: 'Todo server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'Todos',
+                        idField: 'todoId',
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Todo Rules',
+                    rules: [],
+                  },
+                },
+              },
+              {
+                name: 'views user project todos',
+                id: 'USER-PROJECT-SLICE',
+                type: 'query',
+                client: {
+                  description: 'User project client',
+                },
+                server: {
+                  description: 'User project server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'UserProjectTodos',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'UserProjectTodos',
+                        idField: ['userId', 'projectId'],
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'User Project Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoListSummary',
+            fields: [
+              { name: 'summaryId', type: 'string', required: true },
+              { name: 'totalTodos', type: 'number', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+          {
+            type: 'state',
+            name: 'TodoState',
+            fields: [
+              { name: 'todoId', type: 'string', required: true },
+              { name: 'description', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+          {
+            type: 'state',
+            name: 'UserProjectTodos',
+            fields: [
+              { name: 'userId', type: 'string', required: true },
+              { name: 'projectId', type: 'string', required: true },
+              { name: 'todos', type: 'Array<string>', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithAllProjectionTypes);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoListSummary = State<
+  'TodoListSummary',
+  {
+    summaryId: string;
+    totalTodos: number;
+  }
+>;
+type TodoState = State<
+  'TodoState',
+  {
+    todoId: string;
+    description: string;
+  }
+>;
+type UserProjectTodos = State<
+  'UserProjectTodos',
+  {
+    userId: string;
+    projectId: string;
+    todos: string[];
+  }
+>;
+narrative('All Projection Types', 'ALL-PROJ', () => {
+  query('views summary', 'SUMMARY-SLICE').server(() => {
+    data([source().state('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    specs('Summary Rules', () => {});
+  });
+  query('views todo', 'TODO-SLICE').server(() => {
+    data([source().state('TodoState').fromProjection('Todos', 'todoId')]);
+    specs('Todo Rules', () => {});
+  });
+  query('views user project todos', 'USER-PROJECT-SLICE').server(() => {
+    data([source().state('UserProjectTodos').fromCompositeProjection('UserProjectTodos', ['userId', 'projectId'])]);
+    specs('User Project Rules', () => {});
+  });
+});
+`);
+    });
+  });
 });

package/src/schema.ts

@@ -49,7 +49,18 @@ export const OriginSchema = z
     z.object({
       type: z.literal('projection'),
       name: z.string(),
-      idField: z.string().describe('Field from event used as the projection’s unique identifier'),
+      idField: z
+        .union([z.string(), z.array(z.string())])
+        .optional()
+        .describe(
+          'Field(s) from event used as the projection unique identifier. Can be single field or array for composite keys. Omit for singleton projections.',
+        ),
+      singleton: z
+        .boolean()
+        .optional()
+        .describe(
+          'True if this is a singleton projection that aggregates data from multiple entities into one document',
+        ),
     }),
     z.object({
       type: z.literal('readModel'),

package/src/transformers/model-to-narrative/generators/flow.ts

@@ -110,6 +110,42 @@ function addDestinationToChain(f: tsNS.NodeFactory, chain: tsNS.Expression, dest
   }
 }
 
+function buildProjectionCall(
+  f: tsNS.NodeFactory,
+  baseCall: tsNS.Expression,
+  origin: { type: 'projection'; name: string; idField?: string | string[]; singleton?: boolean },
+): tsNS.Expression {
+  if (origin.singleton === true) {
+    return f.createCallExpression(
+      f.createPropertyAccessExpression(baseCall, f.createIdentifier('fromSingletonProjection')),
+      undefined,
+      [f.createStringLiteral(origin.name)],
+    );
+  }
+  if (Array.isArray(origin.idField)) {
+    return f.createCallExpression(
+      f.createPropertyAccessExpression(baseCall, f.createIdentifier('fromCompositeProjection')),
+      undefined,
+      [
+        f.createStringLiteral(origin.name),
+        f.createArrayLiteralExpression(origin.idField.map((field) => f.createStringLiteral(field))),
+      ],
+    );
+  }
+  if (typeof origin.idField === 'string' && origin.idField.length > 0) {
+    return f.createCallExpression(
+      f.createPropertyAccessExpression(baseCall, f.createIdentifier('fromProjection')),
+      undefined,
+      [f.createStringLiteral(origin.name), f.createStringLiteral(origin.idField)],
+    );
+  }
+  return f.createCallExpression(
+    f.createPropertyAccessExpression(baseCall, f.createIdentifier('fromSingletonProjection')),
+    undefined,
+    [f.createStringLiteral(origin.name)],
+  );
+}
+
 function buildStateCall(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
@@ -135,11 +171,7 @@ function buildStateCall(
       );
     }
     case 'projection':
-      return f.createCallExpression(
-        f.createPropertyAccessExpression(baseStateCall, f.createIdentifier('fromProjection')),
-        undefined,
-        [f.createStringLiteral(origin.name), f.createStringLiteral(origin.idField)],
-      );
+      return buildProjectionCall(f, baseStateCall, origin);
     case 'database': {
       const args: tsNS.Expression[] = [f.createStringLiteral(origin.collection)];
       if (origin.query !== null && origin.query !== undefined) {
@@ -173,10 +205,39 @@ function buildStateCall(
   }
 }
 
+function buildProjectionArgs(
+  f: tsNS.NodeFactory,
+  origin: { name: string; idField?: string | string[]; singleton?: boolean },
+): tsNS.Expression[] {
+  if (origin.singleton === true) {
+    return [f.createStringLiteral(origin.name)];
+  }
+  if (Array.isArray(origin.idField)) {
+    return [
+      f.createStringLiteral(origin.name),
+      f.createArrayLiteralExpression(origin.idField.map((field) => f.createStringLiteral(field))),
+    ];
+  }
+  if (typeof origin.idField === 'string' && origin.idField.length > 0) {
+    return [f.createStringLiteral(origin.name), f.createStringLiteral(origin.idField)];
+  }
+  return [f.createStringLiteral(origin.name)];
+}
+
+function getProjectionMethodName(origin: { idField?: string | string[]; singleton?: boolean }): string {
+  if (origin.singleton === true) {
+    return 'fromSingletonProjection';
+  }
+  if (Array.isArray(origin.idField)) {
+    return 'fromCompositeProjection';
+  }
+  return 'fromProjection';
+}
+
 function buildOriginArgs(ts: typeof import('typescript'), f: tsNS.NodeFactory, origin: Origin): tsNS.Expression[] {
   switch (origin.type) {
     case 'projection':
-      return [f.createStringLiteral(origin.name), f.createStringLiteral(origin.idField)];
+      return buildProjectionArgs(f, origin);
     case 'integration': {
       const [sys] = origin.systems;
       return [f.createIdentifier(sys)];
@@ -205,7 +266,7 @@ function buildOriginArgs(ts: typeof import('typescript'), f: tsNS.NodeFactory, o
 function getOriginMethodName(origin: Origin): string {
   switch (origin.type) {
     case 'projection':
-      return 'fromProjection';
+      return getProjectionMethodName(origin);
     case 'integration':
       return 'fromIntegration';
     case 'database':
@@ -454,27 +515,25 @@ function buildServerStatements(
     const ruleGroups = buildRuleGroups(server.specs.rules as RuleType[]);
     const allRuleStatements = buildConsolidatedRules(ts, f, ruleGroups, sliceType, messages);
 
-    if (allRuleStatements.length > 0) {
-      const arrowFunction = f.createArrowFunction(
-        undefined,
-        undefined,
-        [],
-        undefined,
-        f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-        f.createBlock(allRuleStatements, true),
-      );
-
-      const args: tsNS.Expression[] = [];
-      if (server.specs.name && server.specs.name.trim() !== '') {
-        args.push(f.createStringLiteral(server.specs.name));
-      }
-      args.push(arrowFunction);
+    const arrowFunction = f.createArrowFunction(
+      undefined,
+      undefined,
+      [],
+      undefined,
+      f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+      f.createBlock(allRuleStatements, true),
+    );
 
-      const specsStatement = f.createExpressionStatement(
-        f.createCallExpression(f.createIdentifier('specs'), undefined, args),
-      );
-      statements.push(specsStatement);
+    const args: tsNS.Expression[] = [];
+    if (server.specs.name && server.specs.name.trim() !== '') {
+      args.push(f.createStringLiteral(server.specs.name));
     }
+    args.push(arrowFunction);
+
+    const specsStatement = f.createExpressionStatement(
+      f.createCallExpression(f.createIdentifier('specs'), undefined, args),
+    );
+    statements.push(specsStatement);
   }
 
   return statements;

package/src/types.ts

@@ -87,9 +87,11 @@ export const createDatabaseDestination = (collection: string): DatabaseDestinati
 });
 export const createTopicDestination = (name: string): TopicDestination => ({ type: 'topic', name });
 
-export interface ProjectionOrigin {
+export interface ProjectionOriginWithId {
   type: 'projection';
   name: string;
+  idField?: string | string[];
+  singleton?: boolean;
 }
 
 export interface ReadModelOrigin {
@@ -116,14 +118,8 @@ export interface IntegrationOrigin {
 
 export type Origin = ProjectionOriginWithId | ReadModelOrigin | DatabaseOrigin | ApiOrigin | IntegrationOrigin;
 
-export interface ProjectionOriginWithId {
-  type: 'projection';
-  name: string;
-  idField: string;
-}
-
 // Helper functions to create origins
-export const createProjectionOrigin = (name: string): ProjectionOrigin => ({ type: 'projection', name });
+export const createProjectionOrigin = (name: string): ProjectionOriginWithId => ({ type: 'projection', name });
 export const createReadModelOrigin = (name: string): ReadModelOrigin => ({ type: 'readModel', name });
 export const createDatabaseOrigin = (collection: string, query?: Record<string, unknown>): DatabaseOrigin => ({
   type: 'database',
@@ -161,7 +157,7 @@ export interface DataItem {
   __type: 'sink' | 'source';
 }
 
-type DefaultRecord = Record<string, unknown>;
+export type DefaultRecord = Record<string, unknown>;
 
 export type State<
   StateType extends string = string,
@@ -224,3 +220,5 @@ export type Event<
 > & {
   readonly kind?: 'Event';
 };
+
+export type ExtractStateData<T> = T extends State<string, infer Data, DefaultRecord | undefined> ? Data : never;