Configuration API

/**
 * Eleventy's user-land Configuration API
 */
class UserConfig {
  constructor();
  
  /** Reset configuration to initial state */
  reset(): void;
  
  /** Check version compatibility */
  versionCheck(compatibleRange?: string): void;
  
  /** Get configuration object for merging */
  getMergingConfigObject(): object;
}

/**
 * Add event listener
 * @param eventName - Event name to listen for
 * @param callback - Function to call when event fires
 */
on(eventName: string, callback: Function): void;

/**
 * Add one-time event listener
 * @param eventName - Event name to listen for
 * @param callback - Function to call when event fires once
 */
once(eventName: string, callback: Function): void;

/**
 * Emit custom event
 * @param eventName - Event name to emit
 * @param args - Arguments to pass to listeners
 */
emit(eventName: string, ...args: any[]): void;

/**
 * Set event handler mode
 * @param mode - Event handling mode
 */
setEventEmitterMode(mode: string): void;

// Listen for build events
eleventyConfig.on("beforeBuild", ({ directories, runMode }) => {
  console.log("Starting build:", runMode);
});

eleventyConfig.on("afterBuild", ({ results }) => {
  console.log("Build complete:", results.length, "files");
});

// Custom events
eleventyConfig.emit("myCustomEvent", { data: "value" });

/**
 * Add universal filter that works in all template engines
 * @param name - Filter name
 * @param callback - Filter function
 */
addFilter(name: string, callback: Function): void;

/**
 * Add async filter for asynchronous operations
 * @param name - Filter name  
 * @param callback - Async filter function
 */
addAsyncFilter(name: string, callback: Function): void;

/**
 * Add filter specific to Liquid templates
 * @param name - Filter name
 * @param callback - Filter function
 */
addLiquidFilter(name: string, callback: Function): void;

/**
 * Add filter specific to Nunjucks templates
 * @param name - Filter name
 * @param callback - Filter function
 * @param isAsync - Whether filter is asynchronous
 */
addNunjucksFilter(name: string, callback: Function, isAsync?: boolean): void;

/**
 * Add async filter specific to Nunjucks templates
 * @param name - Filter name
 * @param callback - Async filter function
 */
addNunjucksAsyncFilter(name: string, callback: Function): void;

/**
 * Add filter specific to JavaScript templates
 * @param name - Filter name
 * @param callback - Filter function
 */
addJavaScriptFilter(name: string, callback: Function): void;

/**
 * Get filter by name
 * @param name - Filter name
 * @returns Filter function
 */
getFilter(name: string): Function;

/**
 * Get all filters with optional filtering
 * @param options - Filter options
 * @returns Object containing filters
 */
getFilters(options?: { type?: string }): Record<string, Function>;

// Universal filters
eleventyConfig.addFilter("uppercase", (str) => str.toUpperCase());
eleventyConfig.addFilter("reverse", (arr) => [...arr].reverse());

// Async filters
eleventyConfig.addAsyncFilter("fetchData", async (url) => {
  const response = await fetch(url);
  return response.json();
});

// Engine-specific filters
eleventyConfig.addLiquidFilter("slugify", (str) => 
  str.toLowerCase().replace(/\s+/g, "-")
);

eleventyConfig.addNunjucksFilter("dateFormat", (date, format) => {
  return new Intl.DateTimeFormat("en-US").format(date);
});

/**
 * Add universal shortcode that works in all template engines
 * @param name - Shortcode name
 * @param callback - Shortcode function
 */
addShortcode(name: string, callback: Function): void;

/**
 * Add async shortcode for asynchronous operations
 * @param name - Shortcode name
 * @param callback - Async shortcode function
 */
addAsyncShortcode(name: string, callback: Function): void;

/**
 * Add paired shortcode that wraps content
 * @param name - Shortcode name
 * @param callback - Shortcode function receiving content as last parameter
 */
addPairedShortcode(name: string, callback: Function): void;

/**
 * Add async paired shortcode that wraps content
 * @param name - Shortcode name
 * @param callback - Async shortcode function receiving content as last parameter
 */
addPairedAsyncShortcode(name: string, callback: Function): void;

/**
 * Add shortcode specific to Liquid templates
 * @param name - Shortcode name
 * @param callback - Shortcode function
 */
addLiquidShortcode(name: string, callback: Function): void;

/**
 * Add paired shortcode specific to Liquid templates
 * @param name - Shortcode name
 * @param callback - Paired shortcode function
 */
addPairedLiquidShortcode(name: string, callback: Function): void;

/**
 * Add shortcode specific to Nunjucks templates
 * @param name - Shortcode name
 * @param callback - Shortcode function
 * @param isAsync - Whether shortcode is asynchronous
 */
addNunjucksShortcode(name: string, callback: Function, isAsync?: boolean): void;

/**
 * Add async shortcode specific to Nunjucks templates
 * @param name - Shortcode name
 * @param callback - Async shortcode function
 */
addNunjucksAsyncShortcode(name: string, callback: Function): void;

/**
 * Add paired shortcode specific to Nunjucks templates
 * @param name - Shortcode name
 * @param callback - Paired shortcode function
 * @param isAsync - Whether shortcode is asynchronous
 */
addPairedNunjucksShortcode(name: string, callback: Function, isAsync?: boolean): void;

/**
 * Add async paired shortcode specific to Nunjucks templates
 * @param name - Shortcode name
 * @param callback - Async paired shortcode function
 */
addPairedNunjucksAsyncShortcode(name: string, callback: Function): void;

/**
 * Add shortcode specific to JavaScript templates
 * @param name - Shortcode name
 * @param callback - Shortcode function
 */
addJavaScriptShortcode(name: string, callback: Function): void;

/**
 * Add paired shortcode specific to JavaScript templates
 * @param name - Shortcode name
 * @param callback - Paired shortcode function
 */
addPairedJavaScriptShortcode(name: string, callback: Function): void;

/**
 * Add JavaScript function (for backwards compatibility)
 * @param name - Function name
 * @param callback - Function
 */
addJavaScriptFunction(name: string, callback: Function): void;

/**
 * Get shortcode by name
 * @param name - Shortcode name
 * @returns Shortcode function
 */
getShortcode(name: string): Function;

/**
 * Get paired shortcode by name
 * @param name - Paired shortcode name
 * @returns Paired shortcode function
 */
getPairedShortcode(name: string): Function;

// Basic shortcodes
eleventyConfig.addShortcode("year", () => new Date().getFullYear());
eleventyConfig.addShortcode("icon", (name) => `<i class="icon-${name}"></i>`);

// Paired shortcodes
eleventyConfig.addPairedShortcode("callout", (content, type = "info") => {
  return `<div class="callout callout-${type}">${content}</div>`;
});

// Async shortcodes
eleventyConfig.addAsyncShortcode("image", async (src, alt) => {
  const metadata = await getImageMetadata(src);
  return `<img src="${src}" alt="${alt}" width="${metadata.width}" height="${metadata.height}">`;
});

// Engine-specific shortcodes
eleventyConfig.addNunjucksShortcode("button", (text, url) => {
  return `<a href="${url}" class="btn">${text}</a>`;
});

/**
 * Add custom Liquid tag
 * @param name - Tag name
 * @param tagFn - Tag function that returns parse/render object
 */
addLiquidTag(name: string, tagFn: (liquidEngine: any) => { parse: Function; render: Function }): void;

/**
 * Add custom Nunjucks tag
 * @param name - Tag name  
 * @param tagFn - Tag function that extends Nunjucks
 */
addNunjucksTag(name: string, tagFn: (nunjucksEngine: any) => void): void;

// Liquid custom tag
eleventyConfig.addLiquidTag("currentYear", (liquidEngine) => {
  return {
    parse: function(tagToken, remainingTokens) {
      this.str = tagToken.args; 
    },
    render: function(scope, hash) {
      return Promise.resolve(new Date().getFullYear());
    }
  };
});

// Nunjucks custom tag
eleventyConfig.addNunjucksTag("datetime", function(nunjucksEngine) {
  this.tags = ["datetime"];
  this.parse = function(parser, nodes, lexer) {
    var tok = parser.nextToken();
    var args = parser.parseSignature(null, true);
    parser.advanceAfterBlockEnd(tok.value);
    return new nodes.CallExtension(this, "run", args);
  };
  this.run = function(context, format) {
    return new Date().toLocaleDateString();
  };
});

/**
 * Add template collection
 * @param name - Collection name
 * @param callback - Function that returns collection items
 */
addCollection(name: string, callback: (collectionApi: CollectionApi) => any[]): void;

/**
 * Get all configured collections
 * @returns Object containing all collections
 */
getCollections(): Record<string, Function>;

/**
 * Set precompiled collections
 * @param collections - Precompiled collection data
 */
setPrecompiledCollections(collections: any): void;

interface CollectionApi {
  /** Get all templates */
  getAll(): CollectionItem[];
  
  /** Get templates with specific tag */
  getFilteredByTag(tagName: string): CollectionItem[];
  
  /** Get templates matching glob pattern */
  getFilteredByGlob(glob: string): CollectionItem[];
}

interface CollectionItem {
  inputPath: string;
  fileSlug: string;
  outputPath: string;
  url: string;
  date: Date;
  data: any;
  template: any;
}

// Basic collections
eleventyConfig.addCollection("posts", (collectionApi) => {
  return collectionApi.getFilteredByGlob("./src/posts/*.md");
});

eleventyConfig.addCollection("featured", (collectionApi) => {
  return collectionApi.getAll().filter(item => item.data.featured);
});

// Advanced collections with sorting
eleventyConfig.addCollection("recentPosts", (collectionApi) => {
  return collectionApi
    .getFilteredByTag("post")
    .sort((a, b) => b.date - a.date)
    .slice(0, 5);
});

/**
 * Set the template formats to process
 * @param templateFormats - Array or comma-separated string of formats
 */
setTemplateFormats(templateFormats: string | string[]): void;

/**
 * Add additional template formats (additive)
 * @param templateFormats - Additional formats to support
 */
addTemplateFormats(templateFormats: string | string[]): void;

// Set specific formats
eleventyConfig.setTemplateFormats(["md", "njk", "html"]);
eleventyConfig.setTemplateFormats("md,njk,html");

// Add formats (usually for plugins)
eleventyConfig.addTemplateFormats("vue");
eleventyConfig.addTemplateFormats(["tsx", "jsx"]);

/**
 * Add custom file extension support
 * @param fileExtension - File extension or array of extensions
 * @param options - Extension configuration options
 */
addExtension(fileExtension: string | string[], options?: ExtensionOptions): void;

/**
 * Add custom data file extension support  
 * @param extensionList - Comma-separated list of extensions
 * @param parser - Parser function or configuration object
 */
addDataExtension(extensionList: string, parser: Function | { parser: Function; options?: any }): void;

interface ExtensionOptions {
  /** Override key for the extension */
  key?: string;
  /** Output file extension */
  outputFileExtension?: string;
  /** Compile function for the extension */
  compile?: (inputContent: string, inputPath: string) => Function;
  /** Compile options */
  compileOptions?: any;
  /** Get data function */
  getData?: Function;
  /** Get instance function */
  getInstanceFromInputPath?: Function;
}

// Add Vue single-file component support
eleventyConfig.addExtension("vue", {
  outputFileExtension: "html",
  compile: (inputContent, inputPath) => {
    return (data) => {
      // Custom Vue compilation logic
      return compileVue(inputContent, data);
    };
  }
});

// Add custom data file support  
eleventyConfig.addDataExtension("toml", require("@iarna/toml").parse);
eleventyConfig.addDataExtension("csv", {
  parser: require("csv-parse/sync").parse,
  options: { columns: true }
});

/**
 * Add plugin to Eleventy
 * @param plugin - Plugin function or object
 * @param options - Plugin configuration options
 */
addPlugin(plugin: PluginDefinition, options?: any): void;

/**
 * Resolve built-in plugin by name
 * @param name - Plugin package name
 * @returns Plugin function or Promise<Plugin>
 */
resolvePlugin(name: string): Function | Promise<Function>;

/**
 * Check if plugin is already added
 * @param plugin - Plugin name or definition
 * @returns Whether plugin is registered
 */
hasPlugin(plugin: string | PluginDefinition): boolean;

/**
 * Execute code within a plugin namespace
 * @param pluginNamespace - Namespace for plugin
 * @param callback - Function to execute in namespace
 */
namespace(pluginNamespace: string, callback: (eleventyConfig: UserConfig) => void): Promise<void>;

interface PluginDefinition {
  /** Plugin configuration function */
  configFunction?: (eleventyConfig: UserConfig, options?: any) => void;
  /** Plugin package name */
  eleventyPackage?: string;
  /** Plugin options */
  eleventyPluginOptions?: {
    /** Only add plugin once */
    unique?: boolean;
  };
}

// Add built-in plugins
eleventyConfig.addPlugin(require("@11ty/eleventy").RenderPlugin);
eleventyConfig.addPlugin(require("@11ty/eleventy").I18nPlugin, {
  defaultLanguage: "en"
});

// Add community plugins
eleventyConfig.addPlugin(require("@11ty/eleventy-plugin-syntaxhighlight"));
eleventyConfig.addPlugin(require("@11ty/eleventy-plugin-rss"));

// Resolve plugins dynamically
const i18nPlugin = await eleventyConfig.resolvePlugin("@11ty/eleventy/i18n-plugin");
eleventyConfig.addPlugin(i18nPlugin, { defaultLanguage: "en" });

// Plugin with namespace
await eleventyConfig.namespace("myPlugin", (eleventyConfig) => {
  eleventyConfig.addFilter("myFilter", (content) => content);
});

interface CollectionApi {
  getAll(): CollectionItem[];
  getFilteredByTag(tagName: string): CollectionItem[];
  getFilteredByGlob(glob: string): CollectionItem[];
}

interface CollectionItem {
  inputPath: string;
  fileSlug: string;
  outputPath: string;
  url: string;
  date: Date;
  data: any;
  template: any;
}

interface ExtensionOptions {
  key?: string;
  outputFileExtension?: string;
  compile?: (inputContent: string, inputPath: string) => Function;
  compileOptions?: any;
  getData?: Function;
  getInstanceFromInputPath?: Function;
}

interface PluginDefinition {
  configFunction?: (eleventyConfig: UserConfig, options?: any) => void;
  eleventyPackage?: string;
  eleventyPluginOptions?: {
    unique?: boolean;
  };
}