@auto-engineer/narrative 0.18.0 → 0.19.1

package/src/id/addAutoIds.ts

@@ -77,11 +77,30 @@ function processClientSpecs(slice: Slice): Slice {
   return modifiedSlice;
 }
 
+function processDataItems(slice: Slice): Slice {
+  if (!('server' in slice) || !slice.server?.data || !Array.isArray(slice.server.data)) return slice;
+
+  const modifiedSlice = structuredClone(slice);
+  if ('server' in modifiedSlice && modifiedSlice.server?.data && Array.isArray(modifiedSlice.server.data)) {
+    modifiedSlice.server.data = modifiedSlice.server.data.map((item) => {
+      const itemCopy = { ...item };
+      ensureId(itemCopy);
+      if ('destination' in itemCopy && itemCopy._withState) {
+        itemCopy._withState = { ...itemCopy._withState };
+        ensureId(itemCopy._withState);
+      }
+      return itemCopy;
+    });
+  }
+  return modifiedSlice;
+}
+
 function processSlice(slice: Slice): Slice {
   let sliceCopy = { ...slice };
   ensureId(sliceCopy);
   sliceCopy = processServerSpecs(sliceCopy);
   sliceCopy = processClientSpecs(sliceCopy);
+  sliceCopy = processDataItems(sliceCopy);
   return sliceCopy;
 }
 

package/src/id/hasAllIds.specs.ts

@@ -451,6 +451,229 @@ describe('hasAllIds', () => {
     expect(hasAllIds(model)).toBe(true);
   });
 
+  describe('data item ID validation', () => {
+    it('should return false when data sink is missing an ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'command',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                  data: [
+                    {
+                      __type: 'sink',
+                      target: { type: 'Event', name: 'TestEvent' },
+                      destination: { type: 'stream', pattern: 'test-stream' },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(false);
+    });
+
+    it('should return false when data source is missing an ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'query',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                  data: [
+                    {
+                      __type: 'source',
+                      target: { type: 'State', name: 'TestState' },
+                      origin: { type: 'projection', name: 'TestProjection' },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(false);
+    });
+
+    it('should return false when nested _withState source is missing an ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'command',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                  data: [
+                    {
+                      __type: 'sink',
+                      id: 'SINK-001',
+                      target: { type: 'Command', name: 'TestCommand' },
+                      destination: { type: 'stream', pattern: 'test-stream' },
+                      _withState: {
+                        target: { type: 'State', name: 'TestState' },
+                        origin: { type: 'projection', name: 'TestProjection' },
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(false);
+    });
+
+    it('should return true when all data items have IDs', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'command',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                  data: [
+                    {
+                      __type: 'sink',
+                      id: 'SINK-001',
+                      target: { type: 'Event', name: 'TestEvent' },
+                      destination: { type: 'stream', pattern: 'test-stream' },
+                    },
+                    {
+                      __type: 'source',
+                      id: 'SOURCE-001',
+                      target: { type: 'State', name: 'TestState' },
+                      origin: { type: 'projection', name: 'TestProjection' },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(true);
+    });
+
+    it('should return true when sink with _withState both have IDs', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'command',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                  data: [
+                    {
+                      __type: 'sink',
+                      id: 'SINK-001',
+                      target: { type: 'Command', name: 'TestCommand' },
+                      destination: { type: 'stream', pattern: 'test-stream' },
+                      _withState: {
+                        id: 'SOURCE-001',
+                        target: { type: 'State', name: 'TestState' },
+                        origin: { type: 'projection', name: 'TestProjection' },
+                      },
+                    },
+                  ],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(true);
+    });
+
+    it('should return true when slice has no data array', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Test Flow',
+            id: 'FLOW-001',
+            slices: [
+              {
+                type: 'command',
+                name: 'Test slice',
+                id: 'SLICE-001',
+                client: { specs: [] },
+                server: {
+                  description: 'Test server',
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+      expect(hasAllIds(model)).toBe(true);
+    });
+  });
+
   describe('module ID validation', () => {
     it('should return true when all modules have IDs', () => {
       const model: Model = {

package/src/id/hasAllIds.ts

@@ -40,8 +40,20 @@ function hasClientSpecIds(slice: Slice): boolean {
   return hasClientSpecNodeIds(slice.client.specs);
 }
 
+function hasDataIds(slice: Slice): boolean {
+  if (!('server' in slice) || !slice.server?.data || !Array.isArray(slice.server.data)) return true;
+
+  return slice.server.data.every((item) => {
+    if (!hasValidId(item)) return false;
+    if ('destination' in item && item._withState) {
+      return hasValidId(item._withState);
+    }
+    return true;
+  });
+}
+
 function hasSliceIds(slice: Slice): boolean {
-  return hasValidId(slice) && hasServerSpecIds(slice) && hasClientSpecIds(slice);
+  return hasValidId(slice) && hasServerSpecIds(slice) && hasClientSpecIds(slice) && hasDataIds(slice);
 }
 
 function hasModuleIds(modules: Module[]): boolean {

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

@@ -2938,4 +2938,180 @@ narrative('All Projection Types', 'ALL-PROJ', () => {
       }
     });
   });
+
+  describe('data item IDs', () => {
+    it('should generate sink id when provided', async () => {
+      const modelWithSinkId: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Order Flow',
+            id: 'ORDER-FLOW',
+            slices: [
+              {
+                name: 'places order',
+                id: 'ORDER-SLICE',
+                type: 'command',
+                client: { specs: [] },
+                server: {
+                  description: 'Order server',
+                  data: [
+                    {
+                      id: 'SINK-001',
+                      target: { type: 'Event', name: 'OrderPlaced' },
+                      destination: { type: 'stream', pattern: 'orders-stream' },
+                    },
+                  ],
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'event',
+            source: 'internal',
+            name: 'OrderPlaced',
+            fields: [{ name: 'orderId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithSinkId));
+      expect(code).toContain("sink('SINK-001').event('OrderPlaced').toStream('orders-stream')");
+    });
+
+    it('should generate source id when provided', async () => {
+      const modelWithSourceId: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Order Flow',
+            id: 'ORDER-FLOW',
+            slices: [
+              {
+                name: 'views order',
+                id: 'ORDER-SLICE',
+                type: 'query',
+                client: { specs: [] },
+                server: {
+                  description: 'Order server',
+                  data: [
+                    {
+                      id: 'SOURCE-001',
+                      target: { type: 'State', name: 'OrderState' },
+                      origin: { type: 'projection', name: 'Orders', idField: 'orderId' },
+                    },
+                  ],
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'OrderState',
+            fields: [{ name: 'orderId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithSourceId));
+      expect(code).toContain("source('SOURCE-001').state('OrderState').fromProjection('Orders', 'orderId')");
+    });
+
+    it('should not generate id when not provided', async () => {
+      const modelWithoutId: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Order Flow',
+            id: 'ORDER-FLOW',
+            slices: [
+              {
+                name: 'places order',
+                id: 'ORDER-SLICE',
+                type: 'command',
+                client: { specs: [] },
+                server: {
+                  description: 'Order server',
+                  data: [
+                    {
+                      target: { type: 'Event', name: 'OrderPlaced' },
+                      destination: { type: 'stream', pattern: 'orders-stream' },
+                    },
+                  ],
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'event',
+            source: 'internal',
+            name: 'OrderPlaced',
+            fields: [{ name: 'orderId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithoutId));
+      expect(code).toContain("sink().event('OrderPlaced').toStream('orders-stream')");
+      expect(code).not.toContain("sink('')");
+    });
+
+    it('should generate _additionalInstructions on source items', async () => {
+      const modelWithSourceInstructions: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Order Flow',
+            id: 'ORDER-FLOW',
+            slices: [
+              {
+                name: 'views order',
+                id: 'ORDER-SLICE',
+                type: 'query',
+                client: { specs: [] },
+                server: {
+                  description: 'Order server',
+                  data: [
+                    {
+                      target: { type: 'State', name: 'OrderState' },
+                      origin: { type: 'projection', name: 'Orders', idField: 'orderId' },
+                      _additionalInstructions: 'Filter by active orders only',
+                    },
+                  ],
+                  specs: [],
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'OrderState',
+            fields: [{ name: 'orderId', type: 'string', required: true }],
+          },
+        ],
+        integrations: [],
+        modules: [],
+      };
+
+      const code = getCode(await modelToNarrative(modelWithSourceInstructions));
+      expect(code).toContain(".additionalInstructions('Filter by active orders only')");
+    });
+  });
 });

package/src/schema.ts

@@ -112,6 +112,7 @@ export const OriginSchema = z
 
 const DataSinkSchema = z
   .object({
+    id: z.string().optional().describe('Optional unique identifier for the data sink'),
     target: MessageTargetSchema,
     destination: DestinationSchema,
     transform: z.string().optional().describe('Optional transformation function name'),
@@ -125,6 +126,7 @@ const DataSinkSchema = z
 
 const DataSourceSchema = z
   .object({
+    id: z.string().optional().describe('Optional unique identifier for the data source'),
     target: MessageTargetSchema,
     origin: OriginSchema,
     transform: z.string().optional().describe('Optional transformation function name'),

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

@@ -84,13 +84,15 @@ function buildInitialChain(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
   target: DataSinkItem['target'] | DataSourceItem['target'],
+  id?: string,
 ): tsNS.Expression {
   const op = target.type === 'Event' ? 'event' : target.type === 'Command' ? 'command' : 'state';
+  const sinkOrSourceArgs: tsNS.Expression[] = id != null && id !== '' ? [f.createStringLiteral(id)] : [];
   return f.createCallExpression(
     f.createPropertyAccessExpression(
       target.type === 'State'
-        ? f.createCallExpression(f.createIdentifier('source'), undefined, [])
-        : f.createCallExpression(f.createIdentifier('sink'), undefined, []),
+        ? f.createCallExpression(f.createIdentifier('source'), undefined, sinkOrSourceArgs)
+        : f.createCallExpression(f.createIdentifier('sink'), undefined, sinkOrSourceArgs),
       ts.factory.createIdentifier(op),
     ),
     undefined,
@@ -309,7 +311,7 @@ function buildSingleDataItem(
   f: tsNS.NodeFactory,
   it: DataSinkItem | DataSourceItem,
 ): tsNS.Expression {
-  let chain = buildInitialChain(ts, f, it.target);
+  let chain = buildInitialChain(ts, f, it.target, it.id);
 
   if ('destination' in it) {
     const sinkItem = it;
@@ -333,11 +335,13 @@ function buildSingleDataItem(
     }
   } else if ('origin' in it) {
     const sourceItem = it;
+    const sourceArgs: tsNS.Expression[] =
+      sourceItem.id != null && sourceItem.id !== '' ? [f.createStringLiteral(sourceItem.id)] : [];
     chain = f.createCallExpression(
       f.createPropertyAccessExpression(
         f.createCallExpression(
           f.createPropertyAccessExpression(
-            f.createCallExpression(f.createIdentifier('source'), undefined, []),
+            f.createCallExpression(f.createIdentifier('source'), undefined, sourceArgs),
             f.createIdentifier('state'),
           ),
           undefined,
@@ -348,6 +352,14 @@ function buildSingleDataItem(
       undefined,
       buildOriginArgs(ts, f, sourceItem.origin),
     );
+
+    if (sourceItem._additionalInstructions != null && sourceItem._additionalInstructions !== '') {
+      chain = f.createCallExpression(
+        f.createPropertyAccessExpression(chain, f.createIdentifier('additionalInstructions')),
+        undefined,
+        [f.createStringLiteral(sourceItem._additionalInstructions)],
+      );
+    }
   }
 
   return chain;

package/src/types.ts

@@ -130,6 +130,7 @@ export const createApiOrigin = (endpoint: string, method?: string): ApiOrigin =>
 export const createIntegrationOrigin = (systems: string[]): IntegrationOrigin => ({ type: 'integration', systems });
 
 export interface DataSink {
+  id?: string;
   target: MessageTarget;
   destination: Destination;
   transform?: string;
@@ -138,6 +139,7 @@ export interface DataSink {
 }
 
 export interface DataSource {
+  id?: string;
   target: MessageTarget;
   origin: Origin;
   transform?: string;