marcel/mermaid
1
0
Fork 0
mirror of https://github.com/mermaid-js/mermaid.git synced 2025-11-21 13:14:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #7136 from mermaid-js/feat/sequence-alias-support-new-participant-syntax

Browse Source 
feat : add alias support for new participant syntax
This commit is contained in:
Shubham P
2025-11-20 07:46:34 +00:00
committed by GitHub
parent 61c18b99a0 8add133bbe
commit b1fe4ffe97
11 changed files with 447 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
.changeset/lazy-brooms-battle.md Normal file
View File

@@ -0,0 +1,5 @@
---
'mermaid': patch
---
feat: add alias support for new participant syntax of sequence diagrams

189
cypress/integration/rendering/sequencediagram-v2.spec.js
View File

@@ -776,5 +776,194 @@ describe('Sequence Diagram Special Cases', () => {
);
});
});
describe('Participant Stereotypes with Aliases', () => {
it('should render participants with stereotypes and aliases', () => {
imgSnapshotTest(
`sequenceDiagram
participant API@{ "type" : "boundary" } as Public API
participant Auth@{ "type" : "control" } as Auth Controller
participant DB@{ "type" : "database" } as User Database
participant Cache@{ "type" : "entity" } as Cache Layer
API ->> Auth: Authenticate request
Auth ->> DB: Query user
DB -->> Auth: User data
Auth ->> Cache: Store session
Cache -->> Auth: Confirmed
Auth -->> API: Token`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render actors with stereotypes and aliases', () => {
imgSnapshotTest(
`sequenceDiagram
actor U@{ "type" : "actor" } as End User
actor A@{ "type" : "boundary" } as API Gateway
actor S@{ "type" : "control" } as Service Layer
actor D@{ "type" : "database" } as Data Store
U ->> A: Send request
A ->> S: Process
S ->> D: Persist
D -->> S: Success
S -->> A: Response
A -->> U: Result`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render mixed participants and actors with stereotypes and aliases', () => {
imgSnapshotTest(
`sequenceDiagram
actor Client@{ "type" : "actor" } AS Mobile Client
participant Gateway@{ "type" : "boundary" } as API Gateway
participant OrderSvc@{ "type" : "control" } as Order Service
participant Queue@{ "type" : "queue" } as Message Queue
participant DB@{ "type" : "database" } as Order Database
participant Logs@{ "type" : "collections" } as Audit Logs
Client ->> Gateway: Place order
Gateway ->> OrderSvc: Validate order
OrderSvc ->> Queue: Queue for processing as well
OrderSvc ->> DB: Save order
OrderSvc ->> Logs: Log transaction
Queue -->> OrderSvc: Processing started AS Well
DB -->> OrderSvc: Order saved
Logs -->> OrderSvc: Logged
OrderSvc -->> Gateway: Order confirmed
Gateway -->> Client: Confirmation`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render stereotypes with aliases in boxes', () => {
imgSnapshotTest(
`sequenceDiagram
box rgb(200,220,255) Frontend Layer
actor User@{ "type" : "actor" } as End User
participant UI@{ "type" : "boundary" } as User Interface
end
box rgb(255,220,200) Backend Layer
participant API@{ "type" : "boundary" } as REST API
participant Svc@{ "type" : "control" } as Business Logic
end
box rgb(220,255,200) Data Layer
participant DB@{ "type" : "database" } as Primary DB
participant Cache@{ "type" : "entity" } as Cache Store
end
User ->> UI: Click button
UI ->> API: HTTP request
API ->> Svc: Process
Svc ->> Cache: Check cache
Cache -->> Svc: Cache miss
Svc ->> DB: Query data
DB -->> Svc: Data
Svc ->> Cache: Update cache
Svc -->> API: Response
API -->> UI: Data
UI -->> User: Display`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render stereotypes with aliases and complex interactions', () => {
imgSnapshotTest(
`sequenceDiagram
participant Web@{ "type" : "boundary" } as Web Portal
participant Auth@{ "type" : "control" } as Auth Service
participant UserDB@{ "type" : "database" } as User DB
participant Queue@{ "type" : "queue" } as Event Queue
participant Audit@{ "type" : "collections" } as Audit Trail
Web ->> Auth: Login request
activate Auth
Auth ->> UserDB: Verify credentials
activate UserDB
UserDB -->> Auth: User found
deactivate UserDB
alt Valid credentials
Auth ->> Queue: Publish login event
Auth ->> Audit: Log success
par Parallel processing
Queue -->> Auth: Event queued
and
Audit -->> Auth: Logged
end
Auth -->> Web: Success token
else Invalid credentials
Auth ->> Audit: Log failure
Audit -->> Auth: Logged
Auth --x Web: Access denied
end
deactivate Auth
Note over Web,Audit: All interactions logged`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
});
describe('Participant Inline Alias in Config', () => {
it('should render participants with inline alias in config object', () => {
imgSnapshotTest(
`sequenceDiagram
participant API@{ "type" : "boundary", "alias": "Public API" }
participant Auth@{ "type" : "control", "alias": "Auth Service" }
participant DB@{ "type" : "database", "alias": "User DB" }
API ->> Auth: Login request
Auth ->> DB: Query user
DB -->> Auth: User data
Auth -->> API: Token`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render actors with inline alias in config object', () => {
imgSnapshotTest(
`sequenceDiagram
actor U@{ "type" : "actor", "alias": "End User" }
actor G@{ "type" : "boundary", "alias": "Gateway" }
actor S@{ "type" : "control", "alias": "Service" }
U ->> G: Request
G ->> S: Process
S -->> G: Response
G -->> U: Result`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should handle mixed inline and external alias syntax', () => {
imgSnapshotTest(
`sequenceDiagram
participant A@{ "type" : "boundary", "alias": "Service A" }
participant B@{ "type" : "control" } as Service B
participant C@{ "type" : "database" }
A ->> B: Request
B ->> C: Query
C -->> B: Data
B -->> A: Response`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should prioritize external alias over inline alias', () => {
imgSnapshotTest(
`sequenceDiagram
participant API@{ "type" : "boundary", "alias": "Internal Name" } as External Name
participant DB@{ "type" : "database", "alias": "Internal DB" } AS External DB
API ->> DB: Query
DB -->> API: Result`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
it('should render inline alias with only alias field (no type)', () => {
imgSnapshotTest(
`sequenceDiagram
participant API@{ "alias": "Public API" }
participant Auth@{ "alias": "Auth Service" }
API ->> Auth: Request
Auth -->> API: Response`,
{ look: 'classic', sequence: { diagramMarginX: 50, diagramMarginY: 10 } }
);
});
});
});
});

4
docs/config/setup/mermaid/interfaces/ParseOptions.md
View File

@@ -10,7 +10,7 @@
# Interface: ParseOptions
Defined in: [packages/mermaid/src/types.ts:88](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L88)
Defined in: [packages/mermaid/src/types.ts:89](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L89)
## Properties
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:88](https://github.com/mermaid-js/mer
> `optional` **suppressErrors**: `boolean`
Defined in: [packages/mermaid/src/types.ts:93](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L93)
Defined in: [packages/mermaid/src/types.ts:94](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L94)
If `true`, parse will return `false` instead of throwing error when the diagram is invalid.
The `parseError` function will not be called.

6
docs/config/setup/mermaid/interfaces/ParseResult.md
View File

@@ -10,7 +10,7 @@
# Interface: ParseResult
Defined in: [packages/mermaid/src/types.ts:96](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L96)
Defined in: [packages/mermaid/src/types.ts:97](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L97)
## Properties
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:96](https://github.com/mermaid-js/mer
> **config**: [`MermaidConfig`](MermaidConfig.md)
Defined in: [packages/mermaid/src/types.ts:104](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L104)
Defined in: [packages/mermaid/src/types.ts:105](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L105)
The config passed as YAML frontmatter or directives
@@ -28,6 +28,6 @@ The config passed as YAML frontmatter or directives
> **diagramType**: `string`
Defined in: [packages/mermaid/src/types.ts:100](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L100)
Defined in: [packages/mermaid/src/types.ts:101](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L101)
The diagram type, e.g. 'flowchart', 'sequence', etc.

8
docs/config/setup/mermaid/interfaces/RenderResult.md
View File

@@ -10,7 +10,7 @@
# Interface: RenderResult
Defined in: [packages/mermaid/src/types.ts:114](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L114)
Defined in: [packages/mermaid/src/types.ts:115](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L115)
## Properties
@@ -18,7 +18,7 @@ Defined in: [packages/mermaid/src/types.ts:114](https://github.com/mermaid-js/me
> `optional` **bindFunctions**: (`element`) => `void`
Defined in: [packages/mermaid/src/types.ts:132](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L132)
Defined in: [packages/mermaid/src/types.ts:133](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L133)
Bind function to be called after the svg has been inserted into the DOM.
This is necessary for adding event listeners to the elements in the svg.
@@ -45,7 +45,7 @@ bindFunctions?.(div); // To call bindFunctions only if it's present.
> **diagramType**: `string`
Defined in: [packages/mermaid/src/types.ts:122](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L122)
Defined in: [packages/mermaid/src/types.ts:123](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L123)
The diagram type, e.g. 'flowchart', 'sequence', etc.
@@ -55,6 +55,6 @@ The diagram type, e.g. 'flowchart', 'sequence', etc.
> **svg**: `string`
Defined in: [packages/mermaid/src/types.ts:118](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L118)
Defined in: [packages/mermaid/src/types.ts:119](https://github.com/mermaid-js/mermaid/blob/master/packages/mermaid/src/types.ts#L119)
The svg code for the rendered graph.

78
docs/syntax/sequenceDiagram.md
View File

@@ -196,7 +196,11 @@ sequenceDiagram
### Aliases
The actor can have a convenient identifier and a descriptive label.
The actor can have a convenient identifier and a descriptive label. Aliases can be defined in two ways: using external syntax with the `as` keyword, or inline within the configuration object.
#### External Alias Syntax
You can define an alias using the `as` keyword after the participant declaration:
```mermaid-example
sequenceDiagram
@@ -214,6 +218,78 @@ sequenceDiagram
J->>A: Great!
```
The external alias syntax also works with participant stereotype configurations, allowing you to combine type specification with aliases:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary" } as Public API
actor DB@{ "type": "database" } as User Database
participant Svc@{ "type": "control" } as Auth Service
API->>Svc: Authenticate
Svc->>DB: Query user
DB-->>Svc: User data
Svc-->>API: Token
```
```mermaid
sequenceDiagram
participant API@{ "type": "boundary" } as Public API
actor DB@{ "type": "database" } as User Database
participant Svc@{ "type": "control" } as Auth Service
API->>Svc: Authenticate
Svc->>DB: Query user
DB-->>Svc: User data
Svc-->>API: Token
```
#### Inline Alias Syntax
Alternatively, you can define an alias directly inside the configuration object using the `"alias"` field. This works with both `participant` and `actor` keywords:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Public API" }
participant Auth@{ "type": "control", "alias": "Auth Service" }
participant DB@{ "type": "database", "alias": "User Database" }
API->>Auth: Login request
Auth->>DB: Query user
DB-->>Auth: User data
Auth-->>API: Access token
```
```mermaid
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Public API" }
participant Auth@{ "type": "control", "alias": "Auth Service" }
participant DB@{ "type": "database", "alias": "User Database" }
API->>Auth: Login request
Auth->>DB: Query user
DB-->>Auth: User data
Auth-->>API: Access token
```
#### Alias Precedence
When both inline alias (in the configuration object) and external alias (using `as` keyword) are provided, the **external alias takes precedence**:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Internal Name" } as External Name
participant DB@{ "type": "database", "alias": "Internal DB" } as External DB
API->>DB: Query
DB-->>API: Result
```
```mermaid
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Internal Name" } as External Name
participant DB@{ "type": "database", "alias": "Internal DB" } as External DB
API->>DB: Query
DB-->>API: Result
```
In the example above, "External Name" and "External DB" will be displayed, not "Internal Name" and "Internal DB".
### Actor Creation and Destruction (v10.3.0+)
It is possible to create and destroy actors by messages. To do so, add a create or destroy directive before the message.

4
packages/mermaid/src/diagrams/sequence/parser/sequenceDiagram.jison
View File

@@ -30,6 +30,7 @@
[0-9]+(?=[ \n]+) return 'NUM';
<ID>\@\{ { this.begin('CONFIG'); return 'CONFIG_START'; }
<CONFIG>[^\}]+ { return 'CONFIG_CONTENT'; }
<CONFIG>\}(?=\s+as\s) { this.popState(); this.begin('ALIAS'); return 'CONFIG_END'; }
<CONFIG>\} { this.popState(); this.popState(); return 'CONFIG_END'; }
<ID>[^\<->\->:\n,;@\s]+(?=\@\{) { yytext = yytext.trim(); return 'ACTOR'; }
<ID>[^<>:\n,;@\s]+(?=\s+as\s) { yytext = yytext.trim(); this.begin('ALIAS'); return 'ACTOR'; }
@@ -264,7 +265,10 @@ participant_statement
| 'participant_actor' actor 'AS' restOfLine 'NEWLINE' {$2.draw='actor'; $2.type='addParticipant';$2.description=yy.parseMessage($4); $$=$2;}
| 'participant_actor' actor 'NEWLINE' {$2.draw='actor'; $2.type='addParticipant'; $$=$2;}
| 'destroy' actor 'NEWLINE' {$2.type='destroyParticipant'; $$=$2;}
| 'participant' actor_with_config 'AS' restOfLine 'NEWLINE' {$2.draw='participant'; $2.type='addParticipant'; $2.description=yy.parseMessage($4); $$=$2;}
| 'participant' actor_with_config 'NEWLINE' {$2.draw='participant'; $2.type='addParticipant'; $$=$2;}
| 'participant_actor' actor_with_config 'AS' restOfLine 'NEWLINE' {$2.draw='actor'; $2.type='addParticipant'; $2.description=yy.parseMessage($4); $$=$2;}
| 'participant_actor' actor_with_config 'NEWLINE' {$2.draw='actor'; $2.type='addParticipant'; $$=$2;}
;

6
packages/mermaid/src/diagrams/sequence/sequenceDb.ts
View File

@@ -172,6 +172,12 @@ export class SequenceDB implements DiagramDB {
doc = yaml.load(yamlData, { schema: yaml.JSON_SCHEMA }) as ParticipantMetaData;
}
type = doc?.type ?? type;
// If alias is provided in metadata and description is not already set, use the alias
if (doc?.alias && (!description || description.text === name)) {
description = { text: doc.alias, wrap: description?.wrap, type };
}
const old = this.state.records.actors.get(id);
if (old) {
// If already set and trying to set to a new one throw error

109
packages/mermaid/src/diagrams/sequence/sequenceDiagram.spec.js
View File

@@ -2621,5 +2621,114 @@ Bob->>Alice:Got it!
}
expect(error).toBe(true);
});
it('should parse participant with stereotype and alias', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant Alice@{ "type" : "boundary" } as Public API
participant Bob@{ "type" : "control" } as Controller
Alice->>Bob: Request
Bob-->>Alice: Response
`);
const actors = diagram.db.getActors();
expect(actors.get('Alice').type).toBe('boundary');
expect(actors.get('Alice').description).toBe('Public API');
expect(actors.get('Bob').type).toBe('control');
expect(actors.get('Bob').description).toBe('Controller');
});
it('should parse actor with stereotype and alias', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
actor A@{ "type" : "database" } AS Database Server
actor B@{ "type" : "queue" } as Message Queue
A->>B: Send message
`);
const actors = diagram.db.getActors();
expect(actors.get('A').type).toBe('database');
expect(actors.get('A').description).toBe('Database Server');
expect(actors.get('B').type).toBe('queue');
expect(actors.get('B').description).toBe('Message Queue');
});
it('should parse participant with stereotype and simple alias', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant API@{ "type" : "boundary" } AS Public API
API->>API: test
`);
const actors = diagram.db.getActors();
expect(actors.get('API').type).toBe('boundary');
expect(actors.get('API').description).toBe('Public API');
});
it('should parse participant with inline alias in config object', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant API@{ "type" : "boundary", "alias": "Public API" }
participant Auth@{ "type" : "control", "alias": "Auth Controller" }
API->>Auth: Request
Auth-->>API: Response
`);
const actors = diagram.db.getActors();
expect(actors.get('API').type).toBe('boundary');
expect(actors.get('API').description).toBe('Public API');
expect(actors.get('Auth').type).toBe('control');
expect(actors.get('Auth').description).toBe('Auth Controller');
});
it('should parse actor with inline alias in config object', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
actor U@{ "type" : "actor", "alias": "End User" }
actor DB@{ "type" : "database", "alias": "User Database" }
U->>DB: Query
DB-->>U: Result
`);
const actors = diagram.db.getActors();
expect(actors.get('U').type).toBe('actor');
expect(actors.get('U').description).toBe('End User');
expect(actors.get('DB').type).toBe('database');
expect(actors.get('DB').description).toBe('User Database');
});
it('should prioritize external alias over inline alias', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant API@{ "type" : "boundary", "alias": "Internal Name" } as External Name
API->>API: test
`);
const actors = diagram.db.getActors();
expect(actors.get('API').type).toBe('boundary');
expect(actors.get('API').description).toBe('External Name');
});
it('should handle participant with only inline alias (no type)', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant API@{ "alias": "Public API" }
API->>API: test
`);
const actors = diagram.db.getActors();
expect(actors.get('API').description).toBe('Public API');
});
it('should handle mixed inline and external alias syntax', async () => {
const diagram = await Diagram.fromText(`
sequenceDiagram
participant A@{ "type" : "boundary", "alias": "Service A" }
participant B@{ "type" : "control" } as Service B
participant C@{ "type" : "database" }
A->>B: Request
B->>C: Query
`);
const actors = diagram.db.getActors();
expect(actors.get('A').type).toBe('boundary');
expect(actors.get('A').description).toBe('Service A');
expect(actors.get('B').type).toBe('control');
expect(actors.get('B').description).toBe('Service B');
expect(actors.get('C').type).toBe('database');
expect(actors.get('C').description).toBe('C');
});
});
});

48
packages/mermaid/src/docs/syntax/sequenceDiagram.md
View File

@@ -120,7 +120,11 @@ sequenceDiagram
### Aliases
The actor can have a convenient identifier and a descriptive label.
The actor can have a convenient identifier and a descriptive label. Aliases can be defined in two ways: using external syntax with the `as` keyword, or inline within the configuration object.
#### External Alias Syntax
You can define an alias using the `as` keyword after the participant declaration:
```mermaid-example
sequenceDiagram
@@ -130,6 +134,48 @@ sequenceDiagram
J->>A: Great!
```
The external alias syntax also works with participant stereotype configurations, allowing you to combine type specification with aliases:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary" } as Public API
actor DB@{ "type": "database" } as User Database
participant Svc@{ "type": "control" } as Auth Service
API->>Svc: Authenticate
Svc->>DB: Query user
DB-->>Svc: User data
Svc-->>API: Token
```
#### Inline Alias Syntax
Alternatively, you can define an alias directly inside the configuration object using the `"alias"` field. This works with both `participant` and `actor` keywords:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Public API" }
participant Auth@{ "type": "control", "alias": "Auth Service" }
participant DB@{ "type": "database", "alias": "User Database" }
API->>Auth: Login request
Auth->>DB: Query user
DB-->>Auth: User data
Auth-->>API: Access token
```
#### Alias Precedence
When both inline alias (in the configuration object) and external alias (using `as` keyword) are provided, the **external alias takes precedence**:
```mermaid-example
sequenceDiagram
participant API@{ "type": "boundary", "alias": "Internal Name" } as External Name
participant DB@{ "type": "database", "alias": "Internal DB" } as External DB
API->>DB: Query
DB-->>API: Result
```
In the example above, "External Name" and "External DB" will be displayed, not "Internal Name" and "Internal DB".
### Actor Creation and Destruction (v10.3.0+)
It is possible to create and destroy actors by messages. To do so, add a create or destroy directive before the message.

1
packages/mermaid/src/types.ts
View File

@@ -23,6 +23,7 @@ export interface ParticipantMetaData {
| 'database'
| 'collections'
| 'queue';
alias?: string;
}
export interface EdgeMetaData {