Convenience Functions

/**
 * Add a default import to the program path of given path
 * @param path - The starting path to find a program path
 * @param importedSource - The source of the import
 * @param opts - Optional import configuration
 * @returns Identifier representing the imported default value
 */
function addDefault(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

import { addDefault } from "@babel/helper-module-imports";

// Basic default import
const lodashId = addDefault(path, "lodash");
// Generates: import _lodash from "lodash";

// With name hint
const lodashId = addDefault(path, "lodash", { nameHint: "lodash" });
// Generates: import _lodash2 from "lodash";

// With live reference in CommonJS
const lodashId = addDefault(path, "lodash", { 
  ensureLiveReference: true,
  importedType: "commonjs" 
});
// Generates: var _lodash = _interopRequireDefault(require("lodash")); _lodash.default

/**
 * Add a named import to the program path of given path
 * @param path - The starting path to find a program path
 * @param name - The name of the generated binding (Babel will prefix with _)
 * @param importedSource - The source of the import
 * @param opts - Optional import configuration
 * @returns Different types based on options:
 *   - Identifier if no special options
 *   - MemberExpression if ensureLiveReference is true
 *   - SequenceExpression if ensureNoContext is true
 */
function addNamed(
  path: NodePath,
  name: string,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

// Basic version - returns Identifier
function addNamed(
  path: NodePath,
  name: string,
  importedSource: string,
  opts?: Omit<Partial<ImportOptions>, "ensureLiveReference" | "ensureNoContext">
): t.Identifier;

// Live reference version - returns MemberExpression
function addNamed(
  path: NodePath,
  name: string,
  importedSource: string,
  opts?: Omit<Partial<ImportOptions>, "ensureLiveReference"> & {
    ensureLiveReference: true;
  }
): t.MemberExpression;

// No context version - returns SequenceExpression
function addNamed(
  path: NodePath,
  name: string,
  importedSource: string,
  opts?: Omit<Partial<ImportOptions>, "ensureNoContext"> & {
    ensureNoContext: true;
  }
): t.SequenceExpression;

import { addNamed } from "@babel/helper-module-imports";

// Basic named import
const debounceId = addNamed(path, "debounce", "lodash");
// Generates: import { debounce as _debounce } from "lodash";

// With live reference
const debounceExpr = addNamed(path, "debounce", "lodash", { 
  ensureLiveReference: true 
});
// Generates: import _lodash from "lodash"; _lodash.debounce

// With no context (useful for function calls)
const debounceSeq = addNamed(path, "debounce", "lodash", { 
  ensureNoContext: true 
});
// Generates: import { debounce as _debounce } from "lodash"; (0, _debounce)

// CommonJS named import
const debounceId = addNamed(path, "debounce", "lodash", {
  importedType: "commonjs",
  importedInterop: "babel"
});
// Generates: var _lodash = require("lodash"); _lodash.debounce

/**
 * Add a namespace import to the program path of given path
 * @param path - The starting path to find a program path
 * @param importedSource - The source of the import
 * @param opts - Optional import configuration
 * @returns Identifier representing the imported namespace
 */
function addNamespace(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

import { addNamespace } from "@babel/helper-module-imports";

// ES6 namespace import
const reactId = addNamespace(path, "react");
// Generates: import * as _react from "react";

// With name hint
const reactId = addNamespace(path, "react", { nameHint: "React" });
// Generates: import * as _React from "react";

// CommonJS namespace with Babel interop
const reactId = addNamespace(path, "react", {
  importedType: "commonjs",
  importedInterop: "babel"
});
// Generates: var _react = _interopRequireWildcard(require("react"));

/**
 * Add a side-effect import to the program path of given path
 * @param path - The starting path to find a program path
 * @param importedSource - The source of the import
 * @param opts - Optional import configuration
 * @returns Identifier representing any incidental binding (usually unused)
 */
function addSideEffect(
  path: NodePath,
  importedSource: string,
  opts?: Partial<ImportOptions>
): t.Identifier | t.MemberExpression | t.SequenceExpression;

import { addSideEffect } from "@babel/helper-module-imports";

// ES6 side-effect import
addSideEffect(path, "reflect-metadata");
// Generates: import "reflect-metadata";

// CommonJS side-effect import
addSideEffect(path, "reflect-metadata", { importedType: "commonjs" });
// Generates: require("reflect-metadata");

// CSS import
addSideEffect(path, "./styles.css");
// Generates: import "./styles.css";

interface ImportOptions {
  /** The module being referenced (usually overridden by function parameter) */
  importedSource: string | null;
  /** Type of module being imported: 'es6' or 'commonjs' (default: 'commonjs') */
  importedType: "es6" | "commonjs";
  /** Interop behavior for CommonJS modules (default: 'babel') */
  importedInterop: "babel" | "node" | "compiled" | "uncompiled";
  /** CommonJS interop in the loading environment (default: 'babel') */
  importingInterop: "babel" | "node";
  /** Force imported values to be live references (default: false) */
  ensureLiveReference: boolean;
  /** Force calls to exclude context (default: false) */
  ensureNoContext: boolean;
  /** Whether import should be loaded before or after existing imports (default: 'before') */
  importPosition: "before" | "after";
  /** Hint for variable name generation */
  nameHint?: string;
  /** Control import statement ordering */
  blockHoist?: number;
}

// Multiple calls with same source
const lodashId1 = addDefault(path, "lodash");
const lodashId2 = addDefault(path, "lodash");
// Result: Only one import statement is generated

// Compatible named imports are merged
const debounceId = addNamed(path, "debounce", "lodash");
const throttleId = addNamed(path, "throttle", "lodash");
// Generates: import { debounce as _debounce, throttle as _throttle } from "lodash";