API Reference: `@lottiefiles/last` (LAST Specification)

This page details the @lottiefiles/last package, which defines the Lottie Abstract Syntax Tree (LAST) specification. LAST is the tree structure used by relottie to represent Lottie JSON animations programmatically.

Understanding LAST is crucial for writing plugins that analyze or transform Lottie files.

Installation

While @lottiefiles/relottie includes core functionality, you might install @lottiefiles/last directly if you need access to the type definitions for plugin development or other advanced use cases:

npm install @lottiefiles/last
# or
yarn add @lottiefiles/last

Core Concepts

AST for Lottie: LAST provides a standard way to represent the nested structure and properties of Lottie JSON as a tree.
Based on unist: LAST extends the unist (Universal Syntax Tree) specification. This means it inherits the basic node structure (type, children, value, position) and is compatible with the rich ecosystem of unist utilities for tree manipulation and traversal (like unist-util-visit).
Semantic Titles: A key feature of LAST is the title property on parent nodes, which provides the Lottie-specific semantic meaning (e.g., version, layer-image, transform-opacity) based on the Lottie documentation, distinguishing nodes beyond their basic JSON key.
TypeScript Types: The package exports TypeScript interfaces for all defined node types, enabling type safety in your plugins.

Node Types

The following are the core node types defined by the LAST specification (based on the source documentation). See the package source code or generated TypeDocs for the complete set of title values.

Abstract Interfaces (from `unist`)

Parent: Base interface for nodes containing other nodes (children). In LAST, it also includes the semantic title property.

interface Parent extends UnistParent {
  title: AnyTitle; // Lottie's qualified semantic name
  // children: Node[];
  // position?: Position;
}

Literal: Base interface for nodes containing a literal value.

interface Literal extends UnistLiteral {
  // value: any;
  // position?: Position;
}

Core LAST Nodes

Root: Represents the entire Lottie animation object. It's the top-level node.

interface Root extends Omit<ObjectNode, "type"> {
  type: "root";
  title: "animation";
  hasExpressions: boolean; // Indicates if Lottie uses expressions
}

The hasExpressions flag is important for Security Considerations.

Primitive: Represents a primitive JSON value.

type PrimitiveValueType = "string" | "number" | "boolean" | "null";
type PrimitiveValue = string | number | boolean | null;

interface Primitive extends Literal {
  type: "primitive";
  value: PrimitiveValue;
  valueType?: PrimitiveValueType;
}

KeyNode: Represents the key (property name) in a JSON key-value pair.

interface KeyNode extends Literal {
  type: "key";
  value: string;
}

Member (Interface): A base interface shared by Attribute, Element, and Collection. Represents a keyed member of an object.

interface Member extends Parent {
  key: KeyNode | string; // The JSON key
  title: AttributeTitle | CollectionTitle | ElementTitle; // Semantic Lottie title
  // children: ...
}

Attribute: A Member whose value is a single Primitive.

interface Attribute extends Member {
  type: "attribute";
  title: AttributeTitle;
  children: [Primitive] | []; // Contains zero or one Primitive
}

Element: A Member whose value is a JSON object, represented by an ObjectNode.

interface Element extends Member {
  type: "element";
  title: ElementTitle;
  children: [ObjectNode] | []; // Contains zero or one ObjectNode
}

Collection: A Member whose value is a JSON array, represented by an ArrayNode.

interface Collection extends Member {
  type: "collection";
  title: CollectionTitle;
  children: [ArrayNode] | []; // Contains zero or one ArrayNode
}

ObjectNode: Represents the value part of an Element (a JSON object).

type ObjectNodeValue = Attribute | Element | Collection;
interface ObjectNode extends Parent {
  type: "object";
  title: ObjectTitle;
  children: ObjectNodeValue[]; // Contains object members
}

ArrayNode: Represents the value part of a Collection (a JSON array).

type ArrayNodeValue = Primitive | ObjectNode | ArrayNode;
interface ArrayNode extends Parent {
  type: "array";
  title: ArrayTitle;
  children: ArrayNodeValue[]; // Contains array items
}

Security

As noted in the source documentation, Lottie animations can contain JavaScript expressions. The Root node's hasExpressions property helps identify if expressions are present. Improper handling or execution of untrusted Lottie files containing expressions can lead to security vulnerabilities like Cross-Site Scripting (XSS). Always be cautious when processing Lottie files from untrusted sources.

Guide: Working with the LAST AST: Practical examples of using the AST.
@lottiefiles/last-builder: Utilities for programmatically creating LAST nodes.
unist: The underlying syntax tree specification.

LAST Specification - Relottie API

API Reference: @lottiefiles/last (LAST Specification)