CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-babel--helper-annotate-as-pure

Helper function to annotate AST nodes with #__PURE__ comment for tree-shaking optimization

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

@babel/helper-annotate-as-pure

Helper function to annotate AST nodes with #PURE comment for tree-shaking optimization. This utility enables bundlers to identify side-effect-free function calls and expressions, allowing unused code to be safely removed during the build process.

Package Information

  • Package Name: @babel/helper-annotate-as-pure
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @babel/helper-annotate-as-pure
  • Node.js: >=6.9.0

Core Imports

import annotateAsPure from "@babel/helper-annotate-as-pure";

Note: This package is published as an ES module with TypeScript definitions included. The package exports both the main function and TypeScript types through its exports field. It only provides a default export - there are no named exports available.

For CommonJS environments (with proper module loading):

const annotateAsPure = require("@babel/helper-annotate-as-pure").default;

Basic Usage

import annotateAsPure from "@babel/helper-annotate-as-pure";
import { Node } from "@babel/types";

// Annotating a direct AST node
const callExpression: Node = {
  type: "CallExpression",
  callee: { type: "Identifier", name: "myFunction" },
  arguments: []
};

annotateAsPure(callExpression);
// Result: callExpression now has leadingComments: [{ type: "CommentBlock", value: "#__PURE__" }]

// Annotating via Babel traverse path
import traverse from "@babel/traverse";

traverse(ast, {
  CallExpression(path) {
    annotateAsPure(path); // Works with path objects too
  }
});

Capabilities

Pure Annotation

Adds a #__PURE__ leading comment to AST nodes to indicate they are side-effect-free for tree-shaking optimization.

/**
 * Annotates a Babel AST node or path with a #__PURE__ comment
 * @param pathOrNode - Either a @babel/types Node or a Babel traverse path containing a node
 * @returns void
 */
export default function annotateAsPure(
  pathOrNode: Node | { node: Node }
): void;

Parameters:

  • pathOrNode: Can be either:
    • A @babel/types Node object directly
    • A Babel traverse path object containing a node property

Behavior:

  • Automatically prevents duplicate annotations - won't add multiple #__PURE__ comments to the same node
  • Recognizes both @__PURE__ and #__PURE__ annotation formats when checking for existing annotations
  • Uses @babel/types.addComment() internally to add the leading comment
  • Operates by mutation - modifies the node's leadingComments property directly

Usage Examples:

import annotateAsPure from "@babel/helper-annotate-as-pure";
import * as t from "@babel/types";

// Example 1: Annotating a function call
const functionCall = t.callExpression(
  t.identifier("calculate"),
  [t.numericLiteral(42)]
);

annotateAsPure(functionCall);
console.log(functionCall.leadingComments);
// Output: [{ type: "CommentBlock", value: "#__PURE__" }]

// Example 2: Using with Babel traverse
import traverse from "@babel/traverse";

traverse(ast, {
  CallExpression(path) {
    // Only annotate specific function calls
    if (t.isIdentifier(path.node.callee, { name: "safeFunction" })) {
      annotateAsPure(path);
    }
  }
});

// Example 3: Preventing duplicates
const alreadyAnnotated = t.callExpression(t.identifier("test"), []);
annotateAsPure(alreadyAnnotated); // Adds comment
annotateAsPure(alreadyAnnotated); // Does nothing - prevents duplicate

Types

// From @babel/types - base interface for all AST nodes
interface Node {
  type: string;
  leadingComments?: Comment[] | null;
  trailingComments?: Comment[] | null;
  innerComments?: Comment[] | null;
  // ... other AST node properties
}

// Comment structure added by annotation
interface Comment {
  type: "CommentBlock" | "CommentLine";
  value: string;
}

// Path object structure (from @babel/traverse)
interface TraversePath {
  node: Node;
  // ... other traverse path properties
}

Dependencies

This package has the following runtime dependency:

  • @babel/types: For the addComment function and Node type definitions

Development dependency (used in tests):

  • @babel/traverse: For path traversal in test scenarios

Common Use Cases

  1. Babel Plugin Development: Mark function calls as pure in Babel transformations
  2. Tree-shaking Optimization: Help bundlers identify removable code
  3. Library Development: Annotate utility functions that don't have side effects
  4. Build Tool Integration: Automatically mark certain patterns as pure during compilation

Important Notes

  • This is a low-level utility designed for Babel plugin authors and build tool developers
  • The annotation only affects bundler behavior - it doesn't change runtime semantics
  • Only use #__PURE__ annotations on truly side-effect-free expressions
  • The package works with any Babel AST node type, not just function calls

docs

index.md

tile.json