@ts-bridge/cli/dist/transformers.d.ts

Bridge the gap between ES modules and CommonJS modules with an easy-to-use alternative to `tsc`.

import type { FileFormat } from '@ts-bridge/resolver';
import type { CustomTransformer, ResolutionMode, SourceFile, System, TransformationContext, Transformer, TypeChecker } from 'typescript';
/**
 * The options for the transformer functions.
 *
 * @property typeChecker - The type checker to use.
 * @property system - The compiler system to use.
 * @property baseDirectory - The base directory to start resolving from.
 */
export type TransformerOptions = {
    typeChecker: TypeChecker;
    system: System;
    verbose?: boolean;
};
/**
 * Get a transformer that updates the import extensions to append the given
 * extension.
 *
 * For example, the following import declaration:
 * ```js
 * import { foo } from './foo.js';
 * ```
 *
 * will be transformed to (assuming the extension is `.mjs`):
 * ```js
 * import { foo } from './foo.mjs';
 * ```
 *
 * @param extension - The extension to append to import paths.
 * @param options - The transformer options.
 * @param options.system - The compiler system to use.
 * @param options.verbose - Whether to enable verbose logging.
 * @returns The transformer function.
 */
export declare function getImportExtensionTransformer(extension: string, { system, verbose }: TransformerOptions): (context: TransformationContext) => CustomTransformer;
/**
 * Get a transformer that updates the dynamic import extensions to append the
 * given extension.
 *
 * For example, the following import declaration:
 * ```js
 * import('./foo.js');
 * ```
 *
 * will be transformed to (assuming the extension is `.mjs`):
 * ```js
 * import('./foo.mjs');
 * ```
 *
 * @param extension - The extension to append to import paths.
 * @param options - The transformer options.
 * @param options.system - The compiler system to use.
 * @param options.verbose - Whether to enable verbose logging.
 * @returns The transformer function.
 */
export declare function getDynamicImportExtensionTransformer(extension: string, { system, verbose }: TransformerOptions): (context: TransformationContext) => CustomTransformer;
/**
 * Get a transformer that updates the `require` calls to use the given
 * extension.
 *
 * For example, the following `require` call:
 * ```js
 * const foo = require('./foo.js');
 * ```
 *
 * will be transformed to (assuming the extension is `.mjs`):
 * ```js
 * const foo = require('./foo.mjs');
 * ```
 *
 * @param extension - The new extension for the `require` calls.
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @param options.system - The compiler system to use.
 * @param options.verbose - Whether to enable verbose logging.
 * @returns The transformer function.
 */
export declare function getRequireExtensionTransformer(extension: string, { typeChecker, system, verbose }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that updates the export extensions to append the given
 * extension.
 *
 * For example, the following export declaration:
 * ```js
 * export * from './foo.js';
 * ```
 *
 * will be transformed to (assuming the extension is `.mjs`):
 * ```js
 * export * from './foo.mjs';
 * ```
 *
 * @param extension - The extension to append to export paths.
 * @param options - The transformer options.
 * @param options.system - The compiler system to use.
 * @param options.verbose - Whether to enable verbose logging.
 * @returns The transformer function.
 */
export declare function getExportExtensionTransformer(extension: string, { system, verbose }: TransformerOptions): (context: TransformationContext) => CustomTransformer;
/**
 * Get a transformer that updates `__filename`, `__dirname` to an ES-compatible
 * version using `import.meta.url`.
 *
 * For example, the following statement:
 * ```ts
 * const foo = __filename;
 * ```
 *
 * will be transformed to:
 * ```ts
 * function $__filename(url) {
 *   // ...;
 * }
 *
 * const foo = $__filename(import.meta.url);
 * ```
 *
 * This should only be used for the ES module target.
 *
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @returns The transformer function.
 */
export declare function getGlobalsTransformer({ typeChecker }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that updates `require` to an ES-compatible version using
 * `createRequire` and `import.meta.url`.
 *
 * For example, the following statement:
 * ```ts
 * const foo = require('bar');
 * ```
 *
 * will be transformed to:
 * ```ts
 * function require(path, url) {
 *   // ...;
 * }
 *
 * const foo = require('bar', import.meta.url);
 * ```
 *
 * This should only be used for the ES module target.
 *
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @returns The transformer function.
 */
export declare const getRequireTransformer: ({ typeChecker }: TransformerOptions) => (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that updates `import.meta.url` to a CommonJS-compatible
 * version using `__filename`.
 *
 * For example, the following statement:
 * ```ts
 * const foo = import.meta.url;
 * ```
 *
 * will be transformed to:
 * ```ts
 * function getImportMetaUrl(filename) {
 *   // ...;
 * }
 *
 * const foo = getImportMetaUrl(__filename);
 * ```
 *
 * This should only be used for the CommonJS target.
 *
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @returns The transformer function.
 */
export declare function getImportMetaTransformer({ typeChecker }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that updates the default imports to use the `importDefault`
 * helper function for CommonJS modules.
 *
 * For example, the following default import:
 *
 * ```ts
 * import foo from 'module';
 * ```
 *
 * will be transformed to:
 *
 * ```ts
 * function $importDefault(module) {
 *   // ...;
 * }
 *
 * import $foo from 'module';
 * const foo = $importDefault($foo);
 * ```
 *
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @param options.system - The compiler system to use.
 * @returns The transformer function.
 */
export declare function getDefaultImportTransformer({ typeChecker, system, }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that updates the named imports. This updates the imports to
 * use a default import, and destructures the imports from the default import.
 *
 * For example, the following import (assuming the module is a CommonJS module):
 * ```ts
 * import { foo, bar } from 'module';
 * ```
 *
 * will be transformed to:
 * ```ts
 * import module from 'module';
 * const { foo, bar } = module;
 * ```
 *
 * @param options - The transformer options.
 * @param options.typeChecker - The type checker to use.
 * @param options.system - The compiler system to use.
 * @returns The transformer function.
 */
export declare function getNamedImportTransformer({ typeChecker, system, }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that removes type-only imports and exports. This is the
 * default behaviour for TypeScript when invoked from the command line, but does
 * not seem to be the default behaviour when using the TypeScript API.
 *
 * For example, the following type-only imports and exports:
 * ```ts
 * import type { Foo } from 'module';
 * export type { Foo };
 * ```
 *
 * will be removed.
 *
 * @param context - The transformer options.
 * @param context.typeChecker - The type checker to use.
 * @returns The transformer function.
 */
export declare function getTypeImportExportTransformer({ typeChecker, }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * The options for the {@link getImportAttributeTransformer} function.
 */
export type ImportAssertionTransformerOptions = {
    /**
     * The type of the module, i.e., CommonJS or ES module, to apply the
     * transformation to.
     */
    moduleType: FileFormat;
    /**
     * The import assertion type to apply.
     */
    type: string;
};
/**
 * Get a transformer that adds an import attribute to the given module type with
 * the given type attribute. This is mainly useful for JSON imports, which
 * require `with { type: 'json' }` to be added to the import statement.
 *
 * @param options - The import attribute options.
 * @param options.moduleType - The type of the module, i.e., CommonJS or ES
 * module, to apply the transformation to.
 * @param options.type - The import assertion type to apply.
 * @param context - The transformer options.
 * @param context.system - The compiler system to use.
 * @returns The transformer function.
 */
export declare function getImportAttributeTransformer(options: ImportAssertionTransformerOptions, { system }: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a transformer that removes any import attributes from the import
 * declarations.
 *
 * This is useful in CommonJS environments where import attributes are not
 * supported.
 *
 * @param _context - The transformer options. This is not used.
 * @returns The transformer function.
 */
export declare function getRemoveImportAttributeTransformer(_context: TransformerOptions): (context: TransformationContext) => Transformer<SourceFile>;
/**
 * Get a custom transformer that sets the target module kind for the source
 * file.
 *
 * @param impliedNodeFormat - The target module kind, i.e., ES module or
 * CommonJS module.
 * @returns The custom transformer function.
 */
export declare function getTargetTransformer(impliedNodeFormat: ResolutionMode): () => Transformer<SourceFile>;
/**
 * Update the source map path to match the new file extension of the source
 * file.
 *
 * Source maps contain a `file` property that points to the original source
 * file. When the source file extension is changed, the source map file path
 * should be updated to match the new extension.
 *
 * @param sourceMap - The source map JSON string.
 * @param extension - The new file extension.
 * @returns The updated source map JSON string.
 */
export declare function transformSourceMap(sourceMap: string, extension: string): string;
/**
 * Transform the dynamic imports in the declaration file to use the new file
 * extension.
 *
 * @param content - The content of the declaration file.
 * @param extension - The new file extension.
 * @param parentUrl - The URL of the parent module.
 * @param system - The TypeScript system.
 * @param verbose - Whether to show verbose output.
 * @returns The transformed content.
 */
export declare function transformDeclarationImports(content: string, extension: string, parentUrl: string, system: System, verbose: boolean): string;
/**
 * Transform the file content to update the source map path or the source file
 * extension.
 *
 * @param fileName - The name of the file.
 * @param sourceFileName - The name of the source file.
 * @param content - The content of the source file.
 * @param extension - The new file extension.
 * @param declarationExtension - The new file extension for declaration files.
 * @param system - The TypeScript system.
 * @param verbose - Whether to show verbose output.
 * @returns The transformed content.
 */
export declare function transformFile(fileName: string, sourceFileName: string, content: string, extension: string, declarationExtension: string, system: System, verbose: boolean): string;
//# sourceMappingURL=transformers.d.ts.map