sol2uml 2.4.2 → 2.4.3

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Nick Addison
+Copyright (c) 2023 Nick Addison
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/lib/converterClasses2Storage.d.ts

@@ -1,4 +1,5 @@
 import { Attribute, UmlClass } from './umlClass';
+import { BigNumberish } from '@ethersproject/bignumber';
 export declare enum StorageType {
     Contract = "Contract",
     Struct = "Struct",
@@ -31,11 +32,20 @@ export interface Storage {
 }
 /**
  *
- * @param url
- * @param contractAddress Contract address to get the storage slot values from
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
  * @param storage is mutated with the storage values
+ * @param blockTag block number or `latest`
+ */
+export declare const addStorageValues: (url: string, contractAddress: string, storage: Storage, blockTag?: BigNumberish | 'latest') => Promise<void>;
+/**
+ *
+ * @param contractName name of the contract to get storage layout.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param contractFilename relative path of the contract in the file system
+ * @return array of storage objects with consecutive slots
  */
-export declare const addStorageValues: (url: string, contractAddress: string, storage: Storage, blockTag: string) => Promise<void>;
 export declare const convertClasses2Storages: (contractName: string, umlClasses: UmlClass[], contractFilename?: string) => Storage[];
 export declare const parseReferenceStorage: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[], storages: Storage[]) => Storage | undefined;
 export declare const calcStorageByteSize: (attribute: Attribute, umlClass: UmlClass, otherClasses: UmlClass[]) => {

package/lib/converterClasses2Storage.js

@@ -21,9 +21,11 @@ let storageId = 1;
 let variableId = 1;
 /**
  *
- * @param url
- * @param contractAddress Contract address to get the storage slot values from
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
  * @param storage is mutated with the storage values
+ * @param blockTag block number or `latest`
  */
 const addStorageValues = async (url, contractAddress, storage, blockTag) => {
     const valueVariables = storage.variables.filter((s) => !s.noValue);
@@ -34,6 +36,13 @@ const addStorageValues = async (url, contractAddress, storage, blockTag) => {
     });
 };
 exports.addStorageValues = addStorageValues;
+/**
+ *
+ * @param contractName name of the contract to get storage layout.
+ * @param umlClasses array of UML classes of type `UMLClass`
+ * @param contractFilename relative path of the contract in the file system
+ * @return array of storage objects with consecutive slots
+ */
 const convertClasses2Storages = (contractName, umlClasses, contractFilename) => {
     // Find the base UML Class from the base contract name
     const umlClass = umlClasses.find(({ name, relativePath }) => {

package/lib/slotValues.d.ts

@@ -1,3 +1,19 @@
 import { BigNumberish } from '@ethersproject/bignumber';
-export declare const getStorageValue: (url: string, contractAddress: string, slot: BigNumberish, blockTag?: BigNumberish | 'latest') => Promise<string>;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
+ * @param slots array of slot numbers to retrieve values for.
+ * @param blockTag block number or `latest`
+ */
 export declare const getStorageValues: (url: string, contractAddress: string, slots: BigNumberish[], blockTag?: BigNumberish | 'latest') => Promise<string[]>;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
+ * @param slot slot number to retrieve the value for.
+ * @param blockTag block number or `latest`
+ */
+export declare const getStorageValue: (url: string, contractAddress: string, slot: BigNumberish, blockTag?: BigNumberish | 'latest') => Promise<string>;

package/lib/slotValues.js

@@ -3,18 +3,19 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getStorageValues = exports.getStorageValue = void 0;
+exports.getStorageValue = exports.getStorageValues = void 0;
 const bignumber_1 = require("@ethersproject/bignumber");
 const axios_1 = __importDefault(require("axios"));
 const debug = require('debug')('sol2uml');
-const getStorageValue = async (url, contractAddress, slot, blockTag = 'latest') => {
-    debug(`About to get storage slot ${slot} value for ${contractAddress}`);
-    const values = await (0, exports.getStorageValues)(url, contractAddress, [slot], blockTag);
-    debug(`Got slot ${slot} value: ${values[0]}`);
-    return values[0];
-};
-exports.getStorageValue = getStorageValue;
 let jsonRpcId = 0;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
+ * @param slots array of slot numbers to retrieve values for.
+ * @param blockTag block number or `latest`
+ */
 const getStorageValues = async (url, contractAddress, slots, blockTag = 'latest') => {
     try {
         debug(`About to get ${slots.length} storage values for ${contractAddress} at block ${blockTag}`);
@@ -48,4 +49,19 @@ const getStorageValues = async (url, contractAddress, slots, blockTag = 'latest'
     }
 };
 exports.getStorageValues = getStorageValues;
+/**
+ * Get storage slot values from JSON-RPC API provider.
+ * @param url of Ethereum JSON-RPC API provider. eg Infura or Alchemy
+ * @param contractAddress Contract address to get the storage slot values from.
+ * If proxied, use proxy and not the implementation contract.
+ * @param slot slot number to retrieve the value for.
+ * @param blockTag block number or `latest`
+ */
+const getStorageValue = async (url, contractAddress, slot, blockTag = 'latest') => {
+    debug(`About to get storage slot ${slot} value for ${contractAddress}`);
+    const values = await (0, exports.getStorageValues)(url, contractAddress, [slot], blockTag);
+    debug(`Got slot ${slot} value: ${values[0]}`);
+    return values[0];
+};
+exports.getStorageValue = getStorageValue;
 //# sourceMappingURL=slotValues.js.map

package/lib/sol2uml.js

@@ -103,7 +103,7 @@ If an Ethereum address with a 0x prefix is passed, the verified source code from
         // Convert UML classes to Graphviz dot format.
         const dotString = (0, converterClasses2Dot_1.convertUmlClasses2Dot)(filteredUmlClasses, combinedOptions.clusterFolders, combinedOptions);
         // Convert Graphviz dot format to file formats. eg svg or png
-        await (0, writerFiles_1.writeOutputFiles)(dotString, fileFolderAddress, contractName || 'classDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
+        await (0, writerFiles_1.writeOutputFiles)(dotString, contractName || 'classDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
         debug(`Finished generating UML`);
     }
     catch (err) {
@@ -160,10 +160,10 @@ WARNING: sol2uml does not use the Solidity compiler so may differ with solc. A k
             const storage = storages.find((so) => so.name === contractName);
             if (!storageAddress)
                 throw Error(`Could not find the "${contractName}" contract in list of parsed storages`);
-            await (0, converterClasses2Storage_1.addStorageValues)(combinedOptions.url, storageAddress, storage, combinedOptions.blockNumber);
+            await (0, converterClasses2Storage_1.addStorageValues)(combinedOptions.url, storageAddress, storage, combinedOptions.block);
         }
         const dotString = (0, converterStorage2Dot_1.convertStorages2Dot)(storages, combinedOptions);
-        await (0, writerFiles_1.writeOutputFiles)(dotString, fileFolderAddress, contractName || 'storageDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
+        await (0, writerFiles_1.writeOutputFiles)(dotString, contractName || 'storageDiagram', combinedOptions.outputFormat, combinedOptions.outputFileName);
     }
     catch (err) {
         console.error(err.stack);

package/lib/writerFiles.d.ts

@@ -1,7 +1,27 @@
 export type OutputFormats = 'svg' | 'png' | 'dot' | 'all';
-export declare const writeOutputFiles: (dot: string, fileFolderAddress: string, contractName: string, outputFormat?: OutputFormats, outputFilename?: string) => Promise<void>;
+/**
+ * Writes output files to the file system based on the provided input and options.
+ * @param dot The input string in DOT format.
+ * @param contractName The name of the contract.
+ * @param outputFormat The format of the output file. choices: svg, png, dot or all. default: png
+ * @param outputFilename optional filename of the output file.
+ */
+export declare const writeOutputFiles: (dot: string, contractName: string, outputFormat?: OutputFormats, outputFilename?: string) => Promise<void>;
 export declare function convertDot2Svg(dot: string): any;
 export declare function writeSolidity(code: string, filename?: string): void;
 export declare function writeDot(dot: string, filename: string): void;
+/**
+ * Writes an SVG file to the file system.
+ * @param svg The SVG input to be written to the file system.
+ * @param svgFilename The desired file name for the SVG file. default: classDiagram.svg
+ * @param outputFormats The format of the output file. choices: svg, png, dot or all. default: png
+ * @throws Error - If there is an error writing the SVG file.
+ */
 export declare function writeSVG(svg: any, svgFilename?: string, outputFormats?: OutputFormats): Promise<void>;
+/**
+ * Asynchronously writes a PNG file to the file system from an SVG input.
+ * @param svg - The SVG input to be converted to a PNG file.
+ * @param filename - The desired file name for the PNG file.
+ * @throws Error - If there is an error converting or writing the PNG file.
+ */
 export declare function writePng(svg: any, filename: string): Promise<void>;

package/lib/writerFiles.js

@@ -9,7 +9,14 @@ const path_1 = __importDefault(require("path"));
 const sync_1 = __importDefault(require("@aduh95/viz.js/sync"));
 const { convert } = require('convert-svg-to-png');
 const debug = require('debug')('sol2uml');
-const writeOutputFiles = async (dot, fileFolderAddress, contractName, outputFormat = 'svg', outputFilename) => {
+/**
+ * Writes output files to the file system based on the provided input and options.
+ * @param dot The input string in DOT format.
+ * @param contractName The name of the contract.
+ * @param outputFormat The format of the output file. choices: svg, png, dot or all. default: png
+ * @param outputFilename optional filename of the output file.
+ */
+const writeOutputFiles = async (dot, contractName, outputFormat = 'svg', outputFilename) => {
     // If all output then extension is svg
     const outputExt = outputFormat === 'all' ? 'svg' : outputFormat;
     if (!outputFilename) {
@@ -87,6 +94,13 @@ function writeDot(dot, filename) {
     });
 }
 exports.writeDot = writeDot;
+/**
+ * Writes an SVG file to the file system.
+ * @param svg The SVG input to be written to the file system.
+ * @param svgFilename The desired file name for the SVG file. default: classDiagram.svg
+ * @param outputFormats The format of the output file. choices: svg, png, dot or all. default: png
+ * @throws Error - If there is an error writing the SVG file.
+ */
 function writeSVG(svg, svgFilename = 'classDiagram.svg', outputFormats = 'png') {
     debug(`About to write SVN file to ${svgFilename}`);
     if (outputFormats === 'png') {
@@ -113,6 +127,12 @@ function writeSVG(svg, svgFilename = 'classDiagram.svg', outputFormats = 'png')
     });
 }
 exports.writeSVG = writeSVG;
+/**
+ * Asynchronously writes a PNG file to the file system from an SVG input.
+ * @param svg - The SVG input to be converted to a PNG file.
+ * @param filename - The desired file name for the PNG file.
+ * @throws Error - If there is an error converting or writing the PNG file.
+ */
 async function writePng(svg, filename) {
     // get svg file name from png file name
     const parsedPngFile = path_1.default.parse(filename);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sol2uml",
-  "version": "2.4.2",
+  "version": "2.4.3",
   "description": "Solidity contract visualisation tool.",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -35,11 +35,11 @@
   "devDependencies": {
     "@openzeppelin/contracts": "4.8.0",
     "@types/diff-match-patch": "^1.0.32",
-    "@types/jest": "^29.2.4",
+    "@types/jest": "^29.4.0",
     "@types/klaw": "^3.0.3",
-    "jest": "^29.3.1",
-    "prettier": "^2.8.1",
-    "ts-jest": "^29.0.3",
+    "jest": "^29.4.1",
+    "prettier": "^2.8.3",
+    "ts-jest": "^29.0.5",
     "ts-node": "^10.9.1",
     "typescript": "^4.9.4"
   },