@nonsoo/prisma-mermaid 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Prisma-Mermaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# Prisma to Mermaid Generator
+
+Generate Mermaid class diagrams and Mermaid ERD diagrams directly from your Prisma schema. This package exposes a Prisma generator that runs during `prisma generate` as well as two programmatic helpers -- generateMermaidClass and generateMermaidERD.
+
+## Installation
+
+```bash
+npm i --save-dev @nonsoo/prisma-mermaid @mermaid-js/mermaid-cli
+```
+
+## Usage (Prisma Generator)
+
+Add the following generator to your prisma schema
+
+```prisma
+generator diagram {
+  provider = "prisma-mermaid"
+  output   = "../src/generated/diagrams"
+  format   = "mermaid-erd"
+}
+```
+
+`format` Options
+
+| Value         | Description                       |
+| ------------- | --------------------------------- |
+| mermaid-erd   | Generates a Mermaid ERD diagram   |
+| mermaid-class | Generates a Mermaid class diagram |
+
+### Disabling the Diagram Generator (Useful for CI)
+
+Set the following environment variable in your .env:
+
+```bash
+PRISMA_DIAGRAM_GENERATOR_DISABLE=true
+```
+
+## Usage (Internal Functions)
+
+You can also call the underlying functions directly if you want to generate diagrams outside of the Prisma CLI.
+
+```js
+import {
+  generateMermaidClass,
+  generateMermaidERD,
+} from "@nonsoo/prisma-mermaid";
+
+await generateMermaidClass({
+  schemaPath: "./prisma/schema.prisma",
+  output: "./diagrams/classDiagram.mmd",
+});
+
+await generateMermaidERD({
+  schemaPath: "./prisma/schema.prisma",
+  output: "./diagrams/erdDiagram.mmd",
+});
+```
+
+## Philosophy
+
+Documentation should evolve alongside the code it describes. Diagrams-as-code tools such as Mermaid make it easier for teams to maintain clear, accurate diagrams as their systems grow and change. However, creating these diagrams manually — especially for database schemas — still introduces friction and the risk of diagrams falling out of sync with the system.
+
+Prisma already provides a single source of truth for your data model through the Prisma schema. Therefore, by generating diagrams directly from this schema, we can ensure documentation stays automatically aligned with the current state of the database models.
+
+This library bridges that gap. It transforms your Prisma schema into Mermaid-powered ERD or class diagrams, combining code generation with diagrams-as-code. Once generated, these diagrams can be used to create Markdown files, SVGs, PDFs, or any other Mermaid-supported output — always consistent, always up to date.

package/build/index.cjs

@@ -0,0 +1,383 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  generateMermaidClass: () => generateDiagram,
+  generateMermaidERD: () => generateDiagram2
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/lib/MermaidClass/prismaMermaidClass.ts
+var import_internals = __toESM(require("@prisma/internals"), 1);
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+
+// src/constants/mermaid.ts
+var mermaidERDiagramConfig = {
+  theme: "neutral",
+  themeVariables: {
+    fontSize: "20px",
+    fontFamily: "Arial",
+    padding: "12px",
+    lineHeight: "1.4"
+  },
+  flowchart: {
+    nodeSpacing: 80,
+    rankSpacing: 120,
+    htmlLabels: true
+  }
+};
+var mermaidClassDiagramConfig = {
+  theme: "neutral",
+  themeVariables: {
+    fontFamily: "Arial",
+    lineHeight: "1.4"
+  },
+  flowchart: {
+    nodeSpacing: 300,
+    rankSpacing: 120,
+    htmlLabels: true
+  },
+  class: {
+    hideEmptyMembersBox: true
+  }
+};
+var DEFAULT_BASE_NODE_SPACING = 100;
+var DEFAULT_BASE_EDGE_SPACING = 150;
+
+// src/utils/mermaid.ts
+var generateDiagramSpacing = ({
+  baseEdge,
+  baseNode,
+  models
+}) => {
+  const totalFields = models.reduce((sum, m) => sum + m.fields.length, 0);
+  const totalRelations = models.reduce(
+    (sum, m) => sum + m.fields.filter((f) => f.relationName && f.relationFromFields?.length).length,
+    0
+  );
+  return {
+    nodeSpacing: baseNode + models.length * 6 + totalFields * 2,
+    edgeSpacing: baseEdge + models.length * 4 + totalRelations * 4
+  };
+};
+var generateMermaidConfig = (config, models) => {
+  if (config["themeVariables"]) {
+    const { edgeSpacing, nodeSpacing } = generateDiagramSpacing({
+      baseEdge: DEFAULT_BASE_EDGE_SPACING,
+      baseNode: DEFAULT_BASE_NODE_SPACING,
+      models
+    });
+    config["themeVariables"] = {
+      ...config["themeVariables"],
+      edgeSpacing,
+      nodeSpacing
+    };
+  }
+  const json = JSON.stringify(config, null, 2);
+  return `%%{init: ${json}}%%
+`;
+};
+
+// src/lib/MermaidClass/utils.ts
+var generateCardinality = ({
+  isList,
+  isRequired
+}) => {
+  if (isList) return '"*"';
+  return isRequired ? '"1"' : '"0..1"';
+};
+var generateRelationships = ({
+  relationships
+}) => {
+  const lines = [];
+  for (const relName in relationships) {
+    const sides = relationships[relName];
+    if (!sides) continue;
+    if (sides.length === 1) {
+      const a = sides[0];
+      if (!a) continue;
+      lines.push(
+        `${a.model} ${generateCardinality({
+          isList: a.isList,
+          isRequired: a.isRequired
+        })} --> "1" ${a.fieldType} : ${relName}`
+      );
+    } else if (sides.length === 2) {
+      const a = sides[0];
+      const b = sides[1];
+      if (!a || !b) continue;
+      lines.push(
+        `${a.model} ${generateCardinality({
+          isList: a.isList,
+          isRequired: a.isRequired
+        })} --> ${generateCardinality({
+          isList: b.isList,
+          isRequired: b.isRequired
+        })} ${b.model} : ${relName}`
+      );
+    } else {
+      for (let i = 1; i < sides.length; i++) {
+        const a = sides[0];
+        const b = sides[i];
+        if (!a || !b) continue;
+        lines.push(
+          `${a.model} ${generateCardinality({
+            isList: a.isList,
+            isRequired: a.isRequired
+          })} --> ${generateCardinality({
+            isList: b.isList,
+            isRequired: b.isRequired
+          })} ${b.model} : ${relName}`
+        );
+      }
+    }
+  }
+  return lines;
+};
+
+// src/lib/MermaidClass/prismaMermaidClass.ts
+var { getDMMF } = import_internals.default;
+var generateDiagram = async ({
+  outputPath,
+  schemaPath,
+  generatorPrismaDocument
+}) => {
+  const outputDir = outputPath ? import_node_path.default.resolve(outputPath) : import_node_path.default.join(`${process.cwd()}/src/generated/diagrams`);
+  try {
+    const prismaDocument = generatorPrismaDocument ?? await getDMMF({
+      datamodel: (0, import_node_fs.readFileSync)(schemaPath, "utf-8")
+    });
+    const models = prismaDocument.datamodel.models;
+    const enums = prismaDocument.datamodel.enums;
+    const mermaidLines = [
+      "%% --------------------------------------------",
+      "%% Auto-generated Mermaid Class Diagram.  Do Not Edit Directly.",
+      "%% --------------------------------------------\n",
+      generateMermaidConfig(mermaidClassDiagramConfig, models),
+      "classDiagram"
+    ];
+    const relationships = {};
+    models.forEach((model) => {
+      mermaidLines.push(`class ${model.name} {`);
+      model.fields.forEach((field) => {
+        mermaidLines.push(`  ${field.type} ${field.name}`);
+        if (field.relationName) {
+          if (!relationships[field.relationName]) {
+            relationships[field.relationName] = [];
+          }
+          relationships[field.relationName].push({
+            model: model.name,
+            fieldType: field.type,
+            isList: field.isList ?? false,
+            isRequired: field.isRequired ?? false
+          });
+        }
+      });
+      mermaidLines.push("}");
+    });
+    enums.forEach((enumDef) => {
+      mermaidLines.push(`class ${enumDef.name} {`);
+      enumDef.values.forEach((val) => {
+        mermaidLines.push(`  <<enumeration>> ${val.name}`);
+      });
+      mermaidLines.push("}");
+    });
+    const relationLines = generateRelationships({ relationships });
+    const output = mermaidLines.concat(relationLines).join("\n");
+    (0, import_node_fs.mkdirSync)(outputDir, { recursive: true });
+    const outFile = import_node_path.default.join(outputDir, "mermaidClassDiagram.mmd");
+    (0, import_node_fs.writeFileSync)(outFile, output, "utf-8");
+    console.log(`Mermaid Class Diagram written to: ${outFile}`);
+    return outFile;
+  } catch (e) {
+    console.error("Failed to generate Mermaid Class Diagram.", e);
+    return "";
+  }
+};
+
+// src/lib/MermaidERD/prismaMermaidErd.ts
+var import_internals2 = __toESM(require("@prisma/internals"), 1);
+var import_fs = require("fs");
+var import_node_fs2 = require("fs");
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/lib/MermaidERD/utils.ts
+var generateCardinality2 = ({
+  isList,
+  isRequired
+}) => {
+  if (isList) {
+    return "}|";
+  }
+  return isRequired ? "||" : "o|";
+};
+var getKeyConstraints = (isId, fieldName, foreignKeys, nativeTypes) => {
+  if (isId) return "PK";
+  if (nativeTypes) {
+    const allNativeTypes = nativeTypes.flatMap((nativeType) => nativeType);
+    if (!isId && allNativeTypes.includes("UniqueIdentifier")) {
+      return "FK";
+    }
+  }
+  if (!isId && foreignKeys.has(fieldName)) return "FK";
+  return "";
+};
+var getOptionalitySymbol = (isRequired) => {
+  return isRequired ? "" : `"?"`;
+};
+var generateRelationships2 = ({
+  relationships
+}) => {
+  const relationLines = [];
+  for (const relName in relationships) {
+    const sides = relationships[relName];
+    if (!sides) continue;
+    if (sides.length === 1) {
+      const a = sides[0];
+      if (!a) continue;
+      relationLines.push(
+        `	${a.model} ${generateCardinality2({
+          isList: a.isList,
+          isRequired: a.isRequired
+        })}--${generateCardinality2({ isList: false, isRequired: true })} ${a.fieldType} : ${relName}`
+      );
+    } else if (sides.length === 2) {
+      const a = sides[0];
+      const b = sides[1];
+      if (!a || !b) continue;
+      relationLines.push(
+        `	${a.model} ${generateCardinality2({
+          isList: a.isList,
+          isRequired: a.isRequired
+        })}--${generateCardinality2({
+          isList: b.isList,
+          isRequired: b.isRequired
+        })} ${b.model} : ${relName}`
+      );
+    } else {
+      for (let i = 1; i < sides.length; i++) {
+        const a = sides[0];
+        const b = sides[i];
+        if (!a || !b) continue;
+        relationLines.push(
+          `	${a.model} ${generateCardinality2({
+            isList: a.isList,
+            isRequired: a.isRequired
+          })}--${generateCardinality2({
+            isList: b.isList,
+            isRequired: b.isRequired
+          })} ${b.model} : ${relName}`
+        );
+      }
+    }
+  }
+  return relationLines;
+};
+
+// src/lib/MermaidERD/prismaMermaidErd.ts
+var { getDMMF: getDMMF2 } = import_internals2.default;
+var generateDiagram2 = async ({
+  outputPath,
+  schemaPath,
+  generatorPrismaDocument
+}) => {
+  const outputDir = outputPath ? import_node_path2.default.resolve(outputPath) : import_node_path2.default.join(`${process.cwd()}/src/generated/diagrams`);
+  try {
+    const prismaDocument = generatorPrismaDocument ?? await getDMMF2({
+      datamodel: (0, import_fs.readFileSync)(schemaPath, "utf-8")
+    });
+    const schemaModels = prismaDocument.datamodel.models;
+    const schemaEnums = prismaDocument.datamodel.enums;
+    console.dir(schemaEnums, { depth: null });
+    const mermaidLines = [
+      "%% --------------------------------------------",
+      "%% Auto-generated Mermaid ER Diagram. Do Not Edit Directly.",
+      "%% --------------------------------------------\n",
+      generateMermaidConfig(mermaidERDiagramConfig, schemaModels),
+      "erDiagram"
+    ];
+    const relationships = {};
+    schemaModels.forEach((model) => {
+      mermaidLines.push(`	${model.name} {`);
+      const foreignKeys = /* @__PURE__ */ new Set();
+      model.fields.forEach((field) => {
+        if (field.relationFromFields && field.relationFromFields.length > 0) {
+          field.relationFromFields.forEach((fk) => {
+            foreignKeys.add(fk);
+          });
+        }
+        mermaidLines.push(
+          `		${field.type} ${field.name} ${getKeyConstraints(
+            field.isId,
+            field.name,
+            foreignKeys,
+            field.nativeType
+          )} ${getOptionalitySymbol(field.isRequired)}`
+        );
+        if (field.relationName) {
+          if (!relationships[field.relationName]) {
+            relationships[field.relationName] = [];
+          }
+          relationships[field.relationName].push({
+            model: model.name,
+            fieldType: field.type,
+            isList: field.isList ?? false,
+            isRequired: field.isRequired ?? false
+          });
+        }
+      });
+      mermaidLines.push(`	}`);
+    });
+    schemaEnums.forEach((enumDef) => {
+      mermaidLines.push(`	${enumDef.name} {`);
+      enumDef.values.forEach((enumValue) => {
+        mermaidLines.push(`		${enumValue.name}`);
+      });
+      mermaidLines.push(`	}`);
+    });
+    const relationLines = generateRelationships2({ relationships });
+    const output = mermaidLines.concat(relationLines);
+    (0, import_node_fs2.mkdirSync)(outputDir, { recursive: true });
+    const outFile = import_node_path2.default.join(outputDir, "mermaidErdDiagram.mmd");
+    (0, import_fs.writeFileSync)(outFile, output.join("\n"));
+    console.log(`Mermaid ERD generated at: ${outFile}`);
+    return outFile;
+  } catch {
+    console.error("Failed to generate Mermaid ER Diagram.");
+    return "";
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  generateMermaidClass,
+  generateMermaidERD
+});

package/build/index.d.cts

@@ -0,0 +1,63 @@
+import { DMMF } from '@prisma/generator-helper';
+
+type GenerateDiagramOptions = {
+    generatorPrismaDocument?: DMMF.Document;
+    schemaPath: string;
+    outputPath: string | undefined;
+};
+type Relationships = {
+    [key: string]: Array<{
+        model: string;
+        fieldType: string;
+        isList: boolean;
+        isRequired: boolean;
+    }>;
+};
+type GenerateRelationshipOptions = {
+    relationships: Relationships;
+};
+type GenerateCardinalityOptions = {
+    isList: boolean;
+    isRequired: boolean;
+};
+type ClassCardinality = '"*"' | '"1"' | '"0..1"';
+type ERDCardinality = "||" | "}|" | "o|";
+type GenerateDiagram = (options: GenerateDiagramOptions) => Promise<string>;
+type GenerateRelationships = (options: GenerateRelationshipOptions) => string[];
+type GenerateCardinality = (options: GenerateCardinalityOptions) => ClassCardinality | ERDCardinality;
+type GenerateDiagramSpacingOptions = {
+    models: DMMF.Datamodel["models"];
+    baseNode: number;
+    baseEdge: number;
+};
+type PrismaGeneratorsKeys = "mermaid-erd" | "mermaid-class";
+
+/**
+ * Generates a Mermaid **Class Diagram** from a Prisma schema.
+ *
+ * This function reads the Prisma schema (via a provided DMMF document or by
+ * reading and parsing the schema file), extracts all models, enums, and
+ * relationships, and constructs a Mermaid `classDiagram` definition.
+ *
+ * The output file is written to:
+ *   `<outputPath>/mermaidClassDiagram.mmd`
+ * or, if `outputPath` is omitted:
+ *   `<projectRoot>/src/generated/diagrams/mermaidClassDiagram.mmd`
+ */
+declare const generateDiagram$1: ({ outputPath, schemaPath, generatorPrismaDocument, }: GenerateDiagramOptions) => Promise<string>;
+
+/**
+ * Generates a Mermaid ERD (Entity-Relationship Diagram) from a Prisma schema.
+ *
+ * This function reads the Prisma schema (either from the provided DMMF document
+ * or by loading and parsing the schema file), extracts all models, enums, and
+ * relationships, and then produces a `.mmd` Mermaid ER diagram file.
+ *
+ * The output file is written to:
+ *   `<outputPath>/mermaidErdDiagram.mmd`
+ * or, if no output path is provided:
+ *   `<projectRoot>/src/generated/diagrams/mermaidErdDiagram.mmd`
+ */
+declare const generateDiagram: ({ outputPath, schemaPath, generatorPrismaDocument, }: GenerateDiagramOptions) => Promise<string>;
+
+export { type ClassCardinality, type ERDCardinality, type GenerateCardinality, type GenerateCardinalityOptions, type GenerateDiagram, type GenerateDiagramOptions, type GenerateDiagramSpacingOptions, type GenerateRelationshipOptions, type GenerateRelationships, type PrismaGeneratorsKeys, type Relationships, generateDiagram$1 as generateMermaidClass, generateDiagram as generateMermaidERD };

package/build/index.d.ts

@@ -0,0 +1,63 @@
+import { DMMF } from '@prisma/generator-helper';
+
+type GenerateDiagramOptions = {
+    generatorPrismaDocument?: DMMF.Document;
+    schemaPath: string;
+    outputPath: string | undefined;
+};
+type Relationships = {
+    [key: string]: Array<{
+        model: string;
+        fieldType: string;
+        isList: boolean;
+        isRequired: boolean;
+    }>;
+};
+type GenerateRelationshipOptions = {
+    relationships: Relationships;
+};
+type GenerateCardinalityOptions = {
+    isList: boolean;
+    isRequired: boolean;
+};
+type ClassCardinality = '"*"' | '"1"' | '"0..1"';
+type ERDCardinality = "||" | "}|" | "o|";
+type GenerateDiagram = (options: GenerateDiagramOptions) => Promise<string>;
+type GenerateRelationships = (options: GenerateRelationshipOptions) => string[];
+type GenerateCardinality = (options: GenerateCardinalityOptions) => ClassCardinality | ERDCardinality;
+type GenerateDiagramSpacingOptions = {
+    models: DMMF.Datamodel["models"];
+    baseNode: number;
+    baseEdge: number;
+};
+type PrismaGeneratorsKeys = "mermaid-erd" | "mermaid-class";
+
+/**
+ * Generates a Mermaid **Class Diagram** from a Prisma schema.
+ *
+ * This function reads the Prisma schema (via a provided DMMF document or by
+ * reading and parsing the schema file), extracts all models, enums, and
+ * relationships, and constructs a Mermaid `classDiagram` definition.
+ *
+ * The output file is written to:
+ *   `<outputPath>/mermaidClassDiagram.mmd`
+ * or, if `outputPath` is omitted:
+ *   `<projectRoot>/src/generated/diagrams/mermaidClassDiagram.mmd`
+ */
+declare const generateDiagram$1: ({ outputPath, schemaPath, generatorPrismaDocument, }: GenerateDiagramOptions) => Promise<string>;
+
+/**
+ * Generates a Mermaid ERD (Entity-Relationship Diagram) from a Prisma schema.
+ *
+ * This function reads the Prisma schema (either from the provided DMMF document
+ * or by loading and parsing the schema file), extracts all models, enums, and
+ * relationships, and then produces a `.mmd` Mermaid ER diagram file.
+ *
+ * The output file is written to:
+ *   `<outputPath>/mermaidErdDiagram.mmd`
+ * or, if no output path is provided:
+ *   `<projectRoot>/src/generated/diagrams/mermaidErdDiagram.mmd`
+ */
+declare const generateDiagram: ({ outputPath, schemaPath, generatorPrismaDocument, }: GenerateDiagramOptions) => Promise<string>;
+
+export { type ClassCardinality, type ERDCardinality, type GenerateCardinality, type GenerateCardinalityOptions, type GenerateDiagram, type GenerateDiagramOptions, type GenerateDiagramSpacingOptions, type GenerateRelationshipOptions, type GenerateRelationships, type PrismaGeneratorsKeys, type Relationships, generateDiagram$1 as generateMermaidClass, generateDiagram as generateMermaidERD };