# File Transformation

Single-file transformation capabilities for syntax conversion, minification, and format conversion without full bundling. The transform API is ideal for processing individual files, code snippets, or when you need quick transformations without dependency resolution.

## Capabilities

### Transform Function (Async)

Transforms a single file or code string with the specified options.

```typescript { .api }
/**
 * Transform a single file or code string
 * @param input - Source code as string or Uint8Array
 * @param options - Transformation options
 * @returns Promise resolving to transformation results
 */
function transform(
  input: string | Uint8Array,
  options?: TransformOptions
): Promise<TransformResult>;
```

**Usage Examples:**

```typescript
import * as esbuild from "esbuild";

// Transform TypeScript to JavaScript
const result = await esbuild.transform(`
  interface User {
    name: string;
    age: number;
  }
  
  const user: User = { name: "Alice", age: 30 };
  console.log(\`Hello, \${user.name}!\`);
`, {
  loader: "ts",
  format: "esm",
  target: "es2020",
});

console.log(result.code);

// Transform and minify
const minified = await esbuild.transform(`
  function calculateTax(price, rate) {
    return price * (1 + rate);
  }
`, {
  loader: "js",
  minify: true,
});

// Transform JSX
const jsxResult = await esbuild.transform(`
  const App = () => {
    return <div>Hello World</div>;
  };
`, {
  loader: "jsx",
  jsx: "transform",
  jsxFactory: "React.createElement",
});
```

### Transform Function (Sync)

Synchronous version of the transform function. **Node.js only** - throws error in browser environments.

```typescript { .api }
/**
 * Synchronously transform a single file or code string
 * @param input - Source code as string or Uint8Array
 * @param options - Transformation options
 * @returns Transformation results
 * @throws Error in browser environments
 */
function transformSync(
  input: string | Uint8Array,
  options?: TransformOptions
): TransformResult;
```

**Usage Example:**

```typescript
import * as esbuild from "esbuild";

// Synchronous transformation (Node.js only)
try {
  const result = esbuild.transformSync(`
    const greeting = (name: string) => \`Hello \${name}!\`;
    export { greeting };
  `, {
    loader: "ts",
    format: "cjs",
  });
  
  console.log("Transformed code:", result.code);
} catch (error) {
  console.error("Transform failed:", error);
}
```

## Types

### TransformOptions Interface

Configuration options for transform operations. Extends CommonOptions with transform-specific options.

```typescript { .api }
interface TransformOptions extends CommonOptions {
  // Transform-specific options
  sourcefile?: string;
  loader?: Loader;
  banner?: string;
  footer?: string;
}
```

### TransformResult Interface

Result object returned by transform operations.

```typescript { .api }
interface TransformResult {
  code: string;
  map: string;
  warnings: Message[];
  mangleCache?: Record<string, string | false>;
  legalComments?: string;
}
```

### TransformFailure Interface

Error object thrown when transforms fail.

```typescript { .api }
interface TransformFailure extends Error {
  errors: Message[];
  warnings: Message[];
}
```

## Supported Loaders

ESBuild supports numerous file loaders for different input types:

```typescript { .api }
type Loader = 
  | "js"        // JavaScript
  | "jsx"       // JavaScript with JSX
  | "ts"        // TypeScript  
  | "tsx"       // TypeScript with JSX
  | "css"       // CSS stylesheets
  | "json"      // JSON data
  | "text"      // Plain text
  | "base64"    // Base64 encoded data
  | "dataurl"   // Data URL format
  | "file"      // File path reference
  | "binary"    // Binary data
  | "copy"      // Copy file as-is
  | "default"   // Use file extension
  | "empty"     // Empty module
  | "local-css"; // CSS modules
```

**Usage Examples:**

```typescript
// Different loaders
const cssResult = await esbuild.transform(`
  .header { color: blue; font-size: 18px; }
`, { loader: "css", minify: true });

const jsonResult = await esbuild.transform(`{
  "name": "example",
  "version": "1.0.0"
}`, { loader: "json" });

const textResult = await esbuild.transform(`
  Hello World!
  This is plain text.
`, { loader: "text" });
```