Architecture

dotlottie-io splits responsibilities across four classes. Each one is optimized for a different task.

Class	Role	Use it when...
`DotLottie`	A loaded, fully mutable package	You want to load a file and then read and modify it
`DotLottieBuilder`	A stateful builder for constructing a new package	You're assembling a package from scratch
`DotLottieReader`	A lazy, read-only view over an archive	You only need to inspect or extract specific entries, with minimal memory use
`DotLottieMerger`	Combines multiple packages	You need to merge two or more `.lottie` files with defined collision handling

Why the split

Each class trades off differently between mutability, memory use, and construction cost:

DotLottie eagerly parses every entry in the archive into memory, so once loaded, all reads and writes are immediate and synchronous. This is the right default for small-to-medium packages you intend to modify.
DotLottieBuilder exists because building up a package incrementally (adding animations, themes, assets one at a time) is a distinct workflow from mutating an already-loaded one — build() consumes the builder's queued content and resolves any filename collisions in one pass, returning a DotLottie.
DotLottieReader only parses manifest.json on construction. Every other getter reads exactly one ZIP entry on demand, so inspecting a single animation out of a 200-animation library doesn't require loading the other 199. See Managing Assets and the reading guide for when this matters in practice.
DotLottieMerger is separate from both because merging needs a single place to define collision behavior (MergeStrategy) that applies consistently across every animation, theme, state machine, and asset being combined.

A typical flow

const { DotLottieBuilder, DotLottieMerger, MergeStrategy } = require("@lottiefiles/dotlottie-io");

// 1. Build two packages
const builder1 = new DotLottieBuilder();
builder1.addAnimation("intro", introBuffer);
const packageA = builder1.build(); // → DotLottie

const builder2 = new DotLottieBuilder();
builder2.addAnimation("outro", outroBuffer);
const packageB = builder2.build(); // → DotLottie

// 2. Merge them
const merger = new DotLottieMerger(MergeStrategy.Rename);
const merged = merger.merge(packageA, [packageB]); // → DotLottie

// 3. Serialize the result
merged.toBytes();

Reading later reuses the same DotLottie class:

const { DotLottie } = require("@lottiefiles/dotlottie-io");

const loaded = DotLottie.fromBytes(mergedBytes);
loaded.animationIds(); // ['intro', 'outro']

Next up: Managing Animations