Core Bundling

/**
 * Creates a bundle from input options
 * @param options - Input configuration for bundling
 * @returns Promise resolving to RollupBuild object
 */
function rollup(options: RollupOptions): Promise<RollupBuild>;

interface RollupOptions extends InputOptions {
  output?: OutputOptions | OutputOptions[];
}

import { rollup } from "rollup";

// Basic bundling
const bundle = await rollup({
  input: "src/main.js"
});

// With plugins and external dependencies
const bundle = await rollup({
  input: "src/main.js",
  external: ["lodash", "react"],
  plugins: [
    // Plugin instances
  ],
  treeshake: {
    moduleSideEffects: false
  }
});

// Multiple inputs
const bundle = await rollup({
  input: {
    main: "src/main.js",
    worker: "src/worker.js"
  }
});

/**
 * Build object for generating and writing bundles
 */
interface RollupBuild {
  /** Build cache for performance optimization */
  cache: RollupCache | undefined;
  /** Whether build has been closed */
  closed: boolean;
  /** Files being watched by the build */
  watchFiles: string[];
  /** Generate bundle without writing to disk */
  generate(outputOptions: OutputOptions): Promise<RollupOutput>;
  /** Generate and write bundle to disk */
  write(outputOptions: OutputOptions): Promise<RollupOutput>;
  /** Close the build and clean up resources */
  close(): Promise<void>;
  /** Async disposal support */
  [Symbol.asyncDispose](): Promise<void>;
  /** Performance timing data (if perf option enabled) */
  getTimings?(): SerializedTimings;
}

/**
 * Generate bundle without writing to disk
 * @param outputOptions - Output configuration
 * @returns Promise resolving to generated bundle
 */
generate(outputOptions: OutputOptions): Promise<RollupOutput>;

// Generate ES module bundle
const { output } = await bundle.generate({
  format: "esm"
});

const [chunk] = output;
console.log(chunk.code); // Generated JavaScript code

// Generate multiple formats
const esmResult = await bundle.generate({
  format: "esm",
  sourcemap: true
});

const cjsResult = await bundle.generate({
  format: "cjs",
  exports: "named"
});

/**
 * Generate and write bundle to disk
 * @param outputOptions - Output configuration including file paths
 * @returns Promise resolving to written bundle information
 */
write(outputOptions: OutputOptions): Promise<RollupOutput>;

// Write single file
await bundle.write({
  format: "esm",
  file: "dist/bundle.js",
  sourcemap: true
});

// Write multiple files to directory
await bundle.write({
  format: "esm",
  dir: "dist",
  entryFileNames: "[name].js",
  chunkFileNames: "[name]-[hash].js"
});

// Write with additional options
await bundle.write({
  format: "umd",
  file: "dist/bundle.umd.js",
  name: "MyLibrary",
  globals: {
    lodash: "_",
    react: "React"
  }
});

/**
 * Close the build and clean up resources
 * @returns Promise that resolves when cleanup is complete
 */
close(): Promise<void>;

/**
 * Async disposal support for using with syntax
 * @returns Promise that resolves when disposal is complete
 */
[Symbol.asyncDispose](): Promise<void>;

// Manual cleanup
const bundle = await rollup(options);
try {
  await bundle.write(outputOptions);
} finally {
  await bundle.close();
}

// Using async disposal (Node.js 20+)
{
  await using bundle = await rollup(options);
  await bundle.write(outputOptions);
  // Automatically disposed at end of block
}

/**
 * Get performance timing data (only available if perf option enabled)
 * @returns Timing data for different build phases
 */
getTimings?(): SerializedTimings;

type SerializedTimings = Record<string, [number, number, number]>;

// Enable performance timing
const bundle = await rollup({
  input: "src/main.js",
  perf: true // Enable timing collection
});

// Generate bundle and get timing data
await bundle.write({
  format: "esm",
  file: "dist/bundle.js"
});

// Get timing information
if (bundle.getTimings) {
  const timings = bundle.getTimings();
  console.log('Build timings:', timings);
  
  // Timings format: [self_time, total_time, start_time]
  Object.entries(timings).forEach(([phase, [self, total, start]]) => {
    console.log(`${phase}: ${self}ms self, ${total}ms total`);
  });
}

await bundle.close();

interface InputOptions {
  /** Entry point(s) for bundling */
  input?: InputOption;
  /** External dependencies to exclude from bundle */
  external?: ExternalOption;
  /** Input plugins for processing */
  plugins?: InputPluginOption;
  /** Build caching options */
  cache?: boolean | RollupCache;
  /** Tree-shaking configuration */
  treeshake?: boolean | TreeshakingPreset | TreeshakingOptions;
  /** Logging configuration */
  logLevel?: LogLevelOption;
  onLog?: LogHandlerWithDefault;
  /** Development context path */
  context?: string;
  /** File system abstraction */
  fs?: RollupFsModule;
  /** Module context functions */
  moduleContext?: ((id: string) => string | null) | Record<string, string>;
  /** Performance timing collection */
  perf?: boolean;
  /** Entry signature preservation */
  preserveEntrySignatures?: PreserveEntrySignaturesOption;
  /** Symlink handling */
  preserveSymlinks?: boolean;
  /** JSX processing options */
  jsx?: false | JsxPreset | JsxOptions;
}

type InputOption = string | string[] | Record<string, string>;
type ExternalOption = 
  | (string | RegExp)[]
  | string
  | RegExp
  | ((source: string, importer: string | undefined, isResolved: boolean) => boolean | null);
type TreeshakingPreset = 'smallest' | 'safest' | 'recommended';

interface OutputOptions {
  /** Output format */
  format?: ModuleFormat;
  /** Single file output path */
  file?: string;
  /** Directory for multiple files */
  dir?: string;
  /** Output plugins */
  plugins?: OutputPluginOption;
  /** Source map generation */
  sourcemap?: boolean | 'inline' | 'hidden';
  /** Global variable mappings for external dependencies */
  globals?: GlobalsOption;
  /** Code to prepend to bundle */
  banner?: string | AddonFunction;
  /** Code to append to bundle */
  footer?: string | AddonFunction;
  /** Code to prepend inside wrapper */
  intro?: string | AddonFunction;
  /** Code to append inside wrapper */
  outro?: string | AddonFunction;
  /** Export mode */
  exports?: 'default' | 'named' | 'none' | 'auto';
  /** UMD/IIFE global name */
  name?: string;
  /** Compact output */
  compact?: boolean;
  /** Generated code features */
  generatedCode?: GeneratedCodePreset | GeneratedCodeOptions;
  /** Manual chunk configuration */
  manualChunks?: ManualChunksOption;
  /** File naming patterns */
  entryFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
  chunkFileNames?: string | ((chunkInfo: PreRenderedChunk) => string);
  assetFileNames?: string | ((assetInfo: PreRenderedAsset) => string);
}

type ModuleFormat = 'amd' | 'cjs' | 'es' | 'iife' | 'system' | 'umd' | 'commonjs' | 'esm' | 'module' | 'systemjs';
type GlobalsOption = Record<string, string> | ((name: string) => string);
type AddonFunction = (chunk: RenderedChunk) => string | Promise<string>;

interface RollupOutput {
  output: [OutputChunk, ...(OutputChunk | OutputAsset)[]];
}

interface OutputChunk extends RenderedChunk {
  /** Generated JavaScript code */
  code: string;
  /** Source map if enabled */
  map: SourceMap | null;
  /** Source map file name */
  sourcemapFileName: string | null;
  /** Preliminary file name before final processing */
  preliminaryFileName: string;
}

interface OutputAsset extends PreRenderedAsset {
  /** Final file name */
  fileName: string;
  /** Whether asset needs code reference */
  needsCodeReference: boolean;
}

interface RenderedChunk extends PreRenderedChunk {
  /** Generated file name */
  fileName: string;
  /** Dynamic imports */
  dynamicImports: string[];
  /** Files that should be loaded before this chunk */
  implicitlyLoadedBefore: string[];
  /** Imported bindings per module */
  importedBindings: Record<string, string[]>;
  /** Import file names */
  imports: string[];
  /** Detailed module information */
  modules: Record<string, RenderedModule>;
  /** Referenced asset files */
  referencedFiles: string[];
}