@auto-engineer/narrative 0.11.11

package/src/narrative-registry.ts

@@ -0,0 +1,65 @@
+import { NarrativeSchema } from './schema';
+import { Narrative } from './index';
+import createDebug from 'debug';
+
+const debug = createDebug('auto:narrative:registry');
+// Set non-error-like colors for debug namespace
+// Colors: 0=gray, 1=red, 2=green, 3=yellow, 4=blue, 5=magenta, 6=cyan
+if ('color' in debug && typeof debug === 'object') {
+  (debug as { color: string }).color = '6'; // cyan
+}
+
+class NarrativeRegistry {
+  private narratives: Narrative[] = [];
+  private instanceId = Math.random().toString(36).substring(7);
+
+  constructor() {
+    debug('Creating new NarrativeRegistry instance: %s', this.instanceId);
+  }
+
+  register(narrative: Narrative) {
+    debug('Registering narrative: %s on instance %s', narrative.name, this.instanceId);
+    debug('Narrative slices: %d', narrative.slices.length);
+    debug('Narratives array before push: %d', this.narratives.length);
+    debug('Array object ID before: %s', this.narratives);
+    const validated = NarrativeSchema.parse(narrative);
+    this.narratives.push(validated);
+    debug('Narratives array after push: %d', this.narratives.length);
+    debug('Array object ID after: %s', this.narratives);
+    debug(
+      'Successfully registered narrative: %s on instance %s, total narratives: %d',
+      narrative.name,
+      this.instanceId,
+      this.narratives.length,
+    );
+  }
+
+  getAllNarratives(): Narrative[] {
+    debug('Getting all narratives, count: %d', this.narratives.length);
+    debug('Registry instance ID: %s', this.instanceId);
+    debug('Array object ID: %s', this.narratives);
+    debug('this === registry? %s', this === registry);
+    if (this.narratives.length > 0) {
+      debug(
+        'Narratives: %o',
+        this.narratives.map((f) => f.name),
+      );
+    }
+    return [...this.narratives];
+  }
+
+  clearAll() {
+    debug('Clearing all narratives on instance %s, current count: %d', this.instanceId, this.narratives.length);
+    if (this.narratives.length > 0) {
+      debug(
+        'Clearing narratives on instance %s: %o',
+        this.instanceId,
+        this.narratives.map((f) => f.name),
+      );
+    }
+    this.narratives = [];
+    debug('Cleared! Instance %s now has %d narratives', this.instanceId, this.narratives.length);
+  }
+}
+
+export const registry = new NarrativeRegistry();

package/src/narrative.ts

@@ -0,0 +1,236 @@
+import { registry } from './narrative-registry';
+import {
+  startNarrative,
+  clearCurrentNarrative,
+  getCurrentSlice,
+  startClientBlock,
+  endClientBlock,
+  startServerBlock,
+  endServerBlock,
+  pushSpec,
+  recordShouldBlock,
+  setSliceData,
+  recordRule,
+  recordExample,
+  recordGivenData,
+  recordAndGivenData,
+  recordWhenData,
+  recordThenData,
+  recordAndThenData,
+} from './narrative-context';
+import type { DataItem } from './types';
+import createDebug from 'debug';
+
+const debug = createDebug('auto:narrative:narrative');
+if ('color' in debug && typeof debug === 'object') {
+  (debug as { color: string }).color = '6';
+} // cyan
+
+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 {
+  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);
+  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);
+}
+
+export const client = (fn: () => void) => {
+  const slice = getCurrentSlice();
+  if (slice) {
+    startClientBlock(slice, '');
+    fn();
+    endClientBlock();
+  }
+};
+
+export const server = (fn: () => void) => {
+  const slice = getCurrentSlice();
+  if (slice) {
+    startServerBlock(slice, '');
+    fn();
+    endServerBlock();
+  }
+};
+
+export const request = (_query: unknown) => ({
+  with: (..._dependencies: unknown[]) => {},
+});
+
+export const should = (description: string) => {
+  recordShouldBlock(description);
+};
+
+export function specs(description: string, fn: () => void): void;
+export function specs(fn: () => void): void;
+export function specs(descriptionOrFn: string | (() => void), fn?: () => void): void {
+  const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
+  const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn!;
+
+  pushSpec(description);
+  recordShouldBlock();
+  callback();
+}
+
+export function rule(description: string, fn: () => void): void;
+export function rule(description: string, id: string, fn: () => void): void;
+export function rule(description: string, idOrFn: string | (() => void), fn?: () => void): void {
+  const id = typeof idOrFn === 'string' ? idOrFn : undefined;
+  const callback = typeof idOrFn === 'function' ? idOrFn : fn;
+
+  if (!callback) {
+    throw new Error(`rule() requires a callback function. Got: ${typeof idOrFn}, ${typeof fn}`);
+  }
+
+  recordRule(description, id);
+  callback();
+}
+
+export const example = (description: string) => {
+  recordExample(description);
+  return createExampleBuilder();
+};
+
+type ExtractData<T> = T extends { data: infer D } ? D : T;
+type ContextFor<T> = Partial<Record<keyof ExtractData<T>, string>>;
+
+function normalizeContext(context?: Partial<Record<string, string>>): Record<string, string> | undefined {
+  if (!context) return undefined;
+
+  const filtered: Record<string, string> = {};
+  for (const [key, value] of Object.entries(context)) {
+    if (value !== undefined) {
+      filtered[key] = value;
+    }
+  }
+
+  return Object.keys(filtered).length > 0 ? filtered : undefined;
+}
+
+interface TypedExampleBuilder {
+  given<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenBuilder<T>;
+  when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedWhenBuilder<W>;
+}
+
+interface TypedGivenBuilder<G> {
+  and<U>(data: ExtractData<U> | ExtractData<U>[], context?: ContextFor<U>): TypedGivenBuilder<G | U>;
+  when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedGivenWhenBuilder<G, W>;
+}
+
+interface TypedWhenBuilder<W> {
+  then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedThenBuilder<W, T>;
+}
+
+interface TypedGivenWhenBuilder<G, W> {
+  then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, W, T>;
+}
+
+interface TypedThenBuilder<W, T> {
+  and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedThenBuilder<W, T | A>;
+}
+
+interface TypedGivenThenBuilder<G, W, T> {
+  and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedGivenThenBuilder<G, W, T | A>;
+}
+
+function createThenBuilder<W, T>(): TypedThenBuilder<W, T> {
+  return {
+    and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedThenBuilder<W, T | A> {
+      const andItems = Array.isArray(data) ? data : [data];
+      recordAndThenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
+      return createThenBuilder<W, T | A>();
+    },
+  };
+}
+
+function createGivenBuilder<G>(): TypedGivenBuilder<G> {
+  return {
+    and<U>(data: ExtractData<U> | ExtractData<U>[], context?: ContextFor<U>): TypedGivenBuilder<G | U> {
+      const andItems = Array.isArray(data) ? data : [data];
+      recordAndGivenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
+      return createGivenBuilder<G | U>();
+    },
+    when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedGivenWhenBuilder<G, W> {
+      const whenData = Array.isArray(data) ? data : [data];
+      recordWhenData(
+        whenData.length === 1 ? whenData[0] : whenData,
+        normalizeContext(context as Partial<Record<string, string>>),
+      );
+      return {
+        then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, W, T> {
+          const thenItems = Array.isArray(data) ? data : [data];
+          recordThenData(thenItems, normalizeContext(context as Partial<Record<string, string>>));
+          return {
+            and<A>(
+              data: ExtractData<A> | ExtractData<A>[],
+              context?: ContextFor<A>,
+            ): TypedGivenThenBuilder<G, W, T | A> {
+              const andItems = Array.isArray(data) ? data : [data];
+              recordAndThenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
+              return createThenBuilder<W, T | A>() as TypedGivenThenBuilder<G, W, T | A>;
+            },
+          };
+        },
+      };
+    },
+  };
+}
+
+function createExampleBuilder(): TypedExampleBuilder {
+  return {
+    given<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenBuilder<T> {
+      const items = Array.isArray(data) ? data : [data];
+      recordGivenData(items, normalizeContext(context as Partial<Record<string, string>>));
+      return createGivenBuilder<T>();
+    },
+    when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedWhenBuilder<W> {
+      const whenData = Array.isArray(data) ? data : [data];
+      recordWhenData(
+        whenData.length === 1 ? whenData[0] : whenData,
+        normalizeContext(context as Partial<Record<string, string>>),
+      );
+      return {
+        then<Z>(data: ExtractData<Z> | ExtractData<Z>[], context?: ContextFor<Z>): TypedThenBuilder<W, Z> {
+          const thenItems = Array.isArray(data) ? data : [data];
+          recordThenData(thenItems, normalizeContext(context as Partial<Record<string, string>>));
+          return createThenBuilder<W, Z>();
+        },
+      };
+    },
+  };
+}
+
+export const SliceType = {
+  COMMAND: 'command' as const,
+  QUERY: 'query' as const,
+  REACT: 'react' as const,
+} as const;
+
+export interface SliceTypeValueInterface {
+  readonly value: 'command' | 'query' | 'react';
+}
+
+export function data(items: DataItem[]): void {
+  const slice = getCurrentSlice();
+  if (!slice) throw new Error('No active slice for data configuration');
+
+  const sliceType = slice.type;
+
+  if (sliceType === SliceType.QUERY) {
+    const hasSink = items.some((item) => '__type' in item && item.__type === 'sink');
+    if (hasSink) {
+      throw new Error('Query slices cannot have data sinks, only sources');
+    }
+  }
+
+  setSliceData(items);
+}
+
+export { narrative as flow };

package/src/samples/items.flow.ts

@@ -0,0 +1,90 @@
+import { data, flow, should, specs, rule, example } from '../narrative';
+import { command, query } from '../fluent-builder';
+import gql from 'graphql-tag';
+import { source } from '../data-narrative-builders';
+import { type Event, type Command, type State } from '../types';
+
+type ItemCreated = Event<
+  'ItemCreated',
+  {
+    id: string;
+    description: string;
+    addedAt: Date;
+  }
+>;
+
+type CreateItem = Command<
+  'CreateItem',
+  {
+    itemId: string;
+    description: string;
+  }
+>;
+
+type AvailableItems = State<
+  'AvailableItems',
+  {
+    id: string;
+    description: string;
+  }
+>;
+
+flow('items', () => {
+  command('Create item')
+    .stream('item-${id}')
+    .client(() => {
+      specs('A form that allows users to add items', () => {
+        should('have fields for id and description');
+      });
+    })
+    .server(() => {
+      specs('User can add an item', () => {
+        rule('Valid items should be created successfully', () => {
+          example('User creates a new item with valid data')
+            .when<CreateItem>({
+              itemId: 'item_123',
+              description: 'A new item',
+            })
+            .then<ItemCreated>({
+              id: 'item_123',
+              description: 'A new item',
+              addedAt: new Date('2024-01-15T10:00:00Z'),
+            });
+        });
+      });
+    });
+
+  query('view items')
+    .request(gql`
+      query items($itemId: String!) {
+        items(itemId: $itemId) {
+          id
+          description
+        }
+      }
+    `)
+    .client(() => {
+      specs('view Items Screen', () => {
+        should('display all items');
+        should('show quantity selectors for each item');
+        should('allow removing items');
+      });
+    })
+    .server(() => {
+      data([source().state('items').fromProjection('ItemsProjection', 'itemId')]);
+      specs('Suggested items are available for viewing', () => {
+        rule('Items should be available for viewing after creation', () => {
+          example('Item becomes available after creation event')
+            .when<ItemCreated>({
+              id: 'item_123',
+              description: 'A new item',
+              addedAt: new Date('2024-01-15T10:00:00Z'),
+            })
+            .then<AvailableItems>({
+              id: 'item_123',
+              description: 'A new item',
+            });
+        });
+      });
+    });
+});

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

@@ -0,0 +1,70 @@
+import { flow, specs, rule, example } from '../narrative';
+import { query } from '../fluent-builder';
+import { type Event, type State } from '../types';
+
+type ConfigState = State<
+  'ConfigState',
+  {
+    configId: string;
+    maxItems: number;
+  }
+>;
+
+type ItemAdded = Event<
+  'ItemAdded',
+  {
+    itemId: string;
+    addedAt: Date;
+  }
+>;
+
+type SystemInitialized = Event<
+  'SystemInitialized',
+  {
+    systemId: string;
+    timestamp: Date;
+  }
+>;
+
+type SystemStatus = State<
+  'SystemStatus',
+  {
+    systemId: string;
+    itemCount: number;
+    status: 'ready' | 'full';
+  }
+>;
+
+flow('Mixed Given Types', 'FLOW-MGT', () => {
+  query('system status check', 'SLICE-MGT-001')
+    .client(() => {})
+    .server(() => {
+      specs('System status specs', () => {
+        rule('system reaches full capacity when configured limit is reached', 'RULE-MGT-001', () => {
+          example('system with 2 items reaches max of 2')
+            .given<ConfigState>({
+              configId: 'config-001',
+              maxItems: 2,
+            })
+            .and<SystemInitialized>({
+              systemId: 'system-001',
+              timestamp: new Date('2024-01-01T10:00:00Z'),
+            })
+            .and<ItemAdded>({
+              itemId: 'item-001',
+              addedAt: new Date('2024-01-01T10:01:00Z'),
+            })
+            .and<ItemAdded>({
+              itemId: 'item-002',
+              addedAt: new Date('2024-01-01T10:02:00Z'),
+            })
+            .when({}) // empty when clause
+            .then<SystemStatus>({
+              systemId: 'system-001',
+              itemCount: 2,
+              status: 'full',
+            });
+        });
+      });
+    });
+});

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

@@ -0,0 +1,57 @@
+import { flow, should, specs, rule, example } from '../narrative';
+import { command } from '../fluent-builder';
+
+export interface OrderPlaced {
+  type: 'OrderPlaced';
+  data: {
+    orderId: string;
+    productId: string;
+    quantity: number;
+    placedAt: Date;
+  };
+}
+
+export interface PlaceOrderFlow {
+  type: 'PlaceOrder';
+  data: {
+    productId: string;
+    quantity: number;
+  };
+}
+
+export interface OrderSummary {
+  type: 'OrderSummary';
+  data: {
+    orderId: string;
+    productId: string;
+    quantity: number;
+  };
+}
+
+flow('Place order', () => {
+  command('Submit order')
+    .stream('order-${orderId}')
+    .client(() => {
+      specs('Order submission form', () => {
+        should('allow product selection');
+        should('allow quantity input');
+      });
+    })
+    .server(() => {
+      specs('User submits a new order', () => {
+        rule('Valid orders should be processed successfully', () => {
+          example('User places order for available product')
+            .when<PlaceOrderFlow>({
+              productId: 'product_789',
+              quantity: 3,
+            })
+            .then<OrderPlaced>({
+              orderId: 'order_001',
+              productId: 'product_789',
+              quantity: 3,
+              placedAt: new Date('2024-01-20T10:00:00Z'),
+            });
+        });
+      });
+    });
+});