Core API

/**
 * Creates an asynchronous cosmiconfig explorer instance
 * @param moduleName - Module name used to generate search patterns
 * @param options - Configuration options for customizing behavior
 * @returns PublicExplorer instance for async operations
 */
function cosmiconfig(moduleName: string, options?: Options): PublicExplorer;

import { cosmiconfig } from "cosmiconfig";

// Basic usage with module name
const explorer = cosmiconfig("babel");

// With custom options
const customExplorer = cosmiconfig("myapp", {
  searchPlaces: ["package.json", ".myapprc", ".myapp.config.js"],
  cache: false
});

/**
 * Creates a synchronous cosmiconfig explorer instance
 * @param moduleName - Module name used to generate search patterns
 * @param options - Configuration options for sync operations
 * @returns PublicExplorerSync instance for sync operations
 */
function cosmiconfigSync(moduleName: string, options?: OptionsSync): PublicExplorerSync;

import { cosmiconfigSync } from "cosmiconfig";

const explorerSync = cosmiconfigSync("prettier");
const result = explorerSync.search();

/**
 * Search for configuration starting from a directory
 * @param searchFrom - Directory to start searching from (defaults to process.cwd())
 * @returns Promise resolving to configuration result or null if not found
 */
search(searchFrom?: string): Promise<CosmiconfigResult>;

// Synchronous version
search(searchFrom?: string): CosmiconfigResult;

// Search from current directory
const result = await explorer.search();

// Search from specific directory
const result = await explorer.search("/path/to/project");

// Handle result
if (result) {
  console.log("Config found:", result.config);
  console.log("File path:", result.filepath);
  console.log("Is empty:", result.isEmpty);
} else {
  console.log("No configuration found");
}

/**
 * Load configuration from a specific file path
 * @param filepath - Path to configuration file
 * @returns Promise resolving to configuration result or null if file doesn't exist
 */
load(filepath: string): Promise<CosmiconfigResult>;

// Synchronous version
load(filepath: string): CosmiconfigResult;

// Load specific configuration file
const result = await explorer.load("./config/myapp.config.js");

// Load with error handling
try {
  const result = await explorer.load("./nonexistent.config.js");
  if (result) {
    console.log("Config:", result.config);
  }
} catch (error) {
  console.error("Error loading config:", error);
}

/**
 * Clear the cache used by the load() method
 */
clearLoadCache(): void;

/**
 * Clear the cache used by the search() method
 */
clearSearchCache(): void;

/**
 * Clear all caches (both load and search caches)
 */
clearCaches(): void;

const explorer = cosmiconfig("myapp");

// Use explorer methods
await explorer.search();
await explorer.load("./config.js");

// Clear specific cache
explorer.clearLoadCache();

// Or clear all caches
explorer.clearCaches();

interface PublicExplorerBase {
  clearLoadCache(): void;
  clearSearchCache(): void;
  clearCaches(): void;
}

interface PublicExplorer extends PublicExplorerBase {
  search(searchFrom?: string): Promise<CosmiconfigResult>;
  load(filepath: string): Promise<CosmiconfigResult>;
}

interface PublicExplorerSync extends PublicExplorerBase {
  search(searchFrom?: string): CosmiconfigResult;
  load(filepath: string): CosmiconfigResult;
}

type CosmiconfigResult = {
  /** The parsed configuration object */
  config: any;
  /** Absolute path to the configuration file */
  filepath: string;
  /** True if the configuration file was empty or contained only whitespace */
  isEmpty?: boolean;
} | null;