npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@hexlabelposition/som

v0.5.0

Published

Zero-dependency, tree-shakeable ESM toolkit for working with SVG as plain objects.

Readme

som

som (SVG Object Model) is a zero-dependency, tree-shakeable ESM toolkit for working with SVG as plain objects in any JavaScript runtime.

Status: early development (0.x). v0.4 covers parsing, serialization, tree helpers, the style and class attributes, typed attribute reads, element and attribute data for SVG 1.1 and SVG 2, finding, normalizing and replacing colors, parsing, serializing and normalizing path data, and the bounds and length of paths. Until 1.0, any minor release may change the API. See BACKLOG.md for what is planned and ARCHITECTURE.md for how it is built.

Why

Working with SVG in JavaScript today usually means combining several packages: one to parse, one for paths, one for colors, one for bounds. Each has its own data format, its own types (or none), and often years without updates.

som aims to replace them with one coherent toolkit built around a single document model.

Principles

  • One library, one model. Parse once, run any number of operations on the same tree, serialize once.
  • SVG as plain objects. The tree is ordinary data with no DOM nodes or parent references: edit it with plain property access, store it as JSON or send it to a worker.
  • Lossless round trips. Element order, text, comments, CDATA, processing instructions, the XML declaration, DOCTYPE, namespaces, attribute order, and unknown elements and attributes all survive parse → stringify.
  • Type-safe. Strict public types for the whole tree, and element and attribute name types per SVG version, generated from the specifications (SvgElementName, SvgAttributeName).
  • Fast parsing. One pass over the input. In the benchmarks, parse is 3-4× faster than svg-parser and 6-13× faster than svgson; see Performance.
  • Zero dependencies. Pure JavaScript with no runtime dependencies and no DOM requirement.
  • ESM-only and tree-shakeable. The API is made of independent functions without side effects, so a bundle contains only what you import: using parse does not pull in stringify or the attributes helpers.

Guarantees

  • Strict parsing. Only well-formed XML is accepted, and every error has a stable code and a source position.
  • Bounded parsing. External entities are never loaded, and input size, nesting depth and entity expansion are limited.
  • No implicit interpretation. Attribute values stay strings until a module explicitly parses them.
  • Tree-level round trips. The tree is kept, not the exact source text: quote style, entity spelling and whitespace inside tags are normalized.

Features

| Area | What it covers | Version | | ---------------- | --------------------------------------------------------------------- | ------- | | parse | Parse SVG into an AST | v0.1 | | stringify | Serialize an AST back to SVG | v0.1 | | ast | clone, traversal, queries, type guards | v0.1 | | attributes | Helpers for the style and class attributes | v0.1 | | typed reads | Numbers, lengths, angles, viewBox and other attribute values | v0.2 | | spec types | Element and attribute types per SVG version, generated from the specs | v0.2 | | colors | Extract, normalize and replace colors | v0.3 | | paths | Parse, serialize and normalize path data (d) | v0.4 | | geometry | Bounds, center and length of path data | v0.5 | | transforms | Parse, compose and apply transform matrices | v0.6 | | optimization | Rounding, compact path data, document cleanup | v0.7 |

v0.1 to v0.5 are released. Later versions show the intended order, not dates.

Install

npm install @hexlabelposition/som

Usage

import { parse, stringify, getRoot } from "@hexlabelposition/som";

const doc = parse(
  '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8"/></svg>',
);
const svg = getRoot(doc);

// The tree is plain data: edit it directly.
const circle = svg.children[0];
if (circle.type === "element") {
  circle.attributes.fill = "currentColor";
}

stringify(doc);
// <svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="8" fill="currentColor"/></svg>

Operations mutate the document. When you need to keep the original, copy it explicitly:

import { clone } from "@hexlabelposition/som";

const copy = clone(doc);

Malformed input throws an SvgParseError with a stable code and the line, column and offset of the problem.

Element and attribute names can be checked against SVG 1.1 and SVG 2, as types and at run time:

import {
  isSvgAttributeName,
  type SvgAttributeName,
} from "@hexlabelposition/som";

isSvgAttributeName("rect", "rx"); // true
isSvgAttributeName("rect", "enable-background", "2"); // false: SVG 1.1 only

const name: SvgAttributeName<"rect", "2"> = "paint-order";

Colors are found and replaced where they are written: in attributes, style attributes and <style> sheets. Colors that look the same match, whatever notation they are written in:

import {
  extractColors,
  formatColor,
  normalizeColor,
  parse,
  replaceColor,
} from "@hexlabelposition/som";

const icon = parse(
  '<svg><style>.a { fill: #F00 }</style><path fill="red" stroke="rgb(0 0 255)"/></svg>',
);

extractColors(icon).map((use) => use.value); // ["#F00", "red", "rgb(0 0 255)"]

// Distinct colors, in one form:
const colors = extractColors(icon).flatMap(({ color }) =>
  color ? [formatColor(normalizeColor(color))] : [],
);
new Set(colors); // Set { "#f00", "#00f" }

replaceColor(icon, "red", "currentColor"); // 2

Path data is read into one plain object per command, written back in one readable form, and normalized to absolute full commands. Numbers are kept exactly; relative coordinates are summed as decimals, so 0.1 + 0.2 stays 0.3:

import { normalizePath, parsePath, stringifyPath } from "@hexlabelposition/som";

const path = parsePath("M10,20l5-5 10 0Z");
// [
//   { type: "M", x: 10, y: 20 },
//   { type: "l", x: 5, y: -5 },
//   { type: "l", x: 10, y: 0 },
//   { type: "Z" },
// ]

stringifyPath(path!); // "M10 20 l5 -5 l10 0 Z"
stringifyPath(normalizePath(path!)); // "M10 20 L15 15 L25 15 Z"
stringifyPath(normalizePath(parsePath("M0.1 0 l0.2 0 h0.4")!)); // "M0.1 0 L0.3 0 L0.7 0"

parsePath("M10 20 L"); // undefined: invalid path data

Paths are measured exactly, curves and arcs included, as getBBox() and getTotalLength() measure them in browsers:

import { getPathBounds, getPathLength, parsePath } from "@hexlabelposition/som";

getPathBounds(parsePath("M0 0 C0 -10 10 -10 10 0")!);
// { x: 0, y: -7.5, width: 10, height: 7.5 }: the curve, not its control points

getPathLength(parsePath("M0 0 L3 4 Z")!); // 10
getPathLength(parsePath("M-1 0 A1 1 0 0 1 1 0 A1 1 0 0 1 -1 0")!); // 6.283185307179586, 2π

Performance

All numbers here come from the benchmark suite in scripts/benchmarks/, run with bun run bench against the built package. Compared with svgson 5.3.1 and svg-parser 2.1.0 on Node.js 26.8.1, Linux, Intel Core i5-11400H. Each cell shows how many times more operations per second som runs; below 1× means som is slower.

| Input | parse vs svg-parser | parse vs svgson | stringify vs svgson | | ------------------------------ | --------------------- | ----------------- | --------------------- | | Bootstrap Icons, 2,078 files | 4.0× | 13.5× | 0.8× | | Inkscape export, 4 KB | 3.0× | 6.6× | 1.5× | | Bootstrap Icons sprite, 1.1 MB | 3.7× | 13.4× | 0.75× |

svg-parser has no serializer. svgson's tree leaves out the XML declaration, comments, DOCTYPE, processing instructions and whitespace-only text, so it has less to write; som keeps all of them and checks that every character is allowed in XML.

On Bun 1.4.0 (bun run bench:bun), som was faster than both libraries in every case, but the results varied more between runs. Numbers depend on the machine and the runtime, so run the benchmarks to compare on yours.

Runtimes

Node.js ≥ 22, Bun ≥ 1.2.23, Chromium, Firefox and WebKit, all tested in CI.

Non-goals

som is not a JSX parser, a renderer, a visual editor, or a sanitizer. Parsed documents keep scripts, event handlers and external references, so a document from an untrusted source must not be injected into a page as is. som works with SVG/XML markup, not JSX.

Name

som stands for SVG Object Model: SVG represented as a tree of plain objects. The project is called som; it is published on npm as @hexlabelposition/som, because the unscoped som name is taken.

Contributing

The project is not open for contributions yet. Development setup and conventions are described in CONTRIBUTING.md.

License

MIT