@miragon/event-storming-schema-model 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,480 @@
+import { z } from 'zod';
+
+/**
+ * Event Storming metamodel.
+ *
+ * All interfaces are `readonly` and serve purely as the serialization/interface format.
+ * The runtime source of truth while editing lives in the mutable diagram-js DI properties
+ * (@miragon/event-storming-renderer). `exportMap()` builds an `EventStormingBoard` from
+ * those properties.
+ *
+ * Coordinates are board units = pixels, unbounded (may be negative). An element's
+ * `position` is its CENTER — the single source of positional truth end-to-end; the
+ * renderer converts center <-> diagram-js top-left via the per-kind width/height.
+ */
+/** Position in board pixels. Unbounded — the canvas is free. */
+interface Coordinate {
+    readonly x: number;
+    readonly y: number;
+}
+type ElementType = 'event' | 'command' | 'actor' | 'aggregate' | 'policy' | 'readmodel' | 'external' | 'hotspot' | 'note' | 'drawing';
+interface BoardElementBase {
+    readonly id: string;
+    readonly elementType: ElementType;
+    readonly label: string;
+    /** Element CENTER in board pixels. */
+    readonly position: Coordinate;
+    /**
+     * Optional element color override (CSS color, typically hex from the renderer's palette).
+     * Serialized in the DSL as the project extension `(color …)` after the coordinates.
+     */
+    readonly color?: string;
+}
+/** Orange sticky: something that happened in the domain, past tense. */
+interface DomainEventElement extends BoardElementBase {
+    readonly elementType: 'event';
+}
+/** Blue sticky: an intent/action that triggers a domain event. */
+interface CommandElement extends BoardElementBase {
+    readonly elementType: 'command';
+}
+/** Small yellow sticky: the person issuing commands. */
+interface ActorElement extends BoardElementBase {
+    readonly elementType: 'actor';
+    /**
+     * Pinning: id of the host sticky (a HOST_STICKY_KINDS element) this sticky is attached to
+     * and moves with. `position` stays this element's own absolute center — attachedTo adds
+     * behavior, it never changes how coordinates are stored. DSL: the `(on <Host Name>)` suffix.
+     */
+    readonly attachedTo?: string;
+}
+/** Large yellow sticky: the consistency boundary that handles commands and emits events. */
+interface AggregateElement extends BoardElementBase {
+    readonly elementType: 'aggregate';
+}
+/** Lilac sticky: reactive logic — "whenever X happens, do Y". */
+interface PolicyElement extends BoardElementBase {
+    readonly elementType: 'policy';
+}
+/** Green sticky: information a user looks at to make a decision. */
+interface ReadModelElement extends BoardElementBase {
+    readonly elementType: 'readmodel';
+}
+/** Pink sticky: a third-party system outside the team's control. */
+interface ExternalSystemElement extends BoardElementBase {
+    readonly elementType: 'external';
+}
+/** Red sticky: an open question, conflict or risk spotted during the workshop. */
+interface HotspotElement extends BoardElementBase {
+    readonly elementType: 'hotspot';
+    /** Pinning: id of the host sticky this sticky is attached to (see ActorElement.attachedTo). */
+    readonly attachedTo?: string;
+}
+type NoteAlignHorizontal = 'left' | 'center' | 'right';
+type NoteAlignVertical = 'top' | 'middle' | 'bottom';
+/** Per-note text alignment. An absent axis means the default: left / top. */
+interface NoteAlign {
+    readonly horizontal?: NoteAlignHorizontal;
+    readonly vertical?: NoteAlignVertical;
+}
+/** Free-text note; auto-sizes to its text unless a manual `size` is set. */
+interface NoteElement extends BoardElementBase {
+    readonly elementType: 'note';
+    /**
+     * Manual size in board pixels (the user resized the note by hand). Absent = auto-size
+     * from the text — that decision lives in the renderer, the model only carries the
+     * override. DSL: the `(size <w>x<h>)` suffix.
+     */
+    readonly size?: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * Text alignment inside the note box. Absent (object or axis) = the default left/top —
+     * rendering lives in the renderer, the model only carries the override. DSL: the
+     * `(align <horizontal> <vertical>)` suffix.
+     */
+    readonly align?: NoteAlign;
+    /** Pinning: id of the host sticky this note is attached to (see ActorElement.attachedTo). */
+    readonly attachedTo?: string;
+}
+type DrawingStrokeStyle = 'solid' | 'dashed' | 'dotted';
+/**
+ * Freeform polyline/polygon (project extension, Excalidraw-style annotation drawing).
+ * `position` mirrors the first point; `points` are absolute board pixels.
+ */
+interface DrawingElement extends BoardElementBase {
+    readonly elementType: 'drawing';
+    readonly points: readonly Coordinate[];
+    /** true = closed polygon, false/absent = open polyline. */
+    readonly closed?: boolean;
+    readonly strokeStyle?: DrawingStrokeStyle;
+}
+type BoardElement = DomainEventElement | CommandElement | ActorElement | AggregateElement | PolicyElement | ReadModelElement | ExternalSystemElement | HotspotElement | NoteElement | DrawingElement;
+/** The single edge kind: a directed arrow between two stickies. */
+interface Arrow {
+    readonly id: string;
+    readonly edgeType: 'arrow';
+    /** BoardElement.id of the source sticky. */
+    readonly from: string;
+    /** BoardElement.id of the target sticky. */
+    readonly to: string;
+    /** Annotation text after `;`, e.g. `Order Placed -> Ship Order; async`. */
+    readonly label?: string;
+}
+type BoardEdge = Arrow;
+/**
+ * Workshop granularity of the board — big picture, process modelling or software design.
+ * Filters which sticky kinds the creation surfaces offer; NOT a validation rule (elements
+ * of any kind stay valid and editable on every level).
+ */
+type BoardLevel = 'big-picture' | 'process' | 'design';
+interface BoardConfig {
+    readonly title: string;
+    readonly style?: 'classic' | 'dark';
+    /** Workshop level; absent means `design` (everything available). */
+    readonly level?: BoardLevel;
+}
+/** Root object. Domain and layout are separated logically (not physically). */
+interface EventStormingBoard {
+    readonly schemaVersion: number;
+    readonly config: BoardConfig;
+    readonly elements: readonly BoardElement[];
+    readonly edges: readonly BoardEdge[];
+    /** Preserve unknown/future DSL lines losslessly (round-trip fidelity). */
+    readonly rawPassthrough?: readonly string[];
+}
+
+/** Pure layout helpers for the free Event Storming canvas (no persistence, no DOM). */
+
+/**
+ * Default framing for an empty board in board pixels. Single source of truth for the
+ * renderer's board-bounds service (fitView and SVG export fall back to it when the
+ * board has no elements).
+ */
+declare const DEFAULT_BOARD_SIZE: {
+    readonly width: 1080;
+    readonly height: 680;
+};
+/**
+ * Elements in timeline order: sorted by `position.x`, then `position.y`, then `id`.
+ * Pure and deterministic — mirrors how a facilitator reads a board left to right.
+ */
+declare function sortByTimeline(board: EventStormingBoard): BoardElement[];
+
+/** Workshop-level constants (DOM-free single source of truth for all creation surfaces). */
+
+/** Effective level when `config.level` is absent — everything available. */
+declare const DEFAULT_BOARD_LEVEL: BoardLevel;
+/**
+ * Sticky kinds offered per level (palette, typed append, change-type popup).
+ * `note` and `drawing` are annotations — always available, hence not listed here.
+ */
+declare const LEVEL_STICKY_KINDS: Record<BoardLevel, readonly ElementType[]>;
+
+/** Attachment (pinning) constants — DOM-free single source of truth for model, DSL and renderer. */
+/** Element kinds that can be pinned onto a host sticky and then move with it. */
+declare const ATTACHABLE_STICKY_KINDS: readonly ["actor", "hotspot", "note"];
+/**
+ * Sticky kinds that can carry attachments. Attachable kinds and drawings are never
+ * hosts — so attach chains cannot exist.
+ */
+declare const HOST_STICKY_KINDS: readonly ["event", "command", "aggregate", "policy", "readmodel", "external"];
+
+/**
+ * Validates arbitrary data against the schema plus additional cross-field invariants
+ * (unique IDs, edge endpoints exist and are sticky kinds). Throws on violation.
+ */
+declare function validateBoard(data: unknown): EventStormingBoard;
+declare function loadBoard(data: unknown): EventStormingBoard;
+declare function parseBoardJSON(json: string): EventStormingBoard;
+/**
+ * Deterministic serialization: stable (alphabetical) key order, elements/edges sorted by `id`,
+ * coordinates rounded to 3 decimal places. Produces clean Git diffs and reliable change
+ * detection.
+ */
+declare function serializeBoard(board: EventStormingBoard): string;
+declare function createEmptyBoard(title?: string): EventStormingBoard;
+
+declare const boardElementSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    elementType: z.ZodLiteral<"event">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"command">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"actor">;
+    attachedTo: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"aggregate">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"policy">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"readmodel">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"external">;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"hotspot">;
+    attachedTo: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"note">;
+    size: z.ZodOptional<z.ZodObject<{
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strip>>;
+    align: z.ZodOptional<z.ZodObject<{
+        horizontal: z.ZodOptional<z.ZodEnum<{
+            left: "left";
+            center: "center";
+            right: "right";
+        }>>;
+        vertical: z.ZodOptional<z.ZodEnum<{
+            top: "top";
+            middle: "middle";
+            bottom: "bottom";
+        }>>;
+    }, z.core.$strip>>;
+    attachedTo: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    elementType: z.ZodLiteral<"drawing">;
+    points: z.ZodArray<z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>>;
+    closed: z.ZodOptional<z.ZodBoolean>;
+    strokeStyle: z.ZodOptional<z.ZodEnum<{
+        solid: "solid";
+        dashed: "dashed";
+        dotted: "dotted";
+    }>>;
+    id: z.ZodString;
+    label: z.ZodString;
+    position: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+    }, z.core.$strip>;
+    color: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "elementType">;
+declare const boardEdgeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    edgeType: z.ZodLiteral<"arrow">;
+    from: z.ZodString;
+    to: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "edgeType">;
+declare const eventStormingBoardSchema: z.ZodObject<{
+    schemaVersion: z.ZodNumber;
+    config: z.ZodObject<{
+        title: z.ZodString;
+        style: z.ZodOptional<z.ZodEnum<{
+            classic: "classic";
+            dark: "dark";
+        }>>;
+        level: z.ZodOptional<z.ZodEnum<{
+            "big-picture": "big-picture";
+            process: "process";
+            design: "design";
+        }>>;
+    }, z.core.$strip>;
+    elements: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        elementType: z.ZodLiteral<"event">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"command">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"actor">;
+        attachedTo: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"aggregate">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"policy">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"readmodel">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"external">;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"hotspot">;
+        attachedTo: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"note">;
+        size: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+        align: z.ZodOptional<z.ZodObject<{
+            horizontal: z.ZodOptional<z.ZodEnum<{
+                left: "left";
+                center: "center";
+                right: "right";
+            }>>;
+            vertical: z.ZodOptional<z.ZodEnum<{
+                top: "top";
+                middle: "middle";
+                bottom: "bottom";
+            }>>;
+        }, z.core.$strip>>;
+        attachedTo: z.ZodOptional<z.ZodString>;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        elementType: z.ZodLiteral<"drawing">;
+        points: z.ZodArray<z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>>;
+        closed: z.ZodOptional<z.ZodBoolean>;
+        strokeStyle: z.ZodOptional<z.ZodEnum<{
+            solid: "solid";
+            dashed: "dashed";
+            dotted: "dotted";
+        }>>;
+        id: z.ZodString;
+        label: z.ZodString;
+        position: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+        }, z.core.$strip>;
+        color: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "elementType">>;
+    edges: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        edgeType: z.ZodLiteral<"arrow">;
+        from: z.ZodString;
+        to: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>], "edgeType">>;
+    rawPassthrough: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type EventStormingBoardInput = z.input<typeof eventStormingBoardSchema>;
+
+/**
+ * Schema migrations as an ordered chain of pure functions.
+ * `migrate(json)` reads `schemaVersion`, applies all necessary steps and returns the
+ * object raised to the current version (not yet validated).
+ */
+declare const CURRENT_SCHEMA_VERSION = 1;
+type Json = Record<string, unknown>;
+declare function migrate(input: unknown): Json;
+
+export { ATTACHABLE_STICKY_KINDS, type ActorElement, type AggregateElement, type Arrow, type BoardConfig, type BoardEdge, type BoardElement, type BoardElementBase, type BoardLevel, CURRENT_SCHEMA_VERSION, type CommandElement, type Coordinate, DEFAULT_BOARD_LEVEL, DEFAULT_BOARD_SIZE, type DomainEventElement, type DrawingElement, type DrawingStrokeStyle, type ElementType, type EventStormingBoard, type EventStormingBoardInput, type ExternalSystemElement, HOST_STICKY_KINDS, type HotspotElement, LEVEL_STICKY_KINDS, type NoteAlign, type NoteAlignHorizontal, type NoteAlignVertical, type NoteElement, type PolicyElement, type ReadModelElement, boardEdgeSchema, boardElementSchema, createEmptyBoard, eventStormingBoardSchema, loadBoard, migrate, parseBoardJSON, serializeBoard, sortByTimeline, validateBoard };