eventmodeler 0.6.0 → 0.6.2

package/dist/slices/guide/guides/codegen.js

@@ -1,339 +0,0 @@
-export const meta = {
-    name: 'codegen',
-    description: 'Build code generators that consume eventmodeler codegen output',
-};
-export const content = `
-# Building Code Generators for Event Models
-
-The \`eventmodeler codegen\` commands output structured JSON that code generators can consume:
-- \`eventmodeler codegen slice "<slice-name>"\` for per-slice generation
-- \`eventmodeler codegen events [--chapter "<chapter-name>"]\` for deduplicated event scaffolding across slices
-
-## The Codegen Pipeline
-
-Per-slice pipeline:
-
-\`\`\`
-eventmodeler codegen slice "Place Order" | your-generator > output-files
-\`\`\`
-
-Events-only pipeline:
-
-\`\`\`
-eventmodeler codegen events --chapter "Register Products" | your-events-generator > events.kt
-\`\`\`
-
-Your generator receives JSON on stdin and produces code files.
-
-## Understanding the Input
-
-Run codegen to see what you'll receive:
-
-\`\`\`bash
-eventmodeler codegen slice "Place Order"
-\`\`\`
-
-### Top-Level Structure
-
-\`\`\`json
-{
-  "sliceType": "STATE_CHANGE | STATE_VIEW | AUTOMATION",
-  "slice": { "id": "...", "name": "Place Order" },
-  "chapter": { "name": "...", "hierarchy": ["Parent", "Child"] },
-  "elements": { ... },
-  "inboundDependencies": [ ... ],
-  "internalFlows": [ ... ],
-  "scenarios": [ ... ]
-}
-\`\`\`
-
-### Events-Only Structure (\`codegen events\`)
-
-\`\`\`json
-{
-  "chapter": { "name": "Register Products", "parent": { "name": "Configuration" } },
-  "sliceCount": 4,
-  "eventCount": 9,
-  "slices": [
-    { "id": "...", "name": "Place Product", "sliceType": "STATE_CHANGE" }
-  ],
-  "events": [
-    {
-      "id": "...",
-      "name": "ProductRegistered",
-      "fields": [ ... ],
-      "aggregate": "Product",
-      "sourceSlices": ["Place Product", "Import Product"]
-    }
-  ]
-}
-\`\`\`
-
-Use \`codegen events\` when generating shared event artifacts in one pass (for a chapter or entire model).
-
-### Slice Types and What to Generate
-
-| sliceType | Components | Generate |
-|-----------|------------|----------|
-| \`STATE_CHANGE\` | Screen, Command, Event | API endpoint, command handler, event, tests |
-| \`STATE_VIEW\` | ReadModel | Projection/denormalizer, query endpoint |
-| \`AUTOMATION\` | Processor, ReadModel, Command, Event | Event handler, saga/process manager |
-
-## Building a Generator: Step by Step
-
-### 1. Parse the Input
-
-\`\`\`typescript
-// generator.ts
-import { stdin } from 'process';
-
-interface CodegenInput {
-  sliceType: 'STATE_CHANGE' | 'STATE_VIEW' | 'AUTOMATION';
-  slice: { id: string; name: string };
-  elements: {
-    commands: Array<{ name: string; fields: Field[] }>;
-    events: Array<{ name: string; fields: Field[]; aggregate?: string }>;
-    readModels: Array<{ name: string; fields: Field[] }>;
-    screens: Array<{ name: string; fields: Field[] }>;
-    processors: Array<{ name: string }>;
-  };
-  inboundDependencies: InboundDependency[];
-  internalFlows: Flow[];
-  scenarios: Scenario[];
-}
-
-async function readInput(): Promise<CodegenInput> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of stdin) {
-    chunks.push(chunk);
-  }
-  return JSON.parse(Buffer.concat(chunks).toString());
-}
-\`\`\`
-
-### 2. Route by Slice Type
-
-\`\`\`typescript
-async function main() {
-  const input = await readInput();
-
-  switch (input.sliceType) {
-    case 'STATE_CHANGE':
-      generateStateChangeSlice(input);
-      break;
-    case 'STATE_VIEW':
-      generateStateViewSlice(input);
-      break;
-    case 'AUTOMATION':
-      generateAutomationSlice(input);
-      break;
-  }
-}
-\`\`\`
-
-### 3. Generate from Elements
-
-**Commands → DTOs/Request types:**
-\`\`\`typescript
-function generateCommand(cmd: Command): string {
-  const fields = cmd.fields
-    .map(f => \`  \${f.name}: \${mapType(f.type)}\${f.optional ? ' | null' : ''};\`)
-    .join('\\n');
-
-  return \`export interface \${cmd.name}Command {\\n\${fields}\\n}\`;
-}
-\`\`\`
-
-**Events → Event types with metadata:**
-\`\`\`typescript
-function generateEvent(evt: Event): string {
-  const fields = evt.fields.map(f => {
-    const generated = f.generated ? ' // generated' : '';
-    return \`  \${f.name}: \${mapType(f.type)};\${generated}\`;
-  }).join('\\n');
-
-  return \`export interface \${evt.name}Event {\\n  type: '\${evt.name}';\\n\${fields}\\n}\`;
-}
-\`\`\`
-
-**ReadModels → Projection types:**
-\`\`\`typescript
-function generateReadModel(rm: ReadModel): string {
-  const fields = rm.fields
-    .map(f => \`  \${f.name}: \${mapType(f.type)}\${f.optional ? ' | null' : ''};\`)
-    .join('\\n');
-
-  return \`export interface \${rm.name} {\\n\${fields}\\n}\`;
-}
-\`\`\`
-
-### 4. Use Field Mappings for Projections
-
-The \`inboundDependencies\` show how external events map to read model fields:
-
-\`\`\`typescript
-function generateProjection(input: CodegenInput): string {
-  const rm = input.elements.readModels[0];
-  const handlers: string[] = [];
-
-  for (const dep of input.inboundDependencies) {
-    if (dep.target.name === rm.name) {
-      const mappings = dep.fieldMappings
-        .map(m => \`    state.\${m.targetFieldName} = event.\${m.sourceFieldName};\`)
-        .join('\\n');
-
-      handlers.push(\`
-  on\${dep.source.name}(state: \${rm.name}, event: \${dep.source.name}Event) {
-\${mappings}
-  }\`);
-    }
-  }
-
-  return \`export class \${rm.name}Projection {\\n\${handlers.join('\\n')}\\n}\`;
-}
-\`\`\`
-
-### 5. Generate Tests from Scenarios
-
-Scenarios are BDD specs that become tests. There are two scenario patterns:
-
-**State-Change Scenarios** (whenCommand → then events/error):
-- \`whenCommand\`: The command being tested
-- \`then.type: 'events'\`: Expected events produced
-- \`then.type: 'error'\`: Expected error
-
-**Automation Scenarios** (whenEvents → then command):
-- \`whenEvents\`: The event(s) that trigger the processor
-- \`then.type: 'command'\`: The command the processor should issue
-
-\`\`\`typescript
-function generateTests(input: CodegenInput): string {
-  return input.scenarios.map(scenario => {
-    const givenSetup = scenario.given
-      .map(g => \`    await given(new \${g.eventName}(\${JSON.stringify(g.fieldValues)}));\`)
-      .join('\\n');
-
-    // State-change scenarios: when is a command
-    let whenAction = '';
-    if (scenario.whenCommand) {
-      whenAction = \`    await when(new \${scenario.whenCommand.commandName}(\${JSON.stringify(scenario.whenCommand.fieldValues)}));\`;
-    }
-    // Automation scenarios: when is event(s)
-    if (scenario.whenEvents?.length > 0) {
-      whenAction = scenario.whenEvents
-        .map(e => \`    await whenEvent(new \${e.eventName}(\${JSON.stringify(e.fieldValues)}));\`)
-        .join('\\n');
-    }
-
-    let thenAssertion: string;
-    if (scenario.then.type === 'events') {
-      const expected = scenario.then.expectedEvents!
-        .map(e => \`new \${e.eventName}(\${JSON.stringify(e.fieldValues)})\`)
-        .join(', ');
-      thenAssertion = \`    await thenExpect([\${expected}]);\`;
-    } else if (scenario.then.type === 'command') {
-      const cmd = scenario.then.expectedCommand!;
-      thenAssertion = \`    await thenExpectCommand(new \${cmd.commandName}(\${JSON.stringify(cmd.fieldValues)}));\`;
-    } else if (scenario.then.type === 'error') {
-      thenAssertion = \`    await thenExpectError('\${scenario.then.errorType}', '\${scenario.then.errorMessage}');\`;
-    } else {
-      thenAssertion = \`    await thenExpectState(\${JSON.stringify(scenario.then.expectedFieldValues)});\`;
-    }
-
-    return \`
-  test('\${scenario.name}', async () => {
-\${givenSetup}
-\${whenAction}
-\${thenAssertion}
-  });\`;
-  }).join('\\n');
-}
-\`\`\`
-
-## Type Mapping
-
-Map event model types to your target language:
-
-\`\`\`typescript
-function mapType(fieldType: string, isList?: boolean): string {
-  const baseType = {
-    'UUID': 'string',
-    'String': 'string',
-    'Int': 'number',
-    'Long': 'number',
-    'Double': 'number',
-    'Decimal': 'Decimal',  // or 'number' or 'BigNumber'
-    'Boolean': 'boolean',
-    'Date': 'Date',
-    'DateTime': 'Date',
-    'Custom': 'object',  // handle subfields separately
-  }[fieldType] ?? 'unknown';
-
-  return isList ? \`\${baseType}[]\` : baseType;
-}
-\`\`\`
-
-For Custom types with subfields, generate inline or separate types:
-
-\`\`\`typescript
-function generateFieldType(field: Field): string {
-  if (field.type === 'Custom' && field.subfields) {
-    const nested = field.subfields
-      .map(sf => \`\${sf.name}: \${mapType(sf.type)}\`)
-      .join('; ');
-    const type = \`{ \${nested} }\`;
-    return field.list ? \`Array<\${type}>\` : type;
-  }
-  return mapType(field.type, field.list);
-}
-\`\`\`
-
-## Handling Aggregates
-
-Events include their aggregate name when inside one:
-
-\`\`\`typescript
-function generateEventHandler(input: CodegenInput): string {
-  const event = input.elements.events[0];
-  const aggregate = event.aggregate;
-
-  if (aggregate) {
-    return \`
-export class \${aggregate}Aggregate {
-  apply(event: \${event.name}Event) {
-    // Update aggregate state from event
-  }
-}\`;
-  }
-  // ...
-}
-\`\`\`
-
-## Running Your Generator
-
-\`\`\`bash
-# Single slice
-eventmodeler codegen slice "Place Order" | node generator.js
-
-# All slices (bash loop)
-for slice in $(eventmodeler list slices | node -e 'const fs=require("fs");const d=JSON.parse(fs.readFileSync(0,"utf8"));for(const s of (d.slices||[])) console.log(s.name)'); do
-  eventmodeler codegen slice "$slice" | node generator.js
-done
-
-# Chapter-scoped events scaffolding
-eventmodeler codegen events --chapter "Register Products" | node generate-events.js
-
-# Whole-model events scaffolding
-eventmodeler codegen events | node generate-events.js
-\`\`\`
-
-## Best Practices
-
-1. **Handle all slice types** - Your generator should handle STATE_CHANGE, STATE_VIEW, and AUTOMATION
-2. **Use field mappings** - They define the projection logic between events and read models
-3. **Generate tests from scenarios** - Scenarios are executable specifications
-4. **Respect field attributes** - \`generated\` fields don't need input, \`optional\` fields can be null
-5. **Use aggregate info** - Events in aggregates should be handled by that aggregate
-6. **Handle Custom types recursively** - Subfields can themselves be Custom types
-7. **Make it idempotent** - Running twice should produce the same output
-`;

package/dist/slices/guide/guides/connect-slices.js

@@ -1,202 +0,0 @@
-export const meta = {
-    name: 'connect-slices',
-    description: 'Connect slices with flows to show how data moves through the system',
-};
-export const content = `
-# Connecting Slices
-
-After creating slices, you need to connect them with flows to show how data moves through the system. This creates the complete picture of your event model.
-
-## The Data Flow Pattern
-
-In event modeling, data flows in a specific pattern:
-
-\`\`\`
-[State-Change Slice]              [State-View Slice]              [Next Slice]
-
-     Screen                            ReadModel                     Screen
-       |                                  ^  |                         ^
-       v                                  |  v                         |
-    Command                               |  - - - - - - - - - - - - - +
-       |                                  |                    OR
-       v                                  |                   Processor
-     Event  - - - - - - - - - - - - - - - +                      ^
-                                                                 |
-                                          + - - - - - - - - - - -+
-\`\`\`
-
-**Key flows:**
-1. **Event → ReadModel**: Events project their data into read models
-2. **ReadModel → Screen**: Read models provide data to screens (for user viewing)
-3. **ReadModel → Processor**: Read models provide data to processors (for automation)
-
-Within-slice flows (Screen→Command, Command→Event, Processor→Command) are created automatically when you create a slice.
-
-## Command Syntax
-
-\`\`\`bash
-eventmodeler create flow --from "<source>" --to "<target>"
-\`\`\`
-
-## Valid Flow Combinations
-
-| Source | Target | Use Case |
-|--------|--------|----------|
-| Event | ReadModel | Project event data into a view |
-| ReadModel | Screen | Provide data for user display |
-| ReadModel | Processor | Provide data for automation logic |
-
-## Workflow: Connecting a Complete Model
-
-### 1. Create Your Slices First
-
-Build each slice by adding fields to its elements and connecting them with internal flows.
-
-### 2. Connect Events to Read Models
-
-Events project their data into read models:
-
-\`\`\`bash
-# OrderPlaced feeds into OrderStatus view
-eventmodeler create flow --from "OrderPlaced" --to "OrderStatus"
-
-# OrderFulfilled also updates OrderStatus view
-eventmodeler create flow --from "OrderFulfilled" --to "OrderStatus"
-\`\`\`
-
-### 3. Connect Events to Automation Read Models
-
-Automation slices have their own internal read model. Connect external events to feed it:
-
-\`\`\`bash
-# OrderPlaced feeds the automation's read model
-eventmodeler create flow --from "OrderPlaced" --to "OrderReadyToFulfill"
-
-# PaymentReceived also feeds the automation's read model
-eventmodeler create flow --from "PaymentReceived" --to "OrderReadyToFulfill"
-\`\`\`
-
-Note: The flow from ReadModel → Processor is internal to the automation slice and created automatically.
-
-### 4. Connect Read Models to Screens
-
-State-view read models provide data to screens:
-
-\`\`\`bash
-# OrderStatus provides data to a screen in another slice
-eventmodeler create flow --from "OrderStatus" --to "Order Details Screen"
-\`\`\`
-
-### 5. Set Up Field Mappings
-
-After creating flows, map the fields:
-
-\`\`\`bash
-eventmodeler map fields --from "OrderPlaced" --to "OrderStatus" '[
-  {"from": "orderId", "to": "orderId"},
-  {"from": "customerId", "to": "customerId"},
-  {"from": "placedAt", "to": "placedAt"}
-]'
-\`\`\`
-
-### 6. Verify Completeness
-
-Check that all flows have proper field mappings:
-
-\`\`\`bash
-eventmodeler show model-completeness
-eventmodeler show completeness "OrderStatus"
-\`\`\`
-
-## Handling Duplicate Names with IDs
-
-When multiple elements share the same name (e.g., linked copies of events or read models), you'll need to use element IDs instead of names.
-
-### Finding Element IDs
-
-\`\`\`bash
-# List events with their IDs
-eventmodeler list events
-# Output includes id and name for each event, e.g.:
-# [{"id": "abc12345-...", "name": "OrderPlaced", "fields": 4},
-#  {"id": "def67890-...", "name": "OrderPlaced", "fields": 4}]
-\`\`\`
-
-### Using IDs in Commands
-
-Prefix the ID (or ID prefix) with \`id:\`:
-
-\`\`\`bash
-# Create flow using ID prefix (first 8 characters is usually enough)
-eventmodeler create flow --from "id:abc12345" --to "OrderStatus"
-
-# Map fields using ID prefix
-eventmodeler map fields --from "id:abc12345" --to "OrderStatus" '[
-  {"from": "orderId", "to": "orderId"}
-]'
-\`\`\`
-
-### When the CLI Finds Duplicates
-
-If you use a name that matches multiple elements, the CLI will show you the options:
-
-\`\`\`bash
-eventmodeler create flow --from "OrderPlaced" --to "OrderStatus"
-# Error: Multiple events found with name "OrderPlaced"
-# Please specify using the element ID:
-#   - "OrderPlaced" (id: abc12345-1234-5678-9abc-def012345678)
-#   - "OrderPlaced" (id: def67890-1234-5678-9abc-def012345678)
-#
-# Usage: eventmodeler create flow --from "id:abc12345" --to "OrderStatus"
-\`\`\`
-
-## Common Patterns
-
-### Pattern 1: Event Sourced View
-Multiple events feed into one read model:
-
-\`\`\`bash
-eventmodeler create flow --from "OrderPlaced" --to "OrderSummary"
-eventmodeler create flow --from "OrderShipped" --to "OrderSummary"
-eventmodeler create flow --from "OrderDelivered" --to "OrderSummary"
-\`\`\`
-
-### Pattern 2: Automation Triggered by Events
-Events feed an automation slice's internal read model:
-
-\`\`\`bash
-eventmodeler create flow --from "OrderPlaced" --to "OrderReadyForShipment"
-eventmodeler create flow --from "PaymentReceived" --to "OrderReadyForShipment"
-\`\`\`
-
-### Pattern 3: User Dashboard
-A read model feeds a screen for user viewing:
-
-\`\`\`bash
-eventmodeler create flow --from "UserDashboard" --to "Dashboard Screen"
-\`\`\`
-
-## Error Handling
-
-The CLI prevents invalid flows:
-
-\`\`\`bash
-# This will error - can't go directly from Event to Screen
-eventmodeler create flow --from "OrderPlaced" --to "Checkout Screen"
-# Error: Cannot create flow directly from Event to Screen.
-# Events flow to ReadModels, which then flow to Screens.
-
-# This will error - can't go from ReadModel to ReadModel
-eventmodeler create flow --from "OrderStatus" --to "CustomerProfile"
-# Error: Cannot create flow from ReadModel to ReadModel.
-\`\`\`
-
-## Best Practices
-
-1. **Create all slices first** - Easier to see the full picture before connecting
-2. **Connect events to read models** - Every event should feed at least one read model
-3. **Think about what triggers what** - Automation slices need data from read models
-4. **Map fields after creating flows** - Use \`map fields\` to complete the data flow
-5. **Verify completeness** - Run \`show model-completeness\` to find missing mappings
-6. **Use IDs for duplicates** - When names aren't unique, use \`id:\` prefix with element IDs
-`;