@auto-engineer/narrative 0.11.12 → 0.11.14

package/package.json

@@ -19,9 +19,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "0.11.12",
-    "@auto-engineer/id": "0.11.12",
-    "@auto-engineer/message-bus": "0.11.12"
+    "@auto-engineer/file-store": "0.11.14",
+    "@auto-engineer/id": "0.11.14",
+    "@auto-engineer/message-bus": "0.11.14"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -29,12 +29,12 @@
     "eslint-plugin-sort-keys-fix": "^1.1.2",
     "fake-indexeddb": "^6.0.0",
     "tsx": "^4.20.3",
-    "@auto-engineer/cli": "0.11.12"
+    "@auto-engineer/cli": "0.11.14"
   },
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.11.12",
+  "version": "0.11.14",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/commands/export-schema-helper.ts

@@ -12,7 +12,6 @@ const main = async () => {
   debug('Starting export-schema-helper with directory: %s', directory);
 
   try {
-    // Import getFlows from the project's node_modules to ensure we use the same module context
     const getFileStore = getFs as () => Promise<IExtendedFileStore>;
     const fs: IExtendedFileStore = await getFileStore();
     const projectNarrativePath = fs.join(
@@ -24,7 +23,7 @@ const main = async () => {
       'src',
       'getNarratives.js',
     );
-    debug('Importing getFlows from: %s', projectNarrativePath);
+    debug('Importing getNarratives from: %s', projectNarrativePath);
 
     const { pathToFileURL } = await import('url');
     const narrativeModule = (await import(pathToFileURL(projectNarrativePath).href)) as {

package/src/data-narrative-builders.ts

@@ -1,4 +1,4 @@
-import type { DataSinkItem, DataSourceItem, MessageTarget, Integration } from './types';
+import type { DataSinkItem, DataSourceItem, MessageTarget, Integration, DefaultRecord } from './types';
 import { createIntegrationOrigin } from './types';
 import { integrationExportRegistry } from './integration-export-registry';
 
@@ -240,16 +240,44 @@ export class StateSinkBuilder extends MessageTargetBuilder<DataSinkItem> {
 }
 
 // State source builder
-export class StateSourceBuilder extends MessageTargetBuilder<DataSourceItem> {
+export class StateSourceBuilder<S = unknown> extends MessageTargetBuilder<DataSourceItem> {
   constructor(name: string) {
     super();
     this.target = { type: 'State', name };
   }
 
-  fromProjection(name: string, idField: string): ChainableSource {
+  fromSingletonProjection(name: string): ChainableSource {
     const sourceItem: DataSourceItem = {
       target: this.target as MessageTarget,
-      origin: { type: 'projection', name, idField },
+      origin: { type: 'projection', name, singleton: true },
+      __type: 'source' as const,
+      ...(this.instructions != null && this.instructions !== '' && { _additionalInstructions: this.instructions }),
+    };
+    return createChainableSource(sourceItem);
+  }
+
+  fromProjection<
+    K extends S extends import('./types').State<string, infer D extends DefaultRecord, DefaultRecord | undefined>
+      ? keyof D
+      : string,
+  >(name: string, idField: K): ChainableSource {
+    const sourceItem: DataSourceItem = {
+      target: this.target as MessageTarget,
+      origin: { type: 'projection', name, idField: idField as string },
+      __type: 'source' as const,
+      ...(this.instructions != null && this.instructions !== '' && { _additionalInstructions: this.instructions }),
+    };
+    return createChainableSource(sourceItem);
+  }
+
+  fromCompositeProjection<
+    K extends S extends import('./types').State<string, infer D extends DefaultRecord, DefaultRecord | undefined>
+      ? keyof D
+      : string,
+  >(name: string, idFields: K[]): ChainableSource {
+    const sourceItem: DataSourceItem = {
+      target: this.target as MessageTarget,
+      origin: { type: 'projection', name, idField: idFields as string[] },
       __type: 'source' as const,
       ...(this.instructions != null && this.instructions !== '' && { _additionalInstructions: this.instructions }),
     };
@@ -364,14 +392,16 @@ export class DataSinkBuilder {
 }
 
 export class DataSourceBuilder {
-  state(nameOrBuilder: string | BuilderResult): StateSourceBuilder {
+  state<S extends import('./types').State<string, DefaultRecord> = import('./types').State<string, DefaultRecord>>(
+    nameOrBuilder: string | BuilderResult,
+  ): StateSourceBuilder<S> {
     if (typeof nameOrBuilder === 'string') {
-      return new StateSourceBuilder(nameOrBuilder);
+      return new StateSourceBuilder<S>(nameOrBuilder);
     }
 
     // Handle state builder function
     if (isValidBuilderResult(nameOrBuilder) && nameOrBuilder.__messageCategory === 'state') {
-      return new StateSourceBuilder(nameOrBuilder.type);
+      return new StateSourceBuilder<S>(nameOrBuilder.type);
     }
 
     throw new Error('Invalid state parameter - must be a string or state builder function');
@@ -405,7 +435,9 @@ export function typedSink(builderResult: BuilderResult): EventSinkBuilder | Comm
 }
 
 // Type-safe source function that accepts builder results
-export function typedSource(builderResult: BuilderResult): StateSourceBuilder {
+export function typedSource<
+  S extends import('./types').State<string, DefaultRecord> = import('./types').State<string, DefaultRecord>,
+>(builderResult: BuilderResult): StateSourceBuilder<S> {
   if (!isValidBuilderResult(builderResult)) {
     throw new Error('Invalid builder result - must be from State builders');
   }
@@ -414,5 +446,5 @@ export function typedSource(builderResult: BuilderResult): StateSourceBuilder {
     throw new Error('Source can only be created from State builders');
   }
 
-  return new StateSourceBuilder(builderResult.type);
+  return new StateSourceBuilder<S>(builderResult.type);
 }

package/src/getNarratives.specs.ts

@@ -19,7 +19,7 @@ describe('getNarratives', (_mode) => {
     root = path.resolve(__dirname);
   });
   // eslint-disable-next-line complexity
-  it('loads multiple flows and generates correct models', async () => {
+  it('loads multiple narratives and generates correct models', async () => {
     const flows = await getNarratives({ vfs, root: path.resolve(__dirname), pattern, fastFsScan: true });
     const schemas = flows.toModel();
 
@@ -191,7 +191,7 @@ describe('getNarratives', (_mode) => {
     expect(Array.isArray(parsed.integrations)).toBe(true);
   });
 
-  it('should handle flows with integrations', async () => {
+  it('should handle narratives with integrations', async () => {
     const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
     const specsSchema = flows.toModel();
 
@@ -267,7 +267,7 @@ describe('getNarratives', (_mode) => {
     ).toBe(true);
   });
 
-  it('should have ids for flows and slices that have ids', async () => {
+  it('should have ids for narratives and slices that have ids', async () => {
     const flows = await getNarratives({ vfs: vfs, root: root, pattern: /\.(narrative)\.(ts)$/, fastFsScan: true });
 
     const schemas = flows.toModel();
@@ -640,7 +640,7 @@ flow('questionnaires-test', () => {
     }
   });
 
-  it('does not emit empty generics for empty when()', async () => {
+  it('does not emit empty generics or empty when clauses', async () => {
     const flows = await getNarratives({
       vfs,
       root,
@@ -651,13 +651,9 @@ flow('questionnaires-test', () => {
     const model = flows.toModel();
     const code = await modelToNarrative(model);
 
-    // Should not produce `.when<>({})` for empty when-clauses
     expect(code).not.toMatch(/\.when<>\(\{\}\)/);
-
-    // should render empty whens as `.when({})` for empty when-clauses
-    const emptyWhenCount = (code.match(/\.when\(\{}\)/g) ?? []).length;
-    expect(emptyWhenCount).toBeGreaterThanOrEqual(2);
     expect(code).not.toMatch(/\.when<\s*\{\s*}\s*>\(\{}\)/);
+    expect(code).not.toMatch(/\.when\(\{}\)/);
   });
 
   it('should not generate phantom messages with empty names', async () => {
@@ -927,17 +923,7 @@ function validateMixedGivenTypes(example: Example): void {
 }
 
 function validateEmptyWhenClause(example: Example): void {
-  expect(example.when).toBeDefined();
-  expect(typeof example.when === 'object' && !Array.isArray(example.when)).toBe(true);
-  if (typeof example.when === 'object' && !Array.isArray(example.when)) {
-    expect('commandRef' in example.when).toBe(false);
-    expect('eventRef' in example.when).toBe(true);
-    expect('stateRef' in example.when).toBe(false);
-    if ('eventRef' in example.when) {
-      expect(example.when.eventRef).toBe('');
-    }
-    expect(example.when.exampleData).toEqual({});
-  }
+  expect(example.when).toBeUndefined();
 }
 
 function validateThenClause(example: Example): void {
@@ -1246,3 +1232,263 @@ function validateThenEvents(example: unknown): void {
     });
   }
 }
+
+describe('projection DSL methods', () => {
+  it('should generate correct origin for singleton projection', async () => {
+    const memoryVfs = new InMemoryFileStore();
+    const flowContent = `
+import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+
+type TodoAdded = Event<'TodoAdded', { todoId: string; description: string; addedAt: Date }>;
+type TodoListSummary = State<'TodoListSummary', { summaryId: string; totalTodos: number }>;
+
+flow('Projection Test', () => {
+  query('views summary')
+    .server(() => {
+      specs(() => {
+        rule('shows summary', () => {
+          example('summary')
+            .given<TodoAdded>({ todoId: 'todo-001', description: 'Test', addedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<TodoListSummary>({ summaryId: 'main', totalTodos: 1 });
+        });
+      });
+      data([source().state<TodoListSummary>('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    });
+});
+    `;
+
+    await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
+
+    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const model = flows.toModel();
+
+    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    expect(projectionFlow).toBeDefined();
+
+    if (!projectionFlow) return;
+
+    const summarySlice = projectionFlow.slices.find((s) => s.name === 'views summary');
+    expect(summarySlice?.type).toBe('query');
+
+    if (summarySlice?.type !== 'query') return;
+
+    const data = summarySlice.server.data as DataSource[] | undefined;
+    expect(data).toBeDefined();
+    expect(data).toHaveLength(1);
+
+    expect(data?.[0].origin).toMatchObject({
+      type: 'projection',
+      name: 'TodoSummary',
+      singleton: true,
+    });
+
+    expect(data?.[0].origin).not.toHaveProperty('idField');
+  });
+
+  it('should generate correct origin for regular projection with single idField', async () => {
+    const memoryVfs = new InMemoryFileStore();
+    const flowContent = `
+import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+
+type TodoAdded = Event<'TodoAdded', { todoId: string; description: string; addedAt: Date }>;
+type TodoState = State<'TodoState', { todoId: string; description: string; status: string }>;
+
+flow('Projection Test', () => {
+  query('views todo')
+    .server(() => {
+      specs(() => {
+        rule('shows todo', () => {
+          example('todo')
+            .given<TodoAdded>({ todoId: 'todo-001', description: 'Test', addedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<TodoState>({ todoId: 'todo-001', description: 'Test', status: 'pending' });
+        });
+      });
+      data([source().state<TodoState>('TodoState').fromProjection('Todos', 'todoId')]);
+    });
+});
+    `;
+
+    await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
+
+    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const model = flows.toModel();
+
+    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    expect(projectionFlow).toBeDefined();
+
+    if (!projectionFlow) return;
+
+    const todoSlice = projectionFlow.slices.find((s) => s.name === 'views todo');
+    expect(todoSlice?.type).toBe('query');
+
+    if (todoSlice?.type !== 'query') return;
+
+    const data = todoSlice.server.data as DataSource[] | undefined;
+    expect(data).toBeDefined();
+    expect(data).toHaveLength(1);
+
+    expect(data?.[0].origin).toMatchObject({
+      type: 'projection',
+      name: 'Todos',
+      idField: 'todoId',
+    });
+
+    expect(data?.[0].origin).not.toHaveProperty('singleton');
+  });
+
+  it('should generate correct origin for composite projection with multiple idFields', async () => {
+    const memoryVfs = new InMemoryFileStore();
+    const flowContent = `
+import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+
+type UserProjectAssigned = Event<'UserProjectAssigned', { userId: string; projectId: string; assignedAt: Date }>;
+type UserProjectState = State<'UserProjectState', { userId: string; projectId: string; role: string }>;
+
+flow('Projection Test', () => {
+  query('views user project')
+    .server(() => {
+      specs(() => {
+        rule('shows user project', () => {
+          example('user project')
+            .given<UserProjectAssigned>({ userId: 'user-001', projectId: 'proj-001', assignedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<UserProjectState>({ userId: 'user-001', projectId: 'proj-001', role: 'admin' });
+        });
+      });
+      data([source().state<UserProjectState>('UserProjectState').fromCompositeProjection('UserProjects', ['userId', 'projectId'])]);
+    });
+});
+    `;
+
+    await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
+
+    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const model = flows.toModel();
+
+    const projectionFlow = model.narratives.find((f) => f.name === 'Projection Test');
+    expect(projectionFlow).toBeDefined();
+
+    if (!projectionFlow) return;
+
+    const userProjectSlice = projectionFlow.slices.find((s) => s.name === 'views user project');
+    expect(userProjectSlice?.type).toBe('query');
+
+    if (userProjectSlice?.type !== 'query') return;
+
+    const data = userProjectSlice.server.data as DataSource[] | undefined;
+    expect(data).toBeDefined();
+    expect(data).toHaveLength(1);
+
+    expect(data?.[0].origin).toMatchObject({
+      type: 'projection',
+      name: 'UserProjects',
+      idField: ['userId', 'projectId'],
+    });
+
+    expect(data?.[0].origin).not.toHaveProperty('singleton');
+  });
+
+  it('should validate all three projection patterns together', async () => {
+    const memoryVfs = new InMemoryFileStore();
+    const flowContent = `
+import { flow, query, specs, rule, example, data, source, type Event, type State } from '@auto-engineer/narrative';
+
+type TodoAdded = Event<'TodoAdded', { todoId: string; userId: string; projectId: string; description: string; addedAt: Date }>;
+
+type TodoListSummary = State<'TodoListSummary', { summaryId: string; totalTodos: number }>;
+type TodoState = State<'TodoState', { todoId: string; description: string; status: string }>;
+type UserProjectTodos = State<'UserProjectTodos', { userId: string; projectId: string; todos: string[] }>;
+
+flow('All Projection Patterns', () => {
+  query('views summary')
+    .server(() => {
+      specs(() => {
+        rule('shows summary', () => {
+          example('summary')
+            .given<TodoAdded>({ todoId: 'todo-001', userId: 'u1', projectId: 'p1', description: 'Test', addedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<TodoListSummary>({ summaryId: 'main', totalTodos: 1 });
+        });
+      });
+      data([source().state<TodoListSummary>('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    });
+
+  query('views todo')
+    .server(() => {
+      specs(() => {
+        rule('shows todo', () => {
+          example('todo')
+            .given<TodoAdded>({ todoId: 'todo-001', userId: 'u1', projectId: 'p1', description: 'Test', addedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<TodoState>({ todoId: 'todo-001', description: 'Test', status: 'pending' });
+        });
+      });
+      data([source().state<TodoState>('TodoState').fromProjection('Todos', 'todoId')]);
+    });
+
+  query('views user project todos')
+    .server(() => {
+      specs(() => {
+        rule('shows user project todos', () => {
+          example('user project todos')
+            .given<TodoAdded>({ todoId: 'todo-001', userId: 'u1', projectId: 'p1', description: 'Test', addedAt: new Date('2030-01-01T09:00:00Z') })
+            .when({})
+            .then<UserProjectTodos>({ userId: 'u1', projectId: 'p1', todos: ['todo-001'] });
+        });
+      });
+      data([source().state<UserProjectTodos>('UserProjectTodos').fromCompositeProjection('UserProjectTodos', ['userId', 'projectId'])]);
+    });
+});
+    `;
+
+    await memoryVfs.write('/test/projection.narrative.ts', new TextEncoder().encode(flowContent));
+
+    const flows = await getNarratives({ vfs: memoryVfs, root: '/test', pattern, fastFsScan: true });
+    const model = flows.toModel();
+
+    const parseResult = modelSchema.safeParse(model);
+    if (!parseResult.success) {
+      console.error('Schema validation errors:', parseResult.error.format());
+    }
+    expect(parseResult.success).toBe(true);
+
+    const projectionFlow = model.narratives.find((f) => f.name === 'All Projection Patterns');
+    expect(projectionFlow).toBeDefined();
+
+    if (!projectionFlow) return;
+
+    expect(projectionFlow.slices).toHaveLength(3);
+
+    const summarySlice = projectionFlow.slices.find((s) => s.name === 'views summary');
+    if (summarySlice?.type === 'query') {
+      const data = summarySlice.server.data as DataSource[] | undefined;
+      expect(data?.[0].origin).toMatchObject({
+        type: 'projection',
+        name: 'TodoSummary',
+        singleton: true,
+      });
+    }
+
+    const todoSlice = projectionFlow.slices.find((s) => s.name === 'views todo');
+    if (todoSlice?.type === 'query') {
+      const data = todoSlice.server.data as DataSource[] | undefined;
+      expect(data?.[0].origin).toMatchObject({
+        type: 'projection',
+        name: 'Todos',
+        idField: 'todoId',
+      });
+    }
+
+    const userProjectSlice = projectionFlow.slices.find((s) => s.name === 'views user project todos');
+    if (userProjectSlice?.type === 'query') {
+      const data = userProjectSlice.server.data as DataSource[] | undefined;
+      expect(data?.[0].origin).toMatchObject({
+        type: 'projection',
+        name: 'UserProjectTodos',
+        idField: ['userId', 'projectId'],
+      });
+    }
+  });
+});