Import/Export Analysis

/**
 * Finds all static import statements within the given code string
 * @param code - The source code to search for static imports
 * @returns An array of StaticImport objects representing each static import found
 */
function findStaticImports(code: string): StaticImport[];

import { findStaticImports } from "mlly";

const code = `
import foo, { bar } from './module.mjs';
import { baz as qux } from 'package';
`;

const imports = findStaticImports(code);
console.log(imports[0].specifier); // "./module.mjs"
console.log(imports[0].imports); // "foo, { bar } "

/**
 * Searches for dynamic import statements in the given source code
 * @param code - The source to search for dynamic imports in
 * @returns An array of DynamicImport objects representing each dynamic import found
 */
function findDynamicImports(code: string): DynamicImport[];

import { findDynamicImports } from "mlly";

const code = `
const module = await import('./module.mjs');
import('./conditional.mjs').then(m => m.default());
`;

const dynamicImports = findDynamicImports(code);
console.log(dynamicImports[0].expression); // "'./module.mjs'"

/**
 * Identifies and returns all type import statements in the given source code
 * @param code - The source code to search for type imports
 * @returns An array of TypeImport objects representing each type import found
 */
function findTypeImports(code: string): TypeImport[];

import { findTypeImports } from "mlly";

const code = `
import type { User, Config } from './types';
import { type Database, connect } from './database';
`;

const typeImports = findTypeImports(code);
console.log(typeImports[0].specifier); // "./types"
console.log(typeImports[0].imports); // " User, Config "

/**
 * Parses a static import or type import to extract detailed import elements such as default, namespace and named imports
 * @param matched - The matched import statement to parse
 * @returns A structured object representing the parsed static import
 */
function parseStaticImport(matched: StaticImport | TypeImport): ParsedStaticImport;

import { findStaticImports, parseStaticImport } from "mlly";

const [match] = findStaticImports(`import foo, { bar as baz } from 'module'`);
const parsed = parseStaticImport(match);

console.log(parsed.defaultImport); // "foo"
console.log(parsed.namedImports); // { bar: "baz" }

/**
 * Parses a static import or type import to extract detailed import elements such as default, namespace and named imports
 * @param matched - The matched import statement to parse
 * @returns A structured object representing the parsed static import
 */
function parseTypeImport(matched: TypeImport | StaticImport): ParsedStaticImport;

import { findTypeImports, parseTypeImport } from "mlly";

const [typeMatch] = findTypeImports(`import type { User as UserType, Config } from 'types'`);
const parsed = parseTypeImport(typeMatch);

console.log(parsed.namedImports); // { User: "UserType", Config: "Config" }

/**
 * Identifies all export statements in the supplied source code and categorises them into different types such as declarations, named, default and star exports
 * @param code - The source code containing the export statements to be analysed
 * @returns An array of ESMExport objects representing each export found, properly categorised and structured
 */
function findExports(code: string): ESMExport[];

import { findExports } from "mlly";

const code = `
export const foo = 'bar';
export { baz, qux as quux };
export default class MyClass {}
export * from './other.mjs';
`;

const exports = findExports(code);
// Returns exports categorized by type: declaration, named, default, star

/**
 * Searches specifically for type-related exports in TypeScript code, such as exported interfaces, types, and declarations prefixed with 'declare'
 * @param code - The TypeScript source code to search for type exports
 * @returns An array of ESMExport objects representing each type export found
 */
function findTypeExports(code: string): ESMExport[];

/**
 * Extracts and returns a list of all export names from the given source
 * @param code - The source code to search for export names
 * @returns An array containing the names of all exports found in the code
 */
function findExportNames(code: string): string[];

/**
 * Asynchronously resolves and returns all export names from a module specified by its module identifier
 * @param id - The module identifier to resolve
 * @param options - Optional settings for resolving the module path, such as the base URL
 * @returns A promise that resolves to an array of export names from the module
 */
function resolveModuleExportNames(id: string, options?: ResolveOptions): Promise<string[]>;

import { resolveModuleExportNames } from "mlly";

// Get all export names from a package
const exports = await resolveModuleExportNames("lodash");
console.log(exports); // ["map", "filter", "reduce", ...]

/** Regular expression to match static import statements in JavaScript/TypeScript code */
const ESM_STATIC_IMPORT_RE: RegExp;

/** Regular expression to match dynamic import statements in JavaScript/TypeScript code */
const DYNAMIC_IMPORT_RE: RegExp;

/** Regular expression to match various types of export declarations including variables, functions, and classes */
const EXPORT_DECAL_RE: RegExp;

/** Regular expression to match export declarations specifically for types, interfaces, and type aliases in TypeScript */
const EXPORT_DECAL_TYPE_RE: RegExp;

import { ESM_STATIC_IMPORT_RE, DYNAMIC_IMPORT_RE } from "mlly";

// Use regex directly for custom parsing
const code = `import { foo } from "bar"; const x = import("dynamic");`;
const staticMatches = [...code.matchAll(ESM_STATIC_IMPORT_RE)];
const dynamicMatches = [...code.matchAll(DYNAMIC_IMPORT_RE)];

interface ESMImport {
  /** Specifies the type of import: "static" for static imports and "dynamic" for dynamic imports */
  type: "static" | "dynamic";
  /** The full import declaration code snippet as a string */
  code: string;
  /** The starting position (index) of the import declaration in the source code */
  start: number;
  /** The end position (index) of the import declaration in the source code */
  end: number;
}

interface StaticImport extends ESMImport {
  /** Indicates the type of import, specifically a static import */
  type: "static";
  /** Contains the entire import statement as a string, excluding the module specifier */
  imports: string;
  /** The module specifier from which imports are being brought in */
  specifier: string;
}

interface ParsedStaticImport extends StaticImport {
  /** The default import name, if any */
  defaultImport?: string;
  /** The namespace import name, if any, using the `* as` syntax */
  namespacedImport?: string;
  /** An object representing named imports, with their local aliases if specified */
  namedImports?: { [name: string]: string };
}

interface DynamicImport extends ESMImport {
  /** Indicates that this is a dynamic import */
  type: "dynamic";
  /** The expression or path to be dynamically imported, typically a module path or URL */
  expression: string;
}

interface TypeImport extends Omit<ESMImport, "type"> {
  /** Specifies that this is a type import */
  type: "type";
  /** Contains the entire type import statement as a string, excluding the module specifier */
  imports: string;
  /** The module specifier from which to import types */
  specifier: string;
}

interface ESMExport {
  /** The type of export (declaration, named, default or star) */
  type: "declaration" | "named" | "default" | "star";
  /** The specific type of declaration being exported, if applicable */
  declarationType?: "let" | "var" | "const" | "enum" | "const enum" | "class" | "function" | "async function";
  /** The full code snippet of the export statement */
  code: string;
  /** The starting position (index) of the export declaration in the source code */
  start: number;
  /** The end position (index) of the export declaration in the source code */
  end: number;
  /** The name of the variable, function or class being exported, if given explicitly */
  name?: string;
  /** The name used for default exports when a specific identifier isn't given */
  defaultName?: string;
  /** An array of names to export, applicable to named and destructured exports */
  names: string[];
  /** The module specifier, if any, from which exports are being re-exported */
  specifier?: string;
}

interface DeclarationExport extends ESMExport {
  /** Indicates that this export is a declaration export */
  type: "declaration";
  /** The declaration string, such as 'let', 'const', 'class', etc., describing what is being exported */
  declaration: string;
  /** The name of the declaration to be exported */
  name: string;
}

interface NamedExport extends ESMExport {
  /** Specifies that this export is a named export */
  type: "named";
  /** The export string, containing all exported identifiers */
  exports: string;
  /** An array of names to export */
  names: string[];
  /** The module specifier, if any, from which exports are being re-exported */
  specifier?: string;
}

interface DefaultExport extends ESMExport {
  /** Specifies that this export is a standard export */
  type: "default";
}