├── tsconfig.json ├── tsconfig.cjs.json ├── SECURITY.md ├── src ├── index.ts ├── utils │ └── pixelLevelDiffPng.ts ├── validate.ts ├── extra-apply │ ├── applySvg2Png.ts │ ├── applyDiffSvg.ts │ └── applyRemoveNanCoordinates.ts └── common.ts ├── .github └── workflows │ ├── npm-publish.yml │ └── codeql.yml ├── package.json ├── LICENSE ├── .gitignore └── README.md /tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ESNext", 4 | "module": "ESNext", 5 | "lib": [ 6 | "ESNext", 7 | "DOM" 8 | ], 9 | "outDir": "es", 10 | "sourceMap": true, 11 | "declaration": true, 12 | "strict": true, 13 | "esModuleInterop": true, 14 | "skipLibCheck": true, 15 | "moduleResolution": "node", 16 | "allowSyntheticDefaultImports": true 17 | }, 18 | "include": [ 19 | "src/**/*" 20 | ] 21 | } -------------------------------------------------------------------------------- /tsconfig.cjs.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "es5", 4 | "module": "CommonJS", 5 | "lib": [ 6 | "es2015", 7 | "dom" 8 | ], 9 | "outDir": "lib", 10 | "sourceMap": true, 11 | "declaration": true, 12 | "strict": true, 13 | "esModuleInterop": true, 14 | "skipLibCheck": true, 15 | "moduleResolution": "node", 16 | "allowSyntheticDefaultImports": true 17 | }, 18 | "include": [ 19 | "src/**/*" 20 | ] 21 | } -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Supported Versions 4 | 5 | Use this section to tell people about which versions of your project are 6 | currently being supported with security updates. 7 | 8 | | Version | Supported | 9 | | ------- | ------------------ | 10 | | 5.1.x | :white_check_mark: | 11 | | 5.0.x | :x: | 12 | | 4.0.x | :white_check_mark: | 13 | | < 4.0 | :x: | 14 | 15 | ## Reporting a Vulnerability 16 | 17 | Use this section to tell people how to report a vulnerability. 18 | 19 | Tell them where to go, how often they can expect to get an update on a 20 | reported vulnerability, what to expect if the vulnerability is accepted or 21 | declined, etc. 22 | -------------------------------------------------------------------------------- /src/index.ts: -------------------------------------------------------------------------------- 1 | import svg2Png from './extra-apply/applySvg2Png'; 2 | import diffSvg from './extra-apply/applyDiffSvg'; 3 | import removeNanCoordinates from './extra-apply/applyRemoveNanCoordinates'; 4 | import { createSVGElement, cloneSVGElement, mergeSVGElements, convertSVGToBase64, convertBase64ToSVG } from './common' 5 | import pixelLevelDiffPng from './utils/pixelLevelDiffPng'; 6 | 7 | const removeEmptyCoordinates = removeNanCoordinates 8 | 9 | export { 10 | svg2Png, 11 | diffSvg, 12 | /** 13 | * @deprecated 14 | * @see removeNanCoordinates 15 | */ 16 | removeEmptyCoordinates, 17 | removeNanCoordinates, 18 | createSVGElement, cloneSVGElement, mergeSVGElements, convertSVGToBase64, convertBase64ToSVG, 19 | pixelLevelDiffPng 20 | }; -------------------------------------------------------------------------------- /.github/workflows/npm-publish.yml: -------------------------------------------------------------------------------- 1 | # This workflow will run tests using node and then publish a package to GitHub Packages when a release is created 2 | # For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages 3 | 4 | name: Publish NPM Package 5 | 6 | on: 7 | workflow_dispatch: 8 | 9 | jobs: 10 | build: 11 | runs-on: ubuntu-latest 12 | steps: 13 | - uses: actions/checkout@v4 14 | - uses: actions/setup-node@v4 15 | with: 16 | node-version: 20 17 | - run: npm ci 18 | 19 | publish-npm: 20 | needs: build 21 | runs-on: ubuntu-latest 22 | steps: 23 | - uses: actions/checkout@v4 24 | - uses: actions/setup-node@v4 25 | with: 26 | node-version: 20 27 | registry-url: https://registry.npmjs.org/ 28 | - run: npm ci 29 | - run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> ./.npmrc 30 | - run: npm publish 31 | env: 32 | NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}} 33 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "svg-toolbox", 3 | "version": "1.1.11", 4 | "description": "This library provides some SVG-related tools", 5 | "main": "lib/index.js", 6 | "module": "es/index.js", 7 | "types": "es/index.d.ts", 8 | "files": [ 9 | "lib", 10 | "es", 11 | "LICENSE", 12 | "README.md" 13 | ], 14 | "repository": { 15 | "type": "git", 16 | "url": "git+https://github.com/SteamedBread2333/svg-toolbox.git" 17 | }, 18 | "scripts": { 19 | "build:es": "tsc -p tsconfig.json", 20 | "build:cjs": "tsc -p tsconfig.cjs.json", 21 | "build": "npm run build:es && npm run build:cjs", 22 | "prepublishOnly": "npm run build" 23 | }, 24 | "keywords": [ 25 | "svg" 26 | ], 27 | "author": "pipi", 28 | "license": "MIT", 29 | "dependencies": { 30 | "jsdom": "^26.0.0", 31 | "pixelmatch": "5.3.0", 32 | "pngjs": "^7.0.0", 33 | "sharp": "^0.33.5" 34 | }, 35 | "devDependencies": { 36 | "@types/jsdom": "^21.1.7", 37 | "@types/node": "^22.10.7", 38 | "@types/pixelmatch": "^5.2.6", 39 | "@types/pngjs": "^6.0.5", 40 | "typescript": "^5.7.3" 41 | } 42 | } 43 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 pipi 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /src/utils/pixelLevelDiffPng.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file pixelLevelDiffSvg.ts 3 | * @description This module provides a function to compare two SVG files and generate a diff image. 4 | * @module applyDiffSvg 5 | * @requires pixelmatch - Image comparison library 6 | * @requires pngjs - PNG image processing library 7 | * @author pipi 8 | */ 9 | import { PNG } from "pngjs"; 10 | import pixelmatch from 'pixelmatch'; 11 | 12 | export default function (pngA: Buffer, pngB: Buffer, threshold: number = 0.1): { diffPngBuffer: Buffer, numDiffPixels: number } { 13 | // Decode the PNG buffers 14 | const img1 = PNG.sync.read(pngA); 15 | const img2 = PNG.sync.read(pngB); 16 | const { width, height } = img1; 17 | 18 | // Create a new PNG object for the diff image 19 | const diff = new PNG({ width, height }); 20 | 21 | // Compare the images and get the number of different pixels 22 | const numDiffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, { threshold }); 23 | 24 | // Write the diff image to a buffer 25 | const diffPngBuffer = PNG.sync.write(diff); 26 | 27 | return { 28 | // The diff image buffer 29 | diffPngBuffer, 30 | // The number of different pixels 31 | numDiffPixels 32 | }; 33 | } -------------------------------------------------------------------------------- /src/validate.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file validate.ts 3 | * @description This module provides functions to validate SVG content. 4 | * @module validate 5 | * @author pipi 6 | */ 7 | import { JSDOM } from 'jsdom'; 8 | 9 | /** 10 | * Validates whether the provided content is a valid SVG string. 11 | * 12 | * @param content - The content to be validated (could be a string or another type). 13 | * @returns True if the content is a valid SVG string, false otherwise. 14 | */ 15 | export function isValidSvgString(content: any): boolean { 16 | // Check if the content is of type string. If not, it cannot be a valid SVG string. 17 | if (typeof content !== 'string') { 18 | return false; 19 | } 20 | 21 | try { 22 | // Create a virtual DOM environment 23 | const dom = new JSDOM(content); 24 | // Parse the content as SVG and check if the root node is an SVG element. 25 | const rootNode = new dom.window.DOMParser().parseFromString(content, 'image/svg+xml').documentElement; 26 | // Return true if the root node is an SVG element, false otherwise. 27 | return rootNode.nodeName.toLowerCase() === 'svg'; 28 | } catch (error) { 29 | // If there's an error during parsing, it's not a valid SVG string. 30 | return false; 31 | } 32 | } 33 | 34 | /** 35 | * Validates whether the provided content is a valid SVG element. 36 | * 37 | * @param content - The content to be validated (could be an Element or another type). 38 | * @returns True if the content is a valid SVG element, false otherwise. 39 | */ 40 | export function isValidSvgElement(content: any): boolean { 41 | // Check if the content is an instance of Element and its tag name is 'svg' 42 | return ( 43 | content && 44 | typeof content === 'object' && 45 | content.tagName.toLowerCase() === 'svg' 46 | ); 47 | } -------------------------------------------------------------------------------- /src/extra-apply/applySvg2Png.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file applySvg2Png.js 3 | * @description This module provides a function to convert SVG files to PNG format using the sharp library. 4 | * @module applySvg2Png 5 | * @requires sharp - Image processing library 6 | * @requires fs - File system module 7 | * @author pipi 8 | */ 9 | 10 | import fs from 'fs'; 11 | import sharp from 'sharp'; 12 | 13 | /** 14 | * Converts an SVG file to PNG format. 15 | * @param {string} svgPath - The path to read the SVG file. 16 | * @param {string} pngPath - The path to save the PNG file. if not provided, return the buffer. 17 | * @param {number} x - The scaling factor for the PNG image. 18 | * @returns {Promise>} - The PNG image buffer. 19 | */ 20 | export default async function (svgPath: string, pngPath?: string, x?: number): Promise> { 21 | if (!svgPath) { 22 | console.error('Error converting to PNG: No svg file path provided.'); 23 | return; 24 | } 25 | if (!pngPath) { 26 | console.log(`\x1b[33mNo png file path provided, return the buffer.\x1b[0m`); 27 | } 28 | if (!x) { 29 | x = 2 30 | console.log(`\x1b[33mNo scaling factor provided, use the default value 2.\x1b[0m`); 31 | } 32 | // Read the SVG file 33 | const file = svgPath.split('/').pop(); 34 | const svgContent = fs.readFileSync(svgPath, 'utf8'); 35 | 36 | // Extract the viewBox from the SVG content 37 | const viewBoxRegex = /viewBox="(\d+) (\d+) (\d+) (\d+)"/; 38 | const viewBoxMatch = viewBoxRegex.exec(svgContent); 39 | 40 | if (!viewBoxMatch) { 41 | console.error(`Error converting ${file} to PNG: No viewBox found.`); 42 | return; 43 | } 44 | 45 | // Extract the width and height from the viewBox 46 | const [, , , baseWidth, baseHeight] = viewBoxMatch.map(Number); 47 | 48 | if (pngPath) { 49 | // Resize the SVG to the desired dimensions and convert it to PNG 50 | sharp(svgPath) 51 | .resize(x * baseWidth, x * baseHeight) 52 | .png() 53 | .toFile(pngPath) 54 | .then(() => { 55 | console.log(`\x1b[32mConverted ${file} to PNG successfully.\x1b[0m`); 56 | }) 57 | .catch(error => { 58 | console.error(`Error converting ${file} to PNG:`, error); 59 | }); 60 | } else { 61 | // Resize the SVG to the desired dimensions and convert it to PNG 62 | const buffer = await sharp(svgPath) 63 | .resize(x * baseWidth, x * baseHeight) 64 | .png() 65 | .toBuffer() 66 | return buffer; 67 | } 68 | } -------------------------------------------------------------------------------- /src/extra-apply/applyDiffSvg.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file applyDiffSvg.js 3 | * @description This module provides a function to compare two PNG images and generate a diff image using the sharp and pixelmatch libraries. 4 | * @module applyDiffSvg 5 | * @requires sharp - Image processing library 6 | * @requires pixelmatch - Image comparison library 7 | * @requires fs - File system module 8 | * @requires path - Path module 9 | * @author pipi 10 | */ 11 | import fs from 'fs'; 12 | import sharp from 'sharp'; 13 | import path from 'path'; 14 | import pixelLevelDiffSvg from '../utils/pixelLevelDiffPng'; 15 | 16 | /** 17 | * Checks if the filename has a valid suffix. 18 | * @param {string} filename - The name of the file. 19 | * @returns {boolean} - True if the filename has a suffix, false otherwise. 20 | */ 21 | function validSuffix(filename: string) { 22 | return path.extname(filename) !== ''; 23 | } 24 | 25 | /** 26 | * Compares two SVG files and generates a diff image. 27 | * @param {string} pathA - The path to the first SVG file. 28 | * @param {string} pathB - The path to the second SVG file. 29 | * @param {string} diffFilePath - The path to save the diff image. 30 | * @returns - The diff image buffer and the number of different pixels. 31 | */ 32 | export default async function (pathA: string, pathB: string, diffFilePath: string): Promise<{ diffPngBuffer: Buffer, numDiffPixels: number } | void> { 33 | let diffFileName = ''; 34 | // If a diff file path is provided, save the diff image 35 | if (diffFilePath) { 36 | diffFileName = path.basename(diffFilePath); 37 | if (!validSuffix(diffFileName)) { 38 | console.error(`Error converting ${diffFileName} to PNG: No suffix found.`); 39 | return; 40 | } 41 | } else { 42 | console.error('Error converting to PNG: No diff file path provided.'); 43 | return; 44 | } 45 | // Read the PNG files as buffers 46 | const pngA = await sharp(pathA).toBuffer(); 47 | const pngB = await sharp(pathB).toBuffer(); 48 | 49 | const { diffPngBuffer, numDiffPixels } = pixelLevelDiffSvg(pngA, pngB, 0.1); 50 | fs.writeFileSync(diffFilePath, diffPngBuffer); 51 | // Log the result 52 | if (numDiffPixels === 0) { 53 | console.log(`\x1b[32mFile name: ${diffFileName} Number of different pixels: ${numDiffPixels}\x1b[0m`); 54 | } else { 55 | console.log(`\x1b[33mFile name: ${diffFileName} Number of different pixels: ${numDiffPixels}\x1b[0m`); 56 | } 57 | 58 | return { 59 | // The diff image buffer 60 | diffPngBuffer, 61 | // The number of different pixels 62 | numDiffPixels 63 | }; 64 | } -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | lerna-debug.log* 8 | .pnpm-debug.log* 9 | 10 | # Diagnostic reports (https://nodejs.org/api/report.html) 11 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 12 | 13 | # Runtime data 14 | pids 15 | *.pid 16 | *.seed 17 | *.pid.lock 18 | 19 | # Directory for instrumented libs generated by jscoverage/JSCover 20 | lib-cov 21 | 22 | # Coverage directory used by tools like istanbul 23 | coverage 24 | *.lcov 25 | 26 | # nyc test coverage 27 | .nyc_output 28 | 29 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 30 | .grunt 31 | 32 | # Bower dependency directory (https://bower.io/) 33 | bower_components 34 | 35 | # node-waf configuration 36 | .lock-wscript 37 | 38 | # Compiled binary addons (https://nodejs.org/api/addons.html) 39 | build/Release 40 | 41 | # Dependency directories 42 | node_modules/ 43 | jspm_packages/ 44 | 45 | # Snowpack dependency directory (https://snowpack.dev/) 46 | web_modules/ 47 | 48 | # TypeScript cache 49 | *.tsbuildinfo 50 | 51 | # Optional npm cache directory 52 | .npm 53 | 54 | # Optional eslint cache 55 | .eslintcache 56 | 57 | # Optional stylelint cache 58 | .stylelintcache 59 | 60 | # Microbundle cache 61 | .rpt2_cache/ 62 | .rts2_cache_cjs/ 63 | .rts2_cache_es/ 64 | .rts2_cache_umd/ 65 | 66 | # Optional REPL history 67 | .node_repl_history 68 | 69 | # Output of 'npm pack' 70 | *.tgz 71 | 72 | # Yarn Integrity file 73 | .yarn-integrity 74 | 75 | # dotenv environment variable files 76 | .env 77 | .env.development.local 78 | .env.test.local 79 | .env.production.local 80 | .env.local 81 | 82 | # parcel-bundler cache (https://parceljs.org/) 83 | .cache 84 | .parcel-cache 85 | 86 | # Next.js build output 87 | .next 88 | out 89 | 90 | # Nuxt.js build / generate output 91 | .nuxt 92 | dist 93 | 94 | # Gatsby files 95 | .cache/ 96 | # Comment in the public line in if your project uses Gatsby and not Next.js 97 | # https://nextjs.org/blog/next-9-1#public-directory-support 98 | # public 99 | 100 | # vuepress build output 101 | .vuepress/dist 102 | 103 | # vuepress v2.x temp and cache directory 104 | .temp 105 | .cache 106 | 107 | # Docusaurus cache and generated files 108 | .docusaurus 109 | 110 | # Serverless directories 111 | .serverless/ 112 | 113 | # FuseBox cache 114 | .fusebox/ 115 | 116 | # DynamoDB Local files 117 | .dynamodb/ 118 | 119 | # TernJS port file 120 | .tern-port 121 | 122 | # Stores VSCode versions used for testing VSCode extensions 123 | .vscode-test 124 | 125 | # yarn v2 126 | .yarn/cache 127 | .yarn/unplugged 128 | .yarn/build-state.yml 129 | .yarn/install-state.gz 130 | .pnp.* 131 | 132 | es/ 133 | lib/ 134 | test/ 135 | example/ 136 | test.js -------------------------------------------------------------------------------- /src/extra-apply/applyRemoveNanCoordinates.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file applyRemoveNanCoordinates.js 3 | * @description This module provides a function to parse and normalize the 'd' attribute of all path elements in an SVG content. 4 | * @requires jsdom - JavaScript DOM library 5 | * @module applyRemoveNanCoordinates 6 | * @author pipi 7 | */ 8 | import { JSDOM } from 'jsdom'; 9 | 10 | // Define the types of path commands that do not have parameters 11 | const ignoreTypes = ['z', 'Z']; 12 | 13 | /** 14 | * Parses and normalizes the 'd' attribute of all path elements in an SVG content. 15 | * @param {*} svgContent 16 | * @returns 17 | */ 18 | export default function (svgContent: string): string { 19 | // Create a DOM from the SVG content 20 | const dom = new JSDOM(svgContent, { 21 | contentType: 'image/svg+xml' // Set content type to SVG 22 | }); 23 | // Get the document and SVG element 24 | const document = dom.window.document; 25 | // Get the SVG element 26 | const svgElement = document.querySelector('svg'); 27 | 28 | // Check if an SVG element was found 29 | if (!svgElement) { 30 | throw new Error('No SVG element found in the provided content.'); 31 | } 32 | 33 | const paths = svgElement.querySelectorAll('path'); 34 | // Iterate over each path element 35 | Array.from(paths).forEach((path) => { 36 | const d = path.getAttribute('d'); // Get the 'd' attribute 37 | if (d === null) { 38 | return; 39 | } 40 | // Split the 'd' attribute into commands and parameters 41 | const commands = d 42 | // Remove 'nan' and '-nan' values 43 | .replace(/nan|-nan/g, ' ') 44 | // Split the 'd' attribute into commands and parameters. path command: M, L, H, V, C, S, Q, T, A, Z, z. 45 | // -> https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/d#path_commands 46 | .split(/(?=[MmLlHhVvCcSsQqTtAaZz])/).map((command) => { 47 | // Split each command into type and parameters 48 | const type = command[0]; 49 | // If the command is not 'z' or 'Z', then it has parameters. 50 | const ignoreType = ignoreTypes.includes(type) 51 | if (!ignoreType) { 52 | // Split parameters by spaces or commas, filter out empty values, and convert to numbers 53 | const params = command.slice(1).split(/[\s,]+/) 54 | // Filter out non-numeric values 55 | const pickCommand = params.every(Number) 56 | if (pickCommand) { 57 | return { type, params }; 58 | } 59 | } else { 60 | return { type, params: [] }; 61 | } 62 | }) 63 | // Filter out undefined values 64 | .filter((item) => item !== void 0) 65 | // Filter out commands with no parameters, or commands with only 'z' or 'Z'. 'Zz' means close the path. 66 | // -> https://developer.mozilla.org/zh-CN/docs/Web/SVG/Attribute/d#closepath 67 | .filter((command) => (ignoreTypes.includes(command.type) || command.params.length > 0)); 68 | // Reconstruct the 'd' attribute 69 | const modifiedD = commands.map((command) => { 70 | return command.type + command.params.join(' '); 71 | }).join(''); 72 | path.setAttribute('d', modifiedD); // Set the modified 'd' attribute 73 | }); 74 | 75 | // Get the new SVG content 76 | const newSvgContent = svgElement.outerHTML.trim(); 77 | return newSvgContent; 78 | } -------------------------------------------------------------------------------- /.github/workflows/codeql.yml: -------------------------------------------------------------------------------- 1 | # For most projects, this workflow file will not need changing; you simply need 2 | # to commit it to your repository. 3 | # 4 | # You may wish to alter this file to override the set of languages analyzed, 5 | # or to provide custom queries or build logic. 6 | # 7 | # ******** NOTE ******** 8 | # We have attempted to detect the languages in your repository. Please check 9 | # the `language` matrix defined below to confirm you have the correct set of 10 | # supported CodeQL languages. 11 | # 12 | name: "CodeQL Advanced" 13 | 14 | on: 15 | workflow_dispatch: 16 | 17 | jobs: 18 | analyze: 19 | name: Analyze (${{ matrix.language }}) 20 | # Runner size impacts CodeQL analysis time. To learn more, please see: 21 | # - https://gh.io/recommended-hardware-resources-for-running-codeql 22 | # - https://gh.io/supported-runners-and-hardware-resources 23 | # - https://gh.io/using-larger-runners (GitHub.com only) 24 | # Consider using larger runners or machines with greater resources for possible analysis time improvements. 25 | runs-on: ${{ (matrix.language == 'swift' && 'macos-latest') || 'ubuntu-latest' }} 26 | permissions: 27 | # required for all workflows 28 | security-events: write 29 | 30 | # required to fetch internal or private CodeQL packs 31 | packages: read 32 | 33 | # only required for workflows in private repositories 34 | actions: read 35 | contents: read 36 | 37 | strategy: 38 | fail-fast: false 39 | matrix: 40 | include: 41 | - language: javascript-typescript 42 | build-mode: none 43 | # CodeQL supports the following values keywords for 'language': 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift' 44 | # Use `c-cpp` to analyze code written in C, C++ or both 45 | # Use 'java-kotlin' to analyze code written in Java, Kotlin or both 46 | # Use 'javascript-typescript' to analyze code written in JavaScript, TypeScript or both 47 | # To learn more about changing the languages that are analyzed or customizing the build mode for your analysis, 48 | # see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning. 49 | # If you are analyzing a compiled language, you can modify the 'build-mode' for that language to customize how 50 | # your codebase is analyzed, see https://docs.github.com/en/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/codeql-code-scanning-for-compiled-languages 51 | steps: 52 | - name: Checkout repository 53 | uses: actions/checkout@v4 54 | 55 | # Add any setup steps before running the `github/codeql-action/init` action. 56 | # This includes steps like installing compilers or runtimes (`actions/setup-node` 57 | # or others). This is typically only required for manual builds. 58 | # - name: Setup runtime (example) 59 | # uses: actions/setup-example@v1 60 | 61 | # Initializes the CodeQL tools for scanning. 62 | - name: Initialize CodeQL 63 | uses: github/codeql-action/init@v3 64 | with: 65 | languages: ${{ matrix.language }} 66 | build-mode: ${{ matrix.build-mode }} 67 | # If you wish to specify custom queries, you can do so here or in a config file. 68 | # By default, queries listed here will override any specified in a config file. 69 | # Prefix the list here with "+" to use these queries and those in the config file. 70 | 71 | # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs 72 | # queries: security-extended,security-and-quality 73 | 74 | # If the analyze step fails for one of the languages you are analyzing with 75 | # "We were unable to automatically build your code", modify the matrix above 76 | # to set the build mode to "manual" for that language. Then modify this step 77 | # to build your code. 78 | # ℹ️ Command-line programs to run using the OS shell. 79 | # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun 80 | - if: matrix.build-mode == 'manual' 81 | shell: bash 82 | run: | 83 | echo 'If you are using a "manual" build mode for one or more of the' \ 84 | 'languages you are analyzing, replace this with the commands to build' \ 85 | 'your code, for example:' 86 | echo ' make bootstrap' 87 | echo ' make release' 88 | exit 1 89 | 90 | - name: Perform CodeQL Analysis 91 | uses: github/codeql-action/analyze@v3 92 | with: 93 | category: "/language:${{matrix.language}}" 94 | -------------------------------------------------------------------------------- /src/common.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * @file utils.ts 3 | * @description This module provides utility functions for working with SVG elements. 4 | * @module utils 5 | * @requires jsdom - A JavaScript implementation of the WHATWG DOM and HTML standards. 6 | * @author pipi 7 | */ 8 | 9 | import { JSDOM } from 'jsdom'; 10 | import { isValidSvgElement, isValidSvgString } from './validate'; 11 | 12 | // Create a virtual DOM environment 13 | const dom = new JSDOM(``); 14 | const { document } = dom.window; 15 | 16 | /** 17 | * Creates an SVG element from a given element. 18 | * 19 | * This function serializes the given element to a string, then parses it back to create an SVG element. 20 | * This approach ensures that the element is correctly parsed as an SVG element. 21 | * 22 | * @param {Element} element - The element to create an SVG element from. 23 | * @returns {Element} - The created SVG element. 24 | * @see URL_ADDRESS * @see https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-6ED8C4D5 - DOM Level 2 Core spe 25 | * @see URL_ADDRESS.w3.org/TR/DOM-Level-2-Core/core.html#ID-6ED8C4D5 - DOM Level 2 Core specification 26 | * @see URL_ADDRESS * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLSerializer - XMLSerializer documentation 27 | */ 28 | export function createSVGElement(svgContent: string): Element { 29 | const svgElement = new dom.window.DOMParser().parseFromString(svgContent, 'image/svg+xml').documentElement; 30 | return svgElement 31 | } 32 | 33 | /** 34 | * Clones an SVG element deeply. 35 | * 36 | * This function serializes the given SVG element to a string, then parses it back to create a deep clone. 37 | * This approach ensures that all attributes and child nodes are duplicated. 38 | * 39 | * @param {Element} element - The SVG element to clone. 40 | * @returns {Element} - The cloned SVG element. 41 | * @see https://www.w3.org/TR/DOM-Level-2-Core/core.html#ID-6ED8C4D5 - DOM Level 2 Core specification 42 | * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLSerializer - XMLSerializer documentation 43 | */ 44 | export function cloneSVGElement(element: Element): Element { 45 | const serializer = new dom.window.XMLSerializer(); 46 | const sourceCode = serializer.serializeToString(element); 47 | const parser = new dom.window.DOMParser(); 48 | const doc = parser.parseFromString(sourceCode, 'image/svg+xml'); 49 | return doc.documentElement!; 50 | } 51 | 52 | /** 53 | * Merges multiple SVG elements into a single SVG element. 54 | * 55 | * This function creates a new SVG element and appends clones of the provided elements to it. 56 | * The SVG namespace is specified as 'http://www.w3.org/2000/svg'. 57 | * 58 | * @param {Element[]} elements - An array of SVG elements to merge. 59 | * @returns {Element} - The merged SVG element. 60 | * @see https://www.w3.org/TR/SVG/ - SVG specification 61 | * @see https://developer.mozilla.org/en-US/docs/Web/API/Document/createElementNS - createElementNS documentation 62 | */ 63 | export function mergeSVGElements(elements: Element[]): Element { 64 | const mergedSVG = document.createElementNS('http://www.w3.org/2000/svg', 'svg'); 65 | elements.forEach((element) => { 66 | mergedSVG.appendChild(cloneSVGElement(element)); 67 | }); 68 | return mergedSVG; 69 | } 70 | 71 | /** 72 | * Converts an SVG element or SVG string to a Base64-encoded string. 73 | * 74 | * This function serializes the SVG element or SVG string to a string and then encodes it to Base64. 75 | * The resulting string can be used as a data URI for embedding SVG content in HTML or CSS. 76 | * 77 | * @param {Element | string} svgContent - The SVG element or SVG string to convert. 78 | * @returns {string} - The Base64-encoded string representation of the SVG element. 79 | * @see https://developer.mozilla.org/en-US/docs/Web/API/XMLSerializer - XMLSerializer documentation 80 | * @see https://developer.mozilla.org/en-US/docs/Web/API/Buffer - Buffer documentation 81 | */ 82 | export function convertSVGToBase64(svgContent: Element | string): string { 83 | let svgString: string; 84 | if (isValidSvgString(svgContent)) { 85 | svgString = svgContent as string; 86 | } else if (isValidSvgElement(svgContent)) { 87 | const serializer = new dom.window.XMLSerializer(); 88 | svgString = serializer.serializeToString(svgContent as Element); 89 | } else { 90 | throw new Error('The provided content is not a valid SVG string or SVG element.'); 91 | } 92 | return `data:image/svg+xml;base64,${Buffer.from(svgString).toString('base64')}`; 93 | } 94 | 95 | /** 96 | * Converts a Base64-encoded string to an SVG string. 97 | * 98 | * This function decodes the Base64-encoded string and then converts it to an SVG string. 99 | * The resulting string can be used to create an SVG element using the `createSVGElement` function. 100 | * 101 | * @param {string} base64String - The Base64-encoded string to convert. 102 | * @returns {string} - The SVG string representation of the Base64-encoded string. 103 | * @see https://developer.mozilla.org/en-US/docs/Web/API/DOMParser - DOMParser documentation 104 | * @see https://developer.mozilla.org/en-US/docs/Web/API/Buffer - Buffer documentation 105 | */ 106 | export function convertBase64ToSVG(base64String: string): string { 107 | try { 108 | const svgString = Buffer.from(base64String.split(',')[1], 'base64').toString('utf-8'); 109 | return svgString; 110 | } catch (error) { 111 | throw new Error('Invalid Base64 string.'); 112 | } 113 | } -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |

2 |
3 | image 4 |
5 |

6 | 7 | 8 | # SVG Utility Functions 9 | This module provides utility functions for working with SVG elements and files, including creating, cloning, merging, converting SVG to Base64, comparing SVG images, normalizing path data, and converting SVG to PNG format. 10 | 11 | [![npm version](https://img.shields.io/npm/v/svg-toolbox.svg?style=for-the-badge)](https://www.npmjs.com/package/svg-toolbox) 12 | [![npm downloads](https://img.shields.io/npm/dy/svg-toolbox.svg?style=for-the-badge)](https://www.npmjs.com/package/svg-toolbox) 13 | [![deps](https://img.shields.io/github/license/SteamedBread2333/svg-toolbox.svg?style=for-the-badge)](https://www.npmjs.com/package/svg-toolbox) 14 | 15 | ## Installation 16 | ```bash 17 | npm install svg-toolbox 18 | ``` 19 | 20 | ## Table of Contents 21 | 22 | - [SVG Utility Functions](#svg-utility-functions) 23 | - [Installation](#installation) 24 | - [Table of Contents](#table-of-contents) 25 | - [Usage](#usage) 26 | - [createSVGElement](#createsvgelement) 27 | - [cloneSVGElement](#clonesvgelement) 28 | - [mergeSVGElements](#mergesvgelements) 29 | - [convertSVGToBase64](#convertsvgtobase64) 30 | - [convertBase64ToSVG](#convertbase64tosvg) 31 | - [diffSvg](#diffsvg) 32 | - [svg2png](#svg2png) 33 | - [removeNanCoordinates](#removenancoordinates) 34 | - [License](#license) 35 | 36 | ## Usage 37 | 38 | ### createSVGElement 39 | 40 | Creates an SVG element from a given SVG content string. 41 | 42 | ```typescript 43 | const svgElement = createSVGElement(``); 44 | console.log(svgElement); 45 | ``` 46 | ### cloneSVGElement 47 | 48 | Clones an SVG element deeply. 49 | 50 | ```typescript 51 | import { cloneSVGElement } from 'svg-toolbox'; 52 | import { JSDOM } from 'jsdom'; 53 | 54 | const dom = new JSDOM(``); 55 | const { document } = dom.window; 56 | 57 | const originalElement = document.createElementNS('http://www.w3.org/2000/svg', 'circle'); 58 | originalElement.setAttribute('cx', '50'); 59 | originalElement.setAttribute('cy', '50'); 60 | originalElement.setAttribute('r', '40'); 61 | originalElement.setAttribute('stroke', 'black'); 62 | originalElement.setAttribute('stroke-width', '3'); 63 | originalElement.setAttribute('fill', 'red'); 64 | 65 | const clonedElement = cloneSVGElement(originalElement); 66 | console.log(clonedElement); 67 | ``` 68 | 69 | ### mergeSVGElements 70 | Merges multiple SVG elements into a single SVG element. 71 | 72 | ```typescript 73 | import { mergeSVGElements } from 'svg-toolbox'; 74 | import { JSDOM } from 'jsdom'; 75 | 76 | const dom = new JSDOM(``); 77 | const { document } = dom.window; 78 | 79 | const svgElement1 = document.createElementNS('http://www.w3.org/2000/svg', 'circle'); 80 | svgElement1.setAttribute('cx', '50'); 81 | svgElement1.setAttribute('cy', '50'); 82 | svgElement1.setAttribute('r', '40'); 83 | svgElement1.setAttribute('stroke', 'black'); 84 | svgElement1.setAttribute('stroke-width', '3'); 85 | svgElement1.setAttribute('fill', 'red'); 86 | 87 | const svgElement2 = document.createElementNS('http://www.w3.org/2000/svg', 'rect'); 88 | svgElement2.setAttribute('x', '10'); 89 | svgElement2.setAttribute('y', '10'); 90 | svgElement2.setAttribute('width', '100'); 91 | svgElement2.setAttribute('height', '100'); 92 | svgElement2.setAttribute('fill', 'blue'); 93 | 94 | const mergedElement = mergeSVGElements([svgElement1, svgElement2]); 95 | console.log(mergedElement); 96 | ``` 97 | 98 | ### convertSVGToBase64 99 | Converts an SVG element or SVG string to a Base64-encoded string. 100 | 101 | ```typescript 102 | import { createSVGElement, convertSVGToBase64, convertBase64ToSVG } from 'svg-toolbox'; 103 | 104 | const svgElement = createSVGElement(``); 105 | 106 | const base64String = convertSVGToBase64(svgElement); 107 | console.log('convertSVGToBase64 param element', base64String); 108 | 109 | const svgString = convertBase64ToSVG(base64String); 110 | console.log('convertBase64ToSVG', svgString); 111 | 112 | const svgBase64 = convertSVGToBase64(svgString); 113 | console.log('convertSVGToBase64 param string', svgBase64); 114 | ``` 115 | 116 | ### convertBase64ToSVG 117 | Converts a Base64-encoded string back to an SVG string. 118 | 119 | ```typescript 120 | import { convertBase64ToSVG } from 'svg-toolbox'; 121 | 122 | const base64String = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxjaXJjbGUgY3g9IjUwIiBjeT0iNTAiIHI9IjQwIiBzdHJva2U9ImJsYWNrIiBzdHJva2Utd2lkdGg9IjMiIGZpbGw9InJlZCIgLz48L3N2Zz4='; 123 | const svgString = convertBase64ToSVG(base64String); 124 | console.log(svgString); 125 | ``` 126 | 127 | ### diffSvg 128 | Compares two PNG images and generates a diff image. 129 | 130 | ```typescript 131 | import { diffSvg } from 'svg-toolbox'; 132 | 133 | const pathA = 'path/to/first/image.png'; 134 | const pathB = 'path/to/second/image.png'; 135 | const diffFilePath = 'path/to/save/diff/image.png'; 136 | 137 | // diffPngBuffer is a Buffer object containing the diff image in PNG format. 138 | // numDiffPixels is the number of different pixels between the two images. 139 | const { diffPngBuffer, numDiffPixels } = await diffSvg(pathA, pathB, diffFilePath) 140 | const diffPngBase64 = `data:image/png;base64,${diffPngBuffer.toString('base64')}`; 141 | console.log(`Number of different pixels: ${numDiffPixels}`); 142 | ``` 143 | 144 | ### svg2png 145 | Converts an SVG file to PNG format. 146 | 147 | ```typescript 148 | // Callback/Promise 149 | import { svg2Png } from 'svg-toolbox'; 150 | 151 | const svgPath = 'path/to/input/image.svg'; 152 | const pngPath = 'path/to/output/image.png'; 153 | const scale = 2; // Scaling factor 154 | 155 | svg2Png(svgPath, pngPath, scale); 156 | 157 | // Async/await 158 | const pngBuffer = await svg2Png(svgPath, scale); 159 | const pngBase64 = `data:image/png;base64,${pngBuffer.toString('base64')}`; 160 | console.log(pngBase64); 161 | ``` 162 | 163 | ### removeNanCoordinates 164 | Parses and normalizes the d attribute of all path elements in an SVG content. 165 | 166 | ```typescript 167 | import { removeNanCoordinates } from 'svg-toolbox'; 168 | 169 | const svgContent = ``; 170 | const normalizedSvgContent = removeNanCoordinates(svgContent); 171 | console.log(normalizedSvgContent); 172 | 173 | ``` 174 | 175 | ## License 176 | MIT License 177 | --------------------------------------------------------------------------------