@hexlabelposition/som
v0.5.0
Published
Zero-dependency, tree-shakeable ESM toolkit for working with SVG as plain objects.
Maintainers
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
styleandclassattributes, 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,
parseis 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
parsedoes not pull instringifyor theattributeshelpers.
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/somUsage
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"); // 2Path 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 dataPaths 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.
