@auto-engineer/narrative 1.139.0 → 1.140.0

package/src/narrative.ts

@@ -1,10 +1,10 @@
 import createDebug from 'debug';
 import type { DataTargetItem } from './data-narrative-builders';
 import {
-  clearCurrentNarrative,
+  clearCurrentScene,
   endClientBlock,
   endServerBlock,
-  getCurrentSlice,
+  getCurrentMoment,
   popDescribe,
   pushDescribe,
   pushSpec,
@@ -13,9 +13,9 @@ import {
   recordIt,
   recordRule,
   recordStep,
-  setSliceData,
+  setMomentData,
   startClientBlock,
-  startNarrative,
+  startScene,
   startServerBlock,
 } from './narrative-context';
 import { registry } from './narrative-registry';
@@ -26,35 +26,35 @@ if ('color' in debug && typeof debug === 'object') {
   (debug as { color: string }).color = '6';
 }
 
-export function narrative(name: string, fn: () => void): void;
-export function narrative(name: string, id: string, fn: () => void): void;
-export function narrative(name: string, idOrFn: string | (() => void), fn?: () => void): void {
+export function scene(name: string, fn: () => void): void;
+export function scene(name: string, id: string, fn: () => void): void;
+export function scene(name: string, idOrFn: string | (() => void), fn?: () => void): void {
   const id = typeof idOrFn === 'string' ? idOrFn : undefined;
   const callback = typeof idOrFn === 'function' ? idOrFn : fn!;
 
-  debug('Starting narrative definition: %s', name);
-  const narrativeObj = startNarrative(name, id);
-  debug('Executing narrative function for: %s', name);
+  debug('Starting scene definition: %s', name);
+  const sceneObj = startScene(name, id);
+  debug('Executing scene function for: %s', name);
   callback();
-  debug('Narrative function executed, registering narrative: %s with %d slices', name, narrativeObj.slices.length);
-  registry.register(narrativeObj);
-  clearCurrentNarrative();
-  debug('Narrative registered and context cleared: %s', name);
+  debug('Scene function executed, registering scene: %s with %d moments', name, sceneObj.moments.length);
+  registry.register(sceneObj);
+  clearCurrentScene();
+  debug('Scene registered and context cleared: %s', name);
 }
 
 export const client = (fn: () => void) => {
-  const slice = getCurrentSlice();
-  if (slice) {
-    startClientBlock(slice);
+  const moment = getCurrentMoment();
+  if (moment) {
+    startClientBlock(moment);
     fn();
     endClientBlock();
   }
 };
 
 export const server = (fn: () => void) => {
-  const slice = getCurrentSlice();
-  if (slice) {
-    startServerBlock(slice, '');
+  const moment = getCurrentMoment();
+  if (moment) {
+    startServerBlock(moment, '');
     fn();
     endServerBlock();
   }
@@ -69,8 +69,8 @@ export function describe(title: string, fn: () => void): void;
 export function describe(title: string, id: string, fn: () => void): void;
 export function describe(titleOrFn: string | (() => void), idOrFn?: string | (() => void), fn?: () => void): void {
   if (typeof titleOrFn === 'function') {
-    const slice = getCurrentSlice();
-    const inferredTitle = slice?.name ?? '';
+    const moment = getCurrentMoment();
+    const inferredTitle = moment?.name ?? '';
     pushDescribe(inferredTitle, undefined);
     titleOrFn();
     popDescribe();
@@ -205,34 +205,32 @@ export function thenError(errorType: ErrorType, message?: string): void {
   recordErrorStep(errorType, message);
 }
 
-export const SliceType = {
+export const MomentType = {
   COMMAND: 'command' as const,
   QUERY: 'query' as const,
   REACT: 'react' as const,
 } as const;
 
-export interface SliceTypeValueInterface {
+export interface MomentTypeValueInterface {
   readonly value: 'command' | 'query' | 'react';
 }
 
 export function data(config: Data | (DataItem | DataTargetItem)[]): void {
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice for data configuration');
+  const moment = getCurrentMoment();
+  if (!moment) throw new Error('No active moment for data configuration');
 
   // Normalize to Data structure - cast needed since DataItem includes __type discriminator
-  // which gets stripped by setSliceData
+  // which gets stripped by setMomentData
   const dataConfig: Data = Array.isArray(config) ? { items: config as unknown as Data['items'] } : config;
 
-  const sliceType = slice.type;
+  const momentType = moment.type;
 
-  if (sliceType === SliceType.QUERY) {
+  if (momentType === MomentType.QUERY) {
     const hasSink = dataConfig.items.some((item) => '__type' in item && item.__type === 'sink');
     if (hasSink) {
-      throw new Error('Query slices cannot have data sinks, only sources');
+      throw new Error('Query moments cannot have data sinks, only sources');
     }
   }
 
-  setSliceData(dataConfig);
+  setMomentData(dataConfig);
 }
-
-export { narrative as flow };

package/src/parse-graphql-request.specs.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import { parseGraphQlRequest, parseSliceRequest } from './parse-graphql-request';
+import { parseGraphQlRequest, parseMomentRequest } from './parse-graphql-request';
 
 describe('parseGraphQlRequest', () => {
   it('parses a query operation', () => {
@@ -63,23 +63,23 @@ describe('parseGraphQlRequest', () => {
   });
 });
 
-describe('parseSliceRequest', () => {
+describe('parseMomentRequest', () => {
   it('returns parsed operation when request is present', () => {
     const slice = {
       request: `query GetItems { items { id } }`,
     };
 
-    expect(parseSliceRequest(slice)).toEqual({
+    expect(parseMomentRequest(slice)).toEqual({
       operationName: 'items',
       args: [],
     });
   });
 
   it('returns undefined when request is absent', () => {
-    expect(parseSliceRequest({})).toEqual(undefined);
+    expect(parseMomentRequest({})).toEqual(undefined);
   });
 
   it('returns undefined when request is undefined', () => {
-    expect(parseSliceRequest({ request: undefined })).toEqual(undefined);
+    expect(parseMomentRequest({ request: undefined })).toEqual(undefined);
   });
 });

package/src/parse-graphql-request.ts

@@ -91,10 +91,10 @@ export function parseGraphQlRequest(request: string): ParsedGraphQlOperation {
   };
 }
 
-export function parseSliceRequest(slice: {
+export function parseMomentRequest(moment: {
   request?: string;
   [key: string]: unknown;
 }): ParsedGraphQlOperation | undefined {
-  if (slice.request == null) return undefined;
-  return parseGraphQlRequest(slice.request);
+  if (moment.request == null) return undefined;
+  return parseGraphQlRequest(moment.request);
 }

package/src/samples/items.narrative.ts

@@ -1,7 +1,7 @@
 import gql from 'graphql-tag';
 import { source } from '../data-narrative-builders';
 import { command, query } from '../fluent-builder';
-import { data, describe, example, flow, it, rule, specs } from '../narrative';
+import { data, describe, example, it, rule, scene, specs } from '../narrative';
 import type { Command, Event, State } from '../types';
 
 type ItemCreated = Event<
@@ -29,7 +29,7 @@ type AvailableItems = State<
   }
 >;
 
-flow('items', () => {
+scene('items', () => {
   command('Create item')
     .stream('item-${id}')
     .client(() => {

package/src/samples/mixed-given-types.narrative.ts

@@ -1,5 +1,5 @@
 import { query } from '../fluent-builder';
-import { example, flow, rule, specs } from '../narrative';
+import { example, rule, scene, specs } from '../narrative';
 import type { Event, State } from '../types';
 
 type ConfigState = State<
@@ -35,7 +35,7 @@ type SystemStatus = State<
   }
 >;
 
-flow('Mixed Given Types', 'FLOW-MGT', () => {
+scene('Mixed Given Types', 'FLOW-MGT', () => {
   query('system status check', 'SLICE-MGT-001')
     .client(() => {})
     .server(() => {

package/src/samples/place-order.narrative.ts

@@ -1,5 +1,5 @@
 import { command } from '../fluent-builder';
-import { describe, example, flow, it, rule, specs } from '../narrative';
+import { describe, example, it, rule, scene, specs } from '../narrative';
 
 export interface OrderPlaced {
   type: 'OrderPlaced';
@@ -28,7 +28,7 @@ export interface OrderSummary {
   };
 }
 
-flow('Place order', () => {
+scene('Place order', () => {
   command('Submit order')
     .stream('order-${orderId}')
     .client(() => {

package/src/samples/questionnaires.narrative.ts

@@ -6,12 +6,12 @@ import {
   type Event,
   example,
   experience,
-  flow,
   gql,
   it,
   query,
   rule,
   type State,
+  scene,
   sink,
   source,
   specs,
@@ -95,7 +95,7 @@ type QuestionnaireProgress = State<
   }
 >;
 
-flow('Questionnaires', 'Q9m2Kp4Lx', () => {
+scene('Questionnaires', 'Q9m2Kp4Lx', () => {
   experience('Homepage', 'H1a4Bn6Cy').client(() => {
     it('show a hero section with a welcome message');
     it('allow user to start the questionnaire');

package/src/samples/seasonal-assistant.schema.json

@@ -1,9 +1,9 @@
 {
   "variant": "specs",
-  "narratives": [
+  "scenes": [
     {
       "name": "Seasonal Assistant",
-      "slices": [
+      "moments": [
         {
           "name": "enters shopping criteria into assistant",
           "type": "command",

package/src/samples/test-with-ids.narrative.ts

@@ -1,5 +1,5 @@
 import { command, query, react } from '../fluent-builder';
-import { example, flow, rule, specs, thenError } from '../narrative';
+import { example, rule, scene, specs, thenError } from '../narrative';
 import type { Command, Event, State } from '../types';
 
 type TestItemCreated = Event<
@@ -35,7 +35,7 @@ type SendNotification = Event<
   }
 >;
 
-flow('Test Flow with IDs', 'FLOW-001', () => {
+scene('Test Flow with IDs', 'FLOW-001', () => {
   command('Create test item', 'SLICE-001')
     .client(() => {})
     .server(() => {