@asyncapi/cupid

    0.6.6 • Public • Published

    AsyncAPI logo
    Cupid
    Cupid Image

    npm npm Coverage Status

    Overview

    An official library that focuses on finding and analyzing the relationships between AsyncAPI files to later output consolidated information about the system architecture. Output format would be customizable and available in different formats like PlantUML, mermaid.js, ReactFlow.

    Install

    npm install @asyncapi/cupid
    

    Technical Details

    This library takes AsyncAPI files as an array input for which the user wants to discover the relations between them. It then validates and parses the given array of AsyncAPI files and generates the output in desired passed syntax. In the process, for every different server, it assigns a slug having the server's URL and protocol and then maps channels with the same server. Following, it maps the service information with the channel's name as per if the service is subscribing/publishing to a given channel. The sub/pub Map of default output syntax provides the service name and the metadata of the service including but not limited to description, payload, headers, bindings, extensions.

    API Documentation

    See API documentation for more example and full API reference information.

    Usage

    Node.js

    const cupid = require('@asyncapi/cupid');
    const path = require('path');
    const fs = require('fs');
    
    const examplesPath = './test/examples/flightService';
    
    function getAsyncApiExamples() {
      const docs = [];
      const files = fs.readdirSync(examplesPath);
      for (const file of files) {
        const document_path = path.join('./examples/flightService', file);
        const asyncApiDoc = fs.readFileSync(path.resolve(__dirname, document_path),'utf8');
        docs.push(asyncApiDoc);
      }
      return docs;
    }
    
    // For default output syntax
    const defaultOutput = cupid.getRelations(docs);
    
    // For mermaid Flowchart 
    const mermaidFlowchart = cupid.getRelations(docs,{syntax:'mermaid'});
    
    // For plantUML classDiagram 
    const plantUMLClassDiagram = cupid.getRelations(docs,{syntax:'plantUML'});
    
    // For reactFlow nodes
    const reactFlowNodes = cupid.getRelations(docs,{syntax:'reactFlow'});

    Default Output Syntax

    Map(n) {
      '<server1>' => Map(m) {
        'channel1' => { sub: [Map(1) {"<Service Name>" => "<metadata>"}, ...], pub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...] },
        'channel2' => { sub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...], pub: [[Map(1) {"<Service Name>" => "<metadata>"}, ...] }
      }
    }

    Mermaid Flowchart

    Syntax

    Based on Flight Notification Service example.

    graph TD
     server1[(mqtt://localhost:1883)]
    FlightMonitorService[Flight Monitor Service]
    FlightMonitorService -- flight/update --> server1
    FlightNotifierService[Flight Notifier Service]
    server1 -- flight/update --> FlightNotifierService
    FlightSubscriberService[Flight Subscriber Service]
    FlightSubscriberService -- flight/queue --> server1
    server1 -- flight/queue --> FlightMonitorService
    

    Flowchart

    Mermaid Flowchart

    View in online editor

    PlantUML classDiagram

    Syntax

    Based on FlightService example.

    @startuml
    title Classes - Class Diagram
    
    class server1 { 
     url: mqtt://localhost:1883 
     protocol: mqtt
    }
    FlightMonitorService --|> server1:flight/update
    server1 --|> FlightNotifierService:flight/update
    FlightSubscriberService --|> server1:flight/queue
    server1 --|> FlightMonitorService:flight/queue
    @enduml
    

    ClassDiagram

    PlantUML classDiagram

    View in online editor

    React Flow Nodes

    Syntax

    Based on FlightService example.

    [
      {
        id: 'Server1',
        data: { label: 'mqtt://localhost:1883,mqtt' },
        position: { x: 250, y: 5 }
      },
      {
        id: 'FlightMonitorService',
        data: { label: 'Flight Monitor Service' },
        position: { x: 100, y: 10 }
      },
      {
        id: 'edge1',
        source: 'FlightMonitorService',
        target: 'Server1',
        animated: true,
        label: 'flight/update',
        type: 'edgeType',
        arrowHeadType: 'arrowclosed'
      },
      {
        id: 'FlightNotifierService',
        data: { label: 'Flight Notifier Service' },
        position: { x: 100, y: 10 }
      },
      {
        id: 'edge2',
        source: 'Server1',
        target: 'FlightNotifierService',
        animated: true,
        label: 'flight/update',
        type: 'edgeType',
        arrowHeadType: 'arrowclosed'
      },
      {
        id: 'FlightSubscriberService',
        data: { label: 'Flight Subscriber Service' },
        position: { x: 100, y: 10 }
      },
      {
        id: 'edge3',
        source: 'FlightSubscriberService',
        target: 'Server1',
        animated: true,
        label: 'flight/queue',
        type: 'edgeType',
        arrowHeadType: 'arrowclosed'
      },
      {
        id: 'edge4',
        source: 'Server1',
        target: 'FlightMonitorService',
        animated: true,
        label: 'flight/queue',
        type: 'edgeType',
        arrowHeadType: 'arrowclosed'
      }
    ]

    React Flow Nodes

    reactFlow Nodes

    Steps to visualize relations in React Flow

    1. Setup a react project in which you want to display reactFlow nodes.
    2. Install @asyncapi/cupid into the project.
    3. Make a react component for the example.

    Example

    import React from 'react';
    import ReactFlow from 'react-flow-renderer';
    import cupid from '@asyncapi/cupid';
    import {getAsyncApiDocuments} from 'utils'; // function for reading AysncAPI files 
    
    const docs = getAsyncApiDocuments();
    const elements = cupid.getRelations(docs,{syntax:'reactFlow'});
    
    export default () => (
      <div style={{ height: 300 }}>
        <ReactFlow elements={elements} />
      </div>
    );

    Develop

    1. Clone the project git clone https://github.com/asyncapi/cupid.git
    2. Install the dependencies npm i
    3. For a quick overview you can run tests by npm test. You can also contribute to provide more different syntax outputs to visualize the relations.
    4. Write code and tests.
    5. Make sure all tests pass npm test
    6. Make sure code is well formatted and secure npm run lint

    Contributing

    Read CONTRIBUTING guide.

    Keywords

    none

    Install

    npm i @asyncapi/cupid

    DownloadsWeekly Downloads

    4

    Version

    0.6.6

    License

    Apache-2.0

    Unpacked Size

    422 kB

    Total Files

    42

    Last publish

    Collaborators

    • fmvilas
    • derberg
    • asyncapi-bot