Source Code Transformation

/**
 * Transform source code using jiti's transformation pipeline
 * @param opts - Transformation options including source code and configuration
 * @returns Transformed source code string
 */
transform(opts: TransformOptions): string;

import { createJiti } from "jiti";

const jiti = createJiti(import.meta.url);

// Transform TypeScript to JavaScript
const transformed = jiti.transform({
  source: `
    interface Config {
      apiKey: string;
    }
    export const config: Config = { apiKey: "secret" };
  `,
  filename: "config.ts",
  ts: true
});

// Transform JSX
const jsxTransformed = jiti.transform({
  source: `
    import React from "react";
    export const App = () => <div>Hello World</div>;
  `,
  filename: "App.tsx",
  jsx: true
});

// Transform with custom Babel options
const customTransformed = jiti.transform({
  source: "const x: number = 42;",
  filename: "example.ts",
  babel: {
    plugins: ["@babel/plugin-proposal-decorators"]
  }
});

interface TransformOptions {
  /**
   * Source code to transform
   */
  source: string;
  
  /**
   * Filename for the source (used for sourcemaps and error reporting)
   */
  filename?: string;
  
  /**
   * Enable TypeScript transformation
   * @default Inferred from filename extension
   */
  ts?: boolean;
  
  /**
   * Retain original line numbers in transformed code
   * @default false
   */
  retainLines?: boolean;
  
  /**
   * Enable default export interoperability
   * @default true
   */
  interopDefault?: boolean;
  
  /**
   * Enable async transformation for ESM modules
   * @default false
   */
  async?: boolean;
  
  /**
   * Enable JSX transformation
   * @default false
   */
  jsx?: boolean | JSXOptions;
  
  /**
   * Custom Babel configuration options
   */
  babel?: Record<string, any>;
}

interface TransformResult {
  /**
   * Transformed source code
   */
  code: string;
  
  /**
   * Transformation error if any occurred
   */
  error?: any;
}

/**
 * Evaluate transformed code as a module
 * @param source - Source code to evaluate (should be pre-transformed)
 * @param options - Evaluation options for module context
 * @returns Module evaluation result
 */
evalModule(source: string, options?: EvalModuleOptions): unknown;

import { createJiti } from "jiti";

const jiti = createJiti(import.meta.url);

// Transform and evaluate TypeScript
const source = `
  export const getMessage = (name: string): string => {
    return \`Hello, \${name}!\`;
  };
`;

const transformed = jiti.transform({
  source,
  filename: "greeting.ts",
  ts: true
});

const module = jiti.evalModule(transformed, {
  filename: "greeting.ts",
  async: true
});

console.log(module.getMessage("World")); // "Hello, World!"

interface EvalModuleOptions {
  /**
   * Module identifier for the evaluated code
   */
  id?: string;
  
  /**
   * Filename for the module (used in stack traces)
   */
  filename?: string;
  
  /**
   * File extension for the module
   */
  ext?: string;
  
  /**
   * Module cache to use for caching the evaluated module
   */
  cache?: ModuleCache;
  
  /**
   * Enable async module evaluation
   * @default true
   */
  async?: boolean;
  
  /**
   * Force transpilation even if not needed
   * @default false
   */
  forceTranspile?: boolean;
}

// Transform TypeScript with experimental decorators
const decoratorCode = jiti.transform({
  source: `
    import "reflect-metadata";
    
    @Entity("users")
    class User {
      @Column("varchar")
      name: string;
      
      @Column("int")
      age: number;
    }
    
    export { User };
  `,
  filename: "user.ts",
  ts: true,
  babel: {
    plugins: [
      ["@babel/plugin-proposal-decorators", { legacy: true }],
      ["babel-plugin-transform-typescript-metadata"]
    ]
  }
});

// Transform JSX for Preact
const preactJSX = jiti.transform({
  source: `
    import { Component } from "preact";
    
    export class App extends Component {
      render() {
        return <div>Hello from Preact!</div>;
      }
    }
  `,
  filename: "App.tsx",
  jsx: {
    runtime: "automatic",
    importSource: "preact"
  }
});

// Transform JSX with classic pragma
const customJSX = jiti.transform({
  source: `export const element = <div>Custom JSX</div>;`,
  filename: "element.tsx",
  jsx: {
    runtime: "classic",
    pragma: "h",
    pragmaFrag: "Fragment"
  }
});

// Transform ESM imports for compatibility
const esmCode = jiti.transform({
  source: `
    import { readFile } from "fs/promises";
    import config from "./config.json";
    
    export async function loadConfig() {
      const data = await readFile("./data.txt", "utf8");
      return { ...config, data };
    }
  `,
  filename: "loader.ts",
  async: true,
  interopDefault: true
});

import { readFileSync } from "fs";
import { createJiti } from "jiti";

const jiti = createJiti(import.meta.url);

// Read and transform a TypeScript file
const sourceCode = readFileSync("./src/utils.ts", "utf8");
const transformed = jiti.transform({
  source: sourceCode,
  filename: "./src/utils.ts",
  ts: true,
  retainLines: true // Preserve line numbers for debugging
});

// Write transformed code or use directly
console.log(transformed);

// Create a custom transformation pipeline
function transformTypeScript(filename: string): string {
  const source = readFileSync(filename, "utf8");
  
  return jiti.transform({
    source,
    filename,
    ts: true,
    retainLines: process.env.NODE_ENV === "development",
    babel: {
      // Custom Babel configuration
      presets: [
        ["@babel/preset-typescript", { allowDeclareFields: true }]
      ],
      plugins: [
        "@babel/plugin-syntax-decorators",
        "@babel/plugin-transform-class-properties"
      ]
    }
  });
}

try {
  const result = jiti.transform({
    source: "invalid typescript syntax: const x: = 42;",
    filename: "invalid.ts",
    ts: true
  });
} catch (error) {
  console.error("Transformation failed:", error.message);
  console.error("Location:", error.loc);
  console.error("Code frame:", error.codeFrame);
}

// Enable source maps for better debugging
const jiti = createJiti(import.meta.url, {
  sourceMaps: true,
  debug: true
});

const transformed = jiti.transform({
  source: "const x: number = 42; console.log(x);",
  filename: "debug.ts",
  ts: true,
  retainLines: true
});

// Transformed code will include inline source maps
console.log(transformed.includes("//# sourceMappingURL=")); // true

// jiti automatically caches transformed code to filesystem
// You can control caching behavior:

const jiti = createJiti(import.meta.url, {
  fsCache: true, // Enable filesystem caching
  rebuildFsCache: false // Don't rebuild existing cache
});

// First transform is slow (actual transformation)
const result1 = jiti.transform({
  source: complexTypeScriptCode,
  filename: "complex.ts"
});

// Subsequent transforms are fast (cached)
const result2 = jiti.transform({
  source: complexTypeScriptCode,
  filename: "complex.ts"
});

// Transform multiple files efficiently
const files = ["config.ts", "utils.ts", "types.ts"];
const transformedFiles = files.map(filename => {
  const source = readFileSync(filename, "utf8");
  return {
    filename,
    transformed: jiti.transform({
      source,
      filename,
      ts: true
    })
  };
});