transformation-matrix

transformation-matrix is a focused, dependency-free library for working with 2D affine transformation matrices — the translate/rotate/scale/shear/skew operations used to map points and shapes from one coordinate space to another. It exposes small, composable functions rather than a single monolithic Matrix class: translate(), rotate(), scale(), shear(), and skew() each build a matrix, compose()/transform() merge several into one, and applyToPoint()/applyToPoints() apply the result to point data.

Beyond basic composition, the library can parse and render matrices as CSS matrix() strings, SVG transform attribute values, and plain objects, and it can decompose an arbitrary matrix back into translation, rotation, and scale components (with optional flip handling) — useful for interpreting a transform that came from user input or another system. It is published as ES6 source (tree-shakeable), a CommonJS build, and a minified UMD bundle for direct browser use, with first-class TypeScript definitions.

What You Get

• Matrix builders for translate, rotate (radians or degrees), scale, shear, and skew operations
• compose()/transform() to merge any number of matrices into a single equivalent matrix
• applyToPoint()/applyToPoints() to map point objects or [x, y] tuples through a matrix
• fromString()/toString() and fromTransformAttribute() for round-tripping CSS matrix() and SVG transform syntax
• decomposeTSR() to recover translation, scale, and rotation (with flip support) from a matrix
• fromTriangles() and fromOneMovingPoint/fromTwoMovingPoints() for gesture- and correspondence-based matrix derivation

Common Use Cases

• Implementing pan/zoom/rotate gesture handling for canvas or SVG editors
• Converting between a UI’s internal transform state and CSS or SVG transform strings
• Building diagramming, whiteboard, or node-graph tools that need to map screen coordinates to a virtual canvas
• Recovering scale/rotation/translation components from a matrix supplied by a browser API or another library
• Composing chained transforms (e.g. parent/child coordinate spaces) into one matrix for a single point-mapping pass

Under The Hood

Architecture The library is organized as one small, focused ES module per operation (translate.js, rotate.js, scale.js, shear.js, skew.js, decompose.js, transform.js, fromString.js, fromTransformAttribute.js, fromTriangles.js, fromMovingPoints.js), all re-exported flatly through index.js with no shared internal class or mutable state — every function takes plain matrix/point objects ({a, b, c, d, e, f} and {x, y} or [x, y]) and returns new ones. transform()/compose() is the structural hinge: every higher-level builder ultimately produces a matrix that can be folded through the same reduce-style 2x3 multiplication, so composition is uniform regardless of which operation produced the inputs. The one non-trivial subsystem is CSS/SVG transform-attribute parsing, which is generated from a Peggy grammar (fromTransformAttribute.peggy compiled to fromTransformAttribute.autogenerated.js) rather than hand-written string parsing. Because every function is pure and side-effect free, changing the core {a,b,c,d,e,f} matrix shape is the one change that would ripple through the entire surface area.

Tech Stack Written in ES6 JavaScript with TypeScript typings maintained by hand (transformation-matrix.d.ts). Build tooling is Babel (@babel/cli, @babel/preset-env) for the CommonJS output and Webpack for the minified UMD bundle used via <script src="unpkg...">; Peggy generates the transform-attribute parser at build time. No runtime dependencies are declared — devDependencies cover build, lint (standard), docs (jsdoc-to-markdown), and test tooling only, keeping the published package dependency-free.

Code Quality Tests live under test/ as one Jest spec file per source module (e.g. transform.spec.js, decompose.spec.js, fromTransformAttribute.pegjs.spec.js), run via test:jest/test:coverage, with a separate test:typescript script that type-checks the .d.ts file with tsc --strict and test:standard enforcing the zero-config standard style guide (with generated/example files explicitly excluded). CI runs on GitHub Actions and a Coveralls badge tracks coverage. Naming is consistent and the small pure-function surface makes error handling straightforward — the main explicit failure mode is transform() throwing on zero matrices.

What Makes It Unique Rather than wrapping a mutable Matrix class (the common pattern in comparable libraries), it commits fully to plain-object matrices and free functions, which is what makes true tree-shaking and framework independence possible. Its differentiator against most transform-matrix utilities is round-trip fidelity with both CSS matrix() syntax and the SVG transform attribute grammar via a real generated parser, plus decomposeTSR()’s explicit flip-aware decomposition and the gesture-oriented fromOneMovingPoint/fromTwoMovingPoints/fromTriangles constructors, which most peer libraries omit.